TrustVault Node.js SDK

Installation

Creating a TrustVault Client

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 Bitpanda Custody to get one.

See TrustVault Node.js SDK in github

Sign callback

There are only two ways to receive a payload to sign after creating a transaction. A sign callback via the SDK or a Webhook.

If you don't have access to webhooks, then a sign call back is the best way to sign the transaction created.

The sign callback is called after the request has been created, passing in the request data that needs to be signed as a parameter. The callback allows you to immediately sign the created request. In production environments it is strongly advised that you confirm the shaSignData that was passed in your sign callback is what you expect by re-creating the shaSignData using your original input values.

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, the request can then be signed on the iOS device. See request statuses below.

type SignCallback = (signDataBuffer: SignDataBuffer) => Promise<PublicKeySignaturePairBuffer>;
interface SignDataBuffer {
  // The DER encoded transaction digest and the wallet path
  signData: Buffer;
  // The SHA256 digest of the signData
  shaSignData: Buffer;
}
interface PublicKeySignaturePairBuffer {
  publicKey: Buffer; // 65 bytes - (`04` prefixed publicKey)
  signature: Buffer; // 64 bytes - (r + s ~ 32 bytes + 32 bytes)
}

An example of a sign callback (AWS KMS implementation) can be found on the README of our github repo.

AWS KMS wrapper class (AwsKmsKeyStore)

This is an example of how you can use AWS KMS to sign transactions via the SDK. You should have your own AWS account, with your own AWS KMS instance, which should be securely locked down via IAM roles.

This sample class, AwsKmsKeyStore, shows how you can ensure 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. The AwsKmsKeyStore implementation can be found here

Create a new sub-wallet

This allows you to create a new sub-wallet inside an existing wallet. You can use the get sub-wallets to find your existing walletIds. Since a walletId will never change (it can only be deleted). You may consider hard coding the walletId.

Please note: this method will return a Provenance Signature (trustVaultProvenanceSignature) of the signed PublicKey from the TrustVault API which will be checked against the TrustVault Master Public Key to ensure validity and will then generate the address on the client to ensure the address given (verifiedAddress) is correct.

Returns

{
  "subWalletId": "c7e828ed-77a3-4907-b129-651c2377a929/ETH/1",
  "receiveAddressDetails": {
    "path": [
      "0x8000002c",
      "0x8000003c",
      "0x80000001",
      "0x0",
      "0x0"
    ],
    "publicKey": "0474567eac06c8b185483f8692ff6093793479449a886556febe9883ef350c4715051b0a6984b0bad4b8a2d9c538fe424db66b76e2f198a405d39007ed97313c6e",
    "trustVaultProvenanceSignature": "00f61212deadc84f10f68bc1454a3bc297df09309fa0fcedaaceb2685e2bbfa2131db56585c739e94df30144854291cc44d77db64963c6a2f1f81a5835364227",
    "verifiedAddress": "0x07EC8dead12323EF3DF095Ff1a10D88E0d17cA35"
  }
}

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.

Get a single sub-wallet

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

Returns

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

Send a Ripple Transaction

Passing in a sign callback function as the last parameter to sendRipple(...) above will verify and sign the transaction as well.

Send a Bitcoin Transaction

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

Send an Ethereum Transaction

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

NB: Supported Assets are here

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. This method is useful for testing as it simply changes the policy to allow a single key to sign transactions.

With version 1.5.5 and above you can now generate more complex wallet delegate policy which may be more useful in a production environment.

The delegate schedule is an array of Schedules. Each Schedule is "OR"'d by TrustVault. Inside each Schedule is an array of Clauses. Each Clause is "AND"'d. Each Clause defines a quorum which is the minimum number of keys that must sign for the Clause to be satisfied.

The sample below shows a single Schedule which has 2 Clauses. Since Clauses are "AND"'d, BOTH must be satisfied.

You can read this policy as:

1 of 2 AND 1 of 1.

i.e. If 1 of the 2 keys in the first Clause has signed AND the 1 key of the second Clause has signed, this policy is satisfied.

You can also pass a Sign callback to this method to immediately sign the request. Alternatively, you can wait for the webhook (POLICY_CHANGE_REQUEST_CREATED) to be received by your API and then sign the item from there. See below for signing the webhook request.

Note: Each delegate listed AND Bitpanda Custody MUST sign the change request before the policy can become active.

Validating and signing a webhook request

Validate the webhook, sign and submit the signature to TrustVault

NOTE: validateWebhookSignature is a static method

Create a new Bitcoin Address

Create a new bitcoin address for the given subWalletId

Get request

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

Returns

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

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

You can also pass a second optional parameter that specifies the reason for cancelling the request.

Returns (boolean)

true

Request Statuses

Request Status	Description
AWAITING_SIGNATURES	the request is still awaiting signatures enough signature before it can be processed
SIGNED	the request has received enough signatures to be processed
SUBMITTED	the transaction request has been processed and submitted to the network
CONFIRMED	the transaction request has been confirmed by the network (1+ confirmation)
PROCESSED	the request has been successfully processed
USER_CANCELLED	the request has been cancelled by the user
ERROR	an error occurred when processing the request

Installation#

Creating a TrustVault Client#

Overview#

Sign callback#

AWS KMS wrapper class (AwsKmsKeyStore)#

Create a new sub-wallet#

Returns#

Get a list of all sub-wallets#

Get a single sub-wallet#

Returns#

Send a Ripple Transaction#

Send a Bitcoin Transaction#

Send an Ethereum Transaction#

Changing the external instruction key of a wallet#

Validating and signing a webhook request#

Create a new Bitcoin Address#

Get request#

Returns#

Cancel Request#

Returns (boolean)#

Request Statuses#

Installation

Creating a TrustVault Client

Overview

Sign callback

AWS KMS wrapper class (AwsKmsKeyStore)

Create a new sub-wallet

Returns

Get a list of all sub-wallets

Get a single sub-wallet

Returns

Send a Ripple Transaction

Send a Bitcoin Transaction

Send an Ethereum Transaction

Changing the external instruction key of a wallet

Validating and signing a webhook request

Create a new Bitcoin Address

Get request

Returns

Cancel Request

Returns (boolean)

Request Statuses