Skip to content

Wallet Service

Jump to bottom
chapati edited this page Aug 3, 2020 · 95 revisions

Beam wallet service allows to implement lightweight wallets using BEAM API.

How to build

Wallet service and related projects are supposed to be run on Linux only. It is possible to build everything for Windows and using Windows but it is not oficially supported. Releases are also provided only for Linux.

  1. Install required tools to build the generic BEAM project. Refer BEAM build instructions for detals. For example if you're using Ubuntu 18.04 Desktop you need to execute steps 1. Install dependencies & 2. Install cmake from the Ubuntu 18.04 Desktop section.

  2. Install golang. You need at least v1.13.0 to build the project. If the relevant package is provided with your OS it is better to use it. For example sudo dnf install golang on Fedora. If your OS doesn't not provide recent golang packages (like Ubuntu 18.04) use instructions from the official website.

  3. Clone the repository

    git clone https://github.com/BeamMW/wallet-service.git

  4. Checkout the necessary branch. We use the master branch for development. To be able to connect to the testnet you have to checkout the testnet branch. To be able to connect to the mainnet you have to checkout the mainnet branch.

    cd wallet-service
git checkout testnet

  5. Init submodules

    git submodule update --init --recursive

  6. Build wallet-service & sbbs-monitor. Use build commands from the BEAM build instructions according to your OS.

    For example for Fedora

    cmake -DCMAKE_BUILD_TYPE=Release . && make -j4

    For Ububtu 18.04 Desktop

    export CC=gcc-8 && export CXX=g++-8
cmake -DCMAKE_BUILD_TYPE=Release && make -j4

    After the build process completes you would have wallet-service(-testnet/-masternet) & sbbs-monitor(-testnet/-masternet) binaries in the wallet-service/service folder. Mainnet binaries do not have the -BRANCHNAME postfix.

  7. Build service-balancer

    cd service-balancer && go build && cd ..

    After the build process completes you would have the service-balancer binary in the wallet-service/service-balancer folder. N.B. At the moment manual builds do not add -masternet/-testnet postfix to the service-balancer executable.

Prebuilt binaries

You can get the latest prebuilt wallet service binaries here.

  1. Testnet

  2. Masternet

Deployment

At the moment it is advised to use our public API enpoints until the deployment procedure is stabilized and made public. Docker would be available as well as the detailed deployment guide.

How to try

Currently the Wallet Service is deployed for masternet & testnet and provides the following public Service Balancer endpoints

  1. Testnet

    wss://web-wallet-testnet.beam.mw/ws

  2. Masternet

    wss://web-wallet-masternet.beam.mw/ws

API Guide

Wallet service exposes its API only via JSONRpc v2.0 over WebSockets. To access the API you should

  1. Login to the balancer and get the API enpoint. Check the how to try section for the list of our public balancer endpoints.
  2. Communicate with the API enpoint using the Wallet Service API.

Too keep user 'secrets' at the user's side Wallet Service doesn't ask for the seed phrase. Instead it expects the client to implement a set of methods that deal with secrets/outputs creation/signing, i.e. user-side keykeeper. We provide default WebAssembly implementation of the keykeeper for JS/Web usage. Check the key keeper section for details.

Service Balancer API

Service Balancer API provides the following methods:

In addition to the Web Sockets API Service Balancer provides the following HTTP(S) endpoints:

login

Login to the service balancer and get the wallet service endpoint

<--
{
    "jsonrpc": "2.0",
    "id": "123",
    "method": "login",
    "params":
    {
        "WalletID": "wallet id",
        "SbbsAddress": "",
        "SbbsAddressPrivate": ""
    }
}
  • WalletID - wallet id, get it from keykeeper.getWalletID method based on the generated seed
  • SbbsAddress - reserved for future use, leave empty for now
  • SbbsAddressPrivate - reserved for future use, leave empty for now
-->
{
    "jsonrpc": "2.0",
    "id": "123",
    "result": {
        "endpoint": "web-wallet-testnet.beam.mw?service=30000"
    }
}
  • endpoint - returns wallet service endpoint used to access Walet Service API & Beam Wallet API. You should manually append the web socket protocol prefix wss:// in front of it.

subscribe

Subscribe to the BBS address notifications to be notified about incoming transaction. Reserved for future use

unsubscribe

Unsubsribe from the BBS address notifications. Reserved for future use

balancer root (/)

