Trust lists and the network
This guide is for developers who read Tamga'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. in their own application, and for operators who will run a network node later.
When to read: when you are writing a verifierThe party that checks a presented credential: signature, issuer in the trust list, status and policy. Also called relying party., a wallet or an issuerThe institution that signs and issues credentials: a university, a professional body, a public institution or a company. service and need to answer "who is this institution, and may it issue this credential?". The short version: Trust lists and federation.
How it works
In Tamga, three questions are answered by the trust anchorThe root key or certificate a verifier trusts first; everything else is checked back to it.: who is this institution, may it issue this credential, and what may this verifier ask for?
- Today the anchor is the signed trust lists, signed by the Tamga operator and downloadable by anyone.
- Later, once at least two independent validator operators take part, the same entries move to a permissioned Besu/QBFT ledger (ADR-0009).
Your application uses the same interface in both cases: TrustSource. Your code does not change on the day of the switch.
1. Reading the trust lists
import { fetchListTrustSource, verifyJws } from "@tamga-network/trust";
const { source } = await fetchListTrustSource(
"https://trust.tamga.network",
async (url) => {
const r = await fetch(url);
return { status: r.status, text: () => r.text() };
},
{ rootFingerprints: PINNED_ROOTS, verifyJws }, // root fingerprints fixed in your configuration
);
source.issuers(); // registered institutions
source.relyingPartyByDnsName("example.com"); // a verifier's entry (by its permanent domain name) and the fields it may ask for
source.relyingParty("x509_hash:…"); // the same entry, by the request's client_id
source.isCredentialAcceptable(issuerId, iat); // "YES" | "NO" | "UNKNOWN" — as of the credential's issuance dateWorking example: GUIDE-0004 §4 (examples/04-check-institution). For React Native or the browser, use @tamga-network/trust/core (no Node APIs; the signature verifier is passed in — ADR-0015).
A verifier entry's permanent identifier is its domain name (dns_name); the client identifier is the x509_hashA client identifier scheme from HAIP: the identifier is the base64url SHA-256 hash of the relying party's access certificate. value computed from the certificate (ADR-0034). That is why there are two ways to read it: relyingPartyByDnsName() and relyingParty().
2. Root pinning and freshness
- Pin the root. Take the
rootFingerprintsvalue once fromtamga.network/trust-anchorand write it into your configuration. Trusting the address you download the list from is not enough; the signature must chain to the root you pinned. - Freshness. If the list is past its
next_updatedate or cannot be downloaded, answers becomeUNKNOWNand verification returnsINDETERMINATE— neverACCEPTED, neverREJECTED. - Unknown format version. Stop and raise an alarm; do not accept it.
- Caching. Prefetch the lists and the status listsA compressed, signed list in which each credential has one position that tells whether it is valid, suspended or revoked.; do not go to the network at verification time.
3. Published files
| File | What |
|---|---|
lotl.jws | List of Trusted Lists: country lists, credential types, wallet providers, operator |
tl-tr.jws | Türkiye list: root certificates, issuers (with their authorisations), verifiers (with their scopes) |
anchors.jsonl | hourly signed anchor log (status list and schema digests are anchored here) |
keys/root-fingerprints.json | root fingerprints (the same as on the tamga.network/trust-anchor page) |
CHANGELOG.md | who changed what, and when |
Format: SPEC-TRUST-0001. The lists are versioned and each carries the digest of the previous one; no line is deleted; they are re-signed at least every 90 days.
4. Registration
Issuers and verifiers are added to the list by the registrar (today Tamga, provisionally); changes are published within 24 hours. The application file, the certificate signing request and the mandatory registration data are covered in separate guides:
- As an issuer: GUIDE-0007
- As a verifier: GUIDE-0008
TrustSource carries the status history of every entry; the entry of an ended authorisation is not deleted, so credentials issued earlier still verify correctly.
5. In depth: the ledger stage
Not open yet
The ledger opens with the written acceptance of at least two independent validator operators (ADR-0009 K4). This section describes the configuration for that day and what it means for your application; today it is a development configuration.
Nothing changes for your application. The ledger implementation of TrustSource gives the same answers to the same questions; this is tested with the conformance vectors (conformance/). Institution identifiers (issuer_id, ca_id) and credential types (vct) do not change. A new source address and the contract addresses are added to your configuration.
Network. Hyperledger Besu, QBFT consensus, a permissioned network (only permitted nodes connect). No personal data, no credential and no credential digest is ever written to the ledger; it carries only the trust entries. Status lists stay off the ledger (ADR-0008).
Contracts (Solidity, compiled and tested with Hardhat; the source code, tests and specification have been in the public repository since 2026-11-04, contracts/):
| Contract | What it holds |
|---|---|
Governance | membership and voting (states, 2/3) |
RootCARegistry | national root certificates |
IssuerRegistry | institutions, status history, credential type authorisations |
RelyingPartyRegistry | verifiers and their scopes |
SchemaRegistry | credential types and integrity digests |
StatusListRegistry | anchors of status list publications (not the bits) |
CrossRecognition | recognition between countries |
TrustQueries | the single read surface (the ledger side of TrustSource) |
For node and validator operators:
| Role | What it does | Requirement |
|---|---|---|
| Validator | proposes and signs blocks | an independent institution, written acceptance, key in an HSM |
| Full node | validates and reads the chain; does not sign | an entry in the permission list |
The setup steps (permission list, node declaration, validator voting, RPC protection) are in GUIDE-0015 today, as preparation, and trying them step by step on a test network in GUIDE-0018; the genesis and the network topology are published when the ledger stage opens. During the switch, the list archive is replayed into contract calls; the switch is not complete until both implementations pass the same conformance vectors.
Rules
| Code | What it says |
|---|---|
| Single trust interface | trust data is read only through TrustSource; list files are never interpreted by hand |
| Stale list | if the list is stale or cannot be downloaded, the answer is UNKNOWN and the result INDETERMINATE |
| ARCH-0003 CMP2 | stop and raise an alarm on an unknown format version |
SPEC-BC-0001 DP1 | no contract stores personal data, credential content or a credential digest |
Related
- Format: SPEC-TRUST-0001 · Ledger data schema:
SPEC-BC-0001· Institutional identity: SPEC-ID-0002 - Rules: Tamga ARF — Architecture §3 and §8