# Reproducible, attested release builds

MoonBite is maintained by a pseudonymous operator. That rules out the two
vendor identity schemes users are used to, Microsoft Authenticode and Apple
notarization, because both require a verified legal identity. Release trust
therefore 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 locally

Reproduce the Linux archive from the tagged commit on Ubuntu 22.04 (the runner
image), with the same toolchain versions. The simplest way is a container:

```bash
docker run --rm -it -v "$PWD:/src" -w /src ubuntu:22.04 bash
apt-get update && apt-get install -y build-essential libtool autotools-dev automake \
  pkg-config bsdmainutils curl git ca-certificates cmake python3 zip
export 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; the
claim is "the same inputs yield the same output", not "every machine yields
the same output". If the hash differs on the same image, extract both archives
and `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 entire
toolchain from pinned sources, which removes the GitHub runner image from the
trusted base entirely. It is the long-term target for all hosts, including the
Windows and macOS cross builds, and is what independent builders should use
when attesting a release. It is not run in CI yet because a full Guix build of
every 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.

```bash
HOSTS='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 pinned
commit `102f8acf90a7649ada410de5499a7ec62e49e1da`; a Guix descriptor must do
the 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 identities

Pseudonymity blocks Authenticode and notarization today. Options, in order of
how 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 on
MoonBite binaries are expected, and the verification steps above are the
substitute. Do not disable Gatekeeper or SmartScreen globally; verify, then
allow the single binary.