ADR-0008 — Status list placement
Status: Accepted ✅ (2026-09-09)
Context
The contradiction found
A repository audit on 2026-09-09 found that the revocationWithdrawing a credential before it expires; the issuer marks it in a status list that verifiers check. mechanism was defined in two places in two different ways:
SPEC-CRED-0001 §5 says:
The list is off-chain (hosted by the issuerThe institution that signs and issues credentials: a university, a professional body, a public institution or a company., signed/versioned); the ledger holds only URI + hash + version + bitmap.
(The "+ bitmap" at the end of the sentence is already inconsistent in itself — if the list is off-chain, what is the bitmap doing on the ledger?)
contracts/src/revocation/StatusListRegistry.sol, however, does this:
function setRevoked(bytes32 issuerId, uint256 index) public onlyIssuer(issuerId)
function setRevokedBatch(bytes32 issuerId, uint256[] calldata indexes) external
function getChunk(bytes32 issuerId, uint256 chunkIndex) external view returns (uint256)
function _setBit(bytes32 issuerId, uint256 index, bool value) privateSo the bitmap is on the ledger, in 256-bit chunks. Every revocation is a ledger transaction.
Both cannot be true at the same time. This ADR resolves the contradiction.
Why now
This is a design split that went unnoticed when the code was written, and it stems from two different readings of the SPEC-BC-0001 decision "approach B (bitstring)". "Bitstring" defines the data structure; it does not define where it lives. The decision log recorded that a bitstring was chosen; the placement question was never asked.
Decision
Decision 1 — The bitstring list lives off-chain
The revocation list is published by the issuer as a signed Status ListA compressed, signed list in which each credential has one position that tells whether it is valid, suspended or revoked. Token under the IETF Token Status List (draft-ietf-oauth-status-list):
https://status.<issuer-domain>/v1/statuslist/<listId>The token is signed with a key bound to the same chain of trust as the issuer's credentialA digital document signed by an issuer and held in the person's wallet; the person shows only the fields that are asked for. signing key (SPEC-ID-0002 X.509). Its content is a compressed bitstring.
Decision 2 — The ledger holds only an anchor
The StatusListRegistry contract holds:
listId = keccak256(issuerId, listURI)
issuerId bytes32
listURI string
contentHash bytes32 // hash of the published Status List Token
listSize uint256 // min 100,000 (privacy floor kept)
version uint64 // increases with every publication
publishedAt uint64
status {ACTIVE, RETIRED}There is not a single bit of revocation data on the ledger.
Decision 3 — The publication cycle is fixed and noisy
The issuer republishes the list at fixed intervals (suggested: 1 hour) — whether or not anything was revoked in that interval. contentHash and version are updated on the ledger with every publication.
This is mandatory to keep the privacy benefit of decision 1. If we published only when something was revoked, the ledger update itself would leak "a revocation happened at this hour" — bringing back exactly the problem we are avoiding.
Decision 4 — StatusListRegistry.sol will be rewritten
The _setBit, getChunk, setRevoked, setRevokedBatch and unsetRevoked functions are removed. They are replaced by publishList(...) and getListAnchor(...).
The IStatusList.isRevoked(issuerId, index) interface in ITrustQueries.sol is also removed — the ledger can no longer answer that question, and leaving an interface that looks as if it could is dangerous.
Decision 5 — Verification flow
The verifierThe party that checks a presented credential: signature, issuer in the trust list, status and policy. Also called relying party.:
- Takes
listURI+indexfrom the credential'sstatusclaim. - Downloads the Status List Token (or takes it from cache).
- Verifies the token's signature.
- Compares the token's hash with the
contentHashon the ledger. - Checks that
versionis fresh enough (policy: e.g. within the last 24 hours). - Reads
indexin the bitstring.
Step 4 is critical: it prevents the issuer from silently rolling back the list on its own server (showing a revoked document as "valid").
Rationale
1. Privacy — this is the main reason
The most serious problem of an on-chain bitmap is not gas but leaking the moment of revocation.
In a permissioned network every transaction is visible to every validator and carries a block timestamp. When setRevoked(issuerId, 4711) is written to the ledger, every state in the network learns:
"University X revoked the document at index 4711 on 14 March 2027 at 10:42."
On its own this does not say whom the index belongs to. But correlation narrows it down:
- When a university revokes a diploma by a disciplinary decision, the date of that decision is usually known or public.
- An employee's credential is revoked on the day they leave an institution. The leaving date matches the ledger stamp.
- A bulk revocation (a department closing) shows up on the ledger as a distinct cluster.
Off-chain + fixed-interval publication closes this: the only thing visible from outside is "a new version of the list was published". Which bit changed — even whether any bit changed — is not visible.
This applies the same logic as the PM-TRUST-0001 principle "even a linkable hash is risky", in the time dimension.
2. Standards alignment
ADR-0006 delegated revocation to the Token Status List. That standard's architecture is already "the issuer publishes a token, the verifier fetches it". Putting the bitmap on the ledger would take the standard's data structure and abandon its transport model — half-alignment. Half-alignment breaks working with external wallets and external verifiers.
3. Cost and scale
Even if gas is free on a permissioned network, ledger state is kept on every validator's disk forever.
Rough size: a 100,000-index list for a single university = a 12.5 KB bitmap. ~200 higher-education institutions in Türkiye → 2.5 MB. At Turkic-world scale, thousands of issuers × list growth → tens of MB of permanent state, plus one transaction and one block per revocation.
Off-chain, the same data is served from a CDN and consumes zero ledger state.
4. Balance of scalability and freshness
An off-chain list can be cached aggressively on the verifier side. An on-chain read requires going to an RPC node every time — and verification is the most frequent operation in the network.
5. The same pattern as ADR-0007
The schema registry uses the same pattern: content off-chain, anchor on-chain. Using two different patterns would split both the code and the mental model for no reason. One pattern: the ledger says which version of an outside document is valid.
Alternatives considered
A — Bitmap entirely on the ledger (the existing code) — rejected
- Pro: a single source; the verifier makes no extra HTTP call; revocation data survives even if the issuer's server goes down.
- Con: leaks the moment of revocation (§1), permanent state cost, deviation from the standard, RPC dependency.
Rejected. Its only real advantage — the "issuer server goes down" scenario — is covered sufficiently by decision 5 step 4 + caching.
B — Cryptographic accumulator / ZK revocation — deferred
Revocation with a Merkle/RSA accumulator or a ZK membership proof is the strongest solution for privacy (the verifier does not even reveal which index it is checking).
Not rejected but deferred. Reason: no mature library or wallet support, alignment with the ES256 base of ADR-0006 needs further research, and it would complicate the pilot unnecessarily. RS-REVOCATION-0001 will assess it for phase 2.
C — Short-lived credentials (no revocation) — partly adopted
The way to remove revocation altogether is to make credentials very short-lived and renew them continuously.
- For a student certificate this is the right answer: 30-day TTL, never on a revocation list.
- For a diploma it is wrong: a diploma is permanent; renewing it continuously burdens the issuer and gives the issuer a "this person is still active" signal with every renewal (tracking surface).
Adopted: a mix. A per-schema TTL policy is defined in SPEC-SCHEMA-0002; short-lived types do not use a status list.
D — Hybrid: urgent revocations on the ledger, normal ones off-chain — rejected
"Write critical revocations to the ledger immediately" sounds attractive but produces the worst privacy outcome: the revocation written to the ledger is exactly the most sensitive one. It does not reduce the leak; it concentrates it.
Consequences
Binding
StatusListRegistry.solis rewritten (decision 4). The existing bitmap logic is removed.ITrustQueries.sol→IStatusList.isRevokedis removed.- The
CredentialRevokedcheck inCredentialGate.solmust be rethought, since it can no longer read from the ledger. On-chain credential gating (ADR-0003 decision 4) can no longer see revocation status directly; the revocation check has to rely on fresh evidence presented by the caller. This narrows a consequence of ADR-0003 and will be addressed inSPEC-AGENT-0001. - The "+ bitmap" wording in SPEC-CRED-0001 §5 is corrected.
- SPEC-CRED-0003 writes this decision down normatively: token format, publication cycle, caching policy, freshness threshold.
status.<issuer-domain>is an operated component for every issuer — it enters theARCH-0004inventory and the issuer onboarding checklist.
Accepted trade-offs
- Operational load on the issuer. Every issuer now has to run a status server. Tamga may offer hosting to small institutions — but then Tamga sees every revocation. This is a point of centralisation and should be handled as a policy in
PM-GOV-0001. - Freshness window. Fixed-interval publication means a delay of up to one publication interval (1 hour) in the worst case. For scenarios that need immediate revocation, the decision 3 interval can be shortened per schema.
- Extra network call. The verifier makes one more HTTP request during verification. With caching this is negligible in practice.
Relations
Corrects: SPEC-CRED-0001 §5 (contradiction) · StatusListRegistry.solBuilds on: ADR-0006 · PM-TRUST-0001Implemented by: SPEC-CRED-0003 · SPEC-BC-0001 (rewrite) Narrows: ADR-0003 decision 4 (revocation visibility for credential gating) Sibling decision: ADR-0007 (the same off-chain content + on-chain anchor pattern) Defers: RS-REVOCATION-0001 (accumulator/ZK, phase 2)
Status
Accepted ✅ — 2026-09-09. Recorded in DECISIONS as D-REV-1, with the related lines in the D-NET/D-CRED sections updated.