Skip to content

README.md

Latest commit

 

History

History
55 lines (32 loc) · 3.27 KB

README.md

File metadata and controls

55 lines (32 loc) · 3.27 KB
Raw

README

Upgrade proposal verification

Assume you want to verify a new upgrade proposal with code commit <COMMIT> and binary hash <HASH>.

  1. Install Docker (only once).
  2. git clone https://github.com/TaggrNetwork/taggr.git (only once)
  3. cd taggr
  4. git fetch --all && git checkout <COMMIT>
  5. make release
  6. Verify that the printed hash matches the <HASH> value from the release page.

make release runs the full validation pipeline (lints, Rust tests, Playwright e2e) inside a container and only produces a hash if everything passes. A failing release therefore cannot be hashed — the printed hash is a signal that the source passed validation and the production wasm was built by the reproducible release builder. Podman is used automatically if installed; otherwise Docker. Override with CONTAINER=docker make release.

The production wasm is always built in a linux/amd64 container so its hash matches Linux verifiers. On amd64 hosts this is a single container that runs tests then the production build. On non-amd64 hosts the e2e gate runs in a host-native container (TEST_PLATFORM, e.g. linux/arm64 on Apple Silicon — dfx/PocketIC don't tolerate qemu emulation), then the production wasm is built by a separate amd64 artifact container. The build is reproducible from a cold Cargo target via codegen-units = 1, lto = true, strip = true, panic = "abort" in Cargo.toml plus --remap-path-prefix in the Dockerfile, so the two-container path produces the same hash as the single-container path. Only taggr.wasm.gz is copied out via RELEASE_ARTIFACT_DIR; the Cargo target directory stays inside the container so macOS bind-mount semantics don't change the hash.

By default make release is quiet — only stage markers (==> [N/7] ...), the Playwright run, and the final hash print. To stream every underlying tool's stdout/stderr (cargo, dfx, npm, build.sh) for debugging, set VERBOSE=1:

VERBOSE=1 make release

Same flag works for make tests.

Outputs of a successful run:

  • release-artifacts/taggr.wasm.gz — the production wasm.
  • test-results/ and playwright-report/ — Playwright traces and the HTML report (open playwright-report/index.html to inspect any failures).

Note: the first run is slow (Chromium install layer is several hundred MB) and dfx nns install downloads the NNS canisters on every run.

Release proposal

To propose a release, follow the steps above first. If they were successful, you'll find a binary taggr.wasm.gz in the release-artifacts directory. Use the printed code commit and the binary to submit a new release proposal.

Running tests during development

For day-to-day iteration, skip the prod build and just run the test suite:

make tests

Same image as make release and the same checks (lints, Rust tests, Playwright e2e), but stops before the deterministic prod build. Use this while iterating; use make release when you actually want a hash.

Backups

Make sure you have installed cargo.

To create a backup of the Taggr state, run:

make backup DIR=/path/to/backup

Local development and contributions

Refer to the local development docs for instructions on how to work with Taggr locally.