Axios based node.js wrapper for Tangany WaaS
Getting started
Install the npm package
npm install @tangany/waas-js-sdk
Configure the SDK
const { Waas } = require("@tangany/waas-js-sdk");
// load the environment variables via e.g. dotenv
const dotenv = require("dotenv");
dotenv.config();
// pass the configuration to instantiate the SDK
const api = new Waas({
clientId: process.env.CLIENT_ID,
clientSecret: process.env.CLIENT_SECRET,
subscription: process.env.SUBSCRIPTION,
vaultUrl: "https://my-vault.some.cloud.tld"
});
// e.g. fetch all client wallets
(async () => {
let skiptoken = undefined;
async function listNextPage () {
const {data} = await api.wallet().list(skiptoken);
skiptoken = data.skiptoken;
return data;
}
do {
const { list } = await listNextPage();
console.log(list);
}
while (!!skiptoken); // fetch until no skiptoken is returned in the response
})();
Constructor options
WaaS configuration headers are passed as options into the constructor.
option | description | mandatory |
---|---|---|
clientId | Service to service authentication client ID | |
clientSecret | Service to service authentication client secret | |
subscription | Product subscription key | |
vaultUrl | Tangany vault url. Example: https://my-vault.some.cloud.tld
|
|
ethereumNetwork | Public Ethereum network to operate in (mainnet , ropsten ) or private Ethereum network Custom RPC URL for a private Ethereum network to operate in (example: http://somenetwork.example.org:8540 ). Defaults to mainnet
|
|
ethereumTxSpeed | Additional gas fee that is added to the base gas fee for the given Ethereum network to speed up the mining process of the transaction. The usage of none value may result in the transaction never gets mined and is only intended to use for custom Ethereum networks that employ zero gas price policies. The speed levels correspond with following Ethereum fees (in gwei): none : 0, slow : 2, default : 5, fast : 15. Defaults to default . |
|
bitcoinNetwork | Public Bitcoin network name. Supported networks: bitcoin , testnet . Defaults to bitcoin
|
|
bitcoinTxConfirmations | Minimum amount of block confirmations required for Bitcoin balance outputs ("utxo", "coins") to be included in the total wallet balance calculation. The exclusion of unconfirmed outputs prevents the posthumous invalidation of own wallet transaction by the parent utxo sending party. The levels correspond with following target block confirmations amount (# of confirmations): none : 0, default : 1, secure : 6. Defaults to default . |
|
bitcoinTxSpeed | Defines the target amount of blocks for the transaction to be included to the Bitcoin network. Faster inclusion requires a higher transaction fee. The fee is calculated in real time based on the network state and can be limited by the header-bitcoin-max-fee-rate option. The effective transaction delay can be calculated by multiplying the target confirmation blocks with the Bitcoin block time of 10 minutes (e.g. slow yields an block inclusion time of approx. 4h). The speed levels correspond with following block times (target blocks): slow : 24, default : 6, fast : 2. Defaults to default
|
|
bitcoinMaxFeeRate | Defines the maximum allowed fee rate in satoshi per byte for a Bitcoin transaction. Prevents from spending absurdly high transaction fees during block fee peaks |
More examples
For more examples check out the tests (e.g. ./test/*.e2e.js)
Wallet interface
Global wallet management https://tangany.docs.stoplight.io/api/wallet/
(async () => {
const api = new Waas(options);
// list all wallets
const { list } = (await api.wallet().list()).data;
// create a new wallet
const { wallet, security } = (await api.wallet().create("some-other-wallet", false)).data;
// fetch a wallet
const { created } = (await api.wallet(wallet).get()).data;
// delete a wallet
const { scheduledPurgeDate, recoveryId } = (await api.wallet(wallet).delete()).data;
})();
General Ethereum interface
Ethereum calls that are not wallet based
(async () => {
const api = new Waas(options).eth(txHash);
// get transaction status
const { blockNr, isError } = (await api.get()).data;
// poll until the transaction is mined (for max 60 seconds)
await api.wait(60e3);
})();
Ethereum interface for wallet
Wallet based Ethereum calls https://tangany.docs.stoplight.io/api/ethereum/
(async () => {
const api = new Waas(options).wallet("my-wallet");
// send Ether
const { hash } = (await api.eth().send({to: someOtherWalletAddress, amount: "0.043", data: "0xf03"})).data;
// get eth balance and wallet address
const { currency, balance, address } = (await api.eth().get()).data;
})();
Ethereum ERC20 token interface for wallet
Wallet based calls for Ethereum ERC20 token management https://tangany.docs.stoplight.io/api/ethereum-erc20
(async () => {
const api = new Waas(options).wallet("my-wallet").eth().erc20(tokenAddress);
// send token
const { hash } = (await api.send({to: someOtherWalletAddress, amount: "0.043"})).data;
// get token balance
const { currency, balance, address } = (await api.get()).data;
// mint token
await api.mint({amount: "12.291", to: someOtherWalletAddress}); // assuming myWalletAddress is erc20token's minter
// approve token withdrawal
await api.approve({to: someOtherWalletAddress, amount: "213"});
// withdraw pre-approved tokens
await new Waas(options).wallet("some-other-wallet").eth().erc20(tokenAddress).transferFrom({from: myWalletAddress, amount: "213"});
// burn token
await new Waas(options).wallet("some-other-wallet").eth().erc20(tokenAddress).burn({amount: "2"});
})();
General Bitcoin interface
Bitcoin calls that are not wallet based
(async () => {
const api = new Waas(options).btc(hash);
// get transaction status
const { confirmations, status } = (await api.get()).data;
// poll every second until the transaction is mined (for max 720 seconds)
await api.wait(720e3, 1e3);
})();
Bitcoin interface for wallet
Wallet based Bitcoin calls https://tangany.docs.stoplight.io/api/bitcoin/
(async () => {
const api = new Waas(options).wallet("my-wallet");
// estimate fee for a transaction
const { fee, feeRate } = (await api.btc().estimateFee({to: someAddress, amount: "0.021"})).data;
// send BTC to a single recipient
const { hash } = (await api.btc().send({to: someAddress, amount: "0.021"})).data;
// send BTC to multiple recipients
await api.btc().send([{to: someAddress, amount: "0.324"}, {to: someOtherAddress, amount: "0.021"}]);
// get BTC balance and wallet address
const { balance,address,currency } = (await api.btc().get()).data;
})();
Affinity Cookies
WaaS employs its own load-balanced full-node backend to transmit transactions to the blockchains. Due to the nature of blockchain, full nodes sync their states only in the event of a new block. One implication of this behavior is that sending multiple transactions from the same wallet during a time frame of a single block may lead to an overlap of backend memory pool assignments which subsequent may result in transactions being cancelled and discarded from the blockchain.
E.g. two Ethereum transactions sent to different full nodes from the same wallet shortly one after the other may be assigned the same nonce number by two different full nodes in the backend resulting in Ethereum, by specification, cancelling the former of the two transactions.
To prevent such pooling issues, WaaS supports sticky sessions using the affinity cookies.
Although each Waas
instance does automatically store its individual affinity cookie after a API call, racing conditions may occur when sending multiple simultaneous transactions from a new instance. To prevent such racing conditions it is advised to pre-establish a sticky session using e.g. await waas.eth().fetchAffinityCookie()
.
Check out the example implementation in test/limiter.e2e.js where a high amount of non-overlapping Ethereum transactions are transmitted simultaneously via pre-established sticky session.
Changelog
All notable changes to this project are documented in the changelog
Testing
Copy .env.example
to .env
and enter you WaaS subscription details to be able to run the tests. Use testnet faucets to charge a wallet with some crypto and paste the name to the WALLET
variable.
Start the test suite with npm run test:e2e
Debugging
To enable additional logging (e.g. to debug HTTP requests), use following environment variable
DEBUG=waas-js-sdk:*
API documentation
Full API documentation is available at https://tangany.docs.stoplight.io/
© 2019 Tangany
Imprint • Privacy policy • Newsletter • Twitter • Facebook • LinkedIn • YouTube • Github