Custody Providers

Internet Computer Integration for Custody Providers

This document is aimed at product owners and architects at custody providers who’d like to get an overview of the integration tasks ahead, before diving deeper into implementation details.

Introduction to ICP and what You need to know about the Blockchain

First, the Introduction to ICP.

Second, it's worth repeating that a node in the terminology of the IC refers to a computer executing canisters (i.e. the smart contract / WASM runtime). Custody providers do not interact with these nodes. Instead, they integrate with Rosetta (see below) or so-called boundary nodes. API boundary nodes provide a public endpoint for the IC and route all incoming requests to the right subnet, load-balance requests across replica nodes, and cache responses for improved performance.

Cryptography

Parties that send requests to the Internet Computer authenticate themselves via a digital signature on a 32-byte digest of the request. Currently supported signatures are vanilla Ed25519 and ECDSA (over secp256r1 and secp256k1) digital signature schemes. Either one can be used. In addition, authentication can also use WebAuth signatures (either ECDSA on secp256r1 or RSA PKCS#1v1.5, both using SHA-256.)

Custodians also need to support verification of BLS signatures to authenticate on-chain information such as balances, transactions. They are verifiable with the global master public key (chain key cryptography).

Balances and Transactions

Balance and transaction information needs to be polled from Rosetta API or a boundary node.

Integration with Rosetta

DFINTY’s Financial Integration team provides a Rosetta API docker image for custody providers and other infrastructure providers building on the IC. Rosetta is an open standard designed by Coinbase to simplify blockchain deployment and interaction; this allows custody providers to spend less time on integration and more time on novel blockchain advancements.

Native Integration

If using the Rosetta API is not feasible for whatever reason, then custody providers interact with the network directly through a boundary node.

To integrate tokens on the ICP blockchain (including the native ICP token) providers need to interact with the smart contracts that maintain the tokens. This requires familiarity with:

• Candid, the language used to specify the interfaces of smart contracts running on the IC

• API and execution model of the IC
  • requests are submitted, and replies need to be polled
  • different types of requests yield different levels of trust in the response
• API of the ICP Ledger (in particular how to fetch and verify the transaction chain)
• API of the Governance smart contract (for implementing staking and staking related operations)

Staking

ICP staking is kind of like delegated PoS, but also different in key areas. Staking assets participate in on-chain governance instead of transaction validation, and this governance runs in NNS, i.e. does not require a stand-alone validator infrastructure.

The main custody-related workflows are: 1. stake neuron (-> start staking), 2. follow another neuron (-> delegation), 3. spawn a neuron (-> claim rewards), 4. dissolve a neuron (-> stop staking), 5. disburse a neuron (-> move claimed rewards or dissolved staking assets back to a normal address). Additionally, the actual voting process could be implemented.

Main facts of relevance for custody integration:

• Staking rewards are earned through ICP lock-up (6m-8y) and participation in on-chain governance (~10 votes/day), not through validation of blocks.
• There is no separate validator infrastructure, things happen on-chain.
• Every staking entry creates a so-called Neuron. A private key (and principal ID) can have many neurons.
• Staking properties (timing, unlock, rewards, voting) are managed at the Neuron level
• Most Neuron metadata incl. amounts, staking timelines, etc. are not public on-chain, instead need to be queried using signed transactions
• Voting can be delegated to other staking participants, it is called to “follow a neuron”. This is the recommended setup, as we don’t expect custodians to vote 10 times daily (average # daily votes in 2023)…
• Leaving staking starts with “dissolving” a neuron, at which time the unlock timer starts (e.g. 8 years) and the rewards are reduced
• Getting maximum rewards requires (i) maximum lock-up (8y), (ii) that the neuron is not in dissolving state, and (iii) that all votes are voted on (yes or no - pass does not count)
• Accumulated rewards can be (i) restaked automatically -- this is the default, (ii) automatically participate in the on-chain social fundraising activities (“Neuron’s Fund”) on SNS, or (iii) be liquidated after a 7-day waiting period, which starts with “spawning” of rewards ICP
• Staking does not require a validator infrastructure or any other on-line infrastructure as all the on-line operations are facilitated by the Internet Computer
• Staking support is implemented in the Rosetta container using a documented but unofficial API extension, as the main standard is tailored for D-PoS

ICRC-1 Token Standard

The ICRC-1 token standard was created to facilitate handling of tokens on the IC through a common interface, similar to ERC-20. This standard is a key enabler for DAPPs developed on the IC launch their own token, i.e. tokenize and hand over control over the DAPP to a community of users, hence functioning and being governed as a DAO (“decentralized autonomous organization”). It is expected that, going forward, all tokens will support it.

ICRC-1 tokens may use the SNS for on-chain governance similar to how ICP uses the NNS. We expect to provide a Rosetta API container for SNS and ICRC-1 tokens in about 6 months with 100% API compatibility to the main ICP Rosetta API (pending roadmap confirmation).

SNS and NNS have close but not 100% API compatibility, which needs to be considered when using native integration via boundary nodes.

Integration with the NNS Front-end

Mentioned for completeness sake: the IC operates an on-chain online wallet for rapid on-boarding of end-users with negligible amounts of assets. It is not recommended for institutional use or a significant amount of assets.

Users create an identity on the Internet Identity service, which under the hood creates a private key and distributes it on-chain using threshold secret sharing and chain-key cryptography. Users then use the NNS Front-end to manage their assets, including staking. Access to these websites is protected using Passkeys or a seed phrase.

Support and more detailed documentation

More detailed documentation is available throughout this Wiki. And the Rosetta API documentation is really a great resource for custody related ICP integrations. Even when not using the Rosetta API, its source code can be used as an example of how to interact with boundary nodes.

The Developer Forum is the place to get support at any time, and is also frequently visited by the Dfinity team members who supported Coinbase, Sygnum, Zondax and other custody related ICP-integrations in the past.