Difference between revisions of "Custody Providers"

Latest revision as of 13:26, 2 May 2024

This document is aimed at product owners and architects at custody providers and analytics/reporting firms (“Integrators”) who’d like to get an overview of the integration architecture required for supporting the ICP token and ICP network tokens following the ICRC standards (“ICRC tokens”).

Introduction to Internet Computer (ICP) Integrations

First, the canonical Introduction to ICP. BTW, we use “ICP” interchangeably for the protocol, the network and the token!

The TL;DR from ICP’s 3rd generation approach are:

You don’t run a node to validate transactions block by block. Instead, you get the block(s) in question using https APIs and verify them using ICP’s 48 byte BLS master public key.
BLS is only needed for chain validation, i.e. in online systems. Transaction signing requires ECDSA or Ed25519, at least one of which is available in every crypto HSM and MPC library.
You don’t need an off-chain RPC node: ICP and ICRC token ledgers are ICP canisters (ICP’s name for smart contracts) and have https APIs as primary interface to read balance and transaction data and submit new transactions for broadcasting.

Additionally, Dfinity offers an open source implementation of Coinbase’s Rosetta API as a Docker container. It provides a simple interface to query ICP and ICRC token balances & transactions, as well as prepare and broadcast custody & staking transactions.

Cryptography

Transaction signing: ECDSA or Ed25519

Integrators that send requests to the Internet Computer authenticate the request 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).

Transaction verification: BLS

Integrators 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).

Rosetta takes care of this internally, i.e. integration with Rosetta does not require any BLS support.

Creating and Broadcasting Transactions

Valid transaction requests need to be signed and sent to the corresponding token ledger using the token ledger’s https API. There are libraries for Rust, C, Go, TypeScript, etc.

Rosetta API takes care of both transaction request creation and broadcasting.

Querying Balances and Transactions

Token ledgers on ICP create a new block for every transaction, the current practical limit of transactions per second per ledger is 400-600 tps.

Good to know for analytics & reporting use cases: ICP & ICRC Rosetta containers include a sqlite instance that stores all the relevant information for direct querying. Though, to be clear, that’s not a formally supported interface under the Rosetta standard.

Integration with Rosetta

DFINTY provides a Rosetta API docker image for integrators building on ICP. Rosetta is an open standard designed by Coinbase to simplify blockchain deployment and interaction; this allows integrators to spend less time on integration and more time on novel blockchain advancements.

Rosetta supports all the following use cases:

Querying verified balances & transactions for ICP and ICRC tokens
Creating transaction requests for ICP and ICRC token transfers
Creating transaction requests for all steps of the ICP staking / voting workflow
Broadcasting signed requests

Each token ledger requires its own Rosetta container for local data storage, i.e. integrators will deploy the ICP Rosetta container for ICP token support, and deploy the ICRC Rosetta container multiple times for supporting multiple ICRC tokens.

Compute, memory and storage requirements are minimal, as the heavy lifting computing happens on ICP, and Rosetta acts more like a light node. As of Q2 2024, the biggest container size is the ICP Rosetta container with about 10 GiB space required for the complete 3+ year history.

Native Integration

If using the Rosetta API is not feasible for whatever reason, then integrators interact with ICP or ICRC ledgers directly using their https API.

This requires familiarity with:

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

API and execution model of ICP
- 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)
The ICRC-1 and ICRC-3 standards to support ICRC tokens

There are libraries available from Dfinity for JavaScript/TypeScript (agent-js) and Rust (agent-rs) as well as third-party libraries for other languages incl. Java, C, C++ and Go.

Staking

ICP staking is similar to delegated PoS, but with some key differences:

ICP staking rewards active voting instead of the typical block creation & validation activity. The factors influencing voting rewards are: staked amount, dissolve delay, age bonus, voting activity (the bigger the better)
It doesn’t require a validator infrastructure because the voting process runs as a smart contract on ICP.
Staking sends assets from a custody address to an address type called “neuron”, managed by the Network Nervous System dapp, NNS. The neuron continuous to be controlled by the same private key as the sending custody address (similar to ETH staking)
Instead of actively voting on all proposals, a staker can delegate their vote to someone else’s neuron, this is called “following a neuron”
The unlocking period (called “dissolve delay”) can be up to 8 years for maximum rewards. Note that during the last 6 months of the unlocking period, no more rewards will be paid out, meaning that the minimum viable dissolve delay is 6 months..

