WASM wallet client

Overview

WASM wallet client is a thin wrapper around Beam client library build into WASM using Emscripten toolchain. This wrapper allows to run BEAM wallet inside any browser supporting WebAssembly and it provides the regular BEAM wallet API to communicated with it from external(javascript) code.

API

WASM wallet client module exports following classes:

WasmWalletClient - the main object provides a set of static and member methods to control the wallet. It could be used to implement BEAM wallet as a browser extension

Method	Description
startWallet	Starts the wallet in the background thread
stopWallet	Asynchronously stops the wallet running in the background
isRunning	Checks if the wallet is running
sendRequest	Sends API request to the wallet
subscribe	Subscribes for API responses
unsubscribe	Unsubscribes from response notifications
setSyncHandler	Sets synchronization handler, allows to track sync progress
setApproveSendHandler	Sets handler which allows to approve or reject any send operation initiated by DAPPs
setApproveContractInfoHandler	Sets handler which allows to approve or reject any operation which requires user's attention from application shader
createAppAPI	Asynchronously creates new application wallet API for given application
GeneratePhrase	Generates new seed phrase
IsAllowedWord	Checks if given word is in the dictionary of the words allowed to be used in seed phrases
IsValidPhrase	Validates given seed phrase
ConvertTokenToJson	Converts given BEAM address to json
ConvertJsonToToken	Packs transaction parameters presented as JSON object into BEAM address
MountFS	Asynchronously mounts WASM filesystem to the roor of IndexDB
CreateWallet	Creates new wallet database
DeleteWallet	Deletes given wallet database from IndexDB
IsInitialized	Ensures that database was created
CheckPassword	Tests if given password fits to the database

AppAPI - a proxy API object, it gives limited wallet API for external web applications, which want to work with BEAM wallet

Method Description

callWalletApi Allows to call wallet API methods from application

setHandler Sets handler to receive response for API request

AppAPICallback - a callback object for applications, it allows the wallet to control the action which application want to perform.

Method	Description
sendApproved	Approves send request from application
sendRejected	Rejects send request from application
contractInfoApproved	Approves contract call
contractInfoRejected	Rejects contract call

WasmWalletClient

GeneratePhrase

WasmWalletClient.GeneratePhrase()

Generates new seed phrase

Return value

seed phrase, a string of 12 words from the dictionary separated separated by

Example

 var phrase = Module.WasmWalletClient.GeneratePhrase()
 console.log('seed phrase is: ', phrase);
 // OUTPUT: seed phrase is:  legend hurdle erode ribbon pass exit basket doll sorry version muscle brain

IsAllowedWord

WasmWalletClient.IsAllowedWord(word : String)

Checks if given word is in the dictionary of the words allowed to be used in seed phrases

Parameters

word : the word to be checked

Return value

true if word is in the dictionary otherwise false

Example

  if (Module.WasmWalletClient.IsAllowedWord('hurdle')) {
      console.log("Word is allowed");
  }

IsValidPhrase

WasmWalletClient.IsValidPhrase(phrase : String)

Validates given seed phrase

Parameters

phrase : a string of the words separated by

Return value

true if seed phrase is valid otherwise false

ConvertTokenToJson

WasmWalletClient.ConvertTokenToJson(token : String)

Converts given BEAM address to json

Parameters

token : address to to unpack data

Return value

json object with address parameters unpacked from given string

Notes

in beam address(token) is binary packed set the key-value parameters presented as base58 string

ConvertJsonToToken

WasmWalletClient.ConvertJsonToToken(json : String)

Packs transaction parameters presented as JSON object into BEAM address

Parameters

json : parameters of the transaction

Return value

base58 encoded string of packed parameters

MountFS

WasmWalletClient.MountFS(callback : function)

Asynchronously mounts WASM filesystem to the roor of IndexDB

Parameters

callback : mounting completion handler

Return value

none

Notes

This method should be called before any action which implies work with filesystem

