Installation
1 | $ npm i @trustology/trustvault-nodejs-sdk |
Creating a TrustVault Client
1 | // common |
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 | let 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 | { |
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 | TrustVault.validateWebhookSignature(req.body, "<YOUR_WEBHOOK_SECRET>", req.headers["X-Sha2-Signature"]); |
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 | { |
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
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 |