From 3122b0d369f1b6f60137f728c4d9e79bbd50aba6 Mon Sep 17 00:00:00 2001 From: Marco Walz Date: Wed, 20 May 2026 16:15:38 +0200 Subject: [PATCH 1/2] docs: add resource-limits reference page, rename cycles-costs to cycle-costs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add docs/references/resource-limits.md with full table coverage (message limits, instruction limits, memory, Wasm module, subnet, execution threads, environment variables) plus Performance characteristics and Additional notes prose sections ported from dfinity/portal - Rename references/cycles-costs.md → references/cycle-costs.md; fix title from "Cycles costs" to "Cycle costs" (sentence-case, natural compound noun) - Remove the condensed Resource limits table from cycle-costs.md; replace with a cross-reference to the new dedicated page - Add resource-limits sidebar entry after cycle-costs, before subnet-types - Update all 16 inbound links across concepts/, guides/, and references/; links in execution-errors.md and ic-interface-spec/canister-interface.md that pointed to resource-limit context now point to resource-limits.md (with #message-limits and #memory-limits anchors where appropriate) --- docs/concepts/chain-key-cryptography.md | 2 +- docs/concepts/cycles.md | 2 +- docs/concepts/https-outcalls.md | 4 +- docs/guides/backends/https-outcalls.mdx | 4 +- docs/guides/backends/timers.mdx | 4 +- .../canister-management/cycles-management.mdx | 4 +- .../canister-management/optimization.md | 2 +- docs/guides/canister-management/settings.mdx | 6 +- .../canister-management/subnet-selection.md | 4 +- docs/guides/security/dos-prevention.md | 4 +- docs/guides/security/https-outcalls.md | 4 +- .../{cycles-costs.md => cycle-costs.md} | 26 +---- docs/references/execution-errors.md | 6 +- .../ic-interface-spec/canister-interface.md | 6 +- .../references/ic-interface-spec/changelog.md | 2 +- docs/references/index.md | 3 +- docs/references/resource-limits.md | 105 ++++++++++++++++++ docs/references/subnet-types.md | 8 +- sidebar.mjs | 3 +- 19 files changed, 143 insertions(+), 56 deletions(-) rename docs/references/{cycles-costs.md => cycle-costs.md} (86%) create mode 100644 docs/references/resource-limits.md diff --git a/docs/concepts/chain-key-cryptography.md b/docs/concepts/chain-key-cryptography.md index a8c296d0..c3a94a3a 100644 --- a/docs/concepts/chain-key-cryptography.md +++ b/docs/concepts/chain-key-cryptography.md @@ -98,7 +98,7 @@ The following master keys are deployed at the time of writing. The Network Nervo Test keys are available for development and run on smaller subnets with lower signing costs. They should not be used for anything of value. Production keys run on high-replication subnets (34+ nodes) for stronger security guarantees. Each key is also reshared to a backup subnet for availability: if the signing subnet fails, the backup can take over without generating a new key. -For signing costs, see [Cycles costs](../references/cycles-costs.md). +For signing costs, see [Cycle costs](../references/cycle-costs.md). ## Supported chains diff --git a/docs/concepts/cycles.md b/docs/concepts/cycles.md index 77a1e731..7a8e6374 100644 --- a/docs/concepts/cycles.md +++ b/docs/concepts/cycles.md @@ -120,7 +120,7 @@ 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 - [Calls with attached cycles](../guides/canister-calls/inter-canister-calls.md#calls-with-attached-cycles): attach cycles to an inter-canister call and use the proxy canister pattern for the CLI - [Cycles ledger reference](../references/system-canisters.md#cycles-ledger): canister IDs, interface specification, and CMC integration -- [Cycles Costs Reference](../references/cycles-costs.md): exact cost tables for all operations +- [Cycle costs](../references/cycle-costs.md): exact cost tables for all operations - [Canisters](./canisters.md): canisters as the paying entity for compute and storage diff --git a/docs/concepts/https-outcalls.md b/docs/concepts/https-outcalls.md index 94324524..7a1c61a1 100644 --- a/docs/concepts/https-outcalls.md +++ b/docs/concepts/https-outcalls.md @@ -76,7 +76,7 @@ The cost depends on two factors: If you omit `max_response_bytes`, the system assumes the maximum of 2 MB and charges accordingly: roughly 21.5 billion cycles on a 13-node subnet. Always set this to a reasonable upper bound for your expected response to avoid overpaying. Unused cycles are refunded. -For exact pricing formulas, see the [cycles costs reference](../references/cycles-costs.md). +For exact pricing formulas, see the [cycles costs reference](../references/cycle-costs.md). ## Limitations @@ -110,5 +110,5 @@ One extension is under consideration that may affect architecture decisions: - [HTTPS outcalls guide](../guides/backends/https-outcalls.md): practical how-to with code examples in Motoko and Rust - [Chain Fusion: Ethereum integration](../guides/chain-fusion/ethereum.md): uses HTTPS outcalls via the EVM RPC canister -- [Cycles costs reference](../references/cycles-costs.md): detailed pricing formulas +- [Cycles costs reference](../references/cycle-costs.md): detailed pricing formulas diff --git a/docs/guides/backends/https-outcalls.mdx b/docs/guides/backends/https-outcalls.mdx index 7418e933..0a42511a 100644 --- a/docs/guides/backends/https-outcalls.mdx +++ b/docs/guides/backends/https-outcalls.mdx @@ -146,7 +146,7 @@ For reference, on a 13-node subnet: - Per request byte: 5,200 cycles - Per `max_response_bytes` byte: 10,400 cycles -See [Cycles costs](../../references/cycles-costs.md#https-outcalls) for the full pricing table. +See [Cycles costs](../../references/cycle-costs.md#https-outcalls) for the full pricing table. ## Limitations and pitfalls @@ -166,6 +166,6 @@ Use the "Full example in ICP Ninja" links above to deploy and test directly in t - [Management canister reference](../../references/management-canister.md#http_request): full `http_request` parameter reference including all fields - [Exchange Rate Canister (XRC)](https://github.com/dfinity/exchange-rate-canister): a production service powered by HTTPS outcalls that fetches digital asset and fiat exchange rates - [Chain Fusion: Ethereum](../chain-fusion/ethereum.md): the EVM RPC canister uses HTTPS outcalls under the hood -- [Cycles costs](../../references/cycles-costs.md#https-outcalls): outcall pricing details +- [Cycles costs](../../references/cycle-costs.md#https-outcalls): outcall pricing details {/* Upstream: informed by dfinity/portal docs/building-apps/network-features/using-http/https-outcalls/; dfinity/examples send_http_get, send_http_post */} diff --git a/docs/guides/backends/timers.mdx b/docs/guides/backends/timers.mdx index cf15f6d6..a751e7a5 100644 --- a/docs/guides/backends/timers.mdx +++ b/docs/guides/backends/timers.mdx @@ -215,7 +215,7 @@ Timer tasks are added to the canister's input queue. If the canister or subnet i The canister output queue is limited to 500 messages. This caps how many timers can fire in a single round. The CDK also enforces internal rate limits (250 concurrent timer calls globally, 5 per interval timer). -See [Cycles and costs](../../references/cycles-costs.md#cost-table) for current pricing. +See [Cycles and costs](../../references/cycle-costs.md#cost-table) for current pricing. ## Heartbeats (legacy) @@ -279,6 +279,6 @@ For a complete working example with cycle tracking and multiple timers: - [Canister lifecycle](../canister-management/lifecycle.md#what-happens-during-an-upgrade): init, pre/post-upgrade hooks - [Timers (concept)](../../concepts/timers.md): how the IC protocol timer works -- [Cycles and costs](../../references/cycles-costs.md#cost-table): current pricing +- [Cycles and costs](../../references/cycle-costs.md#cost-table): current pricing {/* Upstream: informed by dfinity/portal docs/building-apps/network-features/periodic-tasks-timers.mdx, docs/building-apps/network-features/time-and-timestamps.mdx, dfinity/cdk-rs ic-cdk-timers/src/lib.rs, and caffeinelabs/motoko-core src/Timer.mo */} diff --git a/docs/guides/canister-management/cycles-management.mdx b/docs/guides/canister-management/cycles-management.mdx index 10301525..93be6d30 100644 --- a/docs/guides/canister-management/cycles-management.mdx +++ b/docs/guides/canister-management/cycles-management.mdx @@ -57,7 +57,7 @@ icp cycles balance -n ic # Output: ~5T cycles ``` -**Budget guidance:** Plan for 1–2T cycles per canister as a starting balance. A simple backend canister with moderate traffic costs roughly 0.1–0.5T cycles per month, though this varies with storage and call volume. See the [cycles costs reference](../../references/cycles-costs.md#cost-table) for per-operation pricing. +**Budget guidance:** Plan for 1–2T cycles per canister as a starting balance. A simple backend canister with moderate traffic costs roughly 0.1–0.5T cycles per month, though this varies with storage and call volume. See the [cycles costs reference](../../references/cycle-costs.md#cost-table) for per-operation pricing. ## Checking canister cycle balances @@ -370,7 +370,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](../../references/cycles-costs.md#cost-table): Exact cost tables per operation +- [Cycles costs reference](../../references/cycle-costs.md#cost-table): Exact cost tables per operation - [Cycles](../../concepts/cycles.md): Why canisters pay for execution and how the cycles ledger works - [Cycles ledger reference](../../references/system-canisters.md#cycles-ledger): Canister IDs and interface specification - [Calls with attached cycles](../canister-calls/inter-canister-calls.md#calls-with-attached-cycles): attach cycles to an inter-canister call and accept them in the callee diff --git a/docs/guides/canister-management/optimization.md b/docs/guides/canister-management/optimization.md index 73360685..104352c7 100644 --- a/docs/guides/canister-management/optimization.md +++ b/docs/guides/canister-management/optimization.md @@ -231,7 +231,7 @@ Most production canisters benefit from combining several techniques: ## Next steps - [Large Wasm](large-wasm.md): when binary size exceeds the upload limit -- [Cycles costs](../../references/cycles-costs.md): how Wasm size and instruction count map to cycle charges +- [Cycles costs](../../references/cycle-costs.md): how Wasm size and instruction count map to cycle charges - [Canister lifecycle](lifecycle.md): how optimized builds integrate with the icp-cli deploy workflow diff --git a/docs/guides/canister-management/settings.mdx b/docs/guides/canister-management/settings.mdx index 79bdf837..23fa3223 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](../../concepts/cycles.md) consumption. See [cycles costs](../../references/cycles-costs.md#compute-allocation) 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](../../references/cycle-costs.md#compute-allocation) for pricing details. ### Memory allocation @@ -90,7 +90,7 @@ Supported suffixes: `kb` (1,000), `kib` (1,024), `mb` (1,000,000), `mib` (1,048, When set, the canister draws new Wasm and stable memory from the pre-allocated pool. If usage exceeds the allocation, additional memory is allocated on demand and may fail if the subnet is at capacity. -Like compute allocation, memory allocation incurs a rental fee based on time and allocated amount, regardless of actual usage. See [cycles costs](../../references/cycles-costs.md#storage-reservation) for pricing. +Like compute allocation, memory allocation incurs a rental fee based on time and allocated amount, regardless of actual usage. See [cycles costs](../../references/cycle-costs.md#storage-reservation) for pricing. ### Freezing threshold @@ -454,7 +454,7 @@ How you configure controllers depends on the trust model for your canister: - [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](../../references/cycles-costs.md#compute-allocation): Pricing for compute and memory allocation. +- [Cycles costs reference](../../references/cycle-costs.md#compute-allocation): Pricing for compute and memory allocation. - [Management canister reference](../../references/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/canister-management/subnet-selection.md b/docs/guides/canister-management/subnet-selection.md index 48481e0a..d054a8b5 100644 --- a/docs/guides/canister-management/subnet-selection.md +++ b/docs/guides/canister-management/subnet-selection.md @@ -133,7 +133,7 @@ Subnets enforce a storage reservation policy above 750 GiB of total utilization. If you expect your canister to use significant storage, check the current utilization of candidate subnets on the [ICP Dashboard](https://dashboard.internetcomputer.org/subnets) before deploying. Choosing a subnet with available headroom avoids unexpected reservation costs as your canister grows. -For details on storage costs and the reservation formula, see [Cycles costs](../../references/cycles-costs.md#storage-reservation). +For details on storage costs and the reservation formula, see [Cycles costs](../../references/cycle-costs.md#storage-reservation). ## Troubleshooting @@ -152,7 +152,7 @@ Note that any canister ID change means losing access to any threshold signature ## Next steps -- [Cycles costs](../../references/cycles-costs.md#replication-factors): Cost tables and the subnet multiplier formula +- [Cycles costs](../../references/cycle-costs.md#replication-factors): Cost tables and the subnet multiplier formula - [Subnet types reference](../../references/subnet-types.md): Full reference for all subnet types with node counts and properties - [Canister snapshots](snapshots.md#example-transferring-state-between-canisters): Download/upload workflow for transferring state to another canister - [Canister migration](canister-migration.md): Complete workflow for moving a canister to a different subnet, with or without preserving the canister ID diff --git a/docs/guides/security/dos-prevention.md b/docs/guides/security/dos-prevention.md index 0e6fb4b3..ceb03f30 100644 --- a/docs/guides/security/dos-prevention.md +++ b/docs/guides/security/dos-prevention.md @@ -30,7 +30,7 @@ In a shared resource environment like the Internet Computer, multiple canisters To mitigate the "noisy neighbor" issue, manage your canister's resource allocation effectively: * **Memory allocation**: Memory can be reserved per canister by setting `memory_allocation`, ensuring that your canister can always allocate memory up to the requested `memory_allocation` and preventing other canisters from using up the subnet's available memory. Note that memory availability is not guaranteed beyond the memory allocation and thus monitoring actual memory usage against this value is important to avoid availability issues. * **Compute reservation**: Similar to memory, computing power can also be reserved by setting `compute_allocation` to a value between 0 and 100, which denotes the percentage of one CPU core to be reserved for this canister. A value of 50 means that every 2 rounds, the canister will be scheduled to execute a message. This guarantees the minimal progress your canister can make, which protects against noisy neighbors. Both allocations are reserving resources for your canister on the subnet, which prevents the other canisters from using them. Hence, they come at a cost. Memory allocation is charged as if all that memory would be allocated. Compute allocation is currently charged at 10M cycles per percentage point. -Learn more about managing memory and compute resources in the [cycles costs reference](../../references/cycles-costs.md). +Learn more about managing memory and compute resources in the [cycles costs reference](../../references/cycle-costs.md). * **Subnet and canister distribution**: Implement a smart canister deployment strategy by monitoring the load on subnets. You can choose to deploy new canisters on less busy subnets or adopt a multi-canister architecture that balances the load across subnets. Be mindful to minimize inter-subnet communication for canisters that frequently interact with each other. Additionally, avoid deploying to known high-traffic subnets where possible, though keep in mind that resource usage can change unexpectedly with new apps. :::note @@ -41,7 +41,7 @@ When the subnet grows above 750GiB, then the new reservation mechanism activates ### Security concern -Some calls (update or query) might be expensive in terms of the memory or cycles they consume. For example, any function using chain-key signing or HTTPS outcalls is relatively expensive. See the [cycles costs reference](../../references/cycles-costs.md) for pricing details and a full list of expensive call types. +Some calls (update or query) might be expensive in terms of the memory or cycles they consume. For example, any function using chain-key signing or HTTPS outcalls is relatively expensive. See the [cycles costs reference](../../references/cycle-costs.md) for pricing details and a full list of expensive call types. An attacker will target expensive calls to drain the cycles balance or available memory quickly. diff --git a/docs/guides/security/https-outcalls.md b/docs/guides/security/https-outcalls.md index 238e7a7d..d8b9dcae 100644 --- a/docs/guides/security/https-outcalls.md +++ b/docs/guides/security/https-outcalls.md @@ -70,7 +70,7 @@ See the [HTTPS outcalls guide](../backends/https-outcalls.md) for more details. ### Security concern -The [pricing](../../references/cycles-costs.md#https-outcalls) of HTTPS outcalls is determined by the size of the HTTP request and the maximal response size, among other variables. Thus, if big requests are made, this could quickly drain the canister's cycles balance. This can be risky in scenarios where HTTPS outcalls are triggered by user actions (rather than a heartbeat or timer invocation). +The [pricing](../../references/cycle-costs.md#https-outcalls) of HTTPS outcalls is determined by the size of the HTTP request and the maximal response size, among other variables. Thus, if big requests are made, this could quickly drain the canister's cycles balance. This can be risky in scenarios where HTTPS outcalls are triggered by user actions (rather than a heartbeat or timer invocation). ### Recommendation @@ -80,7 +80,7 @@ When making an HTTPS outcall, it is possible (and highly recommended) to define Finally, be aware that users may incur cycles costs for HTTPS outcalls in case these calls can be triggered by user actions. -See the [cycles costs reference](../../references/cycles-costs.md) for pricing details. +See the [cycles costs reference](../../references/cycle-costs.md) for pricing details. ## Perform input validation in HTTPS outcalls diff --git a/docs/references/cycles-costs.md b/docs/references/cycle-costs.md similarity index 86% rename from docs/references/cycles-costs.md rename to docs/references/cycle-costs.md index 6f958ec2..47805e47 100644 --- a/docs/references/cycles-costs.md +++ b/docs/references/cycle-costs.md @@ -1,5 +1,5 @@ --- -title: "Cycles costs" +title: "Cycle costs" description: "Exact cycle costs for compute, storage, HTTPS outcalls, signing, and canister operations" sidebar: order: 8 @@ -102,27 +102,6 @@ When a canister grows its memory (via `memory.grow`, `ic0.stable_grow()`, or Was Reserved cycles are non-transferable. Controllers can disable reservation by setting `reserved_cycles_limit = 0`, but opted-out canisters cannot allocate new memory when subnet usage exceeds 750 GiB. -## Resource limits - -| Limit | Value | -|-------|-------| -| Instructions per update call / heartbeat / timer | 40 billion | -| Instructions per query call | 5 billion | -| Instructions per canister install / upgrade | 300 billion | -| Instructions per `inspect_message` | 200 million | -| Max ingress message payload | 2 MiB | -| Max cross-subnet inter-canister message payload | 2 MiB | -| Max same-subnet inter-canister request payload | 10 MiB | -| Max response size (replicated execution) | 2 MiB | -| Max response size (query) | 3 MiB | -| Wasm heap memory per canister | 4 GiB (wasm32) / 6 GiB (wasm64) | -| Wasm stable memory per canister | 500 GiB | -| Subnet capacity (total memory) | 2 TiB | -| Wasm module total size | 100 MiB | -| Wasm code section size | 10 MiB | - - - ## Special features Certain ICP features have additional cycle costs beyond the base execution and messaging fees: @@ -139,5 +118,6 @@ Certain ICP features have additional cycle costs beyond the base execution and m - [Cycles management](../guides/canister-management/cycles-management.md): Topping up and monitoring canister balances - [Cycles](../concepts/cycles.md): Why canisters (not users) pay for execution - [Subnet types](subnet-types.md): Cost multipliers per subnet type +- [Resource limits](resource-limits.md): Instruction limits, memory caps, and message size constraints - + diff --git a/docs/references/execution-errors.md b/docs/references/execution-errors.md index 222e2485..5faff905 100644 --- a/docs/references/execution-errors.md +++ b/docs/references/execution-errors.md @@ -64,7 +64,7 @@ ICP limits the number of WebAssembly instructions a canister can execute per mes | Canister install / upgrade | 300 billion | | `inspect_message` | 200 million | -See [resource limits](./cycles-costs.md) for the full table. +See [resource limits](./resource-limits.md) for the full table. To fix this error, use tools such as the performance counter API or [canbench](https://github.com/dfinity/canbench) to identify which sections of code use the most instructions and optimize them. @@ -77,7 +77,7 @@ The amount of data the canister tried to read or write from stable memory exceed Canister exceeded memory access limits: Exceeded the limit for the number of modified pages in the stable memory in a single message execution: limit: 8388608 KB. ``` -Although stable memory can hold hundreds of GiB of data, each message must execute within a round and is limited to reading and writing only a portion of that data. See [resource limits](./cycles-costs.md) for current values. +Although stable memory can hold hundreds of GiB of data, each message must execute within a round and is limited to reading and writing only a portion of that data. See [resource limits](./resource-limits.md) for current values. To fix this error, break up operations that read or write large regions of stable memory into multiple messages, using self-calls if necessary. @@ -806,7 +806,7 @@ To fix this error, confirm that the metadata section exists for the given canist ## Next steps -- Review [resource limits](./cycles-costs.md) for the full table of ICP constraints. +- Review [resource limits](./resource-limits.md) for the full table of ICP constraints. - Learn about [canister lifecycle](../guides/canister-management/lifecycle.md) including traps during upgrades. - Optimize resource usage with the [canister optimization guide](../guides/canister-management/optimization.md). - Understand the system APIs in the [IC interface specification](./ic-interface-spec/canister-interface.md). diff --git a/docs/references/ic-interface-spec/canister-interface.md b/docs/references/ic-interface-spec/canister-interface.md index 0db58772..2e0f0504 100644 --- a/docs/references/ic-interface-spec/canister-interface.md +++ b/docs/references/ic-interface-spec/canister-interface.md @@ -438,7 +438,7 @@ Eventually, the canister will want to respond to the original call, either by re - `ic0.msg_reply_data_append : (src : I, size : I) → ()`; `I ∈ {i32, i64}` - Appends data it to the (initially empty) data reply. Traps if the total appended data exceeds the [maximum response size](../cycles-costs.md). + Appends data it to the (initially empty) data reply. Traps if the total appended data exceeds the [maximum response size](../resource-limits.md#message-limits). This traps if the current call already has been or does not need to be responded to. @@ -576,7 +576,7 @@ There must be at most one call to `ic0.call_on_cleanup` between `ic0.call_new` a - `ic0.call_data_append : (src : I, size : I) -> ()`; `I ∈ {i32, i64}` - Appends the specified bytes to the argument of the call. Initially, the argument is empty. Traps if the total appended data exceeds the [maximum inter-canister call payload](../cycles-costs.md). + Appends the specified bytes to the argument of the call. Initially, the argument is empty. Traps if the total appended data exceeds the [maximum inter-canister call payload](../resource-limits.md#message-limits). This may be called multiple times between `ic0.call_new` and `ic0.call_perform`. @@ -736,7 +736,7 @@ The 32-bit stable memory System API (`ic0.stable_size`, `ic0.stable_grow`, `ic0. Canisters have the ability to store and retrieve data from a secondary memory. The purpose of this *stable memory* is to provide space to store data beyond upgrades. The interface mirrors roughly the memory-related instructions of WebAssembly, and tries to be forward compatible with exposing this feature as an additional memory. -The stable memory is initially empty and can be grown up to the [Wasm stable memory limit](../cycles-costs.md) (provided the subnet has capacity). +The stable memory is initially empty and can be grown up to the [Wasm stable memory limit](../resource-limits.md#memory-limits) (provided the subnet has capacity). - `ic0.stable_size : () → (page_count : i32)` diff --git a/docs/references/ic-interface-spec/changelog.md b/docs/references/ic-interface-spec/changelog.md index 0018653f..b0c3d2f4 100644 --- a/docs/references/ic-interface-spec/changelog.md +++ b/docs/references/ic-interface-spec/changelog.md @@ -494,7 +494,7 @@ sidebar: diff --git a/docs/references/index.md b/docs/references/index.md index 388fedd1..33c7c67e 100644 --- a/docs/references/index.md +++ b/docs/references/index.md @@ -19,7 +19,8 @@ Technical reference material for ICP development. These pages cover exact specif - **[ICRC Standards](icrc-standards.md)**: Index of all adopted ICRC standards grouped by category. - **[Digital Asset Standards](digital-asset-standards.md)**: ICRC-1, ICRC-2, ICRC-3, ICRC-7, and ICRC-37 in full detail. - **[Chain-Key Token Canister IDs](chain-key-canister-ids.md)**: Mainnet and testnet canister IDs for ckBTC, ckETH, ckERC20, ckDOGE, and ckSOL. -- **[Cycles costs](cycles-costs.md)**: Exact cycle costs for compute, storage, HTTPS outcalls, signing, and canister operations. +- **[Cycle costs](cycle-costs.md)**: Exact cycle costs for compute, storage, HTTPS outcalls, signing, and canister operations. +- **[Resource limits](resource-limits.md)**: Instruction limits, memory caps, message sizes, Wasm module limits, and execution thread counts. - **[Subnet Types](subnet-types.md)**: All subnet types with node counts, replication factors, and cycle cost multipliers. ## Errors and debugging diff --git a/docs/references/resource-limits.md b/docs/references/resource-limits.md new file mode 100644 index 00000000..1b94fecb --- /dev/null +++ b/docs/references/resource-limits.md @@ -0,0 +1,105 @@ +--- +title: "Resource limits" +description: "Execution constraints for canisters: instruction limits, memory caps, message sizes, Wasm module limits, and thread counts" +sidebar: + order: 9 +--- + +ICP uses WebAssembly as the execution environment for canisters. Because WebAssembly is [Turing-complete](https://en.wikipedia.org/wiki/Turing_completeness), the IC enforces resource limits to prevent non-terminating computations and ensure fair scheduling across all canisters on a [subnet](../concepts/network-overview.md#subnets). + +## Message limits + +| Limit | Value | +|-------|-------| +| Message queue limit (between a canister pair) | 500 | +| Max ingress message payload | 2 MiB | +| Max cross-subnet inter-canister message payload | 2 MiB | +| Max same-subnet inter-canister request payload | 10 MiB | +| Max response size (replicated execution) | 2 MiB | +| Max response size (non-replicated execution, query calls) | 3 MiB | + +## Instruction limits + +| Limit | Value | +|-------|-------| +| Per update call, heartbeat, or timer | 40 billion | +| Per query call | 5 billion | +| Per canister install or upgrade | 300 billion | +| Per `inspect_message` | 200 million | +| Per round per execution thread | 7 billion | + +## Memory limits + +| Limit | Value | +|-------|-------| +| Wasm heap memory per canister | 4 GiB (wasm32), 6 GiB (wasm64) | +| Wasm stable memory per canister | 500 GiB | +| Stable memory read per replicated message | 2 GiB | +| Stable memory written per replicated message | 2 GiB | +| Stable memory read per upgrade message | 8 GiB | +| Stable memory written per upgrade message | 8 GiB | +| Stable memory read per replicated query | 1 GiB | +| Stable memory written per replicated query | 1 GiB | + +## Wasm module limits + +| Limit | Value | +|-------|-------| +| Wasm total size per canister | 100 MiB | +| Wasm code section per canister | 10 MiB | +| Custom sections per subnet | 2 GiB | +| Custom sections per canister | 1 MiB | +| Custom section count per canister | 16 | +| Function name length | 1 MiB | + +## Subnet limits + +| Limit | Value | +|-------|-------| +| Subnet capacity (total memory) | 2 TiB | +| Snapshots per canister | 10 | + +## Execution thread limits + +| Limit | Value | +|-------|-------| +| Query execution threads per replica node | 4 | +| Query execution threads per canister | 2 | +| Update execution threads per subnet | 4 | +| Update execution threads per canister | 1 | + +## Canister environment variables + +| Limit | Value | +|-------|-------| +| Environment variables per canister | 20 | +| Variable name length | 128 bytes | +| Variable value length | 128 bytes | + +## Performance characteristics + +Block production rate varies from 0.75 to 1.5 blocks per second depending on [subnet](../concepts/network-overview.md#subnets) load and node count. Up to 1,000 messages can be included in a block. Because ICP decouples message reception from message execution, messages included in a block are not guaranteed to execute in the same block. Messages for different canisters may execute in parallel across up to 4 execution threads, each capable of handling up to 1,000 messages. ICP targets a throughput of 2 billion Wasm instructions per thread per second. + +## Additional notes + +The expiration time of an ingress message is set by the agent making the request and can be up to 5 minutes. + +The IC rejects Wasm modules that exceed these structural limits: + +- More than 50,000 declared functions +- More than 1,000 declared globals +- A function body containing more than 1,000,000 Wasm instructions +- More than 16 exported custom sections (names prefixed with `icp:`) +- More than 1,000 exported `canister_update ` or `canister_query ` functions +- Combined `` lengths across all exported update and query functions exceeding 20,000 characters +- Total exported custom sections size exceeding 1 MiB + +For the full specification of these constraints, see [WebAssembly module requirements](ic-interface-spec/canister-interface.md#system-api-module). + +## Related pages + +- [Cycle costs](cycle-costs.md): Billing rates for instructions, storage, and messaging +- [Subnet types](subnet-types.md): Subnet-specific constraints and cost multipliers +- [Canister optimization](../guides/canister-management/optimization.md): Reducing instruction count and memory footprint + + diff --git a/docs/references/subnet-types.md b/docs/references/subnet-types.md index 4f47c890..8d088aa8 100644 --- a/docs/references/subnet-types.md +++ b/docs/references/subnet-types.md @@ -7,7 +7,7 @@ sidebar: The Internet Computer is composed of independent [**subnets**](../concepts/network-overview.md#subnets): each an autonomous blockchain that hosts a set of canisters. Subnets differ in node count, replication factor, costs, geographic distribution, and what canisters they accept. This page lists all subnet types and their properties. -For guidance on choosing a subnet for deployment, see [Subnet selection](../guides/canister-management/subnet-selection.md). For per-operation cycle costs, see [Cycles costs](cycles-costs.md). +For guidance on choosing a subnet for deployment, see [Subnet selection](../guides/canister-management/subnet-selection.md). For per-operation cycle costs, see [Cycles costs](cycle-costs.md). ## Subnet properties explained @@ -74,7 +74,7 @@ The fiduciary subnet hosts the active threshold signature keys used by all chain > **Note:** Check the [ICP Dashboard](https://dashboard.internetcomputer.org/subnets) for the authoritative current node count and full principal ID of the fiduciary subnet. The node count determines the exact cycle cost multiplier for operations on this subnet. -**Cost example (based on 34 nodes):** An update call that costs 5 million cycles on a 13-node subnet costs approximately 13 million cycles on the fiduciary subnet (`5M × 34/13 ≈ 13M`). See [Cycles costs](cycles-costs.md) for complete tables. +**Cost example (based on 34 nodes):** An update call that costs 5 million cycles on a 13-node subnet costs approximately 13 million cycles on the fiduciary subnet (`5M × 34/13 ≈ 13M`). See [Cycles costs](cycle-costs.md) for complete tables. To deploy to the fiduciary subnet (verify the full principal ID on the [ICP Dashboard](https://dashboard.internetcomputer.org/subnets) before deploying): @@ -129,7 +129,7 @@ For a fiduciary subnet, the multiplier depends on the current node count: verify | European | 13 | 500,000,000,000 | ~$0.68 | | Fiduciary | verify on dashboard | base × n / 13 | varies with node count | -USD values are approximate and vary with the ICP/XDR exchange rate. See [Cycles costs](cycles-costs.md) for current figures and the full cost table including storage, execution, Xnet calls, and HTTPS outcalls. +USD values are approximate and vary with the ICP/XDR exchange rate. See [Cycles costs](cycle-costs.md) for current figures and the full cost table including storage, execution, Xnet calls, and HTTPS outcalls. ## Finding subnet IDs @@ -145,6 +145,6 @@ To find which subnet an existing canister is on, search for the canister ID on t ## Next steps - [Subnet selection](../guides/canister-management/subnet-selection.md): How to choose a subnet for your deployment -- [Cycles costs](cycles-costs.md): Full cost tables and per-operation pricing +- [Cycles costs](cycle-costs.md): Full cost tables and per-operation pricing diff --git a/sidebar.mjs b/sidebar.mjs index eb801c94..32515d9d 100644 --- a/sidebar.mjs +++ b/sidebar.mjs @@ -181,7 +181,8 @@ export const sidebar = [ collapsed: true, items: [ { slug: "references/management-canister" }, - { slug: "references/cycles-costs" }, + { slug: "references/cycle-costs" }, + { slug: "references/resource-limits" }, { slug: "references/subnet-types" }, { slug: "references/execution-errors" }, ], From 8c2b92ccbb96f5dcf7b75a0390542885dcd3315c Mon Sep 17 00:00:00 2001 From: Marco Walz Date: Wed, 20 May 2026 16:31:32 +0200 Subject: [PATCH 2/2] fix: use correct Upstream keyword in resource-limits.md --- docs/references/resource-limits.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/references/resource-limits.md b/docs/references/resource-limits.md index 1b94fecb..087dd57c 100644 --- a/docs/references/resource-limits.md +++ b/docs/references/resource-limits.md @@ -102,4 +102,4 @@ For the full specification of these constraints, see [WebAssembly module require - [Subnet types](subnet-types.md): Subnet-specific constraints and cost multipliers - [Canister optimization](../guides/canister-management/optimization.md): Reducing instruction count and memory footprint - +