Tangany ‘Wallet as a Service’
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.
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 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.
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.
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.
Most blockchain run multiple implementations that manage separate distinguished data states but share the common “play rules” of the blockchain.
mainnet is the official Ethereum network.
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 is the official Bitcoin network.
testnet is also supported and represents the current testnet3 implementation in Bitcoin.
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.
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.
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 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.
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.
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
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
transferFrom with any ERC20-compatible token. Extended methods
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 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.