Module attestation
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:
- 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::decodeenforces 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. - 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.
- 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§
- Settlement
Attestation - 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.