System XLS: Reproducible Release Attestations

[dangell7]

  title: Reproducible Release Attestations
  description: Rebuilders attest xrpld release hashes on the XRP Ledger, and the node verifies a package against the operator's trust policy before install.
  author: Denis Angell (@dangell7) 
  category: System
  status: Proposal
  proposal-from: https://github.com/XRPLF/XRPL-Standards/discussions/235
  created: 2026-10-10
  updated: 2026-10-11

Reproducible Release Attestations

1. Abstract

An operator installing an xrpld package today trusts whoever built and served it. This XLS removes
that trust in three parts. First, a release MUST build byte-for-byte reproducibly from its public
commit. Second, rebuilders who reproduce a release attest the hash of its SHA256SUMS on the XRP
Ledger, each as a Credential it issues to itself, and accreditors such as XRPLF vouch for which
accounts are rebuilders with a Credential issued to each. Third, before a package is installed,
the operator's running node checks it against the rebuilders or accreditors the operator trusts and
a threshold the operator sets, the way a node already trusts a UNL and a quorum. No amendment is
required: Credentials is enabled on Mainnet.

2. Motivation

The only checks available to an operator today are the package repository's GPG signature and the
hashes published in release posts. Both come from the party that built the binary, so both prove
who shipped it, not what source it came from. A compromised CI runner, signing key, package host or
CDN can ship a binary that passes both.

Release 3.4.1 shows both the gap and how close xrpld already is. xrpld_3.4.1-1 was built from a
commit in a private repository: the binary embeds the source path
/__w/xrpld-private/xrpld-private/. Operators upgraded with no way to check it against any source.
xrpld_3.4.1-2 was later built from public tag 3.4.1. The two commits differ only in one CI
workflow line, yet the two binaries differ, because the build path and the commit hash are compiled
into the bytes. Rebuilding each commit in CI's container image at CI's checkout path reproduces each
shipped package byte for byte, debug symbols included. So the build is already deterministic. What
stops an operator verifying it is that one commit was never published and that the bytes depend on
where the source was checked out.

Discussion #235 proposed having xrpld
verify its own binary hash at startup against operator-configured signatures. This XLS keeps its
central idea, signatures from parties the operator chooses, and changes where verification runs and
where signatures live (Section 4).

3. Specification

The key words MUST, MUST NOT, SHOULD and MAY are to be interpreted as described in RFC 2119 and
RFC 8174.

3.1. Terms

• Release tag: a tag in XRPLF/rippled naming the exact commit a release is built from.
• Artifact: any file published for a release: each .deb, .rpm, debug-symbol package,
  container image manifest, the flake.lock and conan.lock used, and the list of Conan
  package revisions used.
• SHA256SUMS: the release's list of artifact hashes (Section 3.3).
• Rebuilder: a party that builds a release tag from source on its own infrastructure, compares
  every artifact with the published one, and attests only on an exact match.
• Attestation: a rebuilder's ledger record of the SHA256SUMS hash for a tag (Section 3.4).
• Accreditor: an account whose holder vets rebuilders, for example XRPLF.
• Accreditation: an accreditor's ledger record that an account is a rebuilder (Section 3.5).
• Trust policy: the rebuilders and accreditors an operator trusts, and the thresholds
  (Section 3.6).

3.2. Reproducible builds

For every release tag:

1. Building the tag MUST produce byte-identical artifacts regardless of the build host, the build
   time, the directory the source is checked out to, and the directory the dependency cache lives
   in.
2. The build MUST NOT embed absolute paths of the source, the build directory or the dependency
   cache. Compilers MUST be given -ffile-prefix-map for each, covering __FILE__, assertion
   strings and debug information (DW_AT_comp_dir). This applies to dependency builds too:
   prebuilt Conan libraries in 3.4.1 carry 534 /root/.conan2/p/ paths. The link MUST NOT write
   an rpath that a later step removes, since patchelf --remove-rpath leaves the string in
   .dynstr.
3. Timestamps in artifacts MUST derive from SOURCE_DATE_EPOCH, set to the commit time of the
   release tag.
4. Every build input MUST be pinned by content hash: the toolchain by flake.lock, container images
   by @sha256 digest, and Conan recipes by a committed conan.lock. A Conan 2 lockfile records
   recipe revisions only, so each release MUST also publish the package revisions it used.
