Hacktoberfest 2026：维护者为十月标记出来的 issue，仍然开放、适合新手。 浏览 Hacktoberfest issue

docs: cycle cost docs follow-up — ICP formula, worked example, instruction profiling, cost traps

未关闭
  • 哪里不对？
#274 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 1 天内回复

还没有人认领这个 Issue。

评估

难度
4/5
预计耗时
3-5 天
新手友好度
68/100
Issue 类型
文档
描述清晰度
描述清楚
活跃度
冷清
技术栈
markdown, rust
领域
documentation

调研方向

首先阅读 docs/references/cycle-costs.md、docs/guides/canister-management/cycles-management.mdx 和 docs/guides/canister-management/optimization.md 中现有的相关章节。在记录 ICP 公式、完整的成本示例、性能计数器、max_response_bytes 警告、freezing threshold 计算方式和计算器说明之前，检查上下文中的术语和现有链接。完成的标准是：在不新增文件、不进行结构性更改且不修改侧边栏的情况下，涵盖全部六处缺口。

由索引模型根据 Issue 内容生成。

描述

Follow-up to #272.

After reviewing the cycle cost documentation restructured in #272, the following gaps remain. All are additive changes to existing pages — no new files, no structural changes, no sidebar edits.

Gap 1: The "how much ICP to buy" formula is never written out

The cycle→XDR→ICP conversion chain is documented in pieces but never assembled. A developer cannot answer "I need 5T cycles — how much ICP do I buy?" without reading three separate sections.

Proposed fix: Add a concise formula + worked example in docs/guides/canister-management/cycles-management.mdx immediately after the budget guidance sentence:

icp_needed = (cycles_needed / 1_000_000_000_000) / (xdr_permyriad_per_icp / 10_000)

Example: need 5T cycles, CMC returns xdr_permyriad_per_icp = 19482 → 1 ICP = 1.9482 XDR → 5 / 1.9482 ≈ 2.57 ICP to purchase.

Gap 2: No worked cost estimation example

All per-operation numbers exist in docs/references/cycle-costs.md but there is no example that combines them. A developer with a canister using HTTPS outcalls + threshold signing + storage + compute cannot find a single synthesized monthly cost estimate.

Proposed fix: Add a "Worked example" section to docs/references/cycle-costs.md — e.g. a canister making 1,000 HTTPS outcalls/day, 10 ECDSA signatures/day, storing 500 MiB, executing 100M instructions/call × 50 calls/day — that walks through each cost line and arrives at a monthly cycle total and ICP purchase estimate.

Gap 3: Instruction count is impossible to estimate before deployment

The docs state "1B instructions = 1B cycles" but do not explain how to measure the instruction count of a canister call. performance_counter() (the Wasm instruction counter available via ic0.performance_counter(0)) is not mentioned anywhere.

Proposed fix: Add a "Measuring instruction counts" paragraph to docs/guides/canister-management/optimization.md showing ic0.performance_counter(0) in Rust (ic_cdk::api::performance_counter(0)) and the equivalent in Motoko (Prim.performanceCounter(0)), with a note that sampling before/after a block gives the instruction cost of that block.

Gap 4: HTTPS outcall max_response_bytes default is a silent cost trap

If max_response_bytes is not set it defaults to 2 MiB. On a 34-node subnet: 2_097_152 × 27_200 cycles/byte ≈ 57B cycles per call regardless of actual response size — even for a 200-byte response. This is not flagged as dangerous anywhere in the cost docs.

Proposed fix: Add a warning callout in the HTTPS outcalls section of docs/references/cycle-costs.md:

Always set max_response_bytes explicitly. The default (2 MiB) charges for the full reserved size even if the actual response is 1 KB. On a 34-node subnet that is approximately 57B cycles per call.

Gap 5: Freezing threshold and burn rate are never connected

The cycles-management guide recommends "90 days for production" but never explains that this requires estimated_daily_burn × threshold_days in cycle reserves. A developer setting a 90-day threshold on a canister burning 5B cycles/day needs 450B cycles reserved — this is non-obvious.

Proposed fix: Add a formula immediately below the freezing threshold section in docs/guides/canister-management/cycles-management.mdx:

required_balance ≥ estimated_daily_burn × threshold_days

Example: 5B cycles/day × 90 days = 450B cycles minimum balance before the threshold triggers.

Gap 6: Pricing calculator is mentioned without explanation

https://3d5wy-5aaaa-aaaag-qkhsq-cai.icp0.io/ is linked once with no description of inputs or how to interpret results. It should either get a one-sentence description or be promoted more visibly from cycles-management.mdx.

Files to change

File Changes
docs/references/cycle-costs.md Gap 2 (worked example) + Gap 4 (max_response_bytes warning)
docs/guides/canister-management/cycles-management.mdx Gap 1 (ICP formula) + Gap 5 (burn rate formula) + Gap 6 (calculator description)
docs/guides/canister-management/optimization.md Gap 3 (performance_counter guidance)
主要语言
JavaScript
星标
4
派生
5
平均合并
21 小时 49 分钟
30 天内合并 PR
28

环境准备

  • 没有 Dockerfile 或 Docker Compose 文件
  • 没有 Pull Request 模板
  • 阅读贡献指南

从这里开始

  1. 先读完整个 Issue，再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库，在一个分支上完成修改。
  4. 提交 Pull Request，并在描述里引用这个 Issue 编号。

dfinity/developer-docs 的其他 Issue

查看 dfinity/developer-docs 的全部 Issue

相似的 Issue

更多 JavaScript Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。