See the chart below for an overview of the main custody-related workflows

ICRC Token Standards

The ICRC-1 and ICRC-3 token standards were created to facilitate handling of tokens on ICP through a common interface, similar to ERC-20 on Ethereum. It is expected that, going forward, all tokens will support them.

ICP and ICRC tokens have close but not 100% API compatibility, which needs to be considered when using native integration. Another gotcha to consider when going from ICP to ICRC is that the ICP ledger uses a hashed representation of the principal, subaccount pair, while interactions with ICRC ledgers require and use the principal, subaccount pair in plaintext. (Although, to confuse things further, Dfinity’s dashboard block explorer uses the hashed representation also for ICRC token addresses).

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 go on about a native integration.

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, Copper, Taurus and other custody related ICP-integrations in the past.

@@ Line 1: / Line 1: @@
-=== Internet Computer Integration for Custody Providers ===
+This document is aimed at product owners and architects at custody providers and analytics/reporting firms (“Integrators”) who’d like to get an overview of the integration architecture required for supporting the ICP token and ICP network tokens following the ICRC standards (“ICRC tokens”).
-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 ===
+=== Introduction to Internet Computer (ICP) Integrations ===
-First, the [[Introduction to ICP]].
+First, the canonical [[Introduction to ICP]]. BTW, we use “ICP” interchangeably for the protocol, the network and the token!
-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|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.
+The TL;DR from ICP’s 3rd generation approach are:
+# You don’t run a node to validate transactions block by block. Instead, you get the block(s) in question using https APIs and verify them using ICP’s 48 byte BLS master public key.
+# BLS is only needed for chain validation, i.e. in online systems. Transaction signing requires ECDSA or Ed25519, at least one of which is available in every crypto HSM and MPC library.
+# You don’t need an off-chain RPC node: ICP and ICRC token ledgers are ICP canisters (ICP’s name for smart contracts) and have https APIs as primary interface to read balance and transaction data and submit new transactions for broadcasting.
+Additionally, Dfinity offers an open source implementation of Coinbase’s Rosetta API as a Docker container. It provides a simple interface to query ICP and ICRC token balances & transactions, as well as prepare and broadcast custody & staking transactions.
 === 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]]).