5. Every dependency MUST be buildable from source, giving the same bytes as any prebuilt binary
   used in the official build. A rebuilder MUST be able to reproduce a release without downloading
   any prebuilt binary from an XRPLF-operated server.
6. The release commit embedded in the binary (BuildInfo) MUST be the release tag's commit. A
   release built from a commit outside the public repository MUST have that same commit object
   published to XRPLF/rippled at disclosure (Section 3.10). A different commit is not
   sufficient, even with identical compiled source.
7. Packaging inputs that are not in the source, namely the package release number and the channel
   written to the changelog, MUST be published with the release.

CI MUST build every release tag twice, in different directories, and fail if any artifact differs.
CI SHOULD run the same check on every merge to the default branch, so a regression is caught before
a release depends on it.

3.3. SHA256SUMS

SHA256SUMS is UTF-8 text with LF line endings. It has one line per artifact,
<sha256 as 64 lowercase hex> <file name> (two spaces), sorted by file name, with no other
content. It is attached to the GitHub release of the tag.

A signature that a package format embeds, such as an RPM header signature, MUST be published
separately as an artifact of its own, so that every rebuilder can apply it to its own unsigned
build and reproduce the signed package byte for byte. For such a package, SHA256SUMS lists three
artifacts: the unsigned package, under its file name with .unsigned appended; the published
signature; and the signed package, under its file name.

3.4. Attestation

A rebuilder attests a release by submitting, from its own account:

Field	Value
TransactionType	CredentialCreate
Account	the rebuilder
Subject	the rebuilder (self-issued; the ledger sets lsfAccepted at creation)
CredentialType	UTF-8 xrpld/release-attestation/v1/<tag>, at most 64 bytes, so <tag> is at most 35 bytes of [A-Za-z0-9._+-]
URI	UTF-8 lowercase hex sha256 of the tag's SHA256SUMS, exactly 64 bytes
Expiration	MUST NOT be present

• A rebuilder MUST verify the release tag's signature against the published release signing keys
  before building.
• A rebuilder attests the SHA256SUMS of the artifacts it built itself. For a package with an
  embedded signature (Section 3.3), it builds the unsigned package and applies the published
  signature, and both its unsigned hash and its signed hash MUST match the published lines. When
  its SHA256SUMS differs from the published one, the attestation is a dissent, and the rebuilder
  SHOULD publish its SHA256SUMS and a diffoscope report at its Domain.
• A rebuilder SHOULD build the toolchain from source, without binary caches, at least once for
  each flake.lock.
• The ledger refuses a second attestation by the same rebuilder for the same tag (tecDUPLICATE).
• A rebuilder deletes an attestation with CredentialDelete (Subject, Issuer and
  CredentialType as above) only to correct its own error, with a public statement at its
  Domain, or after the tag reaches end of life.
• A rebuilder SHOULD attest from an account whose master key is disabled, acting through a regular
  key or SignerList held on hardware.
• A rebuilder SHOULD set its account's Domain, and that domain's xrp-ledger.toml SHOULD list
  the account, so operators can tie the account to an organisation.

An attestation is a claim, not a proof that the work was done. Anyone can create one; verifiers
ignore attestations from accounts outside the operator's trust policy (Section 3.6).

3.5. Accreditation

An accreditor vouches that an account belongs to a vetted rebuilder by submitting, from its own
account:

Field	Value
TransactionType	CredentialCreate
Account	the accreditor
Subject	the rebuilder
CredentialType	UTF-8 xrpld/rebuilder/v1
Expiration	SHOULD be present, at most one year ahead, so accreditation is renewed
URI	MAY point to the accreditor's public statement naming the rebuilder

• The rebuilder MUST accept it with CredentialAccept before verifiers count it.
• The accreditor withdraws it with CredentialDelete. The issuer may delete a credential it issued
  at any time.
• An accreditor MUST NOT issue attestations on a rebuilder's behalf. The claim about the bytes
  stays with the party that built them.
• An accreditor SHOULD disable its account's master key and act through a SignerList whose keys
  are held by different people on hardware, so one stolen key cannot accredit an account.

3.6. Trust policy

A trust policy has six parts:

