KMS - How it works

TABLE OF CONTENTS

• Introduction
• Use Cases
• Good to know

Introduction

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:

1. 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.
2. 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.
3. 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. 

Use Cases

1. 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.
2. 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.

Good to know

• Tatum KMS supports integrations with Azure Key Vault or VGS. For more information, see Tatum KMS GitHub pages.
• After you generate and store the wallets you want to work with, enable daemon mode. Daemon mode periodically checks for pending transactions to sign.
• Every pending transaction has a signatureId. When a pending transaction matches a stored wallet, it is signed locally and sent to the blockchain. Your wallet data are stored only in memory.
• Each signatureId represents one (1) wallet, be mnemonic or Private Key based. 
• 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.

By default, KMS checks for the pending transactions every 5 seconds using this API call.