V2 Transactions

Protocol V2 is the current production version, recommended for all new implementations. V2 consolidates the role structure and dramatically reduces transaction count compared to V1 (29 → 8 transactions).

Transaction Overview

Transaction	Role	Est. Cost	Description
`GENERAL_ACCESS_TOKEN_MINT`	General	~7.9 ADA	Mint access token for protocol participation
`COURSE_ADMIN_CREATE`	Admin	~45.3 ADA	Create a new course on-chain
`COURSE_ADMIN_TEACHERS_UPDATE`	Admin	~5.3 ADA	Add/remove teachers from a course
`COURSE_TEACHER_MODULES_MANAGE`	Teacher	~1.86 ADA	Batch manage modules (mint/update/burn)
`COURSE_TEACHER_ASSIGNMENTS_ASSESS`	Teacher	~0.21 ADA	Assess student assignment submissions
`COURSE_STUDENT_ENROLL`	Student	~2.14 ADA	Enroll in a course with initial commitment
`COURSE_STUDENT_ASSIGNMENT_UPDATE`	Student	~0.33 ADA	Update assignment or commit to new module
`COURSE_STUDENT_CREDENTIAL_CLAIM`	Student	~-1.03 ADA	Claim completed credential (refund)

Naming Convention

V2 transactions follow the pattern: {SYSTEM}_{ROLE}_{ACTION}

System: GENERAL or COURSE (future: PROJECT)
Role: Who can execute (ADMIN, TEACHER, STUDENT)
Action: What the transaction does

General System

GENERAL_ACCESS_TOKEN_MINT

Mint an access token to participate in the Andamio protocol. Required before any other protocol action.

import { GENERAL_ACCESS_TOKEN_MINT } from "@andamio/transactions";

const inputs = GENERAL_ACCESS_TOKEN_MINT.buildTxConfig.inputSchema.parse({
  user_pkh: "paymentKeyHash...",
  alias: "alice",
});

Key Points:

No side effects (purely on-chain action)
Database user records created separately when connecting to application
Alias must be unique and 3+ characters

Course Admin Transactions

COURSE_ADMIN_CREATE

Create a new course on-chain. The course NFT policy ID is returned by the transaction API.

import { COURSE_ADMIN_CREATE } from "@andamio/transactions";

const inputs = COURSE_ADMIN_CREATE.buildTxConfig.inputSchema.parse({
  alias: userAlias,
  initialTeacher: teacherAlias,
  // courseNftPolicyId comes from tx API response
});

Side Effects:

onSubmit: POST /courses/create-on-submit - Create course record with title
onConfirmation: POST /courses/confirm-creation - Set course live to true

Note: The courseNftPolicyId is generated by the transaction API and must be extracted from the response to include in side effects.

COURSE_ADMIN_TEACHERS_UPDATE

Add or remove teachers from a course governance UTxO.

import { COURSE_ADMIN_TEACHERS_UPDATE } from "@andamio/transactions";

const inputs = COURSE_ADMIN_TEACHERS_UPDATE.buildTxConfig.inputSchema.parse({
  alias: adminAlias,
  courseId: courseNftPolicyId,
  teachersToAdd: ["bob", "carol"],
  teachersToRemove: ["dave"],
});

Key Points:

No side effects (purely on-chain action)
Teacher access verified via Andamioscan API /v2/courses/{course_id}

Course Teacher Transactions

COURSE_TEACHER_MODULES_MANAGE

Batch manage modules - mint new ones, update existing, or burn old ones. All in a single transaction.

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

const inputs = COURSE_TEACHER_MODULES_MANAGE.buildTxConfig.inputSchema.parse({
  alias: teacherAlias,
  courseId: courseNftPolicyId,
  modulesToMint: [
    {
      slts: ["I can mint an access token.", "I can complete an assignment."],
      allowedStudents_V2: [], // Policy IDs of allowed student groups
      prerequisiteAssignments_V2: [], // SLT hashes of prerequisites
    },
  ],
  modulesToUpdate: [],
  modulesToBurn: [],
});

// Preview module hashes before minting
inputs.modulesToMint.forEach(m => {
  const hash = computeSltHash(m.slts);
  console.log(`Module hash: ${hash}`);
});

Side Effects:

onSubmit: POST /course-modules/batch-update-status - Set all modules to PENDING_TX
onConfirmation: POST /course-modules/batch-confirm-transaction - Set to ON_CHAIN with hashes

Key Points:

