WalletConnect-JS

Bridging the gap between dApps and Figure wallets using WalletConnect.

Table of Contents

1. Installation
2. WalletConnectContextProvider
3. useWalletConnect
4. walletConnectState
5. walletConnectService
   • connect / init
   • disconnect
   • resetConnectionTimeout
   • signJWT
   • sendMessage
   • signHexMessage
   • removePendingMethod
6. QRCodeModal
7. Window messages
8. Examples
9. Status

Installation

npm install @provenanceio/walletconnect-js --save

Exported items:

import {
  // Constants
  WALLET_LIST,
  WINDOW_MESSAGES,
  CONNECTOR_EVENTS,
  CONNECTION_TYPES,
  // Services/Providers
  useWalletConnect,
  useWalletConnectService,
  WalletConnectContextProvider,
  WalletConnectService,
  // Components
  QRCodeModal
  // Types
  ProvenanceMethod,
  WalletConnectServiceStatus,
  ConnectMethod,
  // -- Broadcast events for methods
  BroadcastEventData,
  SignHexMessageMethodResult,
  SignHexMessageMethodEventData,
  SignJWTMethodResult,
  SignJWTMethodEventData,
  SendMessageMethodResult,
  SendMessageMethodEventData,
  DisconnectMethodResult,
  DisconnectMethodEventData,
  ConnectMethodResult,
  ConnectMethodEventData,
  SwitchToGroupMethodEventData,
  // -- Wallet info
  WalletId,
  WalletType,
} from "@provenanceio/walletconnect-js";

WalletConnectContextProvider

React context provider which provides all children components with state and hooks Optional Params:

• service: (class) Manual instance of walletConnectService to use/reference
• logsEnabled: (boolean) Enable/disable console log of various events (default false)
• connectionRedirect: (string) Auto-redirect to url when status is disconnected
• React.js example:

  // index.js
  ...
  ReactDOM.render(
    <WalletConnectContextProvider>
      <App />
    </WalletConnectContextProvider>,
    document.getElementById('root')
  );

useWalletConnect

React hook which containing walletConnectService and walletConnectState

walletConnectState

Holds current walletconnect-js state values

initialState: {
  address: '', // Wallet address [string]
  attributes: [{ name: string, value: number, type: string}], // Figure Account Attributes
  bridge: 'wss://figure.tech/service-wallet-connect-bridge/ws/external', // WalletConnect bridge used for connection [string]
  status: 'disconnected', // connection status connected ['connected', 'pending', 'disconnected]
  connectionEST: null, // WalletConnect expires at time [number]
  connectionEXP: null, // WalletConnect initialized at time [number]
  connectionTimeout: 1800, // Default timeout duration (seconds)
  modal: { // QRCodeModal values
    showModal: false, // Should the QR modal be open [bool]
    QRCodeUrl: '', // QRCode url contained within image [string]
    QRCodeImg: '', // QRCode image data to connect to WalletConnect bridge [string]
    isMobile: false, // Is the connected browser a mobile device [bool]
    dynamicUrl: '' // Dynamic link to open the Figure mobile wallet [string]
  },
  peer: {}, // Connected wallet info [object]
  pendingMethod: '', // Are any methods currently pending [string]
  publicKey: '', // Wallet public key (base64url encoded)
  signedJWT: '', // Signed JWT token [string]
  walletAppId: '', // Type of wallet [string]
  walletInfo: { // Information about the currently connected wallet account
    coin: '', // [string]
    id: '', // [string]
    name: '', // [string]
  },
  representedGroupPolicy: null, //Present when the wallet holder is acting on behalf of a group
}

walletConnectService

Used to call walletconnect-js methods

• connect / init

  Note: connect is being deprecated and will be replaced with init

  Start the connection process to join a Figure wallet with the dApp.

  walletConnectService.connect(options);
  // WINDOW_MESSAGE: CONNECTED

  | Param | Type | Required | Default | Example | Info | | ------ | ------ | -------- | ---------------------- | ------------ | --------------------------------------- | | bridge | string | no | "wss://figure.tech/service-wallet-connect-bridge/ws/external" | "wss://custom.bridge" | Custom bridge to connect into | | duration | number | no | 1800 | 3600 | Custom connection timeout in seconds | | individualAddress | string | no | '' | tp1knsxfnn0lq48mmnkfnkgtkk8qnxxdu0y2tklkh | Required individual address for dApp connection | | groupAddress | string | no | '' | tp1knsxfnn0lq48mmnkfnkgtkk8qnxxdu0y2tklkh | Required group address for dApp connection | | prohibitGroups | boolean | no | false | true | Prohibit group accounts from connecting to this dApp | | qrOptions | shape | no | null | - | Customize the QR code (padding, background, foreground, logo, note: must use hex colors) | | jwtExpiration | number | no | '' | 3600 | Time from now in seconds to expire new JWT returned | | walletAppId | string | no | '' | 'figure_extension' | Open a specific wallet directly (bypassing the QRCode modal)

• disconnect

  Disconnect current session

  walletConnectService.disconnect();
  // WINDOW_MESSAGE: DISCONNECT

• resetConnectionTimeout

  Change the amount of connection time remaining for the currenct walletconnect session Note: This feature is currently only available in extension wallets

  walletConnectService.resetConnectionTimeout(connectionTimeout);

  | Param | Type | Required | Default | Example | Info | | ------- | ------ | -------- | ------- | --------------------- | ---------------------- | | connectionTimeout | number | no | 1800 | 3600 | Seconds to extend current session |

