diff --git a/docs/concepts/canisters.md b/docs/concepts/canisters.md index deb30018..9a3aac45 100644 --- a/docs/concepts/canisters.md +++ b/docs/concepts/canisters.md @@ -5,7 +5,7 @@ sidebar: order: 2 --- -Canisters are the compute units of the Internet Computer. Each canister bundles compiled WebAssembly code with its own persistent state into a single unit that the network executes, replicates, and secures. You deploy code to a canister, send it messages, and the network guarantees that every honest node in the subnet reaches the same result. +Canisters are the compute units of the Internet Computer. Each canister bundles compiled WebAssembly code with its own persistent state into a single unit that the network executes, replicates, and secures. You deploy code to a canister, send it messages, and the network guarantees that every honest node in the [subnet](network-overview.md#subnets) reaches the same result. Unlike programs on most other blockchains, canisters can serve web pages over HTTP, store gigabytes of data, make calls to external APIs, sign transactions on other chains, and run scheduled tasks autonomously, all without external infrastructure. diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md index 11b3192d..802851c9 100644 --- a/docs/getting-started/quickstart.md +++ b/docs/getting-started/quickstart.md @@ -21,7 +21,7 @@ npm install -g @icp-sdk/icp-cli @icp-sdk/ic-wasm This installs: -- **icp-cli**: builds and deploys canisters on the Internet Computer +- **icp-cli**: builds and deploys [canisters](../concepts/canisters.md) on the Internet Computer - **ic-wasm**: optimizes WebAssembly modules for onchain deployment For Motoko projects, also install the Motoko package manager: diff --git a/docs/guides/backends/certified-variables.md b/docs/guides/backends/certified-variables.md index c1d489dd..e0b282b0 100644 --- a/docs/guides/backends/certified-variables.md +++ b/docs/guides/backends/certified-variables.md @@ -5,7 +5,7 @@ sidebar: order: 5 --- -Query calls on ICP are answered by a single replica without going through consensus. This means a malicious or faulty replica could return fabricated data. **Certified variables** solve this: the canister stores a hash in the subnet's certified state during an update call, and query responses include a certificate signed by the subnet's threshold BLS key, proving the data is authentic. The result is responses that are both fast (no consensus delay) and cryptographically verified. +Query calls on ICP are answered by a single replica without going through consensus. This means a malicious or faulty replica could return fabricated data. **Certified variables** solve this: the [canister](../../concepts/canisters.md) stores a hash in the [subnet's](../../concepts/network-overview.md#subnets) certified state during an update call, and query responses include a certificate signed by the subnet's threshold BLS key, proving the data is authentic. The result is responses that are both fast (no consensus delay) and cryptographically verified. For a conceptual overview of why query integrity matters, see [Security concepts](../../concepts/security.md). diff --git a/docs/guides/backends/data-persistence.mdx b/docs/guides/backends/data-persistence.mdx index c3547c84..c6727ef5 100644 --- a/docs/guides/backends/data-persistence.mdx +++ b/docs/guides/backends/data-persistence.mdx @@ -7,7 +7,7 @@ sidebar: import { Tabs, TabItem } from '@astrojs/starlight/components'; -Canister state lives in two places: **heap memory** and **stable memory** (persistent, survives upgrades). In Rust and most languages, heap memory is wiped on upgrade: any data you care about must be stored in stable memory. In Motoko, the `persistent actor` pattern automatically preserves all actor state across upgrades without any additional work. +[Canister](../../concepts/canisters.md) state lives in two places: **heap memory** and **stable memory** (persistent, survives upgrades). In Rust and most languages, heap memory is wiped on upgrade: any data you care about must be stored in stable memory. In Motoko, the `persistent actor` pattern automatically preserves all actor state across upgrades without any additional work. This guide shows how to store data durably in both Motoko and Rust. For a conceptual explanation of why stable memory works this way, see [Orthogonal Persistence](../../concepts/orthogonal-persistence.md). diff --git a/docs/guides/backends/https-outcalls.mdx b/docs/guides/backends/https-outcalls.mdx index 161cf494..6c132155 100644 --- a/docs/guides/backends/https-outcalls.mdx +++ b/docs/guides/backends/https-outcalls.mdx @@ -8,7 +8,7 @@ sidebar: import { Tabs, TabItem } from '@astrojs/starlight/components'; import CodeExample from '../../../src/components/CodeExample.astro'; -Canisters can make HTTP requests to external web services using HTTPS outcalls. This lets your canister fetch offchain data, call REST APIs, or send notifications: all from onchain code. +[Canisters](../../concepts/canisters.md) can make HTTP requests to external web services using HTTPS outcalls. This lets your canister fetch offchain data, call REST APIs, or send notifications: all from onchain code. HTTPS outcalls are available through the [IC management canister](../../reference/management-canister.md) (`aaaaa-aa`) via the `http_request` method. The `GET`, `HEAD`, and `POST` methods are supported. `HEAD` works identically to `GET` but returns only headers: useful for checking resource availability without downloading the body. Only HTTPS (not plain HTTP) is supported. diff --git a/docs/guides/backends/randomness.md b/docs/guides/backends/randomness.md index fd89f6fd..51e30391 100644 --- a/docs/guides/backends/randomness.md +++ b/docs/guides/backends/randomness.md @@ -5,7 +5,7 @@ sidebar: order: 4 --- -Canisters can generate cryptographically secure random numbers directly from canister code. This guide shows how to call the `raw_rand` method, derive typed values from the returned bytes, and use randomness safely. +[Canisters](../../concepts/canisters.md) can generate cryptographically secure random numbers directly from canister code. This guide shows how to call the `raw_rand` method, derive typed values from the returned bytes, and use randomness safely. For how ICP produces unpredictable randomness without any trusted party, see [Onchain Randomness](../../concepts/onchain-randomness.md). diff --git a/docs/guides/backends/timers.mdx b/docs/guides/backends/timers.mdx index 2d6a54c9..907d6547 100644 --- a/docs/guides/backends/timers.mdx +++ b/docs/guides/backends/timers.mdx @@ -7,7 +7,7 @@ sidebar: import { Tabs, TabItem } from '@astrojs/starlight/components'; -Canisters can schedule code to run automatically after a delay or on a repeating interval. No external cron job required. This guide covers the timer APIs for Rust and Motoko, how system time works, upgrade handling, and when to use heartbeats instead. +[Canisters](../../concepts/canisters.md) can schedule code to run automatically after a delay or on a repeating interval. No external cron job required. This guide covers the timer APIs for Rust and Motoko, how system time works, upgrade handling, and when to use heartbeats instead. ## System time diff --git a/docs/guides/canister-management/subnet-selection.md b/docs/guides/canister-management/subnet-selection.md index 2e1dbfc3..63a67e40 100644 --- a/docs/guides/canister-management/subnet-selection.md +++ b/docs/guides/canister-management/subnet-selection.md @@ -5,7 +5,7 @@ sidebar: order: 8 --- -The Internet Computer is composed of independent subnets: each a blockchain that hosts canisters and runs its own consensus. By default, icp-cli selects a subnet automatically when you deploy. This guide explains when and how to target a specific subnet. +The Internet Computer is composed of independent [subnets](../../concepts/network-overview.md#subnets): each a blockchain that hosts [canisters](../../concepts/canisters.md) and runs its own consensus. By default, icp-cli selects a subnet automatically when you deploy. This guide explains when and how to target a specific subnet. ## When to choose a subnet diff --git a/docs/guides/frontends/asset-canister.md b/docs/guides/frontends/asset-canister.md index d01d7dbf..71c2be51 100644 --- a/docs/guides/frontends/asset-canister.md +++ b/docs/guides/frontends/asset-canister.md @@ -5,7 +5,7 @@ sidebar: order: 1 --- -The asset canister hosts static files (HTML, CSS, JavaScript, images) directly on the Internet Computer. It serves web frontends over HTTP, with responses certified by the subnet so that HTTP gateways and browsers can verify that content was served by the blockchain rather than a centralized server. +The asset [canister](../../concepts/canisters.md) hosts static files (HTML, CSS, JavaScript, images) directly on the Internet Computer. It serves web frontends over HTTP, with responses certified by the [subnet](../../concepts/network-overview.md#subnets) so that HTTP gateways and browsers can verify that content was served by the blockchain rather than a centralized server. This guide covers configuring the asset canister recipe in `icp.yaml`, deploying frontends, configuring SPA routing with `.ic-assets.json5`, connecting frontends to backend canisters, and uploading assets programmatically. diff --git a/docs/guides/frontends/frameworks.md b/docs/guides/frontends/frameworks.md index 44039d6b..3822a80e 100644 --- a/docs/guides/frontends/frameworks.md +++ b/docs/guides/frontends/frameworks.md @@ -5,7 +5,7 @@ sidebar: order: 4 --- -ICP hosts frontend applications as asset canisters: static files (HTML, CSS, JavaScript) deployed onchain and served with certified responses. Any framework that can produce a static build output works: React, Vue, Svelte, Next.js, and even game engines like Unity WebGL and Godot. +ICP hosts frontend applications as asset [canisters](../../concepts/canisters.md): static files (HTML, CSS, JavaScript) deployed onchain and served with certified responses. Any framework that can produce a static build output works: React, Vue, Svelte, Next.js, and even game engines like Unity WebGL and Godot. This guide shows you how to configure your framework's build pipeline, wire up the ICP JavaScript SDK, and deploy to an asset canister. diff --git a/docs/guides/testing/pocket-ic.md b/docs/guides/testing/pocket-ic.md index ab6f4fa3..f7e214c5 100644 --- a/docs/guides/testing/pocket-ic.md +++ b/docs/guides/testing/pocket-ic.md @@ -5,7 +5,7 @@ sidebar: order: 2 --- -PocketIC is a lightweight, deterministic testing library for canister integration tests. Unlike the full local network started by `icp network start`, PocketIC runs entirely inside your test process. No daemon, no ports, no Docker required. Tests execute synchronously, making them fast and fully reproducible. +PocketIC is a lightweight, deterministic testing library for [canister](../../concepts/canisters.md) integration tests. Unlike the full local network started by `icp network start`, PocketIC runs entirely inside your test process. No daemon, no ports, no Docker required. Tests execute synchronously, making them fast and fully reproducible. The `icp-cli` local development network also uses PocketIC under the hood, so behavior you observe in tests closely matches what you see during development. diff --git a/docs/guides/testing/strategies.md b/docs/guides/testing/strategies.md index aa13a404..45f53bf1 100644 --- a/docs/guides/testing/strategies.md +++ b/docs/guides/testing/strategies.md @@ -5,7 +5,7 @@ sidebar: order: 1 --- -Testing canisters on ICP deserves particular attention for two reasons. First, canister upgrades are irreversible in +Testing [canisters](../../concepts/canisters.md) on ICP deserves particular attention for two reasons. First, canister upgrades are irreversible in practice: once a buggy upgrade runs `pre_upgrade`, your stable memory may be corrupted before you can roll back. Second, cycles cost real money: a performance regression that doubles your instruction count doubles your operating cost. Catching these problems in tests before deployment avoids both classes of harm. diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md index c7b6e1e7..5ea0eaae 100644 --- a/docs/reference/glossary.md +++ b/docs/reference/glossary.md @@ -12,20 +12,12 @@ sidebar: #### account -A ledger **account** is a set of entries in the [ ledger -canister](#ledger-canister), which is a smart contract that -mimics the guise and behavior of a regular banking account, whose unit -of measure is [ICP](#i) (Internet Computer Protocol) -utility tokens. Ledger accounts are owned by [ -principals](#p), and their ownerships do not change -over time. Every account on the ledger has a positive [ -balance](#b) measured in ICP with a precision of eight -decimals. +A ledger **account** is a set of entries in the [ledger canister](#ledger-canister), similar to a bank account, denominated in [ICP](#icp) (Internet Computer Protocol) utility tokens. Ledger accounts are owned by [principals](#principal), and their ownerships do not change over time. Every account on the ledger has a positive [balance](#balance) measured in ICP with a precision of eight decimals. #### address -In the context of [transactions](#t) on the ledger, -**address** is synonymous with [ account](#a). +In the context of [transactions](#transaction) on the ledger, +**address** is synonymous with [ account](#account). #### actor @@ -33,74 +25,65 @@ An **actor** is a primitive in the [actor model](https://en.wikipedia.org/wiki/Actor-model). It is a process with encapsulated state that communicates with other concurrently running actors through asynchronous messages that are received sequentially. The -actor model is relevant to the [ICP](#i) -because [canisters](#c) on ICP (a type of smart -contract) follow the actor model for concurrent and asynchronous +actor model is relevant to the [ICP](#icp) +because [canisters](#canister) on ICP follow the actor model for concurrent and asynchronous computation. ## B #### balance -The **balance** of an [account](#a) on the ledger is +The **balance** of an [account](#account) on the ledger is the sum of all deposits minus the sum of all withdrawals. As a degenerate case, it is sometimes useful to say that an account that is not present in the ledger has a balance of zero. The balance of a ledger account is denominated in ICP and is represented with eight decimals. Thus, the minimum positive balance of an account is -0.00000001 or 10^-8 [ICP](#i); this amount is sometimes +0.00000001 or 10^-8 [ICP](#icp); this amount is sometimes referred to as one **e8**. #### batch -A **batch** is a collection of [messages](#m) whose -order is agreed upon by [consensus](#c). +A **batch** is a collection of [messages](#message) whose +order is agreed upon by [consensus](#consensus). #### beneficiary -The **beneficiary** of an [account](#a) is the [ -principal](#p) who owns the [ -balance](#b) of the account. The beneficiary of an +The **beneficiary** of an [account](#account) is the [principal](#principal) who owns the [balance](#balance) of the account. The beneficiary of an account cannot be changed. The beneficiary of an account may or may not -be allowed to make [transactions](#t) on the -account (see [fiduciary](#f)). +be allowed to make [transactions](#transaction) on the +account (see [fiduciary](#fiduciary)). #### blockchain A **blockchain** is a growing list of cryptographically linked blocks, -agreed upon by [consensus](#c). On the [Internet -Computer](#i), every [subnet](#s) maintains its own -blockchain with blocks containing messages for the [canisters](#c) -hosted on this subnet. These blockchains interact using [chain-key cryptography](#c). +agreed upon by [consensus](#consensus). On the [Internet Computer](#internet-computer-protocol-icp), every [subnet](#subnet) maintains its own +blockchain with blocks containing messages for the [canisters](#canister) +hosted on this subnet. These blockchains interact using [chain-key cryptography](#chain-key). #### boundary nodes **Boundary nodes** are gateways to the Internet Computer. These nodes -allow users to access the [canister](#c) smart contracts -running on ICP. +allow users to access the [canisters](#canister) running on ICP. The boundary nodes have several purposes: they aid in discover-ability (the `icp0.io` domain name points to a set of boundary nodes), they are geo-aware and can route incoming requests to the nearest subnet -[node](#n) that hosts the [canister](#c) +[node](#node) that hosts the [canister](#canister) involved, they can help load balance query -[transactions](#t), they can cache +[transactions](#transaction), they can cache cryptographically verified data in the role of a content distribution network, they can throttle excessive interactions from an outside IP address, and they can help protect subnets from DDoS attacks. #### burning transaction -A **burning transaction** is the process of "burning" [ -ICP](#i), whereby a certain amount of ICP is destroyed. -The main use case is purchasing [cycles](#c), +A **burning transaction** is the process of "burning" [ICP](#icp), whereby a certain amount of ICP is destroyed. +The main use case is purchasing [cycles](#cycle), through which ICP is destroyed while at the same time a corresponding amount of cycles is created, using the current exchange rate between ICP -and ([XDR](#x)), in such a way that one XDR corresponds to -one trillion (10E12) cycles. It is represented as a [ -transaction](#t) from the source [ -account](#a) to the [ ICP supply -account](#i). +and ([XDR](#xdr)), in such a way that one XDR corresponds to +one trillion (10E12) cycles. It is represented as a [transaction](#transaction) from the source [account](#account) to the [ICP supply account](#icp-supply-account). ## C @@ -113,18 +96,14 @@ languages. #### canister -A **canister** is a type of smart contract that bundles **code** and -**state**. A canister can be deployed as a [smart -contract](#s) on the [Internet -Computer](#i) and accessed over the Internet. +A **canister** is a compute unit that bundles **code** and **state**. Canisters run on the [Internet Computer](#internet-computer-protocol-icp) and are accessible over the Internet. #### canister account -A **canister account** is a ledger account owned by a [ -canister](#c) (i.e., whose -[fiduciary](#f) is a canister). A non-canister +A **canister account** is a ledger account owned by a [canister](#canister) (i.e., whose +[fiduciary](#fiduciary) is a canister). A non-canister account is a ledger account whose fiduciary is a non-canister -[principal](#p). +[principal](#principal). #### canister development kit (CDK) @@ -133,27 +112,25 @@ A **canister development kit** is an adapter used by the IC SDK that provides a #### canister identifier The **canister identifier** or **canister ID** is a globally unique -identifier that identifies a [canister](#c) and can +identifier that identifies a [canister](#canister) and can be used to interact with it. #### canister signature -A **canister signature** uses a signature scheme based on [certified -variables](#c). Public “keys” include a -[canister id](#c) plus a seed (so that -every [canister](#c) has many public keys); signatures +A **canister signature** uses a signature scheme based on [certified variables](#certified-variable). Public “keys” include a +[canister id](#canister-identifier) plus a seed (so that +every [canister](#canister) has many public keys); signatures are certificates that prove that the canister has put the signed message at a specific place in its state tree. Details can be found in the [Internet Computer interface specification](./ic-interface-spec.md). #### canister state A **canister state** is the entire state of a -[canister](#c) at a given point in time. A canister’s +[canister](#canister) at a given point in time. A canister’s state is divided into **user state** and **system state**. The user state is -a [WebAssembly](#w) module instance and the system -state is the auxiliary state maintained by the [Internet -Computer](#i) on behalf of the canister, such -as its compute allocation, balance of [cycles](#c), +a [WebAssembly](#webassembly) module instance and the system +state is the auxiliary state maintained by the [Internet Computer](#internet-computer-protocol-icp) on behalf of the canister, such +as its compute allocation, balance of [cycles](#cycle), input and output queues, and other metadata. A canister interacts with its own system state either implicitly, such as when consuming cycles, or through the system API, such as when sending messages. @@ -161,8 +138,8 @@ or through the system API, such as when sending messages. #### catch-up package (CUP) A **catch-up package** is a data bundle that contains everything needed -to bootstrap a [subnet](#s) -[replica](#r). +to bootstrap a [subnet](#subnet) +[replica](#replica). #### certified query @@ -171,17 +148,17 @@ certified. #### certified variable -A piece of data that a [canister](#c) can store in its -[subnet](#s)’s canonical state in the processing of an +A piece of data that a [canister](#canister) can store in its +[subnet](#subnet)’s canonical state in the processing of an update call (or inter-canister call), so that during the handling of a -[query](#q) call, the canister can return a certificate +[query](#query) call, the canister can return a certificate to the user that proves that it really committed to that value. #### chain-key **Chain-key** cryptography consists of a set of cryptographic protocols -that orchestrate the [nodes](#n) that make up the -[Internet Computer](#i). The most visible +that orchestrate the [nodes](#node) that make up the +[Internet Computer](#internet-computer-protocol-icp). The most visible innovation of chain-key cryptography is that the Internet Computer has a single public key. This is a huge advantage as it allows any device, including smart watches and mobile phones, to verify the authenticity of @@ -190,32 +167,32 @@ artifacts from the Internet Computer. #### consensus In distributed computing, **consensus** is a [fault-tolerant](https://learn.internetcomputer.org/hc/en-us/articles/34210647901460-Fault-Tolerance) mechanism by -means of which a number of [nodes](#n) can reach agreement +means of which a number of [nodes](#node) can reach agreement about a value or state. -Consensus is a core component of the [replica](#r) -software. The [consensus](https://learn.internetcomputer.org/hc/en-us/articles/34207558615956-Consensus) layer selects [messages](#m) +Consensus is a core component of the [replica](#replica) +software. The [consensus](https://learn.internetcomputer.org/hc/en-us/articles/34207558615956-Consensus) layer selects [messages](#message) from the [peer-to-peer](https://learn.internetcomputer.org/hc/en-us/articles/34207428453140-Peer-to-peer) artifact pool and pulls messages from the -cross-network streams of other [subnets](#s) and -organizes them into a [batch](#b), which is delivered to -the [message routing](#m) layer. +cross-network streams of other [subnets](#subnet) and +organizes them into a [batch](#batch), which is delivered to +the [message routing](#message-routing) layer. #### controller -A **controller** of a [canister](#c) is a person, +A **controller** of a [canister](#canister) is a person, organization, or other canister that has administrative rights over the canister. Controllers are identified by their -[principals](#p). For example, a controller of a -canister can upgrade the [WebAssembly](#w) code of +[principals](#principal). For example, a controller of a +canister can upgrade the [WebAssembly](#webassembly) code of the canister or delete the canister. #### cycle -On the [Internet Computer](#i), a **cycle** +On the [Internet Computer](#internet-computer-protocol-icp), a **cycle** is the unit of measurement for resources consumed in the form of processing, memory, storage, and network bandwidth. Every canister has a cycles account to which resources consumed by the canister are charged. -The Internet Computer’s utility token ([ICP](#i)) can be +The Internet Computer’s utility token ([ICP](#icp)) can be converted to cycles and transferred to a canister. Cycles can also be transferred between canisters by attaching them to an **inter-canister** message. @@ -226,107 +203,94 @@ correspond to one **XDR**. ## D -#### dapp - -A **dapp**, or decentralized application, is a software program that runs -on a decentralized computer network instead of a single computer. On the -[Internet Computer](#i) dapps are composed of -[canister](#c) smart contracts. - #### data center A **data center** (DC) is a physical site that hosts -[nodes](#n) which contribute to the [Internet -Computer](#i). It includes the hardware and +[nodes](#node) which contribute to the [Internet Computer](#internet-computer-protocol-icp). It includes the hardware and software infrastructure required for node deployment. -Data centers are nodes that are selected and vetted by the [NNS](#n). +Data centers are nodes that are selected and vetted by the [NNS](#network-nervous-system-nns). #### dissolve delay The **dissolve delay** is the amount of time that -[neurons](#n) must spend [ -dissolving](#d) before becoming [dissolved](#d). +[neurons](#neuron) must spend [dissolving](#dissolving-state) before becoming [dissolved](#dissolved-state). #### dissolved state -The **dissolved state** is a [neuron](#n) state -characterized by a [dissolve delay](#d) equal to +The **dissolved state** is a [neuron](#neuron) state +characterized by a [dissolve delay](#dissolve-delay) equal to zero. (It is conventionally said that a neuron in this state does not "have" a dissolve delay.) It is in this state that a neuron can be "disbursed," hence its stake moved elsewhere, and its corresponding -[neuron account](#n) closed. The -[age](#n) of a dissolved neuron is considered to be +[neuron account](#neuron-account) closed. The +[age](#neuron-age) of a dissolved neuron is considered to be zero. #### dissolving state -A **dissolving state** is a [neuron](#n) state that +A **dissolving state** is a [neuron](#neuron) state that follows immediately after its owner issues a "start dissolving" command, and continues until a "stop dissolving" command is issued, or until the -dissolve delay timer runs out. The [age of a dissolving neuron](#n) is considered to be zero. +dissolve delay timer runs out. The [age of a dissolving neuron](#neuron-age) is considered to be zero. ## E #### execution environment The **execution environment** is one of the core layers of the -[replica](#r) software. +[replica](#replica) software. ## F #### fiduciary -The **fiduciary** of an [account](#a) is the -[principal](#p) allowed to make -[transactions](#t) on the account; as such, it may +The **fiduciary** of an [account](#account) is the +[principal](#principal) allowed to make +[transactions](#transaction) on the account; as such, it may be useful to think of it as the **owner** of the account, with the caveat -that it may or may not be the [beneficiary](#b) of -the account. The [neuron account](#n) is a +that it may or may not be the [beneficiary](#beneficiary) of +the account. The [neuron account](#neuron-account) is a prominent example of an account for which the beneficiary and fiduciary -do not coincide (the fiduciary is the [governance canister](#g) while the beneficiary is the +do not coincide (the fiduciary is the [governance canister](#governance-canister) while the beneficiary is the neuron holder). The fiduciary of a (ledger) account does not change over time. -The distinction between fiduciary and beneficiary is also important for -DeFi dapps (canisters) that interact with the ICP ledger: in this case, -the fiduciary is the DeFi canister while the beneficiary is the -individual or organization [principal](#p) that uses the -DeFi canister’s services. +The distinction between fiduciary and beneficiary is also important for canisters that manage funds on behalf of users (for example, a canister that holds and transfers ICP for multiple principals). In this case, the fiduciary is the canister while the beneficiary is the [principal](#principal) whose funds it holds. ## G #### governance canister -The **[governance](https://learn.internetcomputer.org/hc/en-us/articles/34574082263700-Tokenomics-Governance) canister** is a [system canister](#s) that implements the -[NNS](#n) governance system, i.e., -among others, stores and manages [neurons](#n) and -[proposals](#p), and implements the NNS -[voting](#v) environment. +The **[governance](https://learn.internetcomputer.org/hc/en-us/articles/34574082263700-Tokenomics-Governance) canister** is a [system canister](#system-canister) that implements the +[NNS](#network-nervous-system-nns) governance system, i.e., +among others, stores and manages [neurons](#neuron) and +[proposals](#proposal), and implements the NNS +[voting](#voting) environment. ## I #### ICP The **Internet Computer Protocol** token (ticker "ICP") is the utility -token of the [Internet Computer](#i). ICP +token of the [Internet Computer](#internet-computer-protocol-icp). ICP allows the broader internet community to participate in the governance of the Internet Computer blockchain network by locking ICP in -[neurons](#n). ICP can also be converted into -[cycles](#c), which are then used to power -[canisters](#c). +[neurons](#neuron). ICP can also be converted into +[cycles](#cycle), which are then used to power +[canisters](#canister). #### ICP supply account The **ICP supply account** is a quasi-fictitious ledger -[account](#a) whose balance is always zero. It has a -central role in [ICP](#i) [burning](#b) -and [minting](#m) operations. +[account](#account) whose balance is always zero. It has a +central role in [ICP](#icp) [burning](#burning-transaction) +and [minting](#minting-transaction) operations. #### identity An **identity** is a byte string that is used to identify an entity, -such as a [principal](#p), that interacts with the -[Internet Computer](#i). For users, the +such as a [principal](#principal), that interacts with the +[Internet Computer](#internet-computer-protocol-icp). For users, the identity is the SHA-224 hash of the DER-encoded public key of the user. [IC interface specification](./ic-interface-spec.md) has more detail. @@ -334,101 +298,96 @@ detail. #### Internet Identity **Internet Identity** is an anonymizing blockchain authentication system -running on the [Internet Computer](#i). +running on the [Internet Computer](#internet-computer-protocol-icp). #### induction pool -The **induction pool** of a [subnet](#s) blockchain is -the collection of all [input queues](#i) of all -[canisters](#c) residing on the subnet. +The **induction pool** of a [subnet](#subnet) blockchain is +the collection of all [input queues](#input-queue) of all +[canisters](#canister) residing on the subnet. #### ingress message -An **ingress message** is a [message](#m) sent by an -end-user to a [canister](#c) running on a -[subnet](#s) blockchain. The message is signed by the +An **ingress message** is a [message](#message) sent by an +end-user to a [canister](#canister) running on a +[subnet](#subnet) blockchain. The message is signed by the secret key corresponding to the end-user’s -[identity](#i) and sent to one of the -[replicas](#r) that participate in the subnet. +[identity](#identity) and sent to one of the +[replicas](#replica) that participate in the subnet. #### ingress message history The **ingress message history** records the current status of every -[ingress message](#i) processed by a -[replica](#r) and keeps track of whether messages were -successfully included in the [induction -pool](#i) and the responses of executed +[ingress message](#ingress-message) processed by a +[replica](#replica) and keeps track of whether messages were +successfully included in the [induction pool](#induction-pool) and the responses of executed messages. #### input queue -The **input queue** of a [canister](#c) contains all -[messages](#m) bound for the canister. See also -[induction pool](#i). When the canister is +The **input queue** of a [canister](#canister) contains all +[messages](#message) bound for the canister. See also +[induction pool](#induction-pool). When the canister is scheduled for execution, messages from its input queue will be executed. #### inter-canister message -An **inter-canister message** is a [message](#m) sent -from one [canister](#c) to another. Inter-canister -messages are different from user-initiated [ingress -messages](#i). +An **inter-canister message** is a [message](#message) sent +from one [canister](#canister) to another. Inter-canister +messages are different from user-initiated [ingress messages](#ingress-message). #### Internet Computer Protocol (ICP) The **Internet Computer Protocol** (ICP) is a decentralized blockchain that provides scalable compute capacity for running -[canisters](#c) through independent [node -providers](#n) running [nodes](#n) -in geographically distributed [data centers](#d). +[canisters](#canister) through independent [node providers](#node-provider) running [nodes](#node) +in geographically distributed [data centers](#data-center). ## L #### ledger canister -The **ledger canister** is a [system -canister](#s) whose main role is to store -[accounts](#a) and their corresponding -[transactions](#t). +The **ledger canister** is a [system canister](#system-canister) whose main role is to store +[accounts](#account) and their corresponding +[transactions](#transaction). ## M #### message -A **message** is data sent from one [canister](#c) to +A **message** is data sent from one [canister](#canister) to another or from a user to a canister. #### message routing -The **[message routing](https://learn.internetcomputer.org/hc/en-us/articles/34208241927316-Message-Routing)** layer receives [batches](#b) from -the [consensus](#c) layer and inducts them into the -[induction pool](#i). Message routing then -schedules a set of [canisters](#c) to execute messages -from their [input queues](#i). +The **[message routing](https://learn.internetcomputer.org/hc/en-us/articles/34208241927316-Message-Routing)** layer receives [batches](#batch) from +the [consensus](#consensus) layer and inducts them into the +[induction pool](#induction-pool). Message routing then +schedules a set of [canisters](#canister) to execute messages +from their [input queues](#input-queue). -After [messages](#m) have been executed, the message +After [messages](#message) have been executed, the message routing layer takes any messages produced in the execution round from the output queues and puts those messages into the outgoing streams to -be consumed by canisters on other [subnets](#s). +be consumed by canisters on other [subnets](#subnet). #### minting transaction A **minting transaction** is the process of "minting" -[ICP](#i), whereby a certain amount of ICP comes into +[ICP](#icp), whereby a certain amount of ICP comes into existence. ICP is minted in order to reward -[neurons](#n) for [voting](#v), and -reward [node providers](#n) for participating in -the [ICP](#i) by providing compute -capacity through the running of [nodes](#n). A minting -transaction is represented as a [transaction](#t) -from the [ICP supply account](#i) to a -destination [account](#a). +[neurons](#neuron) for [voting](#voting), and +reward [node providers](#node-provider) for participating in +the [ICP](#icp) by providing compute +capacity through the running of [nodes](#node). A minting +transaction is represented as a [transaction](#transaction) +from the [ICP supply account](#icp-supply-account) to a +destination [account](#account). #### Motoko **Motoko** is a programming language designed to directly support the -programming model of the [Internet -Computer](#i), making it easier to +programming model of the [Internet Computer](#internet-computer-protocol-icp), making it easier to efficiently build applications and take advantage of some of the more unusual features of ICP, including the actor model for smart contracts and compilation to WebAssembly. @@ -437,9 +396,8 @@ contracts and compilation to WebAssembly. #### non-dissolving state -A [neuron](#n) that is not -[dissolved](#d) or [ -dissolving](#d) is said to be in a +A [neuron](#neuron) that is not +[dissolved](#dissolved-state) or [dissolving](#dissolving-state) is said to be in a **non-dissolving state** (or "aging"). Non-dissolving neurons thus accrue "age," with the caveat that beginning to dissolve at any time reduces this age back to zero. The dissolve delay parameter of a @@ -449,86 +407,77 @@ neuron would have to already be dissolved. #### Network Nervous System (NNS) The **Network Nervous System** (NNS) is the decentralized autonomous -organization (DAO) that governs the [Internet Computer](#i) -by [proposals](#p) on which [ICP](#ICP) [neuron](#n) owners can vote. +organization (DAO) that governs the [Internet Computer](#internet-computer-protocol-icp) +by [proposals](#proposal) on which [ICP](#ICP) [neuron](#neuron) owners can vote. Once such a proposal is accepted, it is autonomously executed. -The NNS consists of a collection of [system -canisters](#s) (aka "NNS canisters"). +The NNS consists of a collection of [system canisters](#system-canister) (aka "NNS canisters"). #### neuron -A **neuron** is an [ICP](#i) entity that -can make [proposals](#p) and vote on proposals related -to the [governance](https://learn.internetcomputer.org/hc/en-us/articles/34574082263700-Tokenomics-Governance) of the [Internet -Computer](#i). +A **neuron** is an [ICP](#icp) entity that +can make [proposals](#proposal) and vote on proposals related +to the [governance](https://learn.internetcomputer.org/hc/en-us/articles/34574082263700-Tokenomics-Governance) of the [Internet Computer](#internet-computer-protocol-icp). To provide the stability required for responsible governance, neurons -need to store ("stake") a certain amount of [ICP](#i) in +need to store ("stake") a certain amount of [ICP](#icp) in order to be able to make and vote on proposals. This -[locks](#n) the tokens for a period of -time, after which it starts [dissolving](#d). -The ICP stake of a neuron is stored in a [neuron -account](#n). The neuron owner has the right to +[locks](#non-dissolving-state) the tokens for a period of +time, after which it starts [dissolving](#dissolving-state). +The ICP stake of a neuron is stored in a [neuron account](#neuron-account). The neuron owner has the right to propose and vote on governance issues and is granted rewards for -[voting](#v) in proportion to the amount of ICP staked, -and the duration of the [dissolve -period](#n). +[voting](#voting) in proportion to the amount of ICP staked, +and the duration of the [dissolve period](#dissolve-delay). #### neuron account -A **neuron account** is a [canister -account](#c) whose -[beneficiary](#b) is a [neuron](#n) -(or the neuron’s owner). The [governance -canister](#g) is the -[fiduciary](#f) of all neuron accounts. +A **neuron account** is a [canister account](#canister-account) whose +[beneficiary](#beneficiary) is a [neuron](#neuron) +(or the neuron’s owner). The [governance canister](#governance-canister) is the +[fiduciary](#fiduciary) of all neuron accounts. #### neuron age -The **neuron age** is a [neuron](#n) parameter roughly +The **neuron age** is a [neuron](#neuron) parameter roughly indicative of the time that has passed since its creation or since when -it last entered into a [non-dissolving -state](#n). Calculation of a neuron’s age -needs to take into account whether the neuron has spent time [dissolving](#d) or -[dissolved](#d), both of which reset this +it last entered into a [non-dissolving state](#non-dissolving-state). Calculation of a neuron’s age +needs to take into account whether the neuron has spent time [dissolving](#dissolving-state) or +[dissolved](#dissolved-state), both of which reset this parameter. #### node A **node** is a physical hardware device run by independent -[node providers](#n). It hosts all the -hardware, [replica](#r) software, and configuration -settings required to participate in the [Internet -Computer](#i). +[node providers](#node-provider). It hosts all the +hardware, [replica](#replica) software, and configuration +settings required to participate in the [Internet Computer](#internet-computer-protocol-icp). #### node operator -A **node operator** (NO) is a non-canister [principal](#p) with a scoped authority to add/remove unassigned [nodes](#n) to/from the [ICP](#i). +A **node operator** (NO) is a non-canister [principal](#principal) with a scoped authority to add/remove unassigned [nodes](#node) to/from the [ICP](#icp). -This power is granted in advance through an NNS [proposal](#p) stored in the [registry canister](#r). -The proposal defines maximum node operator capacity, and is scoped to a specific [node provider](#n), in a specific [data center](#d) with a specific IPv6 prefix. -Actual addition/removal of an unassigned node requires no further approvals, and is executed through a message to the [registry canister](#r) signed by the corresponding node operator. +This power is granted in advance through an NNS [proposal](#proposal) stored in the [registry canister](#registry). +The proposal defines maximum node operator capacity, and is scoped to a specific [node provider](#node-provider), in a specific [data center](#data-center) with a specific IPv6 prefix. +Actual addition/removal of an unassigned node requires no further approvals, and is executed through a message to the [registry canister](#registry) signed by the corresponding node operator. -Node operators and [node providers](#n) **are not** the same entities, however they are related, as configuring [node operator keys and records](https://wiki.internetcomputer.org/wiki/Node_Provider_Onboarding#10._Create_a_node_operator_record) is part of the node provider onboarding process. +Node operators and [node providers](#node-provider) **are not** the same entities, however they are related, as configuring [node operator keys and records](https://wiki.internetcomputer.org/wiki/Node_Provider_Onboarding#10._Create_a_node_operator_record) is part of the node provider onboarding process. #### node provider A **node provider** (NP) is a non-canister -[principal](#p) that receives the rewards stemming -from node participation to the [ICP](#i) +[principal](#principal) that receives the rewards stemming +from node participation to the [ICP](#icp) (aka “payout principal”). Usually, though not necessarily, a node -provider is the owner of the [node](#n), and may also be +provider is the owner of the [node](#node), and may also be involved in node operation and related tasks. A node provider may -receive rewards from multiple nodes in multiple [data -centers](#d). -Node providers are selected and vetted by the [NNS](#n). +receive rewards from multiple nodes in multiple [data centers](#data-center). +Node providers are selected and vetted by the [NNS](#network-nervous-system-nns). ## O #### output queue -Each [canister](#c) has an **output queue** of -[messages](#m) bound for other canisters. +Each [canister](#canister) has an **output queue** of +[messages](#message) bound for other canisters. ## P @@ -536,53 +485,52 @@ Each [canister](#c) has an **output queue** of In common usage, **[peer-to-peer](https://learn.internetcomputer.org/hc/en-us/articles/34207428453140-Peer-to-peer)** (P2P) computing or networking is a distributed application architecture that partitions workload across a -network of equally privileged computer [nodes](#n) so that +network of equally privileged computer [nodes](#node) so that participants can contribute resources such as processing power, disk storage, or network bandwidth to handle application workload. The **[peer-to-peer](https://learn.internetcomputer.org/hc/en-us/articles/34207428453140-Peer-to-peer) layer** collects and disseminates -[messages](#m) and artifacts from users and from other +[messages](#message) and artifacts from users and from other nodes. -The [nodes](#n) of a [subnet](#s) form a +The [nodes](#node) of a [subnet](#subnet) form a dedicated [peer-to-peer](https://learn.internetcomputer.org/hc/en-us/articles/34207428453140-Peer-to-peer) broadcast network that facilitates the secure **bounded-time/eventual delivery** broadcast of artifacts (such as -[ingress messages](#i), control messages, and -their signature shares). The [consensus](#c) layer +[ingress messages](#ingress-message), control messages, and +their signature shares). The [consensus](#consensus) layer builds upon this functionality. #### principal -A **principal** is an entity that can be authenticated by the [Internet -Computer](#i). This is the same sense of the +A **principal** is an entity that can be authenticated by the [Internet Computer](#internet-computer-protocol-icp). This is the same sense of the word principal as the [Wikipedia definition](https://en.wikipedia.org/wiki/Principal-(computer-security)). Principals that interact with the Internet Computer do so using a -certain [identity](#i). +certain [identity](#identity). #### proposal A **proposal** is a statement describing an action to modify certain -parameters of the [ICP](#i), or of any of +parameters of the [ICP](#icp), or of any of its subsystems. It is implemented as an ICP entity having various attributes, such as an ID, a URL, a summary, etc. Proposals are submitted -by eligible [neuron](#n) owners for the consideration of -ICP community, and undergo a [voting](#v) process, +by eligible [neuron](#neuron) owners for the consideration of +ICP community, and undergo a [voting](#voting) process, following which they can be adopted or rejected. Adopted proposals are then executed autonomously. There are several taxonomies of proposals, the most prominent of which groups proposals into "topics," whose adoption, in turn, triggers certain categories of actions, such as the creation of a -[subnet](#s), the addition of -[nodes](#n) to a subnet, or the upgrade to a new [replica](#r) +[subnet](#subnet), the addition of +[nodes](#node) to a subnet, or the upgrade to a new [replica](#replica) software. #### proto-node -A **proto-node** is an [ICP](#i) entity +A **proto-node** is an [ICP](#icp) entity consisting of a combination of hardware and software that differs from -a [node](#n) in that it has not yet been registered with +a [node](#node) in that it has not yet been registered with ICP. A proto-node is, in short, a "node-in-waiting," hence has all -that it takes to be a node except the [replica](#r) +that it takes to be a node except the [replica](#replica) software. ## Q @@ -590,119 +538,95 @@ software. #### query A **query** is an optimized way to execute operations on a -[canister](#c) where the state changes are not +[canister](#canister) where the state changes are not preserved. Queries are synchronous and can be made to any -[node](#n) that hosts the canister. Queries do not require -[consensus](#c) to verify the result. +[node](#node) that hosts the canister. Queries do not require +[consensus](#consensus) to verify the result. ## R #### replica The **replica** an instance of software containing all the protocol components -necessary for a [node](#n) to participate in a -[subnet](#s). +necessary for a [node](#node) to participate in a +[subnet](#subnet). #### registry -The ICP **registry** is a [canister](#c) that manages +The ICP **registry** is a [canister](#canister) that manages the metadata maintained on the -network nervous system ([NNS](#n)) -and accessed by all [subnet](#s) blockchains. +network nervous system ([NNS](#network-nervous-system-nns)) +and accessed by all [subnet](#subnet) blockchains. ## S -#### smart contract - -A **smart contract** is a stateful computer program designed to -automatically execute, control, or document relevant events and actions -according to the terms of a contract or an agreement. A smart contract -can be deployed on the [Internet -Computer](#i) in the form of a -[canister](#c) bundling data and code. - -A canister can have one or more [controllers](#c) -that are permitted to modify the code of the canister, thereby modifying -the terms of the smart contract. For a canister smart contract to have -immutable code, its list of controllers must be empty. - #### state change -A **state change** is the result of any -[transaction](#t), function call, or operation that -changes the information stored in a [canister](#c). -For example, if a function makes an update call that adds two numbers -together or removes a name from a list, the result is a change to the -canister state. +A **state change** is the result of any function call or operation that changes the information stored in a [canister](#canister). For example, if a function makes an update call that adds two numbers together or removes a name from a list, the result is a change to the canister state. #### state manager The **state manager** is responsible for: -- Maintaining (multiple versions of) the replicated state the deterministic state machine implemented by [message routing](#m) and the [execution environment](#e) operates on. +- Maintaining (multiple versions of) the replicated state the deterministic state machine implemented by [message routing](#message-routing) and the [execution environment](#execution-environment) operates on. - Converting back and forth between the replicated state and its canonical version (the latter can be understood independent of the concrete implementation). -- Obtaining certifications of parts of the canonical state, which allow other stakeholders, such as other [subnets](#s) and/or users, to verify that some piece of state indeed originates from a valid subnetwork. -- Providing capabilities to sync the canonical state with other [replicas](#r) in the same subnet so that replicas that have fallen behind can catch up. +- Obtaining certifications of parts of the canonical state, which allow other stakeholders, such as other [subnets](#subnet) and/or users, to verify that some piece of state indeed originates from a valid subnetwork. +- Providing capabilities to sync the canonical state with other [replicas](#replica) in the same subnet so that replicas that have fallen behind can catch up. #### subnet -A **subnet** (subnetwork) is a collection of [nodes](#n) -that run their own instance of the [consensus](#c) +A **subnet** (subnetwork) is a collection of [nodes](#node) +that run their own instance of the [consensus](#consensus) algorithm to produce a subnet blockchain that interacts with other -subnets of [ICP](#i) using [chain -key](#c) cryptography. +subnets of [ICP](#icp) using [chain key](#chain-key) cryptography. #### system canister A **system canister** is a pre-installed -[canister](#c) that performs certain tasks needed to -maintain the [Internet Computer](#i). +[canister](#canister) that performs certain tasks needed to +maintain the [Internet Computer](#internet-computer-protocol-icp). ## T #### transaction A ledger account **transaction** is the process of transferring -[ICP](#i) from one [account](#a) to +[ICP](#icp) from one [account](#account) to another; it can be of three types: - Regular transfer transaction. -- [Burning](#b) transaction -- [Minting](#m) transaction. +- [Burning](#burning-transaction) transaction +- [Minting](#minting-transaction) transaction. #### transfer transaction A **transfer transaction** is the process of transferring ICP from any -regular ledger [account](#a) (i.e., any ledger account -except the [ICP supply account](#i)) to +regular ledger [account](#account) (i.e., any ledger account +except the [ICP supply account](#icp-supply-account)) to another regular ledger account. ## U #### user -A **user** is any entity that interacts with the [Internet -Computer](#i). Users include end users that -use dapps deployed on [ICP](#i), dapp -developers, holders of [ICP](#i) utility tokens, and -[neuron](#n) holders. +A **user** is any entity that interacts with the [Internet Computer](#internet-computer-protocol-icp). Users include end users that +use apps deployed on [ICP](#icp), app +developers, holders of [ICP](#icp) utility tokens, and +[neuron](#neuron) holders. ## V #### valid set rule -The **valid set rule** is the rule that determines a valid [induction -pool](#i). [Ingress -messages](#i) and [inter-canister -messages](#i) must pass certain checks +The **valid set rule** is the rule that determines a valid [induction pool](#induction-pool). [Ingress messages](#ingress-message) and [inter-canister messages](#inter-canister-message) must pass certain checks to ensure that the valid set rule is upheld before they can be added to the induction pool. #### voting **Voting** is the process through which -[proposals](#p) are selected for adoption and +[proposals](#proposal) are selected for adoption and implementation. Its direct participants are the -[neurons](#n), who both: +[neurons](#neuron), who both: -  Submit proposals. -  Vote on proposals. The voting process is a rather intricate undertaking,