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:

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

<--
{
    "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
  • 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>

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