From 1cfbf6610c615167f1ecd87a51e00a7738cecf15 Mon Sep 17 00:00:00 2001 From: Raymond Khalife Date: Fri, 13 Mar 2026 15:00:25 -0400 Subject: [PATCH 1/2] docs: reference page for cycles costs and resource limits Converts the stub into a comprehensive reference covering cost tables, HTTPS outcall formulas, compute allocation, storage reservation, and resource limits, all adapted from portal source material. --- docs/reference/cycles-costs.md | 137 ++++++++++++++++++++++++++++++--- 1 file changed, 127 insertions(+), 10 deletions(-) diff --git a/docs/reference/cycles-costs.md b/docs/reference/cycles-costs.md index 724eb905..7ab64753 100644 --- a/docs/reference/cycles-costs.md +++ b/docs/reference/cycles-costs.md @@ -6,16 +6,133 @@ sidebar: icskills: [] --- -TODO: Write content for this page. +Canisters pay for the resources they consume and operations they perform using **cycles**. The price of cycles is pegged to [XDR](glossary.md) (Special Drawing Rights): **1 trillion cycles = 1 XDR**. As of May 22, 2025, 1 XDR ≈ $1.35 USD — this rate fluctuates; see the [IMF's XDR exchange data](https://www.imf.org/external/np/fin/data/rms_sdrv.aspx) for the current rate. - -Comprehensive cost reference for ICP operations. Include cost tables for: compute (per instruction), storage (per GB per second), bandwidth (per byte), canister creation, HTTPS outcalls, threshold ECDSA/Schnorr signing, and special operations. Include resource limits (instruction limit per message, memory limit per canister, response size limit). Compare with cloud pricing for context. +You can use the [pricing calculator](https://3d5wy-5aaaa-aaaag-qkhsq-cai.icp0.io/) to estimate the cost for your dapp. - -- Portal: building-apps/canister-management/resource-limits.mdx, defi cost tables -- Reference: subnet-types for pricing tier multipliers +## Cycles units - -- guides/canister-management/cycles-management -- managing costs -- concepts/reverse-gas-model -- why costs work this way -- reference/subnet-types -- cost multipliers per subnet +| Abbreviation | Name | In numbers | XDR value | Approx. USD value | +|--------------|----------|-------------------|-----------|-------------------| +| T | Trillion | 1_000_000_000_000 | 1 | ~$1.35 | +| B | Billion | 1_000_000_000 | 0.001 | ~$0.00135 | +| M | Million | 1_000_000 | 0.000001 | ~$0.00000135 | +| k | Thousand | 1_000 | 10⁻⁹ | ~$0.00000000135 | + +## Subnet replication factors + +Costs scale with the number of nodes in the subnet. The base cost tables below assume a **13-node application subnet**. For a 34-node (fiduciary) subnet, costs scale as `34 * (cost / 13)`: + +- **13-node subnet**: Standard application subnets. No scaling needed — costs are as listed. +- **34-node subnet**: Fiduciary subnets (higher security for DeFi). Costs are approximately **2.6×** the 13-node cost. + +See [Subnet types](subnet-types.md) for subnet-specific details. + +## Cost table + +| Operation | Description | Who pays | 13-node cycles | 13-node USD | 34-node cycles | 34-node USD | +|-----------|-------------|----------|----------------|-------------|----------------|-------------| +| Query call | Query information from a canister | N/A | Free | Free | Free | Free | +| Canister creation | Create a new canister | Created canister | 500_000_000_000 | ~$0.677 | 1_307_692_307_692 | ~$1.772 | +| Compute allocation (per % per second) | Reserved compute per second | Canister with allocation | 10_000_000 | ~$0.0000135 | 26_153_846 | ~$0.0000354 | +| Update message execution | Per update message executed | Target canister | 5_000_000 | ~$0.0000068 | 13_076_923 | ~$0.0000177 | +| 1B instructions executed | Per 1B Wasm instructions | Executing canister | 1_000_000_000 | ~$0.00135 | 2_615_384_615 | ~$0.00354 | +| Xnet call (request + response) | Inter-canister call overhead | Sending canister | 260_000 | ~$0.00000035 | 680_000 | ~$0.00000092 | +| Xnet byte transmission | Per byte in inter-canister call | Sending canister | 1_000 | ~$0.00000000135 | 2_615 | ~$0.00000000354 | +| Ingress message reception | Per ingress message received | Receiving canister | 1_200_000 | ~$0.0000016 | 3_138_461 | ~$0.0000043 | +| Ingress byte reception | Per byte in ingress message | Receiving canister | 2_000 | ~$0.0000000027 | 5_230 | ~$0.0000000071 | +| GiB storage per second | Storage cost per GiB per second | Canister with storage | 127_000 | ~$0.000000172 | 332_153 | ~$0.000000450 | + +**Storage cost per GiB per month (30 days):** + +| Subnet | Cycles | USD | +|--------|--------|-----| +| 13-node | ~329B | ~$0.45 | +| 34-node | ~861B | ~$1.70 | + +## HTTPS outcalls + +HTTPS outcall costs scale with subnet size (`n` = number of nodes): + +``` +total_fee = base_fee + size_fee +base_fee = (3_000_000 + 60_000 * n) * n +size_fee = (400 * request_bytes + 800 * max_response_bytes) * n +``` + +`request_bytes` is the total serialized request size (URL + headers + body + transform name/context). `max_response_bytes` defaults to 2 MiB if not explicitly set by the canister. + +| Component | 13-node cycles | 13-node USD | 34-node cycles | 34-node USD | +|-----------|----------------|-------------|----------------|-------------| +| Per call (base) | 49_140_000 | ~$0.0000666 | 171_360_000 | ~$0.000232 | +| Per request byte | 5_200 | ~$0.000000007 | 13_600 | ~$0.0000000184 | +| Per reserved response byte | 10_400 | ~$0.000000014 | 27_200 | ~$0.0000000369 | + +## Execution costs + +Execution cost formula: + +``` +total = base_fee + per_instruction_fee * num_instructions +``` + +Current values (13-node subnet): +- `base_fee` = 5_000_000 cycles (~$0.0000068 USD) +- `per_instruction_fee` = 1 cycle (so 1B instructions = 1B cycles ≈ $0.00135) + +## Compute allocation + +By default canisters are scheduled best-effort. Setting `compute_allocation` guarantees execution slots: + +- **1%** — Scheduled every 100 rounds +- **2%** — Scheduled every 50 rounds +- **100%** — Scheduled every round + +Total allocatable compute capacity per subnet is 299%. The cost is `10M cycles * allocation_percent` per second on a 13-node subnet. + +## Storage reservation + +When a canister grows its memory (via `memory.grow`, `ic0.stable_grow()`, or Wasm installation), the system moves cycles from the canister's main balance into a **reserved cycles balance** to cover future storage payments. + +- If subnet usage is **below 750 GiB**: reservation per byte = 0 (no advance reservation). +- If subnet usage is **above 750 GiB**: reservation per byte scales linearly from 0 up to 10 years of payments at subnet capacity (2 TiB). + +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 | +| 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: + +- **HTTPS outcalls** — See the [HTTPS outcalls cost formula](#https-outcalls) above. +- **Threshold ECDSA / Schnorr signing** — Charged per signing request. +- **Bitcoin integration API** — Per-call fees apply. +- **EVM RPC canister** — Costs depend on the external RPC call and the HTTPS outcall fees above. + +## 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 +- [Subnet types](subnet-types.md) — Cost multipliers per subnet type + + From cc8eade1e74d33e0411e013974fee0f6c285282f Mon Sep 17 00:00:00 2001 From: Raymond Khalife Date: Fri, 13 Mar 2026 15:18:17 -0400 Subject: [PATCH 2/2] docs: address review feedback on cycles-costs reference page --- docs/reference/cycles-costs.md | 41 +++++++++++++++++++--------------- 1 file changed, 23 insertions(+), 18 deletions(-) diff --git a/docs/reference/cycles-costs.md b/docs/reference/cycles-costs.md index 7ab64753..db7fc83b 100644 --- a/docs/reference/cycles-costs.md +++ b/docs/reference/cycles-costs.md @@ -3,7 +3,6 @@ title: "Cycles Costs" description: "Exact cycle costs for compute, storage, HTTPS outcalls, signing, and canister operations" sidebar: order: 6 -icskills: [] --- Canisters pay for the resources they consume and operations they perform using **cycles**. The price of cycles is pegged to [XDR](glossary.md) (Special Drawing Rights): **1 trillion cycles = 1 XDR**. As of May 22, 2025, 1 XDR ≈ $1.35 USD — this rate fluctuates; see the [IMF's XDR exchange data](https://www.imf.org/external/np/fin/data/rms_sdrv.aspx) for the current rate. @@ -30,13 +29,17 @@ See [Subnet types](subnet-types.md) for subnet-specific details. ## Cost table -| Operation | Description | Who pays | 13-node cycles | 13-node USD | 34-node cycles | 34-node USD | +USD values are approximate and based on the May 2025 XDR rate (1 XDR ≈ $1.35). The XDR rate fluctuates — use cycle counts for precise budgeting. + + + +| Operation | Description | Who pays | 13-node cycles | ~USD (May 2025) | 34-node cycles | ~USD (May 2025) | |-----------|-------------|----------|----------------|-------------|----------------|-------------| | Query call | Query information from a canister | N/A | Free | Free | Free | Free | | Canister creation | Create a new canister | Created canister | 500_000_000_000 | ~$0.677 | 1_307_692_307_692 | ~$1.772 | | Compute allocation (per % per second) | Reserved compute per second | Canister with allocation | 10_000_000 | ~$0.0000135 | 26_153_846 | ~$0.0000354 | -| Update message execution | Per update message executed | Target canister | 5_000_000 | ~$0.0000068 | 13_076_923 | ~$0.0000177 | -| 1B instructions executed | Per 1B Wasm instructions | Executing canister | 1_000_000_000 | ~$0.00135 | 2_615_384_615 | ~$0.00354 | +| Update message execution | Per update message executed (base fee) | Target canister | 5_000_000 | ~$0.0000068 | 13_076_923 | ~$0.0000177 | +| 1B instructions executed | Per 1B Wasm instructions (on top of base fee) | Executing canister | 1_000_000_000 | ~$0.00135 | 2_615_384_615 | ~$0.00354 | | Xnet call (request + response) | Inter-canister call overhead | Sending canister | 260_000 | ~$0.00000035 | 680_000 | ~$0.00000092 | | Xnet byte transmission | Per byte in inter-canister call | Sending canister | 1_000 | ~$0.00000000135 | 2_615 | ~$0.00000000354 | | Ingress message reception | Per ingress message received | Receiving canister | 1_200_000 | ~$0.0000016 | 3_138_461 | ~$0.0000043 | @@ -45,10 +48,10 @@ See [Subnet types](subnet-types.md) for subnet-specific details. **Storage cost per GiB per month (30 days):** -| Subnet | Cycles | USD | -|--------|--------|-----| -| 13-node | ~329B | ~$0.45 | -| 34-node | ~861B | ~$1.70 | +| Subnet | Cycles | ~USD (May 2025) | +|--------|--------|-----------------| +| 13-node | ~329 billion | ~$0.45 | +| 34-node | ~861 billion | ~$1.70 | ## HTTPS outcalls @@ -62,23 +65,23 @@ size_fee = (400 * request_bytes + 800 * max_response_bytes) * n `request_bytes` is the total serialized request size (URL + headers + body + transform name/context). `max_response_bytes` defaults to 2 MiB if not explicitly set by the canister. -| Component | 13-node cycles | 13-node USD | 34-node cycles | 34-node USD | -|-----------|----------------|-------------|----------------|-------------| +| Component | 13-node cycles | ~USD (May 2025) | 34-node cycles | ~USD (May 2025) | +|-----------|----------------|-----------------|----------------|-----------------| | Per call (base) | 49_140_000 | ~$0.0000666 | 171_360_000 | ~$0.000232 | | Per request byte | 5_200 | ~$0.000000007 | 13_600 | ~$0.0000000184 | | Per reserved response byte | 10_400 | ~$0.000000014 | 27_200 | ~$0.0000000369 | -## Execution costs +## Execution cost formula -Execution cost formula: +Each update message execution is charged as a base fee plus a per-instruction fee (the *Update message execution* and *1B instructions executed* rows in the Cost table above): ``` total = base_fee + per_instruction_fee * num_instructions ``` Current values (13-node subnet): -- `base_fee` = 5_000_000 cycles (~$0.0000068 USD) -- `per_instruction_fee` = 1 cycle (so 1B instructions = 1B cycles ≈ $0.00135) +- `base_fee` = 5_000_000 cycles (~$0.0000068 USD, May 2025) +- `per_instruction_fee` = 1 cycle (so 1B instructions = 1B cycles ≈ $0.00135, May 2025) ## Compute allocation @@ -88,7 +91,7 @@ By default canisters are scheduled best-effort. Setting `compute_allocation` gua - **2%** — Scheduled every 50 rounds - **100%** — Scheduled every round -Total allocatable compute capacity per subnet is 299%. The cost is `10M cycles * allocation_percent` per second on a 13-node subnet. +Total allocatable compute capacity per subnet is 299%. The per-second cost is `10M cycles * allocation_percent` on a 13-node subnet — see the *Compute allocation* row in the Cost table above for exact figures. ## Storage reservation @@ -125,9 +128,11 @@ Reserved cycles are non-transferable. Controllers can disable reservation by set Certain ICP features have additional cycle costs beyond the base execution and messaging fees: - **HTTPS outcalls** — See the [HTTPS outcalls cost formula](#https-outcalls) above. -- **Threshold ECDSA / Schnorr signing** — Charged per signing request. -- **Bitcoin integration API** — Per-call fees apply. -- **EVM RPC canister** — Costs depend on the external RPC call and the HTTPS outcall fees above. +- **EVM RPC canister** — Costs depend on the underlying RPC call and the HTTPS outcall fees above. +- **Threshold ECDSA / Schnorr signing** — Charged per signing request. Exact cost tables are not yet included on this page. +- **Bitcoin integration API** — Per-call fees apply. Exact cost tables are not yet included on this page. + + ## Related pages