Just a 'hello world' endpoint. Returns the Hello! This is the wallet service balancer string. It is intended to be used for alive checks.

/status

Status endpoint. Returns json with the internal service balancer methods.

/status?secret=secret

Expects secret (password) to be provided. Secret is configured in the balancer's config.json file. For testent & masternet this endpoint is public and can be accessed by anyone:

Wallet Service API

Wallet Service API provides the following methods:

create_wallet

Create new wallet

<--
{
    "jsonrpc": "2.0",
    "id": "123",
    "method": "create_wallet",
    "params":
    {
        "pass": "wallet password",
        "ownerkey": "wallet owner key",
    }
}
  • pass - initial wallet password
  • ownerkey - wallet owner key, get it from key keeper
-->
{
    "jsonrpc": "2.0",
    "id": "123",
    "result": "wallet id"
}
  • result - returns wallet id used to identify the wallet in other API calls

open_wallet

Open wallet with the given ID and password.

<--
{
    "jsonrpc": "2.0",
    "id": "123",
    "method": "open_wallet",
    "params":
    {
        "id": "<wallet ID>",
        "pass": "<wallet password>"
    }
}
  • id - wallet id returned by the create_wallet method or by the keykeeper.getWalletID method
  • pass - wallet password used to create wallet
-->
{
    "jsonrpc": "2.0",
    "id": "123",
    "result": "adc18c1afbb74674b5853fb4350df70a"
}
  • result - unique session id. Reserved for the future use

change_password

Change wallet password. Wallet must be already opened when this method is called.

<--
{
    "jsonrpc": "2.0",
    "id": "123",
    "method": "change_password",
    "params":
    {
        "new_pass": "new password"
    }
}
  • new_pass - new wallet password
-->
{
    "jsonrpc": "2.0",
    "id": "123",
    "result": "done"
}
  • result - "done" on success

release

Close (release) the currently opened wallet. Usually it is not necessary to call this method. Wallet would be automatically closed as soon as the web socket connection is released.

<--
{
    "jsonrpc": "2.0",
    "id": "123",
    "method": "release"
}

This method does not have any parameters.

-->
{
    "jsonrpc": "2.0",
    "id": "123",
    "result": "done"
}
  • result - "done" on success

calc_change

Service method used to calculate change for the given transaction amount

<--
{
    "jsonrpc": "2.0",
    "id": "123",
    "method": "calc_change",
    "params":
    {
        "amount": 100
    }
}
  • amount - transaction amount in groth
-->
{
    "jsonrpc": "2.0",
    "id": "123",
    "result": {
        "change": 499999900,
        "change_str": "499999900"
    }
}
  • change - transaction change in groth
  • change_str - string representation of the change parameter

ping

Just a convenience ping (are you alive?) method. It is recommended not to use this method but to rely on the underlying websocket infrastructure which already implements ping-pong control frames.

<--
{
    "jsonrpc": "2.0",
    "id": "123",
    "method": "ping"
}

This method does not have any parameters.

-->
{
    "jsonrpc": "2.0",
    "id": "123",
    "result": "pong"
}
  • result - "pong" on success

wallet API methods

Wallet service also implements all the BEAM Wallet Protocol API methods. Please consult the Beam wallet protocol API section for details.

WebAssembly Keykeeper

Get latest testnet version

Keykeeper initialization example:

<!DOCTYPE html>
<html>
<script src='wasm-key-keeper.js'></script>
<script type="text/javascript">
	Module().then((Module) => console.log(`Key Keeper module successfully loaded.`))
</script>
</html>

Handling methods from Wallet Service example:

<!DOCTYPE html>
<html>
<script src='wasm-key-keeper.js'></script>
<script type="text/javascript">
    Module().then((Module) => {
        var connection = null;
        var endpoint = 'ws://url-to-service';
        var seed = Module.KeyKeeper.GeneratePhrase();
	var keykeeper = new Module.KeyKeeper(seed);
        connection = new WebSocket(endpoint);
        connection.onmessage = e =>  {
	    var data = JSON.parse(e.data);
            if(data.method) {
	        var res = keykeeper.invokeServiceMethod(e.data);
		connection.send(res);
	    }
       }
    })
</script>
</html>

Wallet Service expects the following methods to be implemented at the client side:

Reference Wallet Implementation

We provide the reference web wallet implementation that combines all the described APIs together and yields the working chrome extension.

Home

API

IPFS

Clone this wiki locally