WRONG (causes race condition - stale data):
  Frontend sees "confirmed" → fires success callback → fetches data → gets PENDING_TX_SUBMIT

CORRECT:
  Frontend sees "confirmed" → keeps polling → Gateway updates DB → state="updated" → success callback

// src/hooks/tx/use-tx-watcher.ts
export const TERMINAL_STATES: TxState[] = ["updated", "failed", "expired"];
// NOTE: "confirmed" is NOT terminal!

// In components:
const { status, isSuccess } = useTxWatcher(txHash, {
  onComplete: (status) => {
    // "updated" means Gateway has confirmed TX AND updated DB
    if (status.state === "updated") {
      toast.success("Transaction complete!");
      void refetchData();
    } else if (status.state === "failed" || status.state === "expired") {
      toast.error(status.last_error ?? "Transaction failed");
    }
  },
});

https://dev.api.andamio.io/api/v1/docs/doc.json

# Get all TX-related paths
curl -s "https://dev.api.andamio.io/api/v1/docs/doc.json" \
  | jq -r '.paths | keys[]' | grep "/api/v2/tx/" | sort

# Get specific request schemas
curl -s "https://dev.api.andamio.io/api/v1/docs/doc.json" \
  | jq '[.definitions | to_entries[] | select(.key | contains("TxRequest"))] | from_entries'

# Get valid tx_type values from API
curl -s "https://dev.api.andamio.io/api/v1/docs/doc.json" \
  | jq '.definitions["tx_state_handlers.RegisterPendingTxRequest"].properties.tx_type.enum'

// CORRECT
export const TERMINAL_STATES: TxState[] = ["updated", "failed", "expired"];

// WRONG - will cause race conditions
export const TERMINAL_STATES: TxState[] = ["confirmed", "updated", "failed", "expired"];

npm run generate:types

# Find all useTxWatcher usages checking for "confirmed"
grep -r 'status\.state === "confirmed"' src/components/

npm run typecheck
npm run build

├─ t=0     User submits TX, frontend calls /tx/register
├─ t=0     Gateway stores TX with state="pending"
│
├─ t=30s   Gateway polls Andamioscan, sees TX on-chain
├─ t=30s   Gateway state → "confirmed"
├─ t=30s   Gateway adds TX to confirmation queue
│
├─ t=60s   Background job processes confirmation queue
├─ t=60s   Gateway calls DB API (UpdateDB handler for tx_type)
├─ t=60s   DB status transitions (e.g., PENDING_TX_SUBMIT → SUBMITTED)
├─ t=60s   Gateway state → "updated"
│
└─ t=60s   Frontend sees "updated", fires onComplete, fetches fresh data

// Alias (1-31 chars, alphanumeric + underscore)
alias: z.string().min(1).max(31)

// Policy ID (56 char hex)
course_id: z.string().length(56)
project_id: z.string().length(56)

// Hash (64 char hex)
slt_hash: z.string().length(64)
task_hash: z.string().length(64)

// Short text (max 140 chars)
assignment_info: z.string().max(140)
project_info: z.string().max(140)

// Wallet data (optional)
initiator_data: z.object({
  used_addresses: z.array(z.string()),
  change_address: z.string(),
}).optional()

// Value (asset tuples)
deposit_value: z.array(z.tuple([z.string(), z.number()]))

// Outcome (string, not enum - API accepts any)
outcome: z.string()

// WRONG
if (status.state === "confirmed" || status.state === "updated") { ... }

// CORRECT
if (status.state === "updated") { ... }

# Regenerate types from gateway spec
npm run generate:types

# Type check after changes
npm run typecheck

# Find incorrect "confirmed" checks
grep -r 'status\.state === "confirmed"' src/components/

# Get all TX request schemas from API
curl -s "https://dev.api.andamio.io/api/v1/docs/doc.json" \
  | jq '[.definitions | to_entries[] | select(.key | contains("TxRequest"))] | from_entries'

# Get tx_type enum values
curl -s "https://dev.api.andamio.io/api/v1/docs/doc.json" \
  | jq '.definitions["tx_state_handlers.RegisterPendingTxRequest"].properties.tx_type.enum'