Transactions

A transaction is a list of operations that execute atomically. This reference describes the JSON structure of commit requests.

Overview

All state changes flow through the /v1/commit endpoint as transactions. The write daemon validates, executes, and persists operations before returning a success response.

Structure

Commit Request

{
  "operations": [
    { "op": "OperationName", "args": { ... } },
    { "op": "AnotherOperation", "args": { ... } }
  ],
  "idempotency_key": "optional-unique-key",
  "metadata": {
    "custom_field": "optional user metadata"
  }
}

Operation Envelope

Each operation has the same envelope structure:

{
  "op": "OperationName",
  "args": {
    "field1": "value1",
    "field2": 123
  }
}

Fields

Request Fields

Field	Type	Required	Description
operations	array	Yes	List of operations to execute
idempotency_key	string	No	Unique key for deduplication
metadata	object	No	User-defined metadata echoed in response

Operation Envelope Fields

Field	Type	Required	Description
op	string	Yes	Operation identifier
args	object	Yes	Operation-specific arguments

Response Fields

Field	Type	Description
global_seq	integer	Global sequence number of the commit
batch_seq	integer	Batch sequence number
minted_instances	array	IDs of instances created by MintInstance
metadata	object	Echo of request metadata including idempotency_key

Examples

Minimal Transaction

{
  "operations": [
    {
      "op": "CreateContainer",
      "args": {
        "container_id": 1001,
        "kind": "Standard",
        "owner": null
      }
    }
  ]
}

Transaction with Idempotency

{
  "operations": [
    {
      "op": "AddFungible",
      "args": {
        "container_id": 1001,
        "class_id": 100,
        "key": 1,
        "quantity": 500
      }
    }
  ],
  "idempotency_key": "add-balance-2024-01-15-001"
}

Multi-Operation Transaction

{
  "operations": [
    {
      "op": "RegisterClass",
      "args": {
        "request": {
          "class_id": 200,
          "name": "Sample",
          "fungible": false
        }
      }
    },
    {
      "op": "MintInstance",
      "args": {
        "class_id": 200,
        "key": 1
      }
    },
    {
      "op": "PlaceInSlot",
      "args": {
        "container_id": 1001,
        "instance_id": 9001,
        "slot_index": 0
      }
    }
  ],
  "metadata": {
    "experiment_id": "exp-001",
    "operator": "system"
  }
}

Response:

{
  "global_seq": 5,
  "batch_seq": 1,
  "minted_instances": [9001],
  "metadata": {
    "experiment_id": "exp-001",
    "operator": "system"
  }
}

Idempotent Retry Response

When the same idempotency key is sent again:

{
  "global_seq": 5,
  "batch_seq": 1,
  "minted_instances": [9001],
  "metadata": {
    "idempotency_key": "create-sample-001"
  }
}

The X-Asset-Idempotency: hit header indicates a cached response.

Related references

• Operations by Domain - Complete operation reference
• Recipes - Common multi-operation patterns
• Error Model - Handling transaction failures