@andamio/transactions

The @andamio/transactions package provides comprehensive specifications for all Andamio transactions, unifying protocol specs, API lifecycle, side effects, and UI metadata into a single authoritative source.

Overview

Andamio transactions operate across three layers:

Protocol Layer - On-chain transaction structure defined in YAML specs
API Layer - Off-chain integration with build endpoints and side effects
UI Layer - User-facing metadata and interface strings

This package brings all three layers together in strongly-typed TypeScript definitions.

Features

Type-Safe Definitions

Full TypeScript support with Zod validation for all transaction inputs

Input Helpers

Format complex inputs with type-safe helper functions

Side Effects

Declarative database updates and notifications

Hash Utilities

Compute module hashes and assignment info hashes

Quick Example

import { getTransactionDefinition, computeSltHash } from "@andamio/transactions";

// Get transaction definition
const txDef = getTransactionDefinition("COURSE_TEACHER_MODULES_MANAGE");

// Preview module hash before minting
const slts = ["I can mint an access token.", "I can complete an assignment."];
const moduleHash = computeSltHash(slts);
console.log(`Module will have hash: ${moduleHash}`);

// Access protocol specification
console.log(txDef.protocolSpec.yamlPath);
// "/yaml/transactions/v2/course/teacher/modules-manage.yaml"

// Get estimated costs
console.log(txDef.buildTxConfig.estimatedCost);
// { txFee: 200000, minDeposit: 1860000 }

Transaction Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    Transaction Lifecycle                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  1. BUILD TRANSACTION                                            │
│     └─> Atlas Tx API builds unsigned CBOR                        │
│                                                                  │
│  2. SIGN & SUBMIT                                                │
│     └─> User signs with wallet, submits to chain                 │
│     └─> onSubmit side effects execute (update DB to PENDING_TX)  │
│                                                                  │
│  3. CONFIRM ON-CHAIN                                             │
│     └─> Transaction confirmed in block                           │
│     └─> onConfirmation side effects execute (finalize DB state)  │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Protocol Versions

Version	Status	Transactions	Description
V2	Current	8	Consolidated role structure, recommended for new implementations
V1	Legacy	8	Maintained for backward compatibility

V2 dramatically reduces transaction count compared to V1's original design (29 → 8 transactions) through:

Batch operations (manage multiple modules in one tx)
Unified assessment (accept/deny in one tx type)
Streamlined enrollment (initial commitment included)

Installation

npm install @andamio/transactions

Next Steps

Getting Started - Installation and basic usage
V2 Transactions - Current production transactions
Utilities - Hash functions and helpers
Side Effects - Database update patterns