Example

 Module.WasmWalletClient.MountFS(function() {
   console.log("mounted");
   var walletClient = new Module.WasmWalletClient("/beam_wallet/wallet.db",
                                                  "123",
                                                  "eu-node01.masternet.beam.mw:8200");
 }

CreateWallet

WasmWalletClient.CreateWallet(seedPhrase : String, database : String, password : String)

Creates new wallet database

Parameters

seedPhrase: seed pharse for the wallet
database : path to the database in IndexedDB
password : password to the new wallet database

Return value

none

Notes

Ensure that MountFS() has been called before

Example

 let phrase = Module.WasmWalletClient.GeneratePhrase();
 Module.WasmWalletClient.CreateWallet(phrase, "/beam_wallet/wallet.db", "123");

DeleteWallet

WasmWalletClient.DeleteWallet(database : String)

Deletes given wallet database from IndexDB

Parameters

database : path to the database file

Return value

none

Notes

Ensure that MountFS() has been called before

IsInitialized

WasmWalletClient.IsInitialized(database : String)

Ensures that database was created

Parameters

database : the path to the database

Return value

true if database is created and initialized, otherwise false

Notes

Ensure that MountFS() has been called before

CheckPassword

WasmWalletClient.CheckPassword(database : String, password : String, callback : function)

Tests asynchronously if given password fits to the database

Parameters

database : path to the database
password : password to test
callback : asynchronously returns the result of the test

Return value

none

Notes

Ensure that MountFS() has been called before

Example

  Module.WasmWalletClient.CheckPassword("/beam_wallet/wallet.db", "13", (res) => {
  if (res)
    console.log("Password is correct")
  else
    console.log("Password is not correct")
  })

Constructor

WasmWalletClient(database : String, password : String, nodeURL : String)

Creates new wallet client object

Parameters

database : path to encrypted database in browser's IndexDB
password : password to the database
nodeURL : URL to BEAM node to communicate with

Return value

object of the wallet client

Notes

wallet client can communicate with node over Web Sockets only, ensure that node located by nodeURL has WebSocket proxy enabled
ensure that MountFS() has been called before

Example

 var walletClient = new Module.WasmWalletClient("/beam_wallet/wallet.db",
                                                "123",
                                                "eu-node01.masternet.beam.mw:8200");

startWallet

function startWallet()

Starts the wallet in the background thread

Notes

wallet client can communicate with node over Web Sockets only, ensure that node located by nodeURL has WebSocket proxy enabled

stopWallet

function stopWallet(callback : function)

Asynchronously stops the wallet running in the background

Parameters

callback : calls when wallet has stopped. In this callback it is safe to delete the wallet database

Return value

none

Example

  wc.stopWallet(()=> {
    console.log("is running: " + wc.isRunning()) // false
  }

isRunning

function isRunning()

Checks if the wallet is running

Parameters

none

Return value

true if the wallet is running, false otherwise

sendRequest

function sendRequest(jsonRequest : String)

Sends API request to the wallet

Parameters

jsonRequest : API request

Return value

none

Notes

to get response you have to subscribe before

Example

 walletClient.sendRequest(JSON.stringify({
     jsonrpc: '2.0',
     id: 5,
     method: 'wallet_status'
 }));

subscribe

function subscribe(callback : function)

Subscribes for API responses

Parameters

callback : function which is called when response arrived

Return value

index of the subscription

Example

  var i = walletClient.subscribe((r)=> {
      console.log("response: " + r)
  });

unsubscribe

function unsubscribe(index : Number)

Unsubscribes from response notifications

Parameters

index : index of the subscription

Return value

none

setSyncHandler

function setSyncHandler(handler : function)

Sets synchronization handler, allows to track sync progress

Parameters

handler : called each time wallet notifies about sync progress

Return value

none

Example

 walletClient.setSyncHandler((done, total) => {
    console.log("sync [" + done + "/" + total + "]");
 });

setApproveSendHandler

function setApproveSendHandler(handler : function)

Sets handler which allows to approve or reject any send operation initiated by DAPPs

Parameters

handler : function called each time application wants to send assets from the wallet

Return value

none

Example

 walletClient.setApproveSendHandler((request, info, cb)=>{
     console.log("Request: " + request);
     console.log("Info: " + info);
     cb.setApproved(request);
     //cb.setRejected(request);
 })

setApproveContractInfoHandler

function setApproveContractInfoHandler(handler : function)

Sets handler which allows to approve or reject any operation which requires user's attention from application shader

Parameters

handler

Return value

none

Example

 walletClient.setApproveContractInfoHandler((request, info, amounts, cb)=>{
     console.log("Request: " + request);
     console.log("Info: " + info);
     cb.contractInfoApproved(request);
     //cb.contractInfoRejected(request);
 })

createAppAPI

function createAppAPI(appid : String, appname : String, callback : function)

Asynchronously creates new application wallet API for given application

Parameters

appid : ID of the application
appname : the name of the app
callback : the callback with API object in the case of success

Example

 console.log("calling API...");
 wc.createAppAPI("appid", "appname", (api)=>{
    api.setHandler((r)=> {
       console.log("API response: " + r)
    })
    api.callWalletApi(JSON.stringify({
       jsonrpc: '2.0',
        id: 5,
        method: 'wallet_status'
    }));        
 });

Method	Description
callWalletApi	Allows to call wallet API methods from application
setHandler	Sets handler to receive response for API request