Andamio Protocol
The four-layer on-chain model behind Andamio credentials — and the transaction lifecycle every Andamio app shares.
Andamio is a set of deployed Cardano smart contracts that issue and verify credentials. You don't have to build on the protocol directly — the API handles transaction building, signing flows, and state sync for you. This section explains what the protocol does underneath so you can reason about what your app is anchoring on-chain.
Three pages cover it:
- This page — the four-layer model and the transaction lifecycle every Andamio transaction shares.
- Validators — the 12 on-chain validators and the actions each authorizes, generated from the compiled contracts so it can't drift.
- Transaction sequences — interactive walkthroughs of the workflows that issue a credential, from onboarding to claim.
The four-layer model
Andamio's on-chain state is organized into four nested layers. Each layer governs who can act on the layer below it.
| Layer | What it holds | What it governs |
|---|---|---|
| Global registry | A person's on-chain identity (their Access Token) and the registry of local states attached to it | Who exists in the protocol and what credentials/commitments they carry |
| Instances | Organization-level governance | Who is allowed to create and administer courses and projects |
| Course | Course modules, enrollments, assignment commitments, and assessments | The learn-and-earn loop that issues a course credential |
| Project | Project tasks, treasury funds, and contributor commitments | The contribute-and-earn loop that issues a project credential |
Course and Project are deliberately symmetric — both run a five-beat loop (create → populate → commit → assess → claim). The transaction sequences make that symmetry concrete.
Two design patterns worth knowing
Hash on-chain, data off-chain
Andamio stores hashes on the blockchain, not raw data:
On-chain: assignment_info: "sha256:abc123def456..."
Off-chain: evidence: { url: "https://...", text: "My submission notes" }| Aspect | On-chain | Off-chain |
|---|---|---|
| Stored | Commitment hash (32 bytes) | Full evidence payload |
| Cost | Minimal (~0.02 ADA) | Database storage |
| Privacy | Public but opaque | Access-controlled |
| Verifiability | Anyone can verify | Hash proves integrity |
The chain holds a small, fixed-size commitment; the raw evidence (URLs, text, files) never touches it. Anyone can later prove that a piece of off-chain evidence matches its on-chain hash — that's what makes a credential verifiable without exposing private work.
Check–Effect–Interact (CEI)
Every Andamio transaction follows a layered CEI pattern across the client and the gateway:
| Phase | Client | Gateway |
|---|---|---|
| Check | Validate params | Validate eligibility, balances, permissions |
| Effect | Sign transaction in wallet | Confirm transaction on-chain |
| Interact | Submit to blockchain | Sync state to the database |
The client never writes to the database directly — the gateway syncs state only after on-chain confirmation. The blockchain stays the source of truth.
The transaction lifecycle
Every Andamio transaction — minting an Access Token, committing to an assignment, claiming a credential — moves through the same six steps. The transaction sequences link here rather than repeating this, so learn it once:
| Step | Who | What happens |
|---|---|---|
| Build | API / gateway | Builds an unsigned transaction (CBOR) from your request |
| Sign | User's wallet | The user approves and signs in their browser wallet (CIP-30) |
| Submit | User's wallet | The signed transaction is submitted to Cardano |
| Register | Your app | Calls the registration endpoint with the transaction hash and type |
| Confirm | Gateway (automatic) | Polls the chain until the transaction is on-chain |
| Update | Gateway (automatic) | Syncs the confirmed on-chain state into the Andamio database |
confirmed is not the finish line. The gateway reaches confirmed when the transaction is found on-chain, but the database hasn't synced yet. Wait for updated before you refetch data — only then is the off-chain state fresh.
You build the UX; Andamio handles the credential. For the request/response details and code, see the API docs.
Where to go next
- Validators → — what each of the 12 on-chain validators does, and the tokens they mint or burn.
- Transaction sequences → — interactive, step-by-step walkthroughs of the credential workflows.
- Contract verification → — verify the deployed contracts against published script hashes.