• rebuilders: rebuilder accounts the operator trusts directly, without an accreditor.
• accreditors: accounts whose xrpld/rebuilder/v1 credentials make other accounts eligible
  rebuilders.
• accreditor_quorum: how many listed accreditors must accredit an account (default 1).
• min_accreditation_age: how many ledgers must have passed since the accreditation was last
  modified, read from its PreviousTxnLgrSeq (default 0). A delay gives watchers time to see a
  new accreditation before it counts.
• threshold: how many eligible rebuilders must attest the same hash.
• max_dissent: how many eligible rebuilders may attest a different hash (default 0).

An account is an eligible rebuilder if it is listed in rebuilders, or if it holds an
accepted, unexpired accreditation from at least accreditor_quorum listed accreditors, each at
least min_accreditation_age ledgers old. Attestations from any other account are ignored.

The operator configures a default policy in a file, referenced from xrpld.cfg by
[rebuilders_file] in the same way as [validators_file]:

[release_rebuilders]
rXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

[release_accreditors]
rAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
rBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB

[release_accreditor_quorum]
2

[release_min_accreditation_age]
100000

[release_threshold]
2

[release_max_dissent]
0

• At least one rebuilder or accreditor MUST be configured.
• The threshold MUST be at least 1. Implementations SHOULD refuse a threshold of 1 unless the
  operator explicitly allows it.
• accreditor_quorum MUST be between 1 and the number of distinct accreditors.
• Packages MAY ship a default file. It is a convenience only, and an operator MAY replace it. A
  shipped default MUST list at least two independent accreditors with accreditor_quorum of at
  least 2, min_accreditation_age of at least 172800 ledgers (about seven days at 3.5 seconds per
  ledger), and a threshold of at least 2.
• A caller of verify_release MAY pass a policy in the request, which replaces the configured one
  for that call.

3.7. Verification

Given a tag, the SHA256SUMS content and a package's sha256, a verifier MUST:

1. Choose one validated ledger and make every read at that ledger's hash. A verifier reading from
   more than one server MUST require all of them to report the same hash for that ledger index.
2. Determine the eligible rebuilders (Section 3.6). To find accredited accounts, read each listed
   accreditor's account_objects of type credential, following marker to the end, and keep
   credentials with that Issuer, CredentialType xrpld/rebuilder/v1, lsfAccepted set, no
   Expiration earlier than the ledger's close time, and PreviousTxnLgrSeq at least
   min_accreditation_age ledgers before it.
3. For each eligible rebuilder, read ledger_entry for the credential keyed by
   (Subject = Issuer = rebuilder, CredentialType as in Section 3.4). entryNotFound means no
   attestation. Any other error fails verification.
4. Treat a credential as malformed if lsfAccepted is clear, Expiration is present, or URI is
   not 64 lowercase hex characters. A malformed credential counts as disagreement.
5. Find the hashes attested by at least threshold eligible rebuilders. Fail unless there is
   exactly one; it is the attested hash.
6. Fail if more than max_dissent eligible rebuilders attest anything else, malformed
   attestations included.
7. Fail if the sha256 of SHA256SUMS is not the attested hash.
8. Fail if the package's sha256 is not a line of SHA256SUMS.
9. Otherwise pass, reporting the ledger index and hash and each attestation's ledger entry index.

xrpld MUST provide an admin RPC, verify_release, that runs these steps against the node's own
validated ledger:

{
  "method": "verify_release",
  "params": [{
    "tag": "3.4.1",
    "sha256sums": "<SHA256SUMS content>",
    "package_sha256": "<64 hex>",
    "policy": {
      "rebuilders": ["rXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"],
      "accreditors": ["rAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"],
      "accreditor_quorum": 1,
      "min_accreditation_age": 172800,
      "threshold": 2,
      "max_dissent": 0
    }
  }]
}

policy is optional; without it the configured policy applies. The RPC returns status
success with verified true or false, ledger_index, ledger_hash, the policy used, a
rebuilders array (account, why it is eligible, attested hash or null, ledger entry index), and
reason when verified is false. The node MUST log every result, with the tag, package hash,
ledger index and hash, and each eligible rebuilder's attestation and entry index, so the record
outlives any later deletion.

