Get started
This page is the first stop for anyone who wants to build something with Tamga: it shows which path fits you, which package to install and how to try things locally.
When to read: on day one, before writing any code. From here you move on to the guide for your role. If you would like a look at the ideas first, the Concepts section is short and plain.
What does Tamga do?
Institutions issue credentials to people: a diploma, a student certificate, an identity credential, a ticket. Tamga puts these credentials into the wallet on the person's phone. Anyone who needs to see one (an employer, a website, an event gate) verifies it in seconds, without asking the institution. Each time, the person shares only the fields that were asked for.
The standards are the same as the EU digital identity wallet: SD-JWT VC (Selective Disclosure JWT Verifiable Credential)The JSON-based credential format with selective disclosure, used for online presentation in the EUDI Wallet and in Tamga. and ISO mdocThe ISO/IEC 18013-5 mobile document format, encoded in CBOR; used for in-person presentation and for the mobile driving licence.credentialsA digital document signed by an issuer and held in the person's wallet; the person shows only the fields that are asked for., OpenID4VCI (OpenID for Verifiable Credential Issuance)The protocol an issuer uses to deliver a credential to a wallet. for issuance, OpenID4VP (OpenID for Verifiable Presentations)The protocol a verifier uses to request a credential from a wallet and receive the presentation. for presentation, X.509 for institutional identity, and signed 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..
This site is for developers. Roles, rules and the conditions for taking part are in Tamga ARF; the general overview is at tamga.network.
Which path is yours?
| What do you want to do? | Guide | Package |
|---|---|---|
| Add "Sign in with Tamga" to your website | GUIDE-0001 | @tamga-network/verifier (+ /web) |
| Verify credentials on your server (hiring, campus, age, ticket gate) | GUIDE-0002 | @tamga-network/verifier, @tamga-network/trust |
| Register your institution as an issuer | GUIDE-0007 | — |
| The IT side of joining: application file, keys, setup check | GUIDE-0014 | tamga-onboard |
| Register your site as a verifier | GUIDE-0008 | — |
| Issue your institution's credentials to people's wallets | GUIDE-0003 | @tamga-network/issuer (+ /client) |
| Build a Tamga-compatible wallet | GUIDE-0005, checklist GUIDE-0010 | @tamga-network/wallet-core |
| Read trust lists, and later run a network node | GUIDE-0006 | @tamga-network/trust |
| See both modes together: signed lists and a shared ledger, which guide for whom | GUIDE-0016 | — |
| Connect your country's trust list to the network | GUIDE-0011 | apps/trust-publisher |
| Operate the national trust list (keys, publication, monitoring) | GUIDE-0017 | apps/trust-publisher |
| Run a node on the shared ledger later (preparation) | GUIDE-0015 | network/ |
| Set up a chain test network on your computer or test server (Besu, step by step) | GUIDE-0018 | network/testnet/ |
| Show that your application follows the rules | GUIDE-0009 | conformance/ |
| Test end to end without touching the real network (test network) | GUIDE-0013 | sandbox.tamga.network |
| See working, tested code for all of the above | GUIDE-0004 | — |
| When something goes wrong | GUIDE-0012 | — |
Try it locally
You need Node.js 22 and Git. Clone the repository and set up the development environment:
git clone https://github.com/tamga-network/tamga-network && cd tamga-network
npm install
npm run setup # development PKI → schema catalogue → trust lists → verification
npm run check # tests + type check
npx vitest run examples # four examples, with the real packagesnpm run setup produces a local root certificate, sample institution certificates and signed trust lists (ops/pki/; private keys never enter the repository). You can test your code against these local lists. For the conformance vectors: npm run conformance (conformance/).
Packages
| Package | What it does | Who uses it |
|---|---|---|
@tamga-network/core | digests, identifier derivation (issuer_id, schema_id), certificate helpers | everyone (indirectly) |
@tamga-network/trust (+ /core) | loads and verifies the signed trust lists; one read interface, TrustSource | verifier, wallet, issuer |
@tamga-network/schemas | credential type catalogue: type metadata, JSON Schema, integrity digests | issuer, verifier |
@tamga-network/sd-jwt | SD-JWT VC: selective disclosure, holder binding, status list | issuer, verifier |
@tamga-network/mdoc | ISO 18013-5 mdoc: CBOR, COSE, issuance and verification | identity issuer, verifier |
@tamga-network/issuer (+ /client) | credential creation, OpenID4VCI; /client for the hosted service | issuer |
@tamga-network/verifier (+ /web, /zk) | verification pipeline, three-valued result, OpenID4VP; /web page kit, /zk zero-knowledge proofs | verifier, website |
@tamga-network/wallet-core | wallet core: keys, receiving credentials, local checks, presentation (Node + React Native) | wallet developer |
@tamga-network/zk (+ /node, /react-native) | wallet-side zero-knowledge prover (mdoc, Longfellow); /react-native native prover on the phone, /node on the desktop | wallet developer |
@tamga-network/onboard (command tamga-onboard) | onboarding tool: application file, keys, setup and listing check; state / operator node steps; local MCP server (GUIDE-0014, GUIDE-0015) | institution IT team, node operator |
Every package has its own page in the SDKs section. The packages are published on npm as the 0.8.7 test release; the stable 1.0.0 comes when everything is ready. In test releases the API may change. Each release is built from this repository; eight packages are published by GitHub Actions and carry provenance, while @tamga-network/zk is published manually without provenance (its Android native libraries cannot yet be built in CI). The first release of @tamga-network/onboard (0.8.2) was also made by hand without provenance (npm trusted publishing can only be set up for a package that already exists); later releases come from GitHub Actions.
Addresses
| Address | What | Who uses it |
|---|---|---|
https://trust.tamga.network | signed trust lists (lotl.jws, tl-tr.jws), anchor log, keys/ | everyone — through TrustSource |
https://tamga.network/trust-anchor | root fingerprints (you pin them in your configuration) | everyone |
https://schemas.tamga.network/v1/catalogue.json | credential type catalogue | issuer, verifier, wallet |
https://issuer.tamga.network/{institution} | hosted issuer service (OpenID4VCI + /api/v1) | issuer, wallet |
https://status.tamga.network/{opaque} | status lists (Token Status List) | verifier |
https://verify.tamga.network | Tamga Verify: hosted verifier + page kit (/tamga-verifier.js) | website, verifier |
https://id.tamga.network | provisional identity credential service | wallet |
What is ready today?
| Part | Status |
|---|---|
| Packages | 0.8.7 test release on npm; the stable 1.0.0 comes when everything is ready (the API may change in test releases) |
| Hosted verifier | running: the website's server opens the presentation with a signed statement, and the values are given only to it, only once (ADR-0017); policies are fixed for now |
| Hosted issuer | running: a scoped API key per institution (ADR-0016) |
| Trust anchor | signed trust lists (ADR-0009); the Tamga operator registers issuers and verifiers |
| Wallets | the network runs no wallet; it lists the wallet providers that follow its rules (ADR-0042); the first wallet's provider, Tamga Wallet's TAMGA-WP-1, is ACTIVE in the production and sandbox lists |
| Privacy | a pseudonym per site (ADR-0031); age verification with a zero-knowledge proof (ZK) — the verifier side is live; the wallet side is wired through @tamga-network/zk, the Android native library is ready, iOS is pending (ADR-0032) |
| Sandbox | live: a single test network with the same rules as the real network, open to everyone; real identity verification with daily/monthly caps (GUIDE-0013) |
| Ledger (Besu/QBFT) | designed, contracts written; opens once there are at least two independent validator operators (GUIDE-0006, preparation: GUIDE-0015, test network: GUIDE-0018) |
Rules for every integration
- Do not log personal data. Credential field values and the status index never go into logs or audit records (SPEC-API-0001 AP3–AP4).
- Ask only for the fields you need. Your request cannot go beyond the scope of your trust list entry (AP6).
- The result has three values:
ACCEPTED,REJECTED,INDETERMINATE. "Cannot be verified right now" does not mean the credential is bad (AP2). - Read trust data only through
TrustSource; do not interpret the list files yourself. - All the binding rules for your role: Tamga ARF — Annex B, Tamga Rulebook.