Transactions and Operations

Transactions are the atomic unit of change in Asset Core. Each transaction contains a sequence of operations that execute together or not at all.

Problem this concept solves

Complex state changes often require multiple coordinated updates:

Creating a container and populating it
Transferring assets between locations
Minting an instance and placing it

Without atomic transactions, these multi-step changes could fail partway through, leaving the system in an inconsistent state. Asset Core solves this by grouping operations into transactions with all-or-nothing semantics.

Additionally, AI agents need a bounded, safe operation set. Open-ended APIs allow agents to make dangerous changes. A fixed operation vocabulary lets you audit and constrain agent behavior.

Core ideas

Commit Structure

A commit request contains a list of operations:

{
  "operations": [
    { "op": "CreateContainer", "args": { ... } },
    { "op": "AddFungible", "args": { ... } }
  ],
  "idempotency_key": "optional-unique-key"
}

Operations execute in order within the transaction. If any operation fails, the entire commit is rolled back.

Operation Envelope

Each operation has the same envelope structure:

{
  "op": "OperationName",
  "args": { ... }
}

op: The operation identifier (e.g., CreateContainer)
args: Operation-specific arguments

This uniform structure makes operations easy to compose and process programmatically.

The 16 Operations

Asset Core defines exactly 16 operations across 5 domains:

Domain	Operations
Container	CreateContainer, RemoveContainer
Balance	AddFungible, RemoveFungible, TransferFungible, MergeStacks, ConsolidateStacks
Instance	MintInstance, BurnInstance, Attach, Detach
Slot	PlaceInSlot, RemoveFromSlot, SwapSlots
Schema	RegisterClass, RegisterClassShape

This fixed set is intentional. It provides:

Auditability: Every possible state change is known
Safety: No arbitrary mutations
Consistency: Same operations work across all environments

Tag System

Operations are categorized across four dimensions:

Domain: What entity type is affected

container, balance, instance, slot, schema

Action: What kind of change

create, destroy, move, link, consolidate

Scope: How many entities

single, multi

Reversibility: Can it be undone

reversible, destructive, neutral

Tags help you:

Filter operations for agent permissions
Understand the nature of changes
Build tooling around operation types

Idempotency

The optional idempotency_key enables safe retries:

First request with a key executes normally
Subsequent requests with the same key return the cached response
Prevents duplicate commits from network retries

Always use idempotency keys for production workloads.

How it fits into the system

Execution Flow

Client sends commit request
Write daemon parses and validates
Operations execute in sequence
Events are recorded for each operation
Events are sealed into a batch
Batch is persisted to commit log
Client receives success response

Rollback on Failure

If any operation fails:

Execution stops at the failing operation
Undo log is applied in reverse order
State is restored to pre-transaction
Client receives error response

No partial commits are visible to readers.

Event Generation

Each operation generates events that:

Describe the state change
Carry post-state for replay
Are grouped into the transaction batch

Events are the durable record; operations are the request format.

Key invariants and guarantees

Atomicity

All operations in a transaction succeed or fail together:

No partial execution visible
Rollback restores exact prior state
Error responses indicate which operation failed

Order Preservation

Operations execute in array order:

Later operations see effects of earlier ones
Dependencies are satisfied sequentially
No reordering or parallel execution

Determinism

Same operations produce same events:

Given identical state and operations
Events will be byte-identical
Enables replay and verification

Fixed Vocabulary

No custom operations can be added:

The 16 operations are complete
Complex changes compose multiple operations
This constraint is a feature, not a limitation