• signJWT

  Prompt user to sign a generated JWT (async)

  walletConnectService.signJWT(expire, options);
  // WINDOW_MESSAGES: SIGN_JWT_COMPLETE, SIGN_JWT_FAILED

  | Param | Type | Required | Default | Example | Info | | ------ | ------ | -------- | ---------------------- | ------------ | --------------------------------------- | | expire | number | no | 24 hours (Date.now() + 86400) | 1647020269 | Custom expiration date (ms) of JWT | | options | object | no | - | { customId: 'abc' } | Additional Options (customId) |

• sendMessage

  Submit custom base64 encoded message (async)

  walletConnectService.sendMessage(options);
  // WINDOW_MESSAGES: SEND_MESSAGE_COMPLETE, SEND_MESSAGE_FAILED

  | Param | Type | Required | Default | Example | Info | | ----------- | -------------- | -------- | ----------------------------------------------------------------- | -------------------------------------------- | --------------------------------------------------- | | message | string / array | yes | - | 'CiwvcHJvdmVuYW5jZS5tZX...' | B64 encoded Message(s) to pass to wallet | | description | string | no | 'Send Message' | 'My Special Message' | Prompt title on mobile wallet | | method | string | no | 'provenance_sendTransaction' | 'provenance_sendTransaction' | Message method | | gasPrice | object | no | { gasPrice: [Figure Default], gasPriceDenom: [Figure Default] } | { gasPrice: 1337, gasPriceDenom: 'nhash' } | Optional gasPrice object, defaults to Figure values | | feeGranter | string | no | - | 'tp1knsxfnn0lq48mmnkfnkgtkk8qnxxdu0y2tklkh' | Specify a fee granter address | | feePayer | string | no | - | 'tp1knsxfnn0lq48mmnkfnkgtkk8qnxxdu0y2tklkh' | Specify a fee payer address | | memo | string | no | - | 'My special memo' | Specify a tx memo | | timeoutHeight | number | no | - | 3 | Specify a tx timeoutHeight | | extensionOptions | any[] | no | - | ['CiwvcHJvdmVuYW5jZS5tZX...'] | Specify tx extensionOptions | | nonCriticalExtensionOptions | any[] | no | - | ['CiwvcHJvdmVuYW5jZS5tZX...'] | Specify tx nonCriticalExtensionOptions | | customId | string | no | - | sendMsg_tx_01 | Custom id to track this transaction message |

• signHexMessage

  Sign a custom hex string message (async)

  walletConnectService.signHexMessage(message, options);
  // WINDOW_MESSAGES: SIGN_HEX_MESSAGE_COMPLETE, SIGN_HEX_MESSAGE_FAILED

  | Param | Type | Required | Default | Example | Info | | ------- | ------ | -------- | ------- | --------------------- | ---------------------- | | message | string | yes | - | 'My Custom Message' | Hex string message to send | | options | object | no | - | { customId: 'abc' } | Additional Options (customId) |

• removePendingMethod

  Remove a pending method from the wallet

  walletConnectService.removePendingMethod(customId);
  // WINDOW_MESSAGES: REMOVE_PENDING_METHOD_COMPLETE, REMOVE_PENDING_METHOD_FAILED

  | Param | Type | Required | Default | Example | Info | | ------- | ------ | -------- | ------- | --------------------- | ---------------------- | | customId | string | yes | - | my-id-01 | Remove a pending request from the wallet based on its customId |

QRCodeModal

Optional React.js component which creates a popup connection interface.

• Params:

  • walletConnectService: Service pulled out of useWalletConnect() hook (Required)
  • devWallets: Array of allowed dev wallets to connect into. (Optional)
  • hideWallets: Array of prod wallets to hide from user. (Optional)
  • className: CSS class to customize the styling (Optional)
  • title: Title displayed on top of the modal (Optional)

• Usage: (See example apps for in-code usage)

• Note:

  • src/consts/walletList.ts contains a list of available walletsAppIDs
  • This modal is built with React.js and will only work within a React project. If you are not using React.js look through the examples folder to see how to initiate the connection without this QRCodeModal.

Window Messages

Each method will return a window message indicating whether it failed or was completed as well as the result.

Note A: You can use await for most walletConnectService methods instead. Note B: All of these are based off Node.js Event Emitters, read more on them here: Node.js Event Emitters

Window Messages:

WalletConnect Connected

CONNECTED

WalletConnect Disconnect

DISCONNECT

WalletConnect Session Update

SESSION_UPDATED

Send Message

SEND_MESSAGE_COMPLETE SEND_MESSAGE_FAILED

Switch to Group Wallet Action

SWITCH_TO_GROUP_COMPLETE SWITCH_TO_GROUP_FAILED

JWT

SIGN_JWT_COMPLETE SIGN_JWT_FAILED

Sign

SIGN_HEX_MESSAGE_COMPLETE SIGN_HEX_MESSAGE_FAILED

Remove Pending Method

REMOVE_PENDING_METHOD_COMPLETE REMOVE_PENDING_METHOD_FAILED

(See example apps for more detailed usage)

Examples, Setup Configurations, and Alternate imports

This package comes bundled with a full demos that you can run locally to test out the various features of walletconnect-js. To see how to initiate and run the different examples, look through the README.md

• Non React Setup
  • See examples folder for demo apps
• Using a CDN Import
  • You can find this package on https://unpkg.com/: - Note: Change the version in the url as needed: https://unpkg.com/@provenanceio/[email protected]/umd/walletconnect-js.min.js

Status

Current development is being supported by Figure Technologies.

Back to top