The official .deb and .rpm packages SHOULD run verification before replacing the binary
(preinst, %pre). They SHOULD call the installed node's verify_release when the node is
running and has a validated ledger. Otherwise they SHOULD fall back to two or more public servers
operated by different parties, pinned as in step 1. When a trust policy is configured and
verification fails, the package SHOULD refuse to install unless the operator sets
XRPLD_SKIP_RELEASE_VERIFY=1. When no policy is configured, it SHOULD warn. Packages SHOULD also
refuse to replace the installed release with an older one unless the operator sets
XRPLD_ALLOW_DOWNGRADE=1.

3.8. CI provenance

The official release workflow SHOULD publish a build provenance attestation (for example
actions/attest-build-provenance, recorded in Sigstore's public transparency log) for every
artifact, naming the workflow, the commit and the runner. Verifiers SHOULD report whether one
exists for the package and MUST NOT count it towards the threshold. It does not prove the source
matches the bytes. It records what CI claims to have run, in a log XRPLF does not control, which
helps diagnose a disagreement between CI and a rebuilder.

3.9. Release gate

A release MUST NOT be promoted to the stable package channel until at least two accredited
rebuilders outside XRPLF, and no fewer than the shipped default policy's threshold, have attested
it with the same hash as the published SHA256SUMS.

3.10. Releases with withheld source

When a security fix ships before its source is public:

1. The release commit is fixed (commit hash and tree hash) before any binary is built.
2. Accredited rebuilders get read access to that commit, rebuild it, and confirm the artifacts
   match before release. Each submits its attestation when the binary ships.
3. At disclosure, that same commit object is pushed to XRPLF/rippled and tagged, so anyone can
   rebuild the binary they already run.
4. The release announcement states the disclosure date, which SHOULD be no more than 14 days after
   the binary ships.

4. Rationale

• Verification outside the binary being verified. Discussion Source Code Validation — Ensuring Integrity of XRPL Builds #235 had xrpld hash its own binary
  at startup. A tampered binary simply skips that check, and anyone who can replace the binary can
  edit the config. Here, the node already installed checks the next package before it is installed.
  Trust carries forward from a binary the operator has already accepted.
• Reproducibility makes a signature mean something. No signature proves work was done.
  Without reproducibility, a signature says only "I trust this binary". With it, a signature says
  "this source produced these bytes", a public and permanent claim that anyone can falsify by
  rebuilding the tag.
• The operator chooses the signers. Kept from Source Code Validation — Ensuring Integrity of XRPL Builds #235. It is the same trust model as the UNL.
• Rebuilders attest; accreditors vouch for rebuilders. A self-issued attestation proves only
  that the account's key holder made the claim. So the question of whom to trust is answered
  separately, by accreditation, which is what a Credential from one party to another is for.
  If XRPLF issued the attestations itself, it would become the single party whose key
  compromise passes any package, which is the trust this XLS removes. Accreditation keeps XRPLF's
  role to vouching for people, the way a validator list publisher vouches for validators. An
  operator who trusts no accreditor lists rebuilders directly.
• On the ledger, not in a Git repository. A signatures repository (as with Bitcoin Core's
  guix.sigs) is controlled by its administrators, who can rewrite history. Ledger state is
  replicated, validated by the operator's own UNL, and readable from the operator's own node.
• Credential, not NFToken, memo or a shared account. These were built and tested on testnet.
  • A self-issued Credential gets one record per rebuilder per tag from the ledger (tecDUPLICATE),
    a direct key lookup with no pagination, and fixed fields with no payload to parse.
  • NFTokens need paging, and a JSON payload invites schema mistakes.
  • Memos live in transaction history, which servers prune.
  • One account controlled by a SignerList lets the account's quorum, not the operator, decide
    who attests.
• GitHub build provenance is recorded but not counted. It proves which CI workflow produced an
  artifact, which is the trust this XLS removes, so it cannot decide a verification. It is still
  an independent public record of CI's claim (Section 3.8).
• Other networks. Bitcoin Core is closest: Guix builds reproduce bit for bit, 16 to 24 builders
  signed each of the last three releases in the guix.sigs repository, and binaries ship only
  after six match. This XLS keeps that release gate and its two-stage hashes for signed outputs,
  and adds what Bitcoin does not have: attestation records on a ledger, with on-ledger revocation
  and expiry, vetting of who counts, and a check at install.
  Ethereum clients and Solana validators have no independent rebuilds; their defence against one bad
  binary is a second client implementation, which XRPL does not have.
• Not an amendment. No ledger rule changes. The XLS adds an RPC, a config file, build
  requirements and a release process.

5. Backwards Compatibility

None. Nodes without the RPC are unaffected. Operators without a trust policy get a warning, not a
refusal.

6. Test Plan

• Ledger mechanism. A testnet proof of 36 scenarios, each run separately and read from two
  independent servers, covers:
  • a listed package passes;
  • an altered SHA256SUMS, an unlisted package, a threshold too high and threshold 0 all fail;
  • a second hash for the same tag returns tecDUPLICATE;
  • verification fails while one rebuilder disagrees, and passes after it withdraws;
  • servers on different ledgers fail;
  • an unfunded listed account counts as no attestation;
  • with an accreditor-based policy: an unaccredited account's conflicting attestation is ignored;
    requiring two accreditors, a minimum accreditation age, an expired accreditation and a
    revoked accreditation each shrink the eligible set as specified;
  • with one dissenting rebuilder: max_dissent 0 fails, max_dissent 1 passes, and two hashes
    that both reach the threshold fail.
• Reproducibility. The CI job in Section 3.2 builds twice and diffs, and at least two rebuilders
  outside XRPLF reproduce a release tag.
• rippled. Unit tests for verify_release cover each step of Section 3.7.

7. Security Considerations

Threat	Mitigation
Compromised CI, package signing key, package host or CDN	Cannot produce rebuilder attestations, so verification fails. Honest rebuilders' builds will not match, and their dissent says so publicly
Malicious code in the tagged source	Out of scope: attestations prove the bytes match the source, not that the source is safe. Rebuilders verify the tag signature (Section 3.4); code review remains the defence
An unaccredited account attests a hash	Ignored; it is not an eligible rebuilder
One accreditor compromised	Shipped defaults need two independent accreditors and a seven-day accreditation age, so one accreditor cannot make an account eligible, and every accreditation is public ledger state for a week before it counts. Accreditor accounts act through a hardware-held SignerList
One eligible rebuilder compromised or broken	Cannot make a bad package pass at threshold ≥ 2. A false dissent fails verification closed until its accreditor revokes it, which takes effect for every operator using that accreditor without a config change. An operator who wants to ride through one bad rebuilder sets max_dissent to 1
A rebuilder deletes its attestation after use	Deletion is allowed only to correct an error or after end of life. Nodes log every verification result, and the CredentialCreate and CredentialDelete transactions stay on full-history servers
A lying RPC server	Upgrades read the installed node's own validated ledger, so they trust only the operator's UNL. Only a first install, with no node yet, reads public servers, and then all of them must report the same ledger hash
An older, genuinely attested package	Fails step 8, since it is not in the requested tag's SHA256SUMS. Packages refuse to downgrade unless the operator overrides
A new release withheld from an operator	xrpld already warns when a majority of trusted validators run a newer version (LedgerMaster.cpp)
Threshold 1	Implementations refuse it unless the operator explicitly allows it
Rebuilder or accreditor key compromise or loss	Master keys disabled, with keys on hardware and rotated through SetRegularKey or SignerListSet. A compromised rebuilder is revoked by its accreditors
Withheld-source release	Only accredited rebuilders see the fix early, and disclosure is announced with a date no more than 14 days out. The binary reveals the fix to anyone who diffs it, so the window only delays source access
Reserve	Each attestation holds one owner reserve (0.2 XRP on Mainnet on 2026-10-10). Rebuilders may delete attestations for end-of-life tags

Appendix

Appendix A: FAQ

A.1: Who are the rebuilders?

Any party that runs the build on its own infrastructure. Accreditors SHOULD accredit parties that
are independent of XRPLF and of each other, in different organisations and jurisdictions and on
different infrastructure. Each operator decides which accreditors and rebuilders to trust.

[mvadari]

The SHA256 hashes are specified in the release blogs, e.g. https://xrpl.org/blog/2026/xrpld-3.4.1#install--upgrade

Is that insufficient?

[dangell7]

For the those installing to compare? Sure but that just tells you what binary hash the build system generated. It doesn't prove the code in the release is the code in the binary. The only way to to do that is through attestations.