Installation

Proton is available through npm. Add Proton as a dependency using the npm install command.

npm install @protonprotocol/proton-web-sdk

Instantiation

To use and instantiate, first import the ConnectWallet function from the SDK.

import { ConnectWallet } from '@protonprotocol/proton-web-sdk'

The following is a list of arguments that ConnectWallet accepts in matching order.

linkOptions:

Custom Storage

By default, the SDK will use local storage with a default prefix of 'proton-storage.' The implementation can be found on Github.

In order to use a custom storage method, please implement the following interface.

export interface LinkStorage {
    /** Write string to storage at key. Should overwrite existing values without error. */
    write(key: string, data: string): Promise<void>
    /** Read key from storage. Should return `null` if key can not be found. */
    read(key: string): Promise<string | null>
    /** Delete key from storage. Should not error if deleting non-existing key. */
    remove(key: string): Promise<void>
}

transportOptions:

selectorOptions:

Custom Styling for Wallet Selector Modal

The wallet selector modal can be customized like so with the following example:

customStyleOptions: {
    modalBackgroundColor: '#F4F7FA',
    logoBackgroundColor: 'white',
    isLogoRound: true,
    optionBackgroundColor: 'white',
    optionFontColor: 'black',
    primaryFontColor: 'black',
    secondaryFontColor: '#6B727F',
    linkColor: '#752EEB'
};

In order to connect directly with Proton Wallet, the connectProton function can be used instead. The arguments that connectProton takes are identical to that of connectWallet. However, one more key is required in linkOptions.

The production value ('proton') will connect with the production version of Proton Wallet while the development value ('proton-dev') will connect with the development version of the Proton Wallet.

Usage

Class Initialization

class ProtonSDK {
  constructor() {
    this.chainId = process.env.REACT_APP_CHAIN_ID;
    this.endpoints = [process.env.REACT_APP_CHAIN_ENDPOINT]; // Multiple for fault tolerance
    this.appName = 'appName';
    this.requestAccount = 'accountName'; // optional
    this.session = null;
    this.link = null;
  }

Login

Using the return value from ConnectWallet, call the login method with the appName as an argument. Not supplying an appName will cause the login request to display 'Unknown requestor' as the requestor.

login = async () => {
    try {
      const { link, session } = await ConnectWallet({
        linkOptions: { chainId: this.chainId, endpoints: this.endpoints },
        transportOptions: { requestAccount: this.requestAccount, backButton: true },
        selectorOptions: { appName: this.appName, appLogo: appLogo}
      });
      this.link = link;
      this.session = session;
      return { auth: session.auth, accountData: session.accountData[0] };
    } catch (e) {
      return e;
    }
  }

The session information should be stored to call other ConnectWallet methods.

session.auth contains authentication information required to approve a transaction and other ConnectWallet methods. session.accountDatacontains the user's information including name and avatar. This object also contains information about identity verification. With every login and restoreSession, the SDK is checking the identity information users have previously sent up against a list of valid KYC providers. The flag isLightKYCVerified will be added to the accountData information as a boolean if users have their first name, last name, date of birth and address verified.

Transaction

To initiate a transaction, use the transact method.

sendTransaction = async (actions) => {
    try {
      const result = await this.session.transact(
        { actions: actions },
        { broadcast: true }
      );
      return result;
    } catch (e) {
      return e;
    }
  }

The actions key takes in an Array of transactions to send to the client for approval. The broadcast key determines if the transaction is to be broadcasted, or to simply return the signature.

Actions

A transaction action object takes the following form.

const actions = [{
        account: 'xtokens',
        name: 'transfer',
        authorization: [{
          actor: actor,
          permission: permission
        }],
        data: {
            from: actor,
            to: ProtonSDK.requestAccount,
            quantity: '1.000000 XUSDT',
            memo: 'memo'
        }
      }];

The account value is the token contract for the token being exchanged. In the example above, the token being exchanged is XUSDT for which the token contract is xtokens.

The actor and permission values can be destructured from the session.auth value from login. The memo value serves as additional details attached to the transaction, but does not affect the transaction.

const actions = [{
        account: 'xtokens',
        name: 'transfer',
        authorization: [{
          actor: actor,
          permission: permission
        }],
        data: {
            from: actor,
            to: ProtonSDK.requestAccount,
            quantity: '5.000000 FOOBAR',
            memo: 'memo'
        }
      }];

Logout

To logout, call the logout method with appName and sesstion.auth as arguments.

logout = async () => {
    await this.link.removeSession(this.requestAccount, this.session.auth);
  }

Restore Session

To restore a previous session, call the ConnectWallet function similar to login, but set the restoreSession key as true in linkOptions. Since it is not necessary to show wallet selector modal when restoring a session, this function will not display the modal selector.

restoreSession = async () => {
    try {
      const { link, session } = await ConnectWallet({
        linkOptions: { chainId: this.chainId, endpoints: this.endpoints, restoreSession: true},
        transportOptions: { requestAccount: this.requestAccount },
        selectorOptions: { appName: this.appName, appLogo: appLogo, showSelector: false}
      });
      this.link = link;
      this.session = session;
​
      if (session) {
        return { auth: this.session.auth, accountData: this.session.accountData[0] };
      } else {
        return { auth: { actor: '', permission: '' }, accountData: {}};
      }
    } catch(e) {
      return e;
    }
  }
}

Running on Local Environment

To contribute and improve our open source code for the Proton Web SDK, you can run the packages locally to see changes as you're updating the SDK. Clone the ProtonWeb repository from Github. The following steps require yarn and the npm packages lerna and tsdx. Upon navigating to the ProtonWeb repository, run the following command:

yarn && lerna bootstrap

Install dependencies in the following order (ReadMe in Github for details):

1. proton-signing-request

2. proton-link

3. proton-browser-transport

4. proton-transit-provider

5. proton-web-sdk

Run yarn watch in the root folder of ProtonWeb and you should see that each of the dependencies have been compiled successfully. To see the built in example, run yarn start on a separate terminal.

In order to connect your project to ProtonWeb locally, use yarn link. Navigate to the proton-web-sdk in the packages folder in ProtonWeb and run yarn link. After, navigate to your project and run yarn link @proton/web-sdk to link your project to your local proton-web-sdk repository.