Skip to content

web3sp/venom-connect

Repository files navigation

Logo

VenomConnect

Install

Use a package manager like:

yarn add venom-connect


How to use VenomConnect?

You can clone this repository and run one of the available usage examples. Right now it's only React app.

Import VenomConnect

import { VenomConnect } from "venom-connect";

Init VenomConnect with your own settings

VenomConnect accepts an object with settings.

There are two types of settings:

  • general settings for this library
    • theme
    • checkNetworkId
    • checkNetworkName
    • nTries
  • list of settings for different wallets, connection methods
    • providersOptions

Theme (theme)

You can specify one of the preset themes. To do this, you need to pass its name as a string.

Available themes:

  • 'light'
  • 'dark'
  • 'venom'

As an advanced feature, instead of a preset theme, you can use your own theme object with the individual values you need. You can use standard themes as a template for writing your own themes. They are located in /src/themes folder in the repository of this project.

Expected network ID or IDs (checkNetworkId)

Here you need to set the correct network IDs for your site to work.

Available formats:

  • "1000"
  • [ "1000", /* ... */ ]

! Use value 0 to work with local-node !

Expected network Name (checkNetworkName)

Here you need to set the correct network Name for your site to work.

Available format:

  • "Venom Mainnet"

You don't have to fill in this field, then the default Name is Venom Mainnet for 1, Venom Local Node for 0 or Venom Testnet for 1000.

Number of Tries to connect to wallet (nTries)

Here you need to set the number of tries to connect to wallet

You don't have to fill in this field, then the default option is 0

Providers options (providersOptions)

Provider Options is an object in which the keys are the wallet IDs and the values are the settings objects for the corresponding wallet.

The keys of the object must accept the IDs of only wallets available in this library.

Currently available IDs (new wallets may be added in the future):

  • venomwallet
  • everwallet
  • oxychatwallet

The value is an object with the settings of this wallet:

  • links
  • walletWaysToConnect
  • defaultWalletWaysToConnect

Links (links)

This is an object with the necessary links for this wallet:

  • extension
  • ios
  • android
  • qr
  • apk

To set your own link, pass the string.

To use the default link, pass undefined or don't use the needed field at all.

To hide the corresponding field, pass null.

Ways to connect a wallet (walletWaysToConnect)

This is an array with the available ways to connect this wallet, that you want to configure. If there is no such need, use the defaultWalletWaysToConnect field.

Attention! type:"extension" you have to configure anyway

Default ways to connect a wallet (defaultWalletWaysToConnect)

This is an array with the available ways to connect this wallet, which you want to use if you want to use the default values..

List of default options:

  • "mobile" — slide with a list of all download links at once
  • "ios" — slide for showing on ios devices
  • "android" — slide for showing on android devices

How to configure extension

  • Basic options
    • package — NPM package
    • packageOptions — An object that is passed inside the RPM package during initialization
    • packageOptionsStandalone — An object that is passed inside the RPM package during initialization (for standalone)
    • id — ID of the corresponding option
    • type — type of the corresponding option; "extension" for example
  • Overwrite default options
    • High-level setup
      • name — your own extension name
      • logo — your own logo link
    • Low-level setup (advanced)
      • options
      • connector
      • authConnector
const initVenomConnect = async () => {
  return new VenomConnect({
    theme: "light",
    providersOptions: {
      venomwallet: {
        links: {
          extension: "...",
          android: undefined,
          ios: null,
        },
        walletWaysToConnect: [
          {
            package: ProviderRpcClient,

            packageOptions: {
              fallback:
                VenomConnect.getPromise("venomwallet", "extension") ||
                (() => Promise.reject()),
              forceUseFallback: true,
            },
            packageOptionsStandalone: {
              fallback: () =>
                EverscaleStandaloneClient.create({
                  connection: {
                    id: 1,
                    group: "venom_mainnet",
                    type: "jrpc",
                    data: {
                      endpoint: "https://jrpc.venom.foundation/rpc",
                    },
                  },
                }),
              forceUseFallback: true,
            },

            id: "extension",
            type: "extension",
          },
        ],
        defaultWalletWaysToConnect: ["mobile", "ios", "android"],
      },
    },
  });
};

const onInitButtonClick = async () => {
  const venomConnect = await initVenomConnect();
  // you can save venomConnect here

  // and check the Authorization
  await checkAuth(venomConnect);
};

Interaction with the library

Available methods (API)

The initialized library returns an instance that contains a number of functions available for use:

  • connect
  • connectTo
  • checkAuth
  • on
  • off
  • currentProvider — getter
  • getStandalone
  • getPromise — static method
  • updateTheme
  • toggleExtensionWindow — static method

connect

This function causes the pop-up to be displayed with the available connection methods: through the extension, links to mobile applications.

connectTo (advanced)

This function allows you to get a specific provider bypassing the selection pop-up connect(walletId, connectorTypeId).

checkAuth

This function checks authorization in the available connection methods (extensions) and returns the corresponding instance of the wallet provider.

on

Subscribing to internal library events. on(event, callback)

Returns the corresponding off function with no accepted parameters.

off

Unsubscribe from internal library events. on(event, callback)

currentProvider

Returns the current provider or null.

getStandalone

The function of getting a standalone provider by its ID. getStandalone("venomwallet") or getStandalone() By default, the ID is venomwallet.

getPromise

The function of getting an object with promises, each of which waits for the initialization of the corresponding provider (for example: __venom) on the window object and is resolved by them or after several attempts is rejected.

You can get the promise you need by wallet ID and connection type getPromise("venomwallet", "extension") or you can use the default connection type ("extension") getPromise("venomwallet").

updateTheme

You can use this function to interactively switch themes in runtime.

toggleExtensionWindow

Toggle the backdrop when performing an action in the extension window. toggleExtensionWindow({ isExtensionWindowOpen: boolean; popUpText?: { title: string; text?: string; }; })

Subscribing to events

Available events:

  • connect — called every time the visibility of the pop-up changes; returns the current provider object
  • error
  • close — after the user closes the pop-up
  • select — after clicking on one of the extension items; opening the extension window
  • extension-auth — after successful authorization in the extension window
  • extension-window-closed — after closing the authorization window prematurely
const onConnect = async (provider: ProviderRpcClient | undefined) => {
  // you can save the provider here
};

useEffect(() => {
  const off = venomConnect?.on("connect", onConnect);

  return () => {
    off?.();
  };
}, [venomConnect]);

Connecting/disconnecting to the provider via the VenomConnect pop-up window

const onConnectButtonClick = async () => {
  venomConnect?.connect();
};

const onDisconnectButtonClick = async () => {
  venomProvider?.disconnect();
};

Use the provider

const getAddress = async (provider: ProviderRpcClient) => {
  // get whatever you want
  const providerState = await provider?.getProviderState?.();

  const address =
    providerState?.permissions.accountInteraction?.address.toString();

  return address;
};

Connecting to the provider after refreshing the page

This check is called before the standard pop-up call (connect).

const checkAuth = async (venomConnect: VenomConnect) => {
  const authObjectOrFalse = await venomConnect?.checkAuth();

  if (authObjectOrFalse) {
    // You can get the data you need. For example, the address.
    await getAddress(venomConnect);
  }
};