From df4df5f9993110fa5c9d72a501fe87b69fa8d182 Mon Sep 17 00:00:00 2001 From: Marco Walz Date: Fri, 24 Apr 2026 10:25:37 +0200 Subject: [PATCH] chore(brand): replace double-dash em-dash substitutes with colons Replace all prose and link-list ` -- ` patterns with `:` across docs pages, consistent with ICP brand guidelines (no em-dashes). Leaves legitimate uses intact: shell end-of-options `--`, pseudocode comment notation, table N/A cells, stub placeholder pages, and the auto-synced Motoko changelog. --- docs/concepts/index.md | 26 +++++----- docs/concepts/orthogonal-persistence.md | 30 +++++------ docs/getting-started/choose-your-path.md | 54 ++++++++++---------- docs/getting-started/project-structure.mdx | 10 ++-- docs/guides/canister-calls/onchain-calls.mdx | 16 +++--- docs/guides/canister-management/settings.mdx | 16 +++--- docs/guides/frontends/asset-canister.md | 16 +++--- docs/guides/index.md | 20 ++++---- docs/languages/index.md | 2 +- docs/reference/index.md | 26 +++++----- 10 files changed, 108 insertions(+), 108 deletions(-) diff --git a/docs/concepts/index.md b/docs/concepts/index.md index 28d08a7b..dcba4fc4 100644 --- a/docs/concepts/index.md +++ b/docs/concepts/index.md @@ -9,25 +9,25 @@ Understand the ideas behind the Internet Computer before you build on it. These ## Architecture -- **[Network Overview](network-overview.md)** -- Subnets, nodes, consensus, and boundary nodes. -- **[Application Architecture](app-architecture.md)** -- How ICP applications are structured: canisters, frontends, and inter-canister communication. -- **[Canisters](canisters.md)** -- Smart contracts that run WebAssembly, hold state, serve HTTP, and pay for their own compute. +- **[Network Overview](network-overview.md)**: Subnets, nodes, consensus, and boundary nodes. +- **[Application Architecture](app-architecture.md)**: How ICP applications are structured: canisters, frontends, and inter-canister communication. +- **[Canisters](canisters.md)**: Smart contracts that run WebAssembly, hold state, serve HTTP, and pay for their own compute. ## Core capabilities -- **[Reverse Gas Model](reverse-gas-model.md)** -- Why users never pay gas: canisters pay cycles for compute, storage, and bandwidth. -- **[Orthogonal Persistence](orthogonal-persistence.md)** -- How canister memory survives across executions and upgrades without databases. -- **[HTTPS Outcalls](https-outcalls.md)** -- How canisters make HTTP requests to external services with consensus on responses. -- **[Onchain Randomness](onchain-randomness.md)** -- Cryptographically secure random numbers using threshold VRF. -- **[Timers](timers.md)** -- Periodic and one-shot scheduled tasks via the global timer mechanism. +- **[Reverse Gas Model](reverse-gas-model.md)**: Why users never pay gas: canisters pay cycles for compute, storage, and bandwidth. +- **[Orthogonal Persistence](orthogonal-persistence.md)**: How canister memory survives across executions and upgrades without databases. +- **[HTTPS Outcalls](https-outcalls.md)**: How canisters make HTTP requests to external services with consensus on responses. +- **[Onchain Randomness](onchain-randomness.md)**: Cryptographically secure random numbers using threshold VRF. +- **[Timers](timers.md)**: Periodic and one-shot scheduled tasks via the global timer mechanism. ## Cryptography and cross-chain -- **[Chain-Key Cryptography](chain-key-cryptography.md)** -- Threshold signatures that enable cross-chain integration, fast finality, and chain evolution. -- **[Chain Fusion](chain-fusion.md)** -- How ICP connects to Bitcoin, Ethereum, Solana, and other blockchains natively. -- **[VetKeys](vetkeys.md)** -- Verifiable encrypted threshold key derivation for onchain encryption and secret management. +- **[Chain-Key Cryptography](chain-key-cryptography.md)**: Threshold signatures that enable cross-chain integration, fast finality, and chain evolution. +- **[Chain Fusion](chain-fusion.md)**: How ICP connects to Bitcoin, Ethereum, Solana, and other blockchains natively. +- **[VetKeys](vetkeys.md)**: Verifiable encrypted threshold key derivation for onchain encryption and secret management. ## Trust and governance -- **[Security Model](security.md)** -- Canister isolation, trust boundaries, and the threat model for app developers. -- **[Governance](governance.md)** -- The NNS, SNS for app governance, neurons, and proposals. +- **[Security Model](security.md)**: Canister isolation, trust boundaries, and the threat model for app developers. +- **[Governance](governance.md)**: The NNS, SNS for app governance, neurons, and proposals. diff --git a/docs/concepts/orthogonal-persistence.md b/docs/concepts/orthogonal-persistence.md index aff5b9a7..a135c3ad 100644 --- a/docs/concepts/orthogonal-persistence.md +++ b/docs/concepts/orthogonal-persistence.md @@ -5,9 +5,9 @@ sidebar: order: 5 --- -On traditional backends, application state lives in memory only while the process runs. To persist data across restarts, you need a database -- PostgreSQL, Redis, SQLite, or a file system. The application logic and the storage layer are separate concerns that developers must wire together. +On traditional backends, application state lives in memory only while the process runs. To persist data across restarts, you need a database: PostgreSQL, Redis, SQLite, or a file system. The application logic and the storage layer are separate concerns that developers must wire together. -On the Internet Computer, persistence is built into the execution model. A canister's memory persists between calls automatically -- no database and no file system. In Motoko, this is fully transparent: you declare a variable, assign it a value, and that value is still there the next time the canister executes -- no explicit save or load. In Rust, you choose persistent data structures that write directly to stable memory, giving you full control over what survives upgrades. Either way, the canister IS its own storage. This property is called **orthogonal persistence**: persistence is orthogonal to (independent of) the programming model. +On the Internet Computer, persistence is built into the execution model. A canister's memory persists between calls automatically: no database and no file system. In Motoko, this is fully transparent: you declare a variable, assign it a value, and that value is still there the next time the canister executes (no explicit save or load). In Rust, you choose persistent data structures that write directly to stable memory, giving you full control over what survives upgrades. Either way, the canister IS its own storage. This property is called **orthogonal persistence**: persistence is orthogonal to (independent of) the programming model. There is no separate storage tier to configure, query, or maintain. @@ -17,29 +17,29 @@ Every canister has two distinct memory regions, each with different characterist ### Heap (Wasm linear) memory -This is regular program memory -- the space where variables, data structures, and the call stack live during execution. It maps to the Wasm linear memory of the canister module. +This is regular program memory: the space where variables, data structures, and the call stack live during execution. It maps to the Wasm linear memory of the canister module. - **Size limit:** 4 GiB for wasm32 canisters, 6 GiB for wasm64 - **Performance:** Fast, native Wasm memory access -- **Upgrade behavior:** Wiped on canister upgrade (Rust) -- use stable structures to persist data; automatically preserved in Motoko with `persistent actor` +- **Upgrade behavior:** Wiped on canister upgrade (Rust): use stable structures to persist data; automatically preserved in Motoko with `persistent actor` ### Stable memory A separate, dedicated memory region provided by the Internet Computer runtime. Its sole purpose is to survive canister upgrades. - **Size limit:** Up to 500 GiB per canister. The actual available capacity also depends on the subnet's total storage usage, since all canisters on a subnet share a common storage budget. For storage-heavy applications, consider [subnet selection](../guides/canister-management/subnet-selection.md). -- **Performance:** Slower than heap memory -- each access goes through system API calls rather than direct Wasm memory operations +- **Performance:** Slower than heap memory: each access goes through system API calls rather than direct Wasm memory operations - **Upgrade behavior:** Always survives upgrades The distinction between these two regions is the foundation of all persistence strategies on ICP. ## How persistence differs by language -The two mainstream canister languages -- Motoko and Rust -- take fundamentally different approaches to persistence. +The two mainstream canister languages (Motoko and Rust) take fundamentally different approaches to persistence. ### Motoko: true orthogonal persistence -Motoko is the only ICP language that delivers true orthogonal persistence. With `persistent actor`, all variable declarations inside the actor body are automatically persisted across upgrades. Developers do not think about persistence at all -- they write normal code and data survives. +Motoko is the only ICP language that delivers true orthogonal persistence. With `persistent actor`, all variable declarations inside the actor body are automatically persisted across upgrades. Developers do not think about persistence at all: they write normal code and data survives. The runtime transparently manages the mapping between the program's heap and stable memory during upgrades. Fields marked `transient var` reset to their initial value on upgrade, giving developers explicit control over what is ephemeral (caches, counters) versus durable. @@ -51,7 +51,7 @@ For implementation details and code examples, see the [Data persistence guide](. Rust canisters take an explicit approach. The `ic-stable-structures` crate provides data structures (`StableBTreeMap`, `StableCell`, `StableLog`) that are backed directly by stable memory. Data written to these structures survives upgrades without any serialization step. -This is not orthogonal persistence -- developers must consciously choose which data structures to use and how to partition stable memory. The tradeoff is full control: Rust developers decide exactly what persists, how it's stored, and how memory is allocated. +This is not orthogonal persistence: developers must consciously choose which data structures to use and how to partition stable memory. The tradeoff is full control: Rust developers decide exactly what persists, how it's stored, and how memory is allocated. For implementation details and code examples, see the [Data persistence guide](../guides/backends/data-persistence.md). @@ -73,7 +73,7 @@ Stable structures avoid this entirely by writing directly to stable memory durin | **API** | Native language constructs | `StableBTreeMap` etc. (Rust); automatic (Motoko) | | **Use case** | All data in Motoko `persistent actor`; caches and temporary computation in Rust | All persistent application data (Rust) | -In Motoko with `persistent actor`, this trade-off is largely invisible -- the runtime manages the mapping between heap and stable memory during upgrades. In Rust, developers choose explicitly: heap data (fast but ephemeral) or stable structures (slightly slower but durable). +In Motoko with `persistent actor`, this trade-off is largely invisible: the runtime manages the mapping between heap and stable memory during upgrades. In Rust, developers choose explicitly: heap data (fast but ephemeral) or stable structures (slightly slower but durable). ## Comparison with traditional backends @@ -89,14 +89,14 @@ The mental model shift: instead of "my app talks to a database," think "my app I ## Further reading -- [IC Internals: Orthogonal Persistence](https://medium.com/dfinity/ic-internals-orthogonal-persistence-9e0c094aac1a) -- deep dive into how orthogonal persistence works at the protocol level -- [A Journey into Stellarator (Part 2)](https://medium.com/dfinity/a-journey-into-stellarator-part-2-d4a83c631748) -- the Stellarator engine that powers Motoko's persistent actors -- [Orthogonal Persistence in 60 Seconds](https://www.youtube.com/shorts/g3sC2wjLzew) -- quick visual explainer +- [IC Internals: Orthogonal Persistence](https://medium.com/dfinity/ic-internals-orthogonal-persistence-9e0c094aac1a): deep dive into how orthogonal persistence works at the protocol level +- [A Journey into Stellarator (Part 2)](https://medium.com/dfinity/a-journey-into-stellarator-part-2-d4a83c631748): the Stellarator engine that powers Motoko's persistent actors +- [Orthogonal Persistence in 60 Seconds](https://www.youtube.com/shorts/g3sC2wjLzew): quick visual explainer ## Next steps -- [Data persistence guide](../guides/backends/data-persistence.md) -- practical implementation patterns for both languages -- [Rust stable structures](../languages/rust/stable-structures.md) -- detailed Rust patterns with `StableBTreeMap`, `StableCell`, and `StableLog` -- [Canister lifecycle](../guides/canister-management/lifecycle.md) -- how upgrades, reinstalls, and other lifecycle events interact with persistence +- [Data persistence guide](../guides/backends/data-persistence.md): practical implementation patterns for both languages +- [Rust stable structures](../languages/rust/stable-structures.md): detailed Rust patterns with `StableBTreeMap`, `StableCell`, and `StableLog` +- [Canister lifecycle](../guides/canister-management/lifecycle.md): how upgrades, reinstalls, and other lifecycle events interact with persistence diff --git a/docs/getting-started/choose-your-path.md b/docs/getting-started/choose-your-path.md index 34522d54..e5d6057c 100644 --- a/docs/getting-started/choose-your-path.md +++ b/docs/getting-started/choose-your-path.md @@ -11,26 +11,26 @@ Choose your next step based on what you want to build. Each path links to the fi If you prefer to learn the concepts before diving into guides, the [Concepts](../concepts/index.md) section explains how ICP works under the hood: -- [Network overview](../concepts/network-overview.md) -- how the Internet Computer is structured -- [Canisters](../concepts/canisters.md) -- the compute unit of ICP -- [Orthogonal persistence](../concepts/orthogonal-persistence.md) -- how data survives canister upgrades -- [Reverse gas model](../concepts/reverse-gas-model.md) -- why users don't pay gas fees -- [Chain-key cryptography](../concepts/chain-key-cryptography.md) -- the cryptographic foundation enabling chain fusion +- [Network overview](../concepts/network-overview.md): how the Internet Computer is structured +- [Canisters](../concepts/canisters.md): the compute unit of ICP +- [Orthogonal persistence](../concepts/orthogonal-persistence.md): how data survives canister upgrades +- [Reverse gas model](../concepts/reverse-gas-model.md): why users don't pay gas fees +- [Chain-key cryptography](../concepts/chain-key-cryptography.md): the cryptographic foundation enabling chain fusion ## Backend development -**You want to:** Write canister logic -- store data, call APIs, run scheduled tasks. +**You want to:** Write canister logic: store data, call APIs, run scheduled tasks. This is where most developers start after the quickstart. The backend guides cover the core patterns for building canister applications in Rust or Motoko. -**Start with:** [Data persistence](../guides/backends/data-persistence.md) -- learn how canisters store and retrieve data using stable memory and orthogonal persistence. +**Start with:** [Data persistence](../guides/backends/data-persistence.md): learn how canisters store and retrieve data using stable memory and orthogonal persistence. **Then explore:** -- [HTTPS outcalls](../guides/backends/https-outcalls.md) -- call external APIs from your canister -- [Timers](../guides/backends/timers.md) -- schedule recurring tasks -- [Randomness](../guides/backends/randomness.md) -- generate unpredictable values onchain -- [Calling other canisters](../guides/canister-calls/onchain-calls.md) -- compose functionality across canisters +- [HTTPS outcalls](../guides/backends/https-outcalls.md): call external APIs from your canister +- [Timers](../guides/backends/timers.md): schedule recurring tasks +- [Randomness](../guides/backends/randomness.md): generate unpredictable values onchain +- [Calling other canisters](../guides/canister-calls/onchain-calls.md): compose functionality across canisters ## Full-stack applications @@ -38,28 +38,28 @@ This is where most developers start after the quickstart. The backend guides cov ICP can serve web assets directly from canisters, giving you a tamperproof application with no external hosting required. -**Start with:** [Asset canister](../guides/frontends/asset-canister.md) -- deploy a frontend alongside your backend canister. +**Start with:** [Asset canister](../guides/frontends/asset-canister.md): deploy a frontend alongside your backend canister. **Then explore:** -- [Framework integration](../guides/frontends/frameworks.md) -- use React, Vue, Svelte, or other frameworks -- [Custom domains](../guides/frontends/custom-domains.md) -- serve your app from your own domain name -- [Internet Identity](../guides/authentication/internet-identity.md) -- add passwordless authentication -- [Wallet integration](../guides/defi/wallet-integration.md) -- connect user wallets +- [Framework integration](../guides/frontends/frameworks.md): use React, Vue, Svelte, or other frameworks +- [Custom domains](../guides/frontends/custom-domains.md): serve your app from your own domain name +- [Internet Identity](../guides/authentication/internet-identity.md): add passwordless authentication +- [Wallet integration](../guides/defi/wallet-integration.md): connect user wallets ## Chain fusion (cross-chain) **You want to:** Integrate with Bitcoin, Ethereum, or other blockchains. -Chain fusion lets your canister hold native assets, sign transactions, and interact with smart contracts on other chains -- without bridges or intermediaries. This is possible because ICP canisters can derive cryptographic keys and sign transactions using chain-key cryptography. +Chain fusion lets your canister hold native assets, sign transactions, and interact with smart contracts on other chains, without bridges or intermediaries. This is possible because ICP canisters can derive cryptographic keys and sign transactions using chain-key cryptography. -**Start with:** [Bitcoin integration](../guides/chain-fusion/bitcoin.md) -- read Bitcoin state and create transactions directly from a canister. +**Start with:** [Bitcoin integration](../guides/chain-fusion/bitcoin.md): read Bitcoin state and create transactions directly from a canister. **Then explore:** -- [Ethereum integration](../guides/chain-fusion/ethereum.md) -- interact with EVM smart contracts and hold ETH -- [Solana integration](../guides/chain-fusion/solana.md) -- connect to the Solana network -- [Dogecoin integration](../guides/chain-fusion/dogecoin.md) -- work with Dogecoin using the same chain-key ECDSA signing as Bitcoin +- [Ethereum integration](../guides/chain-fusion/ethereum.md): interact with EVM smart contracts and hold ETH +- [Solana integration](../guides/chain-fusion/solana.md): connect to the Solana network +- [Dogecoin integration](../guides/chain-fusion/dogecoin.md): work with Dogecoin using the same chain-key ECDSA signing as Bitcoin ## DeFi and tokens @@ -67,12 +67,12 @@ Chain fusion lets your canister hold native assets, sign transactions, and inter ICP has a standard token framework (ICRC) and chain-key tokens that represent assets from other chains. These guides cover the ledger APIs and token patterns you need for DeFi. -**Start with:** [Token ledgers](../guides/defi/token-ledgers.md) -- understand ICRC token standards and interact with ledger canisters. +**Start with:** [Token ledgers](../guides/defi/token-ledgers.md): understand ICRC token standards and interact with ledger canisters. **Then explore:** -- [Chain-key tokens](../guides/defi/chain-key-tokens.md) -- work with ckBTC, ckETH, and other wrapped assets -- [Rosetta API](../guides/defi/rosetta.md) -- integrate with exchanges and wallets using the Rosetta standard +- [Chain-key tokens](../guides/defi/chain-key-tokens.md): work with ckBTC, ckETH, and other wrapped assets +- [Rosetta API](../guides/defi/rosetta.md): integrate with exchanges and wallets using the Rosetta standard ## Decentralized governance @@ -80,12 +80,12 @@ ICP has a standard token framework (ICRC) and chain-key tokens that represent as The Service Nervous System (SNS) lets you tokenize your application and create a decentralized autonomous organization that governs upgrades, treasury, and parameters through proposals and voting. -**Start with:** [Launching an SNS](../guides/governance/launching.md) -- understand the process and requirements for decentralizing your application. +**Start with:** [Launching an SNS](../guides/governance/launching.md): understand the process and requirements for decentralizing your application. **Then explore:** -- [Managing an SNS](../guides/governance/managing.md) -- submit proposals and manage governance -- [Testing an SNS](../guides/governance/testing.md) -- validate your SNS configuration before launch +- [Managing an SNS](../guides/governance/managing.md): submit proposals and manage governance +- [Testing an SNS](../guides/governance/testing.md): validate your SNS configuration before launch ## AI-assisted development diff --git a/docs/getting-started/project-structure.mdx b/docs/getting-started/project-structure.mdx index d8a5a65d..32e5d0c7 100644 --- a/docs/getting-started/project-structure.mdx +++ b/docs/getting-started/project-structure.mdx @@ -242,10 +242,10 @@ For a deep dive on binding generation, see [Binding generation](../guides/canist ## Next steps -- [What next?](choose-your-path.md) -- pick a development path based on what you want to build -- [Binding generation](../guides/canister-calls/binding-generation.md) -- deep dive on generating type-safe client code -- [Asset canister](../guides/frontends/asset-canister.md) -- how the frontend recipe and asset upload work -- [Canister lifecycle](../guides/canister-management/lifecycle.md) -- build, deploy, upgrade, and manage canisters -- [icp-cli reference](https://cli.internetcomputer.org/) -- full CLI and configuration documentation +- [What next?](choose-your-path.md): pick a development path based on what you want to build +- [Binding generation](../guides/canister-calls/binding-generation.md): deep dive on generating type-safe client code +- [Asset canister](../guides/frontends/asset-canister.md): how the frontend recipe and asset upload work +- [Canister lifecycle](../guides/canister-management/lifecycle.md): build, deploy, upgrade, and manage canisters +- [icp-cli reference](https://cli.internetcomputer.org/): full CLI and configuration documentation {/* Upstream: informed by dfinity/icp-cli docs/concepts/project-model.md, docs/concepts/recipes.md, docs/concepts/binding-generation.md, docs/concepts/canister-discovery.md */} diff --git a/docs/guides/canister-calls/onchain-calls.mdx b/docs/guides/canister-calls/onchain-calls.mdx index 47057bed..f9689141 100644 --- a/docs/guides/canister-calls/onchain-calls.mdx +++ b/docs/guides/canister-calls/onchain-calls.mdx @@ -151,8 +151,8 @@ pub async fn call_increment(counter: Principal) -> Result<(), String> { The distinction matters for correctness: -- **Clean reject** -- the callee never executed the method. Safe to retry. -- **Non-clean reject** -- the callee may or may not have executed. Use idempotent APIs or provide a separate endpoint to query the outcome. +- **Clean reject:** the callee never executed the method. Safe to retry. +- **Non-clean reject:** the callee may or may not have executed. Use idempotent APIs or provide a separate endpoint to query the outcome. @@ -359,7 +359,7 @@ Update methods that make inter-canister calls are **not** executed atomically. C - State changes made **before** `await` are persisted - State changes made **after** `await` are rolled back -This means a trap in your callback does not undo work done before the call. Design accordingly -- use idempotent operations and check postconditions. +This means a trap in your callback does not undo work done before the call. Design accordingly: use idempotent operations and check postconditions. ### Caller identity across await (Rust) @@ -390,7 +390,7 @@ Mitigate with locking patterns: set a flag before the call, clear it in the call ### canister_inspect_message does not apply -The `canister_inspect_message` hook is only called for ingress messages (calls from external users). It is **not** called for inter-canister calls. Do not rely on it for access control between canisters -- perform authorization checks inside the method body instead. +The `canister_inspect_message` hook is only called for ingress messages (calls from external users). It is **not** called for inter-canister calls. Do not rely on it for access control between canisters: perform authorization checks inside the method body instead. ### Cross-subnet latency @@ -398,9 +398,9 @@ Calls between canisters on the same subnet complete within a single round. Cross ## Next steps -- [Parallel Calls and Composite Queries](parallel-calls.md) -- make multiple calls concurrently and use composite queries for efficient read patterns -- [Candid](candid.md) -- define the interface your canister exposes for inter-canister calls -- [Certified Variables](../backends/certified-variables.md) -- make query responses verifiable without update call overhead -- [Inter-Canister Call Security](../security/inter-canister-calls.md) -- reentrancy guards, async safety patterns, and trust considerations +- [Parallel Calls and Composite Queries](parallel-calls.md): make multiple calls concurrently and use composite queries for efficient read patterns +- [Candid](candid.md): define the interface your canister exposes for inter-canister calls +- [Certified Variables](../backends/certified-variables.md): make query responses verifiable without update call overhead +- [Inter-Canister Call Security](../security/inter-canister-calls.md): reentrancy guards, async safety patterns, and trust considerations {/* Upstream: informed by dfinity/portal docs/building-apps/interact-with-canisters/advanced-calls.mdx, docs/building-apps/developer-tools/cdks/rust/intercanister.mdx, multi-canister icskill, icp-cli icskill, dfinity/icp-cli docs/concepts/canister-discovery.md, dfinity/examples motoko/pub-sub, and caffeinelabs/motoko doc/md/fundamentals/2-actors/1-actors-async.md (timeout parenthetical syntax, try/finally cleanup pattern) */} diff --git a/docs/guides/canister-management/settings.mdx b/docs/guides/canister-management/settings.mdx index 79a06e97..5480f4a8 100644 --- a/docs/guides/canister-management/settings.mdx +++ b/docs/guides/canister-management/settings.mdx @@ -442,19 +442,19 @@ For the full management canister interface, see the [management canister referen How you configure controllers depends on the trust model for your canister: -**Developer or team** -- One or more developer identities as controllers. Suitable for development and early-stage projects. Add a backup controller to prevent lockout if a key is lost. +**Developer or team:** One or more developer identities as controllers. Suitable for development and early-stage projects. Add a backup controller to prevent lockout if a key is lost. -**Multi-signature** -- A multi-sig canister (such as the [Threshold canister](https://github.com/dfinity/threshold)) controls the application canister. Administrative actions require multiple signers, preventing any single developer from making unilateral changes. +**Multi-signature:** A multi-sig canister (such as the [Threshold canister](https://github.com/dfinity/threshold)) controls the application canister. Administrative actions require multiple signers, preventing any single developer from making unilateral changes. -**DAO-governed** -- The canister is controlled by a decentralized autonomous organization. On ICP, the most common pattern is handing control to a [Service Nervous System (SNS)](../governance/launching.md), where upgrades and settings changes are decided by token-holder vote. +**DAO-governed:** The canister is controlled by a decentralized autonomous organization. On ICP, the most common pattern is handing control to a [Service Nervous System (SNS)](../governance/launching.md), where upgrades and settings changes are decided by token-holder vote. -**Immutable (blackholed)** -- The canister has no controllers. No one can upgrade, change settings, or delete it. This is the strongest trust guarantee but makes bug fixes impossible. +**Immutable (blackholed):** The canister has no controllers. No one can upgrade, change settings, or delete it. This is the strongest trust guarantee but makes bug fixes impossible. ## Next steps -- [Canister lifecycle](lifecycle.md) -- Create, deploy, upgrade, stop, and delete canisters. -- [Cycles management](cycles-management.md) -- Monitor and top up cycle balances. -- [Cycles costs reference](../../reference/cycles-costs.md) -- Pricing for compute and memory allocation. -- [Management canister reference](../../reference/management-canister.md) -- Full interface specification. +- [Canister lifecycle](lifecycle.md): Create, deploy, upgrade, stop, and delete canisters. +- [Cycles management](cycles-management.md): Monitor and top up cycle balances. +- [Cycles costs reference](../../reference/cycles-costs.md): Pricing for compute and memory allocation. +- [Management canister reference](../../reference/management-canister.md): Full interface specification. {/* Upstream: informed by dfinity/portal (docs/building-apps/canister-management/settings.mdx, docs/building-apps/canister-management/control.mdx, docs/references/_attachments/ic.did (snapshot_visibility field); dfinity/icp-cli) docs/reference/canister-settings.md, docs/reference/cli.md; dfinity/icskills: skills/cycles-management/SKILL.md */} diff --git a/docs/guides/frontends/asset-canister.md b/docs/guides/frontends/asset-canister.md index 93fc1804..d01d7dbf 100644 --- a/docs/guides/frontends/asset-canister.md +++ b/docs/guides/frontends/asset-canister.md @@ -54,9 +54,9 @@ canisters: The key fields are: -- **`recipe.type`** -- specifies the asset canister recipe with a pinned version. Always pin to a specific version (e.g., `@v2.1.0`). See [available versions](https://github.com/dfinity/icp-cli-recipes/releases?q=asset-canister&expanded=true). -- **`dir`** -- the directory containing your build output. This is `dist` for Vite-based projects, `out` for Next.js static exports, or `build` for Create React App. The contents of this directory (not the directory itself) are uploaded to the canister. -- **`build`** -- shell commands that icp-cli runs before uploading. If omitted, icp-cli uploads whatever is already in `dir` without building. +- **`recipe.type`:** specifies the asset canister recipe with a pinned version. Always pin to a specific version (e.g., `@v2.1.0`). See [available versions](https://github.com/dfinity/icp-cli-recipes/releases?q=asset-canister&expanded=true). +- **`dir`:** the directory containing your build output. This is `dist` for Vite-based projects, `out` for Next.js static exports, or `build` for Create React App. The contents of this directory (not the directory itself) are uploaded to the canister. +- **`build`:** shell commands that icp-cli runs before uploading. If omitted, icp-cli uploads whatever is already in `dir` without building. For a full-stack project with a backend canister, list both in the same `icp.yaml`: @@ -322,10 +322,10 @@ icp canister call frontend http_request '(record { ## Next steps -- [Framework integration](frameworks.md) -- set up React, Svelte, or Vue with the asset canister -- [Custom domains](custom-domains.md) -- serve your frontend from your own domain -- [Response certification](certification.md) -- verify that asset canister responses are authentic -- [Authentication with Internet Identity](../authentication/internet-identity.md) -- add user login to your frontend -- [photo-storage example](https://github.com/dfinity/examples/tree/master/hosting/photo-storage) -- programmatic uploads with AssetManager +- [Framework integration](frameworks.md): set up React, Svelte, or Vue with the asset canister +- [Custom domains](custom-domains.md): serve your frontend from your own domain +- [Response certification](certification.md): verify that asset canister responses are authentic +- [Authentication with Internet Identity](../authentication/internet-identity.md): add user login to your frontend +- [photo-storage example](https://github.com/dfinity/examples/tree/master/hosting/photo-storage): programmatic uploads with AssetManager diff --git a/docs/guides/index.md b/docs/guides/index.md index 082e97f8..4503e6ab 100644 --- a/docs/guides/index.md +++ b/docs/guides/index.md @@ -9,22 +9,22 @@ Practical how-to guides organized by development stage. Each guide solves a spec ## Build -- **[Backends](backends/data-persistence.md)** -- Data persistence, HTTPS outcalls, timers, randomness, and other backend patterns. -- **[Canister Calls](canister-calls/candid.md)** -- Candid interfaces, binding generation, onchain and offchain calling patterns. -- **[Frontends](frontends/asset-canister.md)** -- Asset canisters, frontend frameworks, custom domains, and response certification. -- **[Authentication](authentication/internet-identity.md)** -- Internet Identity, verifiable credentials, and wallet integration. +- **[Backends](backends/data-persistence.md)**: Data persistence, HTTPS outcalls, timers, randomness, and other backend patterns. +- **[Canister Calls](canister-calls/candid.md)**: Candid interfaces, binding generation, onchain and offchain calling patterns. +- **[Frontends](frontends/asset-canister.md)**: Asset canisters, frontend frameworks, custom domains, and response certification. +- **[Authentication](authentication/internet-identity.md)**: Internet Identity, verifiable credentials, and wallet integration. ## Quality and shipping -- **[Testing](testing/strategies.md)** -- Unit testing, integration testing with PocketIC, and end-to-end strategies. -- **[Canister Management](canister-management/lifecycle.md)** -- Create, upgrade, configure, optimize, fund, deploy, and back up canisters. -- **[Security](security/access-management.md)** -- Access control, encryption, data integrity, DoS prevention, and safe upgrades. +- **[Testing](testing/strategies.md)**: Unit testing, integration testing with PocketIC, and end-to-end strategies. +- **[Canister Management](canister-management/lifecycle.md)**: Create, upgrade, configure, optimize, fund, deploy, and back up canisters. +- **[Security](security/access-management.md)**: Access control, encryption, data integrity, DoS prevention, and safe upgrades. ## Advanced features -- **[Chain Fusion](chain-fusion/bitcoin.md)** -- Native Bitcoin, Ethereum, Solana, and Dogecoin integration. -- **[DeFi](defi/token-ledgers.md)** -- Token ledgers, chain-key tokens, and the Rosetta API. -- **[Governance](governance/launching.md)** -- Launch and manage an SNS DAO for your app. +- **[Chain Fusion](chain-fusion/bitcoin.md)**: Native Bitcoin, Ethereum, Solana, and Dogecoin integration. +- **[DeFi](defi/token-ledgers.md)**: Token ledgers, chain-key tokens, and the Rosetta API. +- **[Governance](governance/launching.md)**: Launch and manage an SNS DAO for your app. ## Developer tools diff --git a/docs/languages/index.md b/docs/languages/index.md index 7a6bffde..a24b9c4b 100644 --- a/docs/languages/index.md +++ b/docs/languages/index.md @@ -5,7 +5,7 @@ sidebar: order: 0 --- -ICP canisters compile to WebAssembly, so any language that targets Wasm can be used. There are two approaches: **Motoko** is a language purpose-built for IC -- its compiler handles system API bindings, Candid serialization, and persistence natively. For other languages, a **Canister Development Kit (CDK)** provides the glue between the language and the IC system API -- type-safe bindings for system calls, macros for exposing canister methods, and utilities for stable memory and inter-canister calls. +ICP canisters compile to WebAssembly, so any language that targets Wasm can be used. There are two approaches: **Motoko** is a language purpose-built for IC. Its compiler handles system API bindings, Candid serialization, and persistence natively. For other languages, a **Canister Development Kit (CDK)** provides the glue between the language and the IC system API: type-safe bindings for system calls, macros for exposing canister methods, and utilities for stable memory and inter-canister calls. ## Officially supported diff --git a/docs/reference/index.md b/docs/reference/index.md index a78492a4..e5a09936 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -9,28 +9,28 @@ Technical reference material for ICP development. These pages cover exact specif ## Canisters -- **[Management Canister](management-canister.md)** -- API reference for the IC management canister (`aaaaa-aa`): canister lifecycle, signing, randomness, and more. -- **[System Canisters](system-canisters.md)** -- NNS canisters, Internet Identity, ICP ledger, and other system-level canisters with IDs. -- **[Protocol Canisters](protocol-canisters.md)** -- Bitcoin canister, EVM RPC canister, exchange rate canister, and other protocol-level canisters. -- **[Application Canisters](application-canisters.md)** -- Asset canister, SNS canisters, LLM canister, and other application-layer canisters. +- **[Management Canister](management-canister.md)**: API reference for the IC management canister (`aaaaa-aa`): canister lifecycle, signing, randomness, and more. +- **[System Canisters](system-canisters.md)**: NNS canisters, Internet Identity, ICP ledger, and other system-level canisters with IDs. +- **[Protocol Canisters](protocol-canisters.md)**: Bitcoin canister, EVM RPC canister, exchange rate canister, and other protocol-level canisters. +- **[Application Canisters](application-canisters.md)**: Asset canister, SNS canisters, LLM canister, and other application-layer canisters. ## Tokens and costs -- **[Token Standards](token-standards.md)** -- ICRC-1 fungible tokens, ICRC-2 approval, ICRC-3 transaction log, and ICRC-7 NFTs. -- **[Cycles Costs](cycles-costs.md)** -- Exact cycle costs for compute, storage, HTTPS outcalls, signing, and canister operations. -- **[Subnet Types](subnet-types.md)** -- All subnet types with node counts, replication factors, and cycle cost multipliers. +- **[Token Standards](token-standards.md)**: ICRC-1 fungible tokens, ICRC-2 approval, ICRC-3 transaction log, and ICRC-7 NFTs. +- **[Cycles Costs](cycles-costs.md)**: Exact cycle costs for compute, storage, HTTPS outcalls, signing, and canister operations. +- **[Subnet Types](subnet-types.md)**: All subnet types with node counts, replication factors, and cycle cost multipliers. ## Errors and debugging -- **[Execution Errors](execution-errors.md)** -- Common canister execution errors with explanations and fixes. +- **[Execution Errors](execution-errors.md)**: Common canister execution errors with explanations and fixes. ## Specifications -- **[IC Interface Specification](ic-interface-spec.md)** -- System API, HTTP interface, and certified data specification. -- **[HTTP Gateway Specification](http-gateway-spec.md)** -- How boundary nodes serve canister HTTP responses with certification verification. -- **[Candid Specification](candid-spec.md)** -- The Candid interface description language: type system, encoding, and subtyping rules. -- **[Internet Identity Specification](internet-identity-spec.md)** -- Delegation chains, passkey management, and canister signatures. +- **[IC Interface Specification](ic-interface-spec.md)**: System API, HTTP interface, and certified data specification. +- **[HTTP Gateway Specification](http-gateway-spec.md)**: How boundary nodes serve canister HTTP responses with certification verification. +- **[Candid Specification](candid-spec.md)**: The Candid interface description language: type system, encoding, and subtyping rules. +- **[Internet Identity Specification](internet-identity-spec.md)**: Delegation chains, passkey management, and canister signatures. ## Other -- **[Glossary](glossary.md)** -- Definitions of ICP-specific terms: canister, cycle, principal, subnet, and more. +- **[Glossary](glossary.md)**: Definitions of ICP-specific terms: canister, cycle, principal, subnet, and more.