chore: sync static-site docs to dfinity/certified-assets 853c291 - #409
Merged
Merged
Conversation
pr-automation-bot-public
Bot
requested a review
from a team
as a code owner
September 25, 2026 14:13
marc0olo
approved these changes
Sep 25, 2026
marc0olo
added a commit
that referenced
this pull request
Sep 28, 2026
## Summary Both certification guides had claims that are wrong on current releases. Every claim was checked against primary sources (the crates, `@icp-sdk/core` 6.1.0, ic-gateway, the interface spec, icp-cli v1.5.0 `cli.md`), and every code block was compiled and run against a local network. The skill side of the same fixes is dfinity/icskills#407. **Wrong, now fixed:** - **"Certified data is cleared on upgrade"** (5 places): it survives upgrades (`abstract-behavior.md`, confirmed locally). What is lost is a heap tree, so Rust rebuilds it in `post_upgrade`, and Motoko's `CertTree.Store` needs no hook. - **Header name:** `IC-Certificate-Expression` is really `IC-CertificateExpression` (gateway spec, crate constant, served headers). - **`icp canister call … get` without `--query`:** icp-cli sends an update call by default, so no certificate comes back. - **Client verification code:** it did not type-check against `@dfinity/certificate-verification` 4 (`Uint8Array`, not `ArrayBuffer`). `lookupResultToBuffer` treated `Unknown` as absent; it now switches on the `lookup_path` status. It also accepts bindgen's `undefined` for an empty `opt` field, which it rejected as a false "key is absent" failure. - **The "custom HTTP client" case** needs `@dfinity/response-verification`, not `certificate-verification`. This is now a "who verifies what" table (HTTP gateway, update calls, Candid queries, raw hosts). - **The `ic-asset-certification` example did not compile** (missing `candid`, `404` needs `StatusCode`). Its uncertified 404 was rejected by the gateway; it now uses a certified `404.html` fallback. - **Rust example:** it lacked `export_candid!()`, so `icp deploy` failed. It now uses `ic-certification` 4 / `ic-cdk` 0.20. - **The single-value Motoko example never certified its initial value**, so a query before the first write failed verification (certified data starts empty). - **Motoko `CertTree` example did not compile** (`CertTree.Ops` must be `transient`). The deprecated `postupgrade` hook is removed, and `remove` becomes `delete` to match the test commands. - **`allow_raw_access: false`:** redirects with `308`, but `raw.icp.net` lands on `<id>.icp0.io`, and only mainnet raw hosts are recognized. - **Asset canister certified headers:** also `Cache-Control` (with `max_age`) and `Content-Encoding`. - **"Boundary node" wording:** the intro linked the API boundary nodes, which verify nothing; both pages now say the HTTP gateway. - **Root key:** `shouldFetchRootKey` is replaced by the `ic_env` cookie / `icp network status --json`. - **Links:** the `js.icp.build` link is dropped (that site does not document this package), and `certified-counter` (dfx, `fetchRootKey`) is replaced by `motoko/cert-var`. **After review:** - The gateway guarantee is scoped to verifying hostnames. - The two certification headers are described accurately (certificate and witness vs CEL expression). - `certified_data_set` is described as allowed in every replicated context, per the spec. - The raw-host row now says the gateway forwards the certificate without checking it. The synced `static-site/how-it-works.md` has the same wording; it is fixed upstream in dfinity/certified-assets#139 and already synced to `main` in #409. **Structural note:** the asset and Rust examples stay inline even though they exceed the 30-line guideline, as before. They could move to `dfinity/examples` with `#region` markers.
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
Automated sync of the certified-assets user docs.
Ref:
853c291(pinned fromv0.4.0), dispatched by hand as853c291.A ref is synced by hand when a docs fix has shipped upstream but not
been released; the next release moves the pin back onto a tag.
Changed upstream files:
docs/how-it-works.mdRan
npm run sync:static-site, regeneratingdocs/guides/frontends/static-site/Validator and build passed
Checklist
certification.md,asset-canister.md)icp.yamlexamples needs bumping with it