Sharing & bundles

The share/verify exchange is the central moment of the protocol. This page describes the Share Grant (the worker’s consent record), the sealed verification bundle (everything a verifier needs, offline), and how the two move between wallet, registrar, and verifier.

The Share Grant

A Share Grant is signed by the holder’s per-employer key. It is a consent record produced by the worker, not a setting held by a server.

A grant names:

• a grant identifier;
• exactly the attestations being disclosed — the identifiers of the specific variants, and no others;
• an audience, either a known verifier’s public key or the BLAKE3 hash of a link secret;
• a scope, either view or monitor;
• an expiry; and
• a single-use nonce.

The granularity dial lives here. A threshold-only share lists only the threshold variant’s identifier, and the bundle built for that grant must not contain the exact variant’s payload bytes at all. Selective disclosure is enforced by what is in the bundle, not by hiding fields inside it.

A Grant Revocation, also holder-signed, names the grant and the time it was withdrawn. It kills future fetches and future recency, but it does not delete copies already viewed or downloaded.

The verification bundle

A verification bundle is self-contained — sufficient for fully offline verification.

Contents	Signed by	What it is
Employer Descriptor	Employer	the employer’s own identity record
Entity Attestation	KYB attester	the third-party attestation of the employer’s legal identity
Epoch chain	Employer	the epoch records, back to the first epoch
Delegations	Employer	the delegations covering the granted mints
Attestations	Registrar	only the granted variants’ payloads
Family supersession entries	Registrar	evidence that a claim family has been superseded, where it exists
Revocation commitments	—	the public BLAKE3 commitments over attestation identifiers, as of the checkpoint
Latest Checkpoint	Registrar	the freshness anchor — the bundle’s “as of”
Share Grant	Holder	the consent record above
Inclusion receipts	Registrar	optional additional witness evidence

The wallet assembles the employer-side materials — descriptor, entity attestation, epoch chain, delegations, revocation commitments, and a live-signed checkpoint — from the registrar’s public feed for that employer. That feed carries the public class only, and never a subject roster. The portable export does carry the roster, is gated on employer credentials, and is not a bundle source.

Alongside the bundle, the verifier supplies a presentation context. This is not trusted content; it is an input to a pure function, describing how the bundle is being presented: the audience the presenter authenticated as, and the scope being requested.

The verify predicate checks the grant’s audience against the presentation context’s, so a bundle sealed for one verifier cannot be replayed by another.

Sealing

The bundle is sealed age-style — X25519 key agreement, HKDF, and ChaCha20-Poly1305 — to its audience:

• when the verifier’s key is known, the bundle is sealed to that key;
• otherwise it is sealed to a key derived from the link secret. The capability URL carries the secret; the stored grant carries only the BLAKE3 hash of it, so the registrar never holds the secret itself.

The exchange

1. The worker signs the Share Grant with the per-employer key, and the wallet seals the assembled bundle to the grant’s audience.
2. The wallet submits the grant and the sealed bundle to the registrar, which stores both and returns the grant identifier.
3. The worker delivers the capability link — as a URL or a QR code — to the verifier, who opens it.
4. The verifier fetches the sealed bundle. The registrar records that fetch in the worker-visible access log.
5. The verifier unseals the bundle and runs the verify predicate over it, producing a verdict.
6. The verifier records the verification with the registrar, which bills it and issues a receipt. The access log shows the worker that the view occurred.

For a live recency check the verifier additionally pulls a fresh checkpoint and the current revocation set for that employer and feeds them to the predicate. For an offline verification it uses only the checkpoint and revocation set carried inside the bundle. The verdict distinguishes the two cases and shows the age of the head it relied on.

Monitoring

A grant whose scope is monitor additionally authorizes a subscription. Thereafter the verifier receives event classes only: that employment status changed, that an attestation was superseded, that a grant was revoked. No values are ever carried. The subscription dies with the grant, and learning what changed requires a fresh share the worker consents to.