Guides
SupportStatusSign UpLogin

Use Case and Functionalities

KMS Use Case and Functionalities

Suggest Edits

Basic Transaction Signature Flow

The Tatum platform allows you to sign transactions directly with your PrivateKeys.

Observations

  • Signing transactions with PrivateKeys simplifies User onboarding, lowering the learning curve on how to build a transaction.
  • Signing transactions with PrivateKeys can expose your keys to MITM attacks.
  • Signing transactions with PrivateKeys is intended for Testnet and early testing in Mainnet (only).
  • Signing transactions with PrivateKeys enables Tatum's back-end to return verbose errors with "dashboardLog".
    • This is helpful for the Support team to troubleshoot requests with you. E.g., malformed payload, wrong address format, wrong digits, etc. Additional details are available in the following article.

📘

Tatum does not store PrivateKeys and or Mnemonics. Our logs do not store these parameters, by design.

KMS Transaction Signature Flow

KMS runs locally on your premises providing security for generating wallets, addresses, PrivateKeys, and signing transactions. Your data is encrypted and stored on your side, so you never have to worry about what would happen if your transaction were somehow intercepted.

Observations

  • KMS is a self-hosted custodial solution.
  • Tatum does not have access to any KMS instance, by design.
  • Mnemonics and or PrivateKeys are stored via KMS in the file "Wallet.dat". Keeping this file safe is your responsibility, the User.
  • Signing transactions with KMS largely prevents Tatum from troubleshooting failed transactions. Here's why:
    1. A transaction sent to KMS for signature and broadcast to the blockchain may be malformed, yet get a "successful" response from core-API or the SDK. Tatum does not store Payload logs, by design, from "successful" requests.
    2. KMS will sign the transaction and broadcast it to the blockchain.
    3. If the blockchain rejects the transaction, you will get an error back to your KMS coming from the blockchain.

      🚧

      You, the User, will have to keep track of the original request log, including the payload, if you expect Tatum to help you troubleshoot potential reasons for your transaction(s) to fail.

📘

By using KMS, it is assumed that you, the User, hold extensive blockchain knowledge and are an experienced developer.

KMS Transaction Signature Flow & Four Eyes Principle

To verify whether the transaction to sign with KMS is yours, enable the Four-eye principle. This ensures that pending transactions are controlled in Tatum and the User side.

Observations

  • All above from KMS
  • The four-eye principle is mandatory on Mainnet. Find how to enable the four-eye principle in the following article.
  • When the four-eye principle is enabled, you allow only the transactions from your application server to be signed: every time a transaction from Tatum is fetched to be signed, it is validated against the external server using a simple HTTP GET operation
    • your_external_url/transaction_id
    • If the response is 2xx, the transaction is signed. Otherwise, the transaction is skipped and it won't be signed. You, the User, should take the appropriate steps on your end to investigate the situation.

How does KMS Work?

KMS runs on your premise (local or cloud) for generating wallets, addresses, PrivateKeys, and signing transactions securely. KMS stores all your mnemonics and private keys in a wallet storage file "wallet.dat". This storage file is an AEC encrypted file, for which only you know the encryption key.

Every wallet stored inside your KMS instance has a unique identifier, called signatureId. This signatureId is used in communication with Tatum API and represents the wallet used by the specific operation. When you generate and store all the wallets you want to work with, you then enable the daemon mode in the KMS. This daemon mode periodically checks for pending transactions to sign.

Summary:

  • When you generate a wallet with KMS, it creates a signature ID that is used in place of the wallet’s mnemonic.
  • When you generate a private key to an address, it creates a signature ID to be used in place of the private key.
  • When you send API requests to Tatum you only have to remember to replace two fields:
    • mnemonic -> signatureId (of the wallet’s mnemonic phrase) - It's best to keep track of the "index"
    • fromPrivateKey -> signatureId (of the private key)

KMS Operation Modes

KMS provides two modes of operation

  • CLI mode: used to generate wallets or private keys, typically for the initial setup and one-time operations.
  • Daemon mode: periodically pulls pending transactions from the Tatum API, signs transactions locally, and broadcasts the transactions to the blockchain.

KMS works with three types of signature IDs

  • Private key-based signature IDs
    When a private key is required to sign an operation, you must replace privateKey with signatureId matching the signature ID of the mnemonic.
  • mnemonic-based signature IDs (intended for Virtual Accounts)
    When a mnemonic is required to sign an operation, you must replace the mnemonic with the signatureId matching the signature ID of the mnemonic.
  • mnemonic && index based signature IDs
    When a mnemonic && index are required to sign an operation, you must replace the mnemonic with the signatureId matching the signature ID of the mnemonic as well its index.

PrivateKey and Mnemonic caveats - storage limits

  • Mnemonic-based: You could assign one (1) signatureId per mnemonic. To support this setup, we'd suggest building a database to store your customers' data, including but not limited to their associated IDs, KMS signature IDs, and the related index matching with their address/PrivateKey within the mnemonic in KMS.
    With a limit of 25.000 mnemonics per API Key in KMS, where each mnemonic can contain up to 2^32 addresses, you could safely store and sign operations for 25K x 2^32 distinctive addresses/customers.
  • Private Key-based: You could assign one (1) signatureId per each individual PrivateKey. With a limit of 25.000 Private Keys per API Key in KMS, you could safely store and sign operations for 25K distinctive addresses/customers.

📘

Each API key assigned to KMS supports up to 25.000 signatureId. You can reuse a seed/mnemonic for different chains. However, each chain requires a distinctive signatureId.

KMS Basic Functions

Updated 5 months ago