In brief
This document describes the format of Tamga Network's trust listsA signed list of a country's root certificates, issuers and registered relying parties. Today trust in Tamga rests on these lists; a shared ledger comes later.: which institution may issue which credential, what each verifierThe party that checks a presented credential: signature, issuer in the trust list, status and policy. Also called relying party. may ask for, and how all of this is signed and published. It is written for the verifiers and wallets that read the lists and for the operator that runs them.
When to read
- Read the concept page Trust lists and federation first.
- To read the lists in code, go to the guide GUIDE-0006.
- The structure of institution certificates is not here: SPEC-ID-0002.
Plain explanation
The network's trust lives in three files. lotl (LOTL (List of Trusted Lists)The signed list that points to the countries' trust lists, their signers and their recognition status.) is the list of lists and points to the other lists; national lists such as tl-tr enumerate institutions, verifiers and wallet providersThe organisation that offers a wallet, registers its wallet units and signs wallet and key attestations. Each wallet runs its own provider; the network does not run one, it lists them in the trusted list.; the anchor log (anchors.jsonl) records changes to status listsA compressed, signed list in which each credential has one position that tells whether it is valid, suspended or revoked. and schemas in time order. Every list is signed, every version is linked to the previous one and the version number only grows; an old version cannot be served again. The lists contain no personal data. Lists run by other operators can also be recognised, within a limited scope (federationA model in which each country runs its own trust list and a list of trusted lists brings them together; Tamga can also show external lists.). Once at least two independent operators join, the same data moves to a ledger (chain); wallets and verification are not affected.
Scope
This specification is the normative implementation of ADR-0009 K2: it defines the list format that carries the trust records until the chain is set up (≥2 independent validator operators). When the chain is set up, the same data is replayed into the contracts (§7); credentials, wallets and the verification pipeline do not change. The canonical field names are taken from SPEC-BC-0001 and the SQL projection in ARCH-0003 §2.4. No list contains personal data (DP1).
1. Principles
- Every field maps to a contract record (§7); a list is the single-signer special case of the chain.
- No personal data — only institution names, certificate fingerprints, statuses, dates, URIs and identifier derivations.
- Version + hash chain —
versionis monotonic,previous_version_hash = sha256(<previous .jws>); nothing is deleted; status changes are appended tostatus_history. - Signature — every list is a compact JWS (
.jws;alg: ES256,x5coperator certificate); the.jsonis for humans only. Verifiers use only the.jws; they match thex5c[0]fingerprint againstkeys/root-fingerprints.json(lotl) orlotl.national_lists[].signing_keys(tl). - ETSI mapping — statuses use the Tamga enum; the ETSI TS 119 612 XML view (
tl-<cc>.xml) is produced with the SPEC-ID-0002 §8.1 profile, from the same signed list and with the same version; status URIs from the Tamga root, no qualified-service claim (ADR-0066). - Cadence —
lotl/tl-<cc>:next_update≤ 90 days, re-signed even without changes; a change is published within 24 hours;anchors.jsonlhourly (heartbeat included). - Type identifier — vct (Verifiable Credential Type)The permanent identifier of a credential type in SD-JWT VC; in Tamga it is a URN such as urn:tamga:edu:Diploma:1. URN (ADR-0010); the
lotl.schemas[]catalogue entry givesmetadata_url + content_hash. - Category signal — institution
class: PUB | QUALIFIED | EAA(EAA (Electronic Attestation of Attributes)The eIDAS term for a credential that attests attributes of a person, such as a degree or a membership.; ADR-0010 K5). - TDT-first —
lotl+ a national list slot for every member state, the full ARF role set,operator.on_behalf_of; a hand-over changes only theoperatorfield;ca_id/issuer_id/vctare fixed (D-GOV-5).
2. File layout (https://trust.tamga.network/)
lotl.jws · lotl.json list of lists + NETWORK schemas + wallet providers + categories
tl-tr.jws · tl-tr.json TR national list (root_cas, issuers, relying_parties, national_schemas)
tl-<cc>.jws (RESERVED) AZ/KZ/KG/UZ (members), HU/TM (observers) — slot
anchors.jsonl anchor log (one line = one JWS)
keys/root-fingerprints.json LOTL signing certificate and national root fingerprints (= tamga.network/trust-anchor);
explanation in the note field
keys/<name>.cert.pem only certificates the list references (operator/root/registrar/wallet-provider/rp; published)
wrprc/index.json · wrprc/… registration certificates (ETSI TS 119 475 rc-wrp+jwt) and their index (ADR-0026)
status/wrprc/<n> status list of the registration certificates (statuslist+jwt, 1 bit, registrar key) and
wrprc-status.json index and revocation record (ADR-0068; only when configured in the registry — today the real network and the sandbox)
crl/<authority>.crl revocation list of access certificates (RFC 5280 CRL, DER, application/pkix-crl; signed by the
issuing authority on every publication and hourly, nextUpdate 24 hours) and access-crl-state.json
(revocation record; ADR-0087; only when roles.access_ca.crl is configured — today the sandbox).
Served not on the trusted-list host but on a separate CRL host: http(s)://crl.<network>/<authority>.crl
(ADR-0090)
zk/<circuit_id>.zst ZK circuit files listed in `zk_circuits` (ADR-0032); wallets download them and check `zk_circuits[].sha256`
lote/<type>.json · .jws ETSI TS 119 602 LoTE views (wallet-providers, wrpac-providers, eaa-providers);
only when LoTE publication is enabled (lote.enabled)
tl-<cc>.xml · tl-<cc>.sha2 ETSI TS 119 612 XML view (XAdES-B-B, signer keys/tl-xml-signer-1.cert.pem; fingerprint
in the LOTL slot's xml_signing_keys) and SHA-256 digest;
only with TAMGA_TL119612=1 (ADR-0066; in the sandbox today)
archive/<file>.v<NNNN>.jws immutable version archive (replay input; the XML archive is archive/tl-<cc>.v<NNNN>.xml)
CHANGELOG.md public change log3. lotl — the list of lists
| Field | Type | Meaning / contract counterpart |
|---|---|---|
list_format_version | string | Format version; unknown → the verifier stops (CMP2) |
list_type | "lotl" | |
environment | "production" | "sandbox" (optional; absent means production) | The network the list belongs to (ADR-0038). The test network's list carries sandbox; the loader stops on a list that does not match the network it expects (ADR-0038/SB2) |
version, issued_at, next_update, previous_version_hash | Version/hash chain (§1.3, §1.6) | |
operator | {name, status: "provisional", on_behalf_of, trust_framework, transparency_report?} | Founding proxy. The status values are provisional and designated: in the list stage only provisional is published (TL1; the publisher does not publish with any other value). designated is the value to be used once list operation is handed over to the body designated by the state (ADR-0009 K5; the operator record on the chain, ADR-0074 K3), and publishing with it opens with a separate handover decision; the loader recognises the value already today so that readers of the list need no update at the handover. The value does not enter the verification decision (ADR-0070 implementation note 2026-11-12). trust_framework = URL of FW-TF-0001 (https://arf.tamga.network/trust-framework); transparency_report is optional, added once its page is published. name: "Tamga Network" in the real network (ADR-0070/OP1); in a list with environment: "sandbox" the name must carry the "(TEST)" mark and the list is published as "Tamga Network Sandbox (TEST)" — otherwise the publisher does not publish (ADR-0070/OP2, 2026-11-12) |
catalogue | {url} | Type Metadata resolution path (schemas.tamga.network/v1/catalogue.json) |
anchor_signing_keys[] | {fingerprint_sha256, cert_ref, status} | Anchor log signers (≥2, rolling — TL3) |
national_lists[] | {state_code, status: ACTIVE|RESERVED, membership, list_url, operator, roles{registrar, tlso, pid_provider, access_ca, national_root_ca}, signing_keys[], xml_signing_keys[]?, recognition{mode, recognizes[]}} | Governance member list + CrossRecognition. signing_keys are the signers of the JSON national list (tl-<cc>.jws) only; xml_signing_keys are the signers of the ETSI TS 119 612 XML view (tl-<cc>.xml, EKU id-tsl-kp-tslSigning) only — present when the slot publishes XML; the two sets are separate and an XML signer never validates a JSON list (ADR-0066 0.7.4 implementation note) |
schemas[] | {schema_id, vct, metadata_url, content_hash, content_hashes[], layer: NETWORK, governance, status, registered_at, status_history[]} | SchemaRegistry (NETWORK); registered_at is permanent (time of the first anchor); content_hashes = digests of the valid versions (ADR-0010 K4; in the development stage only the current digest, ADR-0029), each anchored once |
eaa_categories | {urn → description} | Category namespace (ADR-0010 K5) |
wallet_providers[] | {provider_id, legal_name, wua_signing_keys[], solutions[{solution_id, min_version, status, security_level}], status} | WUA trust anchor (R-7; on the chain in NetworkRegistry, ADR-0074 K3). status (of the entry and of solutions[].status) is from the Status set: ACTIVE | SUSPENDED | REVOKED | RETIRED | ROLLING_OVER | RESERVED | PROVISIONAL | DEPRECATED. WUA validation uses only the ACTIVE keys of an ACTIVE entry. A RESERVED entry holds a place (e.g. a wallet provider whose operator has not yet supplied its own certificate, ADR-0042): wua_signing_keys may be empty and it is not used for WUA validation. security_level is the wallet assurance level (SPEC-WALLET-0001 §2.2; W1 is not supported (except the test key for the network's own trial scenes in the sandbox list — ADR-0042 K5)). Optional identifiers[] (ADR-0024 form, {scheme, value}): the provider's official registration number. The registry tool (wallet-provider activate) checks the signing certificate against the ETSI TS 119 412-6 §5 profile: the subject's organizationIdentifier (2.5.4.97) must equal the semantic identifier derived from this number (VATTR-<VKN> …) and the qcStatements must carry the QcType id-etsi-qct-wal (0.4.0.194126.1.2); an entry without a registration number is not activated (exception: "(TEST)" certificates in the sandbox) |
zk_circuits[] | {circuit_id, system, version, attributes, sha256, status} | Accepted ZK circuits (ADR-0032 ZK2; on the chain in NetworkRegistry, note is not written) |
pid_providers[] | empty, reserved | BT8 → TL8 |
4. tl-<cc> — national list
| Field | Meaning / contract counterpart |
|---|---|
state_code, version, issued_at, next_update, previous_version_hash, operator, environment | Namespace = state; signed only with that namespace's key (the list-stage reading of N1); environment is checked with the same rule as in the LOTL |
root_cas[] {ca_id, legal_name, cert_fingerprint_sha256, cert_pem, service_type, operator, status: ACTIVE|ROLLING_OVER|RETIRED|REVOKED, valid_from/until, successor_ca_id, status_history[]} | RootCARegistry (CA1–CA3); ca_id = keccak256(cc ‖ SHA-256(rootDER)) |
issuers[] {issuer_id, slug, legal_name, category, assurance: I1..I3, class: PUB|QUALIFIED|EAA, assurance_basis, parent_ca_id, cert_fingerprint_sha256, issuer_url, status_list_base, status, valid_from/until, successor_id, status_history[], schema_authorizations[{schema_id, vct, allowed, valid_from, valid_until}], delegate_keys[], authentic_source, test_institution?} | IssuerRegistry (I1–I4, R1–R2); issuer_id = keccak256(cc ‖ SHA-256(leafDER)); authorisation is time-windowed (I3). test_institution: true only in the sandbox list: a test institution opened by self-service in the sandbox (ADR-0041; its certificate comes from the sandbox intermediate CA and its credentials carry the leaf + intermediate chain); never in the real network's list. Optional revocation_policy_uri (ADR-0047 K2): the page of conditions the institution adds to the network's common revocation policy (https); it cannot narrow the common conditions; the wallet shows it on the institution page |
relying_parties[] {rp_id, client_id, dns_name, legal_name, access_cert_fingerprint_sha256, status, registered_at, scopes[{scope_id, service_id?, purpose, purpose_localized?, vct, claims[], format?, mdoc_namespace?, valid_from, valid_until}], status_history[]} | RelyingPartyRegistry; client_id = the OpenID4VP client identifier x509_hash: (computed by the publisher from the access certificate; ADR-0034), dns_name = permanent registration identifier (SAN); scopes[] = the ARF registration certificate counterpart (AP6). Registration data (ADR-0024): optional trade_name, identifiers[], postal_address, info_uri, contact (the institution's role address: support@…, info@… or an https page — not a mailbox carrying a person's name; the list is public and permanent and carries no personal data), service_description, is_public_sector_body, entitlements[], supervisory_authority, uses_intermediaries[] / served_relying_parties[], scopes[].privacy_policy_uri; issuers[] carry the same identity/contact fields and entitlements derived from their class. The publisher does not publish a participant registered on or after 2026-09-30 with a mandatory field missing. Registration certificates (ADR-0026): for every valid use and every issuer the publisher produces an ETSI TS 119 475 rc-wrp+jwt under wrprc/ (index wrprc/index.json; registrar key in LOTL national_lists[].roles.registrar.signing_keys); sub = the semantic identifier from identifiers[] (VATTR-, NTRTR-). The use's optional service_id (ADR-0046, ARF RPRC_17a) goes into the registration certificate as service_id; without it, the scope_id. Optional format (dc+sd-jwt by default · mso_mdoc · mso_mdoc_zk) and, for mdoc, the required mdoc_namespace: the registration certificate's credentials entry is written in the use's presentation format (SD-JWT VC: vct_values + [claim]; mdoc: doctype_value + [namespace, element], element names per CIR 2026/1731 Table 6) — an EU wallet compares the request by format, type and path (ETSI TS 119 475 Annex B.2.9, ARF RPRC_21); the verifier selects the use by the same format. Gate groups (ADR-0012 K5, ADR-0069): optional terminal_groups[{group_id, institution_id, label?, allowed_policies[], cert_fingerprints[]?, offline_allowed?, valid_from, valid_until?}] — group_id unique in the whole list; for an active group institution_id (the slug of an issuer in the same list or a verifier's dns_name) and at least one allowed_policies (gate policy policy_id) are required; the publisher checks this (TG1). The verifier reads the group's institution from here (TrustSource.terminalGroup); cert_fingerprints is for certificate-based gates (preparation). |
national_schemas[] | SchemaRegistry (NATIONAL) |
Status vocabulary: ACTIVE | SUSPENDED | REVOKED | RETIRED (+ root: ROLLING_OVER). History is never deleted; verification looks at status_history with the credential's iat (D-BC-3, SPEC-BC-0001/I2–I3). The list of a REVOKED institution may be published by its successor (successor_id) (I4). Operator tool: trust-publisher status <slug> <STATUS> --reason r (REVOKED --invalidates-from <date>: credentials issued from that moment fail; valid_from = all of the institution's credentials), rp-status <dns_name> <STATUS> for a relying party, end-use <dns_name> <id> for a single use or gate group (end date). The start of a use or a gate group does not change; its end changes only by closing an open period, and the new end cannot be earlier than the start of the row or than the publication time of the previous signed list (a period the previous list stated as open cannot be closed retroactively). Whether a period is open is also decided by the publication time of the previous signed list. The publisher enforces this: if an issuer, relying party or terminal group of the previously published version is missing from the new list, publication stops. The only exception is an approved removal entry written explicitly in the registry, with exactly matching counts (removals.json; list, date, the number of the signed version before the removal, counts and a short reason only — no names or identifiers; the entry passes only in the publication that follows that version and cannot be used again); the list is then published and a line without names is written to the public changelog, while earlier list versions stay in the archive. The limits of this path are binding through ADR-0081 (RR1–RR4): only a record that was entered for testing before institutions joined, that never issued a credential to a real person and never received a real presentation, may be removed; once the first participant institution enters the real network's list the path closes and testing is done only in the sandbox. It has been used once so far (2026-11-11): test records left over from the pre-pilot test period, already REVOKED, were removed from the real network's list. It is not used for the record of a real institution. A record is never removed from the list (TL2); a withdrawn institution stays in the ETSI XML view with its Tamga status URI (…/tl/Svcstatus/revoked etc., SPEC-ID-0002 §8.1) and leaves the LoTE.
5. anchors.jsonl — anchor log
Implemented (2026-11-04), ADR-0074 K4: two new line types for the registration certificate status list and the list views (
registration_status,list_view). The loader recognises them; an unknown type still STOPS the loader. The publisher therefore writes these lines only while the chain projection is on (TAMGA_CHAIN_ENABLED=1; off in production). Condition for opening the chain (2026-11-05): the lowest loader version that recognises these types is@tamga-network/trust0.8.1; the new line types are written only once the consumers that read the list (verifiers, wallets, issuer services) run at least that version — the flag is not turned on before. In astatus_listlinebits/sizecome together,size × bitsis a multiple of 8 andsize≤ 2^32 − 1 (the chain'suint32); the monotonicity key oflist_viewis the (file,source_file) pair; a checkpoint'slist_views[]follows the same format rules as the line.
Every line is an independent JWS; payload {seq, previous_hash, ts, kind, …}:
kind | Fields | Contract counterpart |
|---|---|---|
status_list | list_id, issuer_id, list_uri, content_hash, list_version, published_at, optional bits, size | StatusListRegistry.publishList (list-stage reading of S1/S4, L1); the first line registerList(…, size, bits) |
schema | schema_id, vct, content_hash | SchemaRegistry contentHash (D8: after the CDN publication) |
heartbeat | — | Hourly cadence (S5 logic on the operator side) |
checkpoint | archive: { file, sha256, seq_from, seq_to, lines }, state: { status_lists[], schemas[], registration_status[]?, list_views[]? } | Archive checkpoint (TL12); state = the final state produced by the archived lines |
registration_status | list_uri, content_hash, list_version, published_at | Every publication of the registration certificate status list (ADR-0068); anchorList in the list anchor registry, key keccak256("tamga:registration-status:<env>:<name>") (<name> = the address after /status/), version = list_version |
list_view | file, format, source_file, source_version, content_hash | Every generation of a list view (ADR-0066: tl-<cc>.xml, lote/<kind>.jws); anchorList, key keccak256("tamga:trust-list-view:<env>:<file>"), version = the version of the source list |
Rules: ≥1 line per hour; list_version is monotonic per institution (L1/S3); the verifier compares content_hash with the Status List Token hash in D5; lines are never deleted; the log is public; list_uri is opaque (S8). In the new line types (PJ5) content_hash is the SHA-256 of the file (sha256:<hex>; for XML the same as .sha2); the list_version of registration_status only grows per list and the source_version of list_view only grows per file (the loader rejects a step back). These lines do not enter the verification decision; if a view contradicts its source, the source (JSON list) prevails. The checkpoint state also carries their latest values (older checkpoints do not have the fields).
Bit count and size in a status_list line (2026-11-05). The optional bits (Token Status List set: 1, 2, 4, 8) and size (index capacity = inflated lst bytes × 8 / bits) are read from the token: the publisher's anchor --token <file> command opens the token, checks that its digest equals content_hash and its sub equals list_uri, and writes both fields to the line. The list record on the chain (StatusListRegistry.registerList) needs both values; the replay reads them from the line first and, for older lines, from the token at the list address; if neither is available, writing to the real network is refused. The fields do not enter the verification decision; a checkpoint's state.status_lists[] carries them too. Older loaders ignore the unknown fields (the line type is unchanged).
Archiving and checkpoints (TL12). As the log grows, load time grows linearly with the number of lines (each line is one JWS verification). When the log passes a threshold (500 lines by default), the operator moves all current lines into archive/anchors-<from>-<to>.jsonl (if an archive with that name but different content already exists — e.g. after a sandbox reset restarted seq at 0 — a time suffix is added: anchors-<from>-<to>-<epoch_ms>.jsonl; the old archive is never overwritten) and writes a signed checkpoint as the first line of the new log: seq = seq_to + 1, previous_hash = sha256(last line of the archive), archive.sha256 = sha256(archive file) and state — the final state produced by the archived lines (the status anchor with the highest list_version per list + the schema anchors). The next anchor links to the checkpoint as usual; the chain is unbroken and no line is deleted (TL2). The loader: if the first line is a checkpoint, it verifies its signature (anchor signing key), checks that seq is seq_to + 1, applies state to the store (rejects it if missing) and continues the chain from there; a checkpoint produces no record in TrustSource. A checkpoint seen in the middle is an ordinary line (in a full-history load). Full history (TL10 replay, trust:verify --full): checkpoints are followed backwards, every archive's hash is verified and the chain is loaded from seq 0. Load cost thus stays bounded by the current slice; archives remain public.
6. Loader and TrustSource (verifier side)
@tamga-network/trust loadTrustSet order: lotl.jws signature (root fingerprints) → tl-<cc>.jws signatures (signing_keys) → format (list_format_version) → hash chain → next_update → anchors.jsonl chain → in-memory projection (the tables of ARCH-0003 §2.4). After signature and format, environment is compared with the expected network (default production); a wallet or verifier that connects to the test network expects sandbox and is pinned only to the test network's root (ADR-0038). ListTrustSource then offers the read set of SPEC-BC-0001 §11.2: isCredentialAcceptable(issuerId, iat), isCredentialSchemaAcceptable(issuerId, schemaId, iat), isRecognizedBy, schemaContentHash, statusAnchor, relyingParty, relyingPartyByDnsName, issuer, schema, isWalletProviderKey, freshness(). Three-valued answer: YES | NO | UNKNOWN; UNKNOWN → INDETERMINATE (CMP4). Services reload the list periodically (issuer service TAMGA_TRUST_RELOAD_SEC, verifier TAMGA_VERIFY_TRUST_RELOAD_SEC).
The same dns_name in more than one national list (ADR-0075; 2026-11-05). relyingPartyByDnsName (and the terminal group answers) select the record with this rule; the result does not depend on the order in which lists are loaded:
- No record that is not revoked (not
REVOKEDorRETIRED;SUSPENDEDcounts as not revoked): the record whose status changed last is returned (not ambiguous). - One record not revoked: it is taken only if every other record's last
REVOKEDentry names its country in thereassigned_tofield. A reassignment is recognised only throughreassigned_to; the free-textreasonis not read. - Otherwise (two records not revoked, a revocation with no reassignment record or naming another country) the name is ambiguous:
null, terminal groups inactive (fail closed). A re-registration after revocation in another country (RO2) therefore stays ambiguous until a network-level record exists.
7. Contract mapping and moving to the chain
Accepted, implementation in progress (2026-11-04): ADR-0073 and ADR-0074 extend the replay and the mapping (migration mode, hard revocation, schema version digests, relying party identity, network-level records); the contract side is in the
SPEC-BC-0001version notes, and this section is updated withtrust:chain-replay.
| List field | Contract call |
|---|---|
root_cas[] | RootCARegistry.registerRootCA / rollover / retire / revoke |
issuers[] | IssuerRegistry.registerIssuer / suspend / revoke(revokedAt) / setSuccessor |
issuers[].schema_authorizations[] | IssuerRegistry.setSchemaAuthorization(issuerId, schemaId, from, until) |
lotl.schemas[] | Governance proposal → SchemaRegistry.registerSchema(vct, contentHash, NETWORK) |
relying_parties[] | RelyingPartyRegistry.register / setScope; suspension, reinstatement and revocation with the list date (suspendRelyingPartyAt, reinstateRelyingPartyAt, revokeRelyingPartyAt). Reassignment between countries (ADR-0075): the record in the old country's list becomes REVOKED; its history entry carries the structured reassignment record reassigned_to: "<CC>" and the reason (reassignment to <CC> (approval <ref>)) (rp-status <dns_name> REVOKED --reassigned-to <CC> --approval <ref>). The loader takes the new country's record only through this field; without it the name is ambiguous (null; §6) |
anchors kind=status_list | StatusListRegistry.registerList(issuerId, uri, size, bits) (first line) + publishList(listId, hash, version, published_at) |
anchors kind=schema | SchemaRegistry contentHash |
lotl / tl-<cc> version (whole file) · last line of anchors.jsonl | Trust list anchor registry — anchorList(listKey, version, sha256(jws), previousHash, issuedAt) · anchorLogHead(logKey, seq, sha256(line), ts); digest only, no content (ADR-0051; SPEC-BC-0001 §15). The chain is a projection: on conflict the signed list prevails and the chain's answer is never required for verification. Flag TAMGA_CHAIN_ENABLED, off in production |
wallet_providers[], zk_circuits[], external_lists[], eaa_categories, signers, operator, national_lists[] slots and roles, catalogue | NetworkRegistry network-level records (ADR-0074 K3; SPEC-BC-0001 §16.5); a record that leaves the list becomes RETIRED |
Migration: the archive/ versions are replayed in order as contract calls; the migration is not complete until TrustSource(list) and TrustSource(chain) give the same answers to the conformance/vectors/trust queries (TL10; ADR-0009 K7). Hand-over: only the operator field changes.
8. Invariants
| # | Invariant |
|---|---|
| TL1 | Every list has operator.status, which is "provisional" throughout the list stage; on_behalf_of is never left empty. |
| TL2 | List and anchor log versions increase monotonically; every version carries the hash of the previous one; no line/record is deleted (status changes are appended to status_history). The only exception is test records removed before the first participant institution enters the list (ADR-0081). |
| TL3 | Lists and anchors are signed with ≥2 rolling certificates; a rotation is announced ≥30 days in advance; the new key is signed with the old one. (Demo deviation S-6 declared.) |
| TL4 | No component other than TrustSource interprets the list files. |
| TL5 | Verification with a list whose next_update has passed, or that cannot be reached, produces INDETERMINATE; never ACCEPTED, never REJECTED. |
| TL6 | A loader that sees an unknown list_format_version stops and raises an alarm; it does not accept. |
| TL7 | A national list is signed only by that namespace's signing key; operator proxy is declared with operator.on_behalf_of. |
| TL8 | Tamga does not issue PID; pid_providers[] is empty throughout the list stage. Tamga's provisional identity attestation (ADR-0011) is an issuers[] record (category: IDENTITY, class: EAA, assurance: I2; ADR-0022) and is superseded with successor_id once a state PID provider is appointed. |
| TL9 | A schema's registered_at and status_history.since are permanent; a rebuild cannot change them (time of the first anchor). |
| TL10 | Moving to the chain is not complete until the replay of the list archive and the equivalence test pass. |
| TL11 | No list, anchor log or change log contains personal data, credentials or credential hashes. |
| TL12 | The anchor log is archived only with a signed checkpoint: archived lines remain under archive/ (not deleted), the checkpoint links to the archive's last line with previous_hash and to the archive file with archive.sha256, and carries the final state (state) produced by the archived lines; the loader does not continue the chain without verifying the signature of the checkpoint in the first line, the condition seq = seq_to + 1 and the presence of state; archiving never lowers the visibility of a list or schema; the full history can always be rebuilt from the archives (TL10). |
Security and privacy notes
- Known weakening (ADR-0009 K3): the anchor relies on a single operator signature; if the operator and an institution act together, equivocation is possible — the public log, the
CHANGELOG, the quarterly transparency report (G8) and independent audit deter this. Pilot limitations statement, items 5–6. list_uriis opaque;status_anchorsdo not encode the institution or cohort (S8). IP addresses are not logged (G2).
Open issues
- Chain counterpart of
wallet_providers[](ADR candidate). - ETSI 119 612 XML/XAdES projection generator — CLOSED (2026-10-29, ADR-0066): the generator is in
apps/trust-publisherand published in the sandbox; on the real network it opens with the foundation, postal addresses and signer. - ≥2 rolling certificates (S-6) and the signing key in a KMS — before the pilot.
Related documents
ADR-0009 · ADR-0010 · SPEC-BC-0001 · SPEC-ID-0002 · SPEC-CRED-0003 · SPEC-SCHEMA-0001 · ARCH-0003 · FW-ARF-0001 · FW-RB-0001
Status
In force — version 1.0.0 (2026-10-02).
Version note (2026-11-05): §5 condition for opening the chain (lowest loader @tamga-network/trust 0.8.1; new line types once consumers are updated), the bits/size format rule and the list_view monotonicity key; §6 the selection rule for the same dns_name in more than one national list and relyingPartyByDnsName in the read set; §7 the structured reassignment record (reassigned_to). Behaviour ships with @tamga-network/trust 0.8.1; the ADR-0075 decision is unchanged.
Version note (2026-11-11; implementation notes — the rules are unchanged). @tamga-network/trust and the list publisher 0.8.3:
- §1.4, TL9 — the previous version comes from the signed file. The publisher reads the next version number, the previous version hash and the permanent
registered_at/status_historyof schemas from the signed.jwsof the previous publication, verifying its signature against the list signers named in the source. The unsigned.jsoncopy is not read; publication stops if the previous list's signature cannot be verified. - TL1. For the list operator (
lotl,tl-<cc>and the LOTL national slots) the publisher requiresstatus: "provisional"and a non-emptyon_behalf_of. The loader schema still recognisesdesignated; publishing with that value opens after the handover decision. - TL2. The record-removal check also counts root CAs, schemas (national list and LOTL) and, in records that stay in the list, scopes, schema authorizations and
status_historyrows; an approved removal record carries them as optional counts (root_cas,schemas,scopes,schema_authorizations,status_history; 0 if absent). Second review (2026-11-12): a removal record is bound to one version transition (previous_version: the number of the signed version before the removal, required;previous_version_hash: the digest of that version's.jws, optional) and does not pass in any other. History rows are kept with their content: astatus_historyrow must stay exactly as it was (a row whoseinvalidates_fromis changed counts as removed); in a schema authorization row the only free change is closing an open period (valid_untilabsent → a date). Also counted now: an issuer'sdelegate_keysrows and thenational_lists,wallet_providersandexternal_listsrecords of the LOTL (optional counts of the same names): when a status-list key is renewed the old key is not dropped from the list, it stays with its end date (valid_to). The validity fields of a scope (scopes) and a terminal group (terminal_groups) row that stays in the list are protected too:valid_fromdoes not change;valid_untilchanges only towards closing an open period (an earlier end for a row with no end or with an end that has not passed). A period that has ended is not changed, and no end is moved later or removed: a new period is a new row with a new identifier. A row changed in any other way counts as removed; descriptive fields such as the purpose text can be edited. When the version jumps by more than one the loader cannot verify the hashes in between; it rejects only the contradiction "the jumping version names the last seen version as its predecessor" (the full check uses the archive). - TL11. The publisher applies an allow-list of known fields per record type in the source: an unknown or computed field (
client_id,rp_id,issuer_id,ca_id, fingerprints — ADR-0034 CI3) stops publication; it is not dropped silently. The form ofcontactis checked (support_urian https address,emailan e-mail address,phonein international form); whether an address belongs to a person cannot be checked by machine. The--reasontext of the status commands (it enters the list and the change log) passes the public-text filter: an e-mail address, a long digit sequence, a link or what looks like a person's name is refused. - §4 — form of
dns_name. Lower-case labels separated by dots; no trailing dot. A name that appears in two records of one list is ambiguous (ADR-0075 implementation note). - §6 — anchor freshness in the directory loader.
loadTrustSourceFromDiruses 365 days as the anchor-log freshness limit when none is given (2 hours in the core loader): this path is also used with development and test folders where the hourly heartbeat does not run. With this default a stopped anchor log does not make the source stale (freshness comes only from the lists'next_update); a service that also wants anchor-log freshness as a condition passes the limit itself (anchorMaxAgeMs, e.g. 2 hours). The reference verifier (Tamga Verify, 2026-11-12) passes the limit when its public address is HTTPS: the default is 3 hours, set withTAMGA_VERIFY_ANCHOR_MAX_AGE_SEC; if the last anchor is older, the source is stale and the result is INDETERMINATE (not REJECTED). In local development (http) the 365-day default applies unless the setting is given. External lists: ADR-0036 implementation note. - Registration commands. They run under
registry.lock(refreshed while held); if list validation fails before a signed list is written, the source file is restored and no line is written to the change log. Without the provisional-operator value, publication stops in the real network (ADR-0070 implementation note).
Version note (2026-11-12; approved by project management). The test-record exception to TL2 is now tied to a decision, ADR-0081 (§4, the TL2 row); publisher behaviour is unchanged. The operator row in §3 states what the designated value means and why it is not published today (ADR-0070 implementation note); loader and publisher behaviour are unchanged.
Version note (2026-11-15; approved by project management) — ADR-0087. §2 adds the revocation list of access certificates: crl/<authority>.crl (RFC 5280 v2 CRL; AKI, CRLNumber, a reasonCode per entry) and access-crl-state.json. The setting is in the registry at national_lists[].roles.access_ca.crl (issuers[{ca, uri}]; not written to the LOTL, on the TL11 allow-list). When a verifier's registration is suspended or revoked, its access certificate enters the CRL in the same publication with privilegeWithdrawn; when the registration ends, with cessationOfOperation; when the certificate leaves the registry, with superseded; there is no certificateHold. If an active registration points to a revoked access certificate, publication stops before the list is signed (AR3). If the authority's key is at the publisher, the CRL is signed on every publication and on the hourly heartbeat; the CRL of an offline authority (the root) is signed on the authority's own computer and the publisher checks and publishes it. The status list of registration certificates (§2 status/wrprc/<n>, ADR-0068) is unchanged; registration certificates do not enter the CRL.
Version note (2026-11-18; approved by project management) — ADR-0090. The CRL's publication address moved from the trusted-list host to a separate host: crl.tamga.network (sandbox crl.sandbox.tamga.network), path /<authority>.crl; the same file is served over http and https without redirection, and the /crl/ path on the trusted-list host is closed. The file is still crl/<authority>.crl in the publication folder. The uri setting is the CRL's http address; the distribution point in certificates is a single point with two names (first http, then the https address of the same path; EN 319 412-2 GEN-4.3.11-4).