docs: expand cycle-costs reference with Threshold cryptography and External integrations sections#272
Open
marc0olo wants to merge 8 commits into
Open
docs: expand cycle-costs reference with Threshold cryptography and External integrations sections#272marc0olo wants to merge 8 commits into
marc0olo wants to merge 8 commits into
Conversation
|
🤖 Here's your preview: https://uc7il-jaaaa-aaaam-ai2gq-cai.icp0.io |
marc0olo
changed the title
marc0olo
changed the title
github-actions
Bot
added
the
interface-spec
marc0olo
changed the title
Member
Author
|
@Dfinity-Bjoern sorry for the noise in his PR. some icp brand voice changes were also applied in between and I didn't want to revert those along the way. please focus on the Review guidance in the PR summary. the rest is just cosmetics. following pages are relevant in the preview deployment:
|
This was referenced May 26, 2026
mraszyk
approved these changes
May 27, 2026
Contributor
mraszyk
left a comment
mraszyk
left a comment
There was a problem hiding this comment.
Approving the one-line change in docs/references/ic-interface-spec/management-canister.md
marc0olo
force-pushed
the
docs/cycle-costs-special-features
branch
from
490f44d to
e016589
Compare
marc0olo
added a commit
that referenced
this pull request
May 27, 2026
…guage (#277) ## Summary - Replaces `onchain`/`on-chain` with precise attribute language (e.g. \"runs on the network\", \"canister code\", \"network-enforced\") across 26 pages. Domain exceptions retained for DeFi/MEV context and governance API identifiers per brand voice rules. - Normalizes compound terms to no-hyphen style consistent with `tamperproof`: `offchain`, `crosschain`. Replaces \"tokenize your application\" with \"issue a governance asset and transfer control\". - Retains `decentralized` in governance/trust contexts where it describes no-single-party control (not a marketing claim). Replaces `distributed` back to `decentralized` where the PR had incorrectly substituted it. - Renames `onchain-ai` page to `ai-inference`; updates title and internal links. - Fixes Motion proposal description: replaces \"no direct network effect\" with \"Non-binding vote\". - Replaces `Onchain encryption` heading with `Encryption` in chain-key-cryptography concept page. - Applies review suggestions: `DAO-governed` → `Community-governed`, `token holders` → `asset holders`, `offchain systems` → `external systems`, `offchain dependencies` → `external dependencies`, `network oracle` → descriptive system service label, `Offchain availability` → `Availability` / `client-side` in the IC interface spec. 28 files changed, 42 insertions, 42 deletions. ## Why a separate PR These changes were originally part of #272. Splitting them out so reviewers can focus on the structural content changes in #272 without terminology noise. **Merge this PR first. Once merged, #272 will be rebased on top of it and the two terminology commits removed from that branch.** ## Sync recommendation hand-written
…d Bitcoin API costs The Special features section was a stub with TODO comments for threshold signing and Bitcoin API. Adds complete cost tables for all four feature categories, verified against portal source material. - Threshold ECDSA / Schnorr signing: cost table by key name (test_key_1 and key_1), with note that cost is determined by the signing subnet - VetKeys (vetkd_derive_key): same cost structure, same subnet layout - EVM RPC canister: full cost formula plus collateral cycles requirement and worked example - Bitcoin API: testnet and mainnet tables with base cost, minimum cycles to attach, and USD column; two-tier pricing model explained in prose Also fixes the chain-key-cryptography.md link to point to the specific #threshold-ecdsa-and-schnorr-signing anchor, and adds a cross-reference from vetkeys.md to the cycle-costs reference.
- Remove dead-end HTTPS outcalls subsection under Special features - Split Bitcoin API USD column into base cost and min-to-attach columns - Fix EVM RPC description: formula uses different constants from HTTPS outcalls - Add subnet IDs to ECDSA/Schnorr signing table (consistency with VetKeys) - Add back-link from Bitcoin guide inline table to cycle-costs reference - Update XDR rate May 2025 ($1.354820) -> May 2026 ($1.366430) across cycle-costs.md, subnet-types.md, and concepts/cycles.md - Fix 34-node storage/month: was incorrectly $1.70, correct value is $1.18 (861B cycles * $1.366430/T = $1.18, not $1.70)
… and new chain API tables - Rename "Special features" to "Protocol integrations" and move HTTPS outcalls inside it as first subsection (all four integration types now grouped together) - Add dedicated XDR exchange rate section (May 22, 2026: 1 XDR = $1.366430 USD); remove month/year suffixes from all column headers - Add Dogecoin integration API cost table (mainnet-only, costs verified against dfinity/dogecoin-canister interface/src/lib.rs; identical to Bitcoin Mainnet tier) - Add SOL RPC canister section with pricing formula (standard HTTPS outcall + 10_000_000 cycles × n per-node processing fee × rpc_providers), verified against dfinity/sol-rpc-canister constants.rs and http/mod.rs; reference getBalanceCyclesCost and sibling query methods for per-call estimates - Update upstream comment to include dogecoin-canister and sol-rpc-canister source files
- cycle-costs.md: expand XDR exchange rate section with CMC mechanics (5-minute XRC sampling, get_icp_xdr_conversion_rate returns ICP/XDR not XDR/USD), three machine-readable methods to derive XDR/USD (ICP dashboard API derivation formula, CMC metrics endpoint, on-chain XRC+CMC pattern) - system-canisters.md: add "Querying the current ICP/XDR rate" subsection under CMC — documents get_icp_xdr_conversion_rate Candid signature, xdr_permyriad_per_icp unit semantics, and Prometheus metrics fields (cmc_icp_xdr_conversion_rate, cmc_avg_icp_xdr_conversion_rate, cmc_cycles_per_xdr); cross-links to cycle-costs#getting-the-current-xdrusd-rate - cycles.md: add sentence pointing to cycle-costs for programmatic rate lookup, and note that CMC samples from XRC every 5 minutes - exchange-rate-canister.md: clarify CMC is the XRC's primary consumer (calls every 5 minutes for ICP/XDR to use in cycle minting)
…pages - concepts/cycles.md: replace messaging cost table with prose + link to cycle-costs.md; strip USD values from storage/canister creation numbers - guides/chain-fusion/ethereum.mdx: remove duplicated EVM RPC formula, fix stale collateral cycles figure (0.00028 TC → 10_000_000 * nodes * rpc_services), link to cycle-costs.md#evm-rpc-canister for the full spec - guides/chain-fusion/solana.mdx: add link to cycle-costs.md#sol-rpc-canister - guides/canister-management/cycles-management.mdx: replace "Onchain" with "Network-based" in CycleOps description
…in integrations - Splits `## Protocol integrations` in cycle-costs.md into two sections: `## Threshold cryptography` (threshold ECDSA/Schnorr, VetKeys) and `## Chain integrations` (HTTPS outcalls, EVM RPC, SOL RPC, Bitcoin, Dogecoin) - Reorders sections for Diataxis: Cycle units → Replication factors → Cost table → formulas → Threshold cryptography → Chain integrations → XDR rate - Reorders chain integrations by pricing mechanism: HTTPS outcalls (base primitive) → EVM RPC → SOL RPC (HTTPS-outcall-based) → Bitcoin → Dogecoin (two-tier model) - Corrects EVM RPC collateral: consumed by the canister, not refunded; adds note that sending above the minimum is safe - Renames "Cycles units" → "Cycle units"; moves XDR rate section to end; embeds current rate inline in the intro - Fixes "On-chain (certified, from a canister)" → "From canister code (certified)" in the XDR rate section - Fixes "specialized subnets" description to accurately describe the mechanism - Updates concepts/cycles.md: replaces messaging cost table with prose + link; replaces single "Protocol integrations" bullet and paragraph with separate "Threshold cryptography" and "Chain integrations" entries, each linking to the corresponding reference section - Removes duplicate EVM RPC formula from ethereum.mdx; corrects stale collateral figure to the current formula
marc0olo
force-pushed
the
docs/cycle-costs-special-features
branch
from
e016589 to
94cb11b
Compare
marc0olo
changed the title
Member
Author
|
The brand voice / terminology changes mentioned in my earlier comment have been split into a separate PR (#277) and merged. This PR now contains only the substantive cycle costs changes described in the Review guidance section. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Expands
docs/references/cycle-costs.mdwith four previously-stub cost entries and restructures the page into two named sections:Applies a Diataxis pass to
concepts/cycles.md(prose replaces the cost table, links to the new sections) and adds an XDR rate query subsection tosystem-canisters.md.Review guidance
docs/references/cycle-costs.mddocs/concepts/cycles.mddocs/references/system-canisters.mdxdr_permyriad_per_icpsemantics, Prometheus tabledocs/guides/chain-fusion/ethereum.mdxKey factual correction: the original text said EVM RPC collateral cycles "are currently refunded in full" — that's wrong. Tracing through
canhttp/src/cycles/mod.rsshowsmsg_cycles_accept(request_cost + collateral), meaning collateral is consumed. A second pair of eyes on the corrected wording is welcome.Sync recommendation
docs/references/cycle-costs.md: hand-written (informed by multiple upstream sources listed in theUpstreamcomment)