Skip to content
nokto/docsGitHub (opens in a new tab)

Signed message

The signed message is what an issuer actually signs when it attests an income claim, and what recordIncome verifies before letting any value accrue — see Receive in Operations.

It is an eleven-slot, append-only layout.

SlotFieldWidth
0version16 bits
1–2recipientId (hi, lo)128 + 128 bits
3amount128 bits
4currency64 bits (8 ASCII bytes, big-endian, zero-padded)
5occurredAt64 bits
6–7issuerKeyId (hi, lo)128 + 128 bits
8tier8 bits
9–10claimNonce (hi, lo)128 + 128 bits
  • MSG-1 An issuer's income claim MUST be signed over the eleven-slot layout in the table above, with the widths given.
  • MSG-2 Slots MUST NOT be reordered, resized, or reused. A new field is appended and the version is incremented.
  • MSG-3 A 32-byte field MUST be carried as two exact 128-bit halves, never degraded into a single field element. A byte-degrading conversion discards the least-significant byte, so two identities differing only in their last byte would sign the same message — an attacker could grind an account id matching a victim's first 31 bytes in 256 tries and replay the issuer's signature into their own account.

recipientId, issuerKeyId, and claimNonce are the Bytes<32> fields MSG-3 governs. Each half is well under the field modulus, so neither is reduced.

Where this is defined, twice, and checked once

  • MSG-4 The layout MUST be defined identically in the contract and in @nokto-protocol/schema, and a conformance test MUST assert the two agree slot for slot.

Concretely: buildClaimMessage in the Compact contract's message module, and encodeSignedMessage in @nokto-protocol/schema. If they ever diverged, an issuer would sign one message while the circuit verified another — every claim would fail, or, worse, the wrong claim would succeed.

The Compact source for buildClaimMessage is itself generated (from a Python script, because the field-splitting arithmetic is a 32-term Horner chain and Compact has no mutable locals to accumulate one in a loop), but the expanded source is committed to the repository so the layout stays reviewable without running the generator.

How to read the requirements on this page

MSG-1 through MSG-4 use MUST as Conformance defines it: an implementation that does not satisfy one is not an implementation of this protocol. That page also records where this implementation falls short of its own specification.

Signature verification

recordIncome verifies a Schnorr signature over this exact message against the issuer's registered key. The message is built from the same eight logical fields the message layout describes; tampering with any one of them changes the message and fails signature verification. See Write an issuer adapter for how a claim is built and signed on the issuer side.