docs: expand cycle-costs reference with Threshold cryptography and Chain integrations sections#272
Open
marc0olo wants to merge 9 commits into
Open
docs: expand cycle-costs reference with Threshold cryptography and Chain integrations sections#272marc0olo wants to merge 9 commits into
marc0olo wants to merge 9 commits into
Conversation
…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.
|
🤖 Here's your preview: https://uc7il-jaaaa-aaaam-ai2gq-cai.icp0.io |
- 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)
marc0olo
changed the title
… 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
marc0olo
changed the title
Member
Author
|
Feedback addressed:
|
- 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)
Replace "onchain"/"on-chain" with specific attributes (on the network, canister code, network-enforced, etc.) and "decentralized" with precise alternatives (distributed, community-governed, governed by the NNS) across 27 concept, guide, and reference pages. Domain exceptions kept for DeFi/MEV context and governance API identifiers per brand voice rules.
Member
Author
|
Brand voice and Diataxis pass applied across 27 pages:
|
Use offchain/crosschain (no hyphen) consistently, matching tamperproof style. Replace "tokenize your application" in choose-your-path.md with precise language: "issue a governance token and transfer control".
github-actions
Bot
added
the
interface-spec
…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
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 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
1 participant
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
## Threshold cryptography(threshold ECDSA/Schnorr signing, VetKeys) and## External integrations(HTTPS outcalls, EVM RPC canister, SOL RPC canister, Bitcoin, Dogecoin) — threshold signing is a core ICP protocol capability, not an external integration; HTTPS outcalls are generic HTTP calls, not chain-specificdfinity/dogecoin-canisterinterface/src/lib.rs)dfinity/sol-rpc-canistersourcesystem-canisters.md(CMC section): Candid signature,xdr_permyriad_per_icpunit semantics, and Prometheus metrics tableconcepts/cycles.md: replaces messaging cost table with prose + link to the reference; splits single "Protocol integrations" bullet and paragraph into separate "Threshold cryptography" and "External integrations" entries, each linking to the corresponding reference sectionethereum.mdx; corrects stale collateral figure to the current formula; adds link to the cycle costs referencesolana.mdxoffchain,crosschainthroughoutReview guidance
Most of the diff is mechanical brand voice changes (commits
9e655a8and5662531) touching 34 files with 1–3 line changes each — word substitutions only, no semantic changes. You can skip or skim those.Focus review on these files and topics:
docs/references/cycle-costs.mddocs/concepts/cycles.mddocs/references/system-canisters.mdxdr_permyriad_per_icpsemantics, Prometheus tabledocs/guides/chain-fusion/ethereum.mdxEVM RPC collateral is the most important factual change in this PR. The original text said collateral cycles "are currently refunded in full", which was wrong. The source (
canhttp/canhttp/src/cycles/mod.rs,msg_cycles_accept(request_cost + collateral)) shows the collateral is accepted and consumed. A second pair of eyes on the corrected wording is welcome.Cross-linking structure
concepts/cycles.md→references/cycle-costs.md#threshold-cryptographyconcepts/cycles.md→references/cycle-costs.md#external-integrationsconcepts/cycles.md→references/cycle-costs.md#cost-tablereferences/system-canisters.md(CMC) →references/cycle-costs.md#getting-the-current-xdrusd-rateconcepts/chain-fusion/exchange-rate-canister.md→references/system-canisters.md#cycles-minting-canister-cmcguides/chain-fusion/ethereum.mdx→references/cycle-costs.md#evm-rpc-canisterguides/chain-fusion/solana.mdx→references/cycle-costs.md#sol-rpc-canisterAccuracy verification
All cycle numbers verified against upstream source:
docs/references/bitcoin-how-it-works.mdx,docs/references/t-sigs-how-it-works.mdx,docs/building-apps/chain-fusion/ethereum/evm-rpc/costs.mdx,docs/building-apps/network-features/vetkeys/api.mdxdfinity/dogecoin-canisterinterface/src/lib.rs(Fees::mainnet())dfinity/sol-rpc-canistercanister/src/constants.rs,canister/src/memory/mod.rs,canister/src/http/mod.rscanhttp/canhttp/src/cycles/mod.rs—msg_cycles_accept(request_cost + collateral)confirms collateral is consumed, not returnedicp-cli/crates/icp-canister-interfaces/src/cycles_minting_canister.rs; metrics endpoint verified live/api/v3/icp-usd-rateand/api/v3/icp-xdr-conversion-ratesverified liveSync recommendation
docs/references/cycle-costs.md: hand-written (informed by multiple upstream sources listed in theUpstreamcomment)