Managing private keys can be difficult and exposes users to various risks, such as sending assets to the wrong recipient or having their private keys compromised by malicious fishing campaigns. One solution to this problem is to provide users with tools for protecting their digital assets. This is the role of the Custody Module, which adds an extra layer of protection by providing users with three additional safeguards. This helps to ensure that users are better able to secure their funds and reduce the risks associated with managing private keys.

Each user is responsible of its own custody account parameters and does not depend on specific governance permissions. However, the module has two network properties, max_custody_tx_size and max_custody_buffer_size, which require a specific governance process to be modified (cf. Network Properties).

The first layer is collaborative custody, which allows users to set up specific transaction signature schemes. This means that transactions can only be sent if one or more configurable other addresses (third parties) give their approval. The collaborative custody differs from traditional m-of-n multi-signatures in that it maintains the concept of ownership. This means that third parties cannot sign transactions without the original address owning the assets also signing the transaction. Simply put, collaborative custody can be thought of as a 2-factor authentication that can be set up to N-factor authentication, where N is the number of extra KIRA addresses needed to sign transactions.

The second layer of protection offered by the Custody Module is a mechanism that allows token transfers to occur only when the recipient of funds submits a secret provided off-chain by the sender. If the funds are not claimed within a predefined period of time, they are returned to the sender's account. This mechanism, when combined with collaborative custody, ensures that both the sender and the recipient can be verified in more than one way effectively adding an extra layer of security to the process of transferring digital assets.

The third layer of account protection enable users to manage a withdraw whitelist & set up custom time period transfer limits for every tokens (day, week, month…), i.e. the user’s account cannot transfer tokens unless the recipient address figures in the user’s whitelist and the withdraw amount for the given token doesn’t exceeds the current current withdrawal capacity. The whitelisting & limits setup processes can be protected by secrets, effectively preventing malicious actors getting around this protection in the case where the user’s private key is compromised. Additionally withdrawal limits have a 24-hour waiting period to prevent an attacker to immediately change limits and withdraw all funds at once in the event user’s secrets have also been compromised.

When a user’s custody_enabled is enabled, all token transfers must be performed using the custody send CLI. Attempts to use the bank send CLI will be automatically rejected. Transactions are placed in an on-chain buffer awaiting approval by the quorum of custodian addresses defined by the user via the custody_mode property. The buffer has limited size defined by the max_custody_buffer_size network property (default 10) and the transaction/stored data size by max_custody_tx_size (default 8192 characters). It is important that each transaction includes adequate fees to motivate custodians to cast their approval. The fees should be at least double the cost of approving or denying the transaction, which will effectively cover the refund of transaction fees. If a custodian does not cast a judgement, they do not receive any rewards and any remaining rewards will be returned to the user. Transactions without sufficient fees included will be automatically rejected.

All transactions of the custody module can only be propagated by providing a key defined by the user or the frontend. However a key becomes exposed and thereby obsolete as soon as it used to submit a transaction. Therefore, to circumvent this security weakness, keys can only be used once and each transaction (except the first one) require providing the previously defined key hashed once SHA256(secret) as well as setting up the new key SHA256(SHA256(secret)) for the subsequent transaction.