Skip to main content

Module attestation

Module attestation 

Source
Expand description

The settlement attestation: a canonical, self-contained, content-addressed record (PAY-ARCH-01 guard-rail).

§Why this exists

settlement.capnp declares attestation :Data. An opaque byte blob is fine for “carry this to the verifier and back”, but it is not fine for what the attestation is actually for: a future exchange record (#926) must be able to embed this blob verbatim and content-address it. That requires three properties an arbitrary Data payload does not have:

  1. Canonical. One logical attestation has exactly one byte representation, so its CID is a function of its meaning rather than of whichever encoder produced it. SettlementAttestation::decode enforces this by re-encoding what it parsed and rejecting any input that is not already in canonical form — a non-canonical blob is refused rather than silently normalized, because normalizing would change the CID a peer already committed to.
  2. Self-contained. Everything needed to decide what was settled — issuer, settlement id, unit, destination, amount, grant — is inside the signed body. Nothing is passed alongside it. A verifier that has to be told the settlement id out of band cannot detect a blob presented under the wrong id, so the id is bound in here instead.
  3. Domain-separated. The signed bytes begin with a version tag unique to this record type, so a signature over some other artifact can never be replayed as a settlement attestation, and a future v2 body can never be read as a v1 one.

§Normative encoding

The body is canonical DAG-CBOR — the same discipline hyprstream_ledger::AccountId::derive and hyprstream-pds use (definite lengths, minimal-width integers, no maps so no key ordering to get wrong). A single definite-length array, in this fixed order:

[
  "hs-pay-settlement-attestation-v1",  // domain + version tag
  <issuer_did      : tstr>,
  <settlement_id   : tstr>,
  <unit_issuer_did : tstr>,
  <unit_class      : tstr>,
  <destination_did : tstr>,
  <amount_minor    : bstr(16)>,        // big-endian u128
  <grant_cid       : bstr>,            // empty when absent
  <settled_at      : uint>,            // unix seconds
  <signature       : bstr>             // COSE composite over the body below
]

The signing input is the same array with the trailing signature element omitted (a 9-element array), so the signature covers every semantic field and nothing else. Amounts are 16-byte big-endian rather than CBOR integers because the ledger’s amounts are u128, which CBOR’s integer range cannot carry losslessly.

§CID

SettlementAttestation::cid is blake3(canonical bytes), 32 bytes. It is stable across encode/decode round-trips and across processes, so an exchange record can reference the attestation by CID and a peer can re-derive that CID from the embedded bytes with no re-encoding step.

Structs§

SettlementAttestation
A settlement attestation: the signed, self-contained claim that a specific settlement committed, and therefore that a specific issuance is owed.

Constants§

ATTESTATION_V1_TAG
Domain-separation and version tag. Changing the body shape means minting a new tag, never reinterpreting this one.