Tangany Wallet as a Service
Tangany Wallet as a Service
API Reference
Info

Tangany ‘Wallet as a Service’

Concepts

This document describes the core concepts and workflows of the Wallet as a Service API (WaaS). For terms of technical documentation check out the API Reference Page.

Authentication

WaaS requires service credentials to authenticate and authorize API requests. Currently, only one “Service-to-Service” authentication workflow is supported targeted for usage with backend servers. Thus we currently strictly discourage to access WaaS in any client-side context to rule out possibilities of credentials leakage. Your credentials will be provided by Tangany and consist of three elements: Client ID, Client Secret, Subscription Key.

Client ID is a unique identifier for an application that is calling our service. Client Secret is a secret passphrase that authenticates the client and can be reset upon request. Subscription Key authorizes the API service level.

In case any of the credentials are lost, the Tangany support team will happily help you to re-submit existing ones or to re-create new ones.

Product Subscription

The Subscription Key serves to assign the chosen and paid service package to clients. Tangany offers different levels of packages depending on the needs of our clients.

Usage of the API is only possible with an active subscription. The package can be down- or upgraded monthly (independently of whether a yearly or monthly contract has been signed). Please reach out to our service team to do so.

Call limits

WaaS is rate-limited on a per-subscription basis at currently 10 calls/second for all endpoints. When the rate limit is exceeded, the API will return a HTTP 429 “Too Many Requests” response with an approximate time frame to retry the call.

Each subscription package includes a limited amount of free API calls. When the free contingent is depleted, a small fee is charged per-call basis. Query the endpoint /subscription to retrieve the number of calls made for the current subscription and invoicing period.

Session stickiness

WaaS employes its own load-balanced full nodes backend to transmit transactions to the supported 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 Blockchain block (“block time”) 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, it is advised to esablish sticky sessions with WaaS using the affinity cookies returned by blockchain-based WaaS calls (e.g. via calling HEAD /eth/wallet/{wallet}. Persistence with a single destinct backend node is established for the period of the session lifetime when using the affinity cookie during subsequent API calls.

Unlike browsers, server-based HTTP libraries do not store or include server-based cookies in their calls unless specifically configured to do so. It is advised to refer to the documentation of the WaaS calling HTTP library in order to enable cookie handling. This functionality is often referred to as withCredentials (cf. JavaScript fetch, curl cookies)

The WaaS JavaScript SDK (npm) does support establishing a sticky session since version 1.0.0.beta-4

const api = new Waas({...});
await api.eth().fetchAffinityCookie(); // establish sticky session
await Promise.all(recipients.map(r => api.wallet(w).eth().send(r))); // high-frequency api calls from the same wallet 

About blockchains

Networks

Most blockchain run multiple implementations that manage separate distinguished data states but share the common “play rules” of the blockchain.

Ethereum

mainnet is the official Ethereum network. ropsten, rinkeby and kovan are networks for testing and developing purposes in which Ether can be freely acquired through “faucets”. Furthermore, custom Ethereum networks exist, that are publicly or privately accessible and may deviate in some metrics from the official implementations (e.g. usage of different gas prices, custom consensus mechanism, etc.).

WaaS supports connecting to most of the public Ethereum networks via publicly available RPC Endpoints. Non-publicly available Endpoints require a custom implementation in most cases, that can be requested at sales team.

Bitcoin

bitcoin is the official Bitcoin network. testnet is also supported and represents the current testnet3 implementation in Bitcoin.

Wallets

Wallets allow users to manage the containing assets. A wallet is a representation of a blockchain account entity (“address”) that can be used to read and authorize writing data to the blockchain (transaction of funds, interactions with smart contracts, etc.). One wallet could be assigned to be used per user and blockchain, but there are no technical restrictions to do otherwise.

Private Keys

The private key is a secret blockchain credential which is needed to authorize transactions from an address or, so to speak, to execute “write access” claims to the blockchain. Once lost, the private key can never be restored and no outgoing transactions can ever be issued from the corresponding address, which usually results in a loss of funds. Furthermore, due to its complexity, a private key is not suitable to be memorized and thus is often stored insecurely that often results in key leakage and unauthorized transactions. ‘Wallet as a Service’ generates and manages private keys safely in our FIPS 140 certified Key Vault and thus inhibits the chance of key loss and unauthorized transactions.

The private key can never be extracted from the Key Vault and neither you nor your customers nor Tangany has access to the private key data. Thus it is not possible for the private key to leave the system.

Addresses

The address of a blockchain wallet is used to read the value of that wallet and to receive transactions. The address is a hash representation of the public key - a cryptographic entity derived from the wallet private key that is used to encrypt the transaction data.

Transactions

Transactions represent “writing” access to the blockchain. This could be, for example, the transfer of currencies on the blockchain or some interactions with custom smart contracts.

Most public blockchains require transactions to include a small payment or fee per execution. This Fee is collected by the transaction validator (“miner”) which executes the transaction by including it into a blockchain block. The fee must be paid with the native currency of the blockchain.

When the transaction fee is quite low compared to other transactions at a given time, the inclusion of the given transaction might take a long time. In the worst case, the transaction never gets executed which would require to resend it with a higher fee. WaaS minimizes the chance of transaction not get included into blocks by providing safe defaults for transaction fee handling.

The Fee per transaction is set by Tangany and cannot be changed. The system always aims to pay as less as possible while having an acceptable execution duration. The fee has to be paid by the transaction executed wallet.

Hashes

Once a transaction is issued to the chain, a transaction hash is generated to refer to that specific blockchain activity. Once a transaction is successfully mined, it is assigned a block number and is considered blockchain canon.

Account-based vs. utxo-based blockchains

In utxo-based blockchains like Bitcoin, transactions consist of one or multiple “outputs” and “inputs”. Outputs define the assets to be sent and their recipients. Inputs contain references to outputs of other transactions in which the transaction creator was added as a recipient. When a transaction is mined by the blockchain the transaction outputs are considered “spent”.

Thus the total balance and the spendable “coin base” of a utxo-based account consists of a multitude of outputs from different transactions that are not yet spent (“Unspent Transaction Output”). Thus it is important to ensure that any outputs that are part of a wallet’s total balance are included in one or multiple blocks and thus considered valid before employing them in a new wallet transaction. Otherwise, the wallet transaction might be discarded due to an invalidation of the parent transaction output during the mining of the newest block. This would result in a transaction assents not reaching the recipient.

Account-based blockchains like Ethereum employ a global balance state that is not dependant on previous transactions comparable to a classical bank account.

Supported Blockchains

Ethereum

Status: supported

Ethereum is one of the most used blockchains when it comes to programmable decentralized applications. To learn more about Ethereum please refer to the official website.

Ethereum ERC20 Tokens

Status: supported

Ethereum is a programmable, account-based blockchain which comes with the support of the creation of smart contracts. WaaS can execute the standard ERC20 methods approve and transferFrom with any ERC20-compatible token. Extended methods burn and mint are not part of the official ERC20 spec and thus are only supported with compatible smart contracts.

WaaS does not support the creation of new tokens or smart contracts. This is a service which can be covered by the Tangany consulting team.

A list of well-known ERC20 tokens can be found here. Please refer to the linked resource to analyze the technical and economic details of a specific existing token.

Please keep in mind that Ethereum tokens will need Ether when sent within a transaction.

Bitcoin

Status: supported

Bitcoin was the first cryptocurrency and blockchain, which has been introduced in 2009. Bitcoin is a utxo-based blockchain and thus requires special measures for determining wallet balances and identifying spendable tokens for a transaction.