-
Notifications
You must be signed in to change notification settings - Fork 206
Wallet Service
Beam wallet service allows to implement lightweight wallets using BEAM API.
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.
-
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 theUbuntu 18.04 Desktop
section. -
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. -
Clone the repository
git clone https://github.com/BeamMW/wallet-service.git
-
Checkout the necessary branch. We use the
master
branch for development. To be able to connect to the testnet you have to checkout thetestnet
branch. To be able to connect to the mainnet you have to checkout themainnet
branch.cd wallet-service git checkout testnet
-
Init submodules
git submodule update --init --recursive
-
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 thewallet-service/service
folder. Mainnet binaries do not have the-BRANCHNAME
postfix. -
Build
service-balancer
cd service-balancer && go build && cd ..
After the build process completes you would have the
service-balancer
binary in thewallet-service/service-balancer
folder. N.B. At the moment manual builds do not add-masternet/-testnet
postfix to theservice-balancer
executable.
You can get the latest prebuilt wallet service binaries here.
-
Testnet
-
Masternet
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.
Currently the Wallet Service is deployed for masternet & testnet and provides the following public Service Balancer endpoints
-
Testnet
wss://web-wallet-testnet.beam.mw/ws
-
Masternet
wss://web-wallet-masternet.beam.mw/ws
Wallet service exposes its API only via JSONRpc v2.0 over WebSockets. To access the API you should
- Login to the balancer and get the API enpoint. Check the how to try section for the list of our public balancer endpoints.
- 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 provides the following methods:
In addition to the Web Sockets API Service Balancer provides the following HTTP(S) endpoints:
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 to the BBS address notifications to be notified about incoming transaction. Reserved for future use
Unsubsribe from the BBS address notifications. Reserved for future use
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 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:
- https://web-wallet-testnet.beam.mw/status?secret=secret
- https://web-wallet-masternet.beam.mw/status?secret=secret
Wallet Service API provides the following methods:
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 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 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
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
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
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 service also implements all the BEAM Wallet Protocol API methods. Please consult the Beam wallet protocol API section for details.
<!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:
These methods are supported by the keykeeper and client should implement a simple proxy:
<!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>
We provide the reference web wallet implementation that combines all the described APIs together and yields the working chrome extension.
-
Check out the web-wallet repository for the source code
-
Install the testnet chrome extension