Build & Release

This document covers the wallet’s release process: synchronized versioning, per-shell build pipelines, signing, packaging, and distribution channels.

Synchronized versioning

All packages in the repository ship at the same version number:

• package.json (root) — single source of truth
• packages/core/package.json
• packages/web/package.json
• packages/extension/package.json
• packages/desktop/package.json
• packages/bridge-spec/package.json
• packages/test-dapp/package.json
• e2e/package.json

Rationale: users running the web app, the extension, and the desktop app need an obvious way to confirm they’re on the same build. Every shell’s About screen surfaces its own package.json.version, so synchronized versions let users diff 1.0.0-rc.6-extension vs 1.0.0-rc.6-web vs 1.0.0-rc.6-desktop and immediately know they’re on the same codebase.

CHANGELOG.md at the repo root is authoritative; sub-packages don’t maintain their own changelogs.

Release bump procedure

1. Bump every package.json together
2. Update CHANGELOG.md — move [Unreleased] entries to the new version section with a date
3. Re-derive packages/extension/manifest.json’s version from the new wallet semver via packages/core/scripts/derive-extension-version.js; mirror the human-readable wallet semver into version_name
4. Run the smoke suite — pnpm --filter @xchain-wallet/core test — and verify the extension-manifest-audit smoke passes
5. Tag the commit v<version> and push

Extension version derivation

Chrome’s version field rejects semver prerelease tags like 1.0.0-rc.6. The wallet derives a Chrome-valid 1–4-tuple of integers 0–65535:

The leading 0 on prereleases pins them strictly below every stable tuple with M ≥ 1, so the CWS upgrade ordering stays monotonic across the RC → GA cut. Stable bumps are unchanged (1.2.3 → 1.2.3).

Per-shell build

All builds run with the workspace’s pnpm install --frozen-lockfile to lock dep versions to the shipped lockfile. Drift in transitive deps is the most common source of reproducibility failures; the frozen lockfile is the first line of defense.

Signing

Signing identities live with the publisher (Dankest, LLC). Independent verifiers reproduce the pre-signing Linux artifact and verify it matches the maintainer’s published RELEASE_HASHES.txt — see Reproducible Builds.

Distribution

Auto-update for desktop:

• electron-updater checks the feed at launch + on user-initiated “check for updates”
• New artifacts are downloaded in the background
• Signature verification runs before swap — the updater refuses to install an artifact whose signature doesn’t match the publisher key
• The user is prompted to install + restart; auto-apply is opt-in

Auto-update for the extension is handled entirely by the CWS — the wallet publishes a new build and the CWS pushes it to installed instances within ~24 hours. The wallet does not implement its own auto-update channel.

Chrome Web Store submission

The CWS submission packet lives in the platform repo (gitignored) at claude/reports/specs/2026-04-24_cws-submission.md. It covers:

• Build artifact + zip procedure
• Listing copy with verbatim strings
• Screenshot dimensions + capture procedure for the five required surfaces (Home, Send, Sign-screen, Multisig Receive, Settings → Security)
• Promo tile spec
• Privacy practices form answers
• Common rejection reasons + dry-run greps
• Single-purpose statement to paste
• Pre-submission smoke + audit run
• Post-approval automation roadmap
• Edge / Firefox variants

CWS submission is one of the three remaining user-driven items before v1.0.0 GA. The submitter (Dankest, LLC) hosts the privacy policy at a public URL — packages/extension/PRIVACY_POLICY.md is authored to be hosted as-is on either GitHub Pages or https://dankest.llc/xchain-wallet/privacy.

Release artifact list

A v1.0.0 GA release publishes:

Independent verifiers download the source tarball + the pre-signing Linux bundle + RELEASE_HASHES.txt, run the reproduce script in a Docker container, and verify the output bundle matches the manifest.

Pre-launch readiness gates

Before tagging v1.0.0 GA:

The first three pending items are user-driven and require external coordination; the fourth is a one-shot procedure run by the maintainer on a clean Docker host.

Release notes

Every release ships a CHANGELOG entry describing:

• The phase + step the release closes (e.g. “§56.3 Pre-launch — Step 5 of 7”)
• Added / Changed / Decided / Notes sections
• Why each decision was made — short, specific, audit-friendly

The “Decided” sections capture the reason a particular trade was made so a future reader (audit vendor, maintainer reviewing legacy decisions, downstream packager) can re-evaluate without rediscovering the alternatives.

Copyright © 2026 Dankest, LLC

Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-or-later). See LICENSE and NOTICE for full terms.