Objects

Every protocol object is signed and transmitted in the same shape: the exact canonical bytes plus an Ed25519 signature over them. This page catalogues the objects, the encoding rule that binds each one to its kind, and the claim schemas an attestation can carry.

The encoding rule

The only bytes ever signed or hashed are a BCS serialisation of the object body together with a version-tagged label naming the object’s kind. Because the kind label sits inside the signed bytes, a signature over a Delegation can never be replayed as, say, an Attestation. JSON renderings exist only for storage and display; they are never signed or hashed.

Verification always runs over the transmitted bytes, then decodes under the expected kind — so a single tampered byte fails the signature check before the payload is ever interpreted. Some checks additionally pin the expected signer, rejecting a validly signed object presented by the wrong key. See Wire format for the encoding and envelope shapes.

Object catalogue

“Signer” is the key whose signature is required for the object to be meaningful.

Object	Signer	Purpose
Employer Descriptor	Employer	Declares the employer key, the entity-verification reference, enabled attestation types, dispute and recovery policy, and mirror locations
Entity Attestation	KYB attester	Binds the employer key to a legal entity and jurisdiction, with the verification methods used and an expiry
Epoch Open	Employer	Opens an authority epoch: names the registrar key valid from a given sequence number, chaining to the prior epoch head
Epoch Close	Employer	Closes an epoch at a final sequence number and head hash
Delegation	Employer	Grants the registrar the right to mint specified types up to a daily cap, within a sequence-number and time window
Batch Manifest	Employer (signing device)	Carries the aggregates computed by the signing device plus the hash of the raw batch for one issuance run
Attestation	Registrar	One signed claim about a worker, minted under a covering delegation
Status Change	Registrar	Closes or reopens an employment period
Revocation	Registrar / Employer	Revokes one attestation, with a reason
Family Supersession	Registrar	One log entry that atomically retires every variant of a claim family
Reissue	Registrar (plus employer approval when policy requires)	Re-points attestations to a fresh subject key, for recovery
Share Grant	Holder	The worker’s consent record: which attestations, which audience, what scope, expiry, and a nonce
Grant Revocation	Holder	Withdraws a Share Grant — kills future fetches and recency, never deletes copies already seen
Holder authentication proof	Holder	Proves control of a subject key in order to authorise a read of the holder’s own registrar-side data
Signed Head	Registrar	A signed statement of employer, epoch, sequence number, and head hash — the witnessed head
Checkpoint	Registrar	A timestamped head mirrored externally; its publication time is the “not revoked as of” line

A few non-obvious points:

• Share Grants and Grant Revocations are holder-signed, not registrar-signed. Consent is the worker’s cryptographic act, not a server toggle.
• Batch aggregates are computed by the employer’s signing device, not by the dashboard, and ride inside the signed payload so the registrar can cross-check them against the raw batch it received.
• Family Supersession is the atomicity primitive behind claim families: one signed entry retires the exact, band, and threshold variants together.
• The holder authentication proof is not a log entry. It carries a subject key and a timestamp, is signed by the holder’s per-employer key, and its timestamp must be within five minutes of the registrar’s clock. The registrar verifies it and discards it — never stored, never chained. Knowing a subject key is not authorisation; signing with it is.
• The Signed Head carries exactly the fields a conflicting-head comparison needs, which is what makes a pair of contradictory heads checkable as a misbehavior proof.

Claim schemas

An attestation carries a typed claim body and, for income types, a basis. The seven types and their claim shapes:

Type	Claims
employment_status	{ status: active|ended, start_date, end_date? }
tenure_dates	{ start_date, end_date? }
role_title	{ title, department? }
income_exact	{ cents, basis }
income_band	{ band_floor_cents, band_ceiling_cents, basis }
income_threshold	{ at_least_cents, basis }
hours_class	{ class: full_time|part_time|variable }

Income amounts are integer cents; dates are unix seconds. The basis qualifies income figures:

Basis	Meaning
annual_salary	A stated annual salary
trailing_90d_annualized	The trailing 90 days, annualized
trailing_12m	The trailing twelve months

Income is never minted as a lone exact value. The exact figure and its derived band and threshold variants are minted together as one claim family — see Claim families.

Attestation fields

The attestation body is the object a verifier ultimately renders, so it is worth listing in full:

Field	Notes
Attestation identifier	Unique per variant
Family identifier	Shared by every variant of one underlying fact
Employer, epoch number, log sequence number	Locate the attestation in the employer’s log
Subject key	The worker’s per-employer public key
Type	One of the seven types above
Claim body	The typed claim
Basis	Present for income types
“As of” time	The point in time the claim describes
Expiry	Optional expiry of the claim itself
Superseded family	The prior family identifier this family replaces, if any

The registrar’s signature over this object is valid only if the covering delegation allows the claim’s type at that log sequence number and the claim’s “as of” time falls within the delegation’s time window — see Verification.