Proton
Search…
Proton
Overview
Proton Web SDK
Proton Swift
Proton Kotlin
Proton React Native SDK
Powered By GitBook
Proton Web SDK
Proton Web SDK is a one-stop package to handle all communications with Proton Wallets through a web application.

Installation

This library is currently under heavy development. Please be aware that all functionality is subject to change at any time. Documentation and examples are also constantly being worked on and will be added over time as well.
This documentation is updated for v2.7.16
If you would like to contribute to our open source code, you can do so here - https://github.com/ProtonProtocol/ProtonWeb​
Proton is available through npm. Add Proton as a dependency using the npm install command.
1
npm install @protonprotocol/proton-web-sdk
Copied!

Instantiation

To use and instantiate, first import the ConnectWallet function from the SDK.
1
import { ConnectWallet } from '@protonprotocol/proton-web-sdk'
Copied!
The following is a list of arguments that ConnectWallet accepts in matching order.
Argument
Type
Required
Effect
linkOptions
Object
true
Customize options for communication with chain
transportOptions
Object
false
Customize options for transport (communication with client)
selectorOptions
Object
false
Customize display options for wallet selection

linkOptions:

Key
Type
Required
Description
endpoints
array
true
List of chain API endpoints
chainId
string
false
Chain ID or PSR chain name alias for which the link is valid
storage
LinkStorage
false
Storage interface (see below)
storagePrefix
string
false
Optional prefix added to key names of stored items if default storage is used
restoreSession
boolean
false
Determine if connection request is to restore a saved session. This will not prompt the wallet selector modal to pop up if restoring a session.
Only one endpoint is needed, but the function accepts an array of multiple endpoints for fault tolerance
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.
1
export interface LinkStorage {
2
/** Write string to storage at key. Should overwrite existing values without error. */
3
write(key: string, data: string): Promise<void>
4
/** Read key from storage. Should return `null` if key can not be found. */
5
read(key: string): Promise<string | null>
6
/** Delete key from storage. Should not error if deleting non-existing key. */
7
remove(key: string): Promise<void>
8
}
Copied!

transportOptions:

Key
Type
Description
requestAccount
string
Account that is requesting the transaction with client
*Will most likely be the same as appName
**Optional, but will display "Unknown Requestor' in transaction request
if no value is given
backButton
boolean
Option to disable the back button in transport modal to return to wallet selector modal. Automatically shows the back button unless specified to false.

selectorOptions:

Key
Type
Description
appName
String
Name of app to display in wallet selector
appLogo
String
Logo image of app to display in wallet selector
customStyleOptions
Object
Custom styles for the wallet selector modal for further customization. This is an optional object to pass in. If nothing is passed in, it will default to a white modal. This is particularly useful if you would like to change the background for dark mode websites.
Custom Styling for Wallet Selector Modal
The wallet selector modal can be customized like so with the following example:
Customized modal selector
1
customStyleOptions: {
2
modalBackgroundColor: '#F4F7FA',
3
logoBackgroundColor: 'white',
4
isLogoRound: true,
5
optionBackgroundColor: 'white',
6
optionFontColor: 'black',
7
primaryFontColor: 'black',
8
secondaryFontColor: '#6B727F',
9
linkColor: '#752EEB'
10
};
Copied!
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.
Key
Type
Value options
scheme
string
Production: 'proton'
Development: 'proton-dev'
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

1
class ProtonSDK {
2
constructor() {
3
this.chainId = process.env.REACT_APP_CHAIN_ID;
4
this.endpoints = [process.env.REACT_APP_CHAIN_ENDPOINT]; // Multiple for fault tolerance
5
this.appName = 'appName';
6
this.requestAccount = 'accountName'; // optional
7
this.session = null;
8
this.link = null;
9
}
Copied!
The above is an example using React.js to serve as reference for the methods below.

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.
1
login = async () => {
2
try {
3
const { link, session } = await ConnectWallet({
4
linkOptions: { chainId: this.chainId, endpoints: this.endpoints },
5
transportOptions: { requestAccount: this.requestAccount, backButton: true },
6
selectorOptions: { appName: this.appName, appLogo: appLogo}
7
});
8
this.link = link;
9
this.session = session;
10
return { auth: session.auth, accountData: session.accountData[0] };
11
} catch (e) {
12
return e;
13
}
14
}
Copied!
Note when using ConnectProton, a scheme value is also required in the linkOptions argument.
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.
1
sendTransaction = async (actions) => {
2
try {
3
const result = await this.session.transact(
4
{ actions: actions },
5
{ broadcast: true }
6
);
7
return result;
8
} catch (e) {
9
return e;
10
}
11
}
Copied!
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.
1
const actions = [{
2
account: 'xtokens',
3
name: 'transfer',
4
authorization: [{
5
actor: actor,
6
permission: permission
7
}],
8
data: {
9
from: actor,
10
to: ProtonSDK.requestAccount,
11
quantity: '1.000000 XUSDT',
12
memo: 'memo'
13
}
14
}];
Copied!
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.
For any transactions with X wrapped tokens, the account must be set to xtokens
For all other transactions including XPR, the account must be set to eosio.tokens
FOOBAR token is a fake token that can be used for testing purposes on Proton Chain mainnet. This token is dispensed for free at the Foobar Faucet. For any transactions with FOOBAR token, please reference the code block below.
1
const actions = [{
2
account: 'xtokens',
3
name: 'transfer',
4
authorization: [{
5
actor: actor,
6
permission: permission
7
}],
8
data: {
9
from: actor,
10
to: ProtonSDK.requestAccount,
11
quantity: '5.000000 FOOBAR',
12
memo: 'memo'
13
}
14
}];
Copied!
Account
Decimal Places For Transactions
Examples Tokens
xtokens
6
FOOBAR, XUSDT
eosio.token
4
XPR

Logout

To logout, call the logout method with appName and sesstion.auth as arguments.
1
logout = async () => {
2
await this.link.removeSession(this.requestAccount, this.session.auth);
3
}
Copied!

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.
1
restoreSession = async () => {
2
try {
3
const { link, session } = await ConnectWallet({
4
linkOptions: { chainId: this.chainId, endpoints: this.endpoints, restoreSession: true},
5
transportOptions: { requestAccount: this.requestAccount },
6
selectorOptions: { appName: this.appName, appLogo: appLogo, showSelector: false}
7
});
8
this.link = link;
9
this.session = session;
10
​
11
if (session) {
12
return { auth: this.session.auth, accountData: this.session.accountData[0] };
13
} else {
14
return { auth: { actor: '', permission: '' }, accountData: {}};
15
}
16
} catch(e) {
17
return e;
18
}
19
}
20
}
Copied!
If there is no saved session or if saved session information is incomplete, the ConnectWallet function will return { null, null } and will remove any remaining saved information to remove unexpected side effects.

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:
1
yarn && lerna bootstrap
Copied!
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
The dependencies must be installed using yarn.
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.
Previous
Overview
Next
Proton Swift
Last modified 7mo ago
Copy link
Contents
Installation
Instantiation
Usage
Class Initialization
Login
Transaction
Logout
Restore Session
Running on Local Environment