From 707bdcf2205c7a9c4ff530c20c95c58c58958b54 Mon Sep 17 00:00:00 2001 From: Marco Walz Date: Fri, 24 Apr 2026 11:33:23 +0200 Subject: [PATCH 1/3] fix(design): improve OG image text readability for social previews Increase tagline from 26px to 32px (split across two lines to fit width) and eyebrow label from 15px to 19px. Both were illegible at the ~600px width social platforms render OG images. --- public/og-image.svg | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/public/og-image.svg b/public/og-image.svg index 7dd39b96..04b7eacb 100644 --- a/public/og-image.svg +++ b/public/og-image.svg @@ -13,7 +13,7 @@ INTERNET COMPUTER + font-size="19" font-weight="500" letter-spacing="3.5" fill="#ff7a4d">INTERNET COMPUTER Developer Docs - Build tamperproof full-stack applications on the Internet Computer. + font-size="32" font-weight="400" fill="#a29a8d">Build tamperproof full-stack applications + on the Internet Computer. From 5fbd7c05091145a059ced9589d9730256509b4fe Mon Sep 17 00:00:00 2001 From: Marco Walz Date: Fri, 24 Apr 2026 12:48:27 +0200 Subject: [PATCH 2/3] docs: rename reverse-gas-model to cycles, remove gas jargon Rename concepts/reverse-gas-model.md to concepts/cycles.md. "Gas" is Ethereum-specific jargon with no meaning to developers coming from a Web2 background. - Page title: "Reverse Gas Model" -> "Cycles" - Intro: drop "gas fee", "smart contract", "Web2-like", "reverse gas model" - Body: "No gas auctions" -> "No fee auctions", remove gas model framing - Update all 9 cross-links across docs, choosing plain link text ("Cycles" instead of "Reverse gas model") - app-architecture.md: "Gas (user pays)" -> "Fee (user pays)" - chain-fusion.md: "Web2-like UX" -> "Familiar UX" - cycles-management.mdx: remove Ethereum gas comparison from intro --- docs/concepts/app-architecture.md | 2 +- docs/concepts/canisters.md | 4 ++-- docs/concepts/chain-fusion.md | 2 +- .../concepts/{reverse-gas-model.md => cycles.md} | 16 ++++++++-------- docs/concepts/index.md | 2 +- docs/getting-started/choose-your-path.md | 2 +- .../canister-management/cycles-management.mdx | 4 ++-- docs/guides/security/dos-prevention.md | 2 +- docs/index.mdx | 2 +- docs/reference/cycles-costs.md | 2 +- 10 files changed, 19 insertions(+), 19 deletions(-) rename docs/concepts/{reverse-gas-model.md => cycles.md} (84%) diff --git a/docs/concepts/app-architecture.md b/docs/concepts/app-architecture.md index 80fa59c2..2bab9d70 100644 --- a/docs/concepts/app-architecture.md +++ b/docs/concepts/app-architecture.md @@ -48,7 +48,7 @@ If you have built on Ethereum or other EVM chains, here is how ICP concepts map: | EVM bytecode | WebAssembly | Wasm runs general-purpose code at near-native speed | | Solidity / Vyper | Motoko, Rust (official); TypeScript, Python (community) | Multiple language options, full standard libraries | | Block time (~12s) | Finality (~1–2s) | Update calls typically finalize in 1–2 seconds | -| Gas (user pays) | [Cycles](reverse-gas-model.md) (canister pays) | Users interact for free; developers fund computation | +| Fee (user pays) | [Cycles](cycles.md) (canister pays) | Users interact for free; developers fund computation | | No HTTP serving | Built-in HTTP serving | Canisters serve web pages directly | | Offchain storage (IPFS, etc.) | Onchain stable memory | Up to 500 GiB per canister, no external storage needed | | Bridges / oracles | [Chain-key signing](chain-fusion.md) | Canisters sign transactions on other chains natively | diff --git a/docs/concepts/canisters.md b/docs/concepts/canisters.md index 9a3aac45..2a8f1e4f 100644 --- a/docs/concepts/canisters.md +++ b/docs/concepts/canisters.md @@ -18,7 +18,7 @@ Canisters share the core properties of smart contracts: their execution is gover - **Large state.** Canisters can hold up to 500 GiB of stable memory, far beyond what most blockchains allow per contract. - **Outbound calls.** Canisters make HTTPS requests to external services (see [HTTPS outcalls](https-outcalls.md)) and sign transactions on other blockchains using chain-key cryptography (see [Chain Fusion](chain-fusion.md)). - **Autonomous execution.** Timers let canisters schedule their own work without any external trigger. -- **Reverse gas model.** Canisters pay for their own compute and storage using [cycles](reverse-gas-model.md), so end users don't need tokens to interact with them. +- **Canisters fund themselves.** Canisters pay for their own compute and storage using [cycles](cycles.md), so end users don't need tokens to interact with them. ## Execution model @@ -127,7 +127,7 @@ Under the hood, each canister maintains several components: ## Next steps -- [Reverse gas model](reverse-gas-model.md): how canisters pay for computation +- [Cycles](cycles.md): how canisters pay for computation - [App architecture](app-architecture.md): how canisters fit into application design - [Canister lifecycle](../guides/canister-management/lifecycle.md): practical guide to managing canisters - [Network overview](network-overview.md): the infrastructure canisters run on diff --git a/docs/concepts/chain-fusion.md b/docs/concepts/chain-fusion.md index 81cec26f..f4adc03c 100644 --- a/docs/concepts/chain-fusion.md +++ b/docs/concepts/chain-fusion.md @@ -18,7 +18,7 @@ A canister interacting with Bitcoin or Ethereum has no external dependency beyon - **No bridges.** Canisters hold assets directly on external chains. There is no wrapped token that can depeg, no bridge contract that can be exploited. - **No oracles.** Canisters can read external chain state themselves: either through a direct protocol integration (Bitcoin) or by querying RPC providers via [HTTPS outcalls](https-outcalls.md). - **Full autonomy.** Canisters can schedule cross-chain actions using [timers](../guides/backends/timers.md), enabling use cases like automated trading, periodic liquidations, or cronjob services: all without external triggers. -- **Web2-like UX.** Because ICP has low-cost computation and a [reverse gas model](reverse-gas-model.md), users can interact with cross-chain apps through a standard browser without installing a wallet. +- **Familiar UX.** Because ICP has low-cost computation and [canisters pay for their own cycles](cycles.md), users can interact with cross-chain apps through a standard browser without installing a wallet. ## How it works diff --git a/docs/concepts/reverse-gas-model.md b/docs/concepts/cycles.md similarity index 84% rename from docs/concepts/reverse-gas-model.md rename to docs/concepts/cycles.md index 3fb6d26a..e90b73fd 100644 --- a/docs/concepts/reverse-gas-model.md +++ b/docs/concepts/cycles.md @@ -1,13 +1,13 @@ --- -title: "Reverse Gas Model" -description: "Why users never pay gas on ICP: canisters pay cycles for compute, storage, and bandwidth" +title: "Cycles" +description: "How canisters pay for their own compute, storage, and bandwidth using cycles" sidebar: order: 4 --- -On most blockchains, users pay a gas fee every time they interact with a smart contract. On ICP, the model is flipped: **canisters pay for their own resource consumption using cycles**, and users pay nothing. This is the **reverse gas model**. +On most networks, users pay a fee every time they interact with an app. On ICP, the model is flipped: **canisters pay for their own resource consumption using cycles**, and users pay nothing. -The result is a Web2-like user experience. Users can interact with any app on ICP without holding tokens, configuring a wallet, or approving every transaction. For developers, it means full control over cost management: and the responsibility that comes with it. +The result is a familiar user experience. Users can interact with any app on ICP without holding tokens, configuring a wallet, or approving every transaction. For developers, it means full control over cost management: and the responsibility that comes with it. ## What are cycles? @@ -65,7 +65,7 @@ Every canister is replicated across all nodes on its subnet. Costs scale with su ## Developer responsibility -The reverse gas model shifts payment from users to developers. This comes with ongoing obligations: +Canisters pay for their own resources, which comes with ongoing obligations: **Topping up**: canisters burn cycles continuously for storage and on every update call. Developers must monitor balances and keep canisters funded. A canister that runs out of cycles freezes immediately and stops responding to all calls. @@ -77,9 +77,9 @@ These responsibilities can be automated. Tools like [CycleOps](https://cycleops. ## Cost predictability -The XDR peg and flat per-resource pricing make ICP costs predictable in a way that transaction-fee blockchains are not: +The XDR peg and flat per-resource pricing make ICP costs predictable: -- **No gas auctions**: there is no bidding for block space. Cycle prices are set by the NNS and change infrequently. +- **No fee auctions**: there is no bidding for block space. Cycle prices are set by the NNS and change infrequently. - **No per-transaction fees for users**: apps absorb all costs, like SaaS businesses absorb server bills. - **Stable unit economics**: because cycles are pegged to XDR (not ICP price), infrastructure costs remain consistent even when ICP token price swings. @@ -89,6 +89,6 @@ The tradeoff is that developers must forecast and fund usage upfront rather than - [Cycles Management](../guides/canister-management/cycles-management.md): how to check balances, top up canisters, and set freezing thresholds - [Cycles Costs Reference](../reference/cycles-costs.md): exact cost tables for all operations -- [Canisters](./canisters.md): canisters as the paying entity in the reverse gas model +- [Canisters](./canisters.md): canisters as the paying entity for compute and storage diff --git a/docs/concepts/index.md b/docs/concepts/index.md index dcba4fc4..409b4ea8 100644 --- a/docs/concepts/index.md +++ b/docs/concepts/index.md @@ -15,7 +15,7 @@ Understand the ideas behind the Internet Computer before you build on it. These ## Core capabilities -- **[Reverse Gas Model](reverse-gas-model.md)**: Why users never pay gas: canisters pay cycles for compute, storage, and bandwidth. +- **[Cycles](cycles.md)**: How canisters pay for their own compute, storage, and bandwidth — and why users pay nothing. - **[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. diff --git a/docs/getting-started/choose-your-path.md b/docs/getting-started/choose-your-path.md index e5d6057c..3679d114 100644 --- a/docs/getting-started/choose-your-path.md +++ b/docs/getting-started/choose-your-path.md @@ -14,7 +14,7 @@ If you prefer to learn the concepts before diving into guides, the [Concepts](.. - [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 +- [Cycles](../concepts/cycles.md): why users don't pay to interact with apps - [Chain-key cryptography](../concepts/chain-key-cryptography.md): the cryptographic foundation enabling chain fusion ## Backend development diff --git a/docs/guides/canister-management/cycles-management.mdx b/docs/guides/canister-management/cycles-management.mdx index bea6275a..a6a42fbc 100644 --- a/docs/guides/canister-management/cycles-management.mdx +++ b/docs/guides/canister-management/cycles-management.mdx @@ -7,7 +7,7 @@ sidebar: import { Tabs, TabItem } from '@astrojs/starlight/components'; -Canisters on ICP pay for compute and storage using **cycles**. Unlike gas on Ethereum, cycles are paid by the canister: not the caller. This is ICP's [reverse gas model](../../concepts/reverse-gas-model.md): developers fund their own canisters, and users interact for free. +Canisters on ICP pay for compute and storage using **cycles**. Cycles are paid by the canister, not the caller: developers fund their own canisters, and users interact for free. See [Cycles](../../concepts/cycles.md) for a full explanation of the billing model. This guide covers everything you need to manage cycles in production: acquiring them, monitoring balances, setting thresholds, and deploying to mainnet. @@ -424,7 +424,7 @@ icp canister top-up backend --amount 1T -n ic - [Canister settings](settings.md): Freezing threshold, memory allocation, compute allocation - [Canister lifecycle](lifecycle.md): Create, install, upgrade, and delete canisters - [Cycles costs reference](../../reference/cycles-costs.md): Exact cost tables per operation -- [Reverse gas model](../../concepts/reverse-gas-model.md): Why canisters pay for execution +- [Cycles](../../concepts/cycles.md): Why canisters pay for execution - [Reproducible builds](reproducible-builds.md): Verify your WASM is trustworthy before deploying - [icp-cli docs](https://cli.internetcomputer.org/): Full command reference diff --git a/docs/guides/security/dos-prevention.md b/docs/guides/security/dos-prevention.md index 43baa53c..03684920 100644 --- a/docs/guides/security/dos-prevention.md +++ b/docs/guides/security/dos-prevention.md @@ -5,7 +5,7 @@ sidebar: order: 4 --- -ICP's [reverse gas model](../../concepts/reverse-gas-model.md) means your canister pays for every message it processes: including messages from attackers. Anyone on the internet can send update calls to your canister, and each call burns cycles even if your code ultimately rejects it. Left unmitigated, this lets an attacker drain your cycle balance by flooding your canister with messages. +On ICP, [canisters pay for every message they process](../../concepts/cycles.md): including messages from attackers. Anyone on the internet can send update calls to your canister, and each call burns cycles even if your code ultimately rejects it. Left unmitigated, this lets an attacker drain your cycle balance by flooding your canister with messages. This guide covers the patterns that protect against denial-of-service (DoS) attacks: early message filtering, rate limiting, resource allocation, and cycle monitoring. diff --git a/docs/index.mdx b/docs/index.mdx index 38fee049..264ca905 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -66,7 +66,7 @@ Teach your AI agent canister patterns, API integrations, CLI commands, and deplo Pre-load a canister with cycles and it pays for its own compute, storage, and bandwidth. No usage-based billing to pass on, no per-user pricing logic to build. - [Learn more](concepts/reverse-gas-model.md) + [Learn more](concepts/cycles.md) diff --git a/docs/reference/cycles-costs.md b/docs/reference/cycles-costs.md index 02d1d5c9..e2bdc33b 100644 --- a/docs/reference/cycles-costs.md +++ b/docs/reference/cycles-costs.md @@ -137,7 +137,7 @@ Certain ICP features have additional cycle costs beyond the base execution and m ## Related pages - [Cycles management](../guides/canister-management/cycles-management.md): Topping up and monitoring canister balances -- [Reverse gas model](../concepts/reverse-gas-model.md): Why canisters (not users) pay for execution +- [Cycles](../concepts/cycles.md): Why canisters (not users) pay for execution - [Subnet types](subnet-types.md): Cost multipliers per subnet type From ff99474bc5686d233e853411e8bb5f985239ed8c Mon Sep 17 00:00:00 2001 From: Marco Walz Date: Fri, 24 Apr 2026 12:53:36 +0200 Subject: [PATCH 3/3] docs: link cycles on first use across guides and getting-started --- docs/getting-started/quickstart.md | 2 +- docs/guides/backends/https-outcalls.mdx | 2 +- docs/guides/canister-calls/onchain-calls.mdx | 2 +- docs/guides/canister-management/lifecycle.mdx | 2 +- docs/guides/canister-management/optimization.md | 2 +- docs/guides/canister-management/settings.mdx | 2 +- docs/guides/frontends/asset-canister.md | 2 +- docs/guides/testing/strategies.md | 2 +- 8 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md index 802851c9..be9bef5a 100644 --- a/docs/getting-started/quickstart.md +++ b/docs/getting-started/quickstart.md @@ -68,7 +68,7 @@ Your new project contains: icp network start -d ``` -This starts a local Internet Computer replica in the background. The local network comes pre-funded. You can deploy immediately without setting up a wallet or acquiring cycles. +This starts a local Internet Computer replica in the background. The local network comes pre-funded. You can deploy immediately without setting up a wallet or acquiring [cycles](../concepts/cycles.md). ## Deploy diff --git a/docs/guides/backends/https-outcalls.mdx b/docs/guides/backends/https-outcalls.mdx index 6c132155..735ab637 100644 --- a/docs/guides/backends/https-outcalls.mdx +++ b/docs/guides/backends/https-outcalls.mdx @@ -18,7 +18,7 @@ For how the consensus mechanism works for outcalls, see [Concepts: HTTPS Outcall By default, every replica node in the subnet independently makes the same HTTP request: called **replicated mode**. All nodes must agree on the response before execution continues. Two constraints apply regardless of mode: -- Cycles to cover the request cost **must be attached** at call time. In Rust, `ic_cdk::management_canister::http_request` auto-calculates and attaches cycles. In Motoko, cycles must be attached explicitly with `await (with cycles = ...)`. +- [Cycles](../../concepts/cycles.md) to cover the request cost **must be attached** at call time. In Rust, `ic_cdk::management_canister::http_request` auto-calculates and attaches cycles. In Motoko, cycles must be attached explicitly with `await (with cycles = ...)`. - The **maximum response body is 2MB** (2,097,152 bytes). Requests exceeding this limit fail. Always set `max_response_bytes` to a tight upper bound: omitting it defaults to 2MB and charges cycles accordingly. In replicated mode, a transform function is strongly recommended: without one, responses across nodes will likely differ and consensus will fail. In non-replicated mode (`is_replicated = false`), a transform is unnecessary because only one node makes the request. See [Replicated vs non-replicated mode](#replicated-vs-non-replicated-mode) below. diff --git a/docs/guides/canister-calls/onchain-calls.mdx b/docs/guides/canister-calls/onchain-calls.mdx index f9689141..794c63e9 100644 --- a/docs/guides/canister-calls/onchain-calls.mdx +++ b/docs/guides/canister-calls/onchain-calls.mdx @@ -7,7 +7,7 @@ sidebar: import { Tabs, TabItem } from '@astrojs/starlight/components'; -Canisters on the Internet Computer communicate by calling each other's functions. A caller canister sends a request message containing the method name, arguments, and optionally attached cycles. The callee executes the method and returns a response. If the callee cannot be reached or a resource limit is hit, the system produces a reject response instead. +Canisters on the Internet Computer communicate by calling each other's functions. A caller canister sends a request message containing the method name, arguments, and optionally attached [cycles](../../concepts/cycles.md). The callee executes the method and returns a response. If the callee cannot be reached or a resource limit is hit, the system produces a reject response instead. This guide covers making inter-canister calls in both Motoko and Rust, choosing between query and update calls, handling errors, and avoiding common pitfalls. For the messaging model behind these calls, see [Canisters](../../concepts/canisters.md). diff --git a/docs/guides/canister-management/lifecycle.mdx b/docs/guides/canister-management/lifecycle.mdx index 04cb2841..0aa6ff65 100644 --- a/docs/guides/canister-management/lifecycle.mdx +++ b/docs/guides/canister-management/lifecycle.mdx @@ -20,7 +20,7 @@ A canister progresses through these phases: 3. **Run**: the canister processes messages and serves requests 4. **Upgrade**: replace the code while preserving stable state 5. **Stop**: pause message processing (required before deletion) -6. **Delete**: permanently remove the canister and reclaim cycles +6. **Delete**: permanently remove the canister and reclaim [cycles](../../concepts/cycles.md) In practice, `icp deploy` handles steps 1–3 automatically. You interact with individual steps when you need finer control. diff --git a/docs/guides/canister-management/optimization.md b/docs/guides/canister-management/optimization.md index e002a87d..d5f7e33d 100644 --- a/docs/guides/canister-management/optimization.md +++ b/docs/guides/canister-management/optimization.md @@ -5,7 +5,7 @@ sidebar: order: 4 --- -Canister Wasm binaries compiled from Rust or Motoko are often larger than necessary and may execute more instructions than needed. Smaller binaries install faster, consume fewer cycles on deployment, and leave more room within the per-canister Wasm memory limit. Better runtime efficiency directly reduces the cycles charged per call. +Canister Wasm binaries compiled from Rust or Motoko are often larger than necessary and may execute more instructions than needed. Smaller binaries install faster, consume fewer [cycles](../../concepts/cycles.md) on deployment, and leave more room within the per-canister Wasm memory limit. Better runtime efficiency directly reduces the cycles charged per call. This guide covers the main tools and techniques available: diff --git a/docs/guides/canister-management/settings.mdx b/docs/guides/canister-management/settings.mdx index 5480f4a8..a002be6d 100644 --- a/docs/guides/canister-management/settings.mdx +++ b/docs/guides/canister-management/settings.mdx @@ -69,7 +69,7 @@ settings: A value of `50` means the canister gets 50% of an execution core and is scheduled at least every other round. A value of `100` means the canister runs every round. -Compute allocation incurs a rental fee based on time and allocation percentage, regardless of whether the canister actually executes. This increases idle cycle consumption. See [cycles costs](../../reference/cycles-costs.md) for pricing details. +Compute allocation incurs a rental fee based on time and allocation percentage, regardless of whether the canister actually executes. This increases idle [cycle](../../concepts/cycles.md) consumption. See [cycles costs](../../reference/cycles-costs.md) for pricing details. ### Memory allocation diff --git a/docs/guides/frontends/asset-canister.md b/docs/guides/frontends/asset-canister.md index 71c2be51..5c32e216 100644 --- a/docs/guides/frontends/asset-canister.md +++ b/docs/guides/frontends/asset-canister.md @@ -32,7 +32,7 @@ Users access your frontend at `https://.icp0.io` (mainnet) or `http - **No server-side rendering.** Canisters cannot run JavaScript at the server level. Use static-site generation (SSG) or client-side rendering. If SSR is required, host the frontend outside ICP and keep the backend logic in a canister. - **No dynamic URL routing at the server level.** The asset canister serves static files. Client-side routing (via SPA aliasing) works, but server-generated routes do not. -- **Storage limits.** The asset canister can hold well over 4 GiB in stable memory, but individual uploads are limited by the 2 MB ingress message size (the JS SDK handles chunking automatically for larger files). Large media files become expensive in cycles. Use a dedicated storage solution for video or large datasets. +- **Storage limits.** The asset canister can hold well over 4 GiB in stable memory, but individual uploads are limited by the 2 MB ingress message size (the JS SDK handles chunking automatically for larger files). Large media files become expensive in [cycles](../../concepts/cycles.md). Use a dedicated storage solution for video or large datasets. ## Configure the asset canister diff --git a/docs/guides/testing/strategies.md b/docs/guides/testing/strategies.md index 45f53bf1..901e6993 100644 --- a/docs/guides/testing/strategies.md +++ b/docs/guides/testing/strategies.md @@ -7,7 +7,7 @@ sidebar: 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 +Second, [cycles](../../concepts/cycles.md) 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. ## The testing pyramid