From 4d77e3195cb5858250a6b5c7a1a1955bfe425823 Mon Sep 17 00:00:00 2001 From: Marco Walz Date: Wed, 6 May 2026 15:40:07 +0200 Subject: [PATCH 1/6] =?UTF-8?q?infra:=20Learn=20Hub=20migration=20prep=20?= =?UTF-8?q?=E2=80=94=20staging=20files,=20navigation=20map,=20agent=20inst?= =?UTF-8?q?ructions?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fetch all 86 Learn Hub articles via Zendesk API into .migration/learn-hub/ (57 in-scope under how-does-icp-work/, 29 out-of-scope; each with learn_hub_* frontmatter and migrated: false) - Add .docs-plan/learn-hub-navigation.md: article-to-target mapping for all 9 content batches with action types (new/expand/reference/skip) and per-batch cross-link replacement tables - Add .docs-plan/learn-hub-migration.md: 9-step agent workflow covering skill loading, staging file reading, per-action templates, sidebar config (no changes needed), verification step for protocol content, intra-batch linking rules, skip article policy, and final cleanup PR checklist with human review gate - Update .docs-plan/decisions.md with migration structural decisions - Update .docs-plan/migration-plan.md with 9 batch entries - Remove Learn Hub from AGENTS.md duplicate-content rule and link rule - Remove Learn Hub LinkCard from docs/index.mdx --- .docs-plan/decisions.md | 28 ++ .docs-plan/learn-hub-migration.md | 316 +++++++++++++++ .docs-plan/learn-hub-navigation.md | 234 +++++++++++ .docs-plan/migration-plan.md | 20 + .migration/learn-hub/README.md | 109 +++++ .../blockchain-protocol.md | 34 ++ .../blockchain-protocol/consensus.md | 69 ++++ .../blockchain-protocol/execution-layer.md | 75 ++++ .../blockchain-protocol/message-routing.md | 85 ++++ .../blockchain-protocol/peer-to-peer.md | 35 ++ .../state-synchronization.md | 35 ++ .../canister-control.md | 19 + .../canister-smart-contracts.md | 28 ++ .../computational-model.md | 15 + .../canister-smart-contracts/cycles-ledger.md | 252 ++++++++++++ .../canister-smart-contracts/cycles.md | 22 ++ .../what-is-a-principal.md | 23 ++ .../chain-fusion/bitcoin-checker-canister.md | 52 +++ .../chain-fusion/bitcoin-integration.md | 42 ++ .../chain-fusion/chain-fusion.md | 30 ++ .../chain-fusion/chain-key-bitcoin.md | 371 ++++++++++++++++++ .../chain-fusion/chain-key-tokens.md | 69 ++++ .../chain-fusion/dogecoin-integration.md | 19 + .../chain-fusion/ethereum-integration.md | 33 ++ .../chain-fusion/evm-rpc-canister.md | 31 ++ .../chain-fusion/exchange-rate-canister.md | 81 ++++ .../chain-fusion/sol-rpc-canister.md | 27 ++ .../certified-communication.md | 19 + .../chain-key-cryptography.md | 33 ++ .../chain-key-signatures.md | 25 ++ .../subnet-keys-and-subnet-signatures.md | 32 ++ .../evolution-scaling/chain-evolution.md | 59 +++ .../evolution-scaling/evolution-scaling.md | 18 + .../evolution-scaling/fault-tolerance.md | 57 +++ .../evolution-scaling/subnet-creation.md | 31 ++ .../asset-certification.md | 27 ++ .../http-gateway-protocol.md | 47 +++ .../icp-and-the-internet/https-outcalls.md | 46 +++ .../icp-and-the-internet.md | 25 ++ .../icp-edge-infrastructure.md | 58 +++ .../introduction/how-does-icp-work.md | 40 ++ .../nns/neuron-attributes.md | 39 ++ .../how-does-icp-work/nns/neurons-fund-nf.md | 166 ++++++++ .../how-does-icp-work/nns/neurons.md | 238 +++++++++++ .../how-does-icp-work/nns/overview.md | 50 +++ .../nns/proposal-topics-and-types.md | 219 +++++++++++ .../how-does-icp-work/nns/proposals.md | 109 +++++ .../how-does-icp-work/nns/voting-rewards.md | 103 +++++ .../node-infrastructure/overview.md | 56 +++ .../trusted-execution-environments.md | 315 +++++++++++++++ .../how-does-icp-work/sns/dao-settings.md | 127 ++++++ .../sns/framework-and-architecture.md | 80 ++++ ...o-inspect-an-sns-and-its-dapp-canisters.md | 180 +++++++++ .../learn-hub/how-does-icp-work/sns/launch.md | 62 +++ .../how-does-icp-work/sns/neurons.md | 110 ++++++ .../how-does-icp-work/sns/proposals.md | 145 +++++++ .../how-does-icp-work/sns/rewards.md | 102 +++++ .../sns/sns-service-nervous-system.md | 71 ++++ .../how-does-icp-work/sns/tokenomics.md | 129 ++++++ ...n-ledgers-work-on-the-internet-computer.md | 126 ++++++ .../tokens-governance/tokenomics.md | 81 ++++ .../tokens-governance/tokens-governance.md | 21 + .../governance/community-built-dashboards.md | 12 + .../how-can-i-add-an-icp-sub-account.md | 42 ++ .../how-can-i-configure-a-neuron.md | 42 ++ .../governance/how-can-i-disburse-a-neuron.md | 29 ++ .../governance/how-can-i-disburse-maturity.md | 73 ++++ .../how-can-i-find-my-icp-token-accounts.md | 31 ++ .../how-can-i-import-icrc-tokens.md | 74 ++++ .../how-can-i-log-into-the-nns-dapp.md | 45 +++ .../how-can-i-receive-icp-tokens.md | 102 +++++ .../governance/how-can-i-send-icp-tokens.md | 42 ++ .../governance/how-can-i-stake-a-neuron.md | 38 ++ ...how-can-i-stake-and-auto-stake-maturity.md | 55 +++ .../governance/how-can-i-top-up-a-neuron.md | 31 ++ .../governance/internet-computer-dashboard.md | 12 + .../network-stats/cycle-burn.md | 12 + .../network-stats/network-topology.md | 12 + .../how-can-i-use-icp/network-stats/tx-s.md | 12 + .../how-can-i-stake-icp-with-quill.md | 116 ++++++ ...-set-up-an-air-gapped-wallet-with-quill.md | 55 +++ .../how-do-i-transfer-tokens-with-quill.md | 64 +++ .../tokens-wallets/icp-custody-options.md | 92 +++++ .../what-is-icp/decentralization.md | 67 ++++ .../what-is-icp/icp-subsystems.md | 42 ++ .../not-all-transactions-are-equal.md | 37 ++ .../what-is-icp/performance-comparison.md | 101 +++++ .../out-of-scope/what-is-icp/performance.md | 105 +++++ .../what-is-icp/what-has-happened-so-far.md | 92 +++++ .../out-of-scope/what-is-icp/what-is-icp.md | 45 +++ .../what-is-the-vision-behind-icp.md | 29 ++ AGENTS.md | 4 +- docs/index.mdx | 1 - 93 files changed, 6711 insertions(+), 3 deletions(-) create mode 100644 .docs-plan/learn-hub-migration.md create mode 100644 .docs-plan/learn-hub-navigation.md create mode 100644 .migration/learn-hub/README.md create mode 100644 .migration/learn-hub/how-does-icp-work/blockchain-protocol/blockchain-protocol.md create mode 100644 .migration/learn-hub/how-does-icp-work/blockchain-protocol/consensus.md create mode 100644 .migration/learn-hub/how-does-icp-work/blockchain-protocol/execution-layer.md create mode 100644 .migration/learn-hub/how-does-icp-work/blockchain-protocol/message-routing.md create mode 100644 .migration/learn-hub/how-does-icp-work/blockchain-protocol/peer-to-peer.md create mode 100644 .migration/learn-hub/how-does-icp-work/blockchain-protocol/state-synchronization.md create mode 100644 .migration/learn-hub/how-does-icp-work/canister-smart-contracts/canister-control.md create mode 100644 .migration/learn-hub/how-does-icp-work/canister-smart-contracts/canister-smart-contracts.md create mode 100644 .migration/learn-hub/how-does-icp-work/canister-smart-contracts/computational-model.md create mode 100644 .migration/learn-hub/how-does-icp-work/canister-smart-contracts/cycles-ledger.md create mode 100644 .migration/learn-hub/how-does-icp-work/canister-smart-contracts/cycles.md create mode 100644 .migration/learn-hub/how-does-icp-work/canister-smart-contracts/what-is-a-principal.md create mode 100644 .migration/learn-hub/how-does-icp-work/chain-fusion/bitcoin-checker-canister.md create mode 100644 .migration/learn-hub/how-does-icp-work/chain-fusion/bitcoin-integration.md create mode 100644 .migration/learn-hub/how-does-icp-work/chain-fusion/chain-fusion.md create mode 100644 .migration/learn-hub/how-does-icp-work/chain-fusion/chain-key-bitcoin.md create mode 100644 .migration/learn-hub/how-does-icp-work/chain-fusion/chain-key-tokens.md create mode 100644 .migration/learn-hub/how-does-icp-work/chain-fusion/dogecoin-integration.md create mode 100644 .migration/learn-hub/how-does-icp-work/chain-fusion/ethereum-integration.md create mode 100644 .migration/learn-hub/how-does-icp-work/chain-fusion/evm-rpc-canister.md create mode 100644 .migration/learn-hub/how-does-icp-work/chain-fusion/exchange-rate-canister.md create mode 100644 .migration/learn-hub/how-does-icp-work/chain-fusion/sol-rpc-canister.md create mode 100644 .migration/learn-hub/how-does-icp-work/chain-key-cryptography/certified-communication.md create mode 100644 .migration/learn-hub/how-does-icp-work/chain-key-cryptography/chain-key-cryptography.md create mode 100644 .migration/learn-hub/how-does-icp-work/chain-key-cryptography/chain-key-signatures.md create mode 100644 .migration/learn-hub/how-does-icp-work/chain-key-cryptography/subnet-keys-and-subnet-signatures.md create mode 100644 .migration/learn-hub/how-does-icp-work/evolution-scaling/chain-evolution.md create mode 100644 .migration/learn-hub/how-does-icp-work/evolution-scaling/evolution-scaling.md create mode 100644 .migration/learn-hub/how-does-icp-work/evolution-scaling/fault-tolerance.md create mode 100644 .migration/learn-hub/how-does-icp-work/evolution-scaling/subnet-creation.md create mode 100644 .migration/learn-hub/how-does-icp-work/icp-and-the-internet/asset-certification.md create mode 100644 .migration/learn-hub/how-does-icp-work/icp-and-the-internet/http-gateway-protocol.md create mode 100644 .migration/learn-hub/how-does-icp-work/icp-and-the-internet/https-outcalls.md create mode 100644 .migration/learn-hub/how-does-icp-work/icp-and-the-internet/icp-and-the-internet.md create mode 100644 .migration/learn-hub/how-does-icp-work/icp-and-the-internet/icp-edge-infrastructure.md create mode 100644 .migration/learn-hub/how-does-icp-work/introduction/how-does-icp-work.md create mode 100644 .migration/learn-hub/how-does-icp-work/nns/neuron-attributes.md create mode 100644 .migration/learn-hub/how-does-icp-work/nns/neurons-fund-nf.md create mode 100644 .migration/learn-hub/how-does-icp-work/nns/neurons.md create mode 100644 .migration/learn-hub/how-does-icp-work/nns/overview.md create mode 100644 .migration/learn-hub/how-does-icp-work/nns/proposal-topics-and-types.md create mode 100644 .migration/learn-hub/how-does-icp-work/nns/proposals.md create mode 100644 .migration/learn-hub/how-does-icp-work/nns/voting-rewards.md create mode 100644 .migration/learn-hub/how-does-icp-work/node-infrastructure/overview.md create mode 100644 .migration/learn-hub/how-does-icp-work/node-infrastructure/trusted-execution-environments.md create mode 100644 .migration/learn-hub/how-does-icp-work/sns/dao-settings.md create mode 100644 .migration/learn-hub/how-does-icp-work/sns/framework-and-architecture.md create mode 100644 .migration/learn-hub/how-does-icp-work/sns/how-to-inspect-an-sns-and-its-dapp-canisters.md create mode 100644 .migration/learn-hub/how-does-icp-work/sns/launch.md create mode 100644 .migration/learn-hub/how-does-icp-work/sns/neurons.md create mode 100644 .migration/learn-hub/how-does-icp-work/sns/proposals.md create mode 100644 .migration/learn-hub/how-does-icp-work/sns/rewards.md create mode 100644 .migration/learn-hub/how-does-icp-work/sns/sns-service-nervous-system.md create mode 100644 .migration/learn-hub/how-does-icp-work/sns/tokenomics.md create mode 100644 .migration/learn-hub/how-does-icp-work/tokens-governance/how-token-ledgers-work-on-the-internet-computer.md create mode 100644 .migration/learn-hub/how-does-icp-work/tokens-governance/tokenomics.md create mode 100644 .migration/learn-hub/how-does-icp-work/tokens-governance/tokens-governance.md create mode 100644 .migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/community-built-dashboards.md create mode 100644 .migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-add-an-icp-sub-account.md create mode 100644 .migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-configure-a-neuron.md create mode 100644 .migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-disburse-a-neuron.md create mode 100644 .migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-disburse-maturity.md create mode 100644 .migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-find-my-icp-token-accounts.md create mode 100644 .migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-import-icrc-tokens.md create mode 100644 .migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-log-into-the-nns-dapp.md create mode 100644 .migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-receive-icp-tokens.md create mode 100644 .migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-send-icp-tokens.md create mode 100644 .migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-stake-a-neuron.md create mode 100644 .migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-stake-and-auto-stake-maturity.md create mode 100644 .migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-top-up-a-neuron.md create mode 100644 .migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/internet-computer-dashboard.md create mode 100644 .migration/learn-hub/out-of-scope/how-can-i-use-icp/network-stats/cycle-burn.md create mode 100644 .migration/learn-hub/out-of-scope/how-can-i-use-icp/network-stats/network-topology.md create mode 100644 .migration/learn-hub/out-of-scope/how-can-i-use-icp/network-stats/tx-s.md create mode 100644 .migration/learn-hub/out-of-scope/how-can-i-use-icp/tokens-wallets/how-can-i-stake-icp-with-quill.md create mode 100644 .migration/learn-hub/out-of-scope/how-can-i-use-icp/tokens-wallets/how-do-i-set-up-an-air-gapped-wallet-with-quill.md create mode 100644 .migration/learn-hub/out-of-scope/how-can-i-use-icp/tokens-wallets/how-do-i-transfer-tokens-with-quill.md create mode 100644 .migration/learn-hub/out-of-scope/how-can-i-use-icp/tokens-wallets/icp-custody-options.md create mode 100644 .migration/learn-hub/out-of-scope/what-is-icp/decentralization.md create mode 100644 .migration/learn-hub/out-of-scope/what-is-icp/icp-subsystems.md create mode 100644 .migration/learn-hub/out-of-scope/what-is-icp/not-all-transactions-are-equal.md create mode 100644 .migration/learn-hub/out-of-scope/what-is-icp/performance-comparison.md create mode 100644 .migration/learn-hub/out-of-scope/what-is-icp/performance.md create mode 100644 .migration/learn-hub/out-of-scope/what-is-icp/what-has-happened-so-far.md create mode 100644 .migration/learn-hub/out-of-scope/what-is-icp/what-is-icp.md create mode 100644 .migration/learn-hub/out-of-scope/what-is-icp/what-is-the-vision-behind-icp.md diff --git a/.docs-plan/decisions.md b/.docs-plan/decisions.md index ccd21c43..2b531621 100644 --- a/.docs-plan/decisions.md +++ b/.docs-plan/decisions.md @@ -4,6 +4,34 @@ Record decisions that constrain future work — things an agent needs to know th --- +## 2026-05-06: Learn Hub migration — structure, staging, and sequencing + +**Context:** `learn.internetcomputer.org` (a Zendesk Help Center with ~86 articles) is being retired. Developer-relevant content must move into this docs site before the site goes down. Issues #187 and #190 document the full gap analysis. About 27 articles are end-user content (NNS dapp UI, wallet flows, network stats, vision/history) and are explicitly out of scope for developer docs. + +**Decision:** + +1. **`concepts/` subdirectory structure.** The flat 14-file layout cannot absorb ~20 additional pages cleanly. Add two subdirectories: + - `docs/concepts/protocol/` — six protocol-layer pages (consensus, P2P, message routing, execution, state sync, overview) + - `docs/concepts/chain-fusion/` — per-chain architecture pages; the existing `concepts/chain-fusion.md` moves to `concepts/chain-fusion/index.md` + - All other new pages stay flat under `docs/concepts/` (node-infrastructure, edge-infrastructure, evolution-scaling, certified-data, principals, tokenomics, token-ledgers, sns-framework) + +2. **Source staging.** All Learn Hub articles are committed as raw Markdown into `.migration/learn-hub/`, preserving the original category/section folder structure, before any content PRs are opened. Each batch PR reads from the staging files, writes proper docs pages, and deletes the staging files in the same commit. When `.migration/learn-hub/` is empty, the directory is removed and the migration is done. Each migrated page uses `` — no ongoing sync relationship. PR sync recommendation: `hand-written`. + +3. **End-user articles are out of scope.** All articles under "What is ICP?" (marketing/vision), "How can I use ICP? / Governance" (NNS dapp UI flows), "How can I use ICP? / Tokens & wallets" (quill/wallet how-tos), and "How can I use ICP? / Network stats" are not migrated into developer docs. Their disposition (NNS dapp help, IC dashboard help, marketing site) is handled outside this repo. + +4. **Batched PRs.** One `infra/learn-hub-migration-prep` PR does structural setup (staging files, decisions, navigation map, sidebar config, CLAUDE.md rule updates). Then 9 content PRs (`docs/`) migrate topic batches. See `.docs-plan/learn-hub-navigation.md` for the full batch-to-file mapping. + +5. **CLAUDE.md rule retirement.** Two rules reference Learn Hub and must be updated once all batch PRs are merged: + - The "never duplicate Learn Hub" line in the "Never" section must drop the Learn Hub reference. + - The "link to Learn Hub or explain inline" line in the "Never link to old docs" decision (2026-03-13 below) must be replaced with an instruction to link internally. + After the final batch PR merges, open a follow-up `infra/` PR to make these two edits. + +**Rationale:** Staging files in `.migration/learn-hub/` give every agent a stable, repo-local source to read before writing — consistent with the `.sources/` discipline for all other upstream content. Deleting staging files in the same PR as the content write makes progress unambiguous and prevents the staging directory from drifting out of sync. Subdirectories in `concepts/` are needed for the sidebar to remain navigable; two subdirs (not five) keeps the nesting shallow. + +**When to revisit:** Once `.migration/learn-hub/` is deleted in the final content PR, update this entry to "fully reflected in codebase" and remove it. + +--- + ## 2026-04-27: CLI and language tabs are always separate **Context:** Some pages were mixing CLI commands into the same `` group as Motoko and Rust code. Other pages (e.g. `cycles-management.mdx`, `lifecycle.mdx`) kept CLI as standalone blocks with language tabs appearing separately. The mixed approach creates an awkward tab for users who just want a quick CLI command. diff --git a/.docs-plan/learn-hub-migration.md b/.docs-plan/learn-hub-migration.md new file mode 100644 index 00000000..e58f8e11 --- /dev/null +++ b/.docs-plan/learn-hub-migration.md @@ -0,0 +1,316 @@ +# Learn Hub Migration: Agent Instructions + +`learn.internetcomputer.org` is being retired. This file tells you exactly how to execute one batch PR. Read it completely before touching any file. + +Related files: +- `.docs-plan/learn-hub-navigation.md` — article-to-target mapping for all 9 batches +- `.docs-plan/migration-plan.md` — batch table with branch names and effort estimates +- `.docs-plan/decisions.md` — structural decisions (entry dated 2026-05-06) + +--- + +## Step 0 — Skills (required before writing anything) + +```bash +ls .agents/skills/technical-documentation/SKILL.md .agents/skills/icp-brand-voice/SKILL.md +# If broken symlinks: git submodule update --init --depth 1 +``` + +Load these before writing: +- `technical-documentation` +- `icp-brand-voice` +- The relevant icskill for the batch topic (see CLAUDE.md skills table) + +--- + +## Step 1 — Claim your batch + +Find your batch in `.docs-plan/learn-hub-navigation.md`. Each batch has a name (e.g. "Batch 1 — Protocol stack") and a branch name (e.g. `docs/concepts-protocol-stack`). + +```bash +git fetch origin +git ls-remote origin docs/ # if output is empty, branch doesn't exist yet +git checkout -b docs/ origin/main +``` + +--- + +## Step 2 — Read all staging files for the batch + +The `.migration/learn-hub/` directory is the source of truth. Every article is stored at: + +``` +.migration/learn-hub/how-does-icp-work/
/.md +``` + +With frontmatter: +```yaml +--- +learn_hub_id: +learn_hub_url: +learn_hub_title: +learn_hub_section: <section name> +learn_hub_category: "How does ICP work?" +migrated: false +--- +``` + +**Read every staging file listed for your batch before writing a single line of content.** Use the navigation map to find the file paths. Treat staging files exactly as you treat `.sources/` content — do not write from memory or training data. + +**Staging files contain raw HTML-converted Markdown.** Watch for and clean up: +- `&`, ` `, `<br>` — replace or remove +- Three or more consecutive blank lines — collapse to one +- `[undefined]` link text — drop the link, keep the text +- Internal Learn Hub links of the form `[text](https://learn.internetcomputer.org/hc/en-us/articles/<id>-<slug>)` — replace with the internal docs path from the navigation map. If the target doesn't exist yet (later batch), convert to plain prose without a link. + +--- + +## Step 3 — Write the docs pages + +The navigation map specifies one of four actions for each article: + +### Action: `new` — create a new page + +Template for a new concept page: + +```markdown +--- +title: "Page Title" +description: "One-line description for search and cards." +--- + +One paragraph orienting the developer: what this is and why it matters for building on ICP. + +## First major section + +Content here. + +## Second major section + +Content here. + +## Further reading + +- [Related guide](../guides/<relevant-guide>.md) +- [Related concept](../<related-concept>.md) + +<!-- Upstream: informed by Learn Hub article "<title>" (migrated, source retired) --> +``` + +Template for a new reference page: + +```markdown +--- +title: "Page Title" +description: "One-line description." +--- + +Brief intro (one paragraph) explaining what this reference covers and who uses it. + +## <Category A> + +| Parameter | Type | Description | +|---|---|---| +| ... | ... | ... | + +## <Category B> + +... + +<!-- Upstream: informed by Learn Hub article "<title>" (migrated, source retired) --> +``` + +Rules: +- `.md` extension always (never `.mdx` unless interactive `<Tabs>` are needed — concept pages never need tabs) +- `title` and `description` frontmatter are required +- No `sidebar.order` needed unless the page must appear before or after a specific sibling — if needed, use integer values (lower = earlier) +- No CLI commands on concept pages (Diataxis rule: concepts explain *what* and *why*) +- No code examples unless derived from `.sources/` — Learn Hub has no code; do not invent examples +- **Intra-batch cross-links are allowed.** When your batch creates several pages that reference each other (e.g. Batch 1's six protocol pages), link freely between them — they will all exist by the time the PR merges. Use the standard relative-path format with `.md` extension. +- **Verify technical claims for protocol-layer content.** For pages in batches 1, 2, 4, and 6 (protocol stack, node infrastructure, evolution & scaling, cryptography), cross-check factual claims against `.sources/portal` before publishing — Learn Hub prose is not always precise. Specifically: look up the relevant section in `.sources/portal/docs/references/ic-interface-spec.md` for consensus, execution, message routing, and state sync details. For TEE/IC-OS: `.sources/portal` may not cover this — publish what the staging file says and mark uncertain claims with a `<!-- TODO: verify -->` comment for human review. + +### Action: `expand` — add depth to an existing page + +1. Read the existing page first: `Read docs/<target>.md` +2. Identify where the new content fits — add a new `##` section at the end of the main content, before any "Further reading" or "See also" section +3. Do not restructure existing content; only append +4. Add the staging article's title to the existing `<!-- Upstream: -->` comment (create one if missing): + ``` + <!-- Upstream: <existing sources>, informed by Learn Hub article "<title>" (migrated, source retired) --> + ``` + +### Action: `reference` — create a reference page + +Same as `new`, but the file goes in `docs/references/`. Use tables for taxonomies and parameter lists. Avoid prose-heavy sections — reference pages are for lookup, not explanation. Link to the conceptual counterpart (e.g. `references/nns-proposal-types.md` links to `concepts/governance.md`). + +### Action: `skip` — do not migrate + +Three articles in the in-scope staging directory are marked `skip` in the navigation map. The full list is in the "Skip articles" section of `learn-hub-navigation.md`. For each of them: + +- Do **not** create a docs page +- Do **not** delete the staging file — it stays in the repo until the final cleanup PR, where a human reviews it and decides whether to discard or migrate +- The file being present in a staging directory you're reading is not an invitation to migrate it — always check the navigation map row for your article first + +A quick way to identify skips before you start writing: for every staging file in your batch, look up its row in the navigation map. If the "Action" column says `skip`, move on. + +--- + +## Step 4 — Handle sidebar config + +`concepts` uses `autogenerate: { directory: "concepts" }` in `sidebar.mjs`. **You do not need to edit `sidebar.mjs` for any batch PR.** Starlight automatically groups subdirectories as collapsible sections. + +The only exception: if you create `docs/concepts/protocol/` as a new subdirectory (Batch 1), Starlight will generate the group label "Protocol" from the directory name automatically. If the auto-generated label is wrong, add an `_` prefixed `index.md` with a custom title — but in practice the directory names chosen for this migration all produce correct labels. + +Nesting limit: never go deeper than `concepts/<subdir>/<file>.md` (2 levels). That is the maximum — no further nesting. + +--- + +## Step 5 — Update cross-links + +The navigation map lists required cross-link updates for each batch under "Cross-link updates after this batch." Do all of them in the same PR. + +**For each cross-link update:** +1. Read the file being updated: `Read docs/<file>.md` +2. Find the Learn Hub link with: `grep -n "learn.internetcomputer.org" docs/<file>.md` +3. Replace with the internal path +4. Verify the target exists: `ls docs/<new-target>.md` + +After all edits, confirm no Learn Hub links remain in files you touched: +```bash +grep -rn "learn.internetcomputer.org" docs/ --include="*.md" --include="*.mdx" +``` +Hits in files *outside your batch scope* are acceptable — later batches handle those. Hits in files your PR touched are not. + +--- + +## Step 6 — Delete staging files + +In the same commit as the content, delete every staging file your batch consumed. Check the "Action" column in the navigation map: + +- `new` → delete the staging file(s) used to write the new page +- `expand` → delete the staging file(s) merged into the existing page +- `reference` → delete the staging file(s) +- `skip` → **do not delete** (leave for final cleanup PR) + +```bash +git rm .migration/learn-hub/how-does-icp-work/<section>/<slug>.md +# repeat for each staging file in your batch +``` + +If a batch uses multiple staging files to produce one page (e.g. Batch 5 uses three Bitcoin articles to write `concepts/chain-fusion/bitcoin.md`), delete all three. + +--- + +## Step 7 — Build check + +```bash +npm run build +``` + +Must pass with zero errors before pushing. Fix any broken links surfaced by the build. + +--- + +## Step 8 — Commit and push + +Use conventional commits: + +```bash +git add docs/<new-or-modified-files> +git rm .migration/learn-hub/<staged-files> # already staged by git rm above +git commit -m "docs: <short description of batch content>" +``` + +Examples: +- `docs: add protocol stack concept pages (consensus, P2P, message routing, execution, state sync)` +- `docs: add node infrastructure and TEE concept page` +- `docs: expand chain-key-cryptography with subnet keys and certified communication` + +--- + +## Step 9 — Open the PR + +```bash +git push -u origin docs/<slug> +gh pr create --title "docs: <descriptive title>" --body "$(cat <<'EOF' +## Summary +- <bullet: what pages were created or expanded> +- <bullet: what cross-links were updated> + +## Staging files deleted +- `.migration/learn-hub/<path>` → `docs/<target>` + +## Sync recommendation +hand-written + +<!-- Upstream: informed by Learn Hub articles "<titles>" (migrated, source retired) --> +EOF +)" +``` + +--- + +## Checking overall migration progress + +```bash +# How many in-scope staging files remain? +find .migration/learn-hub/how-does-icp-work -name "*.md" | wc -l + +# Any remaining Learn Hub links in the whole docs tree? +grep -rn "learn.internetcomputer.org" docs/ --include="*.md" --include="*.mdx" +``` + +When `find` returns only the three `skip` files (see "Skip articles" in `learn-hub-navigation.md`), **stop and flag for human review** — do not delete them autonomously. Open a PR with just the migrated-article deletions and a comment listing the skip files for a human to decide: + +```bash +gh pr comment <PR#> --body "$(cat <<'EOF' +<!-- skip-files-review --> +All batch migrations are complete. The following staging files were marked `skip` and need a human decision before the final cleanup PR: + +- `.migration/learn-hub/how-does-icp-work/introduction/how-does-icp-work.md` — redundant with concepts/index.md? +- `.migration/learn-hub/how-does-icp-work/icp-and-the-internet/https-outcalls.md` — already covered in concepts/https-outcalls.md? +- `.migration/learn-hub/how-does-icp-work/sns/how-to-inspect-an-sns-and-its-dapp-canisters.md` — user-facing; discard or move elsewhere? + +Please review each and confirm whether to discard, migrate, or redirect. +EOF +)" +``` + +Once a human approves disposal, open the final cleanup PR: +1. Delete `.migration/learn-hub/` entirely (including the reviewed skip files) +2. In CLAUDE.md: remove the "Learn Hub is being retired" note from the `internetcomputer.org/docs/` rule (replace it with just "explain inline or link to `docs/concepts/`") +3. In `.docs-plan/decisions.md`: mark the 2026-05-06 entry as fully reflected, then remove it +4. Run `npm run build` and push + +--- + +## Batch dependency order + +| Batch | Depends on | +|---|---| +| 1 Protocol stack | none | +| 2 Node infrastructure | none | +| 3 Edge infrastructure | none | +| 4 Evolution & scaling | none | +| 5 Chain Fusion deep dives | none (but links to guides already in main) | +| 6 Cryptography deep dives | none | +| 7 Governance deep dives | Batch 8 (governance.md links to tokenomics.md) — do 8 first, or defer the link | +| 8 Tokens & ledgers | none | +| 9 Canister concept fillers | none | + +Batches 1–4 and 5–9 have no mutual dependencies. All can run in parallel except 7 after 8. + +--- + +## Hard rules (never do these) + +- Do not write content from memory — always derive from the staging file +- Do not add NNS dapp UI steps, wallet flows, or end-user instructions +- Do not create `.mdx` unless you need `<Tabs syncKey="lang">` (concept pages never do) +- Do not link to `learn.internetcomputer.org` — every such link is a bug +- Do not edit `sidebar.mjs` — `autogenerate` handles everything +- Do not nest deeper than `concepts/<subdir>/<file>.md` +- Do not use em-dashes in prose (banned in all content) +- Do not reference `dfx` or `mo:base` +- Do not link to a page that does not yet exist +- Do not delete `skip` articles from `.migration/learn-hub/` — they stay for human review in the final cleanup PR diff --git a/.docs-plan/learn-hub-navigation.md b/.docs-plan/learn-hub-navigation.md new file mode 100644 index 00000000..464f79da --- /dev/null +++ b/.docs-plan/learn-hub-navigation.md @@ -0,0 +1,234 @@ +# Learn Hub Migration: Navigation Map + +This file is the authoritative mapping from every Learn Hub article to its target location in the docs site. It drives the batch PR sequencing. + +Source staging: `.migration/learn-hub/<category>/<section>/<slug>.md` +Scope decision: `.docs-plan/decisions.md` — "2026-05-06: Learn Hub migration" + +--- + +## How to read this table + +| Column | Meaning | +|---|---| +| **Learn Hub article** | Original article title and staging path | +| **Target** | Where the content lands in `docs/` | +| **Action** | `new` = create a new file; `expand` = add depth to an existing page; `reference` = goes to `docs/references/` | +| **Batch** | Which content PR handles this (see Batch plan below) | + +--- + +## In-scope articles + +### Batch 1 — Protocol stack (`docs/concepts-protocol-stack`) + +| Learn Hub article | Staging path | Target | Action | +|---|---|---|---| +| How does ICP work? (intro) | `how-does-icp-work/introduction/how-does-icp-work.md` | — | **skip** (redundant with existing `docs/concepts/index.md`; kept for manual review in final cleanup PR) | +| Blockchain Protocol (overview) | `how-does-icp-work/blockchain-protocol/blockchain-protocol.md` | `docs/concepts/protocol/index.md` | new | +| Consensus | `how-does-icp-work/blockchain-protocol/consensus.md` | `docs/concepts/protocol/consensus.md` | new | +| Peer-to-peer | `how-does-icp-work/blockchain-protocol/peer-to-peer.md` | `docs/concepts/protocol/peer-to-peer.md` | new | +| Message Routing | `how-does-icp-work/blockchain-protocol/message-routing.md` | `docs/concepts/protocol/message-routing.md` | new | +| Execution Layer | `how-does-icp-work/blockchain-protocol/execution-layer.md` | `docs/concepts/protocol/execution.md` | new | +| State Synchronization | `how-does-icp-work/blockchain-protocol/state-synchronization.md` | `docs/concepts/protocol/state-synchronization.md` | new | + +Cross-link updates after this batch: +- `docs/concepts/network-overview.md` — replace Learn Hub link with `concepts/protocol/index.md` +- `docs/references/glossary.md` — update entries for consensus, peer-to-peer, message-routing + +--- + +### Batch 2 — Node infrastructure (`docs/concepts-node-infrastructure`) + +| Learn Hub article | Staging path | Target | Action | +|---|---|---|---| +| Node Infrastructure (overview) | `how-does-icp-work/node-infrastructure/overview.md` | `docs/concepts/node-infrastructure.md` | new | +| Trusted Execution Environments | `how-does-icp-work/node-infrastructure/trusted-execution-environments.md` | `docs/concepts/node-infrastructure.md` | new (same file, dedicated section) | + +Cross-link updates after this batch: +- `docs/concepts/https-outcalls.md` — replace Learn Hub TEE link with `concepts/node-infrastructure.md#trusted-execution-environments` + +--- + +### Batch 3 — Edge infrastructure (`docs/concepts-edge-infrastructure`) + +| Learn Hub article | Staging path | Target | Action | +|---|---|---|---| +| ICP and the Internet (overview) | `how-does-icp-work/icp-and-the-internet/icp-and-the-internet.md` | `docs/concepts/edge-infrastructure.md` | new | +| ICP Edge Infrastructure | `how-does-icp-work/icp-and-the-internet/icp-edge-infrastructure.md` | `docs/concepts/edge-infrastructure.md` | new (same file, expand) | +| HTTP Gateway Protocol (conceptual) | `how-does-icp-work/icp-and-the-internet/http-gateway-protocol.md` | `docs/concepts/edge-infrastructure.md` | new (same file, section) | +| Asset Certification | `how-does-icp-work/icp-and-the-internet/asset-certification.md` | `docs/concepts/edge-infrastructure.md` | new (same file, section) | +| HTTPS Outcalls | `how-does-icp-work/icp-and-the-internet/https-outcalls.md` | — | **skip** (already well-covered in `docs/concepts/https-outcalls.md` per issue #187; kept for manual review in final cleanup PR) | + +Cross-link updates after this batch: +- `docs/references/http-gateway-spec.md` — add "See also: [Edge Infrastructure](../concepts/edge-infrastructure.md)" note at top + +--- + +### Batch 4 — Evolution & scaling (`docs/concepts-evolution-scaling`) + +| Learn Hub article | Staging path | Target | Action | +|---|---|---|---| +| Evolution & Scaling (overview) | `how-does-icp-work/evolution-scaling/evolution-scaling.md` | `docs/concepts/evolution-scaling.md` | new | +| Fault Tolerance | `how-does-icp-work/evolution-scaling/fault-tolerance.md` | `docs/concepts/evolution-scaling.md` | new (same file, section) | +| Subnet Creation | `how-does-icp-work/evolution-scaling/subnet-creation.md` | `docs/concepts/evolution-scaling.md` | new (same file, section) | +| Chain Evolution | `how-does-icp-work/evolution-scaling/chain-evolution.md` | `docs/concepts/evolution-scaling.md` | new (same file, section) | + +Cross-link updates after this batch: +- `docs/concepts/chain-key-cryptography.md` — replace Learn Hub chain-evolution link with `concepts/evolution-scaling.md#chain-evolution` +- `docs/references/glossary.md` — update fault tolerance entry + +--- + +### Batch 5 — Chain Fusion deep dives (`docs/concepts-chain-fusion-deep-dives`) + +Move `docs/concepts/chain-fusion.md` → `docs/concepts/chain-fusion/index.md` in this PR. Merge the staging overview into it. + +| Learn Hub article | Staging path | Target | Action | +|---|---|---|---| +| Chain Fusion (overview) | `how-does-icp-work/chain-fusion/chain-fusion.md` | `docs/concepts/chain-fusion/index.md` | expand (merge into existing page being moved here) | +| Bitcoin Integration (architecture) | `how-does-icp-work/chain-fusion/bitcoin-integration.md` | `docs/concepts/chain-fusion/bitcoin.md` | new | +| Bitcoin Checker Canister | `how-does-icp-work/chain-fusion/bitcoin-checker-canister.md` | `docs/concepts/chain-fusion/bitcoin.md` | new (same file, section) | +| Chain-Key Bitcoin (ckBTC mechanics) | `how-does-icp-work/chain-fusion/chain-key-bitcoin.md` | `docs/concepts/chain-fusion/bitcoin.md` | new (same file, section) | +| Ethereum Integration (architecture) | `how-does-icp-work/chain-fusion/ethereum-integration.md` | `docs/concepts/chain-fusion/ethereum.md` | new | +| EVM RPC Canister | `how-does-icp-work/chain-fusion/evm-rpc-canister.md` | `docs/concepts/chain-fusion/ethereum.md` | new (same file, section) | +| SOL RPC Canister | `how-does-icp-work/chain-fusion/sol-rpc-canister.md` | `docs/concepts/chain-fusion/solana.md` | new | +| Dogecoin Integration | `how-does-icp-work/chain-fusion/dogecoin-integration.md` | `docs/concepts/chain-fusion/dogecoin.md` | new | +| Exchange Rate Canister | `how-does-icp-work/chain-fusion/exchange-rate-canister.md` | `docs/concepts/chain-fusion/exchange-rate-canister.md` | new | +| Chain-Key Tokens (mechanics) | `how-does-icp-work/chain-fusion/chain-key-tokens.md` | `docs/concepts/chain-fusion/chain-key-tokens.md` | new | + +Cross-link updates after this batch: +- `docs/guides/chain-fusion/bitcoin.mdx` — replace Learn Hub link with `concepts/chain-fusion/bitcoin.md` +- `docs/guides/chain-fusion/dogecoin.md` — update upstream comment +- `docs/guides/digital-assets/chain-key-tokens.mdx` — link to `concepts/chain-fusion/chain-key-tokens.md` for mechanics + +--- + +### Batch 6 — Cryptography deep dives (`docs/concepts-cryptography-deep-dives`) + +| Learn Hub article | Staging path | Target | Action | +|---|---|---|---| +| Chain-Key Cryptography (overview) | `how-does-icp-work/chain-key-cryptography/chain-key-cryptography.md` | `docs/concepts/chain-key-cryptography.md` | expand (add depth to intro section) | +| Certified Communication | `how-does-icp-work/chain-key-cryptography/certified-communication.md` | `docs/concepts/certified-data.md` | new | +| Subnet Keys & Subnet Signatures | `how-does-icp-work/chain-key-cryptography/subnet-keys-and-subnet-signatures.md` | `docs/concepts/chain-key-cryptography.md` | expand | +| Chain-Key Signatures (deep) | `how-does-icp-work/chain-key-cryptography/chain-key-signatures.md` | `docs/concepts/chain-key-cryptography.md` | expand | + +Cross-link updates after this batch: +- `docs/guides/backends/certified-variables.md` — link to new `concepts/certified-data.md` for conceptual background + +--- + +### Batch 7 — Governance deep dives (`docs/concepts-governance-deep-dives`) + +| Learn Hub article | Staging path | Target | Action | +|---|---|---|---| +| NNS Overview | `how-does-icp-work/nns/overview.md` | `docs/concepts/governance.md` | expand | +| NNS Neurons | `how-does-icp-work/nns/neurons.md` | `docs/concepts/governance.md` | expand | +| NNS Proposals | `how-does-icp-work/nns/proposals.md` | `docs/concepts/governance.md` | expand | +| Neuron Attributes | `how-does-icp-work/nns/neuron-attributes.md` | `docs/concepts/governance.md` | expand | +| Neurons' Fund | `how-does-icp-work/nns/neurons-fund-nf.md` | `docs/concepts/governance.md` | expand | +| Voting Rewards | `how-does-icp-work/nns/voting-rewards.md` | `docs/concepts/governance.md` | expand | +| NNS Proposal Topics & Types | `how-does-icp-work/nns/proposal-topics-and-types.md` | `docs/references/nns-proposal-types.md` | new (reference) | +| SNS (overview) | `how-does-icp-work/sns/sns-service-nervous-system.md` | `docs/concepts/sns-framework.md` | new | +| SNS Framework & Architecture | `how-does-icp-work/sns/framework-and-architecture.md` | `docs/concepts/sns-framework.md` | new (same file, section) | +| SNS Launch | `how-does-icp-work/sns/launch.md` | `docs/concepts/sns-framework.md` | new (same file, section) | +| SNS Neurons | `how-does-icp-work/sns/neurons.md` | `docs/concepts/sns-framework.md` | new (same file, section) | +| SNS Proposals | `how-does-icp-work/sns/proposals.md` | `docs/concepts/sns-framework.md` | new (same file, section) | +| SNS Rewards | `how-does-icp-work/sns/rewards.md` | `docs/concepts/sns-framework.md` | new (same file, section) | +| SNS DAO Settings | `how-does-icp-work/sns/dao-settings.md` | `docs/references/sns-dao-settings.md` | new (reference) | +| SNS Inspect (user-facing) | `how-does-icp-work/sns/how-to-inspect-an-sns-and-its-dapp-canisters.md` | — | **skip** (out of scope: user-facing UI guide; dev alternative is programmatic SNS aggregator API) | + +Cross-link updates after this batch: +- `docs/guides/governance/managing.md` — replace Learn Hub DAO settings link with `references/sns-dao-settings.md` +- `docs/guides/governance/managing.md` — replace SNS Neurons/Rewards links with `concepts/sns-framework.md` +- `docs/concepts/governance.md` — replace tokenomics Learn Hub link with `concepts/tokenomics.md` (batch 8) +- `docs/references/protocol-canisters.md` — replace SNS Learn Hub link with `concepts/sns-framework.md` +- `docs/references/glossary.md` — update governance entries + +--- + +### Batch 8 — Tokens & ledgers (`docs/concepts-tokens-ledgers`) + +| Learn Hub article | Staging path | Target | Action | +|---|---|---|---| +| Tokenomics (NNS) | `how-does-icp-work/tokens-governance/tokenomics.md` | `docs/concepts/tokenomics.md` | new | +| Tokenomics (SNS) | `how-does-icp-work/sns/tokenomics.md` | `docs/concepts/tokenomics.md` | new (same file, SNS section) | +| How Token Ledgers Work | `how-does-icp-work/tokens-governance/how-token-ledgers-work-on-the-internet-computer.md` | `docs/concepts/token-ledgers.md` | new | +| Tokens & Governance (overview) | `how-does-icp-work/tokens-governance/tokens-governance.md` | `docs/concepts/tokenomics.md` | new (same file, intro) | +| Cycles (billing mechanics) | `how-does-icp-work/canister-smart-contracts/cycles.md` | `docs/concepts/cycles.md` | expand (adds charging model depth) | +| Cycles Ledger | `how-does-icp-work/canister-smart-contracts/cycles-ledger.md` | `docs/concepts/cycles.md` | expand (adds ledger transfer semantics) | + +Cross-link updates after this batch: +- `docs/concepts/governance.md` — replace Learn Hub tokenomics link with `concepts/tokenomics.md` + +--- + +### Batch 9 — Canister concept fillers (`docs/concepts-canister-fillers`) + +| Learn Hub article | Staging path | Target | Action | +|---|---|---|---| +| What is a Principal? | `how-does-icp-work/canister-smart-contracts/what-is-a-principal.md` | `docs/concepts/principals.md` | new | +| Canister Control | `how-does-icp-work/canister-smart-contracts/canister-control.md` | `docs/concepts/principals.md` | new (same file, section) | +| Canister Smart Contracts (conceptual intro) | `how-does-icp-work/canister-smart-contracts/canister-smart-contracts.md` | `docs/concepts/canisters.md` | expand | +| Computational Model | `how-does-icp-work/canister-smart-contracts/computational-model.md` | `docs/concepts/canisters.md` | expand | + +Cross-link updates after this batch: +- `docs/concepts/canisters.md` — replace Learn Hub principal link with `concepts/principals.md` +- `docs/references/glossary.md` — update principal entry to link internally + +--- + +## Skip articles (in-scope directory, not migrated) + +These files sit inside `.migration/learn-hub/how-does-icp-work/` but are not migrated into docs. Do **not** delete them during batch PRs. They remain in the repo until the final cleanup PR, where a human reviews each one and decides whether to discard or migrate. + +| Staging file | Reason skipped | +|---|---| +| `how-does-icp-work/introduction/how-does-icp-work.md` | Redundant with existing `docs/concepts/index.md` | +| `how-does-icp-work/icp-and-the-internet/https-outcalls.md` | Already well-covered in `docs/concepts/https-outcalls.md` (per issue #187) | +| `how-does-icp-work/sns/how-to-inspect-an-sns-and-its-dapp-canisters.md` | User-facing UI guide; developer alternative is the programmatic SNS aggregator API | + +--- + +## Out-of-scope articles (not migrated to dev docs) + +These are committed to `.migration/learn-hub/out-of-scope/` for reference during takedown planning only. + +| Group | Count | Notes | +|---|---|---| +| What is ICP / Overview | 3 | Vision, history, what is ICP — marketing site | +| What is ICP / Performance | 3 | Performance comparison, benchmarks — marketing site | +| What is ICP / Decentralization | 2 | General audience — marketing site | +| How can I use ICP / Governance | ~14 | NNS dapp UI flows — NNS dapp help | +| How can I use ICP / Tokens & wallets | 4 | Quill/wallet flows — quill repo docs | +| How can I use ICP / Network stats | 3 | Operational stats — IC dashboard help | +| SNS inspection (user-facing) | 1 | Programmatic API alternative exists | + +Disposition of these articles (which site each redirects to) is tracked outside this repo. + +--- + +## Known Learn Hub links in the current docs (must all resolve before takedown) + +Run this to find remaining links before Phase 3: +```bash +grep -rn "learn.internetcomputer.org" docs/ --include="*.md" --include="*.mdx" +``` + +Known locations as of 2026-05-06 (from issue #190 analysis): + +| File | Current target | Replacement | +|---|---|---| +| `docs/index.mdx` | Learn Hub LinkCard | Remove or link to `concepts/index.md` | +| `docs/guides/chain-fusion/bitcoin.mdx` | Bitcoin integration article | `concepts/chain-fusion/bitcoin.md` | +| `docs/guides/chain-fusion/dogecoin.md` | Upstream comment only | Drop Learn Hub line | +| `docs/concepts/chain-key-cryptography.md` | Chain Evolution article | `concepts/evolution-scaling.md#chain-evolution` | +| `docs/guides/governance/managing.md` | DAO Settings article | `references/sns-dao-settings.md` | +| `docs/guides/governance/managing.md` | SNS Neurons + Rewards | `concepts/sns-framework.md` | +| `docs/concepts/governance.md` | ICP tokenomics overview | `concepts/tokenomics.md` | +| `docs/concepts/network-overview.md` | Learn Hub generic | `concepts/protocol/index.md` | +| `docs/concepts/https-outcalls.md` | TEE-enabled subnets | `concepts/node-infrastructure.md#trusted-execution-environments` | +| `docs/concepts/https-outcalls.md` | HTTPS outcalls article | Drop (well-covered inline) | +| `docs/concepts/canisters.md` | Principal article | `concepts/principals.md` | +| `docs/references/protocol-canisters.md` | SNS article | `concepts/sns-framework.md` | +| `docs/references/glossary.md` | Various protocol entries | Per-batch internal links (see above) | diff --git a/.docs-plan/migration-plan.md b/.docs-plan/migration-plan.md index 2f251f15..80d9eecf 100644 --- a/.docs-plan/migration-plan.md +++ b/.docs-plan/migration-plan.md @@ -397,3 +397,23 @@ languages/rust/index.md - **All icp-cli commands, flags, and installation instructions must be verified** against the icp-cli repo source (`dfinity/icp-cli`, `docs/reference/cli.md`). Never guess CLI syntax — fetch with: `gh api repos/dfinity/icp-cli/contents/docs/reference/cli.md --jq '.content' | base64 -d` - Each stub page contains `<!-- Content Brief -->`, `<!-- Source Material -->`, and `<!-- Cross-Links -->` HTML comments — read these before writing. - After completing a page, open a PR with a `## Sync recommendation` section and link it to the corresponding GitHub Issue. + +--- + +## Learn Hub migration batches + +Nine content PRs to migrate learn.internetcomputer.org articles into `docs/`. Source staging files are in `.migration/learn-hub/`. Full article-to-file mapping and cross-link instructions: `.docs-plan/learn-hub-navigation.md`. Per-batch agent workflow: `.docs-plan/learn-hub-migration.md`. + +| Batch | Branch | Target files | Effort | +|---|---|---|---| +| 1 — Protocol stack | `docs/concepts-protocol-stack` | `concepts/protocol/index.md`, `consensus.md`, `peer-to-peer.md`, `message-routing.md`, `execution.md`, `state-synchronization.md` | Large | +| 2 — Node infrastructure | `docs/concepts-node-infrastructure` | `concepts/node-infrastructure.md` | Medium | +| 3 — Edge infrastructure | `docs/concepts-edge-infrastructure` | `concepts/edge-infrastructure.md` | Medium | +| 4 — Evolution & scaling | `docs/concepts-evolution-scaling` | `concepts/evolution-scaling.md` | Small–medium | +| 5 — Chain Fusion deep dives | `docs/concepts-chain-fusion-deep-dives` | `concepts/chain-fusion/index.md` (moved), `bitcoin.md`, `ethereum.md`, `solana.md`, `dogecoin.md`, `exchange-rate-canister.md`, `chain-key-tokens.md` | Large | +| 6 — Cryptography deep dives | `docs/concepts-cryptography-deep-dives` | `concepts/certified-data.md`, expand `concepts/chain-key-cryptography.md` | Medium | +| 7 — Governance deep dives | `docs/concepts-governance-deep-dives` | expand `concepts/governance.md`, `concepts/sns-framework.md`, `references/nns-proposal-types.md`, `references/sns-dao-settings.md` | Large | +| 8 — Tokens & ledgers | `docs/concepts-tokens-ledgers` | `concepts/tokenomics.md`, `concepts/token-ledgers.md`, expand `concepts/cycles.md` | Medium | +| 9 — Canister concept fillers | `docs/concepts-canister-fillers` | `concepts/principals.md`, expand `concepts/canisters.md` | Medium | + +Recommended order: batches 1–4 can run in parallel. Batch 8 before batch 7 (governance links to tokenomics). Batches 5, 6, 9 independent. diff --git a/.migration/learn-hub/README.md b/.migration/learn-hub/README.md new file mode 100644 index 00000000..cf0c9fed --- /dev/null +++ b/.migration/learn-hub/README.md @@ -0,0 +1,109 @@ +# ICP Learn Hub Migration + +This directory contains articles fetched from [learn.internetcomputer.org](https://learn.internetcomputer.org). + +## Article counts + +- **In-scope** (How does ICP work?): 57 articles +- **Out-of-scope** (What is ICP? + How can I use ICP?): 29 articles +- **Total**: 86 articles + +## In-scope articles + +These articles are candidates for migration into the developer docs. + +| File | Title | Original URL | +|------|-------|--------------| +| `.migration/learn-hub/how-does-icp-work/blockchain-protocol/blockchain-protocol.md` | Blockchain Protocol | [https://learn.internetcomputer.org/hc/en-us/articles/34206453538964-Blockchain-Protocol](https://learn.internetcomputer.org/hc/en-us/articles/34206453538964-Blockchain-Protocol) | +| `.migration/learn-hub/how-does-icp-work/blockchain-protocol/consensus.md` | Consensus | [https://learn.internetcomputer.org/hc/en-us/articles/34207558615956-Consensus](https://learn.internetcomputer.org/hc/en-us/articles/34207558615956-Consensus) | +| `.migration/learn-hub/how-does-icp-work/blockchain-protocol/execution-layer.md` | Execution Layer | [https://learn.internetcomputer.org/hc/en-us/articles/34208985618836-Execution-Layer](https://learn.internetcomputer.org/hc/en-us/articles/34208985618836-Execution-Layer) | +| `.migration/learn-hub/how-does-icp-work/blockchain-protocol/message-routing.md` | Message Routing | [https://learn.internetcomputer.org/hc/en-us/articles/34208241927316-Message-Routing](https://learn.internetcomputer.org/hc/en-us/articles/34208241927316-Message-Routing) | +| `.migration/learn-hub/how-does-icp-work/blockchain-protocol/peer-to-peer.md` | Peer to peer | [https://learn.internetcomputer.org/hc/en-us/articles/34207428453140-Peer-to-peer](https://learn.internetcomputer.org/hc/en-us/articles/34207428453140-Peer-to-peer) | +| `.migration/learn-hub/how-does-icp-work/blockchain-protocol/state-synchronization.md` | State Synchronization | [https://learn.internetcomputer.org/hc/en-us/articles/34471579767572-State-Synchronization](https://learn.internetcomputer.org/hc/en-us/articles/34471579767572-State-Synchronization) | +| `.migration/learn-hub/how-does-icp-work/canister-smart-contracts/canister-control.md` | Canister Control | [https://learn.internetcomputer.org/hc/en-us/articles/34573932107796-Canister-Control](https://learn.internetcomputer.org/hc/en-us/articles/34573932107796-Canister-Control) | +| `.migration/learn-hub/how-does-icp-work/canister-smart-contracts/canister-smart-contracts.md` | Canister Smart Contracts | [https://learn.internetcomputer.org/hc/en-us/articles/34210839162004-Canister-Smart-Contracts](https://learn.internetcomputer.org/hc/en-us/articles/34210839162004-Canister-Smart-Contracts) | +| `.migration/learn-hub/how-does-icp-work/canister-smart-contracts/computational-model.md` | Computational Model | [https://learn.internetcomputer.org/hc/en-us/articles/34573860369172-Computational-Model](https://learn.internetcomputer.org/hc/en-us/articles/34573860369172-Computational-Model) | +| `.migration/learn-hub/how-does-icp-work/canister-smart-contracts/cycles.md` | Cycles | [https://learn.internetcomputer.org/hc/en-us/articles/34573913497108-Cycles](https://learn.internetcomputer.org/hc/en-us/articles/34573913497108-Cycles) | +| `.migration/learn-hub/how-does-icp-work/canister-smart-contracts/cycles-ledger.md` | Cycles Ledger | [https://learn.internetcomputer.org/hc/en-us/articles/45034096457748-Cycles-Ledger](https://learn.internetcomputer.org/hc/en-us/articles/45034096457748-Cycles-Ledger) | +| `.migration/learn-hub/how-does-icp-work/canister-smart-contracts/what-is-a-principal.md` | What is a Principal? | [https://learn.internetcomputer.org/hc/en-us/articles/34250491785108-What-is-a-Principal](https://learn.internetcomputer.org/hc/en-us/articles/34250491785108-What-is-a-Principal) | +| `.migration/learn-hub/how-does-icp-work/chain-fusion/bitcoin-checker-canister.md` | Bitcoin Checker Canister | [https://learn.internetcomputer.org/hc/en-us/articles/45033984570516-Bitcoin-Checker-Canister](https://learn.internetcomputer.org/hc/en-us/articles/45033984570516-Bitcoin-Checker-Canister) | +| `.migration/learn-hub/how-does-icp-work/chain-fusion/bitcoin-integration.md` | Bitcoin Integration | [https://learn.internetcomputer.org/hc/en-us/articles/34211154520084-Bitcoin-Integration](https://learn.internetcomputer.org/hc/en-us/articles/34211154520084-Bitcoin-Integration) | +| `.migration/learn-hub/how-does-icp-work/chain-fusion/chain-fusion.md` | Chain Fusion | [https://learn.internetcomputer.org/hc/en-us/articles/34329023770260-Chain-Fusion](https://learn.internetcomputer.org/hc/en-us/articles/34329023770260-Chain-Fusion) | +| `.migration/learn-hub/how-does-icp-work/chain-fusion/chain-key-tokens.md` | Chain-Key Tokens | [https://learn.internetcomputer.org/hc/en-us/articles/34211397080980-Chain-Key-Tokens](https://learn.internetcomputer.org/hc/en-us/articles/34211397080980-Chain-Key-Tokens) | +| `.migration/learn-hub/how-does-icp-work/chain-fusion/chain-key-bitcoin.md` | Chain-key Bitcoin | [https://learn.internetcomputer.org/hc/en-us/articles/44598021228564-Chain-key-Bitcoin](https://learn.internetcomputer.org/hc/en-us/articles/44598021228564-Chain-key-Bitcoin) | +| `.migration/learn-hub/how-does-icp-work/chain-fusion/dogecoin-integration.md` | Dogecoin Integration | [https://learn.internetcomputer.org/hc/en-us/articles/46782835018516-Dogecoin-Integration](https://learn.internetcomputer.org/hc/en-us/articles/46782835018516-Dogecoin-Integration) | +| `.migration/learn-hub/how-does-icp-work/chain-fusion/evm-rpc-canister.md` | EVM RPC Canister | [https://learn.internetcomputer.org/hc/en-us/articles/45550731488916-EVM-RPC-Canister](https://learn.internetcomputer.org/hc/en-us/articles/45550731488916-EVM-RPC-Canister) | +| `.migration/learn-hub/how-does-icp-work/chain-fusion/ethereum-integration.md` | Ethereum Integration | [https://learn.internetcomputer.org/hc/en-us/articles/34575019947668-Ethereum-Integration](https://learn.internetcomputer.org/hc/en-us/articles/34575019947668-Ethereum-Integration) | +| `.migration/learn-hub/how-does-icp-work/chain-fusion/exchange-rate-canister.md` | Exchange Rate Canister | [https://learn.internetcomputer.org/hc/en-us/articles/45038506066452-Exchange-Rate-Canister](https://learn.internetcomputer.org/hc/en-us/articles/45038506066452-Exchange-Rate-Canister) | +| `.migration/learn-hub/how-does-icp-work/chain-fusion/sol-rpc-canister.md` | SOL RPC Canister | [https://learn.internetcomputer.org/hc/en-us/articles/46782465439764-SOL-RPC-Canister](https://learn.internetcomputer.org/hc/en-us/articles/46782465439764-SOL-RPC-Canister) | +| `.migration/learn-hub/how-does-icp-work/chain-key-cryptography/certified-communication.md` | Certified Communication | [https://learn.internetcomputer.org/hc/en-us/articles/34214090576404-Certified-Communication](https://learn.internetcomputer.org/hc/en-us/articles/34214090576404-Certified-Communication) | +| `.migration/learn-hub/how-does-icp-work/chain-key-cryptography/chain-key-cryptography.md` | Chain-Key Cryptography | [https://learn.internetcomputer.org/hc/en-us/articles/34209486239252-Chain-Key-Cryptography](https://learn.internetcomputer.org/hc/en-us/articles/34209486239252-Chain-Key-Cryptography) | +| `.migration/learn-hub/how-does-icp-work/chain-key-cryptography/chain-key-signatures.md` | Chain-Key Signatures | [https://learn.internetcomputer.org/hc/en-us/articles/34209497587732-Chain-Key-Signatures](https://learn.internetcomputer.org/hc/en-us/articles/34209497587732-Chain-Key-Signatures) | +| `.migration/learn-hub/how-does-icp-work/chain-key-cryptography/subnet-keys-and-subnet-signatures.md` | Subnet Keys and Subnet Signatures | [https://learn.internetcomputer.org/hc/en-us/articles/34209540682644-Subnet-Keys-and-Subnet-Signatures](https://learn.internetcomputer.org/hc/en-us/articles/34209540682644-Subnet-Keys-and-Subnet-Signatures) | +| `.migration/learn-hub/how-does-icp-work/evolution-scaling/chain-evolution.md` | Chain Evolution | [https://learn.internetcomputer.org/hc/en-us/articles/34210120121748-Chain-Evolution](https://learn.internetcomputer.org/hc/en-us/articles/34210120121748-Chain-Evolution) | +| `.migration/learn-hub/how-does-icp-work/evolution-scaling/evolution-scaling.md` | Evolution & Scaling | [https://learn.internetcomputer.org/hc/en-us/articles/34576974172692-Evolution-Scaling](https://learn.internetcomputer.org/hc/en-us/articles/34576974172692-Evolution-Scaling) | +| `.migration/learn-hub/how-does-icp-work/evolution-scaling/fault-tolerance.md` | Fault Tolerance | [https://learn.internetcomputer.org/hc/en-us/articles/34210647901460-Fault-Tolerance](https://learn.internetcomputer.org/hc/en-us/articles/34210647901460-Fault-Tolerance) | +| `.migration/learn-hub/how-does-icp-work/evolution-scaling/subnet-creation.md` | Subnet Creation | [https://learn.internetcomputer.org/hc/en-us/articles/34209955782420-Subnet-Creation](https://learn.internetcomputer.org/hc/en-us/articles/34209955782420-Subnet-Creation) | +| `.migration/learn-hub/how-does-icp-work/icp-and-the-internet/asset-certification.md` | Asset Certification | [https://learn.internetcomputer.org/hc/en-us/articles/34276431179412-Asset-Certification](https://learn.internetcomputer.org/hc/en-us/articles/34276431179412-Asset-Certification) | +| `.migration/learn-hub/how-does-icp-work/icp-and-the-internet/http-gateway-protocol.md` | HTTP Gateway Protocol | [https://learn.internetcomputer.org/hc/en-us/articles/34211943471892-HTTP-Gateway-Protocol](https://learn.internetcomputer.org/hc/en-us/articles/34211943471892-HTTP-Gateway-Protocol) | +| `.migration/learn-hub/how-does-icp-work/icp-and-the-internet/https-outcalls.md` | HTTPS Outcalls | [https://learn.internetcomputer.org/hc/en-us/articles/34211194553492-HTTPS-Outcalls](https://learn.internetcomputer.org/hc/en-us/articles/34211194553492-HTTPS-Outcalls) | +| `.migration/learn-hub/how-does-icp-work/icp-and-the-internet/icp-edge-infrastructure.md` | ICP Edge Infrastructure | [https://learn.internetcomputer.org/hc/en-us/articles/34212818609684-ICP-Edge-Infrastructure](https://learn.internetcomputer.org/hc/en-us/articles/34212818609684-ICP-Edge-Infrastructure) | +| `.migration/learn-hub/how-does-icp-work/icp-and-the-internet/icp-and-the-internet.md` | ICP and the Internet | [https://learn.internetcomputer.org/hc/en-us/articles/34574399808788-ICP-and-the-Internet](https://learn.internetcomputer.org/hc/en-us/articles/34574399808788-ICP-and-the-Internet) | +| `.migration/learn-hub/how-does-icp-work/introduction/how-does-icp-work.md` | How does ICP work? | [https://learn.internetcomputer.org/hc/en-us/articles/33694833025172-How-does-ICP-work](https://learn.internetcomputer.org/hc/en-us/articles/33694833025172-How-does-ICP-work) | +| `.migration/learn-hub/how-does-icp-work/nns/neuron-attributes.md` | Neuron Attributes | [https://learn.internetcomputer.org/hc/en-us/articles/34140499557908-Neuron-Attributes](https://learn.internetcomputer.org/hc/en-us/articles/34140499557908-Neuron-Attributes) | +| `.migration/learn-hub/how-does-icp-work/nns/neurons.md` | Neurons | [https://learn.internetcomputer.org/hc/en-us/articles/34084120668692-Neurons](https://learn.internetcomputer.org/hc/en-us/articles/34084120668692-Neurons) | +| `.migration/learn-hub/how-does-icp-work/nns/neurons-fund-nf.md` | Neurons' Fund (NF) | [https://learn.internetcomputer.org/hc/en-us/articles/34084179554196-Neurons-Fund-NF](https://learn.internetcomputer.org/hc/en-us/articles/34084179554196-Neurons-Fund-NF) | +| `.migration/learn-hub/how-does-icp-work/nns/overview.md` | Overview | [https://learn.internetcomputer.org/hc/en-us/articles/33692645961236-Overview](https://learn.internetcomputer.org/hc/en-us/articles/33692645961236-Overview) | +| `.migration/learn-hub/how-does-icp-work/nns/proposal-topics-and-types.md` | Proposal Topics and Types | [https://learn.internetcomputer.org/hc/en-us/articles/34140518658068-Proposal-Topics-and-Types](https://learn.internetcomputer.org/hc/en-us/articles/34140518658068-Proposal-Topics-and-Types) | +| `.migration/learn-hub/how-does-icp-work/nns/proposals.md` | Proposals | [https://learn.internetcomputer.org/hc/en-us/articles/34084113508500-Proposals](https://learn.internetcomputer.org/hc/en-us/articles/34084113508500-Proposals) | +| `.migration/learn-hub/how-does-icp-work/nns/voting-rewards.md` | Voting Rewards | [https://learn.internetcomputer.org/hc/en-us/articles/34142993417108-Voting-Rewards](https://learn.internetcomputer.org/hc/en-us/articles/34142993417108-Voting-Rewards) | +| `.migration/learn-hub/how-does-icp-work/node-infrastructure/overview.md` | Overview | [https://learn.internetcomputer.org/hc/en-us/articles/46135518360212-Overview](https://learn.internetcomputer.org/hc/en-us/articles/46135518360212-Overview) | +| `.migration/learn-hub/how-does-icp-work/node-infrastructure/trusted-execution-environments.md` | Trusted Execution Environments | [https://learn.internetcomputer.org/hc/en-us/articles/46124920595988-Trusted-Execution-Environments](https://learn.internetcomputer.org/hc/en-us/articles/46124920595988-Trusted-Execution-Environments) | +| `.migration/learn-hub/how-does-icp-work/sns/dao-settings.md` | DAO Settings | [https://learn.internetcomputer.org/hc/en-us/articles/34142964565396-DAO-Settings](https://learn.internetcomputer.org/hc/en-us/articles/34142964565396-DAO-Settings) | +| `.migration/learn-hub/how-does-icp-work/sns/framework-and-architecture.md` | Framework and Architecture | [https://learn.internetcomputer.org/hc/en-us/articles/34140764336788-Framework-and-Architecture](https://learn.internetcomputer.org/hc/en-us/articles/34140764336788-Framework-and-Architecture) | +| `.migration/learn-hub/how-does-icp-work/sns/how-to-inspect-an-sns-and-its-dapp-canisters.md` | How to Inspect an SNS and Its Dapp Canisters | [https://learn.internetcomputer.org/hc/en-us/articles/46381576634772-How-to-Inspect-an-SNS-and-Its-Dapp-Canisters](https://learn.internetcomputer.org/hc/en-us/articles/46381576634772-How-to-Inspect-an-SNS-and-Its-Dapp-Canisters) | +| `.migration/learn-hub/how-does-icp-work/sns/launch.md` | Launch | [https://learn.internetcomputer.org/hc/en-us/articles/34141180048404-Launch](https://learn.internetcomputer.org/hc/en-us/articles/34141180048404-Launch) | +| `.migration/learn-hub/how-does-icp-work/sns/neurons.md` | Neurons | [https://learn.internetcomputer.org/hc/en-us/articles/34084687583252-Neurons](https://learn.internetcomputer.org/hc/en-us/articles/34084687583252-Neurons) | +| `.migration/learn-hub/how-does-icp-work/sns/proposals.md` | Proposals | [https://learn.internetcomputer.org/hc/en-us/articles/34146571133204-Proposals](https://learn.internetcomputer.org/hc/en-us/articles/34146571133204-Proposals) | +| `.migration/learn-hub/how-does-icp-work/sns/rewards.md` | Rewards | [https://learn.internetcomputer.org/hc/en-us/articles/34143058069396-Rewards](https://learn.internetcomputer.org/hc/en-us/articles/34143058069396-Rewards) | +| `.migration/learn-hub/how-does-icp-work/sns/sns-service-nervous-system.md` | SNS - Service Nervous System | [https://learn.internetcomputer.org/hc/en-us/articles/34084394684564-SNS-Service-Nervous-System](https://learn.internetcomputer.org/hc/en-us/articles/34084394684564-SNS-Service-Nervous-System) | +| `.migration/learn-hub/how-does-icp-work/sns/tokenomics.md` | Tokenomics | [https://learn.internetcomputer.org/hc/en-us/articles/34088279488660-Tokenomics](https://learn.internetcomputer.org/hc/en-us/articles/34088279488660-Tokenomics) | +| `.migration/learn-hub/how-does-icp-work/tokens-governance/how-token-ledgers-work-on-the-internet-computer.md` | How Token Ledgers Work on the Internet Computer | [https://learn.internetcomputer.org/hc/en-us/articles/44969820125972-How-Token-Ledgers-Work-on-the-Internet-Computer](https://learn.internetcomputer.org/hc/en-us/articles/44969820125972-How-Token-Ledgers-Work-on-the-Internet-Computer) | +| `.migration/learn-hub/how-does-icp-work/tokens-governance/tokenomics.md` | Tokenomics | [https://learn.internetcomputer.org/hc/en-us/articles/34090810571284-Tokenomics](https://learn.internetcomputer.org/hc/en-us/articles/34090810571284-Tokenomics) | +| `.migration/learn-hub/how-does-icp-work/tokens-governance/tokens-governance.md` | Tokens & Governance | [https://learn.internetcomputer.org/hc/en-us/articles/34574082263700-Tokens-Governance](https://learn.internetcomputer.org/hc/en-us/articles/34574082263700-Tokens-Governance) | + +## Out-of-scope articles + +These articles are from categories not relevant to developer documentation. + +| File | Title | Section | Original URL | +|------|-------|---------|--------------| +| `.migration/learn-hub/out-of-scope/what-is-icp/decentralization.md` | Decentralization | Decentralization | [https://learn.internetcomputer.org/hc/en-us/articles/44009922536852-Decentralization](https://learn.internetcomputer.org/hc/en-us/articles/44009922536852-Decentralization) | +| `.migration/learn-hub/out-of-scope/what-is-icp/icp-subsystems.md` | ICP subsystems | Decentralization | [https://learn.internetcomputer.org/hc/en-us/articles/44549459496596-ICP-subsystems](https://learn.internetcomputer.org/hc/en-us/articles/44549459496596-ICP-subsystems) | +| `.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/community-built-dashboards.md` | Community-built dashboards | Governance | [https://learn.internetcomputer.org/hc/en-us/articles/33152050043156-Community-built-dashboards](https://learn.internetcomputer.org/hc/en-us/articles/33152050043156-Community-built-dashboards) | +| `.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-add-an-icp-sub-account.md` | How can I add an ICP (sub-)account? | Governance | [https://learn.internetcomputer.org/hc/en-us/articles/42494280383252-How-can-I-add-an-ICP-sub-account](https://learn.internetcomputer.org/hc/en-us/articles/42494280383252-How-can-I-add-an-ICP-sub-account) | +| `.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-configure-a-neuron.md` | How can I configure a neuron? | Governance | [https://learn.internetcomputer.org/hc/en-us/articles/42755094620180-How-can-I-configure-a-neuron](https://learn.internetcomputer.org/hc/en-us/articles/42755094620180-How-can-I-configure-a-neuron) | +| `.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-disburse-a-neuron.md` | How can I disburse a neuron? | Governance | [https://learn.internetcomputer.org/hc/en-us/articles/42754712016148-How-can-I-disburse-a-neuron](https://learn.internetcomputer.org/hc/en-us/articles/42754712016148-How-can-I-disburse-a-neuron) | +| `.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-disburse-maturity.md` | How can I disburse maturity? | Governance | [https://learn.internetcomputer.org/hc/en-us/articles/39755298701204-How-can-I-disburse-maturity](https://learn.internetcomputer.org/hc/en-us/articles/39755298701204-How-can-I-disburse-maturity) | +| `.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-find-my-icp-token-accounts.md` | How can I find my (ICP) token accounts? | Governance | [https://learn.internetcomputer.org/hc/en-us/articles/42493986016788-How-can-I-find-my-ICP-token-accounts](https://learn.internetcomputer.org/hc/en-us/articles/42493986016788-How-can-I-find-my-ICP-token-accounts) | +| `.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-import-icrc-tokens.md` | How can I import ICRC tokens? | Governance | [https://learn.internetcomputer.org/hc/en-us/articles/42529262055700-How-can-I-import-ICRC-tokens](https://learn.internetcomputer.org/hc/en-us/articles/42529262055700-How-can-I-import-ICRC-tokens) | +| `.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-log-into-the-nns-dapp.md` | How can I log into the NNS dapp? | Governance | [https://learn.internetcomputer.org/hc/en-us/articles/39615237318548-How-can-I-log-into-the-NNS-dapp](https://learn.internetcomputer.org/hc/en-us/articles/39615237318548-How-can-I-log-into-the-NNS-dapp) | +| `.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-receive-icp-tokens.md` | How can I receive ICP tokens? | Governance | [https://learn.internetcomputer.org/hc/en-us/articles/42494789123092-How-can-I-receive-ICP-tokens](https://learn.internetcomputer.org/hc/en-us/articles/42494789123092-How-can-I-receive-ICP-tokens) | +| `.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-send-icp-tokens.md` | How can I send ICP tokens? | Governance | [https://learn.internetcomputer.org/hc/en-us/articles/42499104466324-How-can-I-send-ICP-tokens](https://learn.internetcomputer.org/hc/en-us/articles/42499104466324-How-can-I-send-ICP-tokens) | +| `.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-stake-a-neuron.md` | How can I stake a neuron? | Governance | [https://learn.internetcomputer.org/hc/en-us/articles/42754119358484-How-can-I-stake-a-neuron](https://learn.internetcomputer.org/hc/en-us/articles/42754119358484-How-can-I-stake-a-neuron) | +| `.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-stake-and-auto-stake-maturity.md` | How can I stake and auto-stake maturity? | Governance | [https://learn.internetcomputer.org/hc/en-us/articles/39755363912724-How-can-I-stake-and-auto-stake-maturity](https://learn.internetcomputer.org/hc/en-us/articles/39755363912724-How-can-I-stake-and-auto-stake-maturity) | +| `.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-top-up-a-neuron.md` | How can I top up a neuron? | Governance | [https://learn.internetcomputer.org/hc/en-us/articles/42756506278804-How-can-I-top-up-a-neuron](https://learn.internetcomputer.org/hc/en-us/articles/42756506278804-How-can-I-top-up-a-neuron) | +| `.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/internet-computer-dashboard.md` | Internet Computer dashboard | Governance | [https://learn.internetcomputer.org/hc/en-us/articles/33152081370260-Internet-Computer-dashboard](https://learn.internetcomputer.org/hc/en-us/articles/33152081370260-Internet-Computer-dashboard) | +| `.migration/learn-hub/out-of-scope/how-can-i-use-icp/network-stats/cycle-burn.md` | Cycle burn | Network stats | [https://learn.internetcomputer.org/hc/en-us/articles/33152123370772-Cycle-burn](https://learn.internetcomputer.org/hc/en-us/articles/33152123370772-Cycle-burn) | +| `.migration/learn-hub/out-of-scope/how-can-i-use-icp/network-stats/network-topology.md` | Network topology | Network stats | [https://learn.internetcomputer.org/hc/en-us/articles/33152148267412-Network-topology](https://learn.internetcomputer.org/hc/en-us/articles/33152148267412-Network-topology) | +| `.migration/learn-hub/out-of-scope/how-can-i-use-icp/network-stats/tx-s.md` | tx/s | Network stats | [https://learn.internetcomputer.org/hc/en-us/articles/33152121376404-tx-s](https://learn.internetcomputer.org/hc/en-us/articles/33152121376404-tx-s) | +| `.migration/learn-hub/out-of-scope/what-is-icp/what-has-happened-so-far.md` | What Has Happened So Far? | Overview | [https://learn.internetcomputer.org/hc/en-us/articles/33152692358036-What-Has-Happened-So-Far](https://learn.internetcomputer.org/hc/en-us/articles/33152692358036-What-Has-Happened-So-Far) | +| `.migration/learn-hub/out-of-scope/what-is-icp/what-is-icp.md` | What is ICP? | Overview | [https://learn.internetcomputer.org/hc/en-us/articles/33152818663444-What-is-ICP](https://learn.internetcomputer.org/hc/en-us/articles/33152818663444-What-is-ICP) | +| `.migration/learn-hub/out-of-scope/what-is-icp/what-is-the-vision-behind-icp.md` | What is the Vision behind ICP? | Overview | [https://learn.internetcomputer.org/hc/en-us/articles/33624077003668-What-is-the-Vision-behind-ICP](https://learn.internetcomputer.org/hc/en-us/articles/33624077003668-What-is-the-Vision-behind-ICP) | +| `.migration/learn-hub/out-of-scope/what-is-icp/not-all-transactions-are-equal.md` | Not All Transactions Are Equal | Performance | [https://learn.internetcomputer.org/hc/en-us/articles/39158902116884-Not-All-Transactions-Are-Equal](https://learn.internetcomputer.org/hc/en-us/articles/39158902116884-Not-All-Transactions-Are-Equal) | +| `.migration/learn-hub/out-of-scope/what-is-icp/performance.md` | Performance | Performance | [https://learn.internetcomputer.org/hc/en-us/articles/39320190051348-Performance](https://learn.internetcomputer.org/hc/en-us/articles/39320190051348-Performance) | +| `.migration/learn-hub/out-of-scope/what-is-icp/performance-comparison.md` | Performance Comparison | Performance | [https://learn.internetcomputer.org/hc/en-us/articles/39314351721492-Performance-Comparison](https://learn.internetcomputer.org/hc/en-us/articles/39314351721492-Performance-Comparison) | +| `.migration/learn-hub/out-of-scope/how-can-i-use-icp/tokens-wallets/how-can-i-stake-icp-with-quill.md` | How can I stake ICP with quill? | Tokens & wallets | [https://learn.internetcomputer.org/hc/en-us/articles/43823123678100-How-can-I-stake-ICP-with-quill](https://learn.internetcomputer.org/hc/en-us/articles/43823123678100-How-can-I-stake-ICP-with-quill) | +| `.migration/learn-hub/out-of-scope/how-can-i-use-icp/tokens-wallets/how-do-i-set-up-an-air-gapped-wallet-with-quill.md` | How do I set up an air-gapped wallet with quill? | Tokens & wallets | [https://learn.internetcomputer.org/hc/en-us/articles/41523709355668-How-do-I-set-up-an-air-gapped-wallet-with-quill](https://learn.internetcomputer.org/hc/en-us/articles/41523709355668-How-do-I-set-up-an-air-gapped-wallet-with-quill) | +| `.migration/learn-hub/out-of-scope/how-can-i-use-icp/tokens-wallets/how-do-i-transfer-tokens-with-quill.md` | How do I transfer tokens with quill? | Tokens & wallets | [https://learn.internetcomputer.org/hc/en-us/articles/41526165816596-How-do-I-transfer-tokens-with-quill](https://learn.internetcomputer.org/hc/en-us/articles/41526165816596-How-do-I-transfer-tokens-with-quill) | +| `.migration/learn-hub/out-of-scope/how-can-i-use-icp/tokens-wallets/icp-custody-options.md` | ICP Custody Options | Tokens & wallets | [https://learn.internetcomputer.org/hc/en-us/articles/42139140618516-ICP-Custody-Options](https://learn.internetcomputer.org/hc/en-us/articles/42139140618516-ICP-Custody-Options) | diff --git a/.migration/learn-hub/how-does-icp-work/blockchain-protocol/blockchain-protocol.md b/.migration/learn-hub/how-does-icp-work/blockchain-protocol/blockchain-protocol.md new file mode 100644 index 00000000..7a1a8e3a --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/blockchain-protocol/blockchain-protocol.md @@ -0,0 +1,34 @@ +--- +learn_hub_id: 34206453538964 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34206453538964-Blockchain-Protocol" +learn_hub_title: "Blockchain Protocol" +learn_hub_section: "Blockchain Protocol" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# Blockchain Protocol + +The Internet Computer is created by the Internet Computer Protocol (ICP), from which its utility token, the ICP token, derives its name. The Internet Computer consists of multiple subnets, with each subnet created by its own instance of a blockchain protocol stack. Each subnet hosts canister smart contracts and executes messages sent to them either by users or other canister smart contracts (which may be hosted on the same or another subnet). Messages on the IC are analogous to transactions on other blockchains. Messages addressed to a canister smart contract are executed by the nodes on the corresponding subnet by running the code of the canister. Canister code execution updates the canister state. In order to keep the state on the subnet nodes on which a canister is hosted in sync, it must be ensured that every node executes the same messages in the same order, i.e., fully deterministically. This is the core of the blockchain-based replicated state machine functionality realizing the Internet Computer. + +Each node on the Internet Computer runs a replica process. The replica process is structured in a layered architecture consisting of the following 4 layers: + + 1. [Peer-to-peer](https://learn.internetcomputer.org/hc/en-us/articles/34207428453140) + 2. [Consensus](https://learn.internetcomputer.org/hc/en-us/articles/34207558615956) + 3. [Message routing](https://learn.internetcomputer.org/hc/en-us/articles/34208241927316) + 4. [Execution](https://learn.internetcomputer.org/hc/en-us/articles/34208985618836) + + + +![4-layer architecture of the Internet Computer](https://csojb-wiaaa-aaaal-qjftq-cai.icp0.io/_astro/core_protocol_layers.Q9HZPKLE_Z1WJp60.webp) + +_4-layer architecture of the Internet Computer_ + +The **peer-to-peer** layer is responsible for accepting messages from users and exchanging messages between nodes in a subnet. The **consensus** layer makes all the nodes on the subnet agree on the messages to be processed, as well as their ordering. The **message routing** layer picks up the finalized blocks from the consensus layer and routes the messages in the blocks to the appropriate canisters. The **execution** layer determinstically executes canister code on the messages received from the messaging layer. + +The upper two layers realize deterministic execution of the block of messages for a round received from the lower two layers, on each node of the subnet. At the beginning of a round, all (honest) nodes hold the same state, representing the replicated state of the subnet, which includes the current state of all canisters hosted on that subnet. By executing the messages of the next block received from consensus in a completely deterministic manner, it is ensured that the state after executing the messages of the block is the same on each node. + +Canister smart contracts can communicate with each other by sending messages, regardless of whether they are hosted on the same or different subnets. The IC core protocol handles both the inter-canister messages sent locally, i.e., on the same subnet, between canisters, as well as inter-canister messages sent across subnets, so called XNet (or _cross-net_) messages. Local inter-canister messages do not need to go through consensus, while XNet inter-canister messages do (making the former more efficient in terms of throughput and incurring less latency). + +To allow nodes to efficiently join a subnet that is running already or to catch up with the current state in case they have been offline for some time, the protocol supports [state synchronization](https://learn.internetcomputer.org/hc/en-us/articles/34471579767572) without processing all messages that have ever been executed. + diff --git a/.migration/learn-hub/how-does-icp-work/blockchain-protocol/consensus.md b/.migration/learn-hub/how-does-icp-work/blockchain-protocol/consensus.md new file mode 100644 index 00000000..c6115c4c --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/blockchain-protocol/consensus.md @@ -0,0 +1,69 @@ +--- +learn_hub_id: 34207558615956 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34207558615956-Consensus" +learn_hub_title: "Consensus" +learn_hub_section: "Blockchain Protocol" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# Consensus + +The consensus protocol allows the nodes to agree on the messages to be processed, as well as their ordering. The nodes in each ICP subnet run their own instance of the consensus protocol, independently of the other subnets. The purpose of the consensus protocol is to output the same block of ordered messages on each node of a subnet in a given round so that each node can make the same state transition when deterministically executing those messages. + +ICP’s consensus protocol is designed to meet the following requirements: low latency (almost instant finality); high throughput; robustness (graceful degradation of latency and throughput in the presence of node or network failures). + +The consensus protocol provides cryptographically guaranteed finality. The option of choosing probabilistic finality – similar to what is done in Bitcoin-like protocols, by considering a block final once a sufficient number of blocks have built on top of it in the blockchain – is not sufficient for ICP for two reasons: (1) probabilistic finality is a very weak notion of finality and (2) probabilistic finality would increase the time to finality drastically. + +The IC consensus protocol achieves all of these goals making only minimal assumptions about the communication network. In particular, safety of the protocol does not depend on any bounds on the time it takes for protocol messages to be delivered – that is, it only assumes an asynchronous network rather than a synchronous network. Indeed, for a decentralized network that is globally distributed, synchrony is simply not a realistic assumption. In order to achieve good latency, the IC consensus protocol requires protocol messages to be delivered in a timely manner to make progress. While it is possible to design consensus protocols that work in a purely asynchronous setting, these protocols generally have very poor latency. However, the correctness of the protocol is always guaranteed, regardless of message delays, so long as less than a third of the nodes in the subnet are faulty. + +![Consensus round yields an ordered sequences of messages](https://csojb-wiaaa-aaaal-qjftq-cai.icp0.io/_astro/consensus_orders_messages.CPiCaIlB_27rmgz.webp) + +The consensus protocol maintains a tree of notarized blocks (with a special origin block at the root). The protocol proceeds in rounds. In each round, at least one notarized block is added to the tree as a child of a notarized block that was added in the previous round. When things go right, there will be only one notarized block added to the tree in that round, and that block will be marked as finalized. Moreover, once a block is marked as finalized in this way, all ancestors of that block in the tree of notarized blocks are implicitly finalized. The protocol guarantees that there is always a unique chain of finalized blocks in the tree of notarized blocks. This chain of finalized blocks is the output of consensus. + +At a high level, a consensus round has the following three phases: + + * Block making: In every round, at least one node, called a block maker, proposes a block by broadcasting it to all nodes in the subnet using P2P. As we will see, when things go right, there is only one block maker, but sometimes there may be several. + * Notarization: For a block to become notarized, at least two thirds of the nodes must validate the node and support its notarization. + * Finalization: For a block to become finalized, at least two thirds of the nodes must support its finalization. As we will see, a node will support the finalization of a block only if it did not support the notarization of any other block, and this simple rule guarantees that if a block is finalized in a given round, then there can be no other notarized block in that round. + + + +Let us next look at the different phases of a consensus round in more detail. + +## Block making + +A block maker is a node that proposes a block for the current round with a reference to a notarized block of the previous round. As explained below, a cryptographic mechanism called a random beacon is used to select one node (chosen at random) as the primary block maker (or leader) for the current round. The primary block maker assembles a block containing the ingress messages (submitted directly to the node or received from other nodes in the subnet via P2P) and XNet messages (sent to this subnet from other subnets). After assembling a block, the primary block maker proposes this block by broadcasting it to all nodes in the subnet using P2P. + +If the network is slow or the primary block maker is faulty, the block proposed by the primary block maker may not get notarized within a reasonable time. In this case, after some delay, and using the same random beacon mechanism, other block makers are chosen to step in and supplant the primary block maker. The protocol logic guarantees that one block eventually gets notarized in the current round. + +The block makers for a round are chosen through a random permutation of the nodes of the subnet based on randomness derived from a random beacon. [Chain-key cryptography](https://learn.internetcomputer.org/hc/en-us/articles/34209486239252) is used to produce unpredictable and unbiasable pseudo-random numbers. Consensus uses these pseudo-random numbers to define a pseudo-random permutation on the nodes of the subnet. This assigns a rank to each node in the subnet. The lowest-rank node in the subnet acts as the primary block maker. As time goes by without producing a notarized block, nodes of increasing rank gradually step in to supplant the (potentially faulty) nodes of lower rank as block maker. + +In the scenario where the primary block maker is not faulty, and protocol messages get delivered in a timely manner, only the primary block maker will propose a block, and this block will quickly become notarized and finalized. + +![Blockmaker constructs a new block and broadcasts it](https://csojb-wiaaa-aaaal-qjftq-cai.icp0.io/_astro/block_maker.Dwr4LMy1_Z2fhEcM.webp) + +## Notarization + +When a node receives a block proposed by a block maker for the round, it validates the block for syntactic correctness. If the block passes this validity check, the node supports the notarization of the block by broadcasting the block and a notarization share for the block to all nodes in the subnet. A notarization share is a signature share computed using the [BLS multi-signature scheme](https://crypto.stanford.edu/~dabo/pubs/papers/BLSmultisig.html). A block becomes notarized when at least two thirds of the nodes in the subnet support its notarization. In this case, the BLS multi-signature shares may be aggregated to form a compact notarization for the block. + +In the case where the block proposed by the primary block maker gets notarized within a certain amount of time, a node will not support the notarization of any other block in that round. Otherwise, a node may eventually support the notarization of blocks proposed by other block makers of higher rank (but if it has already supported the notarization of a block proposed by a block maker of some rank, it will not support the notarization of blocks proposed by block makers of higher rank). + +![Notarization support of increasing-rank block proposals in a round](https://csojb-wiaaa-aaaal-qjftq-cai.icp0.io/_astro/consensus_notarization.CRg0Lh07_Z1zthef.webp) + +## Finalization + +In a given round, the logic of the protocol guarantees that a node will always obtain a notarized block (assuming less than a third of the nodes in the subnet are faulty). Once it obtains a notarized block, the node will not subsequently support the notarization of any other block. Moreover, if the node did not previously support the notarization of any other block, the node will also support the finalization of this block. It supports the finalization of this block by broadcasting a finalization share for the block to all nodes in the subnet. A finalization share is a signature share computed using the BLS multi-signature scheme. A block becomes finalized when at least two thirds of the nodes in the subnet support its finalization. In this case, the BLS multi-signature shares may be aggregated to form a compact finalization for the block. + +## Additional information + +[Blogpost on Consensus on the Internet Computer](https://medium.com/dfinity/achieving-consensus-on-the-internet-computer-ee9fbfbafcbc) + +[Consensus White Paper](https://eprint.iacr.org/2021/632.pdf) + +[Extended Abstract published at PODC’22](https://assets.ctfassets.net/ywqk17d3hsnp/1Gutwfrd1lMgiUBJZGCdUG/d3ea7730aba0a4b793741681463239f5/podc-2022-cr.pdf) + +[10min video ](https://www.youtube.com/watch?v=WoLWJ5dsWyI&list=PLVEhhIklNtB4HjWkLhqNacvBDzA0Wt2H1) + +[20min video](https://www.youtube.com/watch?v=vVLRRYh3JYo) + diff --git a/.migration/learn-hub/how-does-icp-work/blockchain-protocol/execution-layer.md b/.migration/learn-hub/how-does-icp-work/blockchain-protocol/execution-layer.md new file mode 100644 index 00000000..79541e63 --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/blockchain-protocol/execution-layer.md @@ -0,0 +1,75 @@ +--- +learn_hub_id: 34208985618836 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34208985618836-Execution-Layer" +learn_hub_title: "Execution Layer" +learn_hub_section: "Blockchain Protocol" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# Execution Layer + +The execution layer, the topmost layer of the Internet Computer (IC) core protocol stack, is responsible for executing canister smart contract code. Code execution is done by a [WebAssembly](https://webassembly.org/) (Wasm) virtual machine deployed on every node. WebAssembly bytecode can be executed deterministically, which is important for a blockchain system, and with near-native speed. Canister messages, i.e., ingress messages by users or messages by other canisters, have been inducted into the queues of the canisters on the subnet by message routing. Message routing then hands over control to the execution layer, which deterministically executes messages, either until all messages in the canisters’ queues are consumed or the cycles limit for the round has been reached, to ensure bounded round times. + +The execution layer has many unique features, which set apart the IC from other blockchains: + + 1. **Deterministic Time Slicing (DTS):** The execution of very large messages requiring billions of Wasm instructions to be executed can be split across multiple IC rounds. This capability of executing messages over multiple rounds is unique to ICP. + 2. **Concurrency:** Execution of canister Wasm bytecode is done concurrently on multiple CPU cores, which is possible due to each canister having its own isolated state. + 3. **Pseudorandom number generator:** The execution layer has access to an unpredictable and unbiasable pseudorandom number generator. Canisters can now execute algorithms that require randomness. + + + +## Replicated message execution + +Replicated execution proceeds in rounds. In each round, the message routing layer invokes the execution layer once for executing (a subset of) the messages in the canister input queues. Depending on how much effort (CPU cycles) the execution of the messages of a round requires, a round ends with all messages in the queues being executed or the cycles limit of the round being reached and parts of the messages left to future rounds for execution. + +Each message execution can lead to memory pages of the canister’s state being modified (becoming “dirty” in operating systems terminology), new messages to other canisters on the same or different subnets being created, or a response to be generated in case of an ingress message. Changes to memory pages are tracked and corresponding pages flagged as “dirty” so that they can be processed when certifying the state. + +When a message execution leads to the generation of a new canister message targeted at a canister in the local subnet, this message can be queued up directly by execution in the input queue of the target canister and scheduled in the same round or an upcoming round. This message does not need to go through consensus since the generation and enqueuing of the new message is completely deterministic and thus happens in exactly the same way on all the nodes of the subnet. + +New messages targeted at other subnets are placed into the target cross-subnet queue (XNet queue) and are certified by the subnet at the end of the round as part of the per-round state certification. The receiving subnet can verify that the XNet messages are authenticated by the subnet by validating the signature with the originating subnet’s public key. + +The execution layer is designed at its core to execute multiple canisters concurrently on different CPU cores. This is possible because each canister has its own isolated state and canister communication is asynchronous. This form of concurrent execution within a subnet together with the capability of all ICP subnets executing canisters concurrently makes ICP scalable like a public cloud: ICP scales out by adding more subnets. + +## Deterministic time slicing + +Each execution round progresses alongside the creation of blockchain blocks, which happens roughly once every second. This restricts how much computation can be performed in a single round, with the current limit being around 2 billion instructions given the existing node hardware. + +However, the Internet Computer can handle longer tasks that need up to 20 billion instructions, and some special tasks, like code installation, can even go up to 200 billion instructions. This is achieved using _Deterministic Time Slicing_ (DTS). The idea is to pause a lengthy task at the end of one round and continue it in the next. As a result, a task can span multiple rounds without slowing down the block creation rate. DTS is automatic and transparent to smart contracts, so developers don’t need to write any special code to use it. + +## Memory handling + +Management of the canister bytecode and state (collectively memory) is one of the key responsibilities of the execution layer. The replicated state that can be held by a single subnet is not bounded by the available RAM in the node machines, but rather by the available SSD storage. Available RAM, however, impacts the performance of the subnet, particularly the access latency of memory pages. This depends a lot on the access patterns of the workload, however, much like in traditional computer systems. + +The node machines that comprise the IC are equipped with tens of terabytes of high-end SSD storage and over half a terabyte of RAM to be able to hold large amounts of replicated canister state and Wasm code and achieve good performance when accessing memory. The states obtained while executing canisters are certified (i.e., digitally signed) by the state management component of message routing. Certification of some parts of the states, including the ingress history and the messages that are sent to other subnetworks, are certified every round. The entire state of a subnetwork, including the state of all canisters hosted by that subnetwork, is certified once every (much longer) checkpointing interval. + +Memory pages representing canister state are persisted to SSD by the execution layer, without canister programmers needing to take care of this. This _orthogonal persistence_ frees the smart contract programmers from reading from and writing to storage explicitly as on other blockchains or as in traditional IT systems. This dramatically simplifies smart contract implementation and helps reduce the TCO of a dapp and go to market faster. Programmers can always have the full canister smart contract state on the heap or in stable memory. The difference between heap and stable memory is that the heap is cleared on updates of the canister code, while stable memory remains stable throughout updates, hence its name. Any state on the heap that is to be preserved through a canister update must be transferred to stable memory by a canister programmer before an update and restored from there after the update. Best practices are that large canister state be held directly in stable memory to avoid shuffling around large amounts of storage before and after each upgrade. This also avoids the risk of exceeding the cycles limit allowed in an upgrade operation. + +## Random number generation + +Many applications benefit from, or require, a secure random number generator. Yet, generating random numbers in the naïve way as part of execution trivially destroys determinism as every node would compute different randomness. ICP solves this problem by the execution layer having access to a decentralized pseudorandom number generator called the _random tape_. The random tape is built using chain-key cryptography. Every round, the subnetwork produces a fresh threshold BLS signature which, by its very nature, is unpredictable and uniformly distributed. This signature can then be used as seed in a cryptographic pseudorandom generator. This gives canister smart contracts access to a highly-efficient and secure random number source, which is another unique feature of ICP. + +## Cycles accounting + +The execution of a canister consumes resources of the Internet Computer, which are paid for with cycles. Each canister holds a local cycles account. Ensuring that the account holds sufficient cycles is the responsibility of its maintainer, which can be a developer, a group of developers or a decentralized autonomous organization (DAO) – users do never pay for sending messages to canisters on the IC. This resource charging model is known as the _reverse gas model_ and is a facilitator for mass adoption of the IC. + +Technically, the Wasm code running in a canister gets instrumented, when the Wasm bytecode is installed or updated on the IC, with code that counts the executed instructions for smart contract messages. This allows for deterministically computing the exact amount of cycles to be charged for a given message being executed. Using Wasm as bytecode format for canisters has helped greatly to reach determinism as Wasm itself is a format that is largely deterministic in its execution. It is crucial that the cycles charging be completely deterministic so that every node charges exactly the same amount of cycles for a given operation and that the replicated state machine properties of the subnet are maintained. + +The memory the canister uses in terms of both its Wasm code and canister state needs to be paid for with cycles as well. Much like in the public cloud, consumed storage is charged for per time unit. Compared to other blockchains, it is very inexpensive to store data on the IC. Furthermore, networking activities such as receiving ingress messages, sending XNet messages, and making HTTPS Outcalls to Web 2.0 servers are paid for in cycles by the canister. Prices for a given resource, e.g., executing Wasm instructions, scale with the replication factor of the subnet, i.e., the number of nodes that power the subnet. + +## Non-replicated message execution + +Non-replicated message execution, aka queries, are operations executed by a single node and return a response synchronously, much like a regular function invocation in an imperative programming language. The key difference to messages, which are also called update calls, is that queries cannot change the replicated state of the subnet, while update calls can. Queries are, as the name suggests, essentially read operations performed on one replica of the subnet, with the associated trust model of a compromised replica being able to return any arbitrary result of its choice. + +Analogous to update calls, queries are executed concurrently by multiple threads on a node. + +However, all the nodes of the subnet can concurrently execute different queries because queries are not executed in a replicated way. Query throughput of a subnet thus increases linearly with an increasing number of nodes in the subnet, while update call performance does not. + +Queries by themselves are similar to read operations on a local or cloud Ethereum node on the Ethereum blockchain. The response of any individual node should not be trusted. Whenever an information item to be read is critical, e.g., financial data based on which decisions are made, applications can either use update calls to obtain such information (as the response of an update call is certified by the subnet) or [certified variables](https://learn.internetcomputer.org/hc/en-us/articles/34214090576404), as both are verifiable with the subnet’s public key. + +## Additional Information + +[Usenix ATC article on execution environment](https://www.usenix.org/system/files/atc23-arutyunyan.pdf) + +[16 min video](https://www.youtube.com/watch?v=UHA7W-8My_I&list=PLuhDt1vhGcrfHG_rnRKsqZO1jL_Pd970h&index=16) + diff --git a/.migration/learn-hub/how-does-icp-work/blockchain-protocol/message-routing.md b/.migration/learn-hub/how-does-icp-work/blockchain-protocol/message-routing.md new file mode 100644 index 00000000..b9932d5a --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/blockchain-protocol/message-routing.md @@ -0,0 +1,85 @@ +--- +learn_hub_id: 34208241927316 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34208241927316-Message-Routing" +learn_hub_title: "Message Routing" +learn_hub_section: "Blockchain Protocol" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# Message Routing + +On the Internet Computer, users can interact with canister smart contracts by sending them messages, and canisters themselves can exchange messages with each other. For scalability, the Internet Computer is composed of many subnets and the [Network Nervous System](https://learn.internetcomputer.org/hc/en-us/articles/33692645961236) can add new subnets as required. The message routing component routes messages to and from canisters across all of the Internet Computer’s subnet blockchains and ensures that new subnets can be added seamlessly. + +Message routing is the lower of the two upper layers of the protocol stack. It implements functionality that is crucial for the operation of the IC. Its responsibilities can be roughly grouped as follows: + + * Induction of messages received in blocks from consensus; + * Invocation of the execution layer after successful induction; + * Routing of inter-canister messages resulting from execution within and between subnets; + * Certification of the state of the subnet. + + + +Although the layer derives its name from the functionality of routing messages, all the functionality listed above is equally important for the IC. Particularly, state certification is heavily used in chain-evolution technology to enable resumption of nodes. + +## Message processing + +Whenever consensus produces a finalized block of messages, that is, a block that has been considered correct (notarized) and finalized by at least two thirds of the subnet’s nodes, this block is handed over to message routing. This marks the transition between the lower and upper half of the protocol stack: The lower two layers are responsible for agreeing, in each round, among all nodes in the subnet on a block of messages to be executed. This block is then handed over to the upper layers for deterministic processing, which, more concretely, means passing it over to message routing which takes over the further orchestration of deterministic processing. + +Once message routing receives a block of messages – comprising both ingress messages submitted by users and XNet messages sent by canisters – the messages are extracted from the block and each message is placed into the input queue of its target canister. This process is called induction and all the queues are collectively referred to as induction pool. After induction, the execution layer – the topmost layer of the core IC protocol stack – is triggered to deterministically schedule messages in the induction pool for execution and to execute them. Message routing and execution modify the subnet state in a deterministic way, i.e., the state of the node is changed in the same way on every (honest) node of the subnet, which is crucial for achieving the replicated state machine properties of a subnet. The execution of a message can write to memory pages of the canister the message is executed on and change other metadata in the state. The execution of a message can also lead to the creation of new messages targeted at other canisters. Such a message can be either targeted at a canister on the local subnet or another subnet. In the former case, execution can directly place the new message into the input queue of the target canister. In the latter case, i.e., a new message that is targeted at another subnet, the message is placed into the so-called XNet stream for the target subnet where they can be picked up by block makers of the target subnets after the streams are certified. + +## Inter-canister messaging + +The execution of a canister message can lead to the creation of a new inter-canister message sent to a canister that can be either _local_ or _remote_ (on a different subnet). + +### Intra-subnet inter-canister messaging + +Intra-subnet, i.e., local, inter-canister messages originating from an executing canister method do not need to go through consensus as they deterministically result from messages that have been agreed by a previous consensus round and their further execution remains completely deterministic. This holds transitively, that is, inter-canister messages can create new inter-canister messages, resulting in a tree of messages. Local message invocations can be executed as long as the cycles limit for the round has not yet been exhausted. If the cycles limit is exhausted but there are still local messages left, they will be handled in the same way as intra-subnet messages. It is important to note that this local canister-to-canister messaging is not synchronous message invocation as one might be used to from EVM-based blockchains. Rather, local messages are put into the input queue of the target canister and are scheduled for execution asynchronously. This is the standard inter-canister messaging semantics known for the Internet Computer. + +### Inter-subnet inter-canister messaging + +Remote inter-canister messages, that is, messages sent to canisters on other subnets, are handled by routing them into the respective outgoing subnet stream for the target subnet. This routing happens at the end of the deterministic execution cycle, i.e., after execution hands back control to message routing. The XNet messages in the stream are certified (signed) using a Merkle-tree-style data representation at the end of the round by the subnet using [chain-key cryptography](https://learn.internetcomputer.org/hc/en-us/articles/34209486239252) as part of the per-round state certification. That is, every message in the outgoing stream is certified by the originating subnet. Replicas on the receiving subnet obtain the XNet messages during block making (part of consensus), validate the certificate, and include valid XNet messages in a consensus block. Thanks to using a Merkle-tree-like datastructure to encode and authenticate the XNet streams, parts of the streams can be consumed in a round by the receiving subnets and signatures can still be validated. + +## State certification + +The replicated state of a subnet comprises all the relevant information required for the operation of the subnet: + + * Items certified per round: + * * Responses to ingress messages + * Xnet messages to be sent to other subnets + * Canister metadata (module hashes, certified variables) + * Items certified per checkpoint: + * * The entire replicated state + + + +Certification is always done using chain-key cryptography, thus certifications are computed by the subnet as a whole in a decentralized manner. Such a certification can only exist if the majority of the subnet agrees on the state. + +State certification and secure XNet messaging enable, among others, the secure and transparent communication of canisters across subnet boundaries, a challenge that any blockchain that has multiple shards has to solve. It also provides crucial building blocks to allow users to read certified parts of the replicated state, e.g., responses to messages submitted by them. Furthermore, it allows nodes to join a subnet efficiently without replaying all blocks since genesis or fallen behind nodes to catch up to the most recent state of a subnet. All of this makes message routing an integral layer of the core IC protocol crucial for realizing some of the IC’s unique and distinguishing features. + +### Per-round certification + +At the end of a round, i.e., when all messages have been executed or the cycles limit for the round has been reached (to ensure rounds cannot take arbitrarily long), the message routing layer performs a certification of parts of the replicated state. The certificate covers the part of the state tree containing + + * Responses to ingress messages, + * Xnet messages to be sent to other subnets, and + * Canister metadata (module hashes, certified variables). + + + +The responses to ingress messages are often referred to as ingress history. The certified responses can be read and validated against the subnet’s public key by users as the response to their ingress messages. Each of the public keys of the individual subnets are, in turn, certified by the NNS using the same mechanism. This means that one can verify that certified responses indeed come from the IC only using the public key of the NNS. This way of validating responses to state-changing messages to a blockchain is extremely powerful when compared to other approaches seen in the field like reading the response from a transaction log. + +The per-round state certification ensures that any item of data relevant for interactions of users and subnets and between different subnets on the Internet Computer is authenticated. This particularly enables secure and verifiable inter-subnet communication, a crucial feature of the Internet Computer as well as an enabler of its scalability. + +### Per-checkpoint certification + +Wasm code changed through canister updates and written-to (“dirty”) memory pages of canisters and some other metadata in the replicated state do not get certified in every round. Instead they are only certified whenever a so-called checkpoint is created. A checkpoint is a copy of the replicated state that is persisted to disk. Such a checkpoint is written every multiple hundred rounds (or around 10 minutes), and for each checkpoint the subnet also computes a certification. This allows newly joining and fallen behind nodes to join in without re-executing all blocks. The state certification is done incrementally by incorporating the changes since the last checkpoint certification into the manifest of the previous checkpoint. The manifest can abstractly be viewed as a relatively flat Merkle tree and the incremental computation can be achieved by updating the leaves that have changed and propagating changes up the tree. Finally, the root hash of the manifest is signed by the subnet, thereby certifying the entire contents of the manifest. The signed result is called a catch-up package as it can be used by nodes to efficiently catch up to the point in time when the checkpoint was made. (Note that a catch-up package also contains other things required to resume, which are omitted here for the sake of simplicity.) The run time of this certification operation is linear in the number of memory pages that have changed and not the overall state size on the subnet. This is crucial as a subnet can hold terabytes of state in the future and a full recertification of multiple terabytes of replicated state would not be practical at every checkpoint interval. + +## Additional information + +[Wiki page describing the message routing layer in more detail](https://wiki.internetcomputer.org/wiki/IC_message_routing_layer) + +[8min video on Message Routing and Execution Layer](https://www.youtube.com/watch?v=dS3ny6ik1pA) + +[30min video on Message Routing](https://www.youtube.com/watch?v=YexfeByBXlo) + diff --git a/.migration/learn-hub/how-does-icp-work/blockchain-protocol/peer-to-peer.md b/.migration/learn-hub/how-does-icp-work/blockchain-protocol/peer-to-peer.md new file mode 100644 index 00000000..6ab0b3e8 --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/blockchain-protocol/peer-to-peer.md @@ -0,0 +1,35 @@ +--- +learn_hub_id: 34207428453140 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34207428453140-Peer-to-peer" +learn_hub_title: "Peer to peer" +learn_hub_section: "Blockchain Protocol" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# Peer to peer + +The peer-to-peer layer (P2P) of the Internet Computer, the bottommost layer in the protocol stack, is responsible for the secure and reliable communication between the nodes of a subnet. P2P thus serves as the foundation of the Internet Computer’s protocol stack by enabling nodes to broadcast artifacts, such as user inputs to canisters or protocol messages like block proposals. P2P's key property is the guaranteed message delivery to all required subnet nodes despite varying real-world network conditions and node failures. The P2P layer is used by the [consensus layer](hc/en-us/articles/01JJBWMDX90WR1GE5HHD0EAEPB), the next layer in the stack above it, to broadcast artifacts to the other nodes in the subnet. + +## Abortable broadcast + +At the heart of the P2P layer is the [Abortable Broadcast primitive](https://arxiv.org/abs/2410.22080), which is critical for efficient communication in a setting where nodes may fail or even act maliciously. With Abortable Broadcast, nodes abort the transmission of artifacts they no longer need explicitly. This allows Abortable Broadcast to provide strong delivery guarantees in the presence of network congestion, node or link failures, and backpressure. By preserving bandwidth and bounding the size of its data structures, Abortable Broadcast prevents overload from malicious nodes while ensuring the delivery of non-aborted artifacts from honest nodes. It resembles a publish–subscribe model, with the added ability to abort in-flight messages when needed. + +The P2P layer allows the filtering of incoming artifacts, accepting only necessary ones while discarding or delaying the admission of others. This ensures crucial artifacts are obtained more quickly than the others. This optimization is well-known from traditional networking and reduces the processing load of the layers above P2P. + +## QUIC Transport + +The Abortable Broadcast implementation relies on a transport component consisting of a custom RPC library built on top of [QUIC](https://en.wikipedia.org/wiki/QUIC). This library enables the efficient orchestration of multiple higher-level protocols on the same replica. Key features of the transport component include message multiplexing and caller pushback in the event that packet consumption is significantly slower than packet production. + +## Security + +To prevent Denial of Service (DoS) attacks, nodes connect only with other nodes in the same subnet, with membership managed by the [Network Nervous System (NNS)](https://learn.internetcomputer.org/hc/en-us/articles/01JH3CFANJAE1J5VAZ9NZ3ZQ9Z). The NNS registry canister acts as a service discovery mechanism for the P2P layer, enabling P2P to ensure encrypted and authenticated communication between nodes through TLS. + + + +## Additional information + +[Blogpost on P2P](https://medium.com/dfinity/a-new-p2p-layer-is-coming-to-the-internet-computer-772ac2a29484) +[Scientific article on Abortable Broadcast and its implementation for ICP](https://arxiv.org/abs/2410.22080) +[Video on Abortable Broadcast](https://www.youtube.com/watch?v=f8-G_C4li70&list=PLVEhhIklNtB4HjWkLhqNacvBDzA0Wt2H1) + diff --git a/.migration/learn-hub/how-does-icp-work/blockchain-protocol/state-synchronization.md b/.migration/learn-hub/how-does-icp-work/blockchain-protocol/state-synchronization.md new file mode 100644 index 00000000..a5e26c75 --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/blockchain-protocol/state-synchronization.md @@ -0,0 +1,35 @@ +--- +learn_hub_id: 34471579767572 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34471579767572-State-Synchronization" +learn_hub_title: "State Synchronization" +learn_hub_section: "Blockchain Protocol" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# State Synchronization + +To allow nodes to efficiently join a subnet that is running already or to catch up with the current state in case they have been offline for some time, the protocol supports state synchronization without processing all messages that have ever been executed. + +To this end, the protocol creates checkpoints of the entire subnet state periodically. The checkpoints are [certified](https://learn.internetcomputer.org/hc/en-us/articles/34208241927316) by the subnet through a signature on a Merkle-tree-like structure – the manifest – and made available as part of a catch-up package via the [Peer-to-Peer (P2P) layer](https://learn.internetcomputer.org/hc/en-us/articles/34207428453140). As the name already suggests, a catch-up package allows a node to catch up if it has fallen behind, e.g., because it was offline for some time. In addition, it allows new nodes to join, e.g., if the subnet is to grow in size or a node needs to be replaced because of a failure. + +## Nodes that join the subnet + +A new node can download the latest catch-up package and, after validating it, download the state corresponding to the checkpoint. Downloading the state requires the transfer of large amounts (gigabytes to terabytes) of data from the nodes’s peers. This is done efficiently and in parallel from all peers, by using a protocol that chunks the state and allows for different chunks to be downloaded from different peers. Every chunk is authenticated through the catch-up package individually through its hash. The tree-like structure of the manifest allows to verify each of these chunks individually relative to the root hash in the catch-up package. The chunking protocol is similar to the approach that Bittorrent uses for downloading large files from many peers. + +Once the full state corresponding to the checkpoint has been authentically downloaded, the node catches up to the current block height by processing all the blocks that have been generated in the subnet since the checkpoint. + +Without state synchronization, it becomes practically impossible for nodes to (re-)join in a busy subnet: they would need to replay all blocks from the very first block ever created on the subnet as it is done in other blockchains. Thanks to the state sync protocol allowing to download recent checkpoints, only few blocks need to be replayed as opposed to replaying every block from the start of the blockchain. This is important is that the IC is intended to have a high throughput of compute operations per time unit, much like cloud servers running their applications. Consider a subnet that has been running for multiple years with high CPU utilization. This would make it infeasible for a newly joining node to catch up with the subnet when trying to replay all blocks starting with the genesis block of the subnet as it would have to redo multiple CPU years worth of computation. Thus, state synchronization is a necessary feature for a blockchain that wants to operate successfully under real-world conditions where nodes do fail and need replacement. + +## Nodes that are behind + +If a node is not newly added, but only had a downtime or other performance degradation and needs to catch up, it may still have an older checkpoint. In this case, only the chunks different to the local checkpoint need to be downloaded, which can significantly reduce the volume of data transferred. + +The blockchain state is organized as a Merkle tree and can currently reach a size of up to a terabyte. The syncing node might already have most of the blockchain state and may not need to download everything. Therefore, the syncing node tries to download only the subtrees of the peers’ blockchain state that differ from its local state. The syncing node first requests for the children of the root of the blockchain state. The syncing node then recursively downloads the subtrees that differ from its local state. + +![The catching-up replica only syncs the parts of the replicated state that differ from the up-to-date replica](https://csojb-wiaaa-aaaal-qjftq-cai.icp0.io/_astro/state-sync.CGBHsPNA_Z1fxTja.webp) + +### Additional Information + +[20min video on State Synchronization](https://www.youtube.com/watch?v=WaNJINjGleg&list=PLuhDt1vhGcrfHG_rnRKsqZO1jL_Pd970h&index=14&t=2s) + diff --git a/.migration/learn-hub/how-does-icp-work/canister-smart-contracts/canister-control.md b/.migration/learn-hub/how-does-icp-work/canister-smart-contracts/canister-control.md new file mode 100644 index 00000000..21e4413e --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/canister-smart-contracts/canister-control.md @@ -0,0 +1,19 @@ +--- +learn_hub_id: 34573932107796 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34573932107796-Canister-Control" +learn_hub_title: "Canister Control" +learn_hub_section: "Canister Smart Contracts" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# Canister Control + +Canisters are managed by _controllers_ , which can be users or other canisters. Controllers are responsible for deploying, maintaining, and managing canisters. They can perform operations such as starting, stopping, and updating the canister, as well as adjusting canister parameters like the freezing threshold. The control structure can be centralized (e.g., when the controllers include a centralized entity), organizational (e.g. when the controller is a multi-signer wallet like [Orbit](https://orbitwallet.io/)), decentralized (e.g., when the controller is a DAO), or non-existent, resulting in an immutable smart contract. + +Controllers can update the code that runs on canisters by submitting a new Wasm module to replace the older one. By default, updating the Wasm module of a canister wipes out the Wasm memory, but the content of the stable memory remains unchanged. The Internet Computer offers an upgrade mechanism where three actions are executed atomically: serializing the Wasm memory of the canister and writing it to stable memory, installing the new Wasm code, and then deserializing the content of the stable memory. This allows for the Wasm heap memory to be kept even if the Wasm module changes. Of course, a canister may ensure at all times that the data that needs to be persisted across upgrades is stored in the stable memory, in which case the upgrade process is significantly simpler. + +## Additional Resources + +[25min video on creating, installing, upgrading, and managing canisters](https://www.youtube.com/watch?v=c5nv6vIG3OQ) + diff --git a/.migration/learn-hub/how-does-icp-work/canister-smart-contracts/canister-smart-contracts.md b/.migration/learn-hub/how-does-icp-work/canister-smart-contracts/canister-smart-contracts.md new file mode 100644 index 00000000..fd7491c1 --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/canister-smart-contracts/canister-smart-contracts.md @@ -0,0 +1,28 @@ +--- +learn_hub_id: 34210839162004 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34210839162004-Canister-Smart-Contracts" +learn_hub_title: "Canister Smart Contracts" +learn_hub_section: "Canister Smart Contracts" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# Canister Smart Contracts + +Smart contracts on the Internet Computer come in the form of canisters: computational units that bundle code and state. Canisters expose endpoints that can be called by other canisters and parties external to the IC, such as browsers or mobile apps. + +There are two types of endpoints in canisters: **updates** and **queries**. Updates modify the state of the canister, while queries read from the state without making changes. The code of a canister is a [WebAssembly (Wasm)](https://webassembly.org/) module. The state includes the usual Wasm memory heap, a special type of memory called stable memory and metainformation about the canister. + +The articles in this section describe + + * [Computation model:](https://learn.internetcomputer.org/hc/en-us/articles/34573860369172) how canister code is executed + * [Cycles](https://learn.internetcomputer.org/hc/en-us/articles/34573913497108): how resources consumed by canisters are charged + * [Canister control:](https://learn.internetcomputer.org/hc/en-us/articles/34573932107796) who can deploy and manage canisters + * [Principals](https://learn.internetcomputer.org/hc/en-us/articles/34250491785108): who can call canisters + + + +## Additional Resources + +[Canister Developer Docs](https://internetcomputer.org/docs/current/home) + diff --git a/.migration/learn-hub/how-does-icp-work/canister-smart-contracts/computational-model.md b/.migration/learn-hub/how-does-icp-work/canister-smart-contracts/computational-model.md new file mode 100644 index 00000000..625b67b8 --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/canister-smart-contracts/computational-model.md @@ -0,0 +1,15 @@ +--- +learn_hub_id: 34573860369172 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34573860369172-Computational-Model" +learn_hub_title: "Computational Model" +learn_hub_section: "Canister Smart Contracts" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# Computational Model + +Canisters behave much like actors from the [actor-based concurrency model](https://en.wikipedia.org/wiki/Actor_model). Their code is single-threaded and executed in complete isolation from other canisters. Canisters communicate with one another via asynchronous messaging. When processing a message, a canister can make changes to its state, send messages to other canisters, or even create other canisters. Unlike in the traditional actor model, communication is bidirectional. Canister messages are either requests or replies. For each request sent, the Internet Computer records a callback to be invoked when the callee sends back a response. If the Internet Computer determines that there is no way for the callee to respond, then it will produce a response instead, thereby ensuring that every request receives a reply. + +An important aspect of the canister-based model is how canisters handle errors during message processing. When a canister processes a request, it might send out other requests and wait for some of these replies before completing the original request. If an error occurs (the canister “traps”), the canister’s state reverts to what it was right after its last outgoing message. + diff --git a/.migration/learn-hub/how-does-icp-work/canister-smart-contracts/cycles-ledger.md b/.migration/learn-hub/how-does-icp-work/canister-smart-contracts/cycles-ledger.md new file mode 100644 index 00000000..12d6eea5 --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/canister-smart-contracts/cycles-ledger.md @@ -0,0 +1,252 @@ +--- +learn_hub_id: 45034096457748 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/45034096457748-Cycles-Ledger" +learn_hub_title: "Cycles Ledger" +learn_hub_section: "Canister Smart Contracts" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# Cycles Ledger + +The [cycles ledger](https://github.com/dfinity/cycles-ledger) is a canister that simplifies the management of cycles. + +Instead of creating one or more cycles wallets, which the developer controls and manages, the cycles ledger is a global ledger under the control of the NNS. That is, the burden of managing cycles wallets is lifted. + +The cycles ledger complies with the [IRCR-1](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-1/README.md), [ICRC-2](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-2/README.md), and [ICRC-3](https://github.com/dfinity/ICRC-1/tree/main/standards/ICRC-3) standards. As a result, the cycles ledger can also be integrated into applications and services that work with ICRC tokens. + +The cycles ledger (canister ID: `um5iw-rqaaa-aaaaq-qaaba-cai`) runs on the [uzr34 system subnet](https://dashboard.internetcomputer.org/subnet/uzr34-akd3s-xrdag-3ql62-ocgoh-ld2ao-tamcv-54e7j-krwgb-2gm4z-oqe). The corresponding index canister (canister ID: `ul4oc-4iaaa-aaaaq-qaabq-cai`) runs on the same subnet. + +## Architecture + +The following figure depicts the involved components and their interactions at a high level. + +![](https://learn.internetcomputer.org/hc/article_attachments/45034096454164) + +The cycles ledger interacts with the cycles minting canister of the NNS and user canisters to provide the cycles ledger-specific functionality, such as transferring cycles as well as creating canisters with cycles. Concretely, it provides the following functionality: + + 1. `deposit` credits the sent cycles to the given principal ID. + 2. `withdraw` sends the given number of cycles to the given canister. + 3. `withdraw_from` sends the given number of cycles to the given canister taking the funds from a given account. + 4. `create_canister` creates a new canister using cycles. + 5. `create_canister_from` creates a new canister using cycles taken from a given account. + + + +The cycles balance of an account on the cycles ledger can be increased in the following ways: + + 1. Calling `deposit` with cycles attached. + 2. Calling `notify_mint_cycles` on the cycles minting canister (CMC) after having deposited ICP in a user-specific subaccount of the CMC's account on the ICP ledger. + 3. Calling `icrc1_transfer` or `icrc2_transfer_from` on the cycles ledger to transfer cycles. + + + +Due to the tight interaction with the NNS, in particular the CMC, the cycles ledger is controlled by the [NNS root canister](https://dashboard.internetcomputer.org/canister/r7inp-6aaaa-aaaaa-aaabq-cai). + +It is important to point out that the cycles ledger does not provide the functionality to call arbitrary other canisters with cycles. The reason is that open call contexts may cause the cycles ledger to become stuck. + +If this functionality is needed, a developer can still spin up a cycles wallet - and load it with cycles using the cycles ledger. + +## Technical Details + +As mentioned above, the cycles ledger complies with the ICRC-1, ICRC-2, and ICRC-3 standards, providing all the necessary endpoints. All endpoints are listed in the [Candid file](https://github.com/dfinity/cycles-ledger/blob/main/cycles-ledger/cycles-ledger.did). + +Every endpoint that causes a state change (in particular, the creation of a block) on the cycles ledger incurs a fee of **100 million cycles**. + +This fee is also levied for the cycles ledger-specific endpoints discussed next. + +### Depositing Cycles to the Cycles Ledger + +The function `deposit` provides the means to accept cycles from other canisters. + + + type DepositArgs = record { + to : Account; + memo : opt vec nat8; + }; + + type DepositResult = record { balance : nat; block_index : BlockIndex }; + + deposit : (DepositArgs) -> (DepositResult); + + +The parameters are the account, i.e., a principal ID-subaccount pair, that should be credited for this transfer, and an optional memo. The memo can later on be retrieved when querying the transaction at the returned block index. + +The cycles are attached to the call itself. The cycles ledger checks that at least 100 million cycles are attached and then increases the balance of the account by the number of attached cycles minus the fee. If fewer than 100 million cycles are attached, an error is returned. + +### Withdrawing Cycles from the Cycles Ledger + +The user invokes the function `withdraw` to instruct the cycles ledger to send the given number of cycles to the specified canister. Alternatively, the function `withdraw_from` can be called to make use of an ICRC-2 approval to get the cycles from an account with a different principal ID. + + + type WithdrawArgs = record { + amount : nat; + from_subaccount : opt vec nat8; + to : principal; + created_at_time : opt nat64; + }; + type WithdrawError = variant { + GenericError : record { message : text; error_code : nat }; + TemporarilyUnavailable; + FailedToWithdraw : record { + fee_block : opt nat; + rejection_code : RejectionCode; + rejection_reason : text; + }; + Duplicate : record { duplicate_of : nat }; + BadFee : record { expected_fee : nat }; + InvalidReceiver : record { receiver : principal }; + CreatedInFuture : record { ledger_time : nat64 }; + TooOld; + InsufficientFunds : record { balance : nat }; + }; + type WithdrawFromArgs = record { + spender_subaccount : opt vec nat8; + from : Account; + to : principal; + amount : nat; + created_at_time : opt nat64; + }; + type WithdrawFromError = variant { + GenericError : record { message : text; error_code : nat }; + TemporarilyUnavailable; + FailedToWithdrawFrom : record { + withdraw_from_block : opt nat; + refund_block : opt nat; + approval_refund_block : opt nat; + rejection_code : RejectionCode; + rejection_reason : text; + }; + Duplicate : record { duplicate_of : BlockIndex }; + InvalidReceiver : record { receiver : principal }; + CreatedInFuture : record { ledger_time : nat64 }; + TooOld; + InsufficientFunds : record { balance : nat }; + InsufficientAllowance : record { allowance : nat }; + }; + + withdraw : (WithdrawArgs) -> (variant { Ok : BlockIndex; Err : WithdrawError }); + withdraw_from : (WithdrawFromArgs) -> (variant { Ok : BlockIndex; Err : WithdrawFromError }); + + +The function `withdraw` has four parameters: the number of cycles to be sent, an optional subaccount, the principal ID of the targeted canister, and an optional timestamp to indicate the time when the request was created. + +Note that the sum of the transferred amount and the fee of 100 million cycles is deducted from the user’s account derived from the user’s principal ID and the provided subaccount (if any). The memo in the recorded burn transaction is an encoding of the principal ID of the targeted canister, which makes it possible for the user to verify that the cycles were sent to the right canister when querying the corresponding transaction. + +The effective fee of burn blocks of 100 million cycles is different from other ledgers, particularly the ICP ledger and standard ICRC ledgers, where the effective fee of burn blocks is 0. This is because withdrawing cycles is fundamentally different from just burning tokens. + +The function `withdraw_from` is almost identical but it makes it possible to specify a `from` account, i.e., the cycles are meant to be withdrawn from an account with a different principal ID. If the spender's principal ID plus optional subaccount has not been approved to retrieve at least the specified amount, an `InsufficientAllowance` error is returned. + +### Creating Canisters Using the Cycles Ledger + +A canister can be created by calling the `create_canister` function, which has four parameters: + + * An optional subaccount from which the funds are taken. If no subaccount is provided, the default account (with the all-zero subaccount) is used. + * An optional timestamp to mark the time when the request has been created. + * The number of cycles to be used. + * The canister creation arguments for the cycles minting canister. + + + +There is also the function `create_canister_from`, which in addition requires a `from` account. + + + type CreateCanisterArgs = record { + from_subaccount : opt vec nat8; + created_at_time : opt nat64; + amount : nat; + creation_args : opt CmcCreateCanisterArgs; + }; + + type CreateCanisterFromArgs = record { + from : Account; + spender_subaccount : opt vec nat8; + created_at_time : opt nat64; + amount : nat; + creation_args : opt CmcCreateCanisterArgs; + }; + + type CmcCreateCanisterArgs = record { + settings : opt CanisterSettings; + subnet_selection : opt SubnetSelection; + }; + + type CanisterSettings = record { + controllers : opt vec principal; + compute_allocation : opt nat; + memory_allocation : opt nat; + freezing_threshold : opt nat; + reserved_cycles_limit : opt nat; + }; + + type SubnetSelection = variant { + Subnet : record { + subnet : principal; + }; + Filter : SubnetFilter; + }; + + type SubnetFilter = record { + subnet_type : opt text; + }; + + type CreateCanisterSuccess = record { + block_id : BlockIndex; + canister_id : principal; + }; + + type CreateCanisterError = variant { + InsufficientFunds : record { balance : nat }; + TooOld; + CreatedInFuture : record { ledger_time : nat64 }; + TemporarilyUnavailable; + Duplicate : record { + duplicate_of : nat; + canister_id : opt principal; + }; + FailedToCreate : record { + fee_block : opt BlockIndex; + refund_block : opt BlockIndex; + error : text; + }; + GenericError : record { message : text; error_code : nat }; + }; + + type CreateCanisterFromError = variant { + InsufficientFunds : record { balance : nat }; + InsufficientAllowance : record { allowance : nat }; + TooOld; + CreatedInFuture : record { ledger_time : nat64 }; + TemporarilyUnavailable; + Duplicate : record { + duplicate_of : nat; + canister_id : opt principal; + }; + FailedToCreateFrom : record { + create_from_block : opt BlockIndex; + refund_block : opt BlockIndex; + approval_refund_block : opt BlockIndex; + rejection_code : RejectionCode; + rejection_reason : text; + }; + GenericError : record { message : text; error_code : nat }; + }; + + create_canister : (CreateCanisterArgs) -> (variant { Ok : CreateCanisterSuccess; Err : CreateCanisterError }); + create_canister_from : (CreateCanisterFromArgs) -> (variant { Ok : CreateCanisterSuccess; Err : CreateCanisterFromError }); + + +It is possible to specify canister settings, which are applied to the newly created canister. If not specified, the caller is the controller of the canister and the other settings are set to default values. + +It is further possible to target a specific subnet by specifying the principal ID of a subnet in the `subnet_selection` field. Alternatively, a subnet type such as "fiduciary" may be specified. If the subnet selection is left empty, the new canister is installed on a random subnet. + +Since only the cycles minting canister has the power to create canisters on arbitrary subnets, the cycles ledger simply invokes the function `create_canister` on the cycles minting canister, attaching the user-specified number of cycles to the call. If a canister is created successfully, the cycles ledger returns both the block index of the transaction that burned the cycles on the cycles ledger and the principal ID of the newly created canister. + +## Additional Information + + * [Developer documentation](https://docs.internetcomputer.org/defi/token-ledgers/cycles-ledger) + * [Chain-key tokens](https://learn.internetcomputer.org/hc/en-us/articles/34211397080980) + * [Tokens & cycles](https://docs.internetcomputer.org/building-apps/getting-started/tokens-and-cycles) + + + diff --git a/.migration/learn-hub/how-does-icp-work/canister-smart-contracts/cycles.md b/.migration/learn-hub/how-does-icp-work/canister-smart-contracts/cycles.md new file mode 100644 index 00000000..bec2efec --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/canister-smart-contracts/cycles.md @@ -0,0 +1,22 @@ +--- +learn_hub_id: 34573913497108 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34573913497108-Cycles" +learn_hub_title: "Cycles" +learn_hub_section: "Canister Smart Contracts" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# Cycles + +As they execute, canisters use resources in the form of memory, computation, and network bandwidth, and may also use certain special APIs. On the Internet Computer, all of these are paid for using a unit called _cycles_. Each canister maintains a local cycle account from which cycles are deducted as execution proceeds. + + * **Memory usage:** Charging for memory usage is straightforward. The protocol keeps track of the memory used by the canister and regularly charges the canister’s balance. This charging happens at regular intervals but not every round. + * **Computation:** Charging for computation occurs at the time the computation is performed. The canisters are instrumented with code that allows the Internet Computer to count the number of instructions executed while processing a message. There is an upper bound on the number of instructions that can be executed during a round. If this limit is exceeded, execution is paused and continued in a subsequent round, but cycles for the computation performed during any round are charged at the end of that round. + * **Bandwidth:** Charging for bandwidth occurs when a canister receives an ingress message from a user or sends a message to another canister. The protocol calculates the number of cycles required for the outgoing call, which includes a fixed cost and a variable cost based on the payload size. Additionally, the protocol deducts the cost of sending a maximum-size reply from the callee, as the caller pays for the reply. If the actual reply size is smaller, the difference in cycles is refunded to the canister when the reply arrives. + * **API calls:** Calls for [reading data from the Bitcoin blockchain](https://learn.internetcomputer.org/hc/en-us/articles/34211154520084), [making HTTP calls](https://learn.internetcomputer.org/hc/en-us/articles/34211194553492) to web servers, or creating [chain-key signatures](https://learn.internetcomputer.org/hc/en-us/articles/34209497587732) require additional payment charged to the canister's cycles balance. + + + +Canisters have a freezing threshold to prevent sudden deletion when they run out of cycles. When a canister’s balance falls below this threshold, it stops processing new requests but continues handling replies. If a canister runs out of cycles completely, it is uninstalled, deleting its code and state but retaining the canister id so it cannot be accidentally reused. + diff --git a/.migration/learn-hub/how-does-icp-work/canister-smart-contracts/what-is-a-principal.md b/.migration/learn-hub/how-does-icp-work/canister-smart-contracts/what-is-a-principal.md new file mode 100644 index 00000000..902916dd --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/canister-smart-contracts/what-is-a-principal.md @@ -0,0 +1,23 @@ +--- +learn_hub_id: 34250491785108 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34250491785108-What-is-a-Principal" +learn_hub_title: "What is a Principal?" +learn_hub_section: "Canister Smart Contracts" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# What is a Principal? + +The concept of a principal appears at the level of canister smart contracts. In a nutshell, a principal identifies any entity that can call a canister. As both canisters and external users can call canisters, principals include both canister ids and self-authenticating identifiers derived from public keys of users. There are several classes of principals: + + 1. The [Internet Computer Management Canister](https://internetcomputer.org/docs/current/references/ic-interface-spec#ic-management-canister), which is a specific system API that can be called like a canister, uses the fixed principal _aaaaa-aa_. + 2. Canister ids: each canister on ICP is identified by its canister id. + 3. Self-authenticating ids: derived from public keys to identify users. + 4. Derived ids: a class which has been reserved but never implemented. + 5. The anonymous id, _2vxsx-fae:_ used as the identity of the caller for messages that are not signed. + + + +More details can be found in the [relevant section of the interface specification](https://internetcomputer.org/docs/current/references/ic-interface-spec#principal). + diff --git a/.migration/learn-hub/how-does-icp-work/chain-fusion/bitcoin-checker-canister.md b/.migration/learn-hub/how-does-icp-work/chain-fusion/bitcoin-checker-canister.md new file mode 100644 index 00000000..a3850e2e --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/chain-fusion/bitcoin-checker-canister.md @@ -0,0 +1,52 @@ +--- +learn_hub_id: 45033984570516 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/45033984570516-Bitcoin-Checker-Canister" +learn_hub_title: "Bitcoin Checker Canister" +learn_hub_section: "Chain Fusion" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# Bitcoin Checker Canister + +The [Bitcoin checker canister](https://dashboard.internetcomputer.org/canister/oltsj-fqaaa-aaaar-qal5q-cai) provides a useful service to canisters that make use of the [Bitcoin integration](https://learn.internetcomputer.org/hc/en-us/articles/34211154520084) of the Internet Computer: Given any Bitcoin address or transaction, the Bitcoin checker canister checks whether the address or transaction may be associated with illicit activities. + +The following figure shows a high-level overview of how the [ckBTC](https://learn.internetcomputer.org/hc/en-us/articles/44598021228564 "Chain-key Bitcoin") minter interacts with the Bitcoin checker canister. When a user deposits or wishes to withdraw bitcoin, the ckBTC minter sends a request to the Bitcoin checker canister, which in turn checks the involved Bitcoin addresses against the [Specially Designated Nationals (SDN) list](https://sanctionslist.ofac.treas.gov/Home/SdnList) of the [OFAC](https://ofac.treasury.gov/). If there is a hit, the check is considered `Failed`. When receiving the response `Failed`, the actions of the ckBTC minter depend on the type of request. + + * If the user deposited bitcoin, the ckBTC minter refuses to mint ckBTC and quarantines the received bitcoin instead. + * If the user attempted a Bitcoin withdrawal, the ckBTC returns an error and drops the request. + + + +![](https://learn.internetcomputer.org/hc/article_attachments/45033948399764) + +The canister ID of the Bitcoin checker canister is `oltsj-fqaaa-aaaar-qal5q-cai`. + +## Technical Details + +The Bitcoin checker canister stores a copy of the SDN list internally. The list can only be modified by upgrading the Bitcoin checker canister itself, which requires an NNS proposal as the NNS is the only controller of the Bitcoin checker canister. + +The Bitcoin checker canister offers a simple API to other canisters, which is discussed next. The candid file of the Bitcoin checker canister is available [here](https://github.com/dfinity/ic/blob/master/rs/bitcoin/checker/btc_checker_canister.did). + +### Checking Bitcoin Addresses + +The Bitcoin checker canister exposes the endpoint `check_address`, which takes a Bitcoin address in the form of a string as its sole parameter. It is then simply checked if the address is found on the SDN list. Since this is a simple lookup operation, no cycles are charged. + +### Checking Bitcoin Transactions + +The main endpoint to check a Bitcoin transaction is `check_transaction`, which takes the transaction ID as a `blob` as its sole parameter. Given such a transaction ID, the Bitcoin checker canister performs the following steps. + + 1. It uses an [HTTPS outcall](https://learn.internetcomputer.org/hc/en-us/articles/34211194553492) to obtain the (binary) transaction that corresponds to the given transaction ID. + 2. The received transaction is hashed and the result is compared against the transaction ID as they should match. + 3. If there is a match, it makes another HTTPS outcall for each input in the transaction as the inputs themselves are only references to previous transactions with an index that identifies the output that is consumed with the given input. + 4. For each received input transaction, the Bitcoin address is derived that corresponds to the output at the right index. + 5. Each address is looked up in the SDN list. If any address appears on the list, `Failed` is returned. Otherwise, the result is `Passed`. + + + +Since this lookup is expensive due to the (potentially many) HTTPS outcalls, at least **40 billion cycles** must be attached to the call. The actual cost is likely lower, and unused cycles are refunded. + +There is also the `check_transaction_str` endpoint, which is identical to `check_transaction` except for the fact that the transaction ID parameter must be provided as a string. + +Lastly, there is the `check_transaction_query` endpoint, which can be used to check the status of a previous call to `check_transaction` or `check_transaction_str` using a query call. Note that a call to this endpoint does not trigger any HTTPS outcalls, nor is it guaranteed that this endpoint will be maintained in a backwards-compatible manner. + diff --git a/.migration/learn-hub/how-does-icp-work/chain-fusion/bitcoin-integration.md b/.migration/learn-hub/how-does-icp-work/chain-fusion/bitcoin-integration.md new file mode 100644 index 00000000..fbd152dd --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/chain-fusion/bitcoin-integration.md @@ -0,0 +1,42 @@ +--- +learn_hub_id: 34211154520084 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34211154520084-Bitcoin-Integration" +learn_hub_title: "Bitcoin Integration" +learn_hub_section: "Chain Fusion" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# Bitcoin Integration + +The Bitcoin integration on the Internet Computer makes it possible to create Bitcoin smart contracts, that is, smart contracts in the form of canisters running on the Internet Computer that make use of real bitcoin. This integration is made possible through two key components. + +The first component is [chain-key signatures](https://learn.internetcomputer.org/hc/en-us/articles/34209497587732), which enables every canister to obtain [ECDSA](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm) and [Schnorr](https://en.wikipedia.org/wiki/Schnorr_signature) public keys and get signatures with respect to these keys in a secure manner. Since Bitcoin addresses are tied to ECDSA/Schnorr public keys, having ECDSA/Schnorr public keys on a canister means that the canister can derive its own Bitcoin addresses. Given that the canister can request signatures for any of its public keys using the [IC ECDSA](https://internetcomputer.org/docs/current/references/ic-interface-spec#ic-sign_with_ecdsa) and [IC Schnorr](https://internetcomputer.org/docs/references/ic-interface-spec#ic-sign_with_schnorr) interface, a canister can create Bitcoin transactions with valid signatures that move bitcoins from any of its Bitcoin addresses to any other address. + +The second component is the integration with Bitcoin at the network level. The Internet Computer replicas have the capability to instantiate a so-called _Bitcoin adapter_ , a process external to the replica process. The Bitcoin adapter uses the standard Bitcoin peer-to-peer protocol to get information about the Bitcoin blockchain. At the same time, the Bitcoin adapter communicates with the replica process to learn about the current Bitcoin state inside the replica. If the Bitcoin adapter learns that a Bitcoin block has not been made available to the replica yet, the Bitcoin adapter requests the next missing block from the connected Bitcoin nodes and forwards it to the replica upon receipt. + +Inside the replica, Bitcoin blocks are made available to the _Bitcoin canister_. The Bitcoin canister is a canister running on a system subnet whose purpose is to provide Bitcoin-related functionality to other canisters. In particular, it keeps information about the Bitcoin blockchain state and makes this information accessible to other canisters, such as the balance and unspent transaction outputs (UTXOs) of any Bitcoin address. Additionally, the fees of the most recent Bitcoin transactions that were put into blocks can be requested from the Bitcoin canister as well. The Bitcoin canister also offers the last piece of crucial functionality: It provides an endpoint for canisters to send Bitcoin transactions, which are forwarded to the Bitcoin adapter. The Bitcoin adapter in turn advertises the transactions to its connected Bitcoin peers and transfers the transaction upon request. + +The architecture of the Bitcoin integration is summarized in the following figure: + +![](https://learn.internetcomputer.org/hc/article_attachments/41161561347348) + +The figure depicts the main components: The Bitcoin adapter, which acts as a light-weight Bitcoin client that relays Bitcoin-related information between the replica process (on the left) and the Bitcoin network (on the right), and the Bitcoin canister, which interacts with the Bitcoin adapter to maintain the Bitcoin blockchain state and transfer Bitcoin transactions to the Bitcoin network. + +As mentioned before, the Bitcoin canister offers a low-level API to read from and write to the Bitcoin blockchain. Usage of the Bitcoin integration API is illustrated in the following sample flow: + +![](https://learn.internetcomputer.org/hc/article_attachments/43174436435476) + +In this figure, a canister first requests the balance of some Bitcoin address. This may be an address of the canister itself or any other address. Subsequently, the canister fetches the UTXOs of a Bitcoin address with the goal of crafting a Bitcoin transaction, in which case the Bitcoin address must be associated with a public key for which the canister can request signatures. Next, the canister calls the fee endpoint to get recent fees before building a Bitcoin transaction using some of the UTXOs as inputs. For each input, the IC ECDSA API is called to obtain the required signatures. Note that, if a [Taproot address](https://en.wikipedia.org/wiki/List_of_bitcoin_forks#Taproot) is used, the IC Schnorr API is used instead. In the last step, the transaction is submitted. + +## Additional information + +There are many sources providing additional information about the Bitcoin integration on the Internet Computer: + + * The [developer docs](https://internetcomputer.org/docs/build-on-btc/) are the right starting point for developers who wish to implement Bitcoin smart contracts on the Internet Computer. + * The [Bitcoin canister source code](https://github.com/dfinity/bitcoin-canister) can be found on GitHub, including its [interface specification](https://github.com/dfinity/bitcoin-canister/blob/master/INTERFACE_SPECIFICATION.md). + * A more detailed description of the integration, including the cycles cost of each endpoint, can be found [here](https://internetcomputer.org/docs/references/bitcoin-how-it-works). + * The [scientific paper](https://arxiv.org/pdf/2506.21327) on the Bitcoin integration is the right source for those who wish to learn about the technical details. + + + diff --git a/.migration/learn-hub/how-does-icp-work/chain-fusion/chain-fusion.md b/.migration/learn-hub/how-does-icp-work/chain-fusion/chain-fusion.md new file mode 100644 index 00000000..bbc22e42 --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/chain-fusion/chain-fusion.md @@ -0,0 +1,30 @@ +--- +learn_hub_id: 34329023770260 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34329023770260-Chain-Fusion" +learn_hub_title: "Chain Fusion" +learn_hub_section: "Chain Fusion" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# Chain Fusion + +Chain Fusion technology enables canisters to interact with multiple blockchain networks in a decentralized manner. This allows developers to build application using information from as well as holding and transferring assets on various blockchains, eliminating the need for trusted intermediaries like bridges. + +To make this possible, canisters must be able to + + * sign transactions + + * bi-directionally communicate with other chains + + + + +without a single point of trust. + +To achieve the former, [chain-key signatures](https://learn.internetcomputer.org/hc/en-us/articles/34209497587732) let canisters control addresses on several blockchain networks and sign transactions to transfer their assets to other addresses. + +For the latter, ICP nodes either exchange information with nodes from other blockchain networks natively (see [Bitcoin integration](https://learn.internetcomputer.org/hc/en-us/articles/34211154520084) for more details) or they use HTTPs outcalls to interact with JSON RPC providers for other networks ([Ethereum Integration](https://learn.internetcomputer.org/hc/en-us/articles/34575019947668)). + +Among other applications, these integrations have been used to bring digital token twins to ICP. These twin tokens, called [chain-key tokens](https://learn.internetcomputer.org/hc/en-us/articles/34211397080980), including ckBTC, ckETH, ckUSDC, and ckUSDT, are fully backed by their native tokens and controlled by a canister smart contract. This comes with high security guarantees and lets smart contracts on ICP to hold and transact these tokens at high speed and low cost. + diff --git a/.migration/learn-hub/how-does-icp-work/chain-fusion/chain-key-bitcoin.md b/.migration/learn-hub/how-does-icp-work/chain-fusion/chain-key-bitcoin.md new file mode 100644 index 00000000..a5e57a4a --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/chain-fusion/chain-key-bitcoin.md @@ -0,0 +1,371 @@ +--- +learn_hub_id: 44598021228564 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/44598021228564-Chain-key-Bitcoin" +learn_hub_title: "Chain-key Bitcoin" +learn_hub_section: "Chain Fusion" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# Chain-key Bitcoin + +Chain-key Bitcoin (ckBTC) is a token on the Internet Computer that is backed 1:1 by bitcoin (BTC) such that 1 ckBTC can always be redeemed for 1 BTC and vice versa. + +Unlike other tokens pegged to bitcoin, the ckBTC token does not rely on a third-party bridge for the conversion between BTC and ckBTC, making it a substantially more secure alternative to “wrapped” tokens. + +While chain-key bitcoin and regular bitcoin have the same value, the advantage of chain-key bitcoin is fast and cheap transfers: A transfer is finalized within a few seconds (a speed-up of roughly three orders of magnitude compared to transfers on the Bitcoin blockchain when waiting for 6 confirmations) and only costs 0.0000001 ckBTC (approximately two orders of magnitude lower than the Bitcoin miner fees). + +## Architecture + +The ckBTC functionality is built upon the [Bitcoin integration](https://learn.internetcomputer.org/hc/en-us/articles/34211154520084 "Bitcoin integration") of the Internet Computer, which makes it possible for canisters to receive, hold, and send bitcoin. + +There are two canisters, the ckBTC minter and ckBTC ledger, that together provide the ckBTC functionality. The ckBTC minter mints new ckBTC tokens whenever it receives bitcoin. Likewise, it burns ckBTC tokens whenever an owner of ckBTC tokens requests a withdrawal of bitcoin. The ckBTC minter waits for 6 confirmations before minting ckBTC and it burns ckBTC before it transfers BTC back to the users. The ckBTC ledger is [ICRC-2](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-2/README.md) and [ICRC-1](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-1/README.md) compliant, updating the balance accounts when ckBTC tokens are transferred and executing the mint and burn operations coming from the ckBTC minter. + +An overview of the basic architecture is depicted in the following figure. + +![](https://learn.internetcomputer.org/hc/article_attachments/44598021222548) + +The figure shows the main flow at a high level of abstraction: Users interact with the ckBTC minter and the ckBTC ledger to convert ckBTC/BTC and transfer ckBTC, respectively. The ckBTC minter interacts with the [Bitcoin canister](https://github.com/dfinity/bitcoin-canister) to retrieve information about the Bitcoin network state and send Bitcoin transactions. + +The ckBTC minter further interacts with the [Bitcoin checker canister](https://learn.internetcomputer.org/hc/en-us/articles/45033984570516) to run checks against Bitcoin addresses and transactions. These checks are meant to ensure that the ckBTC minter only uses "clean" bitcoins to back the issued ckBTC tokens and to prevent transferring bitcoins to Bitcoin addresses that are considered to be associated with illicit activity. As such, these checks provide an additional layer of security to ckBTC users. + +## Canisters + +Both the [ckBTC ledger](https://dashboard.internetcomputer.org/canister/mxzaz-hqaaa-aaaar-qaada-cai) and the [ckBTC minter](https://dashboard.internetcomputer.org/canister/mqygn-kiaaa-aaaar-qaadq-cai), running on the [pzp6e](https://dashboard.internetcomputer.org/subnet/pzp6e-ekpqk-3c5x7-2h6so-njoeq-mt45d-h3h6c-q3mxf-vpeq5-fk5o7-yae) subnet, are canisters that are controlled by the NNS (specifically, the [NNS root canister](https://dashboard.internetcomputer.org/canister/r7inp-6aaaa-aaaaa-aaabq-cai)). + +### ckBTC Ledger + +The ckBTC ledger, which complies with the [ICRC-2](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-2/README.md) and [ICRC-1](https://github.com/dfinity/ICRC-1/tree/main/standards/ICRC-1) standards, is responsible for keeping account balances and for transferring ckBTC between accounts. It provides the following functionality: + + * It enables the ckBTC minter to mint and burn ckBTC. + * It enables the transfer of ckBTC among users. + + + +As mentioned above, the transaction fee is 0.0000001 ckBTC, the equivalent of 10 satoshi. The transaction fee is sent to the account with the ckBTC minter as the owner and the subaccount `0xfee`. The **minting account** is the ckBTC minter’s default account; that is, the ckBTC minter’s principal ID and the all-zero subaccount. The initial supply of the ckBTC ledger is 0. ckBTC tokens are minted only when the ckBTC minter receives bitcoin, ensuring that the ckBTC supply managed by the ckBTC ledger is upper bounded by the amount of bitcoin held by the ckBTC minter. + +### ckBTC Minter + +The ckBTC minter is the canister responsible for managing deposited BTC and minting/burning ckBTC based on the amount of deposited BTC. It provides the following functionality: + + * For a certain principal ID and an optional subaccount, it returns a specific Bitcoin address under the ckBTC minter’s control. The ckBTC minter uses P2WPKH (“pay to witness public key hash”) addresses as defined in [BIP-141](https://en.bitcoin.it/wiki/BIP_0141). These addresses are rendered in the Bech32 format as defined in [BIP-173](https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki). While the ckBTC minter exclusively uses P2WPKH addresses internally, it supports all currently used address formats (P2PKH, P2SH, P2WPKH, P2TR) for retrievals. + * Users can inform the ckBTC minter about bitcoins that were sent to an address controlled by the ckBTC minter. If the balance has increased, the ckBTC minter mints ckBTC for the user associated with the Bitcoin address. + * Users can request to get bitcoins back. The ckBTC minter burns the same amount of ckBTC and transfers the corresponding BTC amount minus fees to the address provided by the user. + + + +The ckBTC minter canister has a few important configuration parameters including: + + * `retrieve_btc_min_amount`: This is the minimum ckBTC amount that can be burned and, correspondingly, the minimum BTC amount that can be withdrawn. The parameter is set to **0.0005 BTC** , or **50,000 satoshi**. + * `max_time_in_queue_nanos`: Any BTC retrieval request should be kept in a queue for at most this time. Caching requests rather than handling them right away has the advantage that multiple requests can be served in a single transaction, saving Bitcoin miner fees. The parameter is currently set to **5 minutes**. + * `min_confirmations`: The number of confirmations required for the ckBTC minter to accept a Bitcoin transaction. In particular, the ckBTC minter does not mint ckBTC before a transaction transferring BTC to a Bitcoin address managed by the ckBTC minter reaches this number of transactions. The parameter is currently set to **6**. + * `btc_checker_principal`: The principal ID of the Bitcoin checker canister, discussed below. + * `check_fee`: The fee that must be paid when depositing bitcoins to cover the cost in cycles for interacting with the Bitcoin checker canister. It is currently set to **100 satoshi**. + * `utxo_consolidation_threshold`: The minimum number of unspent transaction outputs (UTXOs) to trigger a consolidation. UTXO consolidation is discussed below. + * `max_num_inputs_in_transaction`: The maximum number of inputs that the ckBTC minter uses in a transaction, set to **1000**. + + + +The remaining parameters are self-explanatory and can be found in the [ckBTC minter Candid file](https://github.com/dfinity/ic/blob/master/rs/bitcoin/ckbtc/minter/ckbtc_minter.did). + +The following sections explain how the ckBTC minter manages its internal state. + +#### Addresses + +All Bitcoin addresses that are controlled by the ckBTC minter and have a positive balance are part of the ckBTC minter's state. If the balance of such an address reduces to zero, the address is removed from the state. It can be added back if the balance becomes positive again. + +#### Unspent Transaction Outputs + +Once a new unspent transaction output (UTXO) under the control of the ckBTC minter is discovered (using the `update_balance` function), it is stored internally in a set called `available_utxos` (defined [here](https://github.com/dfinity/ic/blob/2348b094d3d27616ee3f049d3048baa1da8d625a/rs/bitcoin/ckbtc/minter/src/state.rs#L305C14-L305C14) in the source code). + +All discovered UTXOs remain in this set until a Bitcoin transaction is created to spend one or more of them when retrieving bitcoins. When a transaction is created spending some UTXOs, these UTXOs are removed from the set `available_utxos` and inserted in the `used_utxos` field of the `SubmittedBtcTransaction` struct (defined [here](https://github.com/dfinity/ic/blob/70d19f16c17f8f42987a46d473ba27705927cdb7/rs/bitcoin/ckbtc/minter/src/state.rs#L87) in the source code), which is the internal representation of a Bitcoin transaction. + +A UTXO is removed from the ckBTC state when the `SubmittedBtcTransaction` struct that contains the UTXO is removed from the state. + +#### Transactions + +Every transaction that the ckBTC minter creates has an output that sends the ckBTC minter fee plus the transaction change back to its main BTC address (the P2WPKH address derived from its public key with an empty derivation path). + +A transaction can be removed from the cache if the transaction output that belongs to the ckBTC minter appears in the returned list of UTXOs of the ckBTC minter’s main BTC address with at least `min_confirmations=6` confirmations. + +The ckBTC minter may resubmit transactions, making use of Bitcoin’s request by fee (RBF) mechanism as defined in [BIP-125](https://github.com/bitcoin/bips/blob/master/bip-0125.mediawiki). In the case of ckBTC, a resubmission adds a transaction to the cache that spends exactly the same UTXOs as the transaction it replaces. The only difference is that the BTC amount sent to the user(s) is reduced in order to increase the fee. + +BIP-125 states that at most 100 transactions may be evicted from the mempool, i.e., the fee cannot be increased more than 100 times. Moreover, the fee must be increased at least by the minimum relay fee (see minrelaytxfee [here](https://en.bitcoin.it/wiki/Miner_fees#Relaying)) of 1 satoshi/vbyte. + +For example, if we assume a minimum increase of 200 satoshi (the minimum fee for a basic `segwit` transaction with one input and one output is 192 satoshi and the number per output is always lower than 200 if there are at least as many outputs as inputs), the minimum transfer amount should be at least 20,000 satoshi which equals 0.0002 BTC. When adding a base fee at a large fee rate of 100 satoshi/vbyte and assuming a virtual transaction size of 200 vbyte per output, we get a minimum transfer amount of 0.0004 BTC. Adding a security margin, we get the minimum retrieval amount of 0.0005 BTC that is used for the configuration parameter `retrieve_btc_min_amount`. The RBF flag is set on every transaction to ensure that they can be updated if necessary. + +Transactions with `min_confirmations=6` confirmations or more are considered _finalized_. The ckBTC minter stores information about finalized transactions forever. + +## Converting BTC to ckBTC + +In this section, the process to convert BTC to ckBTC is explained, making use of the ckBTC minter and ckBTC ledger endpoints. + +The first step is for the user to determine the Bitcoin address where the user is supposed to transfer bitcoin for the minting process by calling the `get_btc_address` endpoint. Next, the user transfers the desired BTC amount to this Bitcoin address. + +Once the transaction has `min_confirmations=6` confirmations, the user notifies the ckBTC minter to update the balance of the user's account on the ckBTC ledger by calling the `update_balance` function. The ckBTC minter uses the `bitcoin_get_utxos` endpoint of the Bitcoin canister to retrieve the current list of UTXOs for the Bitcoin address associated with the user. If there are new UTXOs, the ckBTC minter instructs the Bitcoin checker canister to perform a check of the newly discovered UTXOs and then, if the checks are successful, issues a minting transaction to the ckBTC ledger per UTXO, minting the value of the UTXO minus the Bitcoin checker fee into the user’s account. + +Formally, Let `R` denote the set of returned UTXOs. The following pseudo-code illustrates how the UTXOs are processed: + + + for utxo in new_utxos(R): // R = set of returned UTXOs + if utxo.value >= check_fee: + if utxo in checked_utxos: + state = checked_utxos.get(utxo) + else: + state = bitcoin_checker.check_transaction(utxo.transaction_id).await? + if state == passed: + checked_utxos.set(utxo, passed) + if state == passed: + ckbtc_ledger.mint(utxo.value-check_fee, recipient_account).await? + available_utxos.add(utxo) // Add to available UTXOs + checked_utxos.remove(utxo) // Remove from checked UTXOs after minting + else: + add_to_quarantine_list(utxo) + else: + add_to_ignore_list(utxo) + return response with UTXO statuses + + +The function `new_utxos` extracts the newly discovered UTXOs from `R`. Details about this function are provided further below. + +A UTXO is considered if its value is at least `check_fee`. UTXOs with a value lower than this fee are added to an ignore list. The additional state `checked_utxos` is maintained to remember that a UTXO was checked if the state is clean. Once the corresponding amount of ckBTC has been minted, this state can be removed again. If the UTXO does not pass the check, it is moved to a quarantine list instead. + +The function `new_utxos` filters out all UTXOs in the ignore list, the quarantine list, and the set `available_utxos`, as well as the UTXOs in any `used_utxos` list of `SubmittedBtcTransaction` structs. By contrast, the UTXOs in `checked_utxos` are not filtered. + +Note that the implementation uses the map `utxos_state_addresses` instead of the set `available_utxos`. For each address, the map contains all UTXOs, including UTXOs already used in outgoing transactions. It is therefore not necessary to parse all `SubmittedBtcTransaction` structs when using the map because UTXOs that have been used in transactions are already considered. + +UTXOs in the ignore list and quarantine list remain there indefinitely. Mechanisms to enable the owner to transfer the funds in these UTXOs back out may be added in the future. + +## Converting ckBTC to BTC + +The process to convert ckBTC to BTC consists of the following steps: + + 1. Transfer request: The user makes the desired ckBTC amount available to the ckBTC minter and requests a conversion. The destination Bitcoin address undergoes a check by the Bitcoin checker canister. If the check is successful, the request is accepted and put into a queue. + 2. Submission: The ckBTC minter periodically attempts to submit transactions for validated transfer requests. + 3. Finalization: The ckBTC minter periodically checks which transactions went through and finalizes these transactions. + 4. Resubmission: The ckBTC minter can resubmit a transaction that has been pending for at least one day with a higher fee. + + + +The individual parts are discussed in greater detail in the following sections. + +There are two flows to convert ckBTC to BTC. The newer, recommended flow is based on the ICRC-2 standard and requires the user to allow the ckBTC minter to withdraw the desired amount from a user-controlled account by calling `icrc2_approve` on the ckBTC ledger. Subsequently, the user can call the `retrieve_btc_with_approval` endpoint to inform the ckBTC minter about the withdrawal intent. In addition to specifying the withdrawal amount, the Bitcoin address where the withdrawn funds are to be sent must be specified as well. + +The ckBTC minter instructs the Bitcoin checker canister to perform a check against the targeted Bitcoin address using the `check_address` endpoint. If the check is successful, the ckBTC minter deducts the fee from the amount to be retrieved and puts the corresponding retrieval request into a queue and checks the status of the queue on a timer. + +If the oldest request has been in the queue for at least 10 minutes or at least 20 retrieval requests have been accumulated, the ckBTC minter creates a single Bitcoin transaction to serve up to 100 retrieval requests as follows: + + 1. It selects available UTXOs with a total sum of at least the sum in the retrieval requests. + 2. It constructs a Bitcoin transaction with the selected UTXOs as inputs and an output for each retrieval request plus an additional output for the ckBTC minter’s fee and the change. + 3. It uses the Bitcoin canister’s fee API to determine an appropriate fee for the transaction, using the median fee rate. + 4. It distributes the fee evenly among all outputs other than the output for the ckBTC minter’s fee plus change. + 5. For each input of the transaction, the ckBTC minter invokes the threshold ECDSA functionality (calling the `sign_with_ecdsa` function) to obtain the required signatures and puts them into the transaction. + 6. Lastly, it sends the Bitcoin transaction by invoking the `bitcoin_send_transaction` function of the Bitcoin integration API. + + + +The BTC retrieval process is depicted in the following figure. + +![](https://learn.internetcomputer.org/hc/article_attachments/44598026440340) + +Note that the amounts in the transfer to the withdrawal account and the retrieval request need not be the same. The `retrieve_btc_status_v2` endpoint can be used to query the current status of a retrieval request. + +The other, older mechanism, which is not based on ICRC-2, is summarized here briefly for the sake of completeness. Since the ckBTC minter can only burn ckBTC in an account that it controls, the first step is to transfer the amount to be retrieved to the owner-specific _withdrawal account_ under the ckBTC minter’s control. After the user has transferred the desired ckBTC amount to the withdrawal account, the user can call the `retrieve_btc` endpoint, specifying the withdrawal amount and the destination Bitcoin address. The ckBTC minter will then attempt to burn the specified ckBTC amount in the withdrawal account and, if the Bitcoin checker canister indicates that the destination address is clean, record the retrieval request, which is handled on a timer as before. + +The advantage of the ICRC-2-based flow is that the ckBTC amount stays with the user until a request is made to retrieve BTC, i.e., the risk that the funds get stuck in the withdrawal account is removed. + +Looking at the retrieval flow in more detail, the first step is to approve the ckBTC minter to withdraw the desired ckBTC amount from (one of) the user's accounts. To this end, the user calls icrc2_approve on the ckBTC ledger. The required parameters are `spender` and `amount` but there are also several optional parameters such as `from_subaccount`. + +Subsequently, the user can call `retrieve_btc_with_approval` on the ckBTC minter with parameters `address`, specifying the Bitcoin address that should receive the retrieved bitcoins, and `amount` (plus, optionally, `from_subaccount`), which causes the ckBTC minter to attempt to transfer the specified amount from the user's account to the minting account. As defined in ICRC-1, transferring tokens to the minting account constitutes a burn operation. Note that specifying an amount to be retrieved smaller than the minimum retrieval amount (`retrieve_btc_min_amount`) results in an immediate rejection of the request. + +If the burn operation fails, the retrieval process is aborted and an error is returned to the user. If the ckBTC tokens are burned successfully, the ckBTC minter instructs the Bitcoin checker canister to perform a check against the Bitcoin address where funds are supposed to be sent. If this check fails, a task is created internally to reimburse the burned amount to the user and an error is returned. Otherwise, the steps depend on the result: if the result is `Passed`, a task to transfer the amount minus the Bitcoin checker fee to the destination address is created and the user receives the signal that the request was accepted in the form of the block index of the burn operation on the ckBTC ledger. If the result is `Failed`, a task to reimburse the amount _minus the Bitcoin checker fee_ is created and a corresponding error message is returned to the user. + +The following pseudo-code illustrates how the `retrieve_btc_with_approval` endpoint works, given the parameters `amount` and `btc_address`. + + + assert(max(retrieve_btc_min_amount, check_fee) <= amount) + index = ckbtc_ledger.icrc2_transfer_from(user_account, minting_account, amount).await? + result = bitcoin_checker.check_address(btc_address).await + if result = error: + create_reimbursement(amount, index, user_account) + return Error("Failed to perform check") + else: + Ok(state) = result + if state == clean: + create_request(amount-check_fee, index, btc_address) + return index + else: + create_reimbursement(amount-check_fee, index, btc_address) + return Error("Tainted destination address") + + +For each recorded retrieval request, the ckBTC minter stores the following data: + + * `index`: The block index of the burn operation used to burn the ckBTC. Since the block index is unique, it is used as the request ID. + * `amount`: The total amount of tokens to retrieve. This amount must be at least the minimum retrieval amount as defined above. + * `btc_address`: The address where the bitcoins will be sent. + * `received_at`: The timestamp when the request was received (not shown in the pseudo-code). + + + +Pseudo-code for the older `retrieve_btc` endpoint whose retrieval flow is based on the concept of withdrawal accounts is shown here, also requiring the parameters `amount` and `btc_address`. + + + assert(amount >= max(retrieve_btc_min_amount, kyt_fee)) + assert(ckbtc_ledger.balance_of(withdrawal_account).await? >= amount) + state = bitcoin_checker.check_address(btc_address).await? + + if state == clean: + index = ckbtc_ledger.icrc1_transfer(withdrawal_account, minting_account, amount).await? + create_request(amount-check_fee, index, btc_address) + return index + else: + index = ckbtc_ledger.burn(check_fee, withdrawal_account).await? + return Error("Tainted destination address", index) + + +Note that while the `retrieve_btc` endpoint achieves the same result as `retrieve_btc_with_approval`, it works quite differently internally. For example, the check performed by the Bitcoin checker canister happens _before_ the ckBTC tokens are burned. Further note that if the check succeeds but the burn transaction fails (regardless of the result of the check), no fee is charged and the request is rejected, which implies that a subsequent request with the same parameters will result in another call to the Bitcoin checker canister. + +#### Submission + +The ckBTC minter uses the [timer functionality](https://internetcomputer.org/docs/current/developer-docs/backend/periodic-tasks) to initiate Bitcoin transfers. The following steps are carried out periodically: + + 1. Check if there is at least one request that is 10 minutes old or there are at least 20 requests in the pending-requests queue. If not, stop. + 2. Update the balance of the ckBTC minter’s main BTC address (the P2WPKH address derived from its public key with an empty derivation path) using the Bitcoin integration’s `bitcoin_get_utxos` function. Newly discovered UTXOs are added to the set `available_utxos`. + 3. Determine the total amount of bitcoins available, which is the sum of all bitcoins in `available_utxos`. + 4. Call the transfer function with the next batch of requests that can be served given the total amount of available bitcoins. A transaction is created, setting the transaction ID for each request in the batch, and sent to the Bitcoin network. + 5. Every request in this batch is then moved to the unconfirmed-transfers queue. + + + + +As evident from the steps outlined above, the transfer function can handle multiple requests at the same time. Handling multiple requests in a single transaction has several advantages over sending individual transactions: + + 1. Requests can possibly be served more quickly, especially if the ckBTC minter must wait for change to return to its main BTC address. + 2. As the fee for the non-input bytes is shared, the fee per request is slightly lower. + 3. Serving multiple requests at the same time can make denial-of-service attacks where an attacker attempts to drain the pool of usable UTXOs with many small requests harder. + + + +Given this set of requests, the next step is to select UTXOs for the transaction. + +Since UTXOs are always spent entirely, the difference between the sum of bitcoins in the spent UTXOs and the requested amount minus the Bitcoin miner fee must be transferred to a new UTXO as well. As mentioned before, the ckBTC minter uses its main BTC address to accumulate change. + +The transfer function performs the following steps: + + 1. Determine the target `t` of bitcoins that must be transferred out to handle all requests in the given batch. + 2. Select UTXOs for the transaction from the set `available_utxos`. + 3. Build the Bitcoin transaction and compute the Bitcoin miner fee based on current Bitcoin fees using the median fee rate of the return value of `bitcoin_get_current_fee_percentiles` and the (virtual) size of the transaction. The ckBTC minter fee is `146*in + 4*out + 26 satoshi`, where `in` and `out` denote the number of transaction inputs and outputs, respectively. Note that the fee is split evenly among the handled retrieval requests, deducting the same fraction of the total fee from each output that is not returning change and the ckBTC minter fee to the ckBTC minter. + 4. Sign every input using the threshold ECDSA interface. + 5. Submit the transaction using the `bitcoin_send_transaction` endpoint. + 6. Create a transaction record in the form of a `SubmittedBtcTransaction` struct. The UTXOs selected for this transaction are moved from the set `available_utxos` to the `used_utxos` field in the `SubmittedBtcTransaction` struct. + + + +The following UTXO selection algorithm, in pseudo-code, is used: + + + // t = target, A = available_utxos, k = # outputs + // Pre-condition: sum(A) >= t + fn select_utxos(t, A, k) + + fn greedy(t, A): + if t ≤ 0 or |A| = 0: return {} + m := max(A) // The UTXO with the largest value + if m.value < t: + return {m} ∪ greedy(t-m.value, A \ {m}) + else: + return min({a ∊ A | a.value ≥ t}) + + S := greedy(t, A) + A := A \ S + if |A| > UTXOS_COUNT_THRESHOLD: + a := min(A) + while a ≠ Ø and |S| < k: + S := S ∪ {a} + A := A \ {a} + return S + + +The algorithm has the following properties. If there are at most `UTXOS_COUNT_THRESHOLD` (currently set to 1,000) UTXOs, the algorithm greedily chooses the smallest number of UTXOs possible for the given target. If a single UTXO suffices, it uses the UTXO that results in the smallest change. + +If there are more than `UTXOS_COUNT_THRESHOLD` UTXOs, the UTXOs with the smallest values are added to the greedy solution until the number of inputs `k` matches the number of outputs that the transaction produces. Note that a transaction with `k` outputs handles `k-1` retrieval requests as there is always one output that returns the change and fee to the ckBTC minter. + +Once the transaction is sent, the requests are moved to the unconfirmed-transfers queue. + +#### Finalization + +The ckBTC minter uses the timer mechanism to determine the status of sent transactions as well. Specifically, the ckBTC minter periodically wakes up and checks the state of the requests in the unconfirmed-transfers queue. The ckBTC minter checks the UTXOs of its main account to determine which transactions have sufficiently many confirmations. Concretely, If an output returning the ckBTC fee and change is discovered, the corresponding transaction is considered final and is discarded. + +#### Resubmission + +It is possible that it takes a long time for a transaction to be included in a block. If fees increase significantly for some time, a transaction may even be stuck for a long time or dropped entirely. While the ckBTC minter uses a reasonable fee, it may still be necessary to issue a transaction again because burned ckBTC are never returned and UTXOs are never freed and are thus stuck when the transaction spending these UTXOs is stuck. + +The ckBTC minter resubmits a transaction that has not been confirmed within 24 hours. + +If a transaction is replaced, the new transaction uses the same UTXOs as the original transaction but the fee is increased. In other words, the transaction is identical except that the outputs for each user is reduced due to the increased fee. The new fee is the sum of the old transaction fee plus the size of the transaction (in `vbytes`) times the minimum relay fee of 1 satoshi/vbyte plus the ckBTC minter fee again because the ckBTC minter must acquire new signatures and send the new transaction to the Bitcoin canister. + +## Fees + +The ckBTC canisters run on an application subnet and must be self-sustainable. Rather than charging cycles for the endpoints, the ckBTC minter accumulates a surplus of BTC over time. Moreover, every ckBTC transaction increases the ckBTC balance of the ckBTC minter's fee account (i.e., its principal ID plus the `0xfee` subacccount) by **10 satoshi**. In the future, the ckBTC minter will mint ckBTC to get the total ckBTC supply and the BTC amount under the ckBTC minter's control to match. The ckBTC minter can then trade these extra ckBTC tokens for cycles to fuel both the ckBTC minter and ckBTC ledger. + +There is a growing surplus of BTC because it collects a fee when bitcoins are withdrawn. The formula for the ckBTC minter fee when calling `retrieve_btc` is determined as follows: + + * Under the conservative assumption that 1 BTC = 20,000 XDR, 1 billion cycles corresponds to 5 satoshi (because 1 trillion cycles corresponds to 1 XDR). + * The [cost](https://docs.internetcomputer.org/references/t-sigs-how-it-works/#api-fees) to obtain a single EDCSA signature is approximately 26.16 billion cycles on a 34-node subnet, whereas sending a Bitcoin transaction costs 5 billion cycles plus 20 million cycles per byte. + + + +Given these numbers, the cost to sign and send a transaction with `in` inputs and `out` outputs is + + + 26.16b*in + 5b + tx_size*20m cycles + < 26.16b*in + 5b + (149*in + 35*out + 10)*20m cycles + < 29.14b*in +0.7b*out + 5.2b cycles + < 146*in + 4*out + 26 satoshi. + + +The formula `146*in + 4*out + 26` is used to determine the ckBTC minter’s fee in satoshi. Since every transaction has at least two inputs and two outputs, the fee is at least 352 satoshi. + +This conservative pricing strategy is used to subsidize the other endpoints, which are free of charge. Moreover, while the `retrieve_btc_with_approval` endpoint is relatively expensive, the fee is typically still lower than the Bitcoin miner fee. + +As mentioned above, there is also a fee (namely, the Bitcoin checker fee of **100 satoshi**) when converting BTC to ckBTC (but not when converting ckBTC to BTC). + +## UTXO Consolidation + +As more and more bitcoins are deposited, the number of UTXOs that are managed by the ckBTC minter grows. Users tend to deposit bitcoins in small quantities, resulting in many UTXOs that lock small amounts. A consequence of the ckBTC minter managing numerous small UTXOs is that it may not be possible to withdraw a large amount in a single transaction because such a transaction would require spending an exceedingly large number of outputs, which would cause the transaction to be larger than the maximum size of a standard Bitcoin transaction of [100 KB](https://github.com/bitcoin/bitcoin/blob/3c098a8aa0780009c11b66b1a5d488a928629ebf/src/policy/policy.h#L24). In other words, large withdrawals may take longer as they might have to be split up into multiple smaller withdrawals, leading to a poor user experience. + +In order to mitigate the risk of failed withdrawal requests, the ckBTC miner creates _UTXO consolidation transactions:_ As long as the ckBTC minter has more than 10,000 UTXOs, it periodically creates transactions that spend the 1000 smallest outputs that it possesses, creating 2 new outputs each locking half of the sum of the bitcoins in the inputs minus the network fee. Initially, a consolidation transaction is created once per day, and the frequency is later reduced to once per week. 1000 inputs are used as it is large enough a number to reduce the total number of managed UTXOs quickly but small enough to generate standard Bitcoin transactions. It is a technical detail why 2 outputs are created as opposed to a single one: More of the existing code can be reused for consolidation transactions as every other transaction created by the ckBTC minter has at least 2 outputs, one for the user requesting a withdrawal and one for the change that goes back to the ckBTC minter. + +In contrast to transactions triggered by withdrawal requests, the ckBTC minter triggers UTXO consolidation transactions and therefore must pay for them itself. The ckBTC minter uses the funds accumulated in its fee collector account, i.e., its `0xfee` subaccount. Since the ckBTC minter is using its own funds, it is still always guaranteed that 1 ckBTC is backed by (at least) 1 BTC. + +## ckBTC Minter API + +The ckBTC minter provides the following endpoints: + + * `get_btc_address`: Returns a specific Bitcoin address that the caller can use to obtain ckBTC by sending BTC to this address. + * `get_known_utxos` (query): Returns the UTXOs associated with the given account (principal ID-subaccount pair) that the ckBTC minter knows. + * `update_balance`: Instructs the ckBTC minter to check the balance of a Bitcoin address and mint ckBTC into the account of the owner. + * `estimate_withdrawal_fee`: Returns a current estimate for the fee to be paid when retrieving a certain BTC amount. + * `get_deposit_fee` (query): Returns the fee charged when minting ckBTC. This fee currently corresponds to `check_fee`. + * `get_withdrawal_account`: Returns a specific ckBTC account where the owner must transfer ckBTC before being able to retrieve BTC. + * `retrieve_btc_with_approval`: Instructs the ckBTC minter to burn a certain ckBTC amount and send the corresponding BTC amount, minus fees, to a provided Bitcoin address. + * `retrieve_btc`: Serves the same purpose as `retrieve_btc_with_approval` but requires the user to first deposit ckBTC in a specific subaccount of the ckBTC minter. + * `retrieve_btc_status_v2` (query): Returns the status of a previous `retrieve_btc` or `retrieve_btc_with_approval` call. + * `retrieve_btc_status_v2_by_account` (query): Provides the status of all recent `retrieve_btc` or `retrieve_btc_with_approval` calls associated with the provided account. + * `retrieve_btc_status` (query): Serves the same purpose as `retrieve_btc_status_v2` but returns less status information. This endpoint is considered _deprecated_. + * `get_minter_info` (query): Returns information about the ckBTC minter itself. + * `get_canister_status`: Returns canister status information. + * `get_events` (query): Returns a set of events for debugging purposes. + + + +## Additional information + + * [Bitcoin integration](https://learn.internetcomputer.org/hc/en-us/articles/34211154520084) + * [ckBTC developer documentation](https://docs.internetcomputer.org/defi/chain-key-tokens/ckbtc/overview) + + + +#### + diff --git a/.migration/learn-hub/how-does-icp-work/chain-fusion/chain-key-tokens.md b/.migration/learn-hub/how-does-icp-work/chain-fusion/chain-key-tokens.md new file mode 100644 index 00000000..ebb96301 --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/chain-fusion/chain-key-tokens.md @@ -0,0 +1,69 @@ +--- +learn_hub_id: 34211397080980 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34211397080980-Chain-Key-Tokens" +learn_hub_title: "Chain-Key Tokens" +learn_hub_section: "Chain Fusion" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# Chain-Key Tokens + +One important way to extend the utility of a token is to bring it from one blockchain to another one. In traditional blockchain architectures, this is mostly accomplished through wrapping. More decentralized (and secure) alternatives to wrapping exist and can replace it: Meet [chain-key cryptography](https://learn.internetcomputer.org/hc/en-us/articles/34209486239252) and chain-key tokens! + +A wrapped token represents an underlying asset, which is typically native on a different blockchain than the wrapped token. For example, a wrapped Bitcoin token represents real bitcoin but is a different token available on a different chain, for example, on the Ethereum blockchain. Traditional wrapping always involves intermediaries that need to be trusted. + +A more secure alternative to wrapping tokens is to use advanced threshold cryptography to obtain chain-key tokens. As an example, chain-key Bitcoin (ckBTC), the first major chain-key token on ICP, is 1:1 backed with real bitcoin held 100% on chain by a smart contract. It can be considered a Bitcoin _twin_ on the Internet Computer that features low transaction fees and latency and high throughput, similar in its properties to a Bitcoin Layer 2. + +## Traditional wrapped tokens + +In traditional blockchain architectures, token wrapping involves an off-chain trusted intermediary and a token ledger smart contract. A user who wants to have a specific token, say a wrapped Bitcoin token, sends tokens of the underlying asset, such as bitcoin, to the intermediary. The intermediary, once it has confirmed the transfer of the underlying token on the token’s native blockchain, keeps the received tokens in custody and instructs the token ledger to create, or mint, the same amount of wrapped tokens that it has received of the underlying token. Minting increases the supply of the wrapped token. The newly minted wrapped tokens can then be used on the blockchain where the wrapped token was minted. + +If a user wants to redeem wrapped tokens for the underlying asset, this again involves the intermediary: The user sends the wrapped token to an address controlled by the intermediary and makes an unwrap request. The intermediary removes the amount of received wrapped tokens from the wrapped token’s supply and returns the corresponding amount of underlying tokens to the user on the blockchain that natively hosts the underlying asset. + +Regular users can just use the wrapped tokens and normally need not bother with the wrapping and unwrapping themselves. Thus, wrapped tokens are convenient for most users and as easy to use as any native token on the same blockchain. + +This traditional off-chain approach of wrapping works well from a functional perspective, but has the major drawback of involving an intermediary whose integrity is crucial for the security of the wrapping and unwrapping of the token. The main problem is that the intermediary can get compromised, for example, hacked, defrauded by an insider, or go out of business, which may result in a total loss of the underlying tokens in the worst case. Strategies such as multi-signature schemes with keys held by multiple parties to try to decentralize the intermediary can provide some mitigation but do not change the fact that wrapping is done by an off-chain entity or group of entities. In short, this architecture is not fully decentralized. There is another potential risk regarding the backing of the wrapped token: Ideally, a wrapped token is always backed 1:1 by the underlying token. In practice, however, the intermediary can use the tokens held in custody to create profit, for example, by using them for risky investments. In the worst case, if things go wrong, this can lead to the loss of tokens and a depegging of the wrapped token. + +Overall, this traditional way of implementing wrapped tokens is not desirable for reasons of security, risk, and its inherent centralized nature. + +## Chain-key tokens + +Chain-key tokens, such as ckBTC, are an advanced cryptography-based replacement for wrapped tokens offering stronger security and decentralization: With chain-key tokens, all operations are performed completely on chain by smart contracts, without involving any off-chain intermediaries. This eliminates the security risks and centralization concerns when using a traditional wrapping approach with an intermediary. Replacing wrapping with on-chain operations require a few key building blocks, in particular, a decentralized interaction between the two blockchains must be possible. + +Chain-key tokens implement the [ICRC-1 and ICRC-2 token standards](https://github.com/dfinity/ICRC-1/tree/main) so that they can be easily integrated by on-chain services, for example, wallets and DEXs. + +## Architecture + +The architecture of any chain-key token on ICP uses the following building blocks as its foundation: + + 1. Some form of decentralized integration with the blockchain that hosts the underlying token. This integration must allow canisters on ICP to query balances of addresses of the underlying token on its native chain as well as send transactions to the underlying chain. + 2. A chain-key implementation of the signature scheme used for signing transactions on the blockchain hosting the underlying asset must be available. For example, Bitcoin and Ethereum require ECDSA signatures. This functionality makes it possible to sign transactions for the chain of the underlying token fully on chain without involving an intermediary. + + + +ICP has been integrated with the Bitcoin network using a [direct integration at the network level](https://learn.internetcomputer.org/hc/en-us/articles/34209531762324). The integration with Ethereum uses multiple JSON-RPC providers accessed via [HTTPS outcalls](hc/en-us/articles/01JJC9PGK13GHY6C1S0D2TQ58Z) and helper smart contracts deployed on Ethereum. + +A chain-key token is typically implemented using a set of canisters: + + 1. A **minter** canister is responsible for creating and removing supply of the chain-key token based on the inflow and outflow of the underlying token. It keeps the underlying tokens in on-chain custody, ensuring a 1:1 backing of the chain-key token with the underlying asset. It must be possible for any user to verify that the total supply of the chain-key token does not exceed the minter’s balance of the underlying asset. + 2. A **ledger** canister keeps track of all the balances and handles all transfers of the chain-key token. As mentioned above, this canister must adhere to the ICRC-1 and ICRC-2 token standards. + 3. An **index** canister is used to look up ledger data such as the status of a transaction or the transaction history. + 4. Optionally, one or more **archive** canisters to hold a backup copy of past transactions. + + + +## Creating chain-key tokens from underlying tokens + +When a user wishes to obtain chain-key tokens for some underlying tokens, they send the underlying tokens to an address or contract on the origin blockchain controlled by the minter. Once the minter learns about the deposit, it will then instruct the ledger to mint the corresponding number of chain-key tokens for the user. + +The minter may learn about the deposit in different ways. The user may inform the minter about the deposit directly by calling an endpoint on the minter. This is the approach used for chain-key Bitcoin. The claim that tokens have been deposited to a certain address is verified by retrieving the current set of unspent outputs of that address. In the case of chain-key Ether (ckETH) and chain-key ERC-20 (ckERC20) tokens, deposits are made to a helper smart contract on Ethereum. The minter learns about deposits by periodically querying the event logs on the helper smart contract. + +## Redeeming chain-key tokens for underlying tokens + +A chain-key token can circulate on the ICP as long as needed. There is no need to frequently bring in and transfer out underlying tokens, and normally there is no need for most users to do this themselves. However, a user may want to redeem chain-key tokens they hold at some point to receive the underlying asset. To this end, the user must first approve the minter to withdraw at least the desired amount of chain-key tokens from the user’s account (using the approval mechanism defined in [ICRC-2](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-2/README.md)). Note that, depending on the chain-key token, more than one approval may be needed. For example, since ERC-20 transactions on Ethereum cost gas, a fee in ckETH must be paid to cover the gas fee in ETH. The user must therefore approve the ckETH minter to withdraw some of the user’s ckETH for the gas fee as well as the minter of the targeted ckERC20 token for the actual withdrawal. + +After the chain-key tokens have been burned, that is, removed from the supply, the minter creates a transaction to transfer the same amount of underlying tokens, possibly minus a fee, from its custody to the user-specified address. The minter uses the chain-key signing functionality available on the Internet Computer to sign the transaction in a decentralized and secure manner. For example, threshold ECDSA signing is used for chain-key tokens where the underlying token can be transferred using ECDSA signatures, which is the case, for example, for Bitcoin, ETH, and tokens on Ethereum. + +Lastly, the signed transaction must be transferred to the blockchain hosting the underying token. The direct integration with Bitcoin makes this step simple as the Internet Computer itself offers the functionality to transmit Bitcoin transactions. For EVM-based chains, this step can be accomplished by sending the transaction to JSON-RPC providers using HTTPS outcalls. + diff --git a/.migration/learn-hub/how-does-icp-work/chain-fusion/dogecoin-integration.md b/.migration/learn-hub/how-does-icp-work/chain-fusion/dogecoin-integration.md new file mode 100644 index 00000000..b7875de2 --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/chain-fusion/dogecoin-integration.md @@ -0,0 +1,19 @@ +--- +learn_hub_id: 46782835018516 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/46782835018516-Dogecoin-Integration" +learn_hub_title: "Dogecoin Integration" +learn_hub_section: "Chain Fusion" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# Dogecoin Integration + +The [Dogecoin](https://dogecoin.com/) integration on the Internet Computer makes it possible to create Dogecoin smart contracts, that is, smart contracts in the form of canisters running on the Internet Computer that make use of real dogecoin. + +This integration heavily reuses the [Bitcoin integration](https://learn.internetcomputer.org/hc/en-us/articles/34211154520084) since Dogecoin is a Bitcoin fork. Just like the Bitcoin integration, the Dogecoin integration consists of two main components. It also uses a dedicated process, called the _Dogecoin adapter_ , that interacts with the Dogecoin network directly. The current state of the Dogecoin blockchain is maintained in the [Dogecoin canister](https://github.com/dfinity/dogecoin-canister), which also manages all communication with the Dogecoin adapter. The high-level architecture is depicted in the following diagram. + +![](https://learn.internetcomputer.org/hc/article_attachments/46782851378068) + +More information including technical details can be found on the [Bitcoin integration](https://learn.internetcomputer.org/hc/en-us/articles/34211154520084) page. Information on how to get started with the Dogecoin integration can be found [here](https://dfinity.github.io/dogecoin-canister/). + diff --git a/.migration/learn-hub/how-does-icp-work/chain-fusion/ethereum-integration.md b/.migration/learn-hub/how-does-icp-work/chain-fusion/ethereum-integration.md new file mode 100644 index 00000000..44def676 --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/chain-fusion/ethereum-integration.md @@ -0,0 +1,33 @@ +--- +learn_hub_id: 34575019947668 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34575019947668-Ethereum-Integration" +learn_hub_title: "Ethereum Integration" +learn_hub_section: "Chain Fusion" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# Ethereum Integration + +Canister smart contracts on ICP can directly interact with the Ethereum network and other networks that are using the Ethereum Virtual Machine (EVM), such as Polygon and Avalanche. This integration is possible thanks to ICP's HTTPS outcalls and chain-key signatures, which allow Ethereum state to be queried and Ethereum transactions to be signed and submitted by canisters. + + * [HTTPS outcalls:](https://learn.internetcomputer.org/hc/en-us/articles/34211194553492) To query information from Ethereum and other EVM networks, HTTPS outcalls are used. HTTPS outcalls can obtain information from external sources. In this integration, they're used to obtain data from JSON-RPC services by querying Ethereum's transactions, addresses, and block information. To facilitate JSON-RPC calls, the [EVM RPC canister](https://learn.internetcomputer.org/hc/en-us/articles/45550731488916) provides an API endpoint that canisters can use. + + * [Chain-key signatures for ECDSA:](https://learn.internetcomputer.org/hc/en-us/articles/34209497587732) A canister can have an Ethereum address and sign transactions for that address in a secure and decentralized way using chain-key cryptography. This allows canisters to hold Ethereum natively. Messages sent by the smart contract can be signed in this way, enabling calling any smart contract on Ethereum from the canister. + + + +The main components are depicted in the following figure. + +### ![](https://learn.internetcomputer.org/hc/article_attachments/34575033443348) + +This functionality also forms the basis for EVM-based [chain-key tokens](https://learn.internetcomputer.org/hc/en-us/articles/34211397080980), like ckETH, ckUSDC, and many more. + +## Additional Resources + +[Blog article](https://medium.com/dfinity/icp-ethereum-how-icps-evm-rpc-canister-connects-the-networks-b57909efecf6) + +[Developer docs on EVM RPC canister](https://internetcomputer.org/docs/current/developer-docs/multi-chain/ethereum/evm-rpc/overview) + +<https://github.com/dfinity/evm-rpc-canister> + diff --git a/.migration/learn-hub/how-does-icp-work/chain-fusion/evm-rpc-canister.md b/.migration/learn-hub/how-does-icp-work/chain-fusion/evm-rpc-canister.md new file mode 100644 index 00000000..5465939d --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/chain-fusion/evm-rpc-canister.md @@ -0,0 +1,31 @@ +--- +learn_hub_id: 45550731488916 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/45550731488916-EVM-RPC-Canister" +learn_hub_title: "EVM RPC Canister" +learn_hub_section: "Chain Fusion" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# EVM RPC Canister + +The [EVM RPC Canister](https://github.com/internet-computer-protocol/evm-rpc-canister) is a canister that enables the communication between canisters on the Internet Computer and smart contracts on Ethereum and other EVM (Ethereum Virtual Machine) blockchains. + +Canisters can send requests to the EVM RPC Canister, which forwards the request to multiple JSON-RPC services using [HTTPS outcalls](https://learn.internetcomputer.org/hc/en-us/articles/34211194553492) and returns a response to the canister that sent the request. As such, the EVM RPC canister acts as a gateway for canisters to communicate with and query information from EVM-compatible chains. It provides endpoints that ICP developers can use to interact with Ethereum smart contracts and ensures that the responses received from the Ethereum network are secure and immediately useful within a canister. + +## Architecture + +The following figure depicts the involved components and their interactions at a high level. + +![](https://learn.internetcomputer.org/hc/article_attachments/45550731486996) + +The EVM RPC Canister accepts requests from canisters and interacts with JSON-RPC providers via HTTPS outcalls to obtain data from and submit data to Ethereum or other EVM-based blockchains. Multiple JSON-RPC providers are queried to ensure that the response does not come from a single centralized party: The HTTPs outcalls mechanism guarantees that at least 2/3 of the subnet's nodes agree on the response obtained from the server. Once the response is validated, it is sent to the canister that originated the request. + +For Candid-RPC methods such as `eth_getTransactionReceipt`, the EVM RPC canister sends the same request to at least three different RPC providers by default and compares the results. If there are discrepancies, the caller receives a set of inconsistent results to handle them in a way that makes sense for the use case. Instead of relying on the default, the caller can specify the total number of providers to be queried or even list the concrete providers of choice. Moreover, the caller can also set a minimum number of providers that must return the same (non-error) result. Currently, the following JSON-RPC providers are supported: [CloudFlare](https://www.cloudflare.com/), [Alchemy](https://www.alchemy.com/), [Ankr](https://www.ankr.com/), and [BlockPI](https://blockpi.io/). + +Beyond the Ethereum blockchain, this canister also has partial support for [Polygon](https://polygon.technology/), [Avalanche](https://www.avax.network/), and other popular EVM networks. + +The EVM RPC is controlled by the [Network Nervous System DAO](https://learn.internetcomputer.org/hc/en-us/articles/33692645961236), i.e., its functionality cannot be changed by a single entity. Together, these mechanisms ensure that no trust in additional parties (bridges or oracles) are necessary for the caller canister to send transactions and to condition executions on Ethereum state. + +Detailed information about the available endpoints and code samples can be found in the [developer docs](https://internetcomputer.org/docs/current/developer-docs/multi-chain/ethereum/evm-rpc/overview). + diff --git a/.migration/learn-hub/how-does-icp-work/chain-fusion/exchange-rate-canister.md b/.migration/learn-hub/how-does-icp-work/chain-fusion/exchange-rate-canister.md new file mode 100644 index 00000000..786e2871 --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/chain-fusion/exchange-rate-canister.md @@ -0,0 +1,81 @@ +--- +learn_hub_id: 45038506066452 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/45038506066452-Exchange-Rate-Canister" +learn_hub_title: "Exchange Rate Canister" +learn_hub_section: "Chain Fusion" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# Exchange Rate Canister + +The exchange rate canister (XRC) is a canister running on the [uzr34 system subnet](https://dashboard.internetcomputer.org/subnet/uzr34-akd3s-xrdag-3ql62-ocgoh-ld2ao-tamcv-54e7j-krwgb-2gm4z-oqe) that provides exchange rates to requesting canisters. A request comprises a base asset, a quote asset, and an optional (UNIX epoch) timestamp. The base and quote asset can be any combination of cryptocurrency and fiat currency assets, for example, BTC/ICP, ICP/USD, or USD/EUR. The timestamp parameter makes it possible to request historic rates. If no timestamp is provided in the request, the rate for the current time is returned. + +The XRC constitutes an on-chain oracle for exchange rates, which is particularly useful for DeFi applications but can further add value to any application that requires exchange rate information. + +The cycle minting canister of the [NNS](https://learn.internetcomputer.org/hc/en-us/articles/33692645961236) makes use of the XRC to obtain up-to-date ICP/XDR rates, which it requires for the conversion of ICP to cycles. + +## Usage + +The canister ID of the XRC is `uf6dk-hyaaa-aaaaq-qaaaq-cai`. A request of the form + + + type GetExchangeRateRequest = record { + base_asset: Asset; + quote_asset: Asset; + timestamp: opt nat64; + }; + + +can be sent to the XRC, which replies with the following result: + + + type GetExchangeRateResult = variant { + Ok: ExchangeRate; + Err: ExchangeRateError; + }; + + +An `Asset` is a record consisting of a symbol (for example, "ICP") and a class (either `Cryptocurrency` or `FiatCurrency`). The full candid file can be found [here](https://github.com/dfinity/exchange-rate-canister/blob/main/src/xrc/xrc.did). The optional timestamp in the request must be a UNIX timestamp in seconds when provided. If no timestamp is provided, the timestamp corresponding to the start of the current minute is used. Note that the granularity for requests is 1 minute, so seconds in a timestamp are ignored. + +It is further worth nothing that some exchanges may not always have exchange rates available for the current minute. Depending on the use case, it may be advisable to use the start of the previous minute to increase the chance to get a response based on rates collected from all queried exchanges. + +For every request, **1B cycles** need to be sent along, otherwise an `ExchangeRateError::NotEnoughCycles` error is returned. The actual cost of the call depends on two factors, the requested asset types and the state of the internal exchange rate cache, as follows: + + * If the request can be served from the cache, the actual cost is 20M cycles. + * If both assets are fiat currencies, the cost is 20M cycles as well. + * If one of the assets is a fiat currency or the cryptocurrency USDT, the cost is 260M cycles. + * If both assets are cryptocurrencies, the cost is 500M cycles. + + + +The remaining cycles are returned to the requesting canister. Note that at least 1M cycles are charged even in case of an error in order to mitigate the risk of a denial-of-service attack. + +## Technical Details + +The following figure depicts the work flow when receiving a request. + +[![](https://learn.internetcomputer.org/hc/article_attachments/45038716591124)](https://wiki.internetcomputer.org/wiki/File:XRC_Flow_Diagram.png) + +After receiving a request (step 1), the exchange rate for each cryptocurrency asset in the request with respect to the quote asset USDT is queried (for the timestamp in the request) from all supported exchanges using [HTTPS outcalls](https://learn.internetcomputer.org/hc/en-us/articles/34211194553492 "HTTPS outcalls") if this rate is not already cached (step 2). If a rate can be computed based on the query results received from the exchanges, it is inserted in the cache and returned to the requesting canister (step 3). The _median rate_ of all received rates is returned as it is not susceptible to outliers (unlike, for example, the average rate). + +If a cryptocurrency/cryptocurrency base-quote pair B/Q was requested, the B/Q rate is derived from the queried B/USDT and Q/USDT rates: First, the Q/USDT rates are inverted to get the USDT/Q rates. Second, the cross product of the B/USDT and USDT/Q rates is computed. Lastly, the median of these rates is returned as the B/Q rate. The motivation for using the cross product is that it contains every B/Q rate that can be derived from the given B/USDT and USDT/Q rates. The median rate is chosen as it is less susceptible to outliers than using, for example, the average. + +The XRC queries daily foreign exchange (forex) rates from forex data providers automatically on a fixed schedule. Furthermore, the XRC queries multiple stablecoin rates automatically to derive the USD/USDT rate as follows. Given SC1/USDT, SC2/USDT, ... rates for a set of stablecoins SC1, SC2, ..., it uses the median of these rates as the USD/USDT rate. This rule is based on the assumption that at least half of the stablecoins in the set keep their peg to USD at any time, in which case the median rate is an adequate estimate for the USD/USDT rate. Given the USD/USDT rate and the forex rates for fiat currencies other than USD, the requested rate can be computed for the case when one or more assets in the request are fiat currencies. + +Since more requests to exchanges are required for cryptocurrency/cryptocurrency pairs, more cycles are charged for such requests. + +As indicated in the figure above, the response to a successful request contains metadata in addition to the rate. The metadata contains the following fields: + + * `decimals`: The rate is returned as a scaled 64-bit integer. The scaling factor is 10 to the power of `decimals`. + * `base_asset_num_received_rates`: The number of received rates for the base asset from all queried exchanges. + * `base_asset_num_queried_sources`: The number of queried exchanges for the base asset. + * `quote_asset_num_received_rates`: The number of received rates for the quote asset from all queried exchanges. + * `quote_asset_num_queried_sources`: The number of queried exchanges for the quote asset. + * `standard_deviation`: The standard deviation of all received rates for this request. Note that the standard deviation is scaled by the same factor as the rate itself. + * `forex_timestamp`: The timestamp of the beginning of the day for which the forex rates were retrieved, if any. + + + +This additional information can be used to determine the trustworthiness of the received rate, for example by checking the number of rates that went into the computation of the rate and the standard deviation. If the XRC receives largely inconsistent rates from exchanges, it returns an `ExchangeRateError::InconsistentRatesReceived` itself. + diff --git a/.migration/learn-hub/how-does-icp-work/chain-fusion/sol-rpc-canister.md b/.migration/learn-hub/how-does-icp-work/chain-fusion/sol-rpc-canister.md new file mode 100644 index 00000000..f9ce81ba --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/chain-fusion/sol-rpc-canister.md @@ -0,0 +1,27 @@ +--- +learn_hub_id: 46782465439764 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/46782465439764-SOL-RPC-Canister" +learn_hub_title: "SOL RPC Canister" +learn_hub_section: "Chain Fusion" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# SOL RPC Canister + +The [SOL RPC canister](https://github.com/dfinity/sol-rpc-canister) is a canister that enables the communication between canisters on the Internet Computer and smart contracts on the [Solana](https://solana.com/) blockchains. + +Canisters can send requests to the SOL RPC Canister, which forwards the request to multiple JSON-RPC services using [HTTPS outcalls](https://learn.internetcomputer.org/hc/en-us/articles/34211194553492) and returns a response to the canister that sent the request. + +# Architecture + +The following figure depicts the involved components and their interactions at a high level. + +![](https://learn.internetcomputer.org/hc/article_attachments/46782497345940) + +The SOL RPC Canister accepts requests from canisters and interacts with JSON-RPC providers via HTTPS outcalls to obtain data from and submit data to Solana. Multiple JSON-RPC providers are queried to ensure that the response does not come from a single centralized party. At the same time, this mechanism guarantees that there is no single point of failure. Currently, the following JSON-RPC providers are supported: [Alchemy](https://www.alchemy.com/), [Ankr](https://www.ankr.com/), [Chainstack](https://chainstack.com/), [dRPC](https://drpc.org/), [Helius](https://www.helius.dev/), and [PublicNode](https://publicnode.com/). + +The SOL RPC is controlled by the [Network Nervous System DAO](https://learn.internetcomputer.org/hc/en-us/articles/33692645961236), i.e., its functionality cannot be changed by a single entity. Together, these mechanisms ensure that no trust in additional parties (bridges or oracles) are necessary for the caller canister to send transactions and to condition executions on Solana state. + +A [code sample](https://github.com/dfinity/sol-rpc-canister/tree/main/examples/basic_solana) showing how to use the SOL RPC canister can be found in the [SOL RPC canister repository](https://github.com/dfinity/sol-rpc-canister/). + diff --git a/.migration/learn-hub/how-does-icp-work/chain-key-cryptography/certified-communication.md b/.migration/learn-hub/how-does-icp-work/chain-key-cryptography/certified-communication.md new file mode 100644 index 00000000..0d1a6815 --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/chain-key-cryptography/certified-communication.md @@ -0,0 +1,19 @@ +--- +learn_hub_id: 34214090576404 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34214090576404-Certified-Communication" +learn_hub_title: "Certified Communication" +learn_hub_section: "Chain-Key Cryptography" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# Certified Communication + +Why do you trust data obtained from a blockchain? Well, all transactions and the subsequent changes to smart contract state made their way through the blockchain consensus protocol, which guarantees correctness as long as the underlying trust assumptions hold. But verifying correctness based on the consensus protocol is tedious: A client has to download and validate the blockchain data. Even in the case of more efficient mechanisms such as [Bitcoin's SPV](https://en.bitcoinwiki.org/wiki/Simplified_Payment_Verification) or [Ethereum's light clients](https://ethereum.org/en/developers/docs/nodes-and-clients/light-clients/), clients still have to perform significant amounts of work, such as downloading and validating block headers. This makes it difficult for applications with restricted uptime and resources, such as mobile or web applications, to operate on blockchain data without defaulting to centralized intermediaries. + +The Internet Computer is different: Using [chain-key cryptography](https://learn.internetcomputer.org/hc/en-us/articles/34209486239252), the Internet Computer can generate [digital signatures](https://en.wikipedia.org/wiki/Digital_signature) that can be validated with a single, permanent public key belonging to the Internet Computer. Unlike with traditional digital signatures, however, the private key material _never_ exists in a single place. It is always securely distributed between many different nodes, and valid signatures can only be generated when the majority of these nodes cooperates in a cryptographic protocol. A client application only has to embed the Internet Computer's public key, and can immediately validate all certified responses it receives from the Internet Computer, without putting any trust into the particular node it received the response from. + +The Internet Computer's certification feature is exposed to canisters through _certified variables_. From an application perspective, certified variables can be set during an update call to a canister, when the canister changes its state during a transaction that went through consensus. The certificate can then be read in a subsequent query call, so the canister can respond to a client's request in a trustworthy way but without incurring the additional delay of consensus. Certified variables also underlie many of the Internet Computer's advanced features such as [certified assets](https://learn.internetcomputer.org/hc/en-us/articles/34276431179412) and [Internet Identity](https://identity.ic0.app/). + +More technically, each canister can specify a single 32-byte value that will be certified by the subnet. Well-known concepts such as [Merkle trees](https://en.wikipedia.org/wiki/Merkle_tree) or, more generally, [authenticated data structures](https://cs.brown.edu/research/pubs/pdfs/2003/Tamassia-2003-ADS.pdf) can be used to extend the certification from this single 32-byte value to arbitrary amounts of data. Libraries such as [certified-map](https://github.com/dfinity/cdk-rs/tree/main/library/ic-certified-map) make the feature easily accessible for developers. + diff --git a/.migration/learn-hub/how-does-icp-work/chain-key-cryptography/chain-key-cryptography.md b/.migration/learn-hub/how-does-icp-work/chain-key-cryptography/chain-key-cryptography.md new file mode 100644 index 00000000..1c374705 --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/chain-key-cryptography/chain-key-cryptography.md @@ -0,0 +1,33 @@ +--- +learn_hub_id: 34209486239252 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34209486239252-Chain-Key-Cryptography" +learn_hub_title: "Chain-Key Cryptography" +learn_hub_section: "Chain-Key Cryptography" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# Chain-Key Cryptography + +_Chain-key cryptography_ enables subnets of the Internet Computer to jointly hold cryptographic keys, in a way that no small subset of potentially misbehaving nodes on the subnet can perform useful operations with the key, but the majority of honest nodes together can. Chain-key cryptography provides several major benefits to ICP: + + 1. Secure and efficient subnet-to-subnet communication enables ICP to scale horizontally, increasing the compute and memory capacity as more nodes are joining the Internet Computer. + 2. [Certified responses](https://learn.internetcomputer.org/hc/en-us/articles/34214090576404) enable clients to validate the information they receive from ICP nodes efficiently and without the need of keeping any blockchain state. + 3. Smart contracts have access to a source of unpredictable and unbiased randomness. + 4. [Chain-key signatures](https://learn.internetcomputer.org/hc/en-us/articles/34209497587732) enable canister smart contracts on ICP to hold assets and invoke smart contracts on other blockchain networks. + 5. [vetKeys](https://internetcomputer.org/docs/current/references/vetkeys-overview) enable dapps to encrypt data based on encryption keys controlled by canister smart contracts. + + + +## Digital Signatures + +A _digital signature scheme_ is a very traditional type of public-key cryptosystem, in which a secret key (held only by the signer) is used to generate a digital signature on a message, and a public key (available to everyone) may be used to efficiently verify a digital signature on a message. The basic security property achieved by such a scheme is that a valid signature on a message cannot be created without explicitly invoking the signing algorithm with the corresponding secret key. + +A _threshold signature scheme_ is a digital signature scheme where the secret signing key is never stored in one location (which would become a single point of failure). Rather, the secret key is effectively split up into _secret shares_ , and each secret share is stored on a different machine. To sign a message, these machines must agree to sign the message and coordinate with one another to generate a digital signature in a distributed fashion (importantly, without ever reconstructing the secret signing key in one location). + +## Sharing Cryptographic Keys among the Nodes of a Subnet + +While threshold signature schemes have been around for a long time, the Internet Computer is the first blockchain-based system to fully integrate this technology in the core of its design. Each subnet is associated with the public key of such a threshold signature scheme. + +More technically, Chain-Key Cryptography is the combination of two cryptographic protocols: The first is a _distributed key generation_ protocol in which nodes of a subnet can together generate shares of a cryptographic key. The protocol ensures that the actual cryptographic key never actually exists at any one place, it exists only _virtually_ , determined by the shares held by all nodes together. A variation of the same protocol is used to re-share the cryptographic key when, e.g. the membership of a subnet changes and new nodes participate in the protocol. The second protocol is the _threshold signature_ protocol, which the nodes evaluate together when a message has to be signed. + diff --git a/.migration/learn-hub/how-does-icp-work/chain-key-cryptography/chain-key-signatures.md b/.migration/learn-hub/how-does-icp-work/chain-key-cryptography/chain-key-signatures.md new file mode 100644 index 00000000..76b00be4 --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/chain-key-cryptography/chain-key-signatures.md @@ -0,0 +1,25 @@ +--- +learn_hub_id: 34209497587732 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34209497587732-Chain-Key-Signatures" +learn_hub_title: "Chain-Key Signatures" +learn_hub_section: "Chain-Key Cryptography" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# Chain-Key Signatures + +The main application of _chain-key signatures_ is to enable direct interoperability with other blockchains as part of [Chain Fusion](https://learn.internetcomputer.org/hc/en-us/articles/34329023770260). Using chain-key signatures, canister smart contracts obtain control over cryptographic keys: They have a public key, from which a blockchain address on another blockchain like Bitcoin or Ethereum can be derived, and they can sign transactions relative to that address. One major application of chain-key signatures is creating [chain-key tokens](https://learn.internetcomputer.org/hc/en-us/articles/34211397080980), which are twins of tokens from other blockchains that exist on ICP. Two major examples of these are ckBTC and ckETH, representations of BTC and ETH on the Internet Computer, in which a canister smart contract cryptographically controls the bitcoin and ether that backs the ckBTC and ckETH tokens 1:1. Indeed, using chain-key signatures is the strongest, most decentralized way of integrating blockchains as no additional trust assumptions besides that of the two blockchains are required. In particular, there are no additional parties that manage signature keys or their shares. + +A key component of chain-key signatures is threshold cryptography. The threshold signature scheme used to implement [certified communication](https://learn.internetcomputer.org/hc/en-us/articles/34214090576404) for ICP is based on BLS signatures. While BLS signatures have distinct advantages, they are not used on many other blockchains. In order to work with other blockchains, the Internet Computer must use threshold signatures that are compatible with the digital signature schemes of those other blockchains. By far the most commonly used signature scheme (including Bitcoin and Ethereum) is the [ECDSA signature scheme](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm). Because of this, _threshold ECDSA_ signatures have been the first ones to be supported on the IC. Subsequently, support for [Schnorr signatures](https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki) as used by Bitcoin has been added, enabling full use of Bitcoin features that depend on Taproot, such as [Ordinals](https://www.bitcoin.com/get-started/what-are-bitcoin-ordinals/). The recently added support for [EdDSA signatures](https://en.wikipedia.org/wiki/EdDSA) unlocks integration with blockchains like Solana, TON, or Cardano. + +## Threshold ECDSA + +Implementing a secure and efficient threshold signing protocol for ECDSA is much more challenging than for BLS signatures. While there has been a flurry of [research on threshold ECDSA in recent years](https://eprint.iacr.org/2020/1390), none of these protocols meet the demanding requirements of the Internet Computer: they all either assume a _synchronous network_ (meaning that the protocols will fail or become insecure if messages are unexpectedly delayed) or provide _no robustness_(meaning that the ability to produce signatures is completely lost if a _single_ node should crash) or _both_. Neither of these assumptions are acceptable on the IC: security and liveness must hold even in an _asynchronous network_ with many faulty nodes. + +The DFINITY R&D team has designed, analyzed, and implemented a new threshold ECDSA signing protocol that works over an _asynchronous network_ and is quite _robust_ (it will still produce signatures if up to a third of the nodes in a subnet are crashed or corrupt) while still delivering acceptable performance. This signing protocol has been published in two research papers that [describe the protocol in detail](https://eprint.iacr.org/2022/506) and [prove the key elements of its security](https://eprint.iacr.org/2021/1330). The NNS DAO decided to adopt threshold ECDSA on the Internet Computer and to roll it out, such that canister smart contracts are able to have an ECDSA public key. + +## Threshold Schnorr and EdDSA + +The Schnorr signature scheme, of which EdDSA is a variant, is more amenable to being adapted to a threshold protocol than the ECDSA signature scheme. Consequently, the threshold signing protocols for Schnorr and EdDSA implemented in ICP are simplified variants of the ECDSA signing protocol, and inherit the property of robustness in an asynchronous network. + diff --git a/.migration/learn-hub/how-does-icp-work/chain-key-cryptography/subnet-keys-and-subnet-signatures.md b/.migration/learn-hub/how-does-icp-work/chain-key-cryptography/subnet-keys-and-subnet-signatures.md new file mode 100644 index 00000000..4dbb9e8b --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/chain-key-cryptography/subnet-keys-and-subnet-signatures.md @@ -0,0 +1,32 @@ +--- +learn_hub_id: 34209540682644 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34209540682644-Subnet-Keys-and-Subnet-Signatures" +learn_hub_title: "Subnet Keys and Subnet Signatures" +learn_hub_section: "Chain-Key Cryptography" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# Subnet Keys and Subnet Signatures + +Each subnet on ICP manages cryptographic keys that are used in several parts of the protocol: + + * An unbiased random beacon determines the block maker in each consensus round. + * Messages to other subnets are signed and can be validated by the receiving subnet based on knowledge of only the public key of the sending subnet, which enables horizontal scalability of ICP. + * Client applications can validate information retrieved from the subnet using only the public key of the subnet, enabling these applications to be resource-efficient (even run as part of a standard website) and fully trustworthy. + * Each canister has access to an unbiased and unpredictable source of randomness. + + + +## Threshold BLS Signatures + +The threshold signature scheme implemented by the IC for the above-mentioned tasks is a threshold version of the well-known [BLS signature scheme](https://en.wikipedia.org/wiki/BLS_digital_signature). One reason for using the BLS signature scheme is that it is the only one that yields a threshold signing protocol that is very simple and efficient. Indeed, a machine holding a share of the secret signing key can very easily generate a share of a signature on a message, and these signature shares can be combined to form a BLS signature on a message – no further interaction between these machines is required. + +Another reason for using the BLS signature scheme is that signatures are _unique_ , meaning that for a given public key and message, there is only one valid signature on that message. This unique-signature property is essential for the application to generating unpredictable and unbiased pseudo-random numbers for smart contracts: after a smart contract requests a pseudo-random number (and not before!), a signature on a special message is generated, and this signature is passed through a hash function to derive a seed from which the required pseudo-random numbers are generated. By the security property of the signature scheme, neither this seed nor the derived pseudo-random numbers can be predicted or biased. + +## Distributed Key Generation + +While signing with threshold BLS is quite straightforward, designing a secure, decentralized protocol for generating and distribution the shares of the secret signing key – that is, a DKG, or Distributed Key Generation protocol – remains a challenge. While there has been quite a bit of research on DKG design, the vast majority of DKG protocols in the literature do not meet the demanding requirements of the Internet Computer, in that they either assume a _synchronous network_ (meaning that the protocols will fail or become insecure if messages are unexpectedly delayed) or provide _no robustness_ (meaning that the ability to produce signatures is completely lost if a _single_ node should crash) or _both_. Neither of these assumptions are acceptable on the IC: security and liveness must hold even an _asynchronous network_ with many faulty nodes. + +DFINITY has designed, analyzed, and implemented [a new DKG protocol](https://eprint.iacr.org/2021/339) that works over an _asynchronous network_ and is quite _robust_ (it will still succeed if up to a third of the nodes in a subnet are crashed or corrupt) while still delivering acceptable performance. In addition to generating a new key, this protocol can also be used to reshare an existing key. This functionality is essential to enable autonomous evolution of the IC topology as subnet membership changes over time. + diff --git a/.migration/learn-hub/how-does-icp-work/evolution-scaling/chain-evolution.md b/.migration/learn-hub/how-does-icp-work/evolution-scaling/chain-evolution.md new file mode 100644 index 00000000..450894a6 --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/evolution-scaling/chain-evolution.md @@ -0,0 +1,59 @@ +--- +learn_hub_id: 34210120121748 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34210120121748-Chain-Evolution" +learn_hub_title: "Chain Evolution" +learn_hub_section: "Evolution & Scaling" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# Chain Evolution + +The Internet Computer is governed by the [Network Nervous System (NNS)](https://learn.internetcomputer.org/hc/en-us/articles/33692645961236), its fully onchain governance system. One of the many duties of the NNS is to orchestrate upgrades of ICP to a new protocol version. Upgrading a blockchain protocol requires solutions to several challenging problems posed by the nature of decentralized systems including how to allow arbitrary changes to the protocol, preserve state of all canister smart contracts, minimize downtime, and roll out upgrades autonomously. + +Any software needs to be updated on a regular basis to stay competitive in the market. This could be to fix bugs, add new features, change the algorithms, change the underlying technology, etc. Blockchain protocols are no different. As a community, we keep learning better ways to solve our problems and would like to upgrade our blockchain protocols accordingly. For example, Ethereum had the “The Merge” upgrade, which upgraded their protocol from Proof of Work to Proof of Stake. Bitcoin had the “Taproot” upgrade, which extended the options for transaction verification. + +While upgrading a blockchain protocol is extremely crucial for its success, most blockchains including Bitcoin and Ethereum are not designed to do so easily and frequently. This is primarily because blockchains are not controlled by a single authority. Every upgrade proposal has to be evaluated by the community. However, the community's opinion on the proposals may be split. There is no quick and formal framework to finalize the decisions and build new features. Upgrades to the protocol potentially cause a fork in the network. As a result, upgrading a blockchain protocol could take years of joint effort by the community. Ethereum went through only [18 protocol upgrades in a 7.5 year time span](https://ethereum.org/en/history/). + +The Internet Computer is a unique blockchain that is designed to be easily upgradeable with a minimal user-perceived downtime and without any forks while still requiring consensus by the community for each upgrade. In the more than three years after genesis, ICP has upgraded many times, approximately once per week, adding crucial features such as deterministic time slicing, Bitcoin integration, HTTPS outcalls, chain-key signatures for ECDSA, Schnorr, and EdDSA, increased stable memory, etc. + +The “protocol upgrades” feature is designed with the following goals: (1) Allow arbitrary changes to the Internet Computer Protocol; (2) Preserve the state between upgrades; (3) Minimize downtime; (4) Roll out upgrades autonomously. + +Protocol upgrades are made feasible due to the blockchain governance system called Network Nervous System (NNS). In the NNS, there is a component called “registry”, which stores all the configuration of the Internet Computer. A versioning system is implemented for the configuration. Each mutation to the configuration shows up as a new version in the registry. The registry has a record for each subnet which includes a replica version, list of nodes in the subnet, cryptographic key material to be used by the subnet, etc. Note that the registry stores the desired configuration. The subnets might actually be running one of the older configurations. + +![Registry implements versioning mechanism](https://csojb-wiaaa-aaaal-qjftq-cai.icp0.io/_astro/registry-versions.-WLMQ1AE_Z2rzSoX.webp) + +To trigger a protocol upgrade, one has to submit a proposal in the NNS to change the configuration of the registry. The proposal can be voted by anyone who staked their ICP tokens. If a majority of voters accept the proposal, then the registry is changed accordingly. + +![Proposal to upgrade a subnet to a new replica version](https://csojb-wiaaa-aaaal-qjftq-cai.icp0.io/_astro/upgrade-proposal.CEzVfpIO_2t9Hbw.webp) + +Protocol upgrades are rolled-out on a per-subnet basis. Each subnet is run by many nodes. Each node runs 2 processes — (1) the Replica and (2) the Orchestrator. The replica consists of the 4-layer software stack that maintains the blockchain. The orchestrator downloads and manages the replica software. The orchestrator regularly queries the NNS registry for any updates. If there is a new registry version, the orchestrator downloads the corresponding change and informs the replica about it. + +In each consensus round, one of the nodes in the subnet (called the block maker) proposes a block. In every block, the block maker includes the latest registry version it downloaded from the registry canister. Other nodes notarize the block only when they have the referenced registry available. + +If the subnet record in the registry indicates a replica version change, the orchestrator downloads the corresponding software. After all the nodes in the subnet agree upon the latest registry version via consensus, the obvious next step is to switch to the new version. To avoid forks, it is crucial that all the nodes coordinate and switch their version at the same block height. To achieve this, the consensus protocol is divided into epochs. Each epoch is a few hundred consensus rounds (can be configured in the registry). Throughout an epoch, all the replicas in the subnet run the same Replica version, even if a newer Replica version is found in the registry and included in the blocks. Protocol upgrades happen only at the epoch boundaries. + +![Protocol upgrade happens at epoch boundaries](https://csojb-wiaaa-aaaal-qjftq-cai.icp0.io/_astro/protocol-transition.CvfhxtsH_Z1q5r7c.webp) + +The first block in each epoch is a summary block, which consists of the configuration information (including registry version and cryptographic key material) that will be used during the epoch. The summary block of epoch x specifies both the registry version to be used throughout epoch x, and the registry version to be used throughout epoch x+1. Therefore, all the nodes agree on what registry version to use for an epoch long before the epoch starts. + +Suppose a protocol upgrade of the subnet is supposed to be done at the beginning of epoch x indicated by a replica version change in the registry version the nodes agreed on. A blockmaker first proposes the summary block. The nodes then stop processing any new update call messages, but produce a series of empty blocks until the summary block is finalized, executed and the complete replicated state is certified. Query calls are executed normally during this time. Next, all the nodes create a catch up package (CUP), which contains the relevant information that needs to be transferred from the old replica software to the new replica software (see Section 8 of the whitepaper for more details) and is signed by more than 2/3 of the subnet nodes for validity. The CUP gives enough context for the new replica software to resume consensus. The replicas send the CUP to the orchestrator. The orchestrator runs the new replica software with the CUP as input. + +![Catch Up Package is handed over to new replica version](https://csojb-wiaaa-aaaal-qjftq-cai.icp0.io/_astro/handing-cup.DC6sx848_Z5jOcg.webp) + +## + +To prevent cross-version contamination, blocks and other consensus artifacts are tagged with protocol versions. With the exception of CUPs, the replica software only processes artifacts of its own version. As a consequence, CUPs must be decipherable by both pre-upgrade and post-upgrade replica software. + +Note that the registry records the desired configurations but does not track real-time subnet versions. Subnets may operate on older versions than indicated in the registry until they have completed the process outlined above. Therefore, nodes determine the currently used version by querying peers for the highest valid CUP. + +## Additional information + +[Blogpost on upgrading the Internet Computer Protocol](https://medium.com/dfinity/upgrading-the-internet-computer-protocol-45bf6424b268) + +[Whitepaper, see Section 8](https://internetcomputer.org/whitepaper.pdf) + +[10min video on core protocol upgrades](https://www.youtube.com/watch?v=mPjiO2bk2lI) + +[55min video on NNS-governed Canister Upgrades](https://www.youtube.com/watch?v=oEEPLJVX5DE) + diff --git a/.migration/learn-hub/how-does-icp-work/evolution-scaling/evolution-scaling.md b/.migration/learn-hub/how-does-icp-work/evolution-scaling/evolution-scaling.md new file mode 100644 index 00000000..612c2296 --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/evolution-scaling/evolution-scaling.md @@ -0,0 +1,18 @@ +--- +learn_hub_id: 34576974172692 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34576974172692-Evolution-Scaling" +learn_hub_title: "Evolution & Scaling" +learn_hub_section: "Evolution & Scaling" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# Evolution & Scaling + +The Internet Computer has the capability to adapt to changing application needs. In case of growing demand for resources, the creation of new subnets provides horizontal scalability. The protocol is also upgraded regularly, allowing for improvements in efficiency as well as extension of functionality. + + * [Subnet creation: ](https://learn.internetcomputer.org/hc/en-us/articles/34209955782420)The capacity of the network scales in response to user demand. To achieve this, the Internet Computer's architecture allows for the seamless addition of nodes and subnets, effectively expanding the network's resources and ensuring it can handle increasing usage. + * [Chain evolution: ](https://learn.internetcomputer.org/hc/en-us/articles/34210120121748) To meet the changing demands of its users, the Internet Computer has been design to evolve over time. Upgradeability must not come at the expense of the system's fundamental principles: decentralization and security. The Internet Computer must maintain its robust guarantees in these areas even as it evolves. + + + diff --git a/.migration/learn-hub/how-does-icp-work/evolution-scaling/fault-tolerance.md b/.migration/learn-hub/how-does-icp-work/evolution-scaling/fault-tolerance.md new file mode 100644 index 00000000..bb33f496 --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/evolution-scaling/fault-tolerance.md @@ -0,0 +1,57 @@ +--- +learn_hub_id: 34210647901460 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34210647901460-Fault-Tolerance" +learn_hub_title: "Fault Tolerance" +learn_hub_section: "Evolution & Scaling" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# Fault Tolerance + +In any large-scale distributed system, it is inevitable that individual nodes fail at any time due to hardware outages, network connectivity issues, or even attacks. ICP is fault tolerant, which means that the protocol will make progress even if some nodes fail or misbehave. When failures are detected, the [Network Nervous System (NNS](https://learn.internetcomputer.org/hc/en-us/articles/33692645961236)) selects a spare node that replaces the failed node in its subnet. The new node then joins the subnet and performs state synchronization with the subnet’s existing nodes and begins contributing to the subnet blockchain’s consensus protocol. + +## Node failures + +In each round, a block is produced by the [consensus layer](https://learn.internetcomputer.org/hc/en-us/articles/34207558615956), and the messages in the block are processed subsequently by the [execution layer](https://learn.internetcomputer.org/hc/en-us/articles/34208985618836). The proposed block and the resulting state need to be agreed upon by more than 2/3rd of the nodes in the subnet in order for the subnet to make progress. As long as less than 1/3rd of the nodes in a subnet fail or misbehave, even in an arbitrary, Byzantine manner, the subnet will continue making progress. + +If less than 1/3rd of the nodes in a subnet fail while the remaining nodes of the subnet continue to make progress, a failed node can recover automatically and catch up with the operational nodes. A newly joined node also uses the same process to catch up with the existing nodes in the subnet. + +Here’s one natural solution. A failed or newly joined node could download all the consensus blocks it missed from its peers, and process each block, one by one. Unfortunately, new nodes will take a long time to catch up if they have to process all the blocks from subnet genesis. Another solution is to let the failed or newly joined node directly copy the latest state from its peers. However, as the peers are continuously updating their state as they process new blocks, copying the latest state while the peers are updating it may lead to inconsistencies. + +ICP uses a mix of both the approaches. The consensus protocol is divided into epochs. Each epoch comprises a few hundred consensus rounds. At the beginning of each epoch, all the nodes create a checkpoint of their blockchain state and a catch-up package (CUP). The CUP at height h contains all relevant information required for consensus to resume from height h. This includes the hash of the blockchain state after processing the block at height h. The CUP is then signed by at least 2/3rd of the nodes in the subnet. Each normally-operating node then broadcasts the CUP. + +All the nodes in the subnet listen to the CUP messages broadcast by their peers. Suppose a node observes that a received CUP has a valid signature (signed by at least 2/3 of the nodes in the subnet) and has a different blockchain state hash than the locally available state hash for that height. Then the node initiates the[ state sync protocol](https://learn.internetcomputer.org/hc/en-us/articles/34471579767572) to sync the blockchain state at that height (the height at which the CUP is published). + +Note that while the failed/newly joined nodes are syncing the blockchain state, the well-functioning nodes continue to process new blocks and make progress. The well-functioning nodes use their backup copy of the blockchain state (created at the same time as the CUP) to supply the state to syncing nodes. After the syncing node finishes syncing the blockchain state, it will request the consensus blocks generated since the CUP and process the blocks one by one. Once fully synced, the node can then process messages regularly like the other nodes. + +If a failed node does not recover, or if a node keeps lagging behind or fail often, then a proposal to replace this node with another one may be submitted to the NNS. + +## Recovery of regular subnets + +In rare cases, an entire subnet can get stuck and fail to make progress. A subnet can fail due to many reasons such as software bugs that lead to non-deterministic execution. This can also happen when more than 1/3rd of the nodes in the subnet fail at the same time. In this case, the well-functioning nodes fail to create and sign a catch-up package (CUP), and thereby the failed nodes cannot recover automatically. + +When a subnet fails, manual intervention is needed for recovery. In a nutshell, as the subnet nodes fail to create and sign a CUP automatically, someone needs to manually create a CUP. The CUP needs to be created at the maximum blockchain height where the state is certified by at least 2/3rd of the nodes in the subnet. The subnet nodes naturally cannot trust a manually created CUP. Community consensus that the CUP is valid is required. Subnet recovery proceeds via a proposal to theNNS to use the created CUP for the subnet. Anyone who staked their ICP can vote on the proposal. If a majority of the voters accept the proposal, the CUP is stored in the NNS registry. + +Each node runs 2 processes — (1) Replica and (2) Orchestrator. The replica consists of the 4-layer software stack that maintains the blockchain. The orchestrator downloads and manages the replica software. The orchestrator regularly queries the NNS registry for any updates. If the orchestrator observes a new CUP in the registry, then the orchestrator restarts the replica process with the newly created CUP as input. As described earlier, the CUP at height h has information relevant to resume the consensus from height h. Once the replica starts, it will initiate a state sync protocol if it observes that the blockchain state hash in the CUP differs from the local state hash. Once the state is synced, it will resume processing consensus blocks. + +Note that this recovery process requires submitting a proposal to the NNS, and therefore works only for recovering regular subnets (not the NNS subnet). This process of recovering a subnet is often termed as disaster recovery in many Internet Computer docs. + +## Handling NNS canister failures + +The Internet Computer's NNS comprises the canisters that govern the entire Internet Computer. This includes the root canister, governance canister, ledger canister, registry canister, etc. + +Suppose a canister in the NNS fails while the NNS subnet continues to make progress. This could be due to a software bug in the canister’s code. In this case, the canister needs to be “upgraded”, i.e., restarted canister with a new Web Assembly code. Generally speaking, each canister in the Internet Computer has a (possibly empty) list of “controllers”. The controller has the right to upgrade the canister’s WASM code. The lifeline canister is assigned as a controller for the root canister. The root canister is assigned as a controller for all the other NNS canisters. The root canister has a method to upgrade other NNS canisters. Similarly, the lifeline canister has a method to upgrade the root canister. + +Suppose the governance canister is working. Then one can manually submit an NNS proposal to call the root/lifeline canister’s method to upgrade the failed canister. Anyone who staked ICP can vote on the proposal. If a majority of the voters accept, then the failed canister will be upgraded. + +## Handling NNS subnet failures + +In the worst case, the subnet which hosts the NNS canisters could get stuck and fail to make progress. In such a case, all the node providers who contributed a node to the NNS subnet need to manually intervene, create a CUP and restart their node with the new CUP. + +## Additional resources + +[12min video on resumption](https://www.youtube.com/watch?v=H7HCqonSMFU) + +[20min video on state synchronization](https://www.youtube.com/watch?v=WaNJINjGleg) + diff --git a/.migration/learn-hub/how-does-icp-work/evolution-scaling/subnet-creation.md b/.migration/learn-hub/how-does-icp-work/evolution-scaling/subnet-creation.md new file mode 100644 index 00000000..af0d8f91 --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/evolution-scaling/subnet-creation.md @@ -0,0 +1,31 @@ +--- +learn_hub_id: 34209955782420 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34209955782420-Subnet-Creation" +learn_hub_title: "Subnet Creation" +learn_hub_section: "Evolution & Scaling" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# Subnet Creation + +Ever wondered about the meaning behind DFINITY? It’s Decentralized + Infinity. It’s named that way because the Internet Computer is designed to scale infinitely. It means that the Internet Computer can host an unlimited number of canisters (smart contracts), store an unlimited amount of memory, process an unlimited amount of transactions per second. In simple words, Internet Computer is designed to host even large scale applications like social media platforms in a fully decentralized way. + +There are two types of widely-used approaches to improve the scalability of a system: (1) Vertical Scaling, and (2) Horizontal Scaling. Vertical scaling means adding more CPU, RAM and disk to a single computer. Horizontal scaling means adding more computers to the system. There is a limit to vertical scaling. But with horizontal scaling, one can achieve unlimited scalability. Internet Computer is one of the first blockchains to successfully use horizontal scaling. + +The Internet Computer scales its capacity horizontally by creating new subnets that host additional canisters — just like traditional cloud infrastructure scales by adding new machines. More precisely, the nodes in the Internet Computer are divided into subnets, each containing a few dozen nodes. The set of nodes in a subnet together maintain one blockchain. Each subnet can host thousands of canisters and process messages received by those canisters. Each subnet has a limited capacity in terms of the number of canisters (around hundred thousand), amount of storage (hundreds of GBs), and bandwidth (a few hundred transactions per second). But as more subnets are added to the Internet Computer, its overall capacity increases proportionately. Once the IC’s Network Nervous System (NNS) decided to create a new subnet, it selects a group of spare nodes that have joined the IC but have not yet been allocated to any subnet and creates the initial configuration of the new subnet. The selected group of nodes then begins to form a new subnet blockchain. + +![Internet Computer is divided into subnets](https://csojb-wiaaa-aaaal-qjftq-cai.icp0.io/_astro/add-new-subnet.34gYPhhU_ZY0r2F.webp) + +Another crucial design aspect is the inter-subnet (Xnet) communication of canisters: A canister of a subnet can send asynchronous messages to any canister on any other subnet. XNet messages are ingested by the receiving subnet’s consensus layer and their integrity is validated based on the sending subnet’s threshold signature — another application of [chain-key cryptography](https://learn.internetcomputer.org/hc/en-us/articles/34209486239252). This architecture of XNet messaging leads to a “loose coupling” of the subnets that does not require a central component such as a shard chain as used in other blockchains with multiple “shards” that would create a bottleneck when scaling out. Therefore newly added subnets can immediately send and receive XNet messages to any other subnet and an increasing number of subnets does not hit a natural bottleneck as in other, more simplistic, architectures. + +Creating a new subnet has two steps. (1) Adding new nodes to the Internet Computer, and (2) Creating a subnet with the available nodes. Anyone can purchase the node hardware and add it to the Internet Computer by following the [node provider onboarding process](https://wiki.internetcomputer.org/wiki/Node_Provider_Documentation). + +We now describe how to create a new subnet with the available nodes. The Internet Computer has a decentralized governance system called [Network Nervous System (NNS)](https://learn.internetcomputer.org/hc/en-us/articles/33692645961236). Essentially, the NNS consists of a group of canisters that manage the Internet Computer. In the NNS, there is a component called “registry”, which stores the full configuration of the Internet Computer. The registry has a record for each subnet which includes a protocol version, the list of nodes in the subnet, protocol configuration parameters, etc. + +![Proposal to create a new subnet.](https://csojb-wiaaa-aaaal-qjftq-cai.icp0.io/_astro/new-subnet-proposal.DhFWWB9r_1YulmL.webp) + +To add a new subnet, one has to submit a proposal to the NNS to add a record for a new subnet to the registry. The proposal consists of the list of nodes to be included in the new subnet. .The status of all proposals can be viewed on the [IC Dashboard](https://www.dashboard.internetcomputer.org). The proposal can be voted on by anyone who staked their ICP tokens. If a majority of voters accept the proposal, then the registry canister instructs the NNS subnet to generate — in a fully decentralized way using [chain-key cryptography](https://learn.internetcomputer.org/hc/en-us/articles/34209486239252) — the cryptographic key material to be used by the new subnet and a catch up package containing the genesis block. The registry canister then adds a record containing the configuration of the subnet. + +We now describe how a new subnet is created after a record is added to the registry. Each node runs 2 main processes, the (1) Replica and the (2) Orchestrator. The replica consists of the 4-layer software stack that maintains the blockchain and executes the canister messages. The orchestrator downloads and manages the replica software. When a new node is onboarded, the node provider has to install IC OS on the node, which contains the orchestrator software. The orchestrator regularly queries the NNS registry for any updates. If the orchestrator sees in a registry record that the node is included in a newly created subnet, then the orchestrator downloads the corresponding replica software, and runs the replica with the Catch Up Package included in the registry as input. The replica then starts accepting messages and the consensus protocol extends the genesis block present in the catch up package. + diff --git a/.migration/learn-hub/how-does-icp-work/icp-and-the-internet/asset-certification.md b/.migration/learn-hub/how-does-icp-work/icp-and-the-internet/asset-certification.md new file mode 100644 index 00000000..a3f4cc61 --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/icp-and-the-internet/asset-certification.md @@ -0,0 +1,27 @@ +--- +learn_hub_id: 34276431179412 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34276431179412-Asset-Certification" +learn_hub_title: "Asset Certification" +learn_hub_section: "ICP and the Internet" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# Asset Certification + +A user interacting with the Internet Computer needs to be able to confirm that the responses they receive are actually coming from the Internet Computer and have not been tampered with. Traditionally, on the Internet, this problem is solved using public-key cryptography. The server running the service has a secret key and uses that to sign all its responses. A user can then verify the signature on the response using the server’s public key. + +Just like a web server in Web2 maintains a public-key/secret-key pair, the Internet Computer blockchain as a whole maintains a public-key/secret-key pair. Additionally, each individual subnet in the Internet Computer also maintains its own public-key/secret-key pair. When a new subnet is formed, the NNS issues a certificate for the subnet which contains a signature of the subnet's public key with the Internet Computer's public key. When the subnet responds to a user's message, the response contains a certificate chain, which includes a signature on the response by the subnet's public key and the certificate issued by the NNS to the subnet. The user can verify the certificate chain using the Internet Computer's public key similar to verifying a certificate chain in Web2. + +Each blockchain node shares only a piece of its subnet secret key. As a result, each node is incapable of signing a message by itself. But if at least 2/3rd of the nodes of a subnet agree on a message, they together can combine their secret key pieces to sign the message. The signed message can be verified easily using the subnet's public key. If the verification succeeds, it means that at least 2/3rd of the blockchain nodes running the canister agreed to deliver that message. The technology used by the Internet Computer to generate and maintain the secret key shares, and sign messages using the secret key shares is called [chain-key cryptography](https://internetcomputer.org/how-it-works/chain-key-technology/). + +The Internet Computer supports two types of messages: Query calls and Update calls. Query calls are similar to HTTP `GET` requests and do not modify the state of the Internet Computer. The query calls do not go through the consensus protocol. The user can make a query call to any blockchain node in the subnet, and only that (possibly malicious) blockchain node answers the query. As generating a certificate requires consensus from at least 2/3rd of the nodes of the subnet, the Internet Computer doesn't issue a certificate when responding to query calls. + +For efficiency reasons, the canisters deliver web pages to the client via query calls. However, as the client needs to verify the received content, the Internet Computer introduces the notion of [Certified Variables](https://internetcomputer.org/how-it-works/response-certification/). In a nutshell, a canister can a-priori choose to create a certificate for a piece of data and store it in the replicated state. Any user can later access the data along with its certificate via query calls. + +We can use the notion of the certified variables to certify all the assets (HTML, CSS, Javascript files, images, videos, etc.) of an app a-priori. There are 2 ways of performing the asset certification. 1) The canister developer can explicitly write code to manage and certify all the assets. 2) The canister developer can create an "asset canister", by creating a canister with type set to "asset" and specifying the folder containing all the assets. The asset canister is a regular canister, except that the boilerplate code for managing and certifying all the assets is taken care of for us. + +When a canister issues a response along with its certificate, a [HTTP Gateway](https://internetcomputer.org/how-it-works/smart-contracts-serve-the-web) can be used to verify the certificate before passing on the response to the client. + +For more information on certification, check [Certified Variables](https://internetcomputer.org/how-it-works/response-certification/). + diff --git a/.migration/learn-hub/how-does-icp-work/icp-and-the-internet/http-gateway-protocol.md b/.migration/learn-hub/how-does-icp-work/icp-and-the-internet/http-gateway-protocol.md new file mode 100644 index 00000000..e3b097c3 --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/icp-and-the-internet/http-gateway-protocol.md @@ -0,0 +1,47 @@ +--- +learn_hub_id: 34211943471892 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34211943471892-HTTP-Gateway-Protocol" +learn_hub_title: "HTTP Gateway Protocol" +learn_hub_section: "ICP and the Internet" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# HTTP Gateway Protocol + +The [HTTP Gateway Protocol](https://internetcomputer.org/docs/current/references/http-gateway-protocol-spec) translates HTTP requests coming from a client (e.g., your browser) into API canister calls and then the responses back into HTTP responses. + +In the following, we describe the life of an HTTP request to a canister until it is turned into the corresponding HTTP response. This involves four components: + + 1. The client, which makes the HTTP request (e.g., a browser); + 2. An HTTP gateway, which translates the HTTP request into an API canister call and the resulting response into an HTTP response; + 3. An API boundary node, which routes the API canister call to a replica of the subnet hosting the target canister; + 4. A canister, which implements the HTTP interface. + + + +![](https://learn.internetcomputer.org/hc/article_attachments/34717980895636) + +_HTTP Gateway converts the format of HTTP Requests to canister API calls, and the resulting responses back to HTTP responses._ + +_ +_So let’s look at what happens when one opens a website that is hosted in a canister, e.g.,[ www.internetcomputer.org](https://internetcomputer.org/). + +It all starts in the browser. The browser does not know that this site is hosted on the Internet Computer and makes a normal HTTP request, just as it would for any other site. It sends that request to the server hosting internetcomputer.org, which is running the HTTP gateway protocol. + +This server takes the HTTP request and translates it into an API canister call. In particular, it turns the HTTP request into a query call to the http_request-method of the target canister and puts the requested path, the HTTP request headers and the body into the payload of that query call. How this works in detail is explained in the[ HTTP gateway protocol specification](https://internetcomputer.org/docs/current/references/http-gateway-protocol-spec). Today, there exists one main implementation of the HTTP gateway protocol: the ic-http-gateway library, which is, for example, used in the HTTP gateways. + +The API boundary node simply takes the API canister call and forwards it to a replica node, which is part of the subnet that hosts the target canister. + +The canister receives that query call for its http_request-method, processes it and replies. To this end, the canister needs to implement the[ Canister HTTP Interface](https://internetcomputer.org/docs/current/references/http-gateway-protocol-spec#canister-http-interface), which is part of the HTTP gateway protocol. + +The HTTP gateway receives the response from the canister and translates it back to an HTTP response. It unpacks the response, takes the status code, the supplied headers, the body, etc. and constructs an HTTP response from that. In addition to constructing the response, the HTTP gateway also verifies that the response is correct and has not been tampered with by a malicious replica node. To this end, each response comes with a certificate from the entire subnet (for more details check[ asset certification](https://learn.internetcomputer.org/hc/en-us/articles/34276431179412)). + +Finally, the browser receives the HTTP response and displays the site. + +## **Additional information** + +[Ic-http-gateway Library](https://github.com/dfinity/http-gateway/tree/main/packages/ic-http-gateway) + +[Response-verification](https://github.com/dfinity/response-verification): a collection of libraries to help canister developers with certifying their responses to work with the HTTP gateway protocol + diff --git a/.migration/learn-hub/how-does-icp-work/icp-and-the-internet/https-outcalls.md b/.migration/learn-hub/how-does-icp-work/icp-and-the-internet/https-outcalls.md new file mode 100644 index 00000000..432e2977 --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/icp-and-the-internet/https-outcalls.md @@ -0,0 +1,46 @@ +--- +learn_hub_id: 34211194553492 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34211194553492-HTTPS-Outcalls" +learn_hub_title: "HTTPS Outcalls" +learn_hub_section: "ICP and the Internet" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# HTTPS Outcalls + +In today's Internet, most data and functionality is accessible through Web 2.0 APIs. This includes data such as stock prices, football scores, IoT-related data, or crypto exchange prices. It includes functionality like sending notifications or text messages. This data or functionality would often be useful to smart contracts. Most blockchains have no direct way of providing access to these APIs and resort to (often centralized) oracle services, which are in the hands of intermediaries, vulnerable to hacking, and subject to service fees. + +Canister HTTPS outcalls on ICP allow direct interaction with Web 2.0 and other blockchains without oracles. Canister smart contracts can make HTTPS outcalls to specified URLs to directly obtain off-chain data, or to interact with off-chain systems, such as Web 2.0 services or enterprise IT infrastructure. + +## Architecture + +The HTTPS outcalls feature allows canisters to make outgoing HTTP calls to conventional Web 2.0 HTTP servers. The response of the request can be safely used in computations of the canister, without the risk of state divergence between the replicas of the subnet. + +### How an HTTPS outcall is processed by ICP + +The canister HTTPS outcalls functionality involves several components on different layers. Let us follow different processing steps when a canister submits an outcalls request. + + 1. A canister makes an outgoing HTTP request by calling the management canister API using the `http_request` method. + 2. The request is stored temporarily in the replicated state of the subnet. + 3. Periodically (in each round) an adapter at the networking layer in each replica fetches the pending HTTPS outcalls from the replicated state. +(In fact, a ‘shim’ layer of the adapter that is inside the replica process does so as the adapter itself is sandboxed into a separate OS-level process for security reasons.) + 4. The adapter on each replica executes the HTTP request by sending it to the target server. + 5. The corresponding HTTP response from the server is received by the adapter on each replica of the subnet and provided to a component in the replica process. +The adapter limits the network response size. + 6. An optional transformation function implemented as part of the canister is invoked on the respective response on each replica to transform the response. + 7. The transformed response is handed over to consensus on each replica. + 8. ICP consensus agrees on a response if more than 2/3rd of the nodes in the subnet have the same response for the request as input. +In this case, consensus provides this response back to the management canister API, or an error if no consensus can be reached or in case of other problems. + 9. The management canister API provides the response or error back to the calling canister. + + + +![HTTPS outcalls high-level architecture](https://internetcomputer.org/assets/images/HTTPS_outcalls_HL_architecture-f6a0eb54aef1aae1bd0989456f5d2aee.jpg) + +The above figure shows a high-level view of how a canister interacts with the feature and the communication patterns of the subnet replicas with external servers. + +To summarize, to perform an HTTP request, each replica pushes an (optionally-transformed) instance of the received HTTP response from the external web server through the Internet Computer's consensus layer, so that the replicas of the subnet can agree on the response provided to the canister, based on all server responses received by the replicas. The optional transformation ensures that, if responses received on different replicas from the server are different in some parts, those differences are eliminated and the same transformed response is provided to consensus on every (honest) replica. This guarantees that on every replica the exact same response (or none at all) is used for canister execution, thereby ensuring that divergence does not happen when using this feature and the replicated state machine properties of the subnet are preserved. + +As you can see, the transformation function and the Internet Computer Protocol's consensus play a crucial role for this feature: The transformation function ensures that differences in the responses received by the replicas are removed and transformed responses on different replicas will be exactly the same, thus enabling consensus to provide the agreed-upon response to the calling canister. By running the responses received by the replicas through consensus, the Internet Computer ensures that every replica provides the same response to the smart contract Wasm execution environment. + diff --git a/.migration/learn-hub/how-does-icp-work/icp-and-the-internet/icp-and-the-internet.md b/.migration/learn-hub/how-does-icp-work/icp-and-the-internet/icp-and-the-internet.md new file mode 100644 index 00000000..c01e5adf --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/icp-and-the-internet/icp-and-the-internet.md @@ -0,0 +1,25 @@ +--- +learn_hub_id: 34574399808788 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34574399808788-ICP-and-the-Internet" +learn_hub_title: "ICP and the Internet" +learn_hub_section: "ICP and the Internet" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# ICP and the Internet + +The Internet Computer aims to extend the functionality of the internet beyond simply connecting devices and networks, but running applications in a tamper-proof manner. The first articles in this section, describe how users' requests and the Internet Computer's responses are transferred and verified + + * [Edge infrastructure:](https://learn.internetcomputer.org/hc/en-us/articles/34212818609684) how request and responses reach their destination, including caching and load-balancing + * [HTTP Gateway Protocol:](https://learn.internetcomputer.org/hc/en-us/articles/34211943471892) how HTTPs is translated into the Internet Computer Protocol + * [Asset certification:](https://learn.internetcomputer.org/hc/en-us/articles/34276431179412) how responses from the Internet Computer are verified + + + +The second part of this section explains how canisters can communicate with web2 servers and use their data for computations without trusted intermediaries. + + * [HTTPS outcalls:](https://learn.internetcomputer.org/hc/en-us/articles/34211194553492) how canisters can interact with web2 + + + diff --git a/.migration/learn-hub/how-does-icp-work/icp-and-the-internet/icp-edge-infrastructure.md b/.migration/learn-hub/how-does-icp-work/icp-and-the-internet/icp-edge-infrastructure.md new file mode 100644 index 00000000..036ca096 --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/icp-and-the-internet/icp-edge-infrastructure.md @@ -0,0 +1,58 @@ +--- +learn_hub_id: 34212818609684 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34212818609684-ICP-Edge-Infrastructure" +learn_hub_title: "ICP Edge Infrastructure" +learn_hub_section: "ICP and the Internet" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# ICP Edge Infrastructure + +The edge infrastructure of the Internet Computer consists of two key components: API boundary nodes and HTTP gateways. These components work together to enable seamless communication between users and the Internet Computer while ensuring scalability, security, and efficient request processing. + +![](https://learn.internetcomputer.org/hc/article_attachments/34717950444948) + +**API Boundary Nodes:** API boundary nodes serve as the primary interface for interacting with the Internet Computer. They handle IC API requests—such as query and update calls—and efficiently route them to nodes (replica in the figure above) of the appropriate subnet. + +**HTTP Gateways:** HTTP gateways act as a translation layer between traditional HTTP and ICP communication, allowing direct browser access to canisters hosted on the Internet Computer. + + + +This split design provides flexibility for future expansions, enabling the integration of additional gateways that bridge between ICP and other established protocols such as DNS and SMTP. + +## API Boundary Nodes + +API boundary nodes are the globally distributed public interface of the Internet Computer. They receive requests from clients and efficiently route them to nodes of the appropriate subnet. This ensures seamless communication between IC-native applications and the decentralized network without reliance on centralized infrastructure. + +**Beyond Simple Routing** + +While their primary role is to deliver IC API requests (e.g., query and update calls), API boundary nodes perform several additional critical functions: + + * **Dynamic Routing** : Continuously monitor the Internet Computer core and adapt accordingly. + * **Load Balancing** : Distribute traffic efficiently to optimize performance. + * **Caching** : Store some responses temporarily to reduce latency and improve user experience. + * **Security Enforcement** : Implement safeguards to protect both themselves and the IC core from potential threats. + + + +**Fully Decentralized and NNS-Managed** + +API boundary nodes are an integral part of the Internet Computer, managed entirely by the [Network Nervous System (NNS)](https://learn.internetcomputer.org/hc/en-us/articles/33692645961236). Any additions, removals, or upgrades require an NNS proposal, ensuring transparency and decentralization. These nodes operate on hardware owned by multiple independent node providers, similar to the replica nodes assigned to subnets. + +**Unified Deployment** + +API boundary nodes run a service called ic-boundary. The Internet Computer utilizes a single virtual machine (VM) image for both replica and API boundary nodes. The orchestrator component on each node determines the node’s role, launching either ic-replica (for replica nodes) or ic-boundary (for API boundary nodes). + +**Global Deployment** + +Currently, around 20 API boundary nodes are deployed worldwide, ensuring a resilient and performant network. An up-to-date list of the API boundary nodes is available on the [dashboard](https://dashboard.internetcomputer.org/nodes?s=100&type=ApiBoundary). + +## HTTP Gateways + +HTTP gateways add an extra layer to the Internet Computer, translating HTTP requests into IC API calls and forwarding them to the API boundary nodes. Thanks to these gateways, browsers and other HTTP-speaking clients can directly interact with canisters on the Internet Computer. This is why, for example, you can access the Internet Computer website, [internetcomputer.org](http://internetcomputer.org/), from a browser without the need for any additional software, even though the site is fully hosted onchain. + +The translation of HTTP to IC API calls and back is defined in the [HTTP Gateway Protocol](https://learn.internetcomputer.org/hc/en-us/articles/34211943471892). + +Since HTTP gateways act as a translation layer, they are not part of ICP and can be deployed and operated by anyone. This open model encourages a diverse set of gateways, enhancing redundancy and availability. + diff --git a/.migration/learn-hub/how-does-icp-work/introduction/how-does-icp-work.md b/.migration/learn-hub/how-does-icp-work/introduction/how-does-icp-work.md new file mode 100644 index 00000000..8853e03b --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/introduction/how-does-icp-work.md @@ -0,0 +1,40 @@ +--- +learn_hub_id: 33694833025172 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/33694833025172-How-does-ICP-work" +learn_hub_title: "How does ICP work?" +learn_hub_section: "Introduction" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# How does ICP work? + +This part explains how the Internet Computer Protocol works. It explains the different components of the protocol, how they interact with each other, and why they are designed this way. It targets readers who have some technical knowledge, but it does not require specialized knowledge on cloud or blockchain technology. + +## Content structure + +The articles in this section are divided into different topics and answer the following questions. + + * [Blockchain Protocol ](https://learn.internetcomputer.org/hc/en-us/articles/34206453538964)\- What are the core layers of the protocol and how do they make the Internet Computer tamperproof and unstoppable? + * [Canister Smart Contracts ](https://learn.internetcomputer.org/hc/en-us/articles/34210839162004)\- How are decentralized applications on the Internet Computer managed and executed? + * [Chain-Key Cryptography ](https://learn.internetcomputer.org/hc/en-us/articles/34209486239252)\- How do cryptographic protocols provide security and verifiability? + * [Tokenomics & Governance](https://learn.internetcomputer.org/hc/en-us/articles/34574082263700) \- What is behind the ICP token and how is the Internet Computer governed? + * [Chain Fusion](https://learn.internetcomputer.org/hc/en-us/articles/34329023770260) \- How can decentralized applications on the Internet Computer interact with blockchains like Ethereum and Bitcoin? + * [Evolution & Scaling](https://learn.internetcomputer.org/hc/en-us/articles/34576974172692) \- How can the Internet Computer extend its functionality and capacity? + * [The Internet Computer and the Internet ](https://learn.internetcomputer.org/hc/en-us/articles/34574399808788)\- How the Internet Computer interacts with its users and with traditional web2 servers? + + + +## Other resources + +For more information on the following topics, we kindly refer you to consult other resources: + + * In case you are a developer who is rather interested to **learn how to build applications on ICP** , please refer to the [developer documentation](https://internetcomputer.org/docs/current/home). + + * If you are curious to see more **live information about the Internet Computer** that is running, such as which node machines are participating, please refer to [Internet Computer Dashboard](https://dashboard.internetcomputer.org/). + + * If you want to learn what projects and applications have already been built on the Internet Computer, please refer to the [ecosystem page](https://internetcomputer.org/ecosystem). + + + + diff --git a/.migration/learn-hub/how-does-icp-work/nns/neuron-attributes.md b/.migration/learn-hub/how-does-icp-work/nns/neuron-attributes.md new file mode 100644 index 00000000..b8e55d6f --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/nns/neuron-attributes.md @@ -0,0 +1,39 @@ +--- +learn_hub_id: 34140499557908 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34140499557908-Neuron-Attributes" +learn_hub_title: "Neuron Attributes" +learn_hub_section: "NNS - Network Nervous System " +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# Neuron Attributes + +In the Network Nervous System (NNS), a [neuron](https://learn.internetcomputer.org/hc/en-us/articles/34084120668692) is an entity that participates in governance and holds voting power. Let's next look here at the detailed attributes of a neuron by looking at the [`Neuron` record](https://github.com/dfinity/ic/blob/173d06185f77265d97bc363d266ce79410f6b914/rs/nns/governance/canister/governance.did#L363C1-L386C3) in the interface of the [governance canister](https://dashboard.internetcomputer.org/canister/rrkah-fqaaa-aaaaa-aaaaq-cai). + + * `id : opt NeuronId`: A unique ID identifying the neuron. This is a number that is randomly chosen by the governance canister when a neuron is created. + * `account : blob`: The neuron's account on the ICP token ledger, holding the tokens locked in the neuron. This corresponds to a subaccount of the NNS governance canister so that the tokens can only be transferred by dissolving the neuron. + * `controller : opt principal`: The [principal](https://learn.internetcomputer.org/hc/en-us/articles/34250491785108) controlling the neuron. The controller has the permissions to read the neuron and perform any operations on the neuron. + * `hot_keys : vec principal`: A list of principals that have limited permissions on the neuron. This can be used for example to use more accessible but less secure keys for everyday operations. Hotkey principals can read the neuron as well as vote with it, which includes both direct voting and changing following. + * `cached_neuron_stake_e8s : nat64`: The amount of staked ICP tokens, measured in fractions of 10E-8 of an ICP token. + * `neuron_fees_e8s : nat64`: The amount of ICP that this neuron has forfeited due to making proposals that were rejected or from using the functionality to manage other neurons through proposals. This value must be smaller than `neuron_stake_e8s`. When a neuron is disbursed, this amount of ICP is burned. + * `created_timestamp_seconds : nat64`: The timestamp, in seconds from the Unix epoch, when the neuron was created. + * `dissolve_state : opt DissolveState; type DissolveState = variant { DissolveDelaySeconds : nat64; WhenDissolvedTimestampSeconds : nat64; }`: The timer that defines how long the tokens in this neuron are locked for. When the neuron is dissolving, i.e., the timer is running down, this this stores the timestamp at which the neuron becomes dissolved `WhenDissolvedTimestampSeconds`. When the neuron is non-dissolving, `DissolveDelaySeconds` stores how much time, in seconds, is left until the neuron is dissolved when the dissolve timer is turned on again. A neuron is dissolved if `WhenDissolvedTimestampSeconds` is in the past or if `DissolveDelaySeconds` is zero. + * `aging_since_timestamp_seconds : nat64`: The timestamp, in seconds from the Unix epoch, when this neuron last entered the non-dissolving state and has started aging. This value is meaningless when the neuron is dissolving and has age zero. The canonical value of this field for a dissolving neuron is `u64::MAX`. + * `followees : vec record { int32; Followees }; type Followees = record { followees : vec NeuronId }`: The followees of a neuron, that is the group of neurons that this neuron follows. They are expressed as maps from proposal topics (expressed by integers) to a list of followees for this particular topic. + * `recent_ballots : vec BallotInfo`: Information about how this neuron voted in the recent past. + * `maturity_e8s_equivalent : nat64`: The accumulated unstaked maturity of the neuron, in e8s equivalent. + * `staked_maturity_e8s_equivalent : opt nat64`: The accumulated staked maturity of the neuron, in e8s equivalent. Staked maturity becomes unstaked maturity once the neuron is dissolved. + * `auto_stake_maturity : opt bool`: If set and true, the maturity rewarded to this neuron for voting will be automatically staked and will contribute to the neuron's voting power. + * `spawn_at_timestamp_seconds : opt nat64`: This is used for neurons that were created when spawning maturity into a neuron. The value denotes the timestamp, in seconds from the Unix epoch, at which this neuron's maturity is replaced by newly minted ICP. + * `visibility : opt int32`: The visibility defines how much information about this neuron is publicly accessible, i.e., visible to those who are neither the controller nor have hot-key privileges to this neuron. Visibility can be public, private, or undefined. For public neurons, the full neuron is accessible to everyone, for private neurons only subset of the fields is visible, which is encoded in the [`NeuronInfo` record](https://github.com/dfinity/ic/blob/173d06185f77265d97bc363d266ce79410f6b914/rs/nns/governance/canister/governance.did#L408) type, further excluding the fields `recent_ballots` and `joined_community_fund_timestamp_seconds`. + * `voting_power_refreshed_timestamp_seconds` the time when the neuron last performed any of the following actions: direct voting, set following, or confirm following. This field is relevant for the neuron's voting power adjustment. If a neuron does not take any of these actions in more than 6 months (hence the timestamp is more than 6 months in the past from the current time), then the neuron has adjusted voting power. The adjustment has the effect that the neuron will have 0 voting power when this timestamp is 7 month in the past. At this time, the neuron's following choices will also be reset. + * `known_neuron_data : opt KnownNeuronData; message KnownNeuronData { string name = 1; optional string description = 2; `: A neuron can be registered as a **known neuron** via proposal so that it can be followed by others. Known neurons have extra information, a name and optionally a description. + * `joined_community_fund_timestamp_seconds : opt nat64`: Timestamp when this neuron joined the [neurons fund](https://learn.internetcomputer.org/hc/en-us/articles/34084179554196). + * `transfer : opt NeuronStakeTransfer`: The record of the transfer that was made to create this neuron. + * `kyc_verified : bool`: This is a field indicating whether genesis neurons have been KYC verified. `false` if this is a genesis neuron that has not been KYC verified. + * `not_for_profit : bool`: Whether this neuron is "Not for profit", making it dissolvable by voting on a manage neuron proposal. + * `neuron_type : opt int32`: The type of a neuron, identifying seed neurons and Early Contributor Token (ECT) neurons. + + + diff --git a/.migration/learn-hub/how-does-icp-work/nns/neurons-fund-nf.md b/.migration/learn-hub/how-does-icp-work/nns/neurons-fund-nf.md new file mode 100644 index 00000000..04433d03 --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/nns/neurons-fund-nf.md @@ -0,0 +1,166 @@ +--- +learn_hub_id: 34084179554196 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34084179554196-Neurons-Fund-NF" +learn_hub_title: "Neurons' Fund (NF)" +learn_hub_section: "NNS - Network Nervous System " +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# Neurons' Fund (NF) + +The Neurons' Fund has been disabled temporarily with the acceptance of [this proposal](https://dashboard.internetcomputer.org/proposal/135970). When it is re-enabled, the design described below might be changed. + +## Background and motivation + +The neurons' fund (NF) is designed to support the development of the [Service Nervous System (SNS) DAO](https://learn.internetcomputer.org/hc/en-us/articles/34084394684564) ecosystem. Any holder of an NNS neuron can decide to participate in the NF, contributing the maturity of their neuron to the fund. Decisions on the allocation of NF resources to decentralization swaps of SNS DAOs are made by the NNS. + +## Neurons' fund components + +The NF comprises four main components that will be discussed in more detail below. + + 1. Joining the NF + 2. NF's participation in decentralization swap + 3. Participation in SNS governance + 4. Maturity increase of NF neurons + + + +### Joining and leaving the NF + +Neurons can join or leave the NF. Users of the [NNS dapp](https://nns.ic0.app/) can do so by using a checkbox. This action can be taken at any time, even during ongoing voting on SNS proposals. Joining the NF means neurons expose their maturity to the risks associated with participating in SNSs. + +### NF participation in decentralization swaps + +SNS DAOs are created through an NNS proposal (refer to [SNS launch](https://learn.internetcomputer.org/hc/en-us/articles/34141180048404) for more background). If a proposal to create an SNS is adopted, the decentralization swap, where initial tokens of the SNS are distributed, starts. + +The extent of the NF's involvement in a specific SNS swap is decided by the Matched Funding scheme. Under this scheme, the NF’s contribution increases in proportion to the direct participation in the swap. This design ensures that the fund's involvement accurately reflects market interest and participation levels. + +At the beginning of the swap, the NF neurons' maturity is reduced proportionally to the maximum possible NF participation (`M`). If the decentralization swap is successful, the NNS mints an amount of `X` ICP as determined by the Matched Funding scheme. + + * The SNS treasury receives `X` ICP. + * The NNS NF treasury receives SNS neurons corresponding to `X` ICP. This is provided as a basket of neurons with various dissolve delays for each participating NF neuron. + * If the participation amount `X` is less than `M`, NF neurons' maturity is increased again to compensate. + + + +If the decentralization swap is not successful, the maturity of NF neurons is increased again by the amount it was decreased by earlier. + +Please note: In the Matched Funding framework, the minimum and maximum funding targets of an SNS swap are refer only to the direct participation. This means that the success of a swap only depends on the level of direct participation, not the contributions from the Neurons’ Fund. + +### Participation in SNS governance + +The SNS neurons created for NF participants are controlled by the NNS. Participation in voting on the SNS proposals is, however, passed through to the NF neurons via hotkeys on the SNS neurons owned by the NNS. This means that NF neurons are owned by NNS but permission is given to the principals that exposed maturity to NF neurons to vote on SNS proposals. + +When the swap is finalized, the hotkeys associated with neurons of NF participants are copied to the SNS neuron that is created for them. This is convenient for NF participants who want to keep their neurons' controller key in cold storage, and want to vote on SNS proposals. These users can add a hotkey to their NNS neuron, and it will automatically be copied to their SNS neuron for new SNSs. + +At most 3 hotkeys are copied. If an NNS neuron has more hotkeys, 3 of them will be chosen, prioritizing self-authenticating principals (i.e. non-canister principals) and favoring principals added earlier. This means that users can influence which hotkeys are selected by removing and then re-adding the hotkeys they don't want to be copied. If the user has hotkeys = [A, B, C, D] (all self-authenticating), and they want [A, B, D] to be copied to the SNS, then they should do something like: + +1\. hotkeys.remove(C) // hotkeys = [A, B, D] +2\. hotkeys.add(C) // hotkeys = [A, B, D, C] + +Now [A, B, D] would be copied. + +The voting power of the SNS neurons is proportional to the amount of maturity exposed. + +### Increasing maturity of NF neurons + +The NNS NF treasury holds SNS neurons & tokens in its treasury, to be dissolved and disbursed at its discretion. When a set of neurons from a decentralization swap of an SNS dissolves, the NNS will determine the value of the dissolved SNS neurons. In the first stage, this will be done by a proposal. In a later stage, this could be done by pulling data from a DEX. + +The maturity of NF neurons whose maturity was reduced when a participation in a SNS-controlled dapp was made is increased by the amount determined by the NNS in the previous step. In the worst case, this amount could also be zero. + +The NNS can liquidate the disbursed SNS tokens at a later point in time. In case the NNS decides to swap the SNS tokens for ICP, the received ICP will be burned. + +## Matched funding + +The _Matched Funding_ scheme, in which the contribution of the Neurons’ Fund to SNS decentralization swaps scales in line with direct participation, allows for a reflection of market signals. + +In a SNS swap, there is a separation of contributions from direct participants and the Neurons’ Fund. In the Matched Funding framework, the minimum and maximum funding targets of an SNS swap refer only to the direct participation. This means that the success of a swap only depends on the level of direct participation, not the contributions from the Neurons’ Fund. + +### The Matching function, _f_ + +The scheme is implemented through a matching function _f_ , where the input represents the amount of direct participation, and the output _f(x)_ denotes the corresponding contribution from the Neurons' Fund (NF). + +The function f is designed to have three distinct phases and will be a continuous function to ensure a smooth transition between these phases. Importantly, the rules for these phases will be globally consistent, applicable to all SNS launches. + + * Initial Lag Phase (I): The function starts at 0, and grows slowly until it reaches a set threshold. This design encourages projects to accumulate enough direct participation before receiving substantial contributions from the NF. + * Growth Phase (II): After crossing the threshold, the NF's contribution increases at a faster rate, signifying more significant support for projects that have demonstrated viability through direct participation. + * Saturation Phase (III): Beyond a certain point, f(x) will level off and will not surpass 10% of the NF's total maturity, which ensures that no single SNS will excessively deplete the NF's resources. + * Bounding Condition: The matching function f(x) is bounded by g(x)=x, meaning that it will never exceed a 1:1 ratio with x. In practical terms, the NF's contribution will always be less than or equal to the amount of direct participation. + + + +These design principles aim to create a fair and sustainable system for allocating NF contributions to various SNS initiatives. + +### Benefits of matched funding + +#### Reflection of market signals + +The matched funding system is designed to closely align with market sentiment. Specifically, a project that successfully raises more direct contributions will correspondingly receive a greater contribution from the Neurons' Fund (NF), up to a predetermined limit. + +#### Simpler decision-making for NF NNS neurons + +The automated adjustment feature in the NF's contributions lessens the decision-making burden on NF NNS neurons. As a result, these neurons have fewer instances where they need to opt out, making the process more efficient. + +#### Improved incentives for projects + +The matching system provides a more compelling incentive structure for projects. Knowing that increased direct funding will be matched (up to a point) by the NF, encourages projects to be more proactive in their fundraising efforts. + +### Detailed specification of the matching function + +#### Cap + +The contribution should be capped by 10% of the NF maturity at proposal execution time and also by a global NF contribution cap being equivalent to 0.75M XDR. In other words we have cap = min (10% of NF maturity, global NF contribution cap). + +The global NF contribution cap is a configurable parameter of the NNS. + +#### Thresholds + +For specifying the shape of the matching function _f_ , we define the following thresholds + + * t_1: Up to this point, a project receives no contribution from the NF. + * t_2: Projects get a 2:1 contribution from the NF. + * t_3: Projects receive a 1:1 contribution from the NF. + * t_4 = 2 * cap: Projects get a 2:1 contribution from the NF. (and afterwards the contribution of the NF remains flat). + + + +The thresholds should be configurable parameters of the NNS. For example, they could become part of the NetworkEconomics record. + +These thresholds are specified in XDR and then converted to ICP thresholds at the execution of the SNS swap proposal using the 30-day average ICP/XDR conversion rate. + + * t_1: 75k XDR + * t_2: 225k XDR + * t_3: 375k XDR + + + +For an interactive tool allowing to explore the functionality of matched funding, please see the SNS [tokenomics analyzer](https://dashboard.internetcomputer.org/sns/tokenomics). + +#### Matching function polynomials + + * f_1: for function values between t_1 and t_2 + * f_2: for function values between t_2 and t_3 + * f_3: for function values between t_3 and t_4. + + + +Formulas for the polynomials can be derived from constraints listed above on the functions f and f’. + +### Clearer separation of contributions + +Feedback from both SNS projects and users on earlier designs has highlighted the need for a clearer separation between contributions from direct participants and those from the NF. This is now realized in two areas: + + 1. Proposal structure: Instead of specifying the overall minimum and maximum funding target, projects have the ability to set distinct minimum and maximum funding targets specifically for direct participation, which is the only factor determining whether the swap succeeds. The contribution from the NF is then added to this base amount, determined by a well-defined model (as per the matching function discussed above). + 2. User transparency in the SNS launchpad: During the swap, contributions from direct participants and the NF are displayed separately for transparency, within the NNS dapp’s SNS launchpad. + + + +### Benefits of the clearer separation + + * Transparency in success metrics: The success of the swap is directly and transparently linked to the amount raised through direct participation. + * More freedom to define funding target range: Projects can set a more flexible range for minimum and maximum funding targets without having to factor in the NF contribution, offering more leeway than in the current system where the NF contribution affects these limit (e.g. because the fixed NF contribution should exceed more than 66% of the minimum funding target). + * User clarity: Users will be able to easily see the amount of direct participation already collected during the swap, as well as the anticipated NF contribution. + + + diff --git a/.migration/learn-hub/how-does-icp-work/nns/neurons.md b/.migration/learn-hub/how-does-icp-work/nns/neurons.md new file mode 100644 index 00000000..f50f7c4c --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/nns/neurons.md @@ -0,0 +1,238 @@ +--- +learn_hub_id: 34084120668692 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34084120668692-Neurons" +learn_hub_title: "Neurons" +learn_hub_section: "NNS - Network Nervous System " +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# Neurons + +## What is a neuron? + +In order to participate in the network's governance and to receive voting rewards, ICP tokens must first be staked in a _neuron_. Neurons represent governance participants. Each neuron has its own identifier and several attributes. + +Once a neuron is locked for more than six months, it gains the ability both to submit proposals and to vote on them. Voting in turn generates voting rewards, based on how active a neuron is. If a neuron votes on every open proposal, it gains the maximum rewards. + +A neuron can also _follow_ other neurons, which causes it to automatically vote the same way as the majority of the neurons that it follows. In order to keep its voting power and thus keep getting voting rewards, a neuron has to regularly vote directly, set following, or confirm the chosen following settings. + +## Why staking matters + +Staking is a way of allowing those who support the Internet Computer to decide what happens next to the network. + +It is possible for proposals to pass with only a majority among 3% of the total voting power, meaning that proposals stand a chance even if large entities abstain and the majority of the network does not vote. + +## Key concepts + +It is important to understand a few key concepts of a neuron. Every user can stake ICP utility tokens into a neuron and participate in the NNS DAO. + +Each neuron has a _neuron ID_ , which is an identity selected by the NNS when the neuron is created. +In addition, each neuron has an associated _account_ on the ICP ledger where the locked ICP balance resides. This account is owned by the NNS governance canister, and therefore a user cannot move staked tokens. + +### Neuron permissions + +The neuron's _controller_ is a [principal](https://learn.internetcomputer.org/hc/en-us/articles/34250491785108) that controls the neuron and which cannot be changed. A principal corresponds to the public key of a public-private key pair, and anyone with possession of the corresponding private key will have full control of the neuron. Therefore, the private key of the controller principal should be kept very secure. One principal can control multiple neurons. + +### Hotkeys + +In addition to the controller, a neuron can have _hotkeys_. Hotkeys are principals that can perform actions with limited privileges, namely: + + * Voting. + * Set and confirm _following_ (see below). + * Reading the full information about the neuron, including non-public fields. + * Submit a proposal. + + + +Hotkeys cannot perform other neuron operations, such as increase dissolve delay, start dissolving, or disburse a neuron's stake. + +A neuron can have up to 15 hotkeys. One common workflow using hotkeys is to set a hardware wallet as the controller of the neuron, then vote or view neuron information through a software wallet set as a hotkey. + +Hotkeys can be added or removed from a neuron using the [NNS dapp](https://nns.ic0.app/) or the [`quill neuron-manage`](https://internetcomputer.org/docs/current/developer-docs/developer-tools/cli-tools/quill-cli-reference/quill-neuron-manage) command. If your principal is added as a hotkey to a neuron, the neuron and its information will be visible in the NNS dapp when you login. + +### Voting power + +The NNS is a stake-based governance system, so the main factor for how much _voting power_ a neuron has is its stake. In addition, the voting power depends on the following factors. + + * _Dissolve delay_ : The tokens in a neuron are locked for a specified duration called the dissolve delay. This can be thought of as a kitchen timer that can only be turned in one direction. It can be arbitrarily increased, but only reduced by turning on the countdown and waiting for the time to pass. A neuron must have a dissolve delay of at least 6 months to be _eligible_ to vote. + * _Dissolve state:_ A neuron can be in one of three states. + * A neuron can be _non-dissolving_ which means that the timer is stopped and the neuron's dissolve delay remains the same. + * A neuron can be _dissolving_ which means that the timer is decreasing the neuron's dissolve delay as time passes. + * Once the timer has counted down, a neuron is _dissolved_ and the ICP tokens can be unstaked again. This is called _disbursing_ a neuron. + * _Age_ : Every non-dissolving neuron has an age, which denotes how long it has been in the non-dissolving state. + * _Voting Power adjustment due to inactivity_ : In order to keep the voting power, a neuron has to regularly perform any of the following actions: vote directly, set following, or confirm its current following settings. If a neuron fails to do this, its voting power decreases slowly with time until it reaches 0. The voting power adjustment can be lifted at any point by the neuron performing one of the above actions. + + + +The first two factors ensure that a neuron who has tokens locked for longer or has been around for longer has more voting power as it is more committed to the long-term interest of the Internet Computer. The last factor ensures that "sleeper" neurons who do not actively participate in the voting process do not automatically get rewards. + +Based on these factors, a neuron's voting power can be determined: + + * Principally, by its stake. 1 ICP = the power of 1 vote. + * By its dissolve delay. 6 months grants a 1.06x voting power bonus, and 8 years grants 2x. All other durations scale linearly between. + * By its age. 4 years grants a 1.25x bonus, multiplicative with any other bonuses. All other durations between 0 seconds and 4 years scale linearly between. + * By voting power adjustments. A neuron who votes directly, sets following, or confirms following once every 6 months gets normal voting power. After 6 months of no action, a neuron’s voting power is linearly decreased for one month until it reaches zero at the end of 7 months without any action. After these 7 months, the neuron’s following settings are fully reset to zero. + + + +This means that the maximum voting power of 2.5 votes per ICP staked is only achievable by locking up your neuron for 8 years, leaving it in that locked-up state for 4 years, and regularly participating in governance by voting, set following, or confirm following. At that time, you will have the most voting power for the stake committed. + +To better understand how these factors influence a neuron's voting power and rewards over time, you can simulate some behaviors with the [NNS neuron sandbox](https://klgza-cqaaa-aaaak-qcz5a-cai.icp0.io/). Note that this tool assumes that neurons are active and therefore are not subject to voting power adjustments. + +### Maturity + +When neurons vote, directly or through following, the _maturity_ of a neuron increases as it collects voting rewards. +Each day the network rewards participants by allocating to every voting neuron a portion of the total reward, based both on its voting power at the time proposals were made and the number of proposals it voted on. See section Voting rewards & maturity for more details. + +### Neuron visibility + +A neuron can be _public_ or _private_. + +If a neuron is private, only its controller and the hotkeys can read the full neuron. Other parties cannot access all the information about the neuron. In particular, they cannot access the neuron's ballot. As a consequence, other neurons can only delegate their voting power to a private neuron if their controller is the same or if their controller is a hotkey of the delegate. + +If a neuron is public, anyone can read the full neuron. All known neurons are public. There are no restrictions who can delegate voting power to a public neuron. + +Refer to the tutorial [Making neurons public](https://internetcomputer.org/docs/current/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-making-neurons-public) to learn how you can change the visibility of your neurons on the NNS dapp. + +## Governance participation + +The main purpose of a neuron is to participate in governance. A neuron with a minimal stake can do so by submitting and voting on a [proposals,](https://learn.internetcomputer.org/hc/en-us/articles/34084113508500) or by participating in governance via the liquid democracy _following_ mechanism. + +### Voting + +A neuron is eligible to vote if it has at least 6 months dissolve delay. An eligible neuron can _vote_ on a proposal by choosing to adopt or reject it. This is called _direct voting_ as a neuron can also delegate voting (see next paragraph). + +As stated above a neuron's eligibility and voting power is dependent on its state and computed at proposal submission time. For more details on how these votes are processed in terms of ballots, refer to[ NNS proposals](https://learn.internetcomputer.org/hc/en-us/articles/34084113508500). + +To learn how you can vote directly, refer to [Voting on proposals](https://internetcomputer.org/docs/current/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-voting-on-proposals). + +### Vote delegation / Following + +Users may not have the time or knowledge to participate in all voting decisions. Therefore, instead of directly voting on proposals, neuron holders may choose to _delegate_ their vote to other neurons that they trust with certain decisions. This concept, where a neuron follows the decisions of some other neurons, is called _following_ in the NNS DAO. Collective decision making which combines the direct execution with dynamic delegation mechanisms for voting rights is called _[liquid democracy](https://en.wikipedia.org/wiki/Liquid_democracy)._ + +_For an explanation video regarding how following works and more information how following can be set on the NNS dapp, refer to[configuring neuron following](https://internetcomputer.org/docs/current/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-following-other-neurons)._ + +#### Periodic confirmation + +A neuron that never votes directly needs to either set or confirm its following decisions regularly (once every 6 months) in order to keep it voting power and keep getting rewards. This _periodic confirmation_ encourages governance participants to regularly review their following choices. + +For additional information on how to confirm following on the NNS dapp, refer to [Periodic neuron following confirmation](https://internetcomputer.org/docs/current/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-confirm-following). + +#### Following rules + +A neuron can be configured to vote automatically by following the voting decision made by a group of other neurons, called _followees_. Proposals are grouped into different [proposal topics ](https://learn.internetcomputer.org/hc/en-us/articles/34140518658068)and following is done on a per-topic basis. + +A neuron can follow any public neuron. A neuron can only follow a private neuron if it has the same controller or if its controller is a hotkey of the neuron to follow. + +Each neuron can follow at most 15 other neurons for each proposal topic. A neuron will only cast a "Yes"-vote if _more than half_ of the neurons within the followee-group voted Yes. A neuron will only cast a "No"-vote if _at least half_ of the neurons within the followee-group voted No. + +Your neuron will cast a vote when there are enough followee votes to make a decision whether it is a ADOPT or REJECT. For example, if you follow 10 neurons on a topic: +\- Your neuron only votes to adopt if at least 6 out of the 10 neurons vote to adopt. +\- Your neuron only votes to reject a proposal if at least 5 out of the 10 reject the proposal. +\- If less than 5 neurons (out of your 10 followed) vote at all, your neuron will not cast any vote. + + +This should be considered when choosing to follow multiple neurons on a topic. It might be better to follow fewer neurons, and it can be more beneficial to follow an odd number of neurons than an even number. + +#### Following "catch-all" + +In addition to setting following for individual topics, neurons may also define a catch-all follow rule which is triggered for proposals with topics for which no other explicit follow rule has been defined. +However, the catch-all follow rule does not include the proposal topics _SNS & neurons' fund_ and _Governance_. + +The catch-all follow rule is only applied for proposal topics with no other explicit choice. For example, let us assume neuron A follows neuron B for the catch-all and neuron C on the topic subnet management. If B votes on a subnet management proposal but C does not, no vote will be cast for A. +The catch-all follow rule does not apply for SNS & neurons' fund or governance proposals. For example, if neuron A follows neuron B for the catch-all and B votes on a governance proposal, no vote will be cast for A. If neuron A intends to also follow B on such decisions, the user has to explicitly choose to also follow B on the governance topic. + +It is in each neuron's interest to follow other neurons that support the best interests of the network and their own economic interests. + +## Known neurons + +In order for neurons to find which other neurons they could delegate their vote to, the NNS has a notion of _known neurons._ This is a list of neurons that can be used as a basis for finding candidates. + +Using a [proposal](https://learn.internetcomputer.org/hc/en-us/articles/34140518658068#h_01JJ2H93WHRBTDDFYPBVKTBHN2), any neuron can apply to register as a known neuron. If the NNS community approves the proposal, the neuron is added with a name in the list of known neurons. Optionally, the known neuron can also have the following self-declared information: + + * A description, for example what person or group is controlling the neuron, what their background is, and how they intend to vote. + * A list of links, for example to socials where voters can find more information. + * A list of proposal topics that the neuron commits to voting on. + + + +In addition to this self-declared information, the governance stores the past ballots of known neurons so that voters can consider their past behavior when they decide who to delegate their voting power to. + +_One place to find a list of all known neurons is on the[ICP Dashboard](https://dashboard.internetcomputer.org/neurons?s=100&type=known)._ + +_Interested parties who want to register a know neuron, update an existing known neuron, or propose to de-register a known neurons can find more information on the[developer documentation about Known Neurons](https://internetcomputer.org/docs/building-apps/governing-apps/nns/concepts/neurons/becoming-a-known-neuron)._ + +## Voting rewards & maturity + +In addition to influencing the future of the Internet Computer, the main incentive for stakeholders to stake their ICP tokens in a neuron and participate in voting is that they get _voting rewards_ by doing so. Voting rewards are collected by neurons in the form of _maturity_. + +Maturity is an attribute of a neuron; it is not a tradable asset. The decentralized governance of the Internet Computer can change the treatment of maturity at any time. To generate income from maturity, a user needs to trigger a non-deterministic process, which is burning maturity to create new ICP via disbursing the maturity (or spawning a neuron). The maturity modulation function introduces uncertainty in the creation of tokens from maturity. + +### What you can do with maturity + +Maturity can either be _disbursed_ (replacing the old functionality of _spawning)_ or it can be staked, meaning compounded to increase the neuron's total voting power. A user can also choose to _auto-stake_ the maturity. + +#### Disbursing maturity via the maturity modulation function + +Maturity can be liquidated by _disbursing maturity_. This is a process that can be started at any time and will then take seven days. In the end, a maturity modulation is applied, and new ICP tokens are minted that can be freely used. Maturity can be disbursed to any ledger account. If no account is specified, the caller's account will be used. +For more information on how to disburse maturity, refer to [How to disburse maturity](https://learn.internetcomputer.org/hc/en-us/articles/39755298701204). + +#### Spawning maturity via the maturity modulation function + +It is recommended to use disburse maturity instead of spawn maturity. While spawning is currently still supported by the NNS governance, it was replaced with disburse maturity and might be deprecated going forward. + +When a user chooses to spawn maturity, a new neuron will be immediately spawned. However, this newly spawned neuron will have no ICP at start, only maturity. Spawned neurons will have a dissolve delay of 7 days and will be set to dissolving at the time of spawning. After 7 days when the neuron is dissolved, the amount of ICP, modulated by the function introduced below, will be minted from the neuron's maturity and be available to the user. + +For more information on how to spawn maturity, refer to [How to disburse maturity](https://learn.internetcomputer.org/hc/en-us/articles/39755298701204). + +#### Staking maturity + +Maturity can be staked into _staked maturity_ of the neuron. Staked maturity is viewed as part of the neuron's stake and contributes to the neuron's voting power. But, similarly to the neuron's stake, it is also locked until the neuron is dissolved. When a neuron dissolves, its staked maturity is converted back to normal un-staked maturity (which is then subject to the maturity modulation). + +For more information on how to stake maturity, refer to [How to stake and auto-stake maturity](https://learn.internetcomputer.org/hc/en-us/articles/39755363912724). + +#### Auto-staking maturity + +Maturity can be _auto-staked_. In order to not have to regularly perform the previous action, a neuron can also choose to auto-stake its maturity. This means that all new maturity will automatically be added to the staked maturity. + +For more information on how to stake maturity, refer to [How to stake and auto-stake maturity](https://learn.internetcomputer.org/hc/en-us/articles/39755363912724). + +### Maturity modulation + +As mentioned above, to generate income from maturity, a user needs to trigger a non-deterministic process, which is burning maturity to create new ICP via disbursing the maturity. The _maturity modulation function_ introduces uncertainty in the creation of ICP from maturity. + +At the day of modulation, for each of the last 29 days, a 30-day moving average ICP/cycles conversion rate is determined, which is displayed on the Internet Computer dashboard. These are labeled `a1` through `a29`, where `a1` denotes the average rate on the previous day, `a2` denotes the rate 2 days ago and so on. The 30-day moving average conversion rates are used because they exhibit less variance than day-to-day conversion rates. + +Then, compute the relative 7-day return for each of the last 4 weeks. Thus: + + * ` w1 = (a1 - a8) / a8`, + * ` w2 = (a8 - a15) / a15`, + * ` w3 = (a15 - a22) / a22`, + * ` w4 = (a22 - a29) / a29`. + * The values w1, w2, w3, and w4 are bounded from -0.05 to 0.05 by clipping values to the limits of this range, i.e., capping by 0.05 and flooring by -0.05. + * Take the average `w = (w1 + w2 + w3 + w4) / 4`. + * The resulting value w is a number between -5% and 5% that determines modulation. + * The maturity amount x is converted to x * (1+w) units of ICP. + + + +The maturity modulation function is updated once a day. + +#### Example + +On Feb 1, 2022, the modulation function is 0.73% which is the average of the relative weekly returns w1 = -4.59%, w2 =-0.63%, w3=5.00%, w4 = 3.13%. If a user disburses on that day (day of transfer) 100 maturity, then this will result in 100.73 ICP. + +#### Motivation and analysis + +Evidently, this process introduces a certain amount of uncertainty for the conversion from maturity to ICP. However this uncertainty is limited in two ways: + + * The modulation value w is between -5% and +5%: This implies that, e.g., 100 maturity will be converted into an ICP amount in the range of 95 and 105. This kind of volatility is well in the range of daily conversion rate fluctuations of ICP. + * The modulation value w is calculated at the day of modulation as `w = (w1+ w2+ w3 + w4) / 4`. At the day of initiation (7 days prior), the user can already determine `(w2+ w3 + w4)/4`. The missing value w1 can affect the modulation value at most by 1.25% (5%/4) up or down. + + + +The modulation value can change by at most 2.5% from one week to the next, as one week drops out of the window and one week enters the calculation window. + +The modulation function gives an incentive for users to disburse maturity when the ICP/Cycles conversion rate has been increasing over time and to hold back when the ICP has been decreasing recently. For example if the ICP/Cycles conversion rate was monotonically increasing, then w1, w2, w3, w4 are positive and thus also w, incentivizing users to convert a maturity amount x to x * (1+w) units of ICP. + diff --git a/.migration/learn-hub/how-does-icp-work/nns/overview.md b/.migration/learn-hub/how-does-icp-work/nns/overview.md new file mode 100644 index 00000000..d7c22456 --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/nns/overview.md @@ -0,0 +1,50 @@ +--- +learn_hub_id: 33692645961236 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/33692645961236-Overview" +learn_hub_title: "Overview" +learn_hub_section: "NNS - Network Nervous System " +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# Overview + +The Network Nervous System (NNS) is the fully onchain decentralized autonomous organization (DAO) that governs the Internet Computer Protocol. It is a stake-based, open governance system where everyone can participate by staking ICP utility tokens. The NNS is implemented by a set of [canister](https://learn.internetcomputer.org/hc/en-us/articles/34210839162004) smart contracts. + +## The need for the NNS + +The Internet Computer is powered by independent nodes that run the Internet Computer protocol. For efficiency, these nodes are organized into different sub-groups, called subnets. To ensure that the Internet Computer can evolve in terms of security, performance, and scale, decisions such as the following need to be made: + + * Upgrading the protocol and guest operating system software used by the nodes, to extend functionality, improve security or performance. + * Adding new nodes by new node providers to the network for more robustness. + * Creating new subnets to scale the Internet Computer's capacity. + * Splitting subnets to balance network load. + + + +The NNS ensures that all these decisions can be made in a decentralized and autonomous way. + +## Neurons + +On the Internet Computer, governance participants are called _neurons_. Neurons correspond to staked ICP tokens. In other words, anyone can become a part of the NNS governance by locking ICP tokens in a neuron. This is incentivized by voting rewards for neurons who participate in decision making. + +Learn how to stake tokens in a neuron by following this [staking tutorial](https://internetcomputer.org/docs/current/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-staking-a-neuron). For more background information on neurons and voting rewards, read the article on [neurons](https://learn.internetcomputer.org/hc/en-us/articles/34084120668692). + +## Proposals + +Proposals are suggestion on how to evolve the Internet Computer. This includes decisions updating the protocol, organizing node machines into subnets, and updating the rules of the NNS DAO itself. Any neuron that has tokens staked for at least 6 months can submit and vote on proposals. + +On a high level, a proposal goes through the following lifecycle (ignoring some special cases): + + 1. **Proposal submission** : A neuron submits a proposal with a new suggestion to make a change to the network. + 2. **Establish ballot roll** : The governance canister takes a snapshot and creates (empty) ballots for all eligible neurons. + 3. **Voting** : All eligible neurons can cast their vote. This can either be done by a manual vote or by _following_ , which is a mechanism for delegating the voting power to another neuron. + 4. **Proposal decision** : The proposal is decided based on either: + * **Absolute Majority** \- At any point, even before the voting period ends, if an absolute majority (more than half of the total voting power) has voted "yes," then the proposal is adopted. If an absolute majority has voted "no," then the proposal is rejected. + * **Simple Majority** \- When the voting period ends, if a simple majority (more than half of the cast votes) has voted "yes" and the number of these yes votes constitutes at least 3% of the total voting power, then the proposal is adopted. Otherwise, the proposal is rejected. + 5. **Proposal execution** : If a proposal is adopted, the NNS DAO automatically and autonomously executes the proposals. For example, if the proposal decided to update the voting rules, an upgrade of the canister which implements these rules would be initiated automatically. Compared to other DAOs, this has the advantage that no human action is needed for proposal execution, removing a source of failure and inefficiency. + + + +For a tutorial on how to vote on a proposal, read [Voting on proposals.](https://internetcomputer.org/docs/current/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-voting-on-proposals) For a tutorial on how to set or change following, refer to [Following](https://internetcomputer.org/docs/current/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-following-other-neurons). For more detailed information about proposals, including details of the lifecycle, how to submit proposals, and the precise type of proposals, refer to [Proposals](https://learn.internetcomputer.org/hc/en-us/articles/34084113508500). For more information about voting, the rules of following, and how to verify proposals, refer to [Voting](https://internetcomputer.org/docs/current/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-voting-on-proposals). + diff --git a/.migration/learn-hub/how-does-icp-work/nns/proposal-topics-and-types.md b/.migration/learn-hub/how-does-icp-work/nns/proposal-topics-and-types.md new file mode 100644 index 00000000..62a66d6b --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/nns/proposal-topics-and-types.md @@ -0,0 +1,219 @@ +--- +learn_hub_id: 34140518658068 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34140518658068-Proposal-Topics-and-Types" +learn_hub_title: "Proposal Topics and Types" +learn_hub_section: "NNS - Network Nervous System " +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# Proposal Topics and Types + +In the Network Nervous System (NNS), governance is performed by means of [proposals](https://learn.internetcomputer.org/hc/en-us/articles/34084113508500) that are voted on and execute automatically upon being adopted. Each proposal has a _proposal type_ , which determines the action taken when the proposal is adopted or rejected. Each type of proposal belongs to a specific _proposal topic_. The following list contains all present proposals types grouped by their topics. For more information on what to consider when verifying the different kinds of proposals, please refer to the [tutorial on verifying proposals](https://internetcomputer.org/docs/current/developer-docs/daos/nns/concepts/proposals/verify-proposals). + +## Topic `ProtocolCanisterManagement` + +This topic covers proposals for managing the canisters which are essential to the Internet Computer Protocol's operation. This includes the canisters comprising the NNS DAO, such as [NNS governance](https://dashboard.internetcomputer.org/canister/rrkah-fqaaa-aaaaa-aaaaq-cai), [NNS root](https://dashboard.internetcomputer.org/canister/r7inp-6aaaa-aaaaa-aaabq-cai), the [registry canister](https://dashboard.internetcomputer.org/canister/rwlgt-iiaaa-aaaaa-aaaaa-cai), and the [ICP ledger](https://dashboard.internetcomputer.org/canister/ryjl3-tyaaa-aaaaa-aaaba-cai) canister. + + * `InstallCode`: Install, reinstall, or upgrade the code of a canister that is controlled by the NNS. + * `UpdateCanisterSettings`: Update the settings of a canister that is controlled by the NNS. + * `StopOrStartCanister`: Stop or start a canister that is controlled by the NNS. + * `HardResetNnsRootToVersion`: Uninstall and install the root canister with the Wasm provided in the function. If `InitArgs` are provided, they will be passed to the `canister_init` function of the Wasm provided. This function is meant as a 'break glass' mechanism for when an open call context in the root canister is preventing root or another canister from upgrading. + + + +## Topic `ServiceNervousSystemManagement` + +This topic covers proposals to manage the canisters of [service nervous systems (SNS)](https://learn.internetcomputer.org/hc/en-us/articles/34084394684564), including upgrading relevant canisters and managing SNS framework canister Web Assembly code modules through SNS-W. + + * `InstallCode`, `UpdateCanisterSettings`, and `StopOrStartCanister` are the same as in topic `ProtocolCanisterManagement`, only targeting different canisters. + * `AddSnsWasm`: Add a new SNS canister Wasm to SNS-W. All SNS DAOs can then upgrade to new versions along the upgrade path. + * `InsertSnsWasmUpgradePathEntries`: Insert custom upgrade path entries into SNS-W for all SNSes, or for an SNS specified by its governance canister ID. + + + +## Topic `ApplicationCanisterManagement` + +This topic covers proposals to manage NNS-controlled canisters not covered by the above topics. + + * `InstallCode`, `UpdateCanisterSettings`, and `StopOrStartCanister` are the same as in topics `ProtocolCanisterManagement` and `ServiceNervousSystemManagement` only targeting different canisters. + * `BitcoinSetConfig`: A proposal to set the configuration of the Bitcoin canister that underlies the Bitcoin API. The configuration includes the amount of fees to charge, whether or not the Bitcoin canister should sync new blocks from the network, whether the API is enabled, etc. + + + +## Topic `IcOsVersionElection` + +To upgrade the ICP protocol, the NNS DAO first elects new IC OS versions (the software that is run by ICP nodes). In a second step, selected nodes can be upgraded to the previously elected IC OS versions. This proposal type is for the first part, i.e., to elect new versions. + +HostOS is the hypervisor OS running on the IC node machine. Its main responsibilities include initializing and configuring the node machine hardware and passing functionality through to the GuestOS. The GuestOS, a VM running on the HostOS, contains the critical parts of the IC Protocol code, including the IC Replica, which runs the IC Canisters smart contracts. + +This topic contains the following proposal types: + + * `ReviseElectedGuestosVersions`: A proposal to change the set of elected GuestOS versions. The version to elect is added to the registry, identified by the Git revision of the installation image, along with the URLs of the upgrade image and the SHA-256 checksum of the image. Besides creating a record for that version to the registry, the proposal also appends that version to the list of elected versions that can be installed on nodes of a subnet. Only elected GuestOS versions can be deployed. + * `ReviseElectedHostosVersions`: A proposal to change the set of currently elected HostOS versions by electing a new version, and/or un-electing some previously elected versions. HostOS versions are identified by the hash of the installation image. The version to elect is added to the registry, and the versions to un-elect are removed from the registry, ensuring that HostOS cannot upgrade to these versions anymore. + + + +## Topic `IcOsVersionDeployment` + +This proposal is used to upgrade selected nodes to IC OS versions that have previously been approved ("elected") by the NNS DAO under the `IcOsVersionElection` topic. + +This topic includes the following proposal types: + + * `DeployHostosToSomeNodes`: Deploy a HostOS version to a specified set of nodes, changing the HostOS version used on those nodes. + * `DeployGuestosToAllSubnetNodes`: Deploy a GuestOS version to a specified subnet, changing the GuestOS version used on that subnet. The version must be in the list of elected GuestOS versions. The upgrade is complete when the subnet nodes create the next regular CUP, and then all subnet nodes restart and load the CUP with the new code. + * `DeployGuestosToSomeApiBoundaryNodes`: Update the GuestOS version on a set of API Boundary Nodes. + * `DeployGuestosToAllUnassignedNodes`: Update the GuestOS version on all unassigned nodes. + + + +## Topic `Governance` + +This topic covers proposals for governing the Internet Computer. In contrast to most other topics, which have reward weight 1, governance proposals have reward weight 20. This means that participation in this topic is rewarded more. + +This topic includes the following proposal types: + + * `Motion`: Motion proposals are the only proposals that don't have a direct onchain effect. Rather they can be used as polls that should guide the future strategy of the ICP ecosystem. + * `UninstallCode`: Uninstall code of a canister. + * `SetDefaultFollowees`: Sets default following. Newly created NNS neurons will be created with this default choice of followers for the topics. + * `KnownNeuron`: This proposal registers a [known neuron](https://learn.internetcomputer.org/hc/en-us/articles/34084120668692#h_01JN0SR92VPHVFPYXWAHKF3BYP) or, if a known neuron with this ID and name is already registered, it updates the known neuron. A known neuron has the following attributes. + * `string name`: a name that identifies the know neuron. + * `optional string description`: a description, for example what person or group is controlling the neuron, what their background is, and how they intend to vote. + * `repeated string links`: a list of links, for example to socials where voters can find more information. + * `repeated Topic committed_topics`: a list of proposal topics that the neuron commits to voting on. + * `DeregisterKnownNeuron`: This proposal de-registers a known neuron. That is it removes the neuron with the given neuron ID from the list of [known neurons.](https://learn.internetcomputer.org/hc/en-us/articles/34084120668692#h_01JN0SR92VPHVFPYXWAHKF3BYP) + + + +## Topic `SnsAndCommunityFund` + +This topic includes proposals that concern SNS decentralization swaps and the Neurons' Fund (formerly called Community Fund). In contrast to most other topics, this topic has reward weight 20. This means that participation in this topic is rewarded more. + +This topic currently only includes one proposal type: + + * `CreateServiceNervousSystem`: This proposal installs a set of canisters for a new SNS DAO and specifies all settings, including the initial token distribution, the conditions for the initial decentralization swap, the initial SNS DAO parameters, as well as the Neurons' Fund contribution. + + + +## Topic `NetworkEconomics` + +This topic includes proposals concerning network economics. This topic contains the following proposal types: + + * `UpdateNodeRewardsTable`: Update the node rewards table. This table is the basis for distributing rewards to node providers according to some rules, depending on where they are. You can find more information and the current reward table on [this Wiki page](https://wiki.internetcomputer.org/wiki/Node_Provider_Remuneration). + * `NetworkEconomics`: Network economics contains the parameters for several operations related to the economy of the network and settings of the NNS DAO that can be changed by a proposal of this type. +A single proposal can update one or several economic parameters. The default values (0) are considered unchanged. Thus, a valid proposal only needs to set the parameters that it wishes to change. Note that this also means that it is not possible to set any of the values to 0. +The following parameters can be changed: + * **Reject cost** : The amount of ICP the proposer of a rejected proposal will be charged to prevent the spamming of frivolous proposals. + * **Minimum neuron stake** : Set the minimum number of ICP required for the creation of a neuron. The same limit must also be respected when increasing the dissolve delay or changing the neuron state from dissolving to aging. + * **Neuron management fee** : The cost in ICP per neuron management proposal. Here the NNS is doing work on behalf of a specific neuron, and a small fee will be applied to prevent overuse of this feature (i.e., spam). + * **Minimum ICP/XDR rate** : To prevent mistakes, there is a lower bound for the ICP/XDR rate, managed by network economic proposals. + * **Dissolve delay of spawned neurons** : The dissolve delay of a neuron spawned from the maturity of an existing neuron. + * **Maximum node provider rewards** : The maximum rewards to be distributed to node providers in a single distribution event (proposal). + * **Transaction fee** : The transaction fee that must be paid for each ledger transaction. + * **Maximum number of proposals to keep per topic** : The maximum number of proposals to keep, per topic. When the total number of proposals for a given topic is greater than this number, the oldest proposals that have reached a “final” state may be deleted to save space + * **Neurons' Fund economics** : This includes all parameters related to the [Neurons' Fund](https://learn.internetcomputer.org/hc/en-us/articles/34084179554196): + * `max_theoretical_neurons_fund_participation_amount_xdr`: A theoretical limit which should be smaller than any realistic amount of maturity that practically needs to be reserved from the Neurons' Fund for a given SNS swap. + * `neurons_fund_matched_funding_curve_coefficients`: Defines a threshold specifying the shape of the matching function used by the Neurons' Fund to determine how much to contribute for a given direct participation amount. + * `minimum_icp_xdr_rate` and `maximum_icp_xdr_rate` are respectively the minimum and maximum value of the ICP/XDR conversion rate used by the Neurons' Fund for converting XDR values into ICP. + * **Voting Power economics** : This includes all parameters that affect the voting power of neurons. + * `start_reducing_voting_power_after_seconds`: A neuron has to regularly take any of the three actions: vote directly, set vote delegations, [confirm the vote delegations.](https://learn.internetcomputer.org/hc/en-us/articles/34084120668692#h_01JJ2G9K5P709E5TQDRKTT3ZTP) If the neurons hasn't done so for a period of time, its deciding voting power starts decreasing linearly. This number decides after which period of time this is the case. + * `clear_following_after_seconds`: A neuron has to regularly take any of the three actions: vote directly, set vote delegations, [confirm the vote delegations.](https://learn.internetcomputer.org/hc/en-us/articles/34084120668692#h_01JJ2G9K5P709E5TQDRKTT3ZTP) If the neurons hasn't done so for a period of time, its deciding voting power starts decreasing linearly (see last parameter) until it reaches zero. At this time, all voting delegations ("following") are removed. This parameter defines after which period of not taking the necessary actions this point is reached where following is removed. + * `neuron_minimum_dissolve_delay_to_vote_seconds`: The minimum dissolve delay a neuron must have in order to be eligible to vote. Neurons with a dissolve delay lower than this threshold are not eligible to vote on proposals, even if they are otherwise active. + * `ClearProvisionalWhitelist`: Clears the provisional whitelist, which allows the listed principals to create canisters with cycles. The mechanism is only needed for bootstrapping and testing and must be deactivated afterward. + + + +## Topic `SubnetManagement` + +All proposals that change the network's subnet topology and configuration. + +The following proposal types relate to the creation and composition of subnets: + + * `CreateSubnet`: Combine a specified set of nodes, typically drawn from data centers and operators in such a way as to guarantee their independence, into a new subnet. The execution of this proposal first initiates a new instance of the distributed key generation protocol. +The transcript of that protocol is written to a new subnet record in the registry, together with the initial configuration information for the subnet, from where the nodes comprising the subnet pick it up. + * `UpdateConfigOfSubnet`: Update a subnet's configuration. This proposal updates the subnet record in the registry, with the changes being picked up by the nodes on the subnet when they reference the respective registry version. Subnet configuration comprises protocol parameters that must be consistent across the subnet (e.g. message sizes). + * `AddNodeToSubnet`: Add a new node to a subnet. The node cannot be currently assigned to a subnet. The execution of this proposal changes an existing subnet record to add a node. From the perspective of the NNS, this update is a simple update of the subnet record in the registry. + * `RemoveNodesFromSubnet`: Remove a node from a subnet. It then becomes available for reassignment. The execution of this proposal changes an existing subnet record to remove a node. From the perspective of the NNS, this update is a simple update of the subnet record in the registry. + * `ChangeSubnetMembership`: Change the subnet node membership. This function combines the functions for adding and removing nodes from the subnet record into one, adding the property of atomic node replacement (node swap) on top. The nodes that are being added to the subnet must be currently unassigned. The nodes that are being removed from the subnet must be currently assigned to the subnet. + * `RecoverSubnet`: Update a subnet’s recovery CUP used to recover subnets that have stalled. Nodes that find a recovery CUP for their subnet will load that CUP from the registry and restart the replica from that CUP. + + + +The following proposal types relate to firewall rules: + + * `SetFirewallConfig:` Change the firewall configuration in the registry and define which boundary nodes the subnet replicas will communicate with. + * `AddFirewallRules`: Add firewall rules in the registry. + * `RemoveFirewallRules`: Remove firewall rules in the registry. + * `UpdateFirewallRules`: Update firewall rules in the registry. + + + +The following proposal types define which principals can create canisters on which subnets, managed by the cycles minting canister: + + * `SetAuthorizedSubnetworks`: Informs the cycles minting canister that a certain principal is authorized to use certain subnetworks (from a list). Can also be used to set the “default” list of subnetworks that principals without special authorization are allowed to use. + * `UpdateSubnetType`: Updates the available subnet types in the cycles minting canister. + * `ChangeSubnetTypeAssignment`: Changes the assignment of subnets to subnet types in the cycles minting canister. + * `UpdateSnsWasmSnsSubnetIds`: Update the list of SNS subnet IDs that SNS Wasm will deploy SNS instances to. + + + +The following proposal types are used for canister migration, e.g., if it is ever needed to split a subnet: + + * `RerouteCanisterRanges`: Update the routing table in the registry which defines the range of canister IDs that are on which subnet. + * `PrepareCanisterMigration`: Insert or update `canister_migrations` entries. This is used during a subnet migration of canisters (e.g., when a subnet needs to be split). + * `CompleteCanisterMigration`: Remove `canister_migrations` entries. This is used during a subnet migration of canisters (e.g., when a subnet needs to be split). + + + +## +Topic `ParticipantManagement` + +All proposals that administer network participants, notably data center and node provider identities. This topic contains the following proposal types: + + * `AddOrRemoveDataCenters`: Add or remove data center records in the registry. + * `AddOrRemoveNodeProvider`: Assign or revoke an identity to a node provider and any associated key information regarding the legal person that should provide a way to uniquely identify it. + + + +## Topic `NodeAdmin` + +Proposals that administer node machines. This topic contains the following proposal types: + + * `AssignNoid`: Assign an identity to a node operator, such as a funding partner, associating key information regarding its ownership, the jurisdiction in which it is located, and other information. The node operator is stored as a record in the registry. It contains the remaining node allowance for that node operator, that is the number of nodes the node operator can still add to the ICP. When an additional node is added by the node operator, the remaining allowance is decreased. + * `UpdateNodeOperatorConfig`: Change a node operator’s allowance in the registry. + * `RemoveNodeOperators`: Remove a Node Operator from the registry. + * `RemoveNodes`: Remove unassigned nodes from the registry. + * `UpdateSshReadonlyAccessForAllUnassignedNodes`: A proposal to update SSH readonly access for all unassigned nodes. + + + +## Topic `KYC` + +This topic only includes the following type concerned with KYCing Genesis neurons: + + * `ApproveGenesisKYC`: When new neurons were created at Genesis, their KYC value was set to `GenesisKYC=false`. This restricts what actions they can perform. Specifically, they cannot spawn new neurons, and once their dissolve delays are zero, they cannot be disbursed and their balances unlocked to new accounts. This proposal sets `GenesisKYC=true` for batches of principals. + + + +The Genesis event disburses all ICP in the form of neurons, whose principals must be KYCed. Consequently, all neurons created after Genesis have `GenesisKYC=true` set automatically since they must have been derived from balances that have already been KYCed. + + + +## Topic `NeuronManagement` (restricted voting) + +A special topic that can be used for multiple users to collectively manage a neuron. Specifically, a neuron can be managed by the followees for this topic. + +In a few aspects, `NeuronManagement` proposals behave differently than other proposals: + + * Only the neuron’s followers on this topic are allowed to vote (and thus have a ballot). + * The [restrictions which private neurons can be followed](https://learn.internetcomputer.org/hc/en-us/articles/34084120668692#01JY3Q496PCW6VVT0R6XXST12S) do not apply to this topic. + * Because the set of eligible voters for proposals on this topic is restricted, proposals on this topic have a shorter than normal voting period. + + + +This topic only includes one proposal type: + + * `ManageNeuron`: The proposal calls a command on a specified target neuron. Only the followers of the target neuron may vote on these proposals. + + + diff --git a/.migration/learn-hub/how-does-icp-work/nns/proposals.md b/.migration/learn-hub/how-does-icp-work/nns/proposals.md new file mode 100644 index 00000000..dbb715fd --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/nns/proposals.md @@ -0,0 +1,109 @@ +--- +learn_hub_id: 34084113508500 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34084113508500-Proposals" +learn_hub_title: "Proposals" +learn_hub_section: "NNS - Network Nervous System " +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# Proposals + +## What is a proposal? + +A proposal is a suggestion to evolve and update the Internet Computer protocol. NNS DAO participants can submit proposals, make suggestions on how the ICP should evolve, and vote on proposals that others have submitted. + +Based on the majority decision, a proposal is either adopted or rejected. If a proposal is adopted, it is automatically executed fully onchain, without the need for manual intervention. + +While other blockchains take weeks or months to upgrade and typically require substantial manual work and coordination to do so, ICP upgrades itself every week (as can be seen on [the dashboard](https://dashboard.internetcomputer.org/releases)). Its ability to upgrade and iterate is a comparative "superpower". + +## Proposal lifecycle + +A proposal lifecycle starts when it is submitted by a [neuron](https://learn.internetcomputer.org/hc/en-us/articles/34084120668692), which is a governance participant. Then, other governance participants form a decision and vote on the proposal. Based on these votes, the governance derives a proposal decision, i.e., the proposal is either adopted or rejected. + +If the proposal is rejected, usually nothing happens. If the proposal is adopted, the agreed upon decision is automatically executed by the governance canister. + +### Proposal submission + +Any eligible neuron can make and submit a proposal. To avoid being inundated by useless proposals, a user submitting a proposal has to pay a fee of 25 ICP when submitting a proposal that they will receive back if the proposal is adopted, but not if the proposal is rejected. + +After a proposal is submitted, the proposal is created and stored in governance. The governance computes and stores additional information with each proposal. + +Then, the governance looks at all neurons, i.e. governance participants, and creates an empty ballot for each eligible neuron that has a dissolve delay of at least 6 months, storing the neuron's voting power in this moment. This means that at the time of the proposal's submission, a neuron snapshot is taken and all neurons can vote on the proposal with the voting power that they have at that moment. + +This results in the following, potentially unintuitive cases: +\- If a neuron is created after a proposal was submitted, it is not eligible to vote on this proposal. +\- If a neuron had a dissolve delay of less than 6 months when a proposal was submitted, it cannot vote on the proposal, even if the neuron's dissolve delay is increased again. +\- If a neuron had a dissolve delay of 6 months when a proposal was submitted, it can vote on the proposal during the full voting period, even if by the time of voting the neuron's dissolve delay decreased slightly below 6 months. + +The sum of all of the neurons' voting powers determines the total voting power associated with a given proposal. In addition to creating all ballots, when a new proposal is created, the proposer's ballot is set to a “Yes” vote. This reflects that the proposal already has the support of the user submitting it. + +Moreover, each proposal has an associated _voting period_ , which determines the period of time over which votes for this proposal are accepted. + +For more information on how to submit a proposal, refer to [How to submit a proposal](https://internetcomputer.org/docs/current/developer-docs/daos/nns/concepts/proposals/proposal-submit). + +### Proposal voting + +After a proposal is submitted and added to the governance canister, other users who control neurons can vote on the proposal. The NNS DAO is an open governance system where anyone can become a participant by [staking some ICP in a neuron](https://internetcomputer.org/docs/current/developer-docs/daos/nns/using-the-nns-dapp/nns-app-quickstart#stake-icp-utility-tokens-in-a-neuron). At least 1 ICP is required to create a neuron. Locking tokens for a period of time is known as the [neuron's dissolve delay](https://learn.internetcomputer.org/hc/en-us/articles/34084120668692). If a neuron has more than 6 months dissolve delay, it is eligible to participate in voting. + +#### Finding proposals and discussions + +You can see all the NNS proposals on the [Internet Computer dashboard](https://dashboard.internetcomputer.org/governance) or on the [NNS dapp](https://nns.ic0.app/). Voters can freely discuss proposals anywhere they like. Many NNS proposals are discussed on the [developer forum](https://forum.dfinity.org/c/roadmap/29). + +#### Verifying proposals + +As proposals are executed fully autonomously (see below), they often include code that will be executed on proposal adoption. Before voting on a proposal, it is therefore crucial that voters not only provide their opinion whether a suggestion is a good idea, but also verify that the proposal does, i.e., implements, what it claims. For more details on the different kinds of proposals, refer to [Proposal types and topics](https://learn.internetcomputer.org/hc/en-us/articles/34140518658068) and for some inputs on how to go about verify proposals, refer to [Verify proposals](https://internetcomputer.org/docs/current/developer-docs/daos/nns/concepts/proposals/verify-proposals). + +#### Voting + +As a neuron represents a governance participant, voting happens via a [neuron](https://learn.internetcomputer.org/hc/en-us/articles/34084120668692). When a user has an eligible neuron and would like to vote on an open proposal, one option is to directly vote to adopt or reject the proposal. For more information how to vote, refer to [Voting on Proposals](https://internetcomputer.org/docs/current/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-voting-on-proposals). + +For more information how a user can set up their neuron to delegate its voting power using liquid democracy, refer to[ following](https://internetcomputer.org/docs/current/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-following-other-neurons). + +### Proposal decision + +The governance canister stores a neuron's choice in the empty ballot where the neuron's voting power has been recorded. In this way, the proposal always contains the information of the total voting power of "Yes" and "No" votes. + +A proposal can be decided in two ways: + + 1. _Absolute majority before the voting period ends_ : At any point, even before the voting period ends, if an absolute majority (more than half of the total voting power stored in the proposal) has voted "Yes", then the proposal is adopted, and if an absolute majority has voted "No", then the proposal is rejected. + 2. _Simple majority at the voting period’s end_ : When the voting period ends, if a simple majority (more than half of the cast votes) has voted "Yes" and the number of these "Yes"-votes constitute at least 3% of the total voting power, then the proposal is adopted. Otherwise, the proposal is rejected. + + + +#### Wait-for-quiet + +What also plays into this is an algorithm called _wait-for-quiet_ that dynamically adjusts the deadline. The idea of wait-for-quiet is to decide proposals quickly when all voters agree, but increase the time that neurons can vote for proposals that are controversial. That means that the voting period can be dynamically increased, depending on the neurons’ votes. In particular, each time a proposal’s outcome is turned (either a "Yes"-majority is turned to a "No"-majority or vice versa), the proposal’s deadline is increased. Currently, a proposal's initial voting period is 4 days and can be increased by at most another 4 days. That is, the voting period that is taken into account for the above rules can be between 4 and 8 days, depending on the voting activity. + +A proposal is adopted or rejected as soon as a decision can be made, which may be before the end of the voting period. However, even if an early decision was made, neurons can cast their vote up to the end of the voting period's end in order to get voting rewards. + +### Proposal execution + +Technically, a proposal defines a method on a canister that will be called if the proposal is adopted with some parameters. + +When a proposal is adopted, the defined method on the specified canister is automatically called with the given parameters. This is done automatically by the governance canister and does not require any manual intervention. A proposal's execution may be successful, in which case the proposal is labeled as `executed`, or it may fail, in which case the proposal is labeled as `failed`. + +When a proposal is rejected, most of the time nothing happens. In very few cases, some cleanup work is initiated. Therefore, `rejected` is also a possible final proposal state. + +### Reward distribution + +[Neurons](https://learn.internetcomputer.org/hc/en-us/articles/34084120668692) receive rewards for governance participation. After a proposal reached the voting period's deadline, the governance canister will take it into account for the next reward round. Even if a proposal was decided early, the proposal remains open for voting until the deadline so voters can get voting rewards even if a decision is made very quickly. For the details about NNS voting rewards, refer to [NNS voting rewards](https://learn.internetcomputer.org/hc/en-us/articles/34142993417108). + +After the rewards are distributed, a proposal has been through the full lifecycle. The proposal's details may be emptied by the governance canister to save space. + +## Proposal structure + +Each proposal submitted to the NNS has the following fields: + + * _Summary_ : Text providing a short description of the proposal using a maximum of 280 bytes. + * _URL_ : The web address of additional content required to evaluate the proposal, specified using HTTPS. For example, the URL's content might describe supporting the assignment of a DCID (data center ID) to a new data center. + * _Proposer_ : The ID of the neuron that submitted the proposal. When a proposal is submitted, a “charge” is placed on its balance in case it is rejected. The balance needs to be enough to pay the charge on all rejection(s). The NNS requires a neuron to have a dissolve delay of ≥ 6 months to vote, which also applies to submitting proposals. + * _Proposal type and topic_ : Each proposal has a _proposal type_ , which determines what happens if the proposal is adopted or rejected. This defines which canister method is invoked with which arguments. Each type of proposal belongs to a specific _proposal topic_. Topics are used for neuron following and also determine some other details about how the proposal is processed. For example, the voting period and the voting reward weight are defined per topic. + * _Parameters_ : The parameters that will be passed to the system function and invoked if the proposal is adopted, as determined by its type. When a proposal is submitted, the NNS checks these parameters. + + + +The NNS assigns a unique identity to each proposal that it receives. + +For more details about what kind proposals exist, refer to [proposal topics and types](https://learn.internetcomputer.org/hc/en-us/articles/34140518658068). + diff --git a/.migration/learn-hub/how-does-icp-work/nns/voting-rewards.md b/.migration/learn-hub/how-does-icp-work/nns/voting-rewards.md new file mode 100644 index 00000000..810c86c9 --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/nns/voting-rewards.md @@ -0,0 +1,103 @@ +--- +learn_hub_id: 34142993417108 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34142993417108-Voting-Rewards" +learn_hub_title: "Voting Rewards" +learn_hub_section: "NNS - Network Nervous System " +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# Voting Rewards + +Within the NNS, voting rewards are paid out to [neurons](https://learn.internetcomputer.org/hc/en-us/articles/34084120668692) who participate in governance by voting on [proposals](https://learn.internetcomputer.org/hc/en-us/articles/34084113508500). + +Rewards are paid out on a regular basis (currently daily), based on an overall reward pool for that time period. Each neuron receives a pro-rata amount of that pool according to the voting power with which the neuron voted and in how many proposals the neuron participated. + +We begin by outlining the long-term composition of the reward pool and then the daily calculation of voting rewards on a high-level. Finally, we describe detailed formulas for the pool and the rewards. + +## Long-term: voting rewards over years + +The voting reward function is depicted on the [ICP dashboard.](https://dashboard.internetcomputer.org/circulation) + +In the first year after genesis, the NNS allocates 10% of the total supply to generate voting rewards. Note the term "allocates" rather than "mints", because rewards are not minted until they are spawned and the according reward neuron is disbursed. This allocation rate drops quadratically until it reaches 5% by year 8 after genesis. The formula for the annualized rewards as a percentage of total supply for the first 8 years is ` R(t) = 5% + 5% [(G + 8y – t)/8y]²`. + +Like all parameters in the NNS, the reward rate and its schedule could be changed via NNS proposals. + +Because the total supply of ICP is a dynamic system with deflation and inflation, it is impossible to predict what voting rewards will be on any given day or year in the future. It is relatively easy to predict what the percentage allocation rate will be months from now, but it is much harder to predict what the total supply will be both because of potential changes to the rate, and how often stakeholders will spawn their maturity. + +## Short-term: voting rewards each day + +Every day, rewards are granted by the network to each voting neuron. The percentage of those rewards received by each neuron depend on the following factors of a neuron: + + * Amount of ICP and maturity staked. + * The neuron's voting power, which in turn depends on + * Length of dissolve delay. + * Age of the neuron (time spent in a non-dissolving state). + * Activity of the neuron (if a neuron neither votes directly nor sets or confirms following for too long it has an adjusted voting power). + * Number of eligible proposals the neuron has voted on. + + + +## Voting rewards details + + * Determination of the total reward pool: + + * For a time t between G (genesis time) and G + 8y the annualized reward as a percentage of total supply is R(t) = 5% + 5% [(G + 8y – t)/8y]² + * For a time t after G+8y, you have R(t) = 5%. + * The total pool of voting rewards for a given day is calculated as ICP supply (total supply of ICP tokens on that day) * R(t) / 365.25. + + + * Voting power of neurons: + * Only neurons with a dissolve delay of more than `neuron_minimum_dissolve_delay_to_vote_seconds`, defined in the [governance's parameters](https://learn.internetcomputer.org/hc/en-us/articles/34140518658068#h_01JJ2HA6H0DBRWPN13VA5P4F55), are eligible for voting. Currently this value is set to 6 months. The maximum dissolve delay is 8 years. + * The voting power of a neuron is computed as `neuron_stake * dissolve_delay_bonus * age_bonus * voting_power_adjustment` + * The neuron stake is the sum of staked ICP and staked maturity. + * In particular the dissolve delay bonus and the age bonus are cumulative. + * The dissolve delay bonus is a value between 1 and 2 and a linear function of the dissolve delay (capped at eight years). + * The age bonus is a value between 1 and 1.25 and a linear function of the age of the neuron (capped at four years). A neuron starts aging when it enters a non-dissolving state. Aging is reset to 0 when a neuron enters a dissolving state. + * Voting power adjustment is applied when a neuron hasn't voted, set following, or confirmed following in more than 6 months. The adjustment then applies a linear decrease of the voting power until it reaches 0 after 7 months of none of the above activities. + * The voting power is calculated when the proposal is made, not when the ballot is cast. + + + * Allocation of reward pool to neurons: + * The reward pool is allocated in proportion to the voting power of proposals that are settled on this day multiplied by the reward weight of the according proposal category. + * Determine the set of proposals that are included in this reward period (typically a day): these are the proposals that are not yet settled with respect to voting rewards, and no longer open for voting. + * The total voting power by neurons who were eligible for voting is added up. + * Each neuron is rewarded in proportion to the voting power it contributed to these proposals multiplied by the reward weight of the according proposal category. + * When a neuron is rewarded for voting, these rewards are recorded in an attribute of the neuron that is called maturity, which is not a tradable asset. If a user wants to generate income from maturity, they need to burn maturity to create new ICP via spawning a neuron which is a non-deterministic process. Find more information about this in [Spawning maturity & modulation](https://learn.internetcomputer.org/hc/en-us/articles/34084120668692). + * **Reward Roll-Over Mechanism:** There may be days when no proposals within the NNS are settled. Since the distribution of rewards is tied to the ballots of settled proposals, no rewards are distributed on such days. Instead, the rewards that would have been distributed are carried over to the next day. In more detail the process works as follows: + * For each day, the NNS determines the total amount of rewards available for distribution, based on the total token supply and the reward function, as mentioned above. + * If no proposal is settled on a given day, the rewards allocated for that day remain undistributed and are rolled over to the following day. This means that on the next day, the available rewards consist of both the newly accrued rewards and the undistributed rewards from the previous day. + * Whenever at least one proposal settles, the accumulated rewards are distributed accordingly. If no proposal settles again, the rewards continue to roll over. + + + +### Example + +#### Neuron's voting power + +If a neuron has a stake of 60 ICP and 40 staked maturity, it has a combined stake of 100. +Then, let's assume a dissolve delay of 8 years, which gives it a dissolve delay bonus of 2. +Also, assume a neuron age of 2 years, which gives it an age bonus of 1.125. Finally, assume the neuron regularly votes directly and has no voting power adjustment (so the adjustment is 1). +All together, this neuron then has a voting power of `100 * 2 * 1.125 * 1 = 225`. + +#### Rewards distribution + +If on a single day the NNS has generated 1000 maturity in total rewards (see below for more on how this is computed), and there were 10 proposals submitted for which only two neurons were eligible to vote on, and: + + * Neuron A has a voting power of 20, and voted on all 10 proposals. + * Neuron B has a voting power of 80, and voted on all 10 proposals. + + + +Then the 1000 maturity would be divided between these two neurons by their proportional voting power: + + * Neuron A with voting power of 20, gets 20% of the total = 200 maturity. + * Neuron B with voting power of 80, gets 80% of the total = 800 maturity. + + + +If either neuron had only voted for X% of those 10 proposals (weighted by the reward weight of the according proposal category), it's reward would be decreased to X% of its maximum eligibility. + +If on a single day there were 10 proposals, but a neuron only voted for five of them, +that neuron would only receive 50% of its rewards for which it is eligible that day. If the five proposals the neuron voted on had a reward weight of two, it would have a `weight_of_proposal_votes = 5 * 2`, while the `weight_of_all_proposals = 5 * 2 + 5 * 1`, therefore it would receive `(5 * 2) / (5 * 1 + 5 * 2) = 66%` of the rewards for which it is eligible that day. + diff --git a/.migration/learn-hub/how-does-icp-work/node-infrastructure/overview.md b/.migration/learn-hub/how-does-icp-work/node-infrastructure/overview.md new file mode 100644 index 00000000..f8e5a6ed --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/node-infrastructure/overview.md @@ -0,0 +1,56 @@ +--- +learn_hub_id: 46135518360212 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/46135518360212-Overview" +learn_hub_title: "Overview" +learn_hub_section: "Node Infrastructure" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# Overview + +IC-OS is the operating system that runs on Internet Computer nodes. It's based on Ubuntu Linux and customized specifically for the IC. + +IC-OS is actually three different operating systems that work together, each with a specific job. + +### SetupOS + +**SetupOS** is used when setting up a new node for the first time. Node providers download the SetupOS onto a USB drive, plug it into their node machine and boot from it. The SetupOS automatically sets everything up and then the machine reboots into the HostOS. + +**What it does:** + + * Checks that the hardware meets requirements + * Tests network connectivity + * Installs the other two operating systems (HostOS and GuestOS) + * Sets up the node with necessary settings and security keys + + + +### HostOS + +**HostOS** runs directly on the physical hardware. Its job is to configure and run the Guest virtual machine. + +**What it does:** + + * Runs a virtual machine that contains GuestOS + * Manages hardware resources + * Handles system upgrades + * Provides a security barrier between hardware and the ICP software + + + +### GuestOS + +**GuestOS** runs inside a virtual machine on the HostOS. This is where the actual Internet Computer software runs. + +**What it does:** + + * Runs the replica + * Runs canisters and manages their state + * Participates in consensus with other nodes + * Manages cryptographic keys and operations + + + +Running GuestOS in a virtual machine ensures every node has the exact same environment, regardless of the underlying hardware. Furthermore, running GuestOS in a virtual machine allows better separation from a potentially malicious host. + diff --git a/.migration/learn-hub/how-does-icp-work/node-infrastructure/trusted-execution-environments.md b/.migration/learn-hub/how-does-icp-work/node-infrastructure/trusted-execution-environments.md new file mode 100644 index 00000000..0c8cd12e --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/node-infrastructure/trusted-execution-environments.md @@ -0,0 +1,315 @@ +--- +learn_hub_id: 46124920595988 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/46124920595988-Trusted-Execution-Environments" +learn_hub_title: "Trusted Execution Environments" +learn_hub_section: "Node Infrastructure" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# Trusted Execution Environments + +The Internet Computer Protocol strengthens its confidentiality and integrity guarantees by running nodes inside Trusted Execution Environments (TEEs). + +This work is part of Milestone Magnetosphere and is being rolled out gradually across the network, with the first machines already live. In this article, we explore the security properties TEEs provide and how the Internet Computer Protocol leverages them. + +![Securing the Internet Computer with Trusted Execution Environments](https://learn.internetcomputer.org/hc/article_attachments/46126182872340) + +## The Internals of an ICP Node + +The Internet Computer is composed of many nodes distributed across the globe and operated by independent node providers. Each node is a physical server running a host operating system (_HostOS_), which in turn runs a virtual machine (_GuestOS_). + +All critical components, such as the orchestrator, the replica, the canisters, and their associated state, run inside the GuestOS. The GuestOS is logically isolated from the HostOS, which is treated as untrusted. + +## TEE Foundations for ICP Nodes + +While this virtualization-based isolation has always been in place, it was previously possible for a highly sophisticated attacker with physical access to a node to compromise the host and inspect or tamper with the memory and state of the GuestOS. + +TEEs address this by providing hardware-enforced isolation between a virtual machine and its host. Even if the HostOS or hypervisor is compromised, the confidentiality and integrity of the GuestOS is still preserved. + +The Internet Computer Protocol currently relies on AMD’s TEE technology: **Secure Encrypted Virtualization – Secure Nested Paging (SEV-SNP)**. SEV-SNP provides four core features that make it possible to place trust in a GuestOS running on a potentially compromised host: + + 1. **Memory Encryption** \- Protection of the GuestOS memory from unauthorized reads or writes by the host. + 2. **VM Launch Measurements** \- Cryptographic measurements that capture how the VM was initialized. + 3. **Attestation Reports** \- Verifiable evidence that a VM is running inside a genuine SEV-SNP TEE with a specific configuration. + 4. **Sealing Keys** \- Hardware-derived keys that allow data to be securely encrypted for persistent storage. + + + +In the following, we will highlight each of the four features in more detail and explain how they are used by the Internet Computer Protocol. + +### Memory Encryption + +SEV-SNP encrypts all memory pages of a virtual machine using keys protected by the CPU’s secure processor. This means that even if an attacker gains full control over the host machine, any attempt to inspect the VM’s memory will only result in encrypted blobs. + +This is important for the Internet Computer, as a node’s runtime memory contains highly sensitive data, including canister state and cryptographic material (e.g., signing keys and threshold key shares). + +### VM Launch Measurements + +A VM launch measurement in SEV-SNP is a cryptographic fingerprint that represents the state of a virtual machine at launch. It is computed by the SEV-SNP secure processor and captures both the contents of the VM’s initial memory and relevant configuration metadata. In effect, the measurement uniquely identifies what software was loaded and how the virtual machine was initialized. + +The launch measurement is derived from inputs such as the CPU model and firmware, the guest kernel, the initial ramdisk, and the kernel command-line parameters. Because the measurement reflects these inputs exactly, even a single-byte change in the guest software or configuration results in a different launch measurement. + +Importantly, the launch measurement can also be computed offline, using the same inputs that are used to initialize the VM. This makes it possible to know the expected measurement of a VM before it is ever started. + +The Internet Computer Protocol relies on VM launch measurements to securely identify different versions of the GuestOS. For each GuestOS release, the expected launch measurement can be computed ahead of time and published as part of the release process. As long as nodes run the same GuestOS version, their launch measurements will be identical across all Internet Computer nodes. + +The kernel command-line parameters included in the measurement contain, among other things, the expected hash of the root filesystem, which is verified during early boot. As a result, any modification to the GuestOS, whether in code, configuration, or filesystem contents, leads to a different launch measurement. + +These measurements play a central role for both remote attestation and sealing keys to bind trust and confidentiality to a specific, verified software configuration. + +![SEV-SNP attestation report](https://learn.internetcomputer.org/hc/article_attachments/46124888515860) + +### Attestation Reports + +An attestation report in AMD SEV-SNP is a cryptographically signed document produced by the SEV-SNP secure processor. It serves as verifiable evidence that a virtual machine is running inside a genuine Trusted Execution Environment (TEE). + +The report includes important information such as the VM’s launch measurement and a unique hardware identifier of the CPU. By examining the launch measurement, a verifier can determine precisely what software and configuration were used to initialize the VM. In other words, the attestation report allows anyone to confirm what is running inside the VM and that it is indeed protected by SEV-SNP. + +For the Internet Computer Protocol, attestation reports are critical to trust and transparency. They allow nodes and external parties to verify that a machine is running an approved GuestOS release, tying the VM back to the code base. + +### Sealing Keys + +A sealing key is a cryptographic key generated inside a Trusted Execution Environment (TEE) that cannot be accessed outside the virtual machine. In AMD SEV-SNP, sealing keys are derived from two sources: the CPU’s unique hardware identifier (chip ID) and the VM’s launch measurement. + +Because of this derivation: + + * Each machine produces a different key, even for the same GuestOS release; + * The key is tied to the specific software and configuration of the VM; if either changes, the key cannot decrypt previously sealed data. + + + +Sealing keys can be used to encrypt sensitive information such that it can only be decrypted inside the original VM with the original configuration, providing a strong guarantee of confidentiality and integrity for stored data. + +In the Internet Computer, sealing keys are used to protect the persistent state of a node. By encrypting this data with a sealing key, the protocol ensures that it can only be accessed by the intended GuestOS running on the intended hardware. This provides a powerful security guarantee: even if an attacker gains physical access to a node or copies the disk elsewhere, they cannot decrypt the node’s persistent data without the exact VM configuration and CPU. + +## Practical Considerations of Running TEE-Protected ICP Nodes + +With the foundational features of TEEs in place, running Internet Computer nodes inside AMD SEV-SNP environments introduces new operational considerations. The protocol must handle challenges such as: + + 1. leveraging sealing keys for disk encryption, + 2. enabling remote attestation to allow externals to verify that the nodes are running an approved GuestOS version within a TEE, + 3. securely upgrading nodes to a new GuestOS version without data loss and leakage, + 4. allowing failure recoveries in emergency situations. + + + +In the following sections, we explore each of these topics in detail. + +### Leveraging Sealing Keys to Encrypt the Disks + +#### SEV-SNP and Persistent Storage + +Out of the box, AMD SEV-SNP provides memory encryption for virtual machines, protecting runtime data in RAM from being accessed by the host. However, SEV-SNP does not automatically encrypt persistent storage. Without additional measures, data written to disk remains readable by the host operating system. To fully protect node state, persistent data must be encrypted before being written to disk using keys that are private to the virtual machine. + +Sealing keys provide a solution: they allow data on disk to be encrypted such that only the intended GuestOS, running on the intended hardware and version, can decrypt it. + +Partition name +--- +EFI +GRUB +config +boot (A) +root (A) +**var (A)** +encryption key based on VM A's measurement +boot (B) +root (B) +**var (B)** +encryption key based on VM B's measurement +**store** +(2 encryption keys based on each VM's measurement) + +#### Guest Disk Layout + +The layout of an Internet Computer GuestOS disk is fairly standard, consisting of partitions for boot, root, var, and a shared data store. However, the ICP node’s upgrade mechanism introduces a key twist: some partitions are duplicated across two sets (A and B) to allow safe upgrades. The full disk layout is shown on the right. + +Each partition set (A and B) contains a boot, root, and var partition. This design allows the node to download and prepare the next GuestOS version into the inactive partition set while continuing to run the current version. In case of a failed upgrade, the node can simply boot from the previous partition set. + +Only partitions that store sensitive data are encrypted. The var partitions are private to the currently active GuestOS, containing runtime data for that VM. The store partition is shared between both VMs and contains persistent data accessible to all GuestOS versions. System and configuration partitions (boot, root, config) are not encrypted, both because their contents are not confidential and because, in the case of the root partition, their integrity is protected via the root hash included in the VM launch measurement. + +#### Traditional Disk Encryption + +Internet Computer nodes have always used disk encryption for the data partitions. However, the encryption keys were independent of the GuestOS and could, in principle, be accessed by a malicious GuestOS. This left a potential attack vector: a highly skilled adversary could compromise the GuestOS and read the encrypted data. + +#### Using SEV-SNP Sealing Keys for Disk Encryption + +With SEV-SNP, encryption keys can now be derived from the VM’s sealing key, which is tied to both the CPU’s unique hardware identifier and the GuestOS launch measurement. This ensures that: + + * Each node has a unique key. + * Only the GuestOS that was used to encrypt the partition can decrypt it. + * Any change in the GuestOS version or hardware prevents access to previously encrypted data. + + + +When a node is deployed from scratch: + + 1. Encrypted partitions are created. + 2. LUKS passphrases for each partition are derived from the SEV-SNP sealing key using HKDF. + 3. Each encrypted partition receives a unique passphrase. + + + +The figure below shows how the LUKS encryption key is derived and ultimately depends on the specific GuestOS release and CPU: + +![SEV-SNP key derivation](https://learn.internetcomputer.org/hc/article_attachments/46124920593428) + +On reboot, the GuestOS requests the sealing key from the SEV-SNP secure processor. As long as the launch measurement has not changed, the same sealing key is returned, allowing the node to decrypt the partitions. If the launch measurement changes (e.g., after an upgrade), a different sealing key is generated and the encrypted partitions can no longer be accessed. + +This approach tightly couples data confidentiality and integrity to the GuestOS version, ensuring that persistent storage remains protected even if an attacker gains physical access to the host. At the same time, it creates a dependency: before a new GuestOS can access the data, we need a way to verify the integrity and authenticity of the new VM. This is where remote attestation comes in, providing the foundation for trust between nodes and enabling secure upgrades. + +### Remote Attestation of TEE-Enabled GuestOS + +Running TEE-enabled GuestOSs provides strong confidentiality and integrity guarantees, but those guarantees are meaningless if nobody can verify them. This is where remote attestation becomes critical: it allows parties, whether other nodes or external users, to confirm that a VM is running a genuine, approved GuestOS in a secure TEE. + +#### Node-to-Node Attestation + +Before sensitive data or secrets are shared between nodes, SEV-SNP-enabled nodes must attest each other to ensure that the other party is running a valid GuestOS. This is already integral to the upgrade process, where a new GuestOS running in an Upgrade VM must provide an attestation report to the old GuestOS before receiving the disk encryption key. + +As SEV-SNP adoption expands, node-to-node attestation will be extended to connection establishment across the network. When two nodes communicate, each attests the other, guaranteeing that secrets and sensitive data are exchanged only with trustworthy nodes. + +#### External Attestation + +Remote attestation is also important for external parties, such as IC users, who want to verify that the nodes serving them are running TEE-enabled GuestOSs. +To balance security and accessibility: + + * SEV-SNP-equipped nodes provide a dedicated attestation endpoint for external verification. + * Access to this endpoint is restricted by strict firewall rules and is only available via API boundary nodes (API BNs). + * External parties indirectly attest individual nodes through these API BNs, which in turn verify the nodes they communicate with. + + + +This layered attestation approach ensures that both the network and external users can trust the integrity and confidentiality of TEE-enabled GuestOSs, while maintaining security and scalability. + +With an understanding of both disk encryption and remote attestation, we now have all the pieces needed to explore GuestOS upgrades. Upgrades must securely transfer access to encrypted data while ensuring that only verified, trusted GuestOSes are allowed to run: combining the protections of sealing keys and attestation in practice. + +### Upgrades of TEE-Enabled GuestOS + +In TEE-enabled Internet Computer nodes, upgrading the GuestOS introduces a challenge: the new GuestOS has a different SEV-SNP launch measurement, which means its sealing key, and therefore the derived disk encryption key, differs from the one of the old GuestOS. Without a special upgrade process, the new GuestOS would be unable to access the node’s encrypted data store. + +To securely transfer access to encrypted data, the old and new GuestOS instances run side-by-side in parallel. The key idea is: Both VMs verify each other using SEV-SNP remote attestation to ensure that they are running on genuine TEE hardware and an approved GuestOS version. Once the new GuestOS proves its integrity and authenticity, the old GuestOS securely shares the disk encryption key with the new GuestOS over an encrypted channel. + +This ensures that only a legitimate, verified GuestOS can obtain the key and decrypt the data. + +#### Upgrade Process in Detail + +**Preparation** + + * When a new GuestOS release is approved, its attributes (e.g., root filesystem hash and launch measurement) are published to the NNS Registry, which serves as the source of truth for valid GuestOS versions. + * A malicious GuestOS cannot participate because it will have no entry in the Registry. + + + +**Initiating an Upgrade** + + * A proposal to upgrade a subnet or a set of nodes is submitted and voted on by the ICP community. If the proposal is accepted, the upgrade starts. + + + +**Deployment to Inactive Partition** + + * The nodes download the new GuestOS image into the inactive partition set. + * The old GuestOS continues running from the active set. + + + +**Launching the Upgrade VM** + + * A temporary Upgrade VM boots the new GuestOS while the old GuestOS is still running. + * The Upgrade VM cannot yet access the encrypted store or var partitions because its sealing key and derived disk encryption key differ. + + + +**Mutual Attestation** + + * The Upgrade VM generates an attestation report, which contains its launch measurement. + * It sends the report to the old GuestOS (key exchange server) over a TLS channel. + * The old GuestOS verifies the attestation report against the NNS Registry to ensure the new GuestOS is approved. + + + +**Secure Key Exchange** + + * Once verified, the old GuestOS shares the disk encryption key with the Upgrade VM. + * The Upgrade VM can now decrypt the partitions. It then replaces the old key with a new key derived from its own launch measurement. + + + +**Completion** + + * Both the old and Upgrade VMs shut down. + * The new GuestOS boots from the upgraded partition set and can access the data using its own derived encryption key. + + + +This process ensures that encrypted data remains confidential and is accessible only to a verified GuestOS, even during upgrades. The same procedure repeats for future upgrades, maintaining security across the node’s lifecycle. + +### Emergency Recovery of TEE-Enabled GuestOS + +TEE-enabled GuestOSes are designed to lock anyone out, including node operators, hosts, and potential attackers. While this ensures strong confidentiality and integrity, it also creates a challenge: if a node fails or its GuestOS becomes unresponsive, there is no simple way to intervene. + +Even though every GuestOS release undergoes extensive testing, unexpected failures cannot be completely ruled out. Bugs in rarely executed code paths, hardware quirks, or unforeseen incompatibilities may cause a node to crash or prevent the GuestOS from fully starting. In these cases, the Internet Computer Protocol needs a secure way to recover the node, even if such events remain extremely rare. + +Historically, emergency recoveries have occurred only a few times, and the frequency has decreased as the platform matured. For example, during 2025, not even a single emergency recovery was necessary. + +Recovery is never automatic. It is always coordinated by a recovery coordinator and must be approved by the community. Without an elected proposal, neither the coordinator nor node operators can modify the node. This ensures that recoveries maintain the security guarantees of the TEE while respecting the decentralized governance of the Internet Computer. + +The recovery approach depends on the severity of the failure. If the node’s orchestrator is still responsive and can interact with the NNS registry, existing recovery methods can be used. If the orchestrator is unresponsive, new strategies are required. These include a manual rollback initiated by the node provider and, if that fails, the deployment of a specially crafted, community-approved Recovery-GuestOS. The following sections describe both approaches in detail. + +#### Manual Rollback of GuestOS + +Manual rollback is the first line of defense when a node encounters issues after an upgrade. Its success assumes that the previous GuestOS version was stable and fully operational before the upgrade. + +Thanks to the dual partition setup, the node maintains two sets of partitions (A and B), allowing the new GuestOS to be downloaded into the inactive set while the active set continues running. In the event of a failure, node providers can simply switch the active partition set back to the previous version. This action can be performed from outside the GuestOS, via the HostOS limited console, without compromising confidentiality or integrity. + +The full process is as follows: + + 1. The recovery coordinator submits a proposal to the NNS marking the problematic GuestOS version as broken, including a description of the issue. + 2. If the community approves the proposal, nodes will refuse to upgrade to the broken version, even if the subnet record still references it. This ensures that nodes do not immediately upgrade again after a successful rollback. + 3. Node providers activate the rollback function via the HostOS limited console, switching the active partition set to the previous GuestOS version. + 4. If successful, the previous GuestOS boots, and the node can resume normal operation. With the orchestrator responsive again, standard recovery and upgrade procedures can continue. Once a fixed GuestOS version is released and approved, nodes can safely upgrade to it. + + + +#### Booting a Recovery-GuestOS with the Same SEV-SNP Measurement + +In rare cases, a node may be so severely broken that manual rollback is insufficient. Even the previously working GuestOS may fail to boot, leaving the node’s data inaccessible. Because the persistent data is encrypted with a key derived from the broken GuestOS’s SEV-SNP launch measurement, it cannot be accessed by any other GuestOS version. This creates a fundamental challenge: how can the node be restored without losing access to its encrypted state? + +The core difficulty lies in the tight binding of the disk encryption key to the GuestOS launch measurement. SEV-SNP ensures that the key is only available to a VM with the same measurement, which depends (among others) on: kernel, initial ramdisk, kernel command-line parameters. + +These components cannot be changed, as any modification would result in a different launch measurement, making the encrypted data inaccessible. The root filesystem, however, is indirectly part of the measurement through its hash: the kernel command-line includes the root hash, and the filesystem is only mounted if the hash matches. Normally, this prevents any modifications to the root partition. + +To overcome this, the Internet Computer introduces a Recovery-GuestOS mechanism. The goal is to provide a “fixed” GuestOS that can boot and restore node functionality, while using the same launch measurement as the broken GuestOS such that it retains access to the encrypted data. + +This is achieved by keeping the kernel, initramdisk, and kernel command-line identical to the base (broken) GuestOS, while replacing the root filesystem with a version containing the necessary fixes. + +The table below highlights the key differences between a standard GuestOS upgrade image and a Recovery-GuestOS image, illustrating which components are preserved, which can change, and how the Recovery-GuestOS is authorized to access the disk while maintaining the original launch measurement. + +| upgrade image | recovery image +---|---|--- +**can be reproduced and verified by the community** | yes | yes +**kernel, initrd, kernel command-line** | arbitrary | same as in base image +**root filesystem hash corresponds to the** _**root_hash**_**kernel command-line parameter's value** | yes | no +**boot partition contains NNS proposal with root filesystem hash** | no | yes + +The system introduces a special NNS-approved override mechanism: during early boot, if the actual root filesystem hash does not match the expected hash in the kernel command line, the node checks for a `BlessAlternativeGuestOsVersion` proposal. If present and valid, this proposal allows the Recovery-GuestOS to mount its new root filesystem while preserving the original launch measurement. This ensures the disk encryption key remains unchanged, so the data stays accessible. + +##### Recovery Process + +The Recovery-GuestOS procedure works as follows: + + 1. The recovery coordinator identifies the affected nodes and collects their chip IDs and the base GuestOS launch measurement. + 2. A Recovery-GuestOS branch is prepared in the Internet Computer repository. + 3. A root filesystem image for recovery is created, and a `BlessAlternativeGuestOsVersion` proposal is submitted to the NNS, containing: + * Recovery root filesystem hash + * Base launch measurement + * List of authorized node chip IDs + 4. Once the proposal is approved, a Recovery-GuestOS upgrade image is built, combining the base kernel, initramdisk, kernel command-line, the recovery rootfs, and the signed proposal. + 5. Node operators deploy the Recovery-GuestOS via the HostOS limited console. + 6. During early boot, the integrity checker detects the root hash mismatch, verifies the NNS proposal, confirms the node’s measurement and chip ID match the proposal, and then mounts the recovery root filesystem. + 7. The Recovery-GuestOS boots successfully, allowing the node to resume operation while maintaining SEV-SNP privacy guarantees. + + + +Since the integrity checker is part of the initramdisk, a malicious actor cannot tamper with it without affecting the SEV-SNP launch measurement, preserving the security of the node. + diff --git a/.migration/learn-hub/how-does-icp-work/sns/dao-settings.md b/.migration/learn-hub/how-does-icp-work/sns/dao-settings.md new file mode 100644 index 00000000..dc51ab58 --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/sns/dao-settings.md @@ -0,0 +1,127 @@ +--- +learn_hub_id: 34142964565396 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34142964565396-DAO-Settings" +learn_hub_title: "DAO Settings" +learn_hub_section: "SNS - Service Nervous System" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# DAO Settings + +While all SNSs run the same code that is approved by the NNS, the _nervous system parameters_ define the settings of a particular SNS. Since all SNSs are [upgraded along the same upgrade path](https://learn.internetcomputer.org/hc/en-us/articles/34140764336788), this allows SNSs to customize the rules of their governance, the tokenomics, etc to meet their needs. + +## The parameters + +### `default_followees` + +The set of default followees that every newly created neuron will follow per function. This is specified as a mapping of proposal functions to followees. If unset, neurons will have no followees by default. The number of followees for each function can be at most `max_followees_per_function`. + +### `max_dissolve_delay_seconds` + +The maximum dissolve delay that a neuron can have, given in seconds. That is, the maximum that a neuron's dissolve delay can be increased to. The maximum is also enforced when saturating the dissolve delay bonus in the voting power computation. + +### `max_dissolve_delay_bonus_percentage` + +E.g. if a large dissolve delay can double the voting power of a neuron, then this field would have a value of 100, indicating a maximum of 100% additional voting power. + +For no bonus, this should be set to 0. To achieve functionality equivalent to the NNS, this should be set to 100. + +### `max_followees_per_function` + +The maximum number of followees each neuron can have for each nervous system function. + +This number can be at most as large as the defined ceiling `MAX_FOLLOWEES_PER_FUNCTION_CEILING` (15 at time of writing). + +### `neuron_claimer_permissions` + +The default set of neuron permissions granted to the principal claiming a neuron. + +### `neuron_minimum_stake_e8s` + +The minimum number of e8s (10E-8 of a token) that can be staked in a neuron. + +To ensure that staking and disbursing of the neuron work, the chosen value must be larger than the `transaction_fee_e8s` set in the SNS ledger canister. + +### `max_neuron_age_for_age_bonus` + +The maximum age of a neuron (defined in seconds) that saturates the age bonus for the voting power computation. + +### `initial_voting_period_seconds` + +The initial voting period of a proposal, given in seconds. Changing this parameter will not affect existing proposals. + +### `neuron_minimum_dissolve_delay_to_vote_seconds` + +The minimum dissolve delay, defined in seconds, that a neuron must have to be eligible to vote. The chosen value must be smaller than `max_dissolve_delay_seconds`. + +### `reject_cost_e8s` + +The number of e8s (10E-8 of a token) that a rejected proposal costs the proposer. + +### `max_proposals_to_keep_per_action` + +The maximum number of proposals to keep, per action (i.e., proposal type). When the total number of proposals for a given action is greater than this number, the oldest proposals that have reached final decision state (rejected, executed, or failed) and final rewards status state (settled) may be deleted. + +The number must be larger than zero and at most as large as the defined ceiling `MAX_PROPOSALS_TO_KEEP_PER_ACTION_CEILING` (700 at time of writing). + +### `wait_for_quiet_deadline_increase_seconds` + +A parameter of the wait-for-quiet algorithm that increases the voting period of a proposal if it is controversial and changes the voting outcome. A proposal's voting period starts with `initial_voting_period_seconds` seconds and will be incresed at most by two twice the seconds defined in `wait_for_quiet_deadline_increase_seconds`. +Changing this parameter does not affect existing proposals. + +### `max_number_of_neurons` + +The maximum number of allowed neurons. When this maximum is reached, no new neurons will be created until some are removed. + +This number must be larger than zero and at most as large as the defined ceiling `MAX_NUMBER_OF_NEURONS_CEILINGM` (200_000 at time of writing). + +### `transaction_fee_e8s` + +The transaction fee, in 10E-8 of an SNS token, that must be paid for ledger transactions (except minting and burning governance tokens). + +### `max_number_of_proposals_with_ballots` + +The max number of proposals for which ballots are still stored, i.e., unsettled proposals. If this number of proposals is reached, new proposals can only be added in exceptional cases (for few proposals it is defined that they are allowed even if resources are low to guarantee that the relevant canisters can be upgraded). + +This number must be larger than zero and at most as large as the defined ceiling `MAX_NUMBER_OF_PROPOSALS_WITH_BALLOTS_CEILING` (700 at time of writing). + +### `max_age_bonus_percentage` + +Analogous to `max_dissolve_delay_bonus_percentage`, but this one relates to neuron age instead of dissolve delay. + +To achieve functionality equivalent to the NNS, this should be set to 25. + +### `neuron_grantable_permissions` + +The superset of neuron permissions a principal with permission `NeuronPermissionType::ManagePrincipals` for a given neuron can grant to another principal for this same neuron. If this set changes via a `ManageNervousSystemParameters` proposal, previous neurons' permissions will be unchanged and only newly granted permissions will be affected. + +### `voting_rewards_parameters` + +When this field is not populated, voting rewards are "disabled". Changing this should be evaluated carefully as it might be hard to understand rewards if they change. + +The reward parameters are: + + + final_reward_rate_basis_points : opt nat64; + initial_reward_rate_basis_points : opt nat64; + reward_rate_transition_duration_seconds : opt nat64; + round_duration_seconds : opt nat64; + +### `maturity_modulation_disabled` + +By default, maturity modulation (which is the same as in the NNS - see [here](https://learn.internetcomputer.org/hc/en-us/articles/34084120668692)) is enabled; however, an SNS can use this field to disable it. When disabled, this canister will still poll the Cycles Minting Canister (CMC), and store the value received from there. +However, the fetched value is not used when this setting is set to true. + +The reason this is called "disabled" instead of (positive) "enabled" is so that the protobuf default (bool fields are false) and our application default (enabled) agree. + +### `max_number_of_principals_per_neuron` + +The maximum number of principals that can have permissions for a neuron. + +### `automatically_advance_target_version` + +A boolean defining whether to automatically advance the SNS target version after a new upgrade is approved an published by the NNS. If set to true, this has the effect that the SNS is always automatically upgraded to the latest available version that was approved by the NNS. See also [Framework and Architecture](https://learn.internetcomputer.org/hc/en-us/articles/34140764336788) for details how SNS framework canisters are upgraded. + +If not specified, the value defaults to false for backward compatibility. For newly launched SNSs, the value defaults to true. + diff --git a/.migration/learn-hub/how-does-icp-work/sns/framework-and-architecture.md b/.migration/learn-hub/how-does-icp-work/sns/framework-and-architecture.md new file mode 100644 index 00000000..ebda6da2 --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/sns/framework-and-architecture.md @@ -0,0 +1,80 @@ +--- +learn_hub_id: 34140764336788 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34140764336788-Framework-and-Architecture" +learn_hub_title: "Framework and Architecture" +learn_hub_section: "SNS - Service Nervous System" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# Framework and Architecture + +## SNS framework + +The [SNS](https://learn.internetcomputer.org/hc/en-us/articles/34084394684564) operates as a framework within the Internet Computer Protocol (ICP). This means the ICP is responsible for the SNS functionality and maintains the code for the SNS canisters. More concretely, this means that the [NNS](https://learn.internetcomputer.org/hc/en-us/articles/33692645961236) community maintains the code that is run by all SNSs - it approved the original SNS canisters' code and continuously approves new improved SNS versions. + +### Advantages of the framework + +The fact that SNSs are built into the platform makes it easy for SNS DAO communities to maintain the code and increases trust, as NNS voters verify the code. It is also easy for users to verify different SNS DAOs as they all run the same, pre-approved code. Because all SNSs share a common framework, users familiar with one SNS DAO will find it easy to use another DAO. + +### SNS Wasm modules canister (SNS-W) + +The Wasms run by SNS canister are approved by the NNS and published on an NNS canister called the [SNS wasm modules canister (SNS-W)](https://dashboard.internetcomputer.org/canister/qaa6y-5yaaa-aaaaa-aaafa-cai). This means that all the SNS DAOs run code that is pre-approved by the NNS and they all run the same code (some of the SNS might be a few versions behind). + +The SNS framework canisters are published in a unique order on SNS-W, defining different SNS versions. + +### Upgrading SNS framework canisters + +Historically, there are different options how an SNS DAO can be updated to a new version that was pre-approved by the NNS and published on the SNS-W. + + * An SNS community can decide to update the SNS framework by submitting a proposal that will update the SNS to the next version. In this case, the DAO will automatically fetch the new version from SNS-W and update one canister (versions always only differ by one canister). + * An SNS community can choose to update to a particular target version. If an SNS is several versions behind, this is particularly useful as it has the effect that with the adoption of just one proposal, the DAO applies all required updates in sequence until the target version is reached. Compared to the first option, this requires less proposals and thus less time and effort for SNSs to catch up to the latest version. + * Finally, an SNS community can choose to always automatically upgrade to the latest available versions approved by the NNS. This can be done by an appropriate choice in the [DAO settings](https://learn.internetcomputer.org/hc/en-us/articles/34142964565396). All newly created SNSs have this enabled by default. + + + +For more details about the proposals that can be used to trigger these upgrades or change these settings, refer to the [developer documentation](https://internetcomputer.org/docs/building-apps/governing-apps/managing/making-proposals). + +### SNS subnet + +The SNS DAOs are hosted on the [SNS subnet](https://dashboard.internetcomputer.org/subnet/x33ed-h457x-bsgyx-oqxqf-6pzwv-wkhzr-rm2j3-npodi-purzm-n66cg-gae). Since this subnet exclusively hosts SNSs, this simplifies the verification for end users: users can simply verify that an SNS is running on the SNS subnet and infer that the underlying code has been approved by the NNS community as explained in the previous paragraph. + +## SNS canisters + +Each SNS DAO consists of a set of canisters smart contracts that run Wasm code. The most central canisters closely resemble the NNS (NNS) which is the DAO that governs the full ICP. + +The SNS consists of the following canisters: + + * The governance canister. + * The ledger canister and archive canisters. + * The index canister. + * The root canister. + * The decentralization swap canister. + + + +### SNS governance canisters + +The _governance canister_ defines who can participate in governance decisions and automatically triggers the execution of these decisions. It stores [proposals](https://learn.internetcomputer.org/hc/en-us/articles/34146571133204) that are suggestions on how to evolve the dapp that the SNS governs and [neurons](https://learn.internetcomputer.org/hc/en-us/articles/34084687583252) that define who the governance participants are. Neurons facilitate stake-based voting as they contain staked SNS tokens. When a proposal is adopted, the governance system automatically and autonomously triggers the execution of the proposal in the form calling a defined method. In most cases, these decisions are therefore executed fully onchain. + +### SNS ledger canister with archive and index + +The _ledger canister_ implements the [ICRC-1 standard ](https://github.com/dfinity/ICRC-1)and contains a unique token that is different for each SNS. These tokens are called _SNS tokens ._ "SNS token" may refer to one specific token of one SNS or to all these kinds of tokens, depending on the context. In each SNS, this SNS's ledger stores which accounts own how many SNS tokens and the history of transactions between them. + +To keep the full ledger history even though a canister has limited memory, the ledger canister spawns _archive canisters_ that store the ledger block history. + +Moreover, wallets and other frontends will need to show all transactions that are relevant for a given account. To facilitate this and ensure that not every frontend has to implement this themselves, the _index canister_ provides a map of which transactions are relevant for a given account. + +### SNS root canister + +The _root canister_ is responsible for upgrading the other SNS canisters and the dapp canisters that the SNS governs. + +### SNS (decentralization) swap canister + +The _decentralization swap canister_ , or swap canister for short, is the main canister involved in the [SNS launch](https://learn.internetcomputer.org/hc/en-us/articles/34141180048404). Users can provide ICP tokens to the swap and, if the swap is successful, they get staked SNS tokens (in SNS neurons) in return. Hence, the ICP and the SNS tokens are "swapped". +This facilitates that 1) the SNS can collect initial funding and 2) the distribution of neurons and thus of voting power to many different participants, which makes the governance decentralized. + +## Nervous system parameters for individual settings + +Individual SNSs can nevertheless be customized by choosing settings, called nervous system parameters, that can be configured to realize different forms of voting and tokenomics. Refer to [SNS DAO settings](https://learn.internetcomputer.org/hc/en-us/articles/34142964565396) for more information. + diff --git a/.migration/learn-hub/how-does-icp-work/sns/how-to-inspect-an-sns-and-its-dapp-canisters.md b/.migration/learn-hub/how-does-icp-work/sns/how-to-inspect-an-sns-and-its-dapp-canisters.md new file mode 100644 index 00000000..3131757a --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/sns/how-to-inspect-an-sns-and-its-dapp-canisters.md @@ -0,0 +1,180 @@ +--- +learn_hub_id: 46381576634772 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/46381576634772-How-to-Inspect-an-SNS-and-Its-Dapp-Canisters" +learn_hub_title: "How to Inspect an SNS and Its Dapp Canisters" +learn_hub_section: "SNS - Service Nervous System" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# How to Inspect an SNS and Its Dapp Canisters + +This guide explains how to discover and inspect all canisters that belong to a Service Nervous System (SNS), including governed dapps. + +You can interact with canisters in two ways: + + * **Internet Computer Dashboard** : [https://dashboard.internetcomputer.org](https://dashboard.internetcomputer.org/)[](https://dashboard.internetcomputer.org/) + + * **DFX command line tool** : <https://internetcomputer.org/docs/current/developer-docs/build/install-upgrade-remove> + +[](https://internetcomputer.org/docs/current/developer-docs/build/install-upgrade-remove) + + + + +* * * + +## 1\. Start from the SNS Root Canister + +Each SNS has a **root canister** that controls the SNS system. + +### Verify the SNS root + +All deployed SNS root canisters are listed in the SNS-W canister: + +**SNS-W canister ID:** +`qaa6y-5yaaa-aaaaa-aaafa-cai` + +Call: + +`list_deployed_snses` + +**DFX example:** + + + dfx canister --network ic call qaa6y-5yaaa-aaaaa-aaafa-cai list_deployed_snses '(record {})' + + +In the Dashboard: + + 1. Search for the SNS-W canister ID + + 2. Click `list_deployed_snses` + + 3. Click **Call** + + + + +* * * + +## 2\. List All SNS and Dapp Canisters + +From the SNS root canister, call: + +`list_sns_canisters` + +This returns: + + * Governance canister + + * Ledger canister + + * Swap canister + + * Any governed dapp canisters + + + + +**DFX example:** + + + dfx canister --network ic call <SNS_ROOT_CANISTER_ID> list_sns_canisters '(record {})' + + +* * * + +## 3\. Get Full Status and Controllers + +To inspect canister status, cycles balance, and controllers, call: + +`get_sns_canisters_summary` + +**DFX example:** + + + dfx canister --network ic call <SNS_ROOT_CANISTER_ID> get_sns_canisters_summary '(record {})' + + +You can verify the controller hierarchy: + + * SNS root controls all SNS canisters except the swap canister + + * Swap is controlled by the NNS root + + * NNS root canister ID: +`r7inp-6aaaa-aaaaa-aaabq-cai` + + * SNS root itself is controlled by SNS governance + + + + +* * * + +## 4\. Start from a Dapp Instead + +If you only know the dapp canister ID: + + 1. Query its controller + + 2. If it is controlled by an SNS root, use that root canister ID + + 3. Follow the steps above + + + + +If you only have a URL ending in `.ic0.app`, remove `.ic0.app` to obtain the canister ID. + +* * * + +## 5\. Inspect SNS Governance Neurons + +To list neurons in SNS governance: + +Method: `list_neurons` + +This method is paginated using: + + * `limit` + + * `start_page_at` + + + + +**DFX example:** + + + dfx canister --network ic call <SNS_GOVERNANCE_CANISTER_ID> list_neurons '(record { of_principal=null; limit=100: nat32; start_page_at=null })' + + +* * * + +## 6\. Check Token Balances + +### Tokens in the decentralization swap + +Call: + +`icrc1_balance_of` + +on the SNS ledger, using the swap canister as owner. + +### Tokens in the SNS treasury + +Call: + +`icrc1_balance_of` + +on the SNS ledger, using: + + * Owner = SNS governance canister + + * Subaccount = treasury subaccount + + + + diff --git a/.migration/learn-hub/how-does-icp-work/sns/launch.md b/.migration/learn-hub/how-does-icp-work/sns/launch.md new file mode 100644 index 00000000..60be3e48 --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/sns/launch.md @@ -0,0 +1,62 @@ +--- +learn_hub_id: 34141180048404 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34141180048404-Launch" +learn_hub_title: "Launch" +learn_hub_section: "SNS - Service Nervous System" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# Launch + +## What is the purpose of the launch? + +The SNS launch not only creates the SNS, but one of its main purposes is to decentralize the control of an SNS and thereby of the dapp that the SNS governs. To achieve this, new tokens must be distributed to a large community to ensure proper decentralization of the voting power. + +During an SNS launch, a developer hands over their dapp to the NNS, proposing to the NNS to create an SNS and start a decentralization swap for it. The decentralization swap collects ICP from participants and distributes the voting power of the SNS among participants by swapping the ICP for (staked) SNS tokens. + +## What are the steps of an SNS launch? + +If a developer team wants to hand over their dapp on ICP to an SNS, in a first step they propose this in an NNS proposal defining the details of the SNS launch and the initial configuration of the SNS DAO to be created. + +Note that such a proposal often requires some technical as well as non-technical preparation, such as thorough testing, getting the community on board, etc. For more information how to prepare and propose an SNS launch, refer to the [SNS developer documentation](https://internetcomputer.org/docs/current/developer-docs/daos/sns/). + +If the NNS community approves this proposal, the steps below to launch an SNS are then executed fully automatically. + + * The NNS creates a new set of SNS canisters and initializes them as defined in the NNS proposal. + * The initial parameters define the initial settings of the SNS and the token distribution. Some initial neurons can be assigned to some predefined entities, such as the original developer team that built the dapp. It is also defined how many tokens are initially in the treasury and how many tokens are distributed to the community for decentralizing the dapp. + * The NNS hands over the dapp's control to the newly created SNS. + * The NNS starts a decentralization swap for the SNS. The purpose of this is to raise initial funds for the DAO and to decentralize the voting power. This is done by an open swap where users can contribute ICP tokens as initial funding and get in return (staked) SNS tokens. See the next Section for more details. + * The NNS proposal can optionally define that the SNS would like contributions from the [Neurons' Fund (NF)](https://learn.internetcomputer.org/hc/en-us/articles/34084179554196). + * If the decentralization swap is successful, the SNS turns into a fully functional DAO. Otherwise, all assets such as the canisters comprising the dapp and the tokens collected from participants are returned to the original holder. + + + +### Initial decentralization swap + +A decentralization swap is run entirely onchain. Every aspect of the swap, from its initiation to execution, is completely decentralized and not controlled by any centralized entity. + +An initialization swap proceeds as follows. + + * The swap is set up at the start with a defined amount of SNS tokens to be distributed publicly. For each SNS that is launched, this is a new, unique token associated with this SNS. + * During the decentralization swap, participants can send ICP to the swap canister. + * At the end of the swap, the collected ICP are exchanged for the SNS tokens. The participants receive staked SNS tokens. The ICP tokens collected in the swap will become the treasury of the new SNS DAO. + * Each swap participant will receive their portion of the pool of SNS tokens, pro-rated by their share of the overall number of ICP contributed. Note that the final price of SNS tokens isn't known at the time of the decentralization swap, as it is dependent on the total amount of ICP swapped. However, one can calculate the minimum and maximum price based on the minimum and maximum ICP that the swap accepts, which is defined in the initial parameters. Refer to the next paragraph for some examples. + * Participants receive a basket of [neurons](https://learn.internetcomputer.org/hc/en-us/articles/34084687583252). These neurons hold SNS tokens and therefore a share of the DAO's voting power. + + + + +After a successful decentralization swap, SNS tokens are owned and the SNS is governed by a community. + +#### Some examples + +Let's consider some examples how many SNS tokens one would get in neurons when participating in a swap. + + * The decentralization swap distributed 1000 SNS tokens and 500 ICP tokens were collected during the decentralization swap. The exchange rate is 2:1 and each participant would get 2 SNS tokens for each ICP token they contributed. + * The decentralization swap distributed 5000 tokens for 1000 ICP. You participated with 10 ICP. This means you will have 50 SNS tokens, each worth 0.2 ICP. + * The decentralization swap distributed 1 million tokens for 500,000 ICP. You participated with 200 ICP. This means you will have 400 SNS tokens, each worth 0.5 ICP. + * The decentralization swap distributed 100 tokens for 10,000 ICP. You participated with 5 ICP. This means you will have 0.05 SNS tokens, where a full token would be worth 100 ICP. + + + diff --git a/.migration/learn-hub/how-does-icp-work/sns/neurons.md b/.migration/learn-hub/how-does-icp-work/sns/neurons.md new file mode 100644 index 00000000..9239fe36 --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/sns/neurons.md @@ -0,0 +1,110 @@ +--- +learn_hub_id: 34084687583252 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34084687583252-Neurons" +learn_hub_title: "Neurons" +learn_hub_section: "SNS - Service Nervous System" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# Neurons + +## What is a neuron? + +Neurons represent SNS governance participants that can vote on proposals. In order to participate in governance, SNS governance tokens (that are unique in each SNS) must be _staked in a neuron_. + +Once tokens are locked in a neuron for a specified time, it gains the ability both to submit proposals and to vote on them. A neuron can also _follow_ other neurons, which causes it to automatically vote the same way as the majority of the neurons that it follows. + +### Relationship to neurons in other DAOs + +The concept of neurons closely resembles [neurons in the NNS.](https://learn.internetcomputer.org/hc/en-us/articles/34084120668692) If you understand and are used to NNS neurons, you most likely understand a lot about SNS neurons already. There are however a few differences, including that NNS neurons can be public or private while all SNS neuron are public. + +Detailed neurons' settings can be chosen by each SNS communities as part of the [governance settings](https://learn.internetcomputer.org/hc/en-us/articles/34142964565396). For example, each SNS community can choose the rules about how long tokens must be staked in a neuron for the neuron to be eligible to vote, which neuron attributes influence its voting power, whether the governance rewards participation with voting rewards and if so how much. + +### +Key concepts + +Each neuron has a _neuron ID._ In the SNSs, and unlike the NNS, the neuron ID is the neuron _account_ on this SNS's ledger where the locked token balance resides. This account is owned by the governance canister, and therefore a user cannot move staked tokens. + +#### Neuron permissions + +While the NNS has a controller, that cannot be changed, and hotkeys with limited permissions, permissions are more flexible and fine-grained in the SNS framework. + +An SNS distinguishes many different permissions, for example for voting, or for changing certain settings of the neuron. With this, an SNS can for example define that certain operations are reserved for the original "controller" of the neuron (like in the NNS) or that all permissions can be handed over to a new principal. + +Within these rules, a user can then assign any set of permissions to a given principal and has thus a lot of flexibility. Some frontends, such as the[ NNS dapp](https://nns.ic0.app/), only allow users to add and remove "hotkeys" - even though this concept does not exist in the SNS governance it is easier for users to understand. The hotkey setting represents the set of permissions of a [hotkey in the NNS](https://learn.internetcomputer.org/hc/en-us/articles/34084120668692) and is just translated to the SNS's permission system in the background. + +#### Voting power + +An SNS is a stake-based governance system, so the main factor for how much _voting power_ a neuron has is its stake. Each SNS community can decide how the following factors influence a neuron's voting power by [choosing according settings](https://learn.internetcomputer.org/hc/en-us/articles/34142964565396). + + * _Dissolve delay_ : The tokens in a neuron are locked for a specified duration called the _dissolve delay_. This can be thought of as a kitchen timer that can only be turned in one direction. It can be arbitrarily increased, but only reduced by turning on the countdown and waiting for the time to pass. Each SNS defines the _minimum dissolve delay_ a neuron must have to be _eligible_ to vote. + * _Dissolve state:_ A neuron can be in one of three states. + * A neuron can be _non-dissolving_ which means that the timer is stopped and the neuron's dissolve delay remains the same. + * A neuron can be _dissolving_ which means that the timer is decreasing the neuron's dissolve delay as time passes. + * Once the timer has counted down, a neuron is _dissolved_ and the ICP tokens can be unstaked again. This is called _disbursing_ a neuron. + * _Age_ : Every non-dissolving neuron has an age, which denotes how long it has been in the non-dissolving state. + + + +These factors ensure that a neuron who has tokens locked for longer or has been around for longer has more voting power as it is more committed to the project. + +#### Maturity + +Each [SNS can choose](https://learn.internetcomputer.org/hc/en-us/articles/34142964565396) whether participation in voting is rewarded with [voting rewards](https://learn.internetcomputer.org/hc/en-us/articles/34143058069396). If activated, when neurons vote, directly or through following, the _maturity_ of a neuron increases as it collects voting rewards. See [SNS Rewards](https://learn.internetcomputer.org/hc/en-us/articles/34143058069396) for more details. +There are different things that a neuron holder can do with maturity: + + * Maturity can be liquidated by _disbursing maturity_. This is a process that can be started at any time and will then take seven days. In the end, a _maturity modulation_ is applied, and new SNS tokens are minted that can be freely used. + * Maturity can be disbursed to any ledger account. If no account is specified, the caller's account will be used. + * Maturity can be staked into _staked maturity_ into the neuron. Staked maturity is viewed as part of the neuron's stake and contributes to the neuron's voting power. But, similarly to the neuron's stake, it is also locked until the neuron is dissolved. When a neuron dissolves, its staked maturity is converted back to normal un-staked maturity. + * Maturity can be _auto-staked._ In order to not have to regularly perform the previous action, a neuron can also choose to auto-stake its maturity. This means that all new maturity will automatically be added to the staked maturity. + + + +The (same)[_maturity modulation_](https://learn.internetcomputer.org/hc/en-us/articles/34084120668692#01JY1DDWXPKKD5JHH927Z683D0) applies both to NNS neurons and SNS neurons. In both scenarios, the function of maturity modulation will be influenced by the ICP/cycles conversion rate. For more details, refer to [maturity modulation](https://learn.internetcomputer.org/hc/en-us/articles/34084120668692#01JY1DDWXPKKD5JHH927Z683D0). + +#### Neuron visibility + +All SNS neurons are _public._ + +## Governance participation + +The main purpose of a neuron is to participate in governance. A neuron with a minimal stake can do so by submit and vote on a [proposals,](https://learn.internetcomputer.org/hc/en-us/articles/34146571133204) or by participating in governance via the liquid democracy. + +### Voting + +A neuron is eligible to vote if it has a minimum staked ([defined in the SNS's settings](https://learn.internetcomputer.org/hc/en-us/articles/34142964565396)). An eligible neuron can _vote_ on a proposal by choosing to adopt or reject it. As a neuron can also delegate voting (see next paragraph), this is sometimes also called _direct voting._ + +As stated above a neuron's eligibility and voting power is dependent on its state and computed at proposal submission time. For more details how these votes are processed in terms of ballots, refer to[ SNS proposals](https://learn.internetcomputer.org/hc/en-us/articles/34146571133204). + +### Following / vote delegation + +Users may not have the time or knowledge to participate in all voting decisions. Therefore, instead of directly voting on proposals, neuron holders may choose to _delegate_ their vote to other neurons that they trust with certain decisions. This concept, where a neuron follows the decisions of some other neurons, is called _following_. Collective decision making which combines the direct execution with dynamic delegation mechanisms for voting rights is called liquid democracy. + +Following works as in the NNS and you can refer to an explanation video how it can be set on the NNS dapp [here](https://learn.internetcomputer.org/docs/current/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-following-other-neurons). + +#### Following rules + +A neuron can be configured to vote automatically by following the voting decision made by a group of other neurons, called _followees_. In the SNS, following is currently based on [proposal types](https://learn.internetcomputer.org/hc/en-us/articles/34146571133204). + +A neuron will only cast a "Yes"-vote if _more than half_ of the neurons within the followee-group voted Yes. A neuron will only cast a "No"-vote if _at least half_ of the neurons within the followee-group voted No. + +Your neuron will follow when there are enough votes to make a decision whether it is a ADOPT or REJECT. For example, if you follow 10 neurons on a topic: +\- Your neuron only votes to adopt if at least 6 out of the 10 neurons vote to adopt. +\- Your neuron only votes to reject a proposal if at least 5 out of the 10 reject the proposal. +\- If less than 5 neurons (out of your 10 followed) vote at all, your neuron will not cast any vote. + +This should be considered when choosing to follow multiple neurons on a topic. It might be better to follow fewer neurons, and it can be more beneficial to follow an odd number of neurons than an even number. + +#### Following "catch-all" + +In addition to setting following for individual topics, neurons may also define a catch-all follow rule which is triggered for proposals with topics for which no other explicit follow rule has been defined. +However, the _catch-all follow rule does not include critical proposal types_. + +The catch-all follow rule is only applied for proposal topics with no other explicit choice. For example, let's assume neuron A follows neuron B for the catch-all and neuron C on the topic dapp upgrade. If B votes on a dapp upgrade proposal but C does not, no vote will be cast for A. +The catch-all follow rule does not apply for critical proposals. For example, if neuron A follows neuron B for the catch-all and B votes on a treasury transfer proposal (which is critical, see [SNS Proposals](https://learn.internetcomputer.org/hc/en-us/articles/34146571133204)), no vote will be cast for A. If neuron A intends to also follow B on such decisions, the user has to explicitly choose to also follow B on the treasury type. + + + +It is in each neuron's interest to follow other neurons that support the best interests of the project and their own economic interests. + diff --git a/.migration/learn-hub/how-does-icp-work/sns/proposals.md b/.migration/learn-hub/how-does-icp-work/sns/proposals.md new file mode 100644 index 00000000..94614d17 --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/sns/proposals.md @@ -0,0 +1,145 @@ +--- +learn_hub_id: 34146571133204 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34146571133204-Proposals" +learn_hub_title: "Proposals" +learn_hub_section: "SNS - Service Nervous System" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# Proposals + +Proposals are suggestions of how to evolve the dapp that an SNS governs and the SNS DAO itself. They are thus the integral part of managing a dapp as a decentralized community. + +The proposal lifecycle in SNSs closely resembles the one for [NNS proposals](https://learn.internetcomputer.org/hc/en-us/articles/34084113508500). In contrast to the NNS, there are two main distinguishing factors for SNS proposals. First, SNSs have a notion of _proposal criticality -_ some proposal topics are defined to be critical and follow stricter voting rules. Second, to ensure that SNSs are flexible for the needs of different dapps that they govern, SNSs distinguish between has _Built-in proposals_ that are the same in each SNS and _custom proposals_ that can be defined by each SNS community for their specific needs. + +## Proposal lifecycle + +The lifecycle of SNS proposals closely resembles the one from NNS and goes through the following high level flow: + + 1. An eligible neurons submits a proposal. + 2. All other eligible neurons can vote on the proposal. + * Voting can be done by direct voting or by delegating voting power to other neurons + 3. A proposal is decided early when it has sufficient support for adopting or rejection. Otherwise the proposal is decided when the defined voting period is reached, which follows the [wait-for-quiet](https://learn.internetcomputer.org/hc/en-us/articles/34084113508500/h_01JJ2GW8QMPCY5PCV3X96Q1Y79) approach. + 4. Even if a proposal is decided early, voters can cast their vote until the end of the voting period to for getting voting rewards. + 5. An adopted proposal is automatically executed on-chain. + + + +The criteria for proposal decision as well as the voting period in Step 3 depend on the proposal's topic as explained next. + +### Proposal criticality + +In contrast to the NNS, the SNSs distinguish different rules for the proposals' decision, based on whether the proposal is _critical_. + +Criticality is defined based on proposal topics. That is, each proposal has a topic and each topic is either critical or non-critical. Proposals with a critical topic are also called "critical". They follow more strict rules to ensure they are only passed with broad community consensus. + +#### Voting thresholds + +Non-critical proposals can be passed if 3% of the total voting power votes yes and 50% of the exercised voting power votes yes. + +Critical proposals can only be passed if 20% of the total voting power votes yes and 67% of the exercised voting power votes yes. + +#### + +#### Voting period + +The voting period for critical proposal types is 5-10 days and cannot be changed by the SNS. In contrast, for non-critical proposals the default is 4-8 days and this can be adjusted by each SNS DAO. + +Critical proposal have a longer voting period as they require a larger voting participation and it is therefore beneficial to give voters a bit more time to participate. + +As in the NNS, for all proposals the [wait-for-quiet algorithm](https://learn.internetcomputer.org/hc/en-us/articles/34084113508500) ensures that controversial proposals will have a longer voting period (up to 10 days for critical proposals) while proposals where everyone agrees on have a shorter voting period (5 days for critical proposals). + +#### Catch-all following + +Vote delegation is based on proposal topics and, in contrast to the NNS, there is no longer any notion of a "catch-all" following that covers multiple proposal topics. +However, SNS vote delegation used to be based on proposal types, which may still be used by some neurons. This old legacy way of vote delegation supported a "catch-all following" that covered all types, except for the critical proposals. + +## Built-in and custom proposals + +An SNS comes built-in proposals called built-in proposals and SNS-specific custom proposals. + +### + +### Built-in SNS proposals + +These proposals are provided as part of the SNS framework and thus all SNS DAOs have them. + +Built-in proposals also have pre-defined proposal topics, also deciding on the proposal's criticality (see above). This ensures that the same built-in proposal has the same topic in all SNS DAOs, which makes it easier for users of one SNS to quickly navigate another SNS. + +Built-in proposals include: + + * Motion proposals for opinion polls + * Proposals to change the SNS's settings and metadata + * Proposals to upgrade the SNS framework canisters + * Proposals to register and deregister dapp canisters under SNS control, as well as to change the dapps' settings + * Proposals to move treasury funds or mint new tokens + + + +You can find more details on all built-in SNS proposals, including their types and how to submit them in the [developer documentation.](https://internetcomputer.org/docs/building-apps/governing-apps/managing/making-proposals) All the proposals used to manage an SNS are executed on the SNS governance canister, so for the most up-to-date definition of SNS proposals, it helps to have as a reference the [interface for the governance canister](https://github.com/dfinity/ic/blob/master/rs/sns/governance/canister/governance.did), where you can find all proposals defined in the type `Action`. + +### Custom SNS proposals + +Each SNS community might have functions that they would like to only execute if the SNS DAO agrees on it, but that might be very dapp-specific. _Custom proposals_ , also called _generic proposals_ , _generic functions_ , or _generic nervous system functions_ , allow a flexible way for SNS communities to define such functions. + +Some examples: + + * A dapp may have lots of canisters to maintain. For example, there may be one canister for each user, in which case they may want to apply upgrades through an orchestrator canister. For this workflow, they would have to tell this orchestrator what the user-canisters should be upgraded to and when to trigger this upgrade. In a DAO-governed dapp, this should happen via proposal. + * Developers might want the DAO to be the only entity that can elect moderators, call certain methods, make certain payments, etc. + + + +For all these cases, SNS DAOs can use generic proposals. Fundamentally, a custom proposal is just a call to a method on a canister with a certain argument. This means that one can do anything with a generic proposal as long as one can tell the SNS governance canister which method to call. + +In addition, since the governance canister is not aware of what a generic proposal does or in which context it will be applied, a custom proposal also has to define a validation method and canister. This method is called whenever such a generic proposal is submitted and if the validator method fails, the proposal will not be put to vote in the SNS. + +#### Lifecycle of custom proposals + +To use a custom proposal, it first needs to be added to the SNS governance system. This means that the SNS DAO needs to approve that this is a proposal that should be supported going forward. This is also due to the fact that there are a few important, security-critical considerations to make when adding a generic proposal. You can find some of these considerations in the [developer documentation](https://internetcomputer.org/docs/building-apps/governing-apps/managing/making-proposals#security-considerations-when-designing-generic-proposals). + +All SNS proposals have assigned topics that are used for filtering and for vote delegation. Since generic proposals are SNS-specific, each SNS community must define which topic fits a new generic proposal best. This is done when the generic proposal is added. Later the community can re-assign a proposal to a new topic by proposal. + +To use a generic proposal, i.e., submit such a proposal, one uses the “execute generic nervous system function” proposal type and specifies which of the registered generic proposals should be used. + +Finally, custom proposals can then also be removed again from SNS governance if they are not needed anymore. + +All of this handling of custom proposals is done by built-in proposals that are explained in more detail in the [developer documentation](https://internetcomputer.org/docs/building-apps/governing-apps/managing/making-proposals#generic-proposals). + +## Proposal topics + +Each SNS proposal is assigned to a _proposal topics_. There are seven proposal topics that are defined as part of the SNS framework and thus the same for all SNSs. + +A proposal's topics also decides whether the proposal is [critical](https://learn.internetcomputer.org/hc/en-us/articles/34146571133204/h_01K0RK6HWZ0N9HN0EH19P48K44). + +Learn more details on how SNS topics were introduced and how they facilitate vote delegation in this tutorial + +#### Critical proposal topics + +Each SNS has the following **critical proposal topics**. + + * **Critical Dapp Operations** : Proposals to execute critical operations on dapps, such as adding or removing dapps from the SNS, or executing custom logic on dapps. + * **DAO Community Settings** : Proposals to set the direction of the DAO by tokenomics & branding, such as the name and description, token name, etc. + * **Treasury and Asset Management** : Proposals to move and manage assets that are DAO-owned, including tokens in the treasury, tokens in liquidity pools, or DAO-owned neurons. + + + +#### Non-critical proposal topics + +In addition, each SNS has the following **non-critical topics**. + + * **Application Business Logic** : Proposals that are custom to what the governed dapp requires. + * **Dapp Canister Management** : Proposals to upgrade the registered dapp canisters and dapp upgrades via built-in or custom logic and updates to frontend assets. + * **Governance** : Proposals that represent community polls or other forms of community opinion but don’t have any immediate effect in terms of code changes. + * **SNS Framework Management** : Proposals to upgrade and manage the SNS DAO framework. + + + +#### Assignment of proposal types to topics + +Built-in proposals have a fixed assigned topic. This means that in each SNS the same built-in proposal has the same topic. + +For custom proposals, the SNS community needs to assign a topic when the custom proposal is added to governance. This means in particular that two SNSs could have a very similar or even the same custom proposal but have it assigned to different topics. + +For a given SNS where you have a neuron controlled on the NNS dapp, you can find which proposals are assigned to which topic by navigating to `Voting Delegation` in the neuron detail page and clicking on `View topic definitions`. + diff --git a/.migration/learn-hub/how-does-icp-work/sns/rewards.md b/.migration/learn-hub/how-does-icp-work/sns/rewards.md new file mode 100644 index 00000000..25de3b7a --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/sns/rewards.md @@ -0,0 +1,102 @@ +--- +learn_hub_id: 34143058069396 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34143058069396-Rewards" +learn_hub_title: "Rewards" +learn_hub_section: "SNS - Service Nervous System" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# Rewards + +The full potential of tokenization can be unlocked by a tokenized open governance system, where tokens can be staked to participate in voting. Anyone with staked tokens can submit and vote on governance [proposals](https://learn.internetcomputer.org/hc/en-us/articles/34146571133204) for the dapp governed by the SNS DAO. + +SNS governance empowers developers, users, and investors to collectively shape the dapp's future by voting on proposed features. Staked token holders are incentivized to vote strategically, considering the long-term value of both the tokens and the dapp. + +There are two categories of rewards: + + * **Voting rewards** to incentivize users to take part in SNS governance. + * **User rewards** to incentivize dapp users to become early adopters and active users of the dapp that is governed by the SNS. + + + +The reward scheme is based on the principles for [voting rewards used in the NNS](https://learn.internetcomputer.org/hc/en-us/articles/34142993417108), flexibly configurable for each SNS. + +## Voting rewards + +The SNSs leverage the [NNS voting reward scheme ](https://learn.internetcomputer.org/hc/en-us/articles/34142993417108)with the flexibility to configure the scheme to the DAO's needs. Hence, in the following this guide goes through the features of the NNS and describes how it is adapted and made configurable for the SNS. Unless otherwise stated, the approach and formulae are the same as for the NNS. As for the NNS, it is possible to change the SNS configuration by an SNS governance proposal. + +### Determination of the total reward pool + +The impact of changing the parameters of the reward function can be simulated in this [tool](https://docs.google.com/spreadsheets/d/1cTqgjGcG5rEQ5kRGprpdLvBL7ZdTqUDCuCi0QjClbgk/edit#gid=0). + +![graph_rewards_total_supply.png](https://learn.internetcomputer.org/hc/article_attachments/34143317612948) + + * Reward minimum r_min: rational value greater than or equal to 0. Default value: 0.00. + * Reward maximum r_max: rational value greater than or equal to r_min. Default value: 0.00. + * Start time for paying out rewards t_start: timestamp greater than or equal to genesis time of the SNS. The start time is set to the current time once the reward calculation is switched on. + * Time length t_delta which is greater than or equal to 0 and which determines the time transition length between r_max and r_min. Default value: 0 years. + * For a time t between t_start and t_start+t_delta the annualized reward as a percentage of total supply is R(t) = r_min + (r_max - r_min) [ (t_start + t_delta – t) / t_delta ]² + * For a time t after t_start + t_delta , you have R(t) = r_min + * For the special case r_max = r_min the reward function is constant, namely R(t)=r_min + * The total pool of voting rewards for a given day is calculated as SNS supply (total supply of SNS tokens) * R(t) / 365.25. + * Voting rewards are minted, i.e. generating new supply once the according maturity is converted to the SNS token. In case that the SNS would like to stop a token supply increase after t_start + t_delta the SNS should set r_min = 0. + + + +### Voting power of neurons + + * Required minimum dissolve delay for voting dd_min: integer value greater than or equal to zero. Default value: 6 months. + * Maximum dissolve delay dd_max: integer value greater than or equal to dd_min. Default value: 8 years. + * Maximum dissolve delay bonus: + * ddb_max rational value greater than or equal to 1. Default value: 2. + * The special case ddb_max = 1 results in no dissolve delay bonus. + * Maximum age a_max: integer value greater than or equal to 0. Default value: 4 years. + * Maximum age bonus ab_max rational value greater than or equal to 1. Default value: 1.25. + * The special case ab_max = 1 results in no age bonus. + + + +### Allocation of reward pool + + * The reward pool is allocated in proportion to the voting power of proposals that are settled on this day (same as for the NNS). + * If on a particular day no proposal was submitted then rewards will be carried over to the next day. + * NNS has reward weights for different proposal types. In the current version of the SNS reward scheme this functionality is not available. + + + +There is a flag which activates the calculation and distribution of voting rewards, as an SNS might choose to go through a ramp-up period without voting rewards, or with no voting rewards at all. + +## Setting voting reward parameters + +Voting reward parameters are defined as part of the nervous system parameters that define the[ individual settings for a given SNS instance](https://learn.internetcomputer.org/hc/en-us/articles/34142964565396). + +The following table provides an overview of all relevant parameters which are collectively called _VotingRewardsParameters_ , linking the notation of this article to full names used in the implementation. + +**Parameter** | **Full name in _VotingRewardsParameters_** +---|--- +r_min | _initial_reward_rate_basis_points_ +r_max | _final_reward_rate_basis_points_ +t_start | _start_timestamp_seconds_ +t_delta | _reward_rate_transition_duration_seconds_ + +When _VotingRewardsParameters_ is not populated, voting rewards are disabled. + +The following provides an overview of the relevant parameters for the determination of voting power. + +**Parameter** | **Full name in _VotingRewardsParameters_** +---|--- +dd_min | neuron_minimum_dissolve_delay_to_vote_seconds +dd_max | max_dissolve_delay_seconds +ddb_max | To be added, once implemented. +a_max | max_neuron_age_for_age_bonus +ab_max | To be added, once implemented. + +## User rewards + + * The purpose of user rewards is to foster early adoption and active usage of the SNS. Given that the meaning of usage and the according user rewards can vary greatly across individual SNSs, there is a very simple set-up. + * Some tokens (reserved for user rewards) can be held in an account that is owned by an SNS-controlled canister. This canister can then codify when the rewards are paid out and to whom. + * This solution allows paying out existing (not newly minted) tokens. Triggering minting for user rewards is currently not supported, this functionality may be added in a future version. + + + diff --git a/.migration/learn-hub/how-does-icp-work/sns/sns-service-nervous-system.md b/.migration/learn-hub/how-does-icp-work/sns/sns-service-nervous-system.md new file mode 100644 index 00000000..cd40b8cd --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/sns/sns-service-nervous-system.md @@ -0,0 +1,71 @@ +--- +learn_hub_id: 34084394684564 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34084394684564-SNS-Service-Nervous-System" +learn_hub_title: "SNS - Service Nervous System" +learn_hub_section: "SNS - Service Nervous System" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# SNS - Service Nervous System + +The Service Nervous System (SNS) framework enables creating and maintaining decentralized autonomous organizations (DAOs) to govern dapps. An SNS consists of an open, permissionless governance system that can control a dapp, and of a built-in governance token that is unique to each SNS. + +Any dapp on the Internet Computer can be handed over to an SNS with the result that the dapp is owned and controlled by a community. + +## What is a Decentralized Autonomous Organization (DAO)? + +A DAO is an organization whose members – typically holders of the governance token – collectively decide how the organization or the product evolves. Example scenarios: + + * 10'000 token holders each deposit crypto into a smart contract and vote on what to purchase with the total. + * 1 million token holders control a decentralized version of Twitter where token holders propose and vote on feature updates. + + + +A DAO can take the role of carrying out community-driven decisions on when and how to update the code that shapes the organization or product. + +## What is a Service Nervous System (SNS)? + +An SNS is a powerful software framework that enables a DAO community to govern smart contracts and decentralized apps (dapps) running on the Internet Computer completely onchain. + + * A dapp controlled by an SNS DAO is governed by SNS token holders submitting and voting on onchain proposals. No one developer or group of people controls the dapp, rather the dapp is controlled by voting via tokens. + * There can be many SNSs on ICP. Any developer can hand over the control of their dapp to an SNS DAO. Doing so gives control to DAO token holders. + + + +Generally, for each dapp that is under SNS DAO control, there is one SNS DAO. The SNS DAO works very similarly to the [NNS DAO that governs ICP. ](https://learn.internetcomputer.org/hc/en-us/articles/33692645961236)DAO participants are called [neurons](https://learn.internetcomputer.org/hc/en-us/articles/34084687583252) and all neurons can suggest and vote on suggestions how to evolve the dapp that are called [proposals](https://learn.internetcomputer.org/hc/en-us/articles/34084705977876). + +### What can be controlled by an SNS DAO? + +The core purpose of an SNS DAO is to govern a dapp, i.e., decide on the code of that dapp, including configuration, data, and frontend. Moreover, the SNS DAO makes decisions on the DAO itself, for example on how to change the DAO [tokenomics](https://learn.internetcomputer.org/hc/en-us/articles/34088279488660). More technically, there are [native proposals](https://learn.internetcomputer.org/hc/en-us/articles/34146571133204) that are common to all SNSs, such as proposals to upgrade the DAO-controlled dapp canisters, change governance rules, or making transfers from the treasury to open a liquidity pool on a DEX. In addition, each SNS can define [custom proposals](https://learn.internetcomputer.org/hc/en-us/articles/34146571133204) that are specific to the dapp's needs. A proposal can be defined to call any method on any canister. This allows, for example, to define proposals that orchestrate upgrades of dapps with many canisters. + +### SNS framework + +The[ SNS framework](https://learn.internetcomputer.org/hc/en-us/articles/34140764336788) is built into ICP and allows anyone to hand over their dapp to an SNS DAO. It comes with a pre-defined path of how an SNS is launched and results in a SNS DAO instance. Each SNS includes a stake-based governance system, that orchestrates decision making and changes, and a ledger that defines a unique token for each SNS. + +The framework ensures that all SNSs run code that is trustworthy and that all SNSs run the same code. This not only simplifies verification that the code is correct and does what it should but also has the advantage that DAOs are more user-friendly - a user that used one SNS will likely have a good intuition how to participate in a second SNS. Despite all SNSs using the same code, each SNS community can choose their own unique tokenomics and governance rules by parameters that can be set for each SNS DAO. Refer to [SNS framework and architecture](https://learn.internetcomputer.org/hc/en-us/articles/34140764336788) for more details. + +### SNS launch + +As mentioned above, the SNS framework includes a process that defines how to launch an SNS. To decentralize a dapp, the dapp is handed over to the Internet Computer together with an NNS proposal defining the details of the SNS launch and the initial configuration of the SNS DAO to be created. On a high level, the following things happen during a successful SNS launch: + + * the canisters for a new SNS DAO are created and installed + * the governance control is distributed to users in a decentralization swap that + * collects initial treasury funds in the form of ICP + * gives participants a share of the governance control in the form of SNS neurons + * the dapp's control is handed over to the new SNS + + + +Refer to the article on [SNS launch](https://learn.internetcomputer.org/hc/en-us/articles/34141180048404) for more details about these events and to [SNS decentralization swap](https://internetcomputer.org/docs/current/developer-docs/daos/nns/using-the-nns-dapp/nns-dapp-additional-features#sns-decentralization-swaps) for a tutorial on how you can participate in an SNS launch. + +### SNS governance + +After an SNS launch, the control of both the dapp it governs and the SNS canisters shifts from a single entity (like the developer) to the decentralized SNS community. This community then determines the future of the dapp's functionality, the behavior of the SNS canisters, and any modifications to either. Any changes to the dapp and the SNS can only be made by [proposals](https://learn.internetcomputer.org/hc/en-us/articles/34084705977876) and are decided on by the SNS's [neurons](https://learn.internetcomputer.org/hc/en-us/articles/34084687583252). + +The initial neuron holders include holders of initial neurons (e.g., used for the original developer team of the dapp) as well as the participants of the swap. Over time, more users may stake SNS tokens and participate in governance. + +### Resources + +There are different places where you can learn more about existing and upcoming SNS launches. For example, you can find all launched SNSs on the [Internet Computer dashboard](https://dashboard.internetcomputer.org/sns) and you can find and participate in ongoing launches on the [NNS dapp launchpad](https://nns.ic0.app/launchpad/). + diff --git a/.migration/learn-hub/how-does-icp-work/sns/tokenomics.md b/.migration/learn-hub/how-does-icp-work/sns/tokenomics.md new file mode 100644 index 00000000..585c724c --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/sns/tokenomics.md @@ -0,0 +1,129 @@ +--- +learn_hub_id: 34088279488660 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34088279488660-Tokenomics" +learn_hub_title: "Tokenomics" +learn_hub_section: "SNS - Service Nervous System" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# Tokenomics + +Each SNS can be individually configured with [parameters](https://learn.internetcomputer.org/hc/en-us/articles/34142964565396) that define, among other things, the tokenomics of an SNS and the dapp that it governs. + +## What is tokenomics? + +A token is a digital asset on a blockchain. Tokenomics describes the economics of a token system on a blockchain. It is a game changer for decentralized autonomous organization (DAOs) compared to traditional apps running on a Web 2.0 infrastructure, because it enables the introduction of new incentive systems and use cases. Tokenizing a DAO allows, for instance, that anyone in the world can purchase a DAO's tokens and thereby contribute to the initial funding for the DAO. Moreover, tokens can be tranferred to early adopters and active users, which will help attract users. + +Tokenomics covers a wide range of topics, such as + + * How tokens are used. + * Allocation of tokens to participants of the DAO. + * Incentive mechanisms, e.g., providing tokens to early adopters. + * Development of token supply & demand over time. This includes creating new tokens (minting) and destroying tokens (burning). + + + +### Supply and demand + +The supply of a token is defined as the amount which token holders are willing to sell at a given price. Likewise, token demand is the amount of tokens which buyers are willing to buy for a given price. The following graph depicts the typical relationship between the supply, demand and price for an example good, which in our case could be a token priced in USD. + +![graph_supply_demand.png](https://learn.internetcomputer.org/hc/article_attachments/34146812547476) + +_(Image source: epthinktank.eu)_ + +Typically supply increases with increasing prices. For example, if the price of Bitcoin increases, typically more Bitcoin holders will be willing to sell at the higher price on the market. On the other hand, demand typically decreases with increasing prices. The intersection of the two curves determines the so-called equilibrium price, depicted by P_2 in the picture. + +How does it end up at the equilibrium price? + + * If P_1 > P_2: There is a surplus, i.e., more supply than demand. This creates downward pressure on the price. + * If P_3 < P_2: There is a shortage, i.e., more demand than supply. This creates upward pressure on the price. + + + +### Token emission over time + +A token emission schedule defines the rate at which new tokens are minted over time. The design of a token emission schedule is crucial for the success of a DAO. + +On the one hand, token emissions generate _liquidity_ of tokens. It should be ensured that sufficient amounts of tokens are available from the start so that people can participate in activities on the DAO. + +On the other hand, token emissions contribute to the token supply and hence influence the token price. Therefore, limiting the token emission schedule can have a positive impact on the token price. + +As a consequence, emission schedules are typically designed as follows: Initially, high amounts of tokens are issued to kickstart the token economy and to incentivize early participation. Over time, the marginal increase of the token supply goes down to limit the impact on the token price and to create scarcity, i.e., limited availability. + +### Token use cases + +Tokens can cover many different (potentially overlapping) use cases. For example + + * **Governance** : tokens may give holders the right to vote on proposed changes of a DAO. +To incentivize long-term thinking and commitment, systems often require staking of tokens. Staking means that token holders lock up a portion of tokens for a period of time. In exchange, stakers can earn rewards. + * **Currency** : a form of digital money that functions as a medium of exchange, unit of account, and store of value. + * **Operations** : facilitate operations on the blockchain, for example to cover resource consumption with fees to store information and execute transactions. + * **Decentralized Finance (DeFi)** : financial functions (e.g. lending, saving, trading) on a blockchain. DeFi tokens incentivize users to facilitate these functions, e.g. providing liquidity. + * **Social Finance (SoFi)** : tokens underpinning social networks. This includes the tokenization of popularity & reputation. For example participants could receive tokens if they have a lot of followers or views. + + + +## Tokenomics aspects to consider in a DAO + +In a DAO, (at least) the following aspects are important for tokenomics. + +### Token utility + +Define concisely for which use cases the token (or several tokens) of the DAO will be used (see prior section on use cases). In particular, it should be considered how the token(s) could be used for + + * Participation in governance. + * Rewarding active participation in services offered by the DAO. + * Rewarding contributions to the growth of the DAO. + + + +### Initial token allocation + +For the initial token allocation, i.e., defining which groups/accounts should receive how many tokens, consider the following main blocks. + + * **DAO treasury** : these are tokens which are at the disposition of the DAO. They can be used according to predefined rules defined in the protocol of the DAO or distributed ad-hoc subject to voting. For example, they might be used for community bounties & user rewards. + * **Decentralization swap** : distribution to the community via an initial or subsequent decentralization swap. + * **Seed funders** : distribution to funders (if you choose to have them) who invested in the project prior to the launch of the DAO. + * **Funding development team** : developers who created the initial version of the DAO. + + + +To facilitate a healthy DAO from the start the initial allocation should ensure the following. + + * At least as many tokens are allocated to the decentralization swap as granted to the seed funders and the funding development team (enforced at the time of SNS initialization). + * A significant part of the tokens is allocated to the DAO treasury, allowing the treasury to incentivize and reward users over time. + + + +### Voting power and decentralization + +The voting power should be distributed over many, independent entities such that there is not one single or a few entities that can decide by themselves how the DAO evolves. + +As mentioned above, participation in governance typically requires the staking of tokens for a certain amount of time. To incentivize long-term thinking and commitment, DAOs can provide more voting power to those token holders who stake for a longer time period. The configuration of the voting power should also consider the (initial) allocation of tokens, to ensure decentralization from the start. For example, it should be ensured that the voting power of the funding developer team is below 50% of the total voting power. + +Find more information on how to configure [voting rewards](https://learn.internetcomputer.org/hc/en-us/articles/34143058069396). + +### Are SNS tokens inflationary or deflationary? + +This depends on the specific SNS configuration. An SNS DAO can have both inflationary and deflationary pressures. + +Inflationary: + + * An SNS DAO can be set up to mint voting rewards for people who participate in governance (similar to ICP). + * An SNS DAO can mint tokens if voted on by SNS token holders. For example: a game mints 2% of total supply each year and distributes it among players. + + + +Deflationary: + + * SNS tokens are burnt for every transaction. + * Locking SNS tokens into neurons removes them from circulation. While not technically deflation, it acts as a deflationary pressure. + + + +## Additional resources + +On [this page ](https://wiki.internetcomputer.org/wiki/How-To:_SNS_tokenomics_configuration)you will find further material enabling teams to choose a suitable tokenomics set-up for their SNS DAO. It provides documentation links to SNS tokenomics key concepts as well as a SNS +tokenomics tool. + diff --git a/.migration/learn-hub/how-does-icp-work/tokens-governance/how-token-ledgers-work-on-the-internet-computer.md b/.migration/learn-hub/how-does-icp-work/tokens-governance/how-token-ledgers-work-on-the-internet-computer.md new file mode 100644 index 00000000..0a8fd7cc --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/tokens-governance/how-token-ledgers-work-on-the-internet-computer.md @@ -0,0 +1,126 @@ +--- +learn_hub_id: 44969820125972 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/44969820125972-How-Token-Ledgers-Work-on-the-Internet-Computer" +learn_hub_title: "How Token Ledgers Work on the Internet Computer" +learn_hub_section: "Tokens & Governance" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# How Token Ledgers Work on the Internet Computer + +## + +The Internet Computer supports decentralized token ledgers that power balances, transfers, transaction history, and fees for both the native ICP token and other fungible tokens. This article explains how those ledgers work from a user perspective — what they are, how they record transactions, how fees work, and why different address formats exist. + +## What Is a Ledger? + +A **ledger** on the Internet Computer is a canister that defines who owns a token and permanently logs every transfer or balance change. + +Unlike a traditional bank book kept privately by one company, ledgers on the Internet Computer are: + + * **Publicly verifiable** — anyone can see transaction history through explorers. + * **Append-only** — once a transaction is recorded it isn’t removed. + * **Transaction-centric** — each change to balances goes into a permanent history. + + + +Ledgers ensure that token ownership and movement are transparent, reliable, and tamper-resistant. On the Internet Computer, there is no single global ledger. Each token is managed by its own ledger canister, which is controlled by the entity that deploys and governs that token. While multiple implementations exist, this article describes the DFINITY-maintained ledger suite, which is the most widely used and underlies the ICP + +## Two Kinds of Ledgers and Addresses + +The Internet Computer uses different ledger designs and address formats for different kinds of tokens. The key distinction users encounter is between the ICP Ledger and ICRC Token Ledgers. + + +### ICP Token Ledger + +The ICP Ledger is the native ledger used to manage ICP, the Internet Computer’s native utility token. ICP is the token you stake for governance, convert to cycles to pay for compute, or send to other users. The ICP Ledger uses a single, flat address format called an **AccountIdentifier** that uniquely identifies an account. + +### ICRC Token Ledgers + +While ICP itself is a token, it uses a dedicated native ledger. Most other fungible tokens on the Internet Computer use ledgers that follow the ICRC standard, which defines a common model for token balances, transfers, and addresses. + +These ledgers use a two-part account format: + + * A **principal** , which represents the identity of the holder (for example, a wallet). + * An optional **subaccount** , which lets a holder manage multiple internal accounts under the same principal. + + + +This account model gives wallets and services flexibility while keeping token handling consistent across different assets. + +## How Transactions Are Recorded + +Each ledger maintains its own append-only transaction log. Transfers and other token adjustments are added to the end of this log and never removed or rewritten. + +This design allows wallets and explorers to present a clear transaction history—similar to a bank statement—while enabling the history to be efficiently verified and cryptographically certified. + +As a result, users can reliably trace how their balance changed over time and independently verify past transactions. + +## +How Ledgers Scale: Archives and Indexes + +As ledgers grow over time, they accumulate a large number of transactions. To remain scalable and efficient, Internet Computer ledgers use additional components behind the scenes. + +### Archives + +Older transaction blocks may be moved into archive canisters. Archives were originally introduced to work around storage limits in individual canisters, and today they are primarily used to allow ledgers to scale beyond a single subnet. + + +From a user perspective: + + * The ledger still has a complete transaction history. + * Older transactions remain accessible through explorers and tools. + + + +Archiving is purely an internal optimization — it does not change balances, ownership, or the visibility of past transactions. + +### Index Canister + +Many ledgers are accompanied by an index canister, which is designed to make wallets and explorers faster and easier to use. + +The index organizes transaction data by address, allowing wallets to: + + * Quickly fetch all transactions related to a specific account. + * Display balances and history without scanning the entire ledger. + * Load transaction lists efficiently, even for long-lived accounts. + + + +While the ledger itself remains the authoritative source of truth, the index enables smooth user experiences in wallets and dashboards. + +### How This Fits Together + + * The ledger records transactions and balances. + * Archives store older transactions for scalability. + * The index helps wallets and explorers retrieve data efficiently. + + + +Together, these components ensure that ledgers on the Internet Computer remain transparent, scalable, and user-friendly — even as transaction history grows over time. + + +## Transaction Fees: What They Are and Who Pays + +Most token transfers on ledgers incur a small transaction fee. This helps deter spam and ensures that the cost of operating the ledger is shared by users making transfers. + + * The sender usually pays the fee when initiating a transfer. + * Fees are either burned (permanently removed from the total supply) or collected in a designated fee account, depending on how the token’s ledger is configured. + + + +Fees are generally small and predictable, and you’ll see them reflected in the final balance after a transfer. + +## What This Means for You + +As a wallet user or token holder on the Internet Computer, understanding ledgers helps you: + + * Know why and how your balance changes after transfers. + * Use the correct address format for different tokens. + * Trust that your transaction history is transparent and verifiable via explorers. + + + +Whether you’re sending ICP, receiving a stablecoin, or inspecting your transaction history, ledgers are the foundational technology that makes token ownership and movement trustworthy on the Internet Computer. + diff --git a/.migration/learn-hub/how-does-icp-work/tokens-governance/tokenomics.md b/.migration/learn-hub/how-does-icp-work/tokens-governance/tokenomics.md new file mode 100644 index 00000000..f0c00573 --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/tokens-governance/tokenomics.md @@ -0,0 +1,81 @@ +--- +learn_hub_id: 34090810571284 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34090810571284-Tokenomics" +learn_hub_title: "Tokenomics" +learn_hub_section: "Tokens & Governance" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# Tokenomics + +## The ICP utility token + +The Internet Computer Protocol (ICP) makes use of a utility token called ICP. This token is used as follows in the protocol: First, any ICP holder can participate in the [governance of the Internet Computer](https://learn.internetcomputer.org/hc/en-us/articles/33692645961236) by staking ICP and then vote on or submit governance proposals and earn [voting rewards](https://learn.internetcomputer.org/hc/en-us/articles/34142993417108). Second, ICP can be transformed into cycles and pay for Internet Computer resources. Third, ICP tokens are used to reward node providers who operate node machines that contribute to the Internet Computer. Last but not least, ICP can be used to participate in [token swaps of decentralized autonomous organizations (SNS DAOs)](https://learn.internetcomputer.org/hc/en-us/articles/34141180048404) on the IC. These four protocol use cases are eloborated on in the following. However, ICP can of course also be used as a medium of exchange to pay for goods and services such as NFTs, subscriptions, etc. + +## Governance and voting rewards + +Anyone can participate in the governance of ICP by staking ICP tokens in so-called [neurons](https://learn.internetcomputer.org/hc/en-us/articles/34084120668692). Neuron holders can vote on proposals, which are suggestions on how ICP should be changed. The neurons’ voting power for decision making is proportional to the number of ICP staked inside and some other characteristics of the neuron such as the staking duration. The increased voting power for neurons with longer staking time creates an incentive to vote on proposals with the aim of driving decisions that maximize the value of their staked ICP over the long term. + +For participation in governance, the voting neurons' maturity increases. Maturity can then be used to mint ICP. Every day, the IC calculates a [voting reward](https://learn.internetcomputer.org/hc/en-us/articles/34142993417108) pot according to a schedule, which it then divides among all eligible neurons according to their relative voting power and participation. The schedule for voting rewards is designed to incentivize early adoption: Initially at genesis, maturity corresponding to 10% of the total supply of ICP is distributed in voting rewards on an annualized basis. Over the course of eight years, this number falls to 5%. + +As the daily reward amount is independent of the overall amount of staked ICP in the system and is distributed to neurons in proportion to their voting power and ratio of the proposals they voted on. This mechanism creates a natural incentive to stake ICP and participate in governance: the lower participation is the higher the rewards are. A significant part of staked ICP is staked for the maximum time of 8 years expressing the long-term commitment of these stakers. For current estimates of annualized voting rewards, refer to the ICP [Dashboard’s Governance page](https://dashboard.internetcomputer.org/governance). + +## Cycles as fuel for computation and other resources + +ICP can be used to pay for the usage of resources. More specifically, ICP tokens can be converted to **cycles** (i.e., burned), and these cycles are used by developers to pay for installing smart contracts, called canisters on ICP, and for the resources that canisters use (storage, CPU, and bandwidth). The cycle price is pegged to a basket of fiat currencies, so the conversion rate ICP to cycle fluctuates with the market price of ICP. Hence the cost to developers of acquiring fuel to run their application is predictable. + +In this so-called _reverse gas model_ of ICP, developers pre-pay costs by loading canisters with computation cycles. As a consequence, users can interact with a decentralized application (dapp) without needing tokens or dealing with seed-phrases. As cycles are stable in cost, developers know in advance how much they will need to spend on computation, storage, and other resources. + +## Node provider rewards + +ICP tokens are used to reward node providers—these are the entities that own and operate the computing nodes that run the Internet Computer Protocol. Node provider rewards are paid via newly minted ICP. The rewards they receive are fixed per node and tightly related to their actual costs. It depends on two parameters: + + 1. The location of the node, as hosting prices differ between locations. + 2. The type of the node, i.e., the hardware and connectivity specifications. + + + +To cover the investment and running cost of nodes, which occur in fiat currency terms, node provider rewards are specified in XDR, and are converted into ICP based on the average exchange rate over the last 30 days. + +### How the average exchange rate is computed + +The cycles minting canister fetches the ICP/XDR rate every 5 minutes from the exchange rate canister, which fetches the rates from various external sources. The cycles minting canister also stores the start-of-day rates (UTC). + +The 30-day-moving average uses the start-of-day rates for the past 30 days, this can be [verified in the code](https://github.com/dfinity/ic/blob/4344a924bcb12bc3d1510805dbb37391179df887/rs/nns/cmc/src/main.rs#L930). The current conversion rate can be viewed on the [ICP dashboard](https://dashboard.internetcomputer.org/network), or pulled automatically directly from the [CMC metrics](https://rkp4c-7iaaa-aaaaa-aaaca-cai.raw.icp0.io/metrics). + +## ICP ecosystem (SNS launch) + +The SNS framework enables developers to create an [SNS DAO](https://learn.internetcomputer.org/hc/en-us/articles/34084394684564) and to transfer control of their dapps unter the decentralized control of that DAO. + +As part of a so-called decentralization swap during an [SNS launch](https://learn.internetcomputer.org/hc/en-us/articles/34141180048404), users can commit some ICP to a new SNS DAO. In return, when the decentralization swap is complete, these users will receive tokens of the DAO with everyone paying the same price. Developers can specify a time period and minimum & maximum funding target of ICP to be collected, which determines when the swap is over. + +The ICP funds raised by the decentralization swap are retained within the reserves of the fully autonomous DAO, rather than being forwarded to the original developers of the dapp or service. These funds can be used to pay for future computation needs of the dapp and also to pay code bounties for future dapp enhancements. + +The SNS framework acts like rocket fuel for the ICP ecosystem. It provides easy and transparent access to exciting Web3 projects and channels funds to productive usage of the platform. + +## Development of total supply + +ICP has inflationary and deflationary mechanisms. Governance participants can convert voting rewards to newly minted ICP. Also, node providers receive rewards in the form of newly minted ICP tokens. On the other hand, ICP is converted to cycles (i.e., burned) in order to pay for computation and storage. This is depicted in the following picture. + +## ![deflation_inflation.png](https://learn.internetcomputer.org/hc/article_attachments/34277843713940) + +## + +In summary, there are the following mechanisms. + +Deflationary mechanisms: + + * Minting cycles to pay for compute and storage burns ICP to create cycles. + * Transaction fees for the ICP token. + * Fees for failed proposals of neurons; note that this only happens at disbursement or merging of neurons, so accumulated fees can persist for a while before visible in the total supply. + + + +Inflationary mechanisms: + + * Node providers are paid by minting ICP. + * [Voting rewards](https://learn.internetcomputer.org/hc/en-us/articles/34142993417108), once spawned and converted to ICP. + + + diff --git a/.migration/learn-hub/how-does-icp-work/tokens-governance/tokens-governance.md b/.migration/learn-hub/how-does-icp-work/tokens-governance/tokens-governance.md new file mode 100644 index 00000000..cb1a19e7 --- /dev/null +++ b/.migration/learn-hub/how-does-icp-work/tokens-governance/tokens-governance.md @@ -0,0 +1,21 @@ +--- +learn_hub_id: 34574082263700 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/34574082263700-Tokens-Governance" +learn_hub_title: "Tokens & Governance" +learn_hub_section: "Tokens & Governance" +learn_hub_category: "How does ICP work?" +migrated: false +--- + +# Tokens & Governance + +The Internet Computer's tokenomics model is centered around two native tokens: [cycles](https://learn.internetcomputer.org/hc/en-us/articles/34573913497108) and ICP. The ICP token plays a critical role in the decentralized network governance and operation. Decentralized applications (dapps) running on the Internet Computer can also use a token-based governance, based on their own, application-specific token. + +In this section, you will find articles describing: + + * [Tokenomics](https://learn.internetcomputer.org/hc/en-us/articles/34090810571284): the economic model of the Internet Computer, encompassing token creation, distribution, and usage that influence its value and overall ecosystem, + * [Network Nervous Systems](https://learn.internetcomputer.org/hc/en-us/articles/33692645961236): onchain decentralized autonomous organization (DAO) that governs the Internet Computer Protocol, + * [Service Nervous System:](https://learn.internetcomputer.org/hc/en-us/articles/34084394684564) framework for creating and maintaining DAOs to govern dapps on the Internet computer. + + + diff --git a/.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/community-built-dashboards.md b/.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/community-built-dashboards.md new file mode 100644 index 00000000..3c24828e --- /dev/null +++ b/.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/community-built-dashboards.md @@ -0,0 +1,12 @@ +--- +learn_hub_id: 33152050043156 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/33152050043156-Community-built-dashboards" +learn_hub_title: "Community-built dashboards" +learn_hub_section: "Governance" +learn_hub_category: "How can I use ICP?" +migrated: false +--- + +# Community-built dashboards + + diff --git a/.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-add-an-icp-sub-account.md b/.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-add-an-icp-sub-account.md new file mode 100644 index 00000000..e9f48251 --- /dev/null +++ b/.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-add-an-icp-sub-account.md @@ -0,0 +1,42 @@ +--- +learn_hub_id: 42494280383252 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/42494280383252-How-can-I-add-an-ICP-sub-account" +learn_hub_title: "How can I add an ICP (sub-)account?" +learn_hub_section: "Governance" +learn_hub_category: "How can I use ICP?" +migrated: false +--- + +# How can I add an ICP (sub-)account? + +Logging into the NNS dapp using an Internet Identity creates a [main account](https://learn.internetcomputer.org/hc/en-us/articles/42493986016788) for you in the ICP ledger. + +You can create one or more linked _sub-accounts_ or attach a hardware wallet to your account. + +#### Step 1: Go on the 'Tokens' tab in the left menu. + +![](https://learn.internetcomputer.org/hc/article_attachments/42494309267860) + +#### Step 2: In the top table, select 'Internet Computer'. + +![](https://learn.internetcomputer.org/hc/article_attachments/42494280371732) + +#### Step 3: Select 'Add Account'. + +![](https://learn.internetcomputer.org/hc/article_attachments/42494309272084) + +#### Step 4: Select the type of account to add, which is 'New Account'. + + * **New Account** creates a new subaccount linked to your Main account address in the ledger. + * **New Account (Hardware Wallet)** adds a hardware wallet to your main account address in the ledger. + + + +#### Step 5: Enter an account name and hit 'Create'. + +![](https://learn.internetcomputer.org/hc/article_attachments/42494309273492) + +#### You now have a new account with this name in your list. + +![](https://learn.internetcomputer.org/hc/article_attachments/42494309276564) + diff --git a/.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-configure-a-neuron.md b/.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-configure-a-neuron.md new file mode 100644 index 00000000..81f94ff9 --- /dev/null +++ b/.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-configure-a-neuron.md @@ -0,0 +1,42 @@ +--- +learn_hub_id: 42755094620180 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/42755094620180-How-can-I-configure-a-neuron" +learn_hub_title: "How can I configure a neuron?" +learn_hub_section: "Governance" +learn_hub_category: "How can I use ICP?" +migrated: false +--- + +# How can I configure a neuron? + +After you [created a neuron](https://learn.internetcomputer.org/hc/en-us/articles/42754119358484), you can set it up and modify it. These are some of the attributes you can modify that influence the neuron's [voting power](https://learn.internetcomputer.org/hc/en-us/articles/34084120668692#h_01JJ26P5EEPSRQSN0Y3Q2Y975K) and state: + + * Start the dissolve delay timer by clicking **Start Unlock**. + * Increase the dissolve delay period by clicking **Increase Dissolve Delay**. + * Stop the dissolve delay after starting the unlock countdown by clicking **Lockup**. + + + +## How to start and stop dissolving the neuron + +Creating a new neuron does not automatically start the dissolve delay timer. If you want to start the timer countdown, you have to do so by explicitly clicking **Start Dissolving** on the neuron detail page. + +![](https://learn.internetcomputer.org/hc/article_attachments/42755787874452) + +For example, if you set a dissolve delay of 200 days and want to immediately begin the countdown, you should click 'Start Dissolving' as part of the process of creating the neuron. If you change your mind and want to stop a current countdown in progress, you can click **Stop Dissolving**. + +![](https://learn.internetcomputer.org/hc/article_attachments/42755787877908) + +After you click Stop Dissolving, you can click Start Dissolving again to resume the countdown without changing the existing dissolve delay period. + +If you start the dissolving of a neuron, the neuron's [age](https://learn.internetcomputer.org/hc/en-us/articles/34084120668692#h_01JJ26P5EEPSRQSN0Y3Q2Y975K) is set back to zero. Therefore, starting dissolving and stopping it again does not result in exactly the same neuron. + +## How to increase a neuron's dissolve delay + +No matter if a neuron is dissolving or non-dissolving, you can increase the lockup period by clicking Increase Dissolve Delay then select a longer dissolve delay. + +![](https://learn.internetcomputer.org/hc/article_attachments/42755787881364) + + + + diff --git a/.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-disburse-a-neuron.md b/.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-disburse-a-neuron.md new file mode 100644 index 00000000..275b899e --- /dev/null +++ b/.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-disburse-a-neuron.md @@ -0,0 +1,29 @@ +--- +learn_hub_id: 42754712016148 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/42754712016148-How-can-I-disburse-a-neuron" +learn_hub_title: "How can I disburse a neuron?" +learn_hub_section: "Governance" +learn_hub_category: "How can I use ICP?" +migrated: false +--- + +# How can I disburse a neuron? + +When the dissolve delay timer for a neuron reaches zero, it is **dissolved** and you can disburse the neuron’s stake and transfer its locked ICP utility token balance to the ledger account you specify. + +To disburse a neuron and return its ICP utility tokens: + +#### Step 1: On the [NNS dapp](https://nns.ic0.app/), go to the Neuron Staking tab and then the table Staked ICP. Then click on an dissolved neuron that has reach the ended of its dissolve delay period (indicated by 'Unlocked'). + +#### Step 2: Click **Disburse**. + +![](https://learn.internetcomputer.org/hc/article_attachments/42756391479956) + +#### Step 3: Type an address or select an account to receive the ICP utility tokens. + +![](https://learn.internetcomputer.org/hc/article_attachments/42756391484564) + +#### Step 4: Verify the transaction information, then click Confirm and Send. + +![](https://learn.internetcomputer.org/hc/article_attachments/42756391486228) + diff --git a/.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-disburse-maturity.md b/.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-disburse-maturity.md new file mode 100644 index 00000000..d787af7a --- /dev/null +++ b/.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-disburse-maturity.md @@ -0,0 +1,73 @@ +--- +learn_hub_id: 39755298701204 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/39755298701204-How-can-I-disburse-maturity" +learn_hub_title: "How can I disburse maturity?" +learn_hub_section: "Governance" +learn_hub_category: "How can I use ICP?" +migrated: false +--- + +# How can I disburse maturity? + +## Overview + +This tutorial is focused on NNS neurons. In SNS DAOs with voting rewards the concepts are very similar and the same tutorial might be helpful. + +As you stake a neuron in the NNS and participate in governance, by voting directly or by delegating your voting power to others, your neuron receives voting rewards in the form of [maturity that can be _disbursed_ or _staked_.](https://learn.internetcomputer.org/hc/en-us/articles/34084120668692-Neurons#01JJ7BJX36NH538SCDQFHSJSVD) + +## Disburse maturity + +When you have at least 1.05 of maturity that is not staked, you can disburse it. This operation burns the maturity and schedules the minting of new ICP tokens. After 7 days, new ICP will be minted to the selected destination address. This process is subject to a maturity modulation function - refer to [Voting rewards & maturity](https://learn.internetcomputer.org/hc/en-us/articles/34084120668692-Neurons#01JJ7BJX36NH538SCDQFHSJSVD) for details. + +For neurons managed by a Ledger hardware wallet, disburse maturity is under development. You can use spawn neuron in the meantime (see below). + +### How to disburse the maturity of you neuron + +#### Step 1: On the [staking page](https://nns.ic0.app/neurons/?u=qoctq-giaaa-aaaaa-aaaea-cai), navigate to the neuron whose maturity you want to disburse. + +Click **Disburse** in the **Maturity** section. + +![](https://learn.internetcomputer.org/hc/article_attachments/39755329006356) + +#### Step 2: In the form that opens, select the percentage of maturity to disburse and the destination account. + +![](https://learn.internetcomputer.org/hc/article_attachments/39755298688660) + +You can choose one of your associated accounts or manually enter any NNS account identifier. Manual input is available either as plain text or via QR code (found by clicking the **Receive** button on the wallet page). + +![](https://learn.internetcomputer.org/hc/article_attachments/39755298688916) + +For a given account, you can copy the account identifier on the account page as follows. + +![](https://learn.internetcomputer.org/hc/article_attachments/39755298690196) + +#### + +#### Step 3: After clicking **Disburse** , you see an overview where you can review and confirm the disbursement. + +#### ![](https://learn.internetcomputer.org/hc/article_attachments/39755298692116) + +#### Step 4: When a disbursement is in progress, a **View Active Disbursements** button appears in the **Maturity** section. + +#### ![](https://learn.internetcomputer.org/hc/article_attachments/39755329012116) + +This opens the **Active Disbursements** window, which shows all disbursements in progress, including their start time, destination address, and the amount of maturity being disbursed. + +![](https://learn.internetcomputer.org/hc/article_attachments/39755329016084) + +You cannot have more than 10 ongoing disbursements. If you have 10, you need to wait for at least one disbursement to finish before adding another. + + +## +Spawn new neurons + + +The old way of converting maturity into ICP utility tokens is via spawning the newly minted ICP into a neuron from where you can extract the ICP after 7 days. + +In the NNS dapp you can only see the option to spawn for Ledger controlled neurons because disburse maturity is not yet supported by the Ledger device. Going forward, spawning neurons might be deprecated for all use cases. + +#### Step 1: In the NNS dapp, open the **Neuron Staking** section, then select the neuron that has reached the required maturity. + +#### Step 2: Click **Spawn Neuron** , then follow the prompts to complete the process. + + diff --git a/.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-find-my-icp-token-accounts.md b/.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-find-my-icp-token-accounts.md new file mode 100644 index 00000000..6cb3b595 --- /dev/null +++ b/.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-find-my-icp-token-accounts.md @@ -0,0 +1,31 @@ +--- +learn_hub_id: 42493986016788 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/42493986016788-How-can-I-find-my-ICP-token-accounts" +learn_hub_title: "How can I find my (ICP) token accounts?" +learn_hub_section: "Governance" +learn_hub_category: "How can I use ICP?" +migrated: false +--- + +# How can I find my (ICP) token accounts? + +Logging into the NNS dapp using an Internet Identity creates a main account for you in the ICP ledger as well as in the other ledgers you might want to interact with. + +We show you how you can find your token account on the example of the ICP token. + +#### Step 1: Go on the 'Tokens' tab in the left menu. + +![](https://learn.internetcomputer.org/hc/article_attachments/42493986007700) + +#### Step 2: Select the token you would like to see in the right table. In this case, select 'Internet Computer'. + +![](https://learn.internetcomputer.org/hc/article_attachments/42494006887828) + +#### Step 3: You now see your main ICP account. + +When you log in for the first time, most likely your main account displays 0.00 for your ICP utility token balance. + +You can now [receive tokens](https://learn.internetcomputer.org/hc/en-us/articles/42494789123092), [send tokens](https://learn.internetcomputer.org/hc/en-us/articles/42499104466324), or [add another account](https://learn.internetcomputer.org/hc/en-us/articles/42494280383252). + +#### + diff --git a/.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-import-icrc-tokens.md b/.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-import-icrc-tokens.md new file mode 100644 index 00000000..2e1387b9 --- /dev/null +++ b/.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-import-icrc-tokens.md @@ -0,0 +1,74 @@ +--- +learn_hub_id: 42529262055700 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/42529262055700-How-can-I-import-ICRC-tokens" +learn_hub_title: "How can I import ICRC tokens?" +learn_hub_section: "Governance" +learn_hub_category: "How can I use ICP?" +migrated: false +--- + +# How can I import ICRC tokens? + +The [NNS dapp](https://nns.ic0.app/) focuses on providing a simple user interface where community members can interact with different on-chain governance systems deployed on the Internet Computer. + +If you want to hold tokens that are not in the default provided list, you can _import_ the token to your wallet. This is possible for any token that supports ICRC-1, which includes all ICRC-2 and ICRC-3 tokens. As a token is uniquely defined by its associated ledger, the first step in this process is to find the ledger's ID. + +## How do I find the relevant token ledger? + +The process of importing a token simply saves a list of token ledger canister IDs on your account, letting the NNS dapp know which tokens to fetch. Therefore, to import a token, you need the associated ledger canister ID. + +In addition, the NNS dapp relies on index canisters to display transaction histories. If your token has an index canister, you can also import the index canister ID, which will allow you to see the transaction history in the NNS dapp too. + +The NNS dapp accepts any token that supports the ICRC-1 standard. A token can pretend to be another token, so make sure to get the ledger canister ID from reputable places. + +There are several ways to find ledger canister IDs of ICRC-1 tokens. The tutorial video above mentions two. This is a more comprehensive list. + + * [ICPSwap](https://info.icpswap.com/swap): Curated list of tokens traded on ICPSwap updated by the ICPSwap SNS DAO. + * [ICP Tokens](https://www.icptokens.net/): Curated list of tokens traded on ICP-based DEXs updated by ICP Tokens. + * [ICP Dashboard](https://dashboard.internetcomputer.org/chain-fusion): List of all chain-key tokens (under Chain Fusion menu option) updated automatically. + * [nftGeek](https://t5t44-naaaa-aaaah-qcutq-cai.raw.icp0.io/tokens): Curated list of tokens traded on ICP-based DEXs updated by nftGeek. + * [CoinMarketCap](https://coinmarketcap.com/view/internet-computer-ecosystem/): The ICRC tokens that are listed on CoinMarketCap provide their ledger canister ID under 'Contract'. + * [CoinGecko](https://www.coingecko.com/en/categories/internet-computer-ecosystem): The ICRC tokens that are listed on CoinGecko provide their ledger canister ID under 'Contract'. + + + +## How do I import ICRC tokens? + +First, find the ledger canister ID of the token you want to import to your NNS dapp wallet. The list above covers most tokens deployed on the Internet Computer. Once you have its ledger canister ID, you may optionally look for its index canister to display the transaction history. + +Importing an index canister is completely optional. Many popular tokens do not have index canisters. + +#### Step 1: Sign into the NNS dapp and navigate to Tokens. In the table menu, click 'Import Token'. + +![](https://learn.internetcomputer.org/hc/article_attachments/42531028276628) + +If you want to hide the tokens you don't hold for better visibility, you can click the settings button at the top right corner of the table, and enable Hide zero balances. + +#### Step 2: Paste the ledger canister ID and optionally the index canister IDs to the corresponding input fields. + +If you don't provide the index canister ID now, you can add it any time in the future. + +![](https://learn.internetcomputer.org/hc/article_attachments/42531028279956) + +#### Step 3: Review and confirm that this is the token you wish to import. By clicking the link you can see the canister on the ICP dashboard. + +#### ![](https://learn.internetcomputer.org/hc/article_attachments/42531028282132) + + +Once your token was successfully imported, you can send tokens to your account. + +![](https://learn.internetcomputer.org/hc/article_attachments/42531028291348) + +Going back, you see all imported tokens in the Imported Tokens table. + +![](https://learn.internetcomputer.org/hc/article_attachments/42531056914708) + +## +How do I remove an imported token? + +You can add and remove tokens any time. + +Removing a token doesn't remove the asset itself. If you remove a token that has a balance above 0, you can always re-import it, and the asset will be accessible. However, the NNS dapp will not remember which tokens you imported and removed again, so you will need to remember any token you intend to re-import in the future. + +![](https://learn.internetcomputer.org/hc/article_attachments/42531028295188) + diff --git a/.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-log-into-the-nns-dapp.md b/.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-log-into-the-nns-dapp.md new file mode 100644 index 00000000..538f155e --- /dev/null +++ b/.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-log-into-the-nns-dapp.md @@ -0,0 +1,45 @@ +--- +learn_hub_id: 39615237318548 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/39615237318548-How-can-I-log-into-the-NNS-dapp" +learn_hub_title: "How can I log into the NNS dapp?" +learn_hub_section: "Governance" +learn_hub_category: "How can I use ICP?" +migrated: false +--- + +# How can I log into the NNS dapp? + +## Overview + +There are different ways to interact with the NNS to stake ICP tokens and participate in governance. + +This guide demonstrates how to interface with the NNS through the [NNS dapp](https://nns.ic0.app). You can interact with the NNS through other tools, such as [quill ](https://github.com/dfinity/quill)and [ic-js](https://github.com/dfinity/ic-js/tree/main/packages/nns). + +This section starts with a tutorial on how to connect and log in to the NNS dapp. + +## +Connect to the NNS using the NNS dapp + +To connect to the NNS using the NNS dapp, follow these steps which are also explained in the first minutes of the following video. + +#### Step 1: Open a browser and navigate to the [NNS dapp](https://nns.ic0.app). + +![](https://learn.internetcomputer.org/hc/article_attachments/39615243724180) + +#### Step 2: Click **Login** to connect to [Internet Identity](https://identity.internetcomputer.org/). + +#### + +![](https://learn.internetcomputer.org/hc/article_attachments/39615243724564) + +If you haven’t previously registered, you can click **Register with Internet Identity** to register. + +It is recommended that you add multiple devices and authentication methods to your Internet Identity. For example, register multiple physical devices like your computer and phone with a security key and using the authentication options that those devices—and browsers running on them—support. + + +For more information about creating an Internet Identity, see [how to use Internet Identity](https://identitysupport.dfinity.org/hc/en-us/articles/15430677359124-How-do-I-create-an-Internet-Identity-on-my-mobile-device). + +After you have registered, you can click **Login** to authenticate using your anchor and the authentication method—for example, a security key or fingerprint—you have registered. + +#### Step 3: Click **Proceed** to access to the Network Nervous System (NNS) dapp. + diff --git a/.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-receive-icp-tokens.md b/.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-receive-icp-tokens.md new file mode 100644 index 00000000..d66dea19 --- /dev/null +++ b/.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-receive-icp-tokens.md @@ -0,0 +1,102 @@ +--- +learn_hub_id: 42494789123092 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/42494789123092-How-can-I-receive-ICP-tokens" +learn_hub_title: "How can I receive ICP tokens?" +learn_hub_section: "Governance" +learn_hub_category: "How can I use ICP?" +migrated: false +--- + +# How can I receive ICP tokens? + +When you log into the NNS dapp for the first time you will not yet have any ICP tokens in your wallet. Therefore, you first might want transfer some tokens to the NNS dapp wallet. This also the first step required for staking a neuron with the NNS dapp. + +## Get tokens from an exchange + +If you already have ICP tokens on an exchange, you can transfer some of them to your NNS dapp account as explained in this video. + +#### Step 1: Go on the Internet Computer Account page. + +![](https://learn.internetcomputer.org/hc/article_attachments/42496260016660) + +If you already [added sub-accounts](https://learn.internetcomputer.org/hc/en-us/articles/42494280383252), you now see the list of them. + +#### Step 2: Copy the ICP address of your account. + +You have two options how to find the address of one of your accounts, for example the 'Main' account. + + * You can click on the QR-code symbol next to the account 'Main'. This will lead you to the following window where you can copy the ICP address. + +![](https://learn.internetcomputer.org/hc/article_attachments/42496260020372) + + * You can use the 'Receive' button and select the account 'Main' at the top. You then see the option to copy the address. + +![](https://learn.internetcomputer.org/hc/article_attachments/42496302608276) + +#### Step 3: Go to your exchange and send tokens to the address you just copied. + +Using this, you can send tokens from any exchange that supports sending ICP. The tokens should be visible in your wallet within a few minutes. + +Not all exchanges support all features. It is advised to check with the exchange to be sure it supports the workflow described above. + +## Get tokens from a developer identity using the CLI + +This part explains how you can transfer ICP utility tokens from an account associated with your developer identity to your NNS dapp account. + +To transfer ICP utility tokens controlled by your developer identity: + +#### Step 1: Open a terminal shell on your local computer. + +#### Step 2: Check that you are using an identity with control over the ledger account by running the following command: + + + dfx identity whoami + +In most cases, you should see that you are currently using your `default` developer identity. For example: + + + default + +#### +Step 3: View the textual representation of the principal for your current identity by running the following command: + + + dfx identity get-principal + +This command displays output similar to the following: + + + tsqwz-udeik-5migd-ehrev-pvoqv-szx2g-akh5s-fkyqc-zy6q7-snav6-uqe + +#### Step 4: Check the current balance in the ledger account associated with your identity by running the following command: + + + dfx ledger --network ic balance + +#### Step 5: Transfer ICP utility tokens to your Main account or a linked subaccount you create by running a command similar to the following: + + + dfx ledger --network ic transfer <destination-account-id> --icp <ICP-amount> --memo <numeric-memo> + +To find your account on the NNS dapp wallet, proceed as explained above. For example, assume your account is `0dff47055d84fd0d89cc55ff477c24026b5c2c9175f8fd36bcb66bb68cac81be` if you want to transfer 1 ICP utility token to this account, you can run the following command: + + + dfx ledger --network ic transfer 0dff47055d84fd0d89cc55ff477c24026b5c2c9175f8fd36bcb66bb68cac81be --memo 12345 --icp 1 + +This example illustrates how to transfer ICP utility tokens using a whole number with the `--icp` command line option. +You can also specify fractional units of ICP utility tokens—called **e8s** —using the `--e8s` option, either on its own or in conjunction with the `--icp` option. +Alternatively, you can use the `--amount` to specify the number of ICP utility tokens to transfer with fractional units up to 8 decimal places, for example, as `5.00000025`. + +The destination address can be any address in the ledger canister which might correspond to: + + * A wallet that is owned by a developer principal. + * An account you have added using the NNS dapp. + * An address for a wallet you have on an exchange. + + + + +If you transfer the ICP utility tokens to an account in the NNS dapp, you might need to refresh the browser to see the transaction reflected. + +For more information about using the `dfx ledger` command line options, see [dfx ledger](https://internetcomputer.org/docs/building-apps/developer-tools/dfx/dfx-ledger). + diff --git a/.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-send-icp-tokens.md b/.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-send-icp-tokens.md new file mode 100644 index 00000000..9d821e2e --- /dev/null +++ b/.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-send-icp-tokens.md @@ -0,0 +1,42 @@ +--- +learn_hub_id: 42499104466324 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/42499104466324-How-can-I-send-ICP-tokens" +learn_hub_title: "How can I send ICP tokens?" +learn_hub_section: "Governance" +learn_hub_category: "How can I use ICP?" +migrated: false +--- + +# How can I send ICP tokens? + +Once you have ICP tokens in your NNS dapp account, you can send them to other accounts by following these steps. + +#### Step 1: Go on the Internet Computer Account page. + +If you already [added sub-accounts](https://learn.internetcomputer.org/hc/en-us/articles/42494280383252), you now see the list of them. + +![](https://learn.internetcomputer.org/hc/article_attachments/42499429037076) + +#### Step 2: Click Send on the bottom of the window. + +![](https://learn.internetcomputer.org/hc/article_attachments/42499413481748) + +#### Step 3: Select one of your accounts, 'Main' or another one, as the source and input the destination address and the amount of ICP to send. + +![](https://learn.internetcomputer.org/hc/article_attachments/42499413489556) +Transactions are charged a ledger fee, which is independent from the NNS dapp and applies to any transaction. For ICP tokens, this fee is 0.0001 ICP. + +The maximum amount you can send is your token balance minus the ledger fee. The minimum amount you can send is 0.00000001 ICP. + +#### Step 4: Select Continue, review the transaction, and if you are happy with it press Send Now to send the transaction. + +The destination address can be any address in the ledger canister which might correspond to: + + * A wallet that is owned by a developer principal. + * An account you have added using the NNS dapp. + * An address for a wallet you have on an exchange. + + + +If you transfer the ICP utility tokens to an account in the NNS dapp, you might need to refresh the browser to see the transaction reflected. + diff --git a/.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-stake-a-neuron.md b/.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-stake-a-neuron.md new file mode 100644 index 00000000..d8471d8a --- /dev/null +++ b/.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-stake-a-neuron.md @@ -0,0 +1,38 @@ +--- +learn_hub_id: 42754119358484 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/42754119358484-How-can-I-stake-a-neuron" +learn_hub_title: "How can I stake a neuron?" +learn_hub_section: "Governance" +learn_hub_category: "How can I use ICP?" +migrated: false +--- + +# How can I stake a neuron? + +To participate in governance, users can lock ICP utility tokens in a [neuron](https://learn.internetcomputer.org/hc/en-us/articles/34084120668692). This is also called **staking**. The balance of ICP utility tokens is locked for a given time which is called the **dissolve delay** and the tokens can only be unlocked by fully **dissolving** the neuron. The longer the tokens are locked, the more voting power a neuron has. See more details on [voting power](https://learn.internetcomputer.org/hc/en-us/articles/34084120668692#h_01JJ26P5EEPSRQSN0Y3Q2Y975K). + +## How to Stake ICP utility tokens in a neuron + +After you transfer ICP utility tokens to the [NNS dapp](https://nns.ic0.app/), you can use it to create and manage neurons, vote on proposals, and create canisters on the Internet Computer. + +Neurons are required to participate in governance to earn rewards. To create a neuron, you must lock up some number of ICP utility tokens for a period of time. The minimum stake required to create a neuron is 1 ICP utility token. You can configure the period of time the stake is locked from 6 months up to a maximum of 8 years. + +To stake ICP utility tokens: + +#### Step 1: In the [NNS dapp](https://nns.ic0.app/), select Neuron Staking from the left navigation bar, then click Stake ICP in the Staked ICP table. + +#### ![](https://learn.internetcomputer.org/hc/article_attachments/42755015108756) +Step 2 : Select which wallet you'd like to use as the source, then type the number of ICP utility tokens to stake, then click Create. + +![](https://learn.internetcomputer.org/hc/article_attachments/42755021558036) + +Optionally, you can choose to make the neuron [public](https://learn.internetcomputer.org/hc/en-us/articles/34084120668692#h_01JJ26QW42Z5QMGJPE2JFBJK92). + +#### Step 3: Set the dissolve delay for the neuron to control the length of time the stake is locked, then click Set Delay. + +![](https://learn.internetcomputer.org/hc/article_attachments/42755015112468) + +You can also skip this step and set the dissolve delay later. However, in that case your neuron is not yet eligible to vote and will not get any voting rewards. + +Once you staked a neuron, you can [configure it ](https://learn.internetcomputer.org/hc/en-us/articles/42755094620180)and use it for voting. + diff --git a/.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-stake-and-auto-stake-maturity.md b/.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-stake-and-auto-stake-maturity.md new file mode 100644 index 00000000..7c838455 --- /dev/null +++ b/.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-stake-and-auto-stake-maturity.md @@ -0,0 +1,55 @@ +--- +learn_hub_id: 39755363912724 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/39755363912724-How-can-I-stake-and-auto-stake-maturity" +learn_hub_title: "How can I stake and auto-stake maturity?" +learn_hub_section: "Governance" +learn_hub_category: "How can I use ICP?" +migrated: false +--- + +# How can I stake and auto-stake maturity? + +## Overview + +This tutorial is focused on NNS neurons. In SNS DAOs with voting rewards the concepts are very similar and the same tutorial might be helpful. + +As you stake a neuron in the NNS and participate in governance, by voting directly or by delegating your voting power to others, your neuron receives voting rewards in the form of [maturity that can be _disbursed_ or _staked_.](https://learn.internetcomputer.org/hc/en-us/articles/34084120668692-Neurons#01JJ7BJX36NH538SCDQFHSJSVD) + +## Stake maturity + +When you have available maturity, you can stake it. Staked maturity is viewed as part of the neuron's stake and contributes to the neuron's voting power. Find more information in [Voting rewards & maturity](https://learn.internetcomputer.org/hc/en-us/articles/34084120668692-Neurons#01JJ7BJX36NH538SCDQFHSJSVD). + +#### Step 1: On the [staking page](https://nns.ic0.app/neurons/?u=qoctq-giaaa-aaaaa-aaaea-cai), navigate to the neuron whose maturity you want to disburse. + +Click **Stake** in the **Maturity** section. + +![](https://learn.internetcomputer.org/hc/article_attachments/39755822790804) + +#### Step 2: In the form that opens, select the percentage of maturity to stake. + +![](https://learn.internetcomputer.org/hc/article_attachments/39755822791828) + +#### Step 3: After clicking **Stake** , you see an overview where you can review and confirm the action. + +![](https://learn.internetcomputer.org/hc/article_attachments/39755783408788) + +#### Step 4: As a result of the operation, you see that now parts of your neuron's maturity is listed in the "Staked" section. + +![](https://learn.internetcomputer.org/hc/article_attachments/39755783409172) + +## Automatically stake maturity + +In order to not have to regularly perform the action of staking maturity, you can also choose to auto-stake a neuron's maturity. This means that all new maturity will automatically be added to the staked maturity. + + +#### Step 1: On the [staking page](https://nns.ic0.app/neurons/?u=qoctq-giaaa-aaaaa-aaaea-cai), navigate to the Advanced Details & Settings. + +Choose **Automatically stake new maturity**. + +#### ![](https://learn.internetcomputer.org/hc/article_attachments/39756773899028) +Step 2: In the form that opens, confirm the setting.![](https://learn.internetcomputer.org/hc/article_attachments/39756773899284) + +#### Step 3: As a result of the operation, you see that now **Automatically stake new maturity** is ticked, indicating that it is chosen for this neuron. + +![](https://learn.internetcomputer.org/hc/article_attachments/39756773899796) + diff --git a/.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-top-up-a-neuron.md b/.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-top-up-a-neuron.md new file mode 100644 index 00000000..2facddc7 --- /dev/null +++ b/.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/how-can-i-top-up-a-neuron.md @@ -0,0 +1,31 @@ +--- +learn_hub_id: 42756506278804 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/42756506278804-How-can-I-top-up-a-neuron" +learn_hub_title: "How can I top up a neuron?" +learn_hub_section: "Governance" +learn_hub_category: "How can I use ICP?" +migrated: false +--- + +# How can I top up a neuron? + +After you [create a neuron](https://learn.internetcomputer.org/hc/en-us/articles/42754119358484), you can increase the number of ICP utility tokens you have staked in that neuron to increase your voting power and rewards. For example, if you initially stake a small number of ICP utility tokens, then decide to purchase additional tokens, you have the option to create a new neuron or "top-up" your existing neuron. + +To increase the stake in an existing neuron: + +#### Step 1: On the NNS dapp, go to the Neuron Staking tab and then the table Staked ICP. Then click on a neuron. + +#### Step 2: Click Increase Stake. + +![](https://learn.internetcomputer.org/hc/article_attachments/42756683493396) + +#### Step 3: Type the amount of ICP utility tokens you want to add to the specified neuron, then click Continue. + +![](https://learn.internetcomputer.org/hc/article_attachments/42756695634196) + +#### Step 4: Verify the transaction details, then click Send Now. + +![](https://learn.internetcomputer.org/hc/article_attachments/42756695635476) + +#### Step 5: Once the transaction has completed, you will see the increased stake value. + diff --git a/.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/internet-computer-dashboard.md b/.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/internet-computer-dashboard.md new file mode 100644 index 00000000..356b8cdd --- /dev/null +++ b/.migration/learn-hub/out-of-scope/how-can-i-use-icp/governance/internet-computer-dashboard.md @@ -0,0 +1,12 @@ +--- +learn_hub_id: 33152081370260 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/33152081370260-Internet-Computer-dashboard" +learn_hub_title: "Internet Computer dashboard" +learn_hub_section: "Governance" +learn_hub_category: "How can I use ICP?" +migrated: false +--- + +# Internet Computer dashboard + + diff --git a/.migration/learn-hub/out-of-scope/how-can-i-use-icp/network-stats/cycle-burn.md b/.migration/learn-hub/out-of-scope/how-can-i-use-icp/network-stats/cycle-burn.md new file mode 100644 index 00000000..af214e41 --- /dev/null +++ b/.migration/learn-hub/out-of-scope/how-can-i-use-icp/network-stats/cycle-burn.md @@ -0,0 +1,12 @@ +--- +learn_hub_id: 33152123370772 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/33152123370772-Cycle-burn" +learn_hub_title: "Cycle burn" +learn_hub_section: "Network stats" +learn_hub_category: "How can I use ICP?" +migrated: false +--- + +# Cycle burn + + diff --git a/.migration/learn-hub/out-of-scope/how-can-i-use-icp/network-stats/network-topology.md b/.migration/learn-hub/out-of-scope/how-can-i-use-icp/network-stats/network-topology.md new file mode 100644 index 00000000..1c3dae02 --- /dev/null +++ b/.migration/learn-hub/out-of-scope/how-can-i-use-icp/network-stats/network-topology.md @@ -0,0 +1,12 @@ +--- +learn_hub_id: 33152148267412 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/33152148267412-Network-topology" +learn_hub_title: "Network topology" +learn_hub_section: "Network stats" +learn_hub_category: "How can I use ICP?" +migrated: false +--- + +# Network topology + + diff --git a/.migration/learn-hub/out-of-scope/how-can-i-use-icp/network-stats/tx-s.md b/.migration/learn-hub/out-of-scope/how-can-i-use-icp/network-stats/tx-s.md new file mode 100644 index 00000000..63b3c25b --- /dev/null +++ b/.migration/learn-hub/out-of-scope/how-can-i-use-icp/network-stats/tx-s.md @@ -0,0 +1,12 @@ +--- +learn_hub_id: 33152121376404 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/33152121376404-tx-s" +learn_hub_title: "tx/s" +learn_hub_section: "Network stats" +learn_hub_category: "How can I use ICP?" +migrated: false +--- + +# tx/s + + diff --git a/.migration/learn-hub/out-of-scope/how-can-i-use-icp/tokens-wallets/how-can-i-stake-icp-with-quill.md b/.migration/learn-hub/out-of-scope/how-can-i-use-icp/tokens-wallets/how-can-i-stake-icp-with-quill.md new file mode 100644 index 00000000..24a19635 --- /dev/null +++ b/.migration/learn-hub/out-of-scope/how-can-i-use-icp/tokens-wallets/how-can-i-stake-icp-with-quill.md @@ -0,0 +1,116 @@ +--- +learn_hub_id: 43823123678100 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/43823123678100-How-can-I-stake-ICP-with-quill" +learn_hub_title: "How can I stake ICP with quill?" +learn_hub_section: "Tokens & wallets" +learn_hub_category: "How can I use ICP?" +migrated: false +--- + +# How can I stake ICP with quill? + +You can use `quill` to stake ICP by creating a neuron in the Network Nervous System (NNS), and subsequently manage and disburse your neuron. The benefit of this method is security: `quill` supports air-gapped operation, which enables you to keep your cryptographic keys optimally secure. We assume that you have already [prepared an air-gapped setup](https://learn.internetcomputer.org/hc/en-us/articles/41523709355668) and [transferred ICP tokens](https://learn.internetcomputer.org/hc/en-us/articles/41526165816596) to it, and that you're thus familiar with the tools – `quill` and the [Scan & Send](https://p5deo-6aaaa-aaaab-aaaxq-cai.raw.ic0.app) application – to bridge the air gap. Throughout the tutorial, we assume that your private key is stored in a file `identity.pem`, which is the same setup we assume in the other tutorials. + +## Create a neuron by staking ICP tokens + +This step assumes that you have already transferred ICP tokens to your `quill` wallet. If you haven't done so yet, please [do the initial steps](https://learn.internetcomputer.org/hc/en-us/articles/41526165816596) now. + +You can then use the neuron-stake command in quill to create the neuron, as follows: + + + $ quill --pem-file identity.pem neuron-stake --name $NAME --amount $AMOUNT --qr + +In the above command, `$NAME` can be an arbitrary string of up to 8 characters, which you can use to identify your neuron for the purposes of increasing your stake later with `quill`. For example, if you intend to have only one eight-year neuron, you could use the name `8yneuron`. This string has no meaning otherwise, and will not be visible anywhere else. You can store the string on your air-gapped computer. It is recommended that you also write the string down. + +The `$AMOUNT` is a decimal number that specifies how many ICP tokens shall be staked. The amount should not include the transaction fee, but remember that it will still be deducted from your account, so if you wish to stake everything you’ve got, stake your balance minus the 0.0001 ICP fee. + +The command generates a QR code that you need to scan with the [Scan & Send](https://p5deo-6aaaa-aaaab-aaaxq-cai.raw.ic0.app/) application. After sending the transaction, the application will display a response which looks like this: + + + ( + record { + result = opt variant { + NeuronId = record { id = 5_241_875_388_871_980_017 } + }; + }, + ) + +The neuron id, `5_241_875_388_871_980_017` in this example, will be needed for subsequent steps and generally referred to as `$NEURON_ID`. + +## Set the dissolve delay of a neuron + +After creating your neuron, it is not locked. In order to participate in governance and collect staking rewards, you need to increase the dissolve delay of your neuron to at least 6 months. To increase the dissolve delay of a neuron whose id is `$NEURON_ID,` there is a command of the form: + + + $ quill --pem-file identity.pem neuron-manage $NEURON_ID --additional-dissolve-delay-seconds $SECONDS --qr + +This shows the `neuron-manage` subcommand, which is used to manipulate neurons after they have been staked. In this case, `$SECONDS` seconds are added to the delay time. + +The following table gives typical values for `$SECONDS`: + +**Duration** | `$SECONDS` +---|--- +six months | `15_778_800` (60 seconds * 60 minutes * 24 hours * 182.625 days) +one year | `31_557_600` (60 seconds * 60 minutes * 24 hours * 365.25 days) +four years | `126_230_400` (60 seconds * 60 minutes * 24 hours * 365.25 days * 4 years) +eight years | `252_460_800` (60 seconds * 60 minutes * 24 hours * 365.25 days * 8 years) + +If you specify a dissolve delay longer than 8 years, it will be rounded down to 8 years. + +The command will show a QR code that you need to scan with the application. + +## Increase the stake of an existing neuron + +The command is exactly the same as for creating the neuron initially, make sure to use the same value as `$NAME`. + +## Set up voting + +While you can use `quill` to vote on proposals, there is a better way: You can configure your neuron so that you can vote from a different interface, such as the [NNS dapp](https://nns.internetcomputer.org). At the same time, this method still preserves the full security of the air-gapped setup for your tokens and rewards; the setup enables the NNS dapp only for voting on proposals and setting up following. This is considered the best trade-off in terms of security and usability. + +For this setup, you need to retrieve your _principal id_ from the NNS dapp, which you can see by clicking on the person icon in the upper right corner. The principal id will look similar to this: `2xt3l-tqk2i-fpygm-lseru-pvgek-t67vb-tu3ap-k0mnu-dr4hl-z3kpn-o2e`. + +You can then add the principal id from the NNS dapp as a so-called hotkey to your neuron: + + + $ quill --pem-file identity.pem neuron-manage $NEURON_ID --add-hot-key $PRINCIPAL --qr + +where `$NEURON_ID` is your neuron id and `$PRINCIPAL_ID` is the principal id you copied from the NNS dapp. + +After scanning the QR code and sending the transaction to the IC, you will be able to see your neuron, configure following, and vote in the NNS dapp. + +## Disburse the voting rewards + +After you participated in governance for a certain time period (at least a few days), your neuron will accumulate maturity that can be converted into ICP tokens. You can use the following command: + + + $ quill --pem-file identity.pem neuron-manage $NEURON_ID --disburse-maturity --qr + +The process of disbursing maturity takes one full week. The ICP tokens will be credited to your `quill` wallet, but you can [transfer them anywhere](https://learn.internetcomputer.org/hc/en-us/articles/41526165816596) as soon as they appear. + +## Start dissolving the neuron + +After you created your neuron and increased the dissolve delay, the neuron will _not_ automatically start to dissolve. That is, unless you start dissolving the neuron, it will remain locked. Once you start dissolving it, the dissolve delay will count downward until it reaches zero, at which point you can disburse the ICP staked in the neuron. You can use the following command to start dissolving your neuron: + + + $ quill --pem-file identity.pem neuron-manage $NEURON_ID --start-dissolving --qr + +**Warning:** As soon as you start dissolving your neuron, you will immediately lose the entire age bonus you may have accumulated. + +## Stop dissolving the neuron + +In order to stop the neuron from dissolving, you can use the following command: + + + $ quill --pem-file identity.pem neuron-manage $NEURON_ID --stop-dissolving --qr + +After you stop dissolving your neuron, it will again accumulate age bonus. + +## Disburse the neuron + +When the dissolve delay of the neuron reached zero, the ICP staked in the neuron can be disbursed. You can use the following command: + + + $ quill --pem-file identity.pem neuron-manage $NEURON_ID --disburse --qr + +The ICP tokens that were staked in the neuron will be transferred to the main `quill` wallet, from where they can be transferred anywhere. + diff --git a/.migration/learn-hub/out-of-scope/how-can-i-use-icp/tokens-wallets/how-do-i-set-up-an-air-gapped-wallet-with-quill.md b/.migration/learn-hub/out-of-scope/how-can-i-use-icp/tokens-wallets/how-do-i-set-up-an-air-gapped-wallet-with-quill.md new file mode 100644 index 00000000..6bf32260 --- /dev/null +++ b/.migration/learn-hub/out-of-scope/how-can-i-use-icp/tokens-wallets/how-do-i-set-up-an-air-gapped-wallet-with-quill.md @@ -0,0 +1,55 @@ +--- +learn_hub_id: 41523709355668 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/41523709355668-How-do-I-set-up-an-air-gapped-wallet-with-quill" +learn_hub_title: "How do I set up an air-gapped wallet with quill?" +learn_hub_section: "Tokens & wallets" +learn_hub_category: "How can I use ICP?" +migrated: false +--- + +# How do I set up an air-gapped wallet with quill? + +Self-custody based on a seed phrase and an air-gapped computer maximizes control over one's tokens. The downside is that it requires significant technical skills and effort to set it up securely and to use it. + +The core idea of this method is to maintain the private keys on a computer that is air-gapped, ie. not connected to the Internet, and thus safe from remote attacks. The computer can sign the transactions but not send them to the network. The signed transactions are instead displayed on the computer screen as QR codes, and a mobile phone is used to scan and decode the QR code and send the transaction to the network. As the phone only forwards the already signed transaction and does not touch sensitive cryptographic keys, the security of this method depends entirely on the air-gapped computer. + +## Preparing your hardware and software + +The hardware requirements are fairly low. Common options are an old laptop or a [Raspberry Pi](https://www.raspberrypi.com). The below description assumes that you have set up macOS or some variant of Linux. + + 1. Install [quill](https://github.com/dfinity/quill) by downloading the appropriate version from the [releases page](https://github.com/dfinity/quill/releases) (or building it from source code, if you prefer). + 2. Make sure to deactivate any and all network connections on the computer in order to air-gap it. + + + +## Generate the seed phrase and private key + +On your air-gapped computer, run the following command: + + + % quill generate + +The command will as you for a password, print the seed phrase on the screen, and generate a file `identity.pem` that is password-encrypted and contains the private key. Write down the seed phrase and store it in a safe place. + +The command will also print your _principal id_ and your _legacy account id_. These are your public addresses, you will need them to receive tokens. The _legacy account id_ is only used for ICP tokens, such as if you send ICP tokens from a centralized exchange. The _principal id_ is used for all tokens except for ICP. The If you want to copy the addresses to your phone, you can use the command + + + % quill --pem-file identity.pem public-ids | quill qr-code --file /dev/stdin + +and scan the resulting QR code with your phone. Paste the result to a note or text file on your phone. + +## Final steps + +The method uses a seed phrase to encode the private key. The seed phrase serves as a backup in case the computer breaks or is otherwise inaccessible. Never show your seed phrase to anyone. Do not store your seed phrase on any electronic device other than the air-gapped computer. + +Write your seed phrase on a sheet of paper or use a more durable option such as a steel wallet like the [Billfodl](https://billfodl.com). As you only need your seed phrase to recover the private key on your air-gapped computer, you should store it safely in a place like a bank vault or a private safe. + +You of course also need to protect your air-gapped computer from physical access as well as using appropriate measures like strong passwords and disk encryption. + +## Additional tools + + * [Harpo](https://github.com/THLO/harpo) is an open-source tool that allows to split a seed phrase in multiple shares. + * The readme file in the [quill repository](https://github.com/dfinity/quill) will guide you through the use of quill. + + + diff --git a/.migration/learn-hub/out-of-scope/how-can-i-use-icp/tokens-wallets/how-do-i-transfer-tokens-with-quill.md b/.migration/learn-hub/out-of-scope/how-can-i-use-icp/tokens-wallets/how-do-i-transfer-tokens-with-quill.md new file mode 100644 index 00000000..9fd891ec --- /dev/null +++ b/.migration/learn-hub/out-of-scope/how-can-i-use-icp/tokens-wallets/how-do-i-transfer-tokens-with-quill.md @@ -0,0 +1,64 @@ +--- +learn_hub_id: 41526165816596 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/41526165816596-How-do-I-transfer-tokens-with-quill" +learn_hub_title: "How do I transfer tokens with quill?" +learn_hub_section: "Tokens & wallets" +learn_hub_category: "How can I use ICP?" +migrated: false +--- + +# How do I transfer tokens with quill? + +This article assumes that you already [set up an air-gapped wallet with quill](https://learn.internetcomputer.org/hc/en-us/articles/41523709355668), which consists of an air-gapped computer that has [quill](https://github.com/dfinity/quill) installed together with an identity file containing a private key. Using the air-gapped wallet also requires a mobile phone and the [Scan & Send](https://p5deo-6aaaa-aaaab-aaaxq-cai.raw.ic0.app/) application. + +## Transferring tokens to the air-gapped wallet + +You can display the addresses of the wallet with the following command: + + + % quill --pem-file identity.pem public-ids + PEM decryption password: [hidden] + Principal id: adett-lionk-6fxvm-cjgo2-ilfvx-7kbcj-ijzvx-3un7v-pl45j-mttb6-aae + Legacy account id: 8c38fd552fc9a6ba6cf4d574df0bb15212574f29ca3b459d2af05def37217488 + +The principal id, here `adett-lionk-6fxvm-cjgo2-ilfvx-7kbcj-ijzvx-3un7v-pl45j-mttb6-aae`, can be used to send any token that complies with the [ICRC-1 standard](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-1/README.md). + +The ICP account id, here `8c38fd552fc9a6ba6cf4d574df0bb15212574f29ca3b459d2af05def37217488`, can be used to send ICP tokens from wallets that do not support the ICRC-1 standard. When sending tokens from centralized exchanges, you usually have to use this address format. + +## Transferring tokens from the air-gapped wallet + +### Transferring ICP tokens + +ICP tokens can be sent toward addresses of either of the above two formats using the following command: + + + % quill --pem-file identity.pem transfer --amount [AMOUNT] [TO-ADDRESS] --qr + +The value `AMOUNT` is the amount of ICP tokens, specified with up to 8 decimal digits. The displayed QR code can be scanned with the Scan & Send application. + +### Transferring ckBTC or SNS tokens + +Quill supports sending ckBTC and SNS tokens using the ICRC-1 address format. For ckBTC, the command is as follows: + + + % quill --pem-file identity.pem ckbtc transfer --satoshis [AMOUNT] [TO-ADDRESS] --qr + +The value `AMOUNT` is the amount of Satoshis to be sent. The displayed QR code can be scanned via the Scan & Send application. + +For SNS tokens, one first needs to create a file that contains the canister ids. For the Dragginz DAO, for example, the file `dragginz.json` would look as follows: + + + { "governance_canister_id": "zqfso-syaaa-aaaaq-aaafq-cai", "ledger_canister_id": "zfcdd-tqaaa-aaaaq-aaaga-cai", "root_canister_id": "zxeu2-7aaaa-aaaaq-aaafa-cai", "swap_canister_id": "zcdfx-6iaaa-aaaaq-aaagq-cai" } + +Given this file, the command for transferring DKP tokens is then as follows: + + + % quill --pem-file identity.pem sns transfer --canister-ids-file dragginz.json --amount [AMOUNT] [TO-ADDRESS] --qr + +## Tools used in this tutorial + + * [Scan & Send](https://p5deo-6aaaa-aaaab-aaaxq-cai.raw.ic0.app/) for ICP using QR codes + * [Quill](https://github.com/dfinity/quill) for creating transactions + + + diff --git a/.migration/learn-hub/out-of-scope/how-can-i-use-icp/tokens-wallets/icp-custody-options.md b/.migration/learn-hub/out-of-scope/how-can-i-use-icp/tokens-wallets/icp-custody-options.md new file mode 100644 index 00000000..cfa5e063 --- /dev/null +++ b/.migration/learn-hub/out-of-scope/how-can-i-use-icp/tokens-wallets/icp-custody-options.md @@ -0,0 +1,92 @@ +--- +learn_hub_id: 42139140618516 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/42139140618516-ICP-Custody-Options" +learn_hub_title: "ICP Custody Options" +learn_hub_section: "Tokens & wallets" +learn_hub_category: "How can I use ICP?" +migrated: false +--- + +# ICP Custody Options + +The following table shows who typically uses each option, how easy it is to operate, the general security profile (**assuming correct setup and operational hygiene**), and representative examples. The list is not exhaustive and is intended as a quick orientation before diving into detailed guides. + + +Category | Typical users | Ease | Security | Examples +---|---|---|---|--- +On-chain / Web | Everyday use, newcomers | High | Medium | [OISY](https://oisy.com/), [NNS dapp](https://nns.ic0.app/)*, [Stoic](https://www.stoicwallet.com/), [NFID](https://nfid.one/) +Mobile | Frequent on-the-go | High | Medium | [Plug](https://plugwallet.ooo/), [AstroX ME](https://astrox.me/), [AirGap](https://airgap.it/), [Trust Wallet](https://trustwallet.com/), [Klever](https://klever.io/en-us/crypto-wallet/icp-wallet), [Bity](https://www.bity.com/bity-wallet) +Browser extension / Desktop | DeFi users, desktop-first | High | Medium | [Plug (ext)](https://plugwallet.ooo/), [Bitfinity](https://wallet.bitfinity.network/), [MetaMask (MSQ)](https://snaps.metamask.io/snap/npm/fort-major/msq/), [Trust Wallet](https://trustwallet.com/blog/beginners-guide-to-icp), [Primevault*](https://www.primevault.com/) +Hardware / Cold / Air-gapped | Long-term holders, security-focused | Low–Medium | High | [Ledger hardware*](https://www.ledger.com/hardware-wallets), [Quill*](https://github.com/dfinity/quill), [AirGap](https://airgap.it/), [Tangem](https://tangem.com/en/cryptocurrencies/internet-computer/) +Institutional custody | Funds, companies, treasuries | High | High (operational) | [ARCHIP](https://www.archip.ch/), [BitGo](https://www.bitgo.com/), [Ceffu](https://www.ceffu.com/), [Cobo](https://www.cobo.com/), [Coinbase](https://www.coinbase.com/custody), [Copper*](https://copper.co/), [Cordial Systems](https://cordial.systems/), [DFNS](https://www.dfns.co/), [Primevault*](https://www.primevault.com/), [Sygnum*](https://www.sygnum.com/digital-asset-banking/internet-computer-icp/), [Taurus*](https://www.taurushq.com/), [Zodia](https://www.zodia.io/) + +Options marked with (*) facilitate ICP token staking. Depending on the solution, staking may be non-custodial (you retain full control of neurons) or managed (the custodian operates neurons on your behalf). Security reflects the typical risk profile assuming correct usage. Hot wallets trade some security for convenience; cold and institutional solutions prioritize protection over ease of use. Examples may include wallets, interfaces, or custody providers depending on category. + +# Quick Chooser + +Use this guide to select the custody option that suits you best. + +## Custody options with staking + +Do you want to participate in ICP governance or stake via the NNS? + +### Yes: I want full control + + * Use the [**NNS dapp**](https://nns.ic0.app/) (Web) — the canonical way to create/manage neurons, vote, and handle staking directly in your browser, or + * Advanced/offline: + * [**Ledger hardware**](https://www.youtube.com/watch?v=0-nSOBC3bxE) \+ [**NNS dapp**](https://nns.ic0.app/) — sign on hardware and manage neurons in the NNS dapp. + * [**Quill**](https://github.com/dfinity/quill) (offline CLI) — create and manage neurons, vote, and perform ledger actions with fully offline signing workflows, then broadcast from an online machine. + * [**Seed + air-gapped machine**](https://learn.internetcomputer.org/hc/en-us/articles/41523709355668) — combine with Quill for end-to-end offline staking and governance operations. + + + +### Yes: I prefer managed operations + + * Use an institutional custodian that supports ICP staking. Confirm availability and operating model (e.g., policy controls, approvals, reporting). Examples: [**BitGo**](https://www.bitgo.com/), [**Copper**](https://copper.co/), [**Primevault**](https://www.primevault.com/)[, **Taurus**](https://www.taurushq.com/), [**Sygnum**](https://www.sygnum.com/digital-asset-banking/internet-computer-icp/). + + + +## Custody options without staking + +Do you want to hold ICP tokens but don't plan to stake? + +### Yes: prefer someone else to hold the keys + + * Choose institutional custody (audits, contractual safeguards, SLAs). + * If you instead want an exchange account (CEX) for trading convenience rather than long-term custody, see: + * [CoinMarketCap list of ICP exchanges](https://coinmarketcap.com/currencies/internet-computer/#Markets) + * [CoinGecko list of ICP exchanges](https://www.coingecko.com/en/coins/internet-computer) + + + +### Yes: prefer self-custody with maximum ease + +The most convenient path is a web/on-chain wallet. Popular choices are [**OISY**](https://oisy.com/) (no install) and the [**NNS dapp**](https://nns.ic0.app/). + + * Fast setup; minimal maintenance. + * Good for everyday balances and newcomers. + * Check required features (e.g., SNS support, multisig, token standards) before committing. + + + +### Yes: prefer self-custody with maximum control + +For tighter control and a smaller software attack surface, use hardware/cold workflows such as [Ledger](https://www.youtube.com/watch?v=0-nSOBC3bxE) (with [Ledger Wallet](https://shop.ledger.com/pages/ledger-wallet) for management interface) or [seed + air-gapped machines](https://learn.internetcomputer.org/hc/en-us/articles/41523709355668) (with [Quill](https://github.com/dfinity/quill) to sign ledger transactions offline). + + * Highest control; greatest responsibility for backups and recovery. + * Best for large/long-term holdings. + * Practice recovery and small test runs before moving significant funds. + + + +# Risk & best practices + + * **Backups:** Store seeds/recovery materials across two or more physically separate, offline locations. + * **Phishing hygiene:** Bookmark official URLs (e.g., NNS dapp); verify certificates and domain spelling. + * **Device health:** Keep firmware up-to-date (hardware wallets) and maintain clean OS/app environments (hot wallets). + * **Least privilege:** Use hotkeys / separate accounts for daily use; keep cold storage isolated. + * **Change control:** For teams/treasuries, enforce multi-approver or MPC policies where available. + * **Test first:** Do small transfers and dry-runs of recovery before high-value actions. + + + diff --git a/.migration/learn-hub/out-of-scope/what-is-icp/decentralization.md b/.migration/learn-hub/out-of-scope/what-is-icp/decentralization.md new file mode 100644 index 00000000..f611e27f --- /dev/null +++ b/.migration/learn-hub/out-of-scope/what-is-icp/decentralization.md @@ -0,0 +1,67 @@ +--- +learn_hub_id: 44009922536852 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/44009922536852-Decentralization" +learn_hub_title: "Decentralization" +learn_hub_section: "Decentralization" +learn_hub_category: "What is ICP?" +migrated: false +--- + +# Decentralization + +In the context of blockchains, “decentralization” [is defined by Wikipedia](https://en.wikipedia.org/wiki/Decentralization#Blockchain_technology) as: + +_“Decentralization [in blockchains] refers to the transfer of control and decision-making from a centralized entity (individual, organization, or group thereof) to a distributed network. Decentralized networks strive to reduce the level of trust that participants must place in one another, and deter their ability to exert authority or control over one another in ways that degrade the functionality of the network.”_ + +All blockchains rely on a consensus protocol to come to agreement on the state of the network. The higher the decentralization of a network, the more individual actors need to coordinate to come to an agreement. In a centralized or low-decentralization system, one or a handful of entities would be sufficient to establish the state of the system. + +Vitalik Buterin [described decentralization](https://medium.com/@VitalikButerin/the-meaning-of-decentralization-a0c92b76a274) along three independent axes: + + 1. **Architectural (de)centralization** — how many physical computers is a system made up of? How many of those computers can it tolerate breaking down at any single time? + 2. **Political (de)centralization** — how many individuals or organizations ultimately control the computers that the system is made up of? + 3. **Logical (de)centralization** — does the interface and data structures that the system presents and maintains look more like a single monolithic object, or an amorphous swarm? One simple heuristic is: if you cut the system in half, including both providers and users, will both halves continue to fully operate as independent units?” + + + +Buterin described blockchains as being **architecturally decentralized** (many computers), **politically decentralized** (many entities), but **logically centralized** (one commonly agreed state). + +This article focuses on the architectural and political decentralization of ICP. + +## Why Decentralization Matters + +Decentralization is key to making web3 dapps run in a trustless manner. Vitalik Buterin broke it down into three core benefits one gets from decentralized computer networks like blockchains: + + 1. **Fault tolerance** — decentralized systems are less likely to fail accidentally because they rely on many separate components that are not likely. + 2. **Attack resistance** — decentralized systems are more expensive to attack and destroy or manipulate because they lack sensitive central points that can be attacked at much lower cost than the economic size of the surrounding system. + 3. **Collusion resistance** — it is much harder for participants in decentralized systems to collude to act in ways that benefit them at the expense of other participants, whereas the leaderships of corporations and governments collude in ways that benefit themselves but harm less well-coordinated citizens, customers, employees and the general public all the time. + + + +For token holders, smart contract developers, or dapp users this means a more decentralized network would be: + + * More resilient to computer or systems faults + * More resilient to attacks by malicious actors + * More resistant to collusion by entities within the network to harm the network + + + +## Measuring Decentralization + +To help measure and improve decentralization, a common index used in the blockchain world is the [Nakamoto Coefficient](https://news.earn.com/quantifying-decentralization-e39db233c28e): + +_“The basic idea is to (a) enumerate the**essential subsystems** of a decentralized system, (b) determine how many entities one would need to collude or be compromised to control each subsystem, and (c) then use the minimum of these as a measure of the effective decentralization of the system. The higher the value of this minimum Nakamoto coefficient, the more decentralized the system is.”_ + +In practice, determining the NC (Nakamoto Coefficient) to particular chains is more art than science, but it helps provide a good way to identify bottlenecks, the growth or decentralization within a blockchain. Please note: comparing NCs across blockchains can be very imprecise and akin to comparing “apples to oranges.” + +To measure decentralization, a common pattern in blockchains is: + + 1. Identify the subsystems of a blockchain + 2. For each subsystem, determine the subsystem’s NC (the # of entities necessary to compromise to control it) + 3. The subsystem with the _minimum_ NC represents the best holistic measure of decentralization + + + + + + + diff --git a/.migration/learn-hub/out-of-scope/what-is-icp/icp-subsystems.md b/.migration/learn-hub/out-of-scope/what-is-icp/icp-subsystems.md new file mode 100644 index 00000000..5f69998d --- /dev/null +++ b/.migration/learn-hub/out-of-scope/what-is-icp/icp-subsystems.md @@ -0,0 +1,42 @@ +--- +learn_hub_id: 44549459496596 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/44549459496596-ICP-subsystems" +learn_hub_title: "ICP subsystems" +learn_hub_section: "Decentralization" +learn_hub_category: "What is ICP?" +migrated: false +--- + +# ICP subsystems + +ICP has multiple levels of subsystems and decentralization. Using the metaphor of a stack, they are (from top to bottom): + +**1\. “Common Good” apps on the IC** + + * These are apps the community uses, often as public goods + * These are controlled by NNS DAO or individual DAOs (e.g. Internet Identity, NNS frontend dapp, SNS) + * Examples of such apps: + * NNS dapp + * Code repository: <https://github.com/dfinity/nns-dapp> + * Canister: [qoctq-giaaa-aaaaa-aaaea-cai](https://dashboard.internetcomputer.org/canister/qoctq-giaaa-aaaaa-aaaea-cai) + * Internet identity + * Code repository: <https://github.com/dfinity/internet-identity> + * Canister: [rdmx6-jaaaa-aaaaa-aaadq-cai](https://dashboard.internetcomputer.org/canister/rdmx6-jaaaa-aaaaa-aaadq-cai) + + + +**2\. Protocol Governance** + + * ICP is controlled by the NNS DAO + * All changes to the protocol or the topology are directly driven by decisions of the DAO + * See [Dashboard: Governance](https://dashboard.internetcomputer.org/governance) + + + +**3\. Infrastructure Layer** + + * Nodes are the physical layer of ICP (how & which nodes participate in the network) + * See [Dashboard: Network](https://dashboard.internetcomputer.org/network) + + + diff --git a/.migration/learn-hub/out-of-scope/what-is-icp/not-all-transactions-are-equal.md b/.migration/learn-hub/out-of-scope/what-is-icp/not-all-transactions-are-equal.md new file mode 100644 index 00000000..bef4f0a4 --- /dev/null +++ b/.migration/learn-hub/out-of-scope/what-is-icp/not-all-transactions-are-equal.md @@ -0,0 +1,37 @@ +--- +learn_hub_id: 39158902116884 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/39158902116884-Not-All-Transactions-Are-Equal" +learn_hub_title: "Not All Transactions Are Equal" +learn_hub_section: "Performance" +learn_hub_category: "What is ICP?" +migrated: false +--- + +# Not All Transactions Are Equal + +Whilst it is typical for blockchains to flaunt metrics around transactions per second (TX/s) or transactions per day (TX/d), comparisons between blockchains only make sense when those transactions are roughly equivalent, i.e., TX/s comparisons only make sense to compare within a single problem domain. + +The Internet Computer is a blockchain-based platform designed to function as a decentralized World Computer. As a consequence, the IC typically performs more demanding computations in a single step than most other blockchain networks. + +This page aims to explain the differences between the work performed on ICP vs Ethereum. + +## ETH vs. ICP execution throughput + +Both ETH and ICP are able to run (general-purpose) smart contracts. At the execution layer, contracts are translated to a lower-level virtual-machine-interpretable language. These are EVM in the case of ETH and a Wasm-compatible runtime in the case of ICP (see [ICP Execution Layer article](https://learn.internetcomputer.org/hc/en-us/articles/34208985618836) for an introduction). Both EVM and Wasm instructions include arithmetic instructions (e.g., add, mul, div), but also more smart-contract specific instructions (e.g., reading and writing memory). The latter are in general more expensive operations in terms of consumed resources, which is then translated into the amount of gas used for each opcode of ETH and [cycles](https://learn.internetcomputer.org/hc/en-us/articles/34573913497108) for ICP. + +To compare the overall throughput of the two blockchains (i.e., how many operations per second can be handled), one needs to make several assumptions. The first is that simpler EVM instructions (e.g., add, mul, div, etc.) are roughly equivalent to the Wasm instructions of the same type, both kinds being translated to a similar x86 instruction executed by the hardware. The comparison is much more complex and not apples-to-apples for the more complex operations. For a proper comparison here one would need to either (1) thoroughly understand the design of both execution layers, or (2) run a similar program/benchmark on both systems and compare their overall performance. These two options are time-consuming and would lead to longer-term research efforts. For a quicker comparison, one can instead assume that all EVM instructions are equal in terms of gas cost (and also assume no fees are involved). Since ETH is currently burning approximately **108.3B gas units per day** (<https://ycharts.com/indicators/ethereum_gas_used_per_day>, as of Sept 16, 2024), and assuming each instruction costs 1 gas unit (which vastly _underestimates_ the costs of memory access operations), it is clear that the ETH blockchain is running less than 109B instructions per day. + +In sharp contrast, the IC executed more than 110B replicated Wasm instructions per **second** on Sept 16, 2024. Under the simplifying assumption that all instructions are comparable, this means the IC runs the daily load of ETH instructions in less than 1 second. + +Ethereum executed about 1.102M transactions on September 16, 2024 ([https://ycharts.com/indicators/ethereum_transactions_per_day](https://ycharts.com/indicators/ethereum_transactions_per_day#:~:text=Ethereum%20Transactions%20Per%20Day%20is,completed%20on%20the%20Ethereum%20network.)), which means that there were on average 0.098M = 98000 instructions per transaction that day. For the same day, the dashboard of the IC shows that 110B instructions/s were executed for about 8500 replicated calls/s, amounting to an average of more than 12.9M instructions per call. To compare the work intensity of the two blockchains, we take the number of instructions executed per replicated call on ICP and divide it by the number of instructions per transaction on Ethereum. By this measure, ICP performs roughly 130× more computational work per transaction. It's important to note that the multiplier is calculated only considering replicated calls as these are the interactions that carry out ETH equivalent work. + +To compare the two networks in terms of efficiency, one also needs to consider the replication factor. In ICP the typical replication factor for a subnet is 13 versus approximately 1.5M for Ethereum (a number that is steadily increasing <https://beaconscan.com/stat/validator>). While not a direct apples-to-apples comparison (since Ethereum validators do not all execute every transaction, whereas ICP subnet nodes do), this highlights how the ICP can achieve consensus with significantly less replicated execution overhead whilst retaining a high level of security, setting it apart from traditional blockchain architectures. + +## ETH vs ICP EdDSA verification + +To get a view on the validity of the above calculations in a real-world setting, comparisons can be made by running a given function. A realistic function that is used often in the blockchain setting is signature verification. + +Previous work from the Ethereum Foundation estimates that validating an EdDSA signature costs around 500K in Gas ([source](https://ethresear.ch/t/verify-ed25519-signatures-cheaply-on-eth-using-zk-snarks/13139)). One way to get a comparison on the IC is to create a canister, import the [Rust ed25519 library](https://docs.rs/ed25519/latest/ed25519/) and test verification by creating a signature on a hash of an arbitrary message and using that for verification. Counting [cycles](https://learn.internetcomputer.org/hc/en-us/articles/34573913497108) burned before and after this call, discounting the base cost (i.e., cycles charged for ingress and for running an update call) results in a cycle cost of 4,211,120. + +Putting a dollar cost on this comparison, with a conservative assumption that 1 Gas costs 40 GWEI and 1 ETH being priced around $1,800, an EdDSA verification on Ethereum currently costs around $36. Considering the cycle cost (4,211,120) on the IC with 1 XDR exchanging for $1.3476 yields a cost of $0.00000567490 to run an EdDSA verification on the IC. Overall, this suggests that the IC is 6,343,718 times less costly for a standard computation. + diff --git a/.migration/learn-hub/out-of-scope/what-is-icp/performance-comparison.md b/.migration/learn-hub/out-of-scope/what-is-icp/performance-comparison.md new file mode 100644 index 00000000..07ad1176 --- /dev/null +++ b/.migration/learn-hub/out-of-scope/what-is-icp/performance-comparison.md @@ -0,0 +1,101 @@ +--- +learn_hub_id: 39314351721492 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/39314351721492-Performance-Comparison" +learn_hub_title: "Performance Comparison" +learn_hub_section: "Performance" +learn_hub_category: "What is ICP?" +migrated: false +--- + +# Performance Comparison + +Given the rapid pace of innovation, periodic assessments are crucial to gauge the progress of the Internet Computer towards the [World Computer vision](https://learn.internetcomputer.org/hc/en-us/articles/33624077003668). + +In this article, we evaluate ICP alongside other blockchain projects using metrics that reflect what constitutes a good Web3 experience, categorized into core protocol, developer experience, and user experience. + +Unless otherwise stated, metric data corresponds to July 13, 2025. + +## Core Protocol + +This section compares standard metrics used to assess the core protocol performance of popular blockchain projects. Note that these metrics cannot always be taken at face value. While references to where the figures can be found are given below, it is not always clear how these figures were obtained. Additionally, parts of different projects may have the same name, but are often constructed differently (most notably, transactions), and so should not be compared blindly like-for-like. The[ a16z blog](https://a16zcrypto.com/why-blockchain-performance-is-hard-to-measure/) has a nice article describing how the industry should think about metrics. + +| Average MIEPS | Average TPS | Average finality | Average block time | Average TX cost | Average energy consumption | Network size | Onchain storage cost +---|---|---|---|---|---|---|---|--- +ICP | 75,000 | 1,176 | 0.64 s | [0.50 s](https://ic-api.internetcomputer.org/api/v3/daily-stats?start=1746662500&end=1746662500&format=json) | $3.3E-8 = $0.000000033 | 0.003 Wh/tx | [571](https://ic-api.internetcomputer.org/api/v3/daily-stats?start=1746662500&end=1746662500&format=json) | [$5.35](https://internetcomputer.org/docs/building-apps/essentials/gas-cost) +Avalanche | [5.42](https://stats.avax.network/dashboard/overview/) | 3.99 | [0.8 s](https://build.avax.network/academy/avalanche-fundamentals/02-avalanche-consensus-intro/04-tps-vs-ttf) | [1.48 s](https://chainspect.app/chain/avalanche?range-cm=month) | $0.006 | 0.395 Wh/tx | [1,367](https://snowtrace.io/validators) | +Cardano | 2 | 0.37 | [120 s](https://chainspect.app/chain/cardano?range-cm=month) | [20.13 s](https://chainspect.app/chain/cardano?range-cm=month) | $0.193 | 1.27 Wh/tx | [2,998](https://cardanoscan.io/pools) (stake pools) | $2,174 +Ethereum | [1.5](https://ycharts.com/indicators/ethereum_gas_used_per_day) | 14.37 | [12 min](https://chainspect.app/chain/ethereum?range-cm=month) | [12.09 s](https://chainspect.app/chain/ethereum?range-cm=month) | $0.659 | 0.956 Wh/tx | [9,509](https://etherscan.io/nodetracker) | $2,993,082 +Near | [948](https://nearblocks.io/) | 67.91 | [1.8 s](https://chainspect.app/chain/near?range-cm=month) | [1.1 s](https://chainspect.app/chain/near?range-cm=month) | $0.002 | 0.602 Wh/tx | [253](https://nearblocks.io/node-explorer) | $1,296 +Solana | [1,250](https://solanacompass.com/statistics) | 1,199 | [12.8 s](https://chainspect.app/chain/solana?range-cm=month) | [0.4 s](https://chainspect.app/chain/solana?range-cm=month) | $0.010 | 0.517 Wh/tx | [5,846](https://solanacompass.com/statistics/decentralization) | $57,440 + + * Average MIEPS measures millions of instructions executed per second, which is an approximation of useful work performed. For ICP, Avalanche and Solana, the calculation follows from the reported cycles / gas / compute units used in execution. For Near, we approximate it by assuming 1 Tgas corresponds to 1 ms of CPU time at 2B instructions / 1s of CPU time. For Cardano, we give the maximum capacity corresponding to 20ms of CPU time per block at 2B instructions / 1s of CPU time. For Ethereum, we go by the block gas limit (the EVM is a 32-byte stack machine; we count 1 gas as 4 CPU instructions to be generous, see [link](https://learn.internetcomputer.org/hc/en-us/articles/39158902116884) for more details). + * Average TPS measures the transactions processed per second over 30 days as reported on [Chainspect](https://chainspect.app/chain/icp?range-cm=month) on May 12, 2025. For ICP, only update calls are considered. + * Average finality refers to the amount of time that passes between the proposal of a new valid block containing transactions until the block has been finalized and its content is guaranteed to not be reversed or modified (for some blockchains, e.g., Bitcoin, this guarantee can only be probabilistic). For ICP, the reported value is the average over all subnets of their nodes' average time between starting a round until a valid finalization for this round is available. + * Average block time refers to the amount of time between blocks (per subnet on the IC) + * Average TX cost measures the cost of a transaction as reported on [Artemis Analytics](https://app.artemisanalytics.com/chains?selectedChains=avalanche%2Cethereum%2Cnear%2Csolana%2Calgorand%2Ccardano%2Cinternet-computer) on Jul 10, 2025. + * Average energy consumption measures the energy consumption to process a transaction (measured in Watt hours). Figures true as of December 2023. Source: [Carbon Crowd Sustainability Report 2023](https://assets.carboncrowd.io/reports/ICF2023.pdf). + * Size of network (nodes) notes the number of nodes currently validating the blockchain. + * On-chain storage cost gives the dollar cost of storing 1 GiB of data per year on chain. For Near and Solana, to store data one needs to maintain a specified token balance. We convert this balance to USD and annualise by multiplying by 5%. For Cardano and Ethereum, the user pays to store the data "forever", and again we annualise by multiplying this cost by 5%. + + + +## Developer Experience + +Developers always face hardware limitations, whether writing games, operating systems, or text editors. Historically, applications were restricted to limited memory, instruction sets, and demanded high power consumption. This mirrors the majority of today's blockchain landscape. Application developers contend with small stack sizes, expensive and limited persistent storage, cumbersome APIs with hidden assumptions, and inefficient chains that consume excessive power per transaction. This not only restricts deployable applications but also increases development and testing time and cost. +In contrast, ICP brings modern programming to on-chain developers. The IC programming model offers orthogonal persistence, large stack and heap spaces (6 GiB), stable storage of 500 GiB in bespoke (Motoko) and mainstream languages, such as Rust, TypeScript, or Python. + +| **Stable TX cost** | **HTTPs outcalls** | **Smart contract language support** | **Max stack size** | **Max persisted memory (per smart-contract)** | **Active developers (full-time / monthly)** | **Active repositories** +---|---|---|---|---|---|---|--- +ICP | ✅ | ✅ | Motoko (native), Rust, TypeScript, Python, C++, ... | 6 GiB | 500 GiB | 1217 / 625 | 15 K +Avalanche | ❌ | ❌ | Solidity | | | 4173 / 538 | 7.1 K +Cardano | ❌ | ❌ | Plutus (native), Haskell | | | 231 / 577 | 3.9 K +Ethereum | ❌ | ❌ | Solidity (native), Vyper, Yul, FE | 32 KiB | 2^261 B | 2500 / 7700 | 27.7 K +Near | ❌ | ❌ | Rust, Javascript | 256 KiB | 32 KiB | 240 / 777 | 14 K +Solana | ❌ | ❌ | Rust C, C++ | | | 1K / 4.2K | 67 K + + * Stable TX cost provides the ability to have predictable costs for computation. + * HTTPs outcalls is the ability to communicate directly with Web2 services (outside of the network). + * Max stack size is the maximum size the stack can grow for smart contracts and serves as a measure for the complexity of code that is supported by each platform. + * Max persisted memory is the maximum amount of persisted memory supported by each platform. Persisted memory is preserved across individual function calls. + * Active developers refers to the number of developers who made commits on more than 10 days in a month (full-time) or original code authors who made commits in a given month ([Electric Capital](https://www.developerreport.com/), July 10, 2025). + * Active repositories are sourced from the [Electric Capital crypto ecosystems list](https://github.com/electric-capital/crypto-ecosystems) (July 10, 2025). + + + +## User Experience + +Key usability criteria include privacy, identity management, and authentication. The ability to trace and monitor every user interaction in many projects is seen as a major barrier to adoption, despite the benefits of transparency. Financial privacy and freedom of interaction are paramount. +The accessibility and openness of onboarding are also measured by the tools required for user interaction. The percentage of native tokens staked is a measure of user confidence and project participation. Similarly, the number of addresses used for transactions indicates the adoption level. + +| **Privacy-preserving authentication** | **Prerequisites to use** | **Staking ratio** | **Daily active addresses** +---|---|---|---|--- +ICP | ✅ | Browser | 43.4% | 10.41 K +Avalanche | ❌ | Browser, browser extension, tokens | 51.34% | 22.78 K +Cardano | ❌ | Browser, browser extension, tokens | 60.32% | 41.37 K +Ethereum | ❌ | Browser, browser extension, tokens | 29.67 % | 37.89 K +Near | ❌ | Browser, browser extension, tokens | 45.46% | 456.45 K +Solana | ❌ | Browser, browser extension, tokens | 66.43% | 2.85 M + + * Privacy-preserving authentication notes whether a project allows privacy-preserving interactions with the blockchain. + * Prerequisites to use lists what is needed to interact with the project + * Staking ratio gives the percentage of native tokens that are staked in the protocol. The staking ratio metrics are taken from [Staking Rewards](https://www.stakingrewards.com/cryptoassets/) on July 13, 2025. + * Daily active addresses counts addresses that sent or received native currency on a given day, taken from [Artemis](https://app.artemisanalytics.com/chains?selectedChains=avalanche%2Cethereum%2Cnear%2Csolana%2Calgorand%2Ccardano%2Cinternet-computer) on July 10, 2025. + + + +## A note on decentralization + +Decentralization is key to make web3 dapps run in a trustless manner. However, decentralization has many dimensions and cannot be understood and quantified using a single number or coefficient. One can distinguish between a) the decentralization of the node providers running the machines on top of which a protocol runs, b) the decentralization of the consensus and sharding mechanism, c) the governance system, the owners of liquid tokens, etc. The whole is greater than the sum of its parts and one cannot understand the decentralization of a system without a discussion of each of these topics. + +## References + + * ICP : [IC Dashboard](https://dashboard.internetcomputer.org/) + * ADA : [Cardano explorer](https://explorer.cardano.org/en) and [cexplorer](https://cexplorer.io/) + * AVAX : [Snowtrace](https://snowtrace.io/) and [Avalanche explorer](https://subnets.avax.network/) + * ETH : [Etherscan](https://etherscan.io/) + * NEAR : [Near explorer](https://explorer.near.org/) and [Near docs](https://docs.near.org/) + * SOL : [Solana website](https://solana.com/) and [Solana beach](https://solanabeach.io/) + + + + diff --git a/.migration/learn-hub/out-of-scope/what-is-icp/performance.md b/.migration/learn-hub/out-of-scope/what-is-icp/performance.md new file mode 100644 index 00000000..aaca48c5 --- /dev/null +++ b/.migration/learn-hub/out-of-scope/what-is-icp/performance.md @@ -0,0 +1,105 @@ +--- +learn_hub_id: 39320190051348 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/39320190051348-Performance" +learn_hub_title: "Performance" +learn_hub_section: "Performance" +learn_hub_category: "What is ICP?" +migrated: false +--- + +# Performance + +The Internet Computer Protocol (ICP) is designed to provide sovereign compute capabilities at **web-speed**. This article explains key performance metrics and reports on mainnet measurements and synthetic experiments. + +## Key Performance Metrics + +The most important metrics for measuring the performance of the Internet Computer are: + + * **MIEPS (Millions of Instructions Executed Per Second):** +Number of instructions executed per second across, providing a direct indicator of useful work done. + * **Throughput (requests per second, RPS):** +How many messages the network can process per second. + * **Latency:** +The time it takes for a message to be processed and finalized. + + + +These metrics heavily depend on the number of instructions executed per message (see also [Not all transactions are equal](https://learn.internetcomputer.org/hc/en-us/articles/39158902116884/)). + +Real-time system performance can be monitored via the [Internet Computer Dashboard](https://dashboard.internetcomputer.org/), reporting a plethora of other statistics. + +## How ICP Achieves High Performance + +The Internet Computer works very differently from other blockchains, and is powered by advanced new cryptography. The IC achieves scalability by sharding the network into [subnet blockchains](https://learn.internetcomputer.org/hc/en-us/articles/34209955782420). Each subnet limits replication to improve performance while maintaining strong security guarantees (see [Blockchain Protocol ](https://learn.internetcomputer.org/hc/en-us/articles/34206453538964)for an introduction). Currently, the IC operates 42 subnets of varying size, with the possibility to scale out to more subnets when more capacity is needed. + +Every subnet blockchain can process [update calls](https://learn.internetcomputer.org/hc/en-us/articles/34208985618836#h_01JJC2Y0A1SF9RHGA77HP7RSJB) (replicated execution of potentially state changing canister operations) independently from other subnets. + +[Query calls](https://learn.internetcomputer.org/hc/en-us/articles/34208985618836#h_01JJC30QJ1AR9F6K3VQ9485D31) (no canister state change possible), on the other hand, are processed locally by a single node in a subnet. The response to a query call can therefore have low latency since the query just needs a response by a single node and does not require inter-node communication or agreement. The more nodes a subnet has, the more query calls it can handle (in contrast to update calls, which are replicated and require agreement by all the nodes in the subnet). + +## Real-World Performance and Benchmarks + +ICP’s performance has been measured both on the public network as well as under controlled conditions with different parameters. To separate execution performance from the rest of system operation, many experiments report metrics for the _counter_ canister (which simply increases a counter variable whenever processing a message). + +### Mainnet + +| Values | Comments +---|---|--- +MIEPS | Average: [64,625.15](https://ic-api.internetcomputer.org/api/v3/metrics/instruction-rate?step=7200&start=1751328000&end=1751328000&format=json) (July 1, 2025) + +Highest value measured: [249,524.31](https://ic-api.internetcomputer.org/api/v3/metrics/instruction-rate?step=7200&start=1736985600&end=1736985600&format=json) (January 16, 2025) Each subnet can execute up to 8 Billion instructions per second. Extrapolated to 42 subnets, this amounts to a maximum capacity of **336,000 MIEPS**. | Replicated execution only, execution of (read-only) query calls is ignored. See [dashboard](https://dashboard.internetcomputer.org/network/subnets). +Throughput | Average over 24h: + + * Update calls:[ 1075.99/s ](https://ic-api.internetcomputer.org/api/v3/daily-stats?format=json&start=1751328000&end=1751328000)(July 1, 2025) + * Query calls: [4022.86/s](https://ic-api.internetcomputer.org/api/v3/daily-stats?format=json&start=1751328000&end=1751328000) (July 1, 2025) + +Highest values recorded over 1 minute: + + * Update calls: [25,621.47/s ](https://ic-api.internetcomputer.org/api/v3/daily-stats/max-update-transactions-per-sec-till-date?format=json&end=1751328000)(November 8, 2025) + * Query calls: [19,598.03/s](https://ic-api.internetcomputer.org/api/v3/daily-stats/max-query-transactions-per-sec-till-date?format=json&end=1751328000) (July 9, 2024) + +| +Latency | Median: + + * Update calls: 1.75s + * Query calls: 0.167s + +![](https://learn.internetcomputer.org/hc/article_attachments/39320216499860) | Observed by HTTP gateways. The measured [RTT](https://en.wikipedia.org/wiki/Round-trip_delay) between nodes in different data centers varies from 10ms to 280ms. For simple and cached queries, the latency is dominated by network latencies from the client to ICP nodes. +Median for selected update calls: + + * Calls to counter canister on application subnets (13 nodes): 1.35s + * ICP ledger transfers on the NNS subnet (40 nodes): 2.23s + +| See [blog post](https://medium.com/dfinity/tokamak-accelerating-the-internet-computer-update-call-lifecycle-f82517472709). + +### Synthetic Experiments + +Throughput | **Update calls** A single test subnet is currently able to handle around 1,200 rps for update calls as sustained load using default production consensus parameters. With optimized parameters, it is possible to reach 2,000 rps in the same test network (experiments from June 2025). Scaled up to the 42 subnets the IC currently operates, this amounts to **84,000 rps.** **Query calls** A single node is able to sustain 7,025 queries per second (experiments from November 2023). Scaled up to the 636 nodes currently assigned to subnets, this amounts to **4,467,900 rps.** | Experiments performed with counter canister. The throughput capacity has been growing in the past and is expected to grow with further future protocol and implementation enhancements and optimizations. + +Alternative throughput measurements in MB/s are discussed in this [blog post](https://medium.com/dfinity/a-journey-into-stellarator-part-3-6f88881ae4bf). Currently, a throughput of 7 MB/s can be sustained per subnet. +---|---|--- +Latency | **Update calls** The observed latency depends on the network conditions and the load targeted at the same and other canisters on the subnet. The median latency at throughput saturation is 2.27s for 1200 rps with mainnet parameters, while 1.08s at 2000rps can be achieved with tuned parameters. ![](https://learn.internetcomputer.org/hc/article_attachments/39320216501396) Under low load (1 rps), the median latency for the tuned parameters is 0.52s (experiments from June 2025). **Query calls** Caching reduces compute-intensive queries numbers (see this [blog post](https://medium.com/dfinity/improving-query-latencies-f5bb2bc019dd%20)). | Experiments performed with counter canister. For repeatability, the machines of an app subnet with 13 nodes in this experiment were all in the same data center, with simulated network latencies of 30ms RTT (nodes in Europe experience <25ms RTT on average). +The tuned parameters include the notary delay (how long nodes wait before they notarize a block), certification timer (how often the certification process is triggered), whether the hashes-in-blocks throughput optimization is enabled and how long and how many user-facing responses are kept in memory. + +A [paper published at Usenix ATC 2023](https://www.usenix.org/system/files/atc23-arutyunyan.pdf) describes the design and measures the performance of the internal components necessary for the ICP execution layer. + +### ICP Network Latency + +All nodes are connected over the public IPv6 Internet, without any dedicated links. The following table depicts the round trip times observed in September 2023. + +| Brussels | Chicago | Dallas | Fremont | Geneva | Ljubljana | Munich | Orlando | Singapore | Stockholm | Tokyo | Zurich +---|---|---|---|---|---|---|---|---|---|---|---|--- +Brussels | | 102 | 121 | 143 | 17.65 | 27.4 | 18.35 | 106 | 167 | 36.6 | 223 | 16.07 +Chicago | 102 | | 24.6 | 59.05 | 118 | 130 | 110 | 49.4 | 249.5 | 117.5 | 152 | 121.5 +Dallas | 121 | 24.6 | | 53.8 | 132 | 137 | 127 | 37.05 | 276 | 131 | 139 | 129.5 +Fremont | 143 | 59.05 | 53.8 | | 145 | 156 | 145 | 67.7 | 191 | 161 | 109 | 147 +Geneva | 17.65 | 118 | 132 | 145 | | 26.95 | 17.9 | 112 | 257.5 | 38.3 | 248 | 16.05 +Ljubljana | 27.4 | 130 | 137 | 156 | 26.95 | | 17.55 | 123 | 258 | 42 | 235 | 22.1 +Munich | 18.35 | 110 | 127 | 145 | 17.9 | 17.55 | | 118 | 251 | 37.5 | 246 | 12.35 +Orlando | 106 | 49.4 | 37.05 | 67.7 | 112 | 123 | 118 | | 250 | 131 | 166 | 111 +Singapore | 167 | 249.5 | 276 | 191 | 257.5 | 258 | 251 | 250 | | 195.5 | 177 | 200.25 +Stockholm | 36.6 | 117.5 | 131 | 161 | 38.3 | 42 | 37.5 | 131 | 195.5 | | 260 | 36.9 +Tokyo | 223 | 152 | 139 | 109 | 248 | 235 | 246 | 166 | 177 | 260 | | 230 +Zurich | 16.07 | 121.5 | 129.5 | 147 | 16.05 | 22.1 | 12.35 | 111 | 200.25 | 36.9 | 230 | + +RTT measurements between a subset of datacenters contributing to the IC mainnet network (in milliseconds). Min / median / max values are 12 / 125 / 276ms for the whole table. Considering European nodes only, the values are 12 / 22 / 42ms. + diff --git a/.migration/learn-hub/out-of-scope/what-is-icp/what-has-happened-so-far.md b/.migration/learn-hub/out-of-scope/what-is-icp/what-has-happened-so-far.md new file mode 100644 index 00000000..79b5998b --- /dev/null +++ b/.migration/learn-hub/out-of-scope/what-is-icp/what-has-happened-so-far.md @@ -0,0 +1,92 @@ +--- +learn_hub_id: 33152692358036 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/33152692358036-What-Has-Happened-So-Far" +learn_hub_title: "What Has Happened So Far?" +learn_hub_section: "Overview" +learn_hub_category: "What is ICP?" +migrated: false +--- + +# What Has Happened So Far? + +## From Bitcoin to the World Computer + +The first successful blockchain project, Bitcoin, revolutionized digital monetary transactions by eliminating the need for a central authority. This reduces trust, costs and latency, compared to traditional centralized banking systems. With the Bitcoin protocol, transactions are recorded in a public ledger and anyone can run a machine with the protocol, adding and verifying transactions in a secure and decentralized manner. Ethereum generalized the ledger concept from storing purely monetary transactions to generic interactions between mutually distrusting parties and made general smart contracts popular. Smart contracts are software programs that are automatically executed on agreement terms when predetermined conditions are met, without intermediaries. Due to Ethereum’s limitations and costs, only small and relatively simple programs are run on it. + +Building upon these innovations, DFINITY Foundation founder Dominic Williams envisioned a decentralized, unstoppable, and tamper-proof "World Computer" capable of hosting humanity's systems, services, data, and computations. In other words, such a World Computer would bring the benefits from smart contracts to any application. As a consequence, a World Computer can revolutionize traditional IT infrastructure often hosted on centralized hyperscalers’ cloud solutions and transform various sectors, including social media, gaming, finance, and enterprise systems. + + + +## 2016-2020 Building ICP + +To realize this vision, Dominic Williams started to conceptualize a scalable blockchain protocol capable of processing hundreds of thousands of transactions per second, drawing from his experience in developing a massive multiplayer online (MMO) game with millions of users. After establishing the non-profit foundation DFINITY, he attracted world-class experts like Ben Lynn (the L from BLS, a cryptographic signature scheme used in many blockchain protocols), Timo Hanke (developer of AsicBoost and CTO of CoinTerra), Andreas Rossberg (co-inventor of [WebAssembly](https://en.wikipedia.org/wiki/WebAssembly), enabling high-performance code execution in web browsers) and Jan Camenisch (renowned cryptographer from IBM research), to name but a few. + +With over $100 million in funding, DFINITY built a world-class R&D composed of computer science research and engineering talents from industry giants like Google, Meta, and IBM. From 2016 to 2021, the DFINITY team designed and implemented the Internet Computer Protocol (ICP). To meet the ambitious performance and security goals, experts in languages, cryptography, distributed system, and software architecture collaborated. For example, ICP required the design and development of advanced cryptographic protocols to establish key material on nodes in a decentralized setting without assumptions on networking conditions. This was achieved through a groundbreaking non-interactive distributed key generation (niDKG) protocol and a key re-sharing protocol, both devised by cryptographer Jens Groth, who worked at DFINITY. + +ICP utilizes a unique architecture, designed towards realizing the World Computer vision. To be able to build powerful applications easily, the Motoko programming language was created. The applications running on ICP are organized into [canisters](https://learn.internetcomputer.org/hc/en-us/articles/34210839162004), processing and sending messages to each other following the [actor model](https://en.wikipedia.org/wiki/Actor_model)[.](https://en.wikipedia.org/wiki/Actor_model) For canister execution, DFINITY built a [WebAssembly](https://en.wikipedia.org/wiki/WebAssembly)-based smart contract execution environment, when WebAssembly was still almost exclusively used in browsers, helping WebAssembly to gain a wider field of applicability. For scalability and energy-efficiency, ICP offers true sharding by partioning nodes into [subnets](https://learn.internetcomputer.org/hc/en-us/articles/34206453538964). Each subnet hosts a set of canisters which can make progress independently from other subnets, yet messages between canisters residing on different subnets are exchanged seamlessly. + +## 2021 Mainnet launch + +In May 2021, the Internet Computer underwent its genesis event, marking its transition to a decentralized production network. The protocol was launched on a sovereign network of 389 specialized node machines, owned and operated by independent node providers, distributed across 16 data centers worldwide. + +The genesis event also marked the kick-off of a novel governance system called the [Network Nervous System (NNS)](https://learn.internetcomputer.org/hc/en-us/articles/33692645961236). The NNSs consists of a set of canisters responsible for the token economics and a voting system which allows token holders to decide on the network’s future behavior. More precisely, token holders can vote on configuration changes and trigger autonomous updates of the NNS’s canister code as well as the code for the whole network protocol. + +Remembering passwords to log into applications is painful and error-prone. To avoid this problem, ICP offered [Internet Identity (II)](https://learn.internetcomputer.org/hc/en-us/articles/33152205747348) based on WebAuthn and Passkeys already at launch, years before these technologies became widely adopted. + +To make trying out canister development as easy as possible, Motoko Playground was launched in the months following mainnet launch. It allows developers to create and deploy canister smart contracts from a standard browser, without any extensions or downloading any software. And of course, the Motoko Playground is actually an application running on the IC as well. + +By the end of the first year, 451 nodes were part of the network, located in 24 data centers, together producing 30 blocks per second, more than 15k canister smart contracts were deployed on ICP and almost 2 million Internet Identities were created. Furthermore, concepts and first prototypes for the interaction with the outside world were being designed and developed. + +## 2022 - 2025 Network Evolution + +In the years since launch, the Internet Computer Protocol has been extended with powerful capabilities to come closer to the World Computer vision. To achieve this, improvements in the following four categories are crucial: + + 1. _Giving More Control and Privacy to Users:_ A World Computer should empower users to safeguard their data and digital assets and decide themselves who can access their data and digital assets. + 2. _Performance and Security:_ A World Computer must be able to handle a massive scale of computations and data, while ensuring the security and reliability of the network. High performance and robust security measures are essential for building trust and attracting users to the platform. + 3. _Interoperability with Traditional IT and Blockchains:_ To benefit from the strengths provided by existing systems, a seamless transfer of data and value between different systems is needed. + 4. _Developer and User Experience:_ A World Computer should be accessible to a wide range of developers and users. This requires intuitive development tools, user-friendly interfaces, and seamless interaction between applications. + + + +### Giving more control and privacy to users + +In most wide-spread applications today, users surrender control over their personal data and assets to centralized entities, e.g., when interacting with an AI chatbot offered by Big Tech. This paragraph describes features developed in the years since launch to offer a solution enabling user-controlled applications, including the decision power over where they run, when and how software gets upgraded and who has access to what data. + +Inspired by the NNS governance approach, a set of canisters forming a [Service Nervous System (SNS)](https://learn.internetcomputer.org/hc/en-us/articles/34084394684564) was developed. They allow a community of token holders to control and update the code of an application. An SNS can be used to raise the initial funding for an application, which can then be used to remunerate teams working on an application’s evolution and adoption based on community decisions. Similarly, the code of an SNS dapp can only be upgraded to a new version when enough community members vote for adoption. The first Test SNS was launched in 2022, one year later, already 11 SNSs had been created and in the meantime there are almost 30 SNSs holding funds in the order of several millions of USD. + +Verifiably Encrypted Threshold Keys, or [vetKeys](hc/en-us/articles/01JJC57VBB7W1W5BCQFZGYTEPS) for short, have been available in production since 2025. vetKeys facilitate key management, data privacy, and security. It allows canisters to obtain an encrypted value that can be used for symmetric, public-key, or identity-based encryption. With vetKeys users can benefit from end-to-end encryption, without having to remember decryption keys or passwords, as the key management is provided by ICP. + +Moreover, Internet Identity has been extended to offer [Verifiable Credentials (VCs)](https://internetcomputer.org/docs/current/developer-docs/identity/verifiable-credentials/overview) in 2024. With the VC protocol, canisters can determine if a user has a certain credential in a tamper-evident and privacy-preserving manner. For example, a user can prove to be over 18 without having to share all details from their ID card to a dapp. The first dapps using this protocol have been implemented, e.g., users can prove to OpenChat that they are unique human based with DecideAI’s face recognition. + +### Performance and Security + +To extend the range of applications which can be run on ICP, its performance and security were improved in the years after launch. Now, each canister can address up to 500 GB of memory (compared to 8GB at launch) and many more subnets have been added to increase the compute capacity of the network. + +Today, each subnet can host up to 100k canisters and the scheduling and memory management mechanisms have been tweaked to meet the growing loads’ usage patterns. On the security side, the original set of nodes from launch has been complemented with better machines featuring the ability to run encrypted VMs in the future. Moreover, the subnets hosting critical assets have been strengthened with more nodes to reduce the trust placed in individual nodes. Additional security mechanisms, e.g., canister sandboxing, key rotation and transport protocol changes have been introduced, to keep the users’ assets safe. + +### Interoperability with traditional IT infrastructure and blockchains + +Traditionally, smart contracts can only operate on inputs and state stored on their blockchain, i.e., they are not able to use information from the outside without additional trust assumptions. Yet, many applications require access to information stored on traditional servers. The [HTTPs outcalls](https://internetcomputer.org/docs/current/developer-docs/smart-contracts/advanced-features/https-outcalls/https-outcalls-overview) feature developed in 2022 enables canister smart contracts to gather such data in a trustworthy manner. Using this feature, stock prices, football scores or IoT data can be fetched directly from web servers publishing such data and then processed by canister smart contracts, without relying on trusted third party services. + +Moreover, ICP was extended to interact with other blockchains. In 2022, ICP brought programmability to Bitcoin. This was achieved by two innovations, network-level interaction between ICP and Bitcoin and chain-key signatures, which together form [Bitcoin integration](https://learn.internetcomputer.org/hc/en-us/articles/34209531762324). Network-level interaction lets canisters read the Bitcoin blockchain and send messages to the Bitcoin nodes directly, without any intermediaries. [Chain-key signatures](https://learn.internetcomputer.org/hc/en-us/articles/34209497587732) enable canisters to control a Bitcoin address and sign Bitcoin transactions. In 2024 support for additional signature schemes was added, which enables canisters to build applications for Ordinals and token standards like BRC-20 and Runes. + +To interact with Ethereum, as well as other chains using the Ethereum Virtual Machine (EVM), canisters can now send transactions to EVM chains nodes and get EVM chain data from several EVM chains via the [EVM RPC canister](https://internetcomputer.org/docs/current/developer-docs/multi-chain/ethereum/evm-rpc/overview/). This canister relies on the chain-key signature and HTTPs outcalls features mentioned above. + +Among other applications, Bitcoin and Ethereum integration has been used to bring digital token twins to ICP. These twin tokens, called [chain-key tokens](https://learn.internetcomputer.org/hc/en-us/articles/34211397080980), including ckBTC, ckETH, ckUSDC, and ckUSDT, are fully backed by their native tokens and controlled by a canister smart contract. This comes with high security guarantees and lets smart contracts on ICP to hold and transact these tokens at high speed and low cost. + +### Developer and User Experience + +The ideal world computer will be easy to program for and a pleasure to use, providing an experience superior to today’s web applications. To approach the former, canister developers can benefit not just from more documentation and examples, but improved tooling simplifying testing, deployment, benchmarking and operations. For example, canisters can now use [timers](https://internetcomputer.org/docs/current/motoko/main/base/Timer/) and thus execute code automatically after a specified delay without external triggers. Debugging and optimizing canisters is now simpler thanks to [canister logs](https://internetcomputer.org/docs/current/developer-docs/smart-contracts/maintain/logs/), [performance counters](https://internetcomputer.org/docs/current/references/samples/rust/performance_counters/) and [metrics](https://internetcomputer.org/docs/current/developer-docs/security/security-best-practices/observability-and-monitoring/) accessible to developers. [Motoko memory persistence](https://internetcomputer.org/docs/current/motoko/main/canister-maintenance/orthogonal-persistence/enhanced) was enhanced to make it easier to upgrade canisters to new versions. To simplify the interaction of applications developed by separate teams, [standards](https://github.com/dfinity/ICRC) for ledgers, wallet integration and verifiable credentials were developed. + +To improve user experience, caching and latency-aware request routing have been implemented. This, combined with network and consensus protocol optimizations, has reduced the average end-to-end latency for state-changing calls by over 40%. This brings ICP closer to the performance levels expected from traditional infrastructures, with an average latency of around 1.5 seconds, depending on load and subnet size. Additionally, the user experience for Internet Identity and governance applications has been improved through design changes and streamlined workflows + +In summary, the advancements in the four categories described above enabled the ICP developers to deploy more than 700k canister smart contracts, which occupy more than 6 TB of state and process more than 6000 messages per second. Thousands of NNS proposals have been voted on, among other things, they led to the upgrade of the whole protocol more than 200 times. Several tens of thousands users log into dapps with Internet Identity per day. Decentralization and capacity have been increased, so today the network is kept up and running by more than 1200 nodes located in 105 datacenters geographically distributed across 22 countries. In other words, the IC more than tripled in size. + +## A thriving community + +The Internet Computer community is fast-growing and strong. There are now thousands of developers building on the Internet Computer network, and thousands of applications running on it. Indeed, the developer community regularly clocks more GitHub commits than any other in the blockchain industry. + +Projects running on the Internet Computer are unique in the industry because they run entirely on a decentralized protocol, without reliance on traditional cloud computing. This was already the case for the very first applications, released in 2021. Among them are social networks, messaging services, NFT marketplaces, and wallets. They showcase how an application which is capable of more than ledger transactions can run on decentralized infrastructure at webspeed, including full frontends, forming a fully decentralized application. See [link to ICP ecosystem page](https://internetcomputer.org/ecosystem) for an overview of the applications running on ICP. + +The fast-growing Internet Computer community is focused on building out a new Web3 ecosystem, and eventually moving the vast majority of online systems and services onto the Internet Computer, in a replacement of traditional IT. + diff --git a/.migration/learn-hub/out-of-scope/what-is-icp/what-is-icp.md b/.migration/learn-hub/out-of-scope/what-is-icp/what-is-icp.md new file mode 100644 index 00000000..29489ccf --- /dev/null +++ b/.migration/learn-hub/out-of-scope/what-is-icp/what-is-icp.md @@ -0,0 +1,45 @@ +--- +learn_hub_id: 33152818663444 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/33152818663444-What-is-ICP" +learn_hub_title: "What is ICP?" +learn_hub_section: "Overview" +learn_hub_category: "What is ICP?" +migrated: false +--- + +# What is ICP? + +ICP, the Internet Computer Protocol, is the protocol that underlies the Internet Computer. The Internet Computer extends the Internet by enabling anyone to install and run software on the network. The software running on top of ICP includes anything from social media, enterprise applications, or personal websites to new AI applications such as chat bots. In contrast to centralized cloud platforms, the Internet Computer Protocol is decentralized, which means that it runs on many node machines that are distributed around the world and maintained by independent node providers. + +## Why ICP rather than traditional Backend IT & cloud providers? + +The decentralization of ICP provides the following key advantages compared to traditional backend IT and cloud providers. + + 1. **User-owned applications and data:** Users can control applications, including how they evolve and what happens to the data. For such applications, no single party can unilaterally change the application or the users' data. This is enabled by ICP's built-in access control determining not only who has access to data but also who can change an application. + 2. **Tamperproof:** ICP provably guarantees the integrity of the protocol and applications running on it, even if some node machines are malicious. + 3. **Verifiable:** Applications run on ICP can be fully verifiable so that users know what code they interact with and what happens to their assets and data. For verifiability, the results generated on the platform are jointly signed by the nodes using a protocol. This guarantees that as long as enough of the node machines are honest, anyone interacting with an application on ICP can check that the result is what it should be and no one can have changed it. + 4. **Robustness and Availability:** ICP is resilient against machines that are faulty or unavailable, for example due to bugs or catastrophic events that cause outages or destroy data centers. It remains available even if some providers of node machines decide to stop supporting the platform. This is achieved as ICP is run by many independent parties distributed all over the globe and because these nodes run a fault-tolerant decentralized protocol. This means that the protocol cryptographically ensures integrity of the programs and data as long as a large enough portion (more than two thirds) of the participating nodes are honest. + + + +All these properties and the mechanisms that achieve them are explained in detail in the section [How Does the Internet Computer Work](https://learn.internetcomputer.org/hc/en-us/articles/33694833025172). Together, they realize the [web3](https://en.wikipedia.org/wiki/Web3) vision of an Internet which empowers users with full ownership and control over their online experiences. + +#### Example: Chat application + +To illustrate the above properties, let us consider a chat application. Assume for example, that you are the creator of such an application. If the application is hosted on a single server, then the server could be destroyed due to a storm and the application would not be available to users. If the application is hosted on a cloud provider, usually the cloud provider would ensure that there is some redundancy over different machines and robustness is provided. However, this cloud provider is a single entity that must be trusted: if the cloud provider does not protect the servers, decides to turn them off or restricts access to them for people from certain regions (due to changes in business strategy or regulation), the chat application is not working properly - users from some regions might all of a sudden be unreachable. In contrast, if the chat application is deployed on ICP, there is no single party that must be trusted. ICP is built such that it can tolerate buggy or misbehaving machines and parties. Therefore, ICP seamlessly provides availability and is tamperproof. + +ICP also adds another element that protects the users and ensures that they can fully verify the programs or applications that they are interacting with. Let's again take the chat app as an example. To convince the users that the chat app is implemented well and does not have any bugs or even malicious backdoors to read along with messages or modify them, the developer can open source the code of the app. However, even if users carefully inspect the code, they often have no way of verifying that the application that they interact with is in fact running the code that they have checked. ICP provides this property and ensures that users can verify that a program they interact with is the one that was compiled from a given code. This can even be taken a step further by Open Internet Services that allow users to co-own an application and collectively decide whether and how it is changed. This means that the users of the chat app cannot only decide how the app's functionality is evolved but also have full control over the messages and pictures that they have sent around. This facilitates a more open and inclusive Internet. + +## Why ICP rather than another blockchain? + +The Internet Computer Protocol is a blockchain-based protocol. Compared to other blockchains, ICP has the following advantages. + + * **Users' full ownership of code and data:** ICP is able to host entire general-purpose applications, including all data and the frontend components. Together with the built-in access control, this ensures that entire applications with all their components and data can be fully owned and controlled by users. + * **Seamless user experience:** For interacting with applications on blockchains, users often need to have special accounts and pay for certain interactions. In contrast, users can interact with applications and websites running on ICP in the same way as they interact with traditional applications and websites (on traditional infrastructure). They can read a website in their browser and don’t need to install any special software or extensions to do so. + * **Flexible integration with existing infrastructure and other chains:** ICP enables applications to interact with existing infrastructure, such as websites and tools, through standard Internet protocols. Moreover, applications can also interact with other blockchains. This means that developers are not locked into one platform and can build on components that already exist. + * **Flexibility in programming language:** Developers can build applications using different programming languages. This includes Motoko, which is a language built specifically for ICP and designed to make ICP features easily accessible. It is also possible to use existing languages such as Rust, Python, or Typescript, which ensures a low entry barrier for experienced developers moving to ICP from another platform. + + + +Users can interact with applications on ICP seamlessly because end-users do not need to directly pay for their activity and because the performance is comparable to traditional infrastructure. Applications can be hosted fully on ICP due to the low cost for compute and storage and due to the fact that ICP is scalable and can provide more infrastructure when needed. Another important factor is that, in contrast to other blockchains, ICP supports upgrading applications while keeping their data in a verifiable way, which is needed to evolve applications with changing user needs. The applications that are deployed on ICP can be written in different languages, as they are deployed in a format called WebAssembly, which many other languages can be compiled to. + diff --git a/.migration/learn-hub/out-of-scope/what-is-icp/what-is-the-vision-behind-icp.md b/.migration/learn-hub/out-of-scope/what-is-icp/what-is-the-vision-behind-icp.md new file mode 100644 index 00000000..3f8bd794 --- /dev/null +++ b/.migration/learn-hub/out-of-scope/what-is-icp/what-is-the-vision-behind-icp.md @@ -0,0 +1,29 @@ +--- +learn_hub_id: 33624077003668 +learn_hub_url: "https://learn.internetcomputer.org/hc/en-us/articles/33624077003668-What-is-the-Vision-behind-ICP" +learn_hub_title: "What is the Vision behind ICP?" +learn_hub_section: "Overview" +learn_hub_category: "What is ICP?" +migrated: false +--- + +# What is the Vision behind ICP? + +## The Internet, today + +As more and more of our daily lives happens online, the value of the data we amass, as well as our reliance upon them, also grows: the memories we record in digital photos, our communication in email, messengers, or social media platforms, our financial transaction history, legal documents, calendars, ... the list goes on. But while it seems clear that this data is _our_ data, do _we_ really own it? + +If you are like most people, your photos, email, and calendar are probably stored in some cloud service. This is extremely convenient: data can be accessed from all your devices, and you do not even have to bother with mundane things like backups. It all happens automatically. But it also means that the company that actually stores your data, and takes care of all the operations on your behalf, can revoke _your_ access to _your_ data at any point in time. And that may happen for reasons beyond your control. For example, in a past incident a faulty bot at Google [blocked hundreds of user accounts in error](https://www.businessinsider.com/markiplier-youtube-fans-heist-lost-access-google-accounts-spamming-emotes-2019-11). In such a case, you are at risk of losing access to major parts of your private data, including photos, emails, and calendar events. What would your life look like if you lost access to all that data today? + +A lot of platforms and companies do not work in your best interest either. Their offers may seem cheap or may not require any monetary payment at all, but you end up paying in a different way: with your data. Social media sites require you to give up any and all ownership rights you have on the content you post. Every crumb of data you leave across the web is used to influence your behavior via advertisement. And nowadays, most services require you to sign off on them using _your_ private data to train _their_ AI models. What will the data be used for and may any of your data leak throughout the process? You never know. But it is someone else's profits that will drive the decisions. + +In today's web, _you_ do not actually own _your_ data. + +## The Internet, tomorrow + +Pioneered by Bitcoin, the introduction of decentralized protocols built on blockchain technology restores end-user agency and removes the reliance on traditional and proprietary IT systems. It also removes the need for expensive legacy intermediaries, for example for financial applications. + +Bitcoin encodes ownership for a monetary token that can be used for payment across the Internet. Ethereum and other second-generation blockchains use smart contracts to generalize the types of tokens that they managed and implement additional functionality, like trading. Due to their technical limitations and the resulting transaction prices, however, the smart contracts as well as the objects stored on such chains are very small. A non-fungible token (NFT) representing an image, for example, generally does not contain the image itself but merely a reference to the image stored on a traditional web server, which comes with the downsides mentioned above. As such, blockchains like Bitcoin and Ethereum can truly encode ownership for a very small fraction of tasks we perform on the Internet. + +The Internet Computer Protocol (ICP) goes one step beyond by realizing the vision of a _World Computer_. That is, extending the Internet's functionality so that it becomes a universal platform upon which the ownership of all code and data can be encoded. Users can truly own the data they store online, and validate all code that is accessing or manipulating that data. This also enables new and novel systems, such as community or [DAO](https://learn.internetcomputer.org/hc/en-us/articles/34084394684564)-owned services without the need for any centralized intermediaries. ICP achieves this through a blockchain network that uses node machines operating from independent datacenters worldwide, creating a fast, seamless, and scalable network. The Internet Computer thus extends the Internet's technology stack, enabling developers and other creators to build decentralized applications and other systems that respect the users' ownership of their data. + diff --git a/AGENTS.md b/AGENTS.md index 7f7dfca8..5ad27e16 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -134,14 +134,14 @@ git checkout main - Reference `dfx` — it is deprecated and banned - Use `mo:base` imports in Motoko code examples — use `mo:core` instead. Critical replacements: `Buffer` → `List`, `HashMap`/`TrieMap`/`Trie`/`RBTree` → `Map`, `Deque` → `Queue`, `OrderedMap` → `pure/Map`, `OrderedSet` → `pure/Set` - Create `.mdx` files without a clear need for interactive components — default to `.md` -- Duplicate content that lives in external docs (icp-cli, JS SDK, icskills, Learn Hub) +- Duplicate content that lives in external docs (icp-cli, JS SDK, icskills) - Edit synced files directly (`docs/languages/motoko/`, `docs/guides/tools/migrating-from-dfx.md`) - Nest sidebar items more than 3 levels deep - Skip reading source material before writing a page - Write code snippets from memory — find and adapt from actual upstream code in `.sources/` - Modify the rationale or context of existing decisions in `.docs-plan/decisions.md` — you may remove entries that are fully reflected in the current codebase but never alter reasoning behind active decisions - Add `Co-Authored-By` or any AI attribution to commits or PR descriptions -- Link to `internetcomputer.org/docs/` — that site is retired. For internal pages use relative paths, not absolute `docs.internetcomputer.org/...` URLs. Link to Learn Hub or explain inline for external content. +- Link to `internetcomputer.org/docs/` — that site is retired. For internal pages use relative paths, not absolute `docs.internetcomputer.org/...` URLs. Explain inline or link to `docs/concepts/` for protocol-level background; do not link to `learn.internetcomputer.org` (Learn Hub is being retired and its content is being migrated into this site — see `.docs-plan/learn-hub-migration.md`). - Link to internal pages that don't exist — every `[text](path.md)` must resolve to an actual file. Run `ls <target>` before linking. Links to `.mdx` pages use `.md` extension (Astro resolves both). - Link to a page without a section anchor when the surrounding context refers to a specific topic covered by a subsection — always check the target file's headings and include `#anchor` when a more precise destination exists. Verify anchors by grepping headings: `grep "^## \|^### " <target>`. Anchor slugs: lowercase, spaces → `-`, special chars stripped. - Link to `https://cli.internetcomputer.org/` (bare root) — all CLI doc pages are under a versioned path. Use `https://cli.internetcomputer.org/0.2/<path>` (current slug; verify with `cat .sources/icp-cli/docs-site/versions.json`) and confirm the path exists in `.sources/icp-cli/docs/<path>.md`. For command-specific links add a section anchor from `.sources/icp-cli/docs/reference/cli.md` (e.g. `#icp-canister-logs`, `#icp-canister-settings-update`, `#icp-cycles`). When bumping icp-cli to a new minor version, follow the "Link adaptation for `icp-cli`" checklist in "Bumping submodules". diff --git a/docs/index.mdx b/docs/index.mdx index 8c662be2..7cb1aecb 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -42,5 +42,4 @@ Teach your AI coding agent the patterns, APIs, and deployment workflows it needs <LinkCard title="ICP CLI" description="Command-line tool for ICP development" href="https://cli.internetcomputer.org/0.2/" /> <LinkCard title="JS SDK" description="JavaScript/TypeScript libraries for ICP" href="https://js.icp.build" /> <LinkCard title="ICP Skills" description="Skills for agents that write code on ICP" href="https://skills.internetcomputer.org" /> - <LinkCard title="Learn Hub" description="Deep protocol-level explanations" href="https://learn.internetcomputer.org" /> </CardGrid> From 0bb7ab6e40c1cdbdee36e0f7644a8332f0799171 Mon Sep 17 00:00:00 2001 From: Marco Walz <marco.walz@dfinity.org> Date: Wed, 6 May 2026 15:42:16 +0200 Subject: [PATCH 2/6] docs: remove icskill requirement from Learn Hub migration instructions --- .docs-plan/learn-hub-migration.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/.docs-plan/learn-hub-migration.md b/.docs-plan/learn-hub-migration.md index e58f8e11..1b135085 100644 --- a/.docs-plan/learn-hub-migration.md +++ b/.docs-plan/learn-hub-migration.md @@ -16,10 +16,13 @@ ls .agents/skills/technical-documentation/SKILL.md .agents/skills/icp-brand-voic # If broken symlinks: git submodule update --init --depth 1 ``` -Load these before writing: -- `technical-documentation` -- `icp-brand-voice` -- The relevant icskill for the batch topic (see CLAUDE.md skills table) +Load before writing: +- `technical-documentation` — doc structure, quality criteria, review checklist +- `icp-brand-voice` — banned terms, preferred vocabulary, tone + +Do **not** load icskills. The icskills provide implementation patterns: canister IDs, SDK API signatures, code examples. Learn Hub content is pure concept and explanation — no code, no canister calls, no SDK usage. The staging file is the source; icskills add nothing here. + +One exception: if a page mentions a specific system canister by name (exchange rate canister, ckBTC minter, etc.), verify its canister ID against `docs/references/chain-key-canister-ids.md` directly — no need to load the full skill for a single lookup. --- From 2c88e6c0b7747ae266b59fe264a2d519f272716e Mon Sep 17 00:00:00 2001 From: Marco Walz <marco.walz@dfinity.org> Date: Wed, 6 May 2026 15:45:16 +0200 Subject: [PATCH 3/6] docs: emphasise icp-brand-voice importance for Learn Hub jargon cleanup --- .docs-plan/learn-hub-migration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.docs-plan/learn-hub-migration.md b/.docs-plan/learn-hub-migration.md index 1b135085..a5742898 100644 --- a/.docs-plan/learn-hub-migration.md +++ b/.docs-plan/learn-hub-migration.md @@ -18,7 +18,7 @@ ls .agents/skills/technical-documentation/SKILL.md .agents/skills/icp-brand-voic Load before writing: - `technical-documentation` — doc structure, quality criteria, review checklist -- `icp-brand-voice` — banned terms, preferred vocabulary, tone +- `icp-brand-voice` — **critical for migration work.** Learn Hub articles were written for a broad audience and routinely use terms the brand voice rules ban or require reframing: "smart contracts", "blockchain", "Web3", "decentralized application", and similar. Migrating without applying these rules imports the jargon wholesale. Every sentence adapted from a staging file must pass the brand voice filter. Do **not** load icskills. The icskills provide implementation patterns: canister IDs, SDK API signatures, code examples. Learn Hub content is pure concept and explanation — no code, no canister calls, no SDK usage. The staging file is the source; icskills add nothing here. From 60ec72f195d6d2b4cbea008fefa56af1a906508b Mon Sep 17 00:00:00 2001 From: Marco Walz <marco.walz@dfinity.org> Date: Wed, 6 May 2026 16:31:18 +0200 Subject: [PATCH 4/6] infra: batch PRs target prep branch, not main; add sync-with-main note --- .docs-plan/learn-hub-migration.md | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/.docs-plan/learn-hub-migration.md b/.docs-plan/learn-hub-migration.md index a5742898..36dc500a 100644 --- a/.docs-plan/learn-hub-migration.md +++ b/.docs-plan/learn-hub-migration.md @@ -30,10 +30,12 @@ One exception: if a page mentions a specific system canister by name (exchange r Find your batch in `.docs-plan/learn-hub-navigation.md`. Each batch has a name (e.g. "Batch 1 — Protocol stack") and a branch name (e.g. `docs/concepts-protocol-stack`). +All batch PRs target `infra/learn-hub-migration-prep`, not `main`. The prep branch accumulates all migration content so the full result can be previewed before anything merges to `main`. + ```bash git fetch origin git ls-remote origin docs/<slug> # if output is empty, branch doesn't exist yet -git checkout -b docs/<slug> origin/main +git checkout -b docs/<slug> origin/infra/learn-hub-migration-prep ``` --- @@ -235,7 +237,10 @@ Examples: ```bash git push -u origin docs/<slug> -gh pr create --title "docs: <descriptive title>" --body "$(cat <<'EOF' +gh pr create \ + --base infra/learn-hub-migration-prep \ + --title "docs: <descriptive title>" \ + --body "$(cat <<'EOF' ## Summary - <bullet: what pages were created or expanded> - <bullet: what cross-links were updated> @@ -279,12 +284,19 @@ EOF )" ``` -Once a human approves disposal, open the final cleanup PR: +Once a human approves disposal, open the final cleanup PR (also targeting `infra/learn-hub-migration-prep`): 1. Delete `.migration/learn-hub/` entirely (including the reviewed skip files) -2. In CLAUDE.md: remove the "Learn Hub is being retired" note from the `internetcomputer.org/docs/` rule (replace it with just "explain inline or link to `docs/concepts/`") +2. In CLAUDE.md: remove the "Learn Hub is being retired" note from the `internetcomputer.org/docs/` rule (replace with just "explain inline or link to `docs/concepts/`") 3. In `.docs-plan/decisions.md`: mark the 2026-05-06 entry as fully reflected, then remove it 4. Run `npm run build` and push +After the final cleanup PR merges into `infra/learn-hub-migration-prep`, a maintainer: +1. Rebases `infra/learn-hub-migration-prep` on `main` to pick up any drift +2. Marks PR #208 ready for review +3. Merges to `main` + +**Keeping the prep branch in sync with main:** If `main` receives commits during the migration window (e.g. guide updates, bug fixes), periodically rebase or merge `main` into `infra/learn-hub-migration-prep` to avoid a large conflict at the end. This is a maintainer task — batch PR authors do not need to worry about it. + --- ## Batch dependency order From 8693f43d302ba7e626f599b22cfe7605e5a0e731 Mon Sep 17 00:00:00 2001 From: Marco Walz <marco.walz@dfinity.org> Date: Wed, 6 May 2026 16:47:12 +0200 Subject: [PATCH 5/6] infra: replace GitHub Issues with branch-based status tracking for migration batches --- .docs-plan/migration-plan.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/.docs-plan/migration-plan.md b/.docs-plan/migration-plan.md index 80d9eecf..92926e5b 100644 --- a/.docs-plan/migration-plan.md +++ b/.docs-plan/migration-plan.md @@ -404,16 +404,16 @@ languages/rust/index.md Nine content PRs to migrate learn.internetcomputer.org articles into `docs/`. Source staging files are in `.migration/learn-hub/`. Full article-to-file mapping and cross-link instructions: `.docs-plan/learn-hub-navigation.md`. Per-batch agent workflow: `.docs-plan/learn-hub-migration.md`. -| Batch | Branch | Target files | Effort | -|---|---|---|---| -| 1 — Protocol stack | `docs/concepts-protocol-stack` | `concepts/protocol/index.md`, `consensus.md`, `peer-to-peer.md`, `message-routing.md`, `execution.md`, `state-synchronization.md` | Large | -| 2 — Node infrastructure | `docs/concepts-node-infrastructure` | `concepts/node-infrastructure.md` | Medium | -| 3 — Edge infrastructure | `docs/concepts-edge-infrastructure` | `concepts/edge-infrastructure.md` | Medium | -| 4 — Evolution & scaling | `docs/concepts-evolution-scaling` | `concepts/evolution-scaling.md` | Small–medium | -| 5 — Chain Fusion deep dives | `docs/concepts-chain-fusion-deep-dives` | `concepts/chain-fusion/index.md` (moved), `bitcoin.md`, `ethereum.md`, `solana.md`, `dogecoin.md`, `exchange-rate-canister.md`, `chain-key-tokens.md` | Large | -| 6 — Cryptography deep dives | `docs/concepts-cryptography-deep-dives` | `concepts/certified-data.md`, expand `concepts/chain-key-cryptography.md` | Medium | -| 7 — Governance deep dives | `docs/concepts-governance-deep-dives` | expand `concepts/governance.md`, `concepts/sns-framework.md`, `references/nns-proposal-types.md`, `references/sns-dao-settings.md` | Large | -| 8 — Tokens & ledgers | `docs/concepts-tokens-ledgers` | `concepts/tokenomics.md`, `concepts/token-ledgers.md`, expand `concepts/cycles.md` | Medium | -| 9 — Canister concept fillers | `docs/concepts-canister-fillers` | `concepts/principals.md`, expand `concepts/canisters.md` | Medium | - -Recommended order: batches 1–4 can run in parallel. Batch 8 before batch 7 (governance links to tokenomics). Batches 5, 6, 9 independent. +To claim a batch: check `git ls-remote origin docs/concepts-*` — branch exists means claimed, open PR against `infra/learn-hub-migration-prep` means in progress, branch gone (merged) means done. No GitHub Issues needed. Full workflow: `.docs-plan/learn-hub-migration.md`. + +| Batch | Branch | Target files | Effort | Status | +|---|---|---|---|---| +| 1 — Protocol stack | `docs/concepts-protocol-stack` | `concepts/protocol/index.md`, `consensus.md`, `peer-to-peer.md`, `message-routing.md`, `execution.md`, `state-synchronization.md` | Large | open | +| 2 — Node infrastructure | `docs/concepts-node-infrastructure` | `concepts/node-infrastructure.md` | Medium | open | +| 3 — Edge infrastructure | `docs/concepts-edge-infrastructure` | `concepts/edge-infrastructure.md` | Medium | open | +| 4 — Evolution & scaling | `docs/concepts-evolution-scaling` | `concepts/evolution-scaling.md` | Small–medium | open | +| 5 — Chain Fusion deep dives | `docs/concepts-chain-fusion-deep-dives` | `concepts/chain-fusion/index.md` (moved), `bitcoin.md`, `ethereum.md`, `solana.md`, `dogecoin.md`, `exchange-rate-canister.md`, `chain-key-tokens.md` | Large | open | +| 6 — Cryptography deep dives | `docs/concepts-cryptography-deep-dives` | `concepts/certified-data.md`, expand `concepts/chain-key-cryptography.md` | Medium | open | +| 7 — Governance deep dives | `docs/concepts-governance-deep-dives` | expand `concepts/governance.md`, `concepts/sns-framework.md`, `references/nns-proposal-types.md`, `references/sns-dao-settings.md` | Large | open (do batch 8 first) | +| 8 — Tokens & ledgers | `docs/concepts-tokens-ledgers` | `concepts/tokenomics.md`, `concepts/token-ledgers.md`, expand `concepts/cycles.md` | Medium | open | +| 9 — Canister concept fillers | `docs/concepts-canister-fillers` | `concepts/principals.md`, expand `concepts/canisters.md` | Medium | open | From fd60aeb480dc2cedb6b0085ee78552179cfb14e8 Mon Sep 17 00:00:00 2001 From: Marco Walz <marco.walz@dfinity.org> Date: Thu, 7 May 2026 13:00:56 +0200 Subject: [PATCH 6/6] docs(index): add examples repo to external resources --- docs/index.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/index.mdx b/docs/index.mdx index 7cb1aecb..2e485ee6 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -42,4 +42,5 @@ Teach your AI coding agent the patterns, APIs, and deployment workflows it needs <LinkCard title="ICP CLI" description="Command-line tool for ICP development" href="https://cli.internetcomputer.org/0.2/" /> <LinkCard title="JS SDK" description="JavaScript/TypeScript libraries for ICP" href="https://js.icp.build" /> <LinkCard title="ICP Skills" description="Skills for agents that write code on ICP" href="https://skills.internetcomputer.org" /> + <LinkCard title="Examples" description="Working Motoko and Rust canister examples" href="https://github.com/dfinity/examples" /> </CardGrid>