Skip to content
GUIDE-0006GuideIn forceversion 1.0.05 November 2026

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 ​

ts
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 date

Working 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 rootFingerprints value once from tamga.network/trust-anchor and 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_update date or cannot be downloaded, answers become UNKNOWN and verification returns INDETERMINATE — never ACCEPTED, never REJECTED.
  • 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 ​

FileWhat
lotl.jwsList of Trusted Lists: country lists, credential types, wallet providers, operator
tl-tr.jwsTürkiye list: root certificates, issuers (with their authorisations), verifiers (with their scopes)
anchors.jsonlhourly signed anchor log (status list and schema digests are anchored here)
keys/root-fingerprints.jsonroot fingerprints (the same as on the tamga.network/trust-anchor page)
CHANGELOG.mdwho 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:

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/):

ContractWhat it holds
Governancemembership and voting (states, 2/3)
RootCARegistrynational root certificates
IssuerRegistryinstitutions, status history, credential type authorisations
RelyingPartyRegistryverifiers and their scopes
SchemaRegistrycredential types and integrity digests
StatusListRegistryanchors of status list publications (not the bits)
CrossRecognitionrecognition between countries
TrustQueriesthe single read surface (the ledger side of TrustSource)

For node and validator operators:

RoleWhat it doesRequirement
Validatorproposes and signs blocksan independent institution, written acceptance, key in an HSM
Full nodevalidates and reads the chain; does not signan 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 ​

CodeWhat it says
Single trust interfacetrust data is read only through TrustSource; list files are never interpreted by hand
Stale listif the list is stale or cannot be downloaded, the answer is UNKNOWN and the result INDETERMINATE
ARCH-0003 CMP2stop and raise an alarm on an unknown format version
SPEC-BC-0001 DP1no contract stores personal data, credential content or a credential digest