Module hash (token name) computed from SLTs using Blake2b-256
Use computeSltHash() to preview hashes before transaction
Supports batch operations for efficiency

COURSE_TEACHER_ASSIGNMENTS_ASSESS

Assess student assignment submissions - accept or refuse. Supports batched decisions.

import { COURSE_TEACHER_ASSIGNMENTS_ASSESS } from "@andamio/transactions";

const inputs = COURSE_TEACHER_ASSIGNMENTS_ASSESS.buildTxConfig.inputSchema.parse({
  // Transaction API params
  alias: teacherAlias,
  courseId: courseNftPolicyId,
  assignmentDecisions: [
    { alias: "student1", outcome: "accept" },
    { alias: "student2", outcome: "refuse" },
  ],
  // Side effect params (for single assessment operations)
  moduleCode: "MODULE_1",
  studentAccessTokenAlias: "student1",
  assessmentResult: "accept", // or "refuse"
});

Side Effects (Conditional):

onSubmit: Set to PENDING_TX_ASSIGNMENT_ACCEPTED or PENDING_TX_ASSIGNMENT_REFUSED
onConfirmation: Finalize to ASSIGNMENT_ACCEPTED or ASSIGNMENT_REFUSED

Course Student Transactions

COURSE_STUDENT_ENROLL

Enroll in a course with an optional initial assignment commitment.

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

// Compute evidence hash
const evidenceHash = computeAssignmentInfoHash(evidenceContent);
const moduleHash = computeSltHash(slts);

const inputs = COURSE_STUDENT_ENROLL.buildTxConfig.inputSchema.parse({
  alias: studentAlias,
  courseId: courseNftPolicyId,
  commitData: {
    sltHash: moduleHash, // 64-char module hash
    assignmentInfo: evidenceHash, // Hash of evidence content
  },
});

Side Effects:

onSubmit: POST /assignment-commitments/create - Create initial commitment
onConfirmation: POST /assignment-commitments/confirm-transaction - Confirm to PENDING_APPROVAL

Key Points:

commitData.sltHash is the module token name (use computeSltHash(slts))
commitData.assignmentInfo is the evidence hash (use computeAssignmentInfoHash(evidence))
Full evidence stored in database, only hash goes on-chain

COURSE_STUDENT_ASSIGNMENT_UPDATE

Update existing assignment evidence OR commit to a different module.

import {
  COURSE_STUDENT_ASSIGNMENT_UPDATE,
  computeAssignmentInfoHash
} from "@andamio/transactions";

const newEvidenceHash = computeAssignmentInfoHash(newEvidence);

const inputs = COURSE_STUDENT_ASSIGNMENT_UPDATE.buildTxConfig.inputSchema.parse({
  alias: studentAlias,
  courseId: courseNftPolicyId,
  assignmentInfo: newEvidenceHash,
  maybeNewSltHash: newModuleHash, // undefined if just updating evidence
  // Side effect params
  moduleCode: "MODULE_2",
  isNewCommitment: true, // false if updating same module
});

Side Effects:

Update mode: POST /assignment-commitments/update-evidence - Update evidence
New commitment mode: POST /assignment-commitments/create - Create new commitment
onConfirmation: POST /assignment-commitments/confirm-transaction - Confirm update

COURSE_STUDENT_CREDENTIAL_CLAIM

Claim completed credential and receive deposit refund.

import { COURSE_STUDENT_CREDENTIAL_CLAIM } from "@andamio/transactions";

const inputs = COURSE_STUDENT_CREDENTIAL_CLAIM.buildTxConfig.inputSchema.parse({
  alias: studentAlias,
  courseId: courseNftPolicyId,
});

Key Points:

No side effects (purely on-chain action)
All assignment commitments should already be completed
Returns ~1 ADA deposit refund

Import Examples

// Import individual transactions
import {
  COURSE_ADMIN_CREATE,
  COURSE_STUDENT_ENROLL,
  COURSE_TEACHER_MODULES_MANAGE
} from "@andamio/transactions";

// Import v2 namespace
import { v2 } from "@andamio/transactions";
const { COURSE_ADMIN_CREATE } = v2;

// Get all v2 transactions
import { getTransactionsByVersion } from "@andamio/transactions";
const allV2 = getTransactionsByVersion("v2");

// Get v2 transactions by role
import { getTransactionsByVersionAndRole } from "@andamio/transactions";
const v2StudentTxs = getTransactionsByVersionAndRole("v2", "student");

Utilities - Hash functions for modules and assignments
Side Effects - How database updates work
V1 Transactions - Legacy transaction reference