+==== Transaction signing: ECDSA or Ed25519 ====
+Integrators that send requests to the Internet Computer authenticate the request 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).
+==== Transaction verification: BLS ====
+Integrators 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]]).
+Rosetta takes care of this internally, i.e. integration with Rosetta does not require any BLS support.
+=== Creating and Broadcasting Transactions ===
+Valid transaction requests need to be signed and sent to the corresponding token ledger using the token ledger’s https API. There are libraries for Rust, C, Go, TypeScript, etc.
+Rosetta API takes care of both transaction request creation and broadcasting.
+=== Querying Balances and Transactions ===
+Token ledgers on ICP create a new block for every transaction, the current practical limit of transactions per second per ledger is 400-600 tps.
-=== Balances and Transactions ===
+Good to know for analytics & reporting use cases: ICP & ICRC Rosetta containers include a sqlite instance that stores all the relevant information for direct querying. Though, to be clear, that’s not a formally supported interface under the Rosetta standard.
-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 [https://internetcomputer.org/docs/current/developer-docs/integrations/rosetta/ Rosetta API docker image] for custody providers and other infrastructure providers building on the IC. [https://www.rosetta-api.org/ 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.
+DFINTY provides a [https://internetcomputer.org/docs/current/developer-docs/integrations/rosetta/ Rosetta API docker] image for integrators building on ICP. [https://docs.cloud.coinbase.com/rosetta/docs/welcome Rosetta is an open standard designed by Coinbase] to simplify blockchain deployment and interaction; this allows integrators to spend less time on integration and more time on novel blockchain advancements.
+Rosetta supports all the following use cases:
+* Querying verified balances & transactions for ICP and ICRC tokens
+* Creating transaction requests for ICP and ICRC token transfers
+* Creating transaction requests for all steps of the ICP staking / voting workflow
+* Broadcasting signed requests
+Each token ledger requires its own Rosetta container for local data storage, i.e. integrators will deploy the ICP Rosetta container for ICP token support, and deploy the ICRC Rosetta container multiple times for supporting multiple ICRC tokens.
+Compute, memory and storage requirements are minimal, as the heavy lifting computing happens on ICP, and Rosetta acts more like a light node. As of Q2 2024, the biggest container size is the ICP Rosetta container with about 10 GiB space required for the complete 3+ year history.
 === Native Integration ===
-If using the Rosetta API is not feasible for whatever reason, then custody providers interact with the network directly through a [[Boundary Nodes|boundary node]].
+If using the Rosetta API is not feasible for whatever reason, then integrators interact with ICP or ICRC ledgers directly using their https API.
-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:
+This requires familiarity with:
-* Candid, the language used to specify the interfaces of smart contracts running on the IC
+* Candid, the language used to specify the interfaces of smart contracts running on ICP
-* API and execution model of the IC
+* API and execution model of ICP
 ** 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 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)
+* The ICRC-1 and ICRC-3 standards to support ICRC tokens
+There are libraries available from Dfinity for JavaScript/TypeScript ([https://github.com/dfinity/agent-js agent-js]) and Rust ([https://docs.rs/ic-agent/latest/ic_agent/ agent-rs]) as well as third-party libraries for other languages incl. Java, C, C++ and Go.
 === Staking ===
-ICP [[Staking, voting and rewards|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.
+ICP [[Staking, voting and rewards|staking]] is similar to delegated PoS, but with some key differences:
-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 [https://internetcomputer.org/docs/current/developer-docs/integrations/icrc-1/ 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).
+* ICP staking rewards active voting instead of the typical block creation & validation activity. The factors influencing voting rewards are: staked amount, dissolve delay, age bonus, voting activity (the bigger the better)
+* It doesn’t require a validator infrastructure because the voting process runs as a smart contract on ICP.
+* Staking sends assets from a custody address to an address type called “neuron”, managed by the Network Nervous System dapp, NNS. The neuron continuous to be controlled by the same private key as the sending custody address (similar to ETH staking)
+* Instead of actively voting on all proposals, a staker can delegate their vote to someone else’s neuron, this is called “following a neuron”
+* The unlocking period (called “dissolve delay”) can be up to 8 years for maximum rewards. Note that during the last 6 months of the unlocking period, no more rewards will be paid out, meaning that the minimum viable dissolve delay is 6 months..
-SNS and NNS have close but not 100% API compatibility, which needs to be considered when using native integration via boundary nodes.
+See the chart below for an overview of the main custody-related workflows[[File:ICP staking flow chart.png|alt=ICP staking flow chart|frameless|927x927px]]
-=== Integration with the NNS Front-end ===
+=== ICRC Token Standards ===
-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.
+The [https://internetcomputer.org/docs/current/developer-docs/integrations/icrc-1/ ICRC-1] and ICRC-3 token standards were created to facilitate handling of tokens on ICP through a common interface, similar to ERC-20 on Ethereum. It is expected that, going forward, all tokens will support them.
-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.
+ICP and ICRC tokens have close but not 100% API compatibility, which needs to be considered when using native integration. Another gotcha to consider when going from ICP to ICRC is that the ICP ledger uses a hashed representation of the principal, subaccount pair, while interactions with ICRC ledgers require and use the principal, subaccount pair in plaintext. (Although, to confuse things further, Dfinity’s [https://dashboard.internetcomputer.org/ dashboard block explorer] uses the hashed representation also for ICRC token addresses).
 === Support and more detailed documentation ===
-More detailed documentation is available throughout this Wiki. And the [https://internetcomputer.org/docs/current/developer-docs/integrations/rosetta/ 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.
+More detailed documentation is available throughout this Wiki. And the [https://internetcomputer.org/docs/current/developer-docs/integrations/rosetta/ 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 go on about a native integration.
-The [https://forum.dfinity.org/ 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.
+The [https://forum.dfinity.org/ 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, Copper, Taurus and other custody related ICP-integrations in the past.