docs: reproducible builds guide

[marc0olo]

Summary

• Explains the trust model: ICP exposes only the SHA-256 Wasm hash; reproducible builds let users verify source matches deployment
• How to obtain the deployed hash with icp canister status --public
• Requirements: source publication, environment documentation, deterministic build instructions
• Dependency pinning: cargo build --locked, npm ci
• Sources of non-determinism to avoid; --remap-path-prefix for Rust path-independent builds
• Docker-based reproducible build environment with complete Dockerfile example
• Deploying verified prebuilt Wasm with @dfinity/prebuilt@v2.0.0 recipe and SHA-256 verification
• Testing reproducibility with reprotest
• Long-term considerations: toolchain archival, URL pinning

Sync recommendation

informed by portal building-apps/best-practices/reproducible-builds.mdx and icp-cli-recipes prebuilt recipe

[marc0olo]

Review: Reproducible Builds

Must fix

• Internal links use .mdx extension: Lines 264–265 in the "Next steps" section link to lifecycle.mdx and settings.mdx. Per project rules, internal links must always use the .md extension even when the target file is .mdx — Astro resolves both. These should read lifecycle.md and settings.md.

• Incorrect build artifact path in reprotest example: Line 244 uses .icp/cache/build/*/*.wasm as the reprotest output path pattern. The actual directory per .sources/icp-cli/docs/concepts/project-model.md is .icp/cache/artifacts/ (not .icp/cache/build/). The correct glob would be .icp/cache/artifacts/*.wasm or similar. This would cause the reprotest command to silently find no files, giving a false "reproduction successful" result.

Suggestions

• --public flag description could be more precise: Lines 34–40 say "Anyone can query this hash — no controller access is required when using the -p / --public flag". The CLI reference states that icp canister status already falls back to public state tree information if the caller is not a controller. The --public flag explicitly forces public-only lookup rather than being the only way to query without controller access. Consider clarifying: "no controller access is required — use -p / --public to explicitly read only public information from the state tree".

• Dockerfile uses very old Rust version: The example Dockerfile pins RUST_VERSION=1.62.0 (released July 2022). While old versions are valid for illustrating the pinning concept, a reader following this example would build canisters with a three-year-old compiler that lacks modern Rust features and security fixes. Consider updating the example to a more recent stable release, or adding a note that readers should substitute the current stable version for their project.

• Link text mismatch for security page: Line 24 links to ../../concepts/security.md with text "Canister security concepts", but the target page's title is "Security Model". This is not a broken link, but the link text does not match the actual page title, which could briefly confuse readers navigating between pages.

Verified

• All internal link targets confirmed to exist: ../../concepts/security.md exists; lifecycle.mdx, settings.mdx, cycles-management.md all exist in docs/guides/canister-management/. The .mdx extension issue in link text is flagged above, but the target files themselves exist.
• All icp canister status commands verified against .sources/icp-cli/docs/reference/cli.md: command syntax correct, -n ic is valid when targeting by principal, -p/--public flag exists and is correctly described.
• icp build command verified against .sources/icp-cli/docs/reference/cli.md: command exists and syntax is correct.
• No dfx references found.
• No banned URLs (internetcomputer.org/docs, docs.internetcomputer.org) found.
• No <\!-- TODO: verify output --> or <\!-- Needs human verification: --> flags present.
• Frontmatter is complete and valid (title, description, sidebar.order).
• prebuilt recipe parameters verified against .sources/icp-cli-recipes/recipes/prebuilt/README.md and recipe.hbs: path, sha256, shrink, compress, metadata all correctly documented. The sha256 field is optional (not required), matching the page's parameter table.
• --locked Cargo flag usage is correct in the context of manual build scripts.
• cargo build --locked --target wasm32-unknown-unknown --release syntax is correct.
• --remap-path-prefix RUSTFLAGS usage is consistent with Rust documentation.
• npm ci recommendation (vs npm install) for reproducibility is correct.
• sha256sum command for computing WASM hash is correct.
• <\!-- Upstream: --> comment is present at the bottom of the page as required.
• Page follows Diataxis "how-to guide" structure appropriately.
• Content is .md (not .mdx) — correct since no interactive components are needed.
• ic-wasm inclusion in Dockerfile is accurate: required for shrink operations.
• No inline code snippets exceed 30 lines.

[marc0olo]

Feedback addressed:

• Fixed .mdx → .md extension in lifecycle.mdx and settings.mdx internal links in the Next steps section
• Fixed build artifact path: .icp/cache/build/ → .icp/cache/artifacts/ in reprotest command and sha256sum example
• Clarified --public flag description to separate the general claim from the flag-specific guidance
• Updated Dockerfile Rust version from 1.62.0 (2022) to 1.82.0
• Fixed link text "Canister security concepts" → "Security Model" to match the target page's actual title