Skip to content
ADR-0038Architecture decisionAcceptedversion 1.0.04 November 2026

Partly changed by ADR-0040 and ADR-0041 (2026-10-04; ADR-0040 updated 2026-10-05): real identity verification steps can be tried in the sandbox by anyone, with the real network's provider account, under daily/monthly caps and with minimal data (K4 and SB3 changed); institutions can open their own test institution and try it in the Institution Console, which runs again in the sandbox ("no console" in K1 and institutions' self-registration in K7 changed). The other points stay in force.

In brief ​

Before a wallet, an institution or a verifier joins the network, it wants to try everything. Today that means either setting up a local test environment on one's own computer or using the real services. There are also no institutions with an official agreement yet; end-to-end testing needs example institutions and example credentials.

This decision opens a separate test network next to the network: sandbox.tamga.network. Everything there behaves like the real thing; only the trust root, the keys, the lists and the data are separate and fake.

Context ​

  • ADR-0037 says the network runs reference services "so that the network works, can be tried out and institutions can join". A test network falls within that definition; it is not sold and is open to everyone on the same terms.
  • Joining the network depends on conformanceProof that an implementation follows the rules, shown by passing the published test vectors and checks. (Tamga ARF, Trust Framework §4.3). The most natural way to test conformance is an environment that behaves like the real network but never touches it.
  • In the EU, too, wallets and verifiers are tested in environments separate from the real trusted lists and at interoperability events.
  • Today's local development environment (development PKI, local trust lists) runs on a single computer only; a wallet on a phone, another institution's server or a verifier cannot reach it.

Decision ​

K1 — A separate test network. Tamga Network runs a test network separate from the real network. Its address is sandbox.tamga.network (landing page and guide); the services inside sit on sub-names of that address in the same layout as the real network: trust.sandbox, issuer.sandbox, status.sandbox, verify.sandbox, wallet.sandbox, id.sandbox (….sandbox.tamga.network). The services therefore behave as in the real network; a wallet or verifier switches by changing only the domain. The institution console does not run in the sandbox: example institutions, people and permissions come from seed data.

K2 — Complete separation. The sandbox has its own test root certificate, its own signing keys and its own list of trusted lists (LOTL (List of Trusted Lists)The signed list that points to the countries' trust lists, their signers and their recognition status.). The sandbox list marks itself clearly as "test". The real network's root signs nothing in the sandbox; the sandbox root appears in no list of the real network. Wallets and verifiers of the real network do not trust the sandbox; a wallet connects to the sandbox only when explicitly switched in a developer setting, and shows it on screen.

K3 — Visible marking. Every credential issued in the sandbox carries that it is a test credential (the test institution's name and the test list); sandbox pages and wallet screens show a "Sandbox · test" mark. A sandbox credential cannot be used in a real transaction, because a real verifier does not recognise its root.

K4 — Fake data only. The institutions, people and credentials in the sandbox are examples. No real personal data is entered; identity verification uses a fake provider. The example people's identity numbers are clearly fake.

K5 — Resettable. Sandbox data returns to its initial state whenever needed, and regularly on its own. Nothing in the sandbox is expected to persist.

K6 — Content. The sandbox contains at least: test lists and the anchor log; at least one example institution per credential type (education, identity, event ticket, contact credentials); example people; a test verifier and example verification pages ("Sign in with Tamga", age check, diploma check, ticket gate); a test wallet provider; a usage guide. The example institutions may carry real institution names to make the tests realistic. In that case every sandbox page and the usage guide state clearly that the names are used only to make the test environment realistic, that there is no relationship or agreement with these institutions, and that the credentials are signed with a test key and are therefore not valid anywhere; the institutions' logos are not used.

Note (2026-10-06, project management): the example university institution in the sandbox is only a test institution; none of the example institutions implies a relationship or agreement with a real institution. The test-key warning and the logo rule do not change.

Change (2026-10-06, ADR-0042 K3): wallet.sandbox in K1 and the "test wallet provider" in K6 are not network services. The network runs no wallet provider; in the sandbox too every wallet runs its own provider and registers it in the sandbox list (today with project management approval). The former wallet.sandbox.tamga.network was removed on 2026-10-06; the sandbox has no wallet provider of its own, and Tamga Wallet's provider (provider.tamgawallet.com) is registered in the sandbox list. There is a single sandbox; no separate wallet sandbox is set up.

K7 — Later steps need their own decision. External participants adding their own institutions, verifiers or wallet providers to the sandbox list themselves (self-service registration), and a conformance service that tests wallets automatically and reports, are later stages; each is decided separately before it opens.

Invariants ​

CodeRule
SB1The sandbox root certificate and the sandbox list signers appear in no list of the real network; the real network's root and signing keys sign nothing in the sandbox.
SB2The sandbox list of trusted lists marks itself as test; a wallet or verifier configured for the real network does not accept the sandbox list.
SB3The sandbox's default identity verification is the fake provider (quick trial) and example identity numbers have an invalid form; a real person's data enters only through the real path of ADR-0040 that the person chooses, and within its limits (warning and confirmation before scanning, daily/monthly caps, the real identity and document numbers are not written into the credential, the provider session is deleted at once, everything is deleted at the nightly reset).
SB4Every credential issued in the sandbox and every screen connected to the sandbox visibly states that it is a test.
SB5Sandbox data can be reset at any time; no process connected to the sandbox assumes persistence.

Rationale and alternatives ​

OptionOutcomeWhy
Local development environment onlyrejectedA wallet on a phone, other institutions' servers and verifiers cannot reach it; no end-to-end testing.
"Test" institutions in the real networkrejectedTest credentials would be valid at real verifiers; the trust list would be polluted.
Test network with its own root and listsacceptedBehaves like the real network but cannot mix with it by any path; everyone tests in the same environment.
Paths under one address (sandbox.tamga.network/issuer/…)rejectedThe services are written to run at the root of their address (page links, redirects, cookies, well-known addresses); a path prefix needs separate adaptation in every service and behaves differently from the real network.
One sub-name per service under sandbox.tamga.networkacceptedSame layout as the real network; service code does not change.

Consequences ​

  • The sandbox runs the real network's services (list publisher, issuer, verifier, wallet provider, identity service) with separate settings, separate keys and a separate database. There is no institution console in the sandbox; example institutions, people and permissions are set up from seed data and return to their initial state at every reset.
  • Tamga Wallet and any wallet that follows the network's rules can switch to the sandbox in a developer setting; the sandbox root is kept separately inside the wallet and never mixes with the real root.
  • A "Sandbox" guide is added to the developer docs, a short explanation to Learn, and a note to the ARF stating that the test network is not part of the real network.
  • Automated wallet analysis and conformance reports are handled separately later.

Status ​

Accepted — 2026-10-03 (project management approval; the verbatim quote is in the private approval record). K4 and SB3 changed with ADR-0040 (real identity verification in the sandbox; open to everyone since 2026-10-05); "no institution console" in K1 and institutions' self-registration in K7 changed with ADR-0041 (institution test accounts) (2026-10-04). The network running the test wallet provider in K1/K6 changed with ADR-0042 (2026-10-06): in the sandbox the wallet runs its wallet provider.

Note (2026-11-04): the real institution name and the relationship wording in the 2026-10-06 note were removed ("an example university institution"); the decision content is unchanged (project management).