git / moonbite-core / doc/reproducible-builds.md · raw

# Reproducible, attested release buildsMoonBite is maintained by a pseudonymous operator. That rules out the twovendor identity schemes users are used to, Microsoft Authenticode and Applenotarization, because both require a verified legal identity. Release trusttherefore rests on evidence anyone can check rather than on a certificate:1. **Deterministic builds.** `.github/workflows/release.yml` builds with   `SOURCE_DATE_EPOCH` taken from the commit timestamp, `-ffile-prefix-map`   so the checkout path never enters the binary, `strip -D` / `ranlib -D`   (deterministic archives), and archives written with sorted members, fixed   mtimes, `uid/gid 0` and `TZ=UTC` (`gzip -n` for tarballs, `zip -X` with a   sorted member list for the Windows zip).2. **Rebuild-and-compare.** The Linux target is built twice, on two separate   runner VMs, and the `reproducibility` job fails the release if the two   `moonbite-miner-linux-x86_64.tar.gz` hashes differ. A release cannot be   published on a build that did not reproduce.3. **Sigstore attestation (SLSA provenance).** `actions/attest-build-provenance`   signs a provenance statement for every asset and `SHA256SUMS.txt`, bound to   this repository, workflow file, tag and commit. Verify with   `gh attestation verify <file> --owner moonbitecoin`.4. **minisign (optional until the key ceremony).** When the `MINISIGN_SECRET_KEY`   secret exists the manifest is signed and `SHA256SUMS.txt.minisig` is   attached; otherwise the step is skipped with a notice. The public key lives   in `moonbite-network/deploy/moonbite-release.pub` (placeholder until the   ceremony in `deploy/RELEASE-SIGNING.md` is done).## Rebuilding locallyReproduce the Linux archive from the tagged commit on Ubuntu 22.04 (the runnerimage), with the same toolchain versions. The simplest way is a container:```bashdocker run --rm -it -v "$PWD:/src" -w /src ubuntu:22.04 bashapt-get update && apt-get install -y build-essential libtool autotools-dev automake \  pkg-config bsdmainutils curl git ca-certificates cmake python3 zipexport TZ=UTC LC_ALL=C SOURCE_DATE_EPOCH="$(git log -1 --pretty=%ct)"# Then run the "Build RandomX", "Build depends", "Configure and build node" and# "Assemble bundle" steps from .github/workflows/release.yml verbatim, with# GITHUB_WORKSPACE=/src and BUILD_PREFIX_MAP_TO=/build/moonbite.sha256sum moonbite-miner-linux-x86_64.tar.gz   # compare with SHA256SUMS.txt```A different compiler version will legitimately produce a different hash; theclaim is "the same inputs yield the same output", not "every machine yieldsthe same output". If the hash differs on the same image, extract both archivesand `sha256sum` each member to localise the divergence, then open an issue.## Guix: the gold-standard path`contrib/guix/` (inherited from Litecoin / Bitcoin Core) builds the entiretoolchain from pinned sources, which removes the GitHub runner image from thetrusted base entirely. It is the long-term target for all hosts, including theWindows and macOS cross builds, and is what independent builders should usewhen attesting a release. It is not run in CI yet because a full Guix build ofevery host takes many hours and needs a persistent builder with a Guix store;the `guix` job in `release.yml` is a disabled stub marking where it plugs in.```bashHOSTS='x86_64-linux-gnu x86_64-w64-mingw32' ./contrib/guix/guix-build.sh```Note that the RandomX library is rebuilt in the workflow from the pinnedcommit `102f8acf90a7649ada410de5499a7ec62e49e1da`; a Guix descriptor must dothe same so the proof-of-work code is covered by the reproducibility claim.## What the attestation proves, and what it does not- Proves: the asset with this exact digest was produced by the named workflow  in `moonbitecoin/moonbite-core` from the named commit, and the statement was  signed via GitHub's OIDC identity and logged in the public Sigstore  transparency log. An attacker who swaps the asset on the release page cannot  produce a matching attestation without controlling the repository's Actions.- Does not prove: that the source at that commit is honest, that GitHub itself  is honest, or that the runner image was uncompromised. Reproducibility  (anyone rebuilding and matching) and public code review cover the first; Guix  bootstrapping is the mitigation for the last.## Roadmap for vendor identitiesPseudonymity blocks Authenticode and notarization today. Options, in order ofhow little identity they demand:- **SignPath Foundation** offers free code signing to open-source projects  through its own certificate; the project, not the individual, is vetted.- **Azure Trusted Signing** requires an organisation with a verifiable  identity; feasible once a legal entity exists.- **Forming an entity** (foundation or company) that holds the certificates  and the Apple developer account on behalf of the project.Until one of these lands, Windows SmartScreen and macOS Gatekeeper warnings onMoonBite binaries are expected, and the verification steps above are thesubstitute. Do not disable Gatekeeper or SmartScreen globally; verify, thenallow the single binary.