Installation

1
2
3

$ npm i @trustology/trustvault-nodejs-sdk
# Or:
$ yarn add @trustology/trustvault-nodejs-sdk

Creating a TrustVault Client

1
2
3
4
5
6
7
8
9
10
11

// common
const { TrustVault } = require("@trustology/trustvault-nodejs-sdk");

// es6
import { TrustVault } from "@trustology/trustvault-nodejs-sdk";

// sandbox env
const trustVaultSandbox = new TrustVault({ apiKey: "<TRUST_VAULT_API_KEY>", environment: "sandbox" });

// production
const trustVault = new TrustVault({ apiKey: "<TRUST_VAULT_API_KEY>"});

Overview

The SDK wraps the TrustVault GraphQL interface and gives you easy access to core functionalities within the API.

The API can be configured against sandbox (ETH ropsten, BTC testnet3) or production environments.

The SDK is focussed on sub-wallets. This article will help on understanding the differences between wallets and sub-wallets.

If you use the SDK with an external instruction key the SDK provides callbacks for you to sign the correct data when creating a transaction or requesting a policy change on a wallet.

The SDK includes helper methods to ensure the data integrity including validating policy template, publicKey provenance, HMAC webhook payload and digests. This ensures that the digests that need signing contain the input data specified from the SDK. This helps prevents man-in-middle attacks.

It also includes a sample AWS KMS wrapper class for data signing.

The SDK requires an API key, please contact Trustology to get one.

See TrustVault Node.js SDK in github

Sign callback

The function that will be called with the data that needs to be signed.

Sign callback is optional for replacePublicKeyInDefaultSchedule, sendBitcoin and sendEthereum methods. If the sign callback is not given, the created request will not be signed and will stay in AWAITING_SIGNATURES status. See request statuses below

AWS KMS wrapper class (AwsKmsKeyStore)

AwsKmsKeyStore class ensures that the correct key from the correct curve is used for signing. It has a method sign which is an implementation of the signCallback.

You will need to ensure that your code has the relevant AWS permissions to access your KMS key.

Get a list of all sub-wallets

This allows you to page through all the sub-wallets. The default is to return 20 items per call. The following code will retrieve all sub-wallets associated with the API key by paging through them 10 at a time. Use with caution if you have hundreds of sub-wallets.

1
2
3
4
5
6
7
8
9
10

let nextToken;
do {
  const subWallets: ResultConnection<SubWallet[]> = await trustVault.getSubWalletsConnection({
    limit: 10, // retrieve 10 at a time
    nextToken,
    includeBalances: true // return the balances for each sub-wallet
  });
  // process the subWallets with subWallets.items
  nextToken = subWallets.nextToken;
} while (nextToken);

Get a single sub-wallet

Retrieve the specific subWallets associated. Use this method to get a specific sub-wallet based on the subWalletId.

1

const subWallet = await trustVault.getSubWallet("0bee0ebb-f3b8-47af-a4aa-d7f1755d89e4/ETH/0");

Returns

1
2
3
4
5
6
7
8
9
10
11
12

{
  "address": "0x829bd824b016326a401d083b33d092293333a830",
  "name": "Test",
  "subWalletId": "3623d274-337e-4cf6-b496-37a4b638f3c1/ETH/0",
  "createdAt": "2020-04-01T15:43:45.000Z",
  "updatedAt": "2020-04-01T15:43:45.000Z",
  "chain": "ETHEREUM",
  "publicKey": "04b2536695a94f0ce089471e8b98da134ed6eac1c10b07d5b57d90b26936aafe33ef137225a935f953ef99ab3a4cd0c7b4e881bef9deb4bb187b7da4c37b715e58",
  "trustVaultPublicKeySignature": "df7fe7e1b3e2a40abf2dd0116714eeb0386cc6be4fad3df2e58464105f8af2f18e998cefe6894bea617ddf7cdc370a218ddeaf3b3c3308af22baf9e655391358",
  "__typename": "BlockchainSubWallet",
  "walletId": "3623d274-337e-4cf6-b496-37a4b638f3c1"
}

You can additionally, pass an options object to request balances of the sub-wallet. This will be slightly slower as it will retrieve balances of all assets

1

const subWallet = await trustVault.getSubWallet("0bee0ebb-f3b8-47af-a4aa-d7f1755d89e4/ETH/0", { includeBalances: true });

Send a Bitcoin Transaction

Send a bitcoin transaction. This will still need to be signed by the wallet policy delegates.

1

const requestId = await trustVault.sendBitcoin(fromSubWalletId, toAddress, amount, speed, signCallback);

Send an Ethereum Transaction

Send an ethereum transaction. This will still need to be signed by the wallet policy delegates.

1

const requestId = await trustVault.sendEthereum(fromAddress, toAddress, amount, asset, speed, currency, signCallback)

Changing the external instruction key of a wallet

Change the external instruction key of a wallet. This is required if you wish to sign transactions yourself rather than on a registered iOS device.

1

const requestId = await trustVault.replacePublicKeyInDefaultSchedule(walletId, publicKey, signCallback);

Validating and signing a webhook request

Validate the webhook, sign and submit the signature to TrustVault

1
2
3

TrustVault.validateWebhookSignature(req.body, "<YOUR_WEBHOOK_SECRET>", req.headers["X-Sha2-Signature"]);
const webhookMessage = JSON.parse(req.body);
const requestId = await trustVault.signAndSubmitSignature(webhookMessage, signCallback);

NOTE: validateWebhookSignature is a static method

Create a new Bitcoin Address

Create a new bitcoin address for the given subWalletId

1

const address = await trustVault.createBitcoinAddress(subWalletId)

Get request

Retrieve the request item associated with the given requestId. Use this method to query the status of your request.

1

const request = await trustVault.getRequest(requestId)

Returns

1
2
3
4
5

{
    "requestId": "12b40615-ab28-5917-d576-5e05ab5d2944",
    "type": "BTC_TRANSACTION",
    "status": "SUBMITTED"
}

Cancel Request

Cancels a request item associated with the given requestId. If successful, the request will be in USER_CANCELLED status. Throws an error if the request is not in a state that can be cancelled (i.e. not AWAITING_SIGNATURES) See request statuses below

1

const success = await trustVault.cancelRequest(requestId)

Returns (boolean)

1

true

Request Statuses