Skip to content

docs: follow-ups on the HTTPS outcalls pricing pages - #398

Merged
marc0olo merged 2 commits into
mainfrom
docs/outcalls-pricing-followups
Sep 17, 2026
Merged

marc0olo merged 2 commits into
mainfrom
docs/outcalls-pricing-followups

Conversation

@marc0olo

@marc0olo marc0olo commented Sep 17, 2026

Copy link
Copy Markdown
Member

Summary

Follow-ups on #254. Wording and one table; no behavior change.

references/cycle-costs.md

  • The version 2 table carried only the base and delivery terms, so the usage fee was invisible to anyone pricing a call from it. Added rows for downloaded bytes, round-trip time and transform instructions, labeled each row with the part of the price it belongs to, and said which nodes pay them.
  • Said what the 13 dividing transform_instructions is: the reference subnet size the fees are calibrated against, not the node count.

guides/backends/https-outcalls.mdx

  • The PUT/DELETE/PATCH conditions move from the opening paragraph into a row of the modes table.
  • "Testing locally" now says that flexible outcalls do run locally, and what a local run does not exercise.
  • "Depends on the CDK" now names the wrapper: Motoko is a language purpose-built for ICP, not a CDK.
  • Added send_http_flexible to the upstream provenance comment.

concepts/https-outcalls.md

  • Replaced the paragraph that named the Rust builders and repeated the guide's Call.httpRequest warning with a pointer to the guide, which is where someone writing the call reads it.

Verification

  • Every figure in the version 2 table was re-derived from rs/https_outcalls/pricing/src/fees.rs at 4be965e1 (the replica elected by proposal 143907) and cross-checked against the six totals that file's own tests assert. The 34-node column is the same formulas at n = 34: http_request_fee_v2 adds no subnet-size scaling of its own. The rows are what a call settles at, not what ic0.cost_http_request_v2 reserves.
  • The method conditions in the modes table are the two validation sites in rs/types/types/src/canister_http.rs (DeterministicResponseCountRequired).
  • send_http_flexible was run on a local network with icp-cli 1.5.0 and returned all five responses it asked for.
  • npm run build passes.

@marc0olo
marc0olo force-pushed the docs/outcalls-pricing-followups branch 2 times, most recently from 17141ba to ff0bde4 Compare September 17, 2026 09:34
Wording and one table, no new behavior documented:

- the version 2 cost table carried only the base and delivery terms, so
  the usage fee was invisible to anyone pricing a call from it
- the 13 dividing transform_instructions is the reference subnet size the
  fees are calibrated against, not the node count
- the mutating-method rule belongs with the modes, not in the lead
- flexible outcalls do run on a local replica; say what a local run does
  not exercise
- Motoko is a language purpose-built for ICP, not a CDK
@marc0olo
marc0olo force-pushed the docs/outcalls-pricing-followups branch from ff0bde4 to cb8f82d Compare September 17, 2026 09:37
@marc0olo
marc0olo marked this pull request as ready for review September 17, 2026 10:05
@marc0olo
marc0olo requested a review from a team as a code owner September 17, 2026 10:05
Comment thread docs/references/cycle-costs.md Outdated
Comment thread docs/guides/backends/https-outcalls.mdx Outdated
- round-trip time does not dominate: it is capped at 234M cycles on a
  13-node subnet, while a maximal transform costs 5B and delivering a
  2MB response 19B
- drop the local node count from the flexible testing note; it read as a
  contradiction next to "the local replica runs a single node"
@marc0olo

Copy link
Copy Markdown
Member Author

Feedback addressed:

  • Round-trip time does not dominate. You are right, and by more than the comment claims: at 13 nodes round trip is capped at 60 s = 234M cycles, while a transform at the full 5B instruction limit costs ~5B and delivering a 2MB response ~19B. One delivered byte already costs 2.43 ms of round trip, so delivery outweighs round trip about tenfold even on a 1 KB, 500 ms call. Replaced the claim with the three ceilings.
  • The local node count. Dropped it. icp-cli's local network is PocketIC: one process, but its registry declares the application subnet with 13 nodes (subnet_size(Application) in rs/pocket_ic_server/src/pocket_ic.rs), so committee validation and cycle costs behave as on a 13-node subnet while that one process makes every request. Stating that next to "the local replica runs a single node" read as a contradiction, and it is local-tooling internals. The note now keeps only the part that affects a test: responses cannot disagree locally.

@marc0olo
marc0olo merged commit 370af6f into main Sep 17, 2026
8 checks passed
@marc0olo
marc0olo deleted the docs/outcalls-pricing-followups branch September 17, 2026 11:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants