Transaction State Machine

How Andamio tracks every transaction from build to database synchronization — the lifecycle, states, monitoring, and integration patterns.

Looking for individual transaction specs? The V2 Transactions section has detailed technical reference for each transaction type — inputs, outputs, costs, and datums.

The Happy Path

You build the UX, Andamio handles credentials. Here's what happens for every transaction:

1. User clicks action — your app handles the UI
2. Request transaction — POST to the appropriate build endpoint
3. Return unsigned CBOR — the API builds the transaction
4. Prompt wallet signature — show the wallet popup
5. User approves & signs — CIP-30 wallet API
6. Submit signed tx — wallet submits to Cardano
7. Register for confirmation — tell Andamio to track it
8. Block confirmation — Cardano confirms (~20-30s)
9. Sync DB + push event — gateway syncs, you get notified
10. Display success — update your UI

Lifecycle Diagram

Client Transaction States

The frontend tracks its own state machine during the build-sign-submit flow:

State Transitions

Once a transaction is registered, it enters the state machine and transitions automatically:

All database updates are idempotent — if a sync is interrupted and retried, it produces the same result.

// ❌ WRONG — data will be stale
if (status.state === "confirmed") refetchData();

// ✅ CORRECT — wait for DB sync (~30s after on-chain)
if (status.state === "updated") refetchData();

Architecture Pattern: Check-Effect-Interact (CEI)

Andamio transactions follow a layered CEI pattern across client and gateway:

The client never writes to the database directly — the gateway handles all database synchronization after on-chain confirmation. This ensures the blockchain remains the source of truth.

Data Model: 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" }

Why this pattern?

• Blockchain space is expensive — hashes are small and fixed-size
• Privacy — raw evidence (URLs, text, files) never touches the chain
• Verifiability — anyone can prove off-chain data matches the on-chain hash

Transaction Types

Andamio supports 17 transaction types across three categories:

Global

Course

Project

"No" DB Sync means the blockchain is the sole source of truth for that data. "Yes" DB Sync means the Gateway automatically synchronizes on-chain state to the database after confirmation.

TX Type Mapping

Some build endpoints share the same state machine type. This is intentional — the on-chain action is identical, so Andamioscan indexes them the same way.

Course Assignments

Both use assignment_submit because the on-chain action is the same: spending and recreating the enrollment UTxO with updated assignment info. The state machine's upsert behavior handles both cases correctly.

Project Tasks

The state machine tries the "join" classifier first, then falls back to "task submit" for already-enrolled contributors. From the API consumer's perspective, use project_join for all task commits.

See also: API Integration Guide for the complete endpoint-to-type mapping table.

Integration Flow

The full flow for building, signing, and tracking a transaction:

1. POST /api/v2/tx/{build-endpoint}         → unsigned_tx (+ course_id/project_id for creates)
2. wallet.signTx(unsigned_tx)                → signed_tx
3. wallet.submitTx(signed_tx)                → tx_hash
4. POST /api/v2/tx/register                  → { state: "pending" }
5. GET  /api/v2/tx/stream/{tx_hash}   (SSE)  → real-time state change events
   OR
   GET  /api/v2/tx/status/{tx_hash}  (poll)  → check state periodically

All build endpoints require authentication via Authorization: Bearer <jwt> or X-API-Key: <key>.

Registration

After submitting a transaction to the Cardano network, register it with the state machine:

POST /api/v2/tx/register

{
  "tx_hash": "64-char hex hash from wallet.submitTx()",
  "tx_type": "course_create",
  "instance_id": "optional course_id or project_id",
  "metadata": {}
}

Most transaction types require no metadata. Only three types need it:

Registering the same tx_hash twice returns 409 Conflict.

Commitment Lifecycle

Several transaction types involve commitments — records that link a participant to a piece of work (an assignment or a task). These commitments follow a draft-to-chain lifecycle that gives developers two integration paths.

Two Paths to On-Chain

Draft-first is recommended because it gives users immediate feedback — they can see their pending commitment in the UI before the blockchain transaction confirms. But if a client goes straight to chain (skipping the draft step), the state machine handles it automatically by creating the DB record on confirmation.

Assignment Commitments (Courses)

When a student submits an assignment (assignment_submit):

1. Optional: Create a draft commitment via the API — the student's intent is saved immediately
2. Required: Build and submit the on-chain transaction, then register it
3. Automatic: On confirmation, the state machine either updates the existing draft or creates a new record, setting the status to ON_CHAIN

Status progression: DRAFT → ON_CHAIN → ACCEPTED or REFUSED (after teacher assessment)

Task Commitments (Projects)

When a contributor commits to a task (project_join):

1. Optional: Create a draft commitment via the API
2. Required: Build and submit the on-chain transaction, then register with task_hash in metadata
3. Automatic: On confirmation, the state machine confirms the commitment and links the contributor to the task

Status progression: DRAFT → SUBMITTED → ACCEPTED or REFUSED → REWARDED

Note: The API previously returned a COMMITTED status between DRAFT and SUBMITTED. As of v2.1.1-rc12, the API normalizes COMMITTED to SUBMITTED at read time — commit and submit are the same action on-chain.

Note: A contributor's first commit to a project also "joins" the project by minting a contributor token. Subsequent commits by the same contributor do not mint again. The state machine handles both cases transparently.

Task Drafts

Managers can also create tasks as drafts in the database before publishing them on-chain via tasks_manage. When the on-chain transaction confirms, the state machine automatically matches new on-chain tasks to existing drafts by content hash and updates their status to ON_CHAIN.

Monitoring

SSE Stream Events

Self-Healing

If a transaction is confirmed on-chain but the database update was missed (for example, due to a service restart), the Gateway automatically detects and repairs the inconsistency when related data is next accessed. This is transparent to API consumers — no manual intervention is needed.

Example Flow: Claiming a Course Credential

A complete walkthrough of one transaction from click to completion.

Prerequisites

The Flow

What the User Sees

[Click]       → Button shows spinner: "Building..."
[~2 seconds]  → Wallet popup appears
[Sign]        → Button: "Submitting..."
[~1 second]   → Toast: "Credential claim submitted"
[~30 seconds] → Toast updates: "✓ Credential claimed!"

CEI Pattern Applied

This transaction has DB Sync: No because the credential NFT in the wallet is the sole proof of completion — the blockchain is the source of truth.

See also: Claim Course Credential API Reference for full request/response details.

Implementation Reference

For working code examples, see the andamio-app-template:

The useTransaction hook follows explicit phases that map to the lifecycle above: