AssetCore Transaction Operations Reference

Generated from Operations Manifest v1.0.0 (API 0.1.0)

Auto-generated from operations manifest on 2026-01-22

AssetCore is a deterministic memory substrate. Containers are persistent memory regions. Operations are atomic memory transformations. Transactions are replayable memory commits.

The following operations modify structured memory regions in a domain-agnostic fashion.

This document provides a complete reference for all 24 operations available in AssetCore commits.

Overview
Tag System
Operations by Domain
Quick Reference

Overview

All state changes in AssetCore’s structured memory substrate flow through the commit endpoint as a sequence of operations. Each operation is an atomic transformation that can be combined with others in a single transaction.

Commit Request Structure

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

Operations are executed in order within a single transaction. If any operation fails, the entire commit is rolled back.

Tag System

Operations are categorized across four dimensions:

Domain

What type of entity the operation affects:

container: Container lifecycle operations
balance: Fungible quantity and stack operations
instance: Unique instance operations
slot: Spatial slot positioning operations
schema: Class and shape definition operations

Action

What kind of action is performed:

create: Brings something into existence
destroy: Removes something from existence
move: Relocates between locations
link: Establishes or removes relationships
consolidate: Merges or reorganizes

Scope

How many entities are affected:

single: One primary target
multi: Multiple targets or containers

Impact

The blast radius of the operation’s effects:

targeted: Changes are limited to explicitly referenced entities
fanout: Changes fan out across multiple entities in a batch or match set
cascade: Changes implicitly remove or invalidate nested contents

Operations by Domain

Container Operations

CreateContainer

Creates a container (structured memory region) with the requested kind.

container create single targeted

Creates a persistent container of the requested kind (balance, grid, slots, continuous 1D/2D). Provide external_id to claim a stable external identifier; internal IDs are dense, auto-allocated, and never exposed. External IDs are namespace-scoped and must not already exist.

Errors:

ContainerAlreadyExists: A container with that ID already exists. Example:

{
  "op": "CreateContainer",
  "args": {
  "external_id": "container-1000",
  "kind": {
    "quantization_inv": 100,
    "type": "balance"
  }
}
}

RemoveContainer

Deletes a container after draining its contents.

container destroy single cascade

Removes a container after the transaction drains any balances, instances, and slot contents. This is irreversible for the container identifier and preserves surrounding memory regions.

Errors:

ContainerNotFound: The specified container does not exist. Example:

{
  "op": "RemoveContainer",
  "args": {
  "container_id": "container-1001"
}
}

Balance Operations

AddFungible

Adds fungible quantity to a balance or an explicit grid cell.

balance create single targeted

Increases fungible quantity for a class/key pair. When targeting a balance container, quantity is added to the aggregate balance. When targeting a grid cell, the operation creates or grows a stack at the specified anchor, enforcing registered shapes and rotation for placement.

Errors:

InvalidQuantity: Quantity must be greater than zero.
WrongContainerKind: Slots containers cannot hold fungible assets.
ContainerNotFound: The target container does not exist.
UnregisteredClass: The class is not registered in the namespace.
UnregisteredClassShape: Grid additions require a registered shape for the class and key.
PositionOccupied: The requested grid anchor overlaps an existing placement. Example:

{
  "op": "AddFungible",
  "args": {
  "class_id": "class-100",
  "key": 1,
  "location": {
    "container_id": "container-2001",
    "kind": "grid_cell",
    "position": 5,
    "rotation": "none"
  },
  "quantity": "500"
}
}

RemoveFungible

Removes fungible quantity from a balance or an explicit grid cell.

balance destroy single targeted

Decreases fungible quantity for a class/key pair within a container. Supports burning from balances or clearing a grid stack at a specific anchor. When a stack reaches zero it may be removed, keeping the substrate deterministic.

Errors:

InvalidQuantity: Quantity must be greater than zero.
WrongContainerKind: Slots containers cannot hold fungible assets.
ContainerNotFound: The target container does not exist.
UnregisteredClass: The class is not registered in the namespace.
InsufficientBalance: The requested quantity exceeds the available balance.
PositionEmpty: No stack exists at the requested grid anchor. Example:

{
  "op": "RemoveFungible",
  "args": {
  "class_id": "class-100",
  "from": {
    "container_id": "container-1001",
    "kind": "balance"
  },
  "key": 1,
  "quantity": "100"
}
}

MoveFungible

Moves fungible quantity between balances or grid cells.

balance move multi targeted

Transfers fungible quantity from one location to another. Supports balance<->balance, balance<->grid, and grid<->grid moves while enforcing registered shapes for grid destinations and ensuring source quantities are sufficient.

Errors:

InvalidQuantity: Quantity must be greater than zero.
WrongContainerKind: Slots containers cannot participate in fungible moves.
ContainerNotFound: One of the containers does not exist.
UnregisteredClass: The class is not registered in the namespace.
InsufficientBalance: Source location lacks the requested quantity.
PositionEmpty: No stack exists at the requested grid anchor.
PositionOccupied: Destination grid anchor overlaps an existing placement.
UnregisteredClassShape: Grid destinations require a registered shape for the class and key. Example:

{
  "op": "MoveFungible",
  "args": {
  "class_id": "class-100",
  "from": {
    "container_id": "container-1001",
    "kind": "balance"
  },
  "key": 1,
  "quantity": "50",
  "to": {
    "container_id": "container-2001",
    "kind": "grid_cell",
    "position": 4,
    "rotation": "clockwise90"
  }
}
}

TransferFungible

Transfers fungible quantity between structured containers.

balance move multi targeted

Moves fungible quantity from one container to another in a single transaction. Both containers must exist, support balances for the class/key pair, and the source must contain the requested amount. Shape registration is enforced when grid placement is required.

Errors:

InvalidQuantity: Quantity must be greater than zero.
InvalidOperation: Identity transfers or arithmetic overflow are invalid.
ContainerNotFound: One of the containers does not exist.
WrongContainerKind: Slots containers cannot participate in fungible transfers.
UnregisteredClass: The class is not registered in the namespace.
InsufficientBalance: Source container lacks the requested quantity.
UnregisteredClassShape: Grid destinations require a registered shape for the class and key. Example:

{
  "op": "TransferFungible",
  "args": {
  "class_id": "class-100",
  "from_container": "container-1001",
  "key": 1,
  "quantity": "250",
  "to_container": "container-1002"
}
}

TransferMany

Transfers multiple fungible quantities between containers in one batch.

balance move multi fanout

Executes an ordered batch of container-to-container transfers with atomic all-or-nothing semantics. Each entry validates container kinds, class registration, and sufficient balances before any mutations occur.

Errors:

InvalidQuantity: Quantity must be greater than zero.
InvalidOperation: Identity transfers or invalid batch structure were rejected.
ContainerNotFound: One of the containers does not exist.
WrongContainerKind: Slots containers cannot participate in fungible transfers.
UnregisteredClass: The class is not registered in the namespace.
InsufficientBalance: Source container lacks the requested quantity.
UnregisteredClassShape: Grid destinations require a registered shape for the class and key. Example:

{
  "op": "TransferMany",
  "args": {
  "transfers": [
    {
      "class_id": "class-100",
      "from_container": "container-1001",
      "key": 1,
      "quantity": "25",
      "to_container": "container-1002"
    },
    {
      "class_id": "class-101",
      "from_container": "container-1002",
      "quantity": "10",
      "to_container": "container-1003"
    }
  ]
}
}

Distribute

Distributes fungible quantity from one source to multiple destinations.

balance move multi fanout

Splits a single source quantity across multiple destination containers in a single atomic batch. The source must contain the total quantity requested across all distribution entries.

Errors:

InvalidQuantity: Each distribution quantity must be greater than zero.
InvalidOperation: Totals must fit within balance limits for the source.
ContainerNotFound: One of the containers does not exist.
WrongContainerKind: Slots containers cannot participate in fungible distribution.
UnregisteredClass: The class is not registered in the namespace.
InsufficientBalance: Source container lacks the total quantity requested.
UnregisteredClassShape: Grid destinations require a registered shape for the class and key. Example:

{
  "op": "Distribute",
  "args": {
  "class_id": "class-100",
  "distributions": [
    {
      "quantity": "10",
      "to_container": "container-2001"
    },
    {
      "quantity": "15",
      "to_container": "container-2002"
    }
  ],
  "from_container": "container-1001",
  "key": 1
}
}

MergeStacks

Merges one fungible stack into another within a container.

balance consolidate multi targeted

Combines the source stack into the destination stack in the same grid container. The stacks must share class and key identity. Quantities are summed deterministically and the source stack is removed.

Errors:

InvalidOperation: Self-merges, cross-container merges, or overflows are rejected.
ContainerNotFound: The grid container vanished before the merge completed.
WrongContainerKind: Only grid containers contain stack entities.
StackNotFound: One of the referenced stacks no longer exists.
IncompatibleStacks: Stacks must share the same class and key to merge. Example:

{
  "op": "MergeStacks",
  "args": {
  "dst_stack": "stack-5001",
  "src_stack": "stack-5002"
}
}

ConsolidateStacks

Consolidates all matching fungible stacks inside a container.

balance consolidate multi fanout

Finds every stack in a container that matches the class/key pair and collapses them into a single stack. Normalizes fragmented balances that accumulated across multiple operations while preserving totals.

Errors:

ContainerNotFound: The specified container does not exist.
WrongContainerKind: Only grid containers can hold stacks for consolidation.
UnregisteredClass: The class is not registered in the namespace.
InvalidOperation: No stacks were found or the total quantity overflowed u64.
StackNotFound: A stack disappeared during consolidation. Example:

{
  "op": "ConsolidateStacks",
  "args": {
  "class_id": "class-100",
  "container_id": "container-1001",
  "key": 1
}
}

MoveMany

Moves multiple stacks between Grid containers in one batch.

balance move multi fanout

Executes a batch of stack moves across Grid containers. Each entry specifies a stack identifier, destination container, and quantity; partial moves split stacks while full moves relocate them.

Errors:

InvalidQuantity: Move quantity must be greater than zero.
InvalidOperation: Duplicate stacks or invalid destinations were rejected.
ContainerNotFound: One of the containers does not exist.
WrongContainerKind: Stacks can only move between Grid containers.
StackNotFound: One of the referenced stacks no longer exists.
InsufficientBalance: A stack lacks the quantity requested for the move.
StackLimitExceeded: Destination container exceeds stack limits. Example:

{
  "op": "MoveMany",
  "args": {
  "moves": [
    {
      "quantity": "3",
      "stack": "stack-5001",
      "to_container": "container-2001"
    },
    {
      "quantity": "5",
      "stack": "stack-5002",
      "to_container": "container-2002"
    }
  ]
}
}

Instance Operations

AddInstance

Mints a new instance and places it at a target location.

instance create single targeted

Creates a unique instance for the specified class/variant and places it into a slot, grid anchor, or continuous coordinate. Validates container kind, shape/rotation rules, and collision before placement.

Errors:

ContainerNotFound: The target container does not exist.
UnregisteredClass: The class is not registered in the namespace.
WrongContainerKind: Grid placements require Grid containers; slot placements require Slots containers; continuous placements require Continuous containers.
SlotOutOfBounds: Slot index exceeds the container capacity.
SlotOccupied: The requested slot is already occupied.
PositionOccupied: The grid anchor overlaps an existing placement.
PositionOutOfBounds: Placement would exceed grid bounds.
ContinuousPlacementOutOfBounds: Continuous placement extends beyond container bounds.
UnregisteredClassShape: Grid placements require a registered shape for the class/key. Example:

{
  "op": "AddInstance",
  "args": {
  "class_id": "class-200",
  "key": 1,
  "location": {
    "container_id": "container-500",
    "kind": "slot",
    "slot_index": 1
  }
}
}

MoveInstance

Moves an existing instance to a new location.

instance move single targeted

Repositions a previously minted instance into a slot, grid anchor, or continuous coordinate. Validates shape/rotation rules and prevents overlap in grid and continuous containers.

Errors:

InstanceNotFound: The instance does not exist.
WrongContainerKind: Destination container type does not support the requested move.
SlotOutOfBounds: Slot index exceeds the container capacity.
SlotOccupied: Destination slot is already occupied.
PositionOccupied: Destination grid anchor overlaps an existing placement.
PositionOutOfBounds: Destination grid anchor exceeds bounds.
ContinuousPlacementOutOfBounds: Continuous placement extends beyond container bounds.
UnregisteredClassShape: Grid destinations require a registered shape for the instance class/key.
ContinuousPlacementOverlap: Continuous destination overlaps an existing placement. Example:

{
  "op": "MoveInstance",
  "args": {
  "instance": "instance-9001",
  "to": {
    "container_id": "container-2001",
    "kind": "grid_cell",
    "position": 5,
    "rotation": "none"
  }
}
}

RemoveInstance

Burns an instance from the world.

instance destroy single targeted

Removes an instance regardless of current placement. The instance cannot have attached children. Grid or slot references are cleared as part of the burn.

Errors:

InstanceNotFound: The target instance ID does not exist.
HasChildren: Children must be detached before burning the instance. Example:

{
  "op": "RemoveInstance",
  "args": {
  "instance": "instance-9001"
}
}

BurnInstance

Removes a unique instance permanently from the substrate.

instance destroy single targeted

Permanently deletes a unique instance. The instance must not be attached to other instances or placed in a slot. The identifier is never reused once burned.

Errors:

InstanceNotFound: The target instance ID does not exist.
HasChildren: Children must be detached before burning the instance. Example:

{
  "op": "BurnInstance",
  "args": {
  "instance_id": "instance-9001"
}
}

Attach

Attaches a child instance to a parent for linked movement.

instance link multi targeted

Creates a parent-child relationship between two instances so they move together. The child can only have one parent, and cycles are rejected to keep the instance graph acyclic.

Errors:

InvalidOperation: Child and parent must differ and cycles are rejected.
InstanceNotFound: The child or parent instance does not exist.
AlreadyAttached: The child already has a parent.
WouldCreateCycle: Attachment would create a cycle in the hierarchy. Example:

{
  "op": "Attach",
  "args": {
  "child_instance": "instance-9002",
  "parent_instance": "instance-9001"
}
}

Detach

Detaches a child instance from its parent instance.

instance link single targeted

Removes the parent-child relationship so the child becomes independent while remaining in the memory substrate. The child retains its ID and can be reattached elsewhere.

Errors:

InstanceNotFound: The specified instance does not exist.
NotAttached: The instance has no parent to detach from. Example:

{
  "op": "Detach",
  "args": {
  "child_instance": "instance-9002"
}
}

Slot Operations

PlaceInSlot

Positions an instance into an addressable slot within a container.

slot move single targeted

Places a unique instance into a specific slot in a container that supports slot layouts. The slot must be empty and the container kind must allow slot placement, preserving deterministic positioning.

Errors:

ContainerNotFound: The destination container does not exist.
WrongContainerKind: Only Slots containers support slot placement.
SlotOutOfBounds: Slot index exceeds the container capacity.
InstanceNotFound: The instance being placed does not exist.
SlotOccupied: The requested slot is already occupied. Example:

{
  "op": "PlaceInSlot",
  "args": {
  "container_id": "container-1001",
  "instance_id": "instance-9001",
  "slot_index": 1
}
}

RemoveFromSlot

Removes an instance from a container slot.

slot move single targeted

Clears a slot and leaves the instance unplaced. The instance remains in the memory substrate but no longer occupies that positional binding, enabling repositioning.

Errors:

ContainerNotFound: The container does not exist.
WrongContainerKind: Only Slots containers support slot removal.
SlotOutOfBounds: Slot index exceeds the container capacity.
SlotEmpty: The slot does not contain an instance to remove. Example:

{
  "op": "RemoveFromSlot",
  "args": {
  "container_id": "container-1001",
  "slot_index": 1
}
}

SwapSlots

Swaps the contents of two occupied slots atomically.

slot move multi targeted

Atomically exchanges the contents of two slots, which can reside in the same or different containers. Both slots must exist and be occupied. The swap preserves positional invariants across containers.

Errors:

InvalidOperation: Cannot swap a slot with itself in the same container.
ContainerNotFound: One of the containers does not exist.
WrongContainerKind: Both containers must be Slots type.
SlotOutOfBounds: One of the slot indices exceeds the container capacity.
SlotEmpty: A slot is empty and cannot be swapped. Example:

{
  "op": "SwapSlots",
  "args": {
  "container_a": "container-1001",
  "container_b": "container-1001",
  "slot_a": 1,
  "slot_b": 5
}
}

Schema Operations

RegisterClass

Registers a class definition so future operations can reference it.

schema create single targeted

Registers a class external ID and name so transactions can reference the class and apply its validation rules. External IDs are namespace-scoped and immutable once registered; internal IDs are auto-assigned and never exposed.

Errors:

ClassAlreadyExists: The provided class_id (external identifier) is already in use.
ClassCapacityExceeded: The global class registry has reached its configured limit. Example:

{
  "op": "RegisterClass",
  "args": {
  "request": {
    "class_id": "class-100",
    "flags": 2,
    "name": "ExampleClass"
  }
}
}

RegisterClassShape

Registers a grid shape footprint for a class or class variant.

schema create single targeted

Defines the width/height shape for a class_id (external identifier) and optional stack_key so grid placements can validate occupancy and rotation. Shapes are required before placing instances or stacks into grid containers for that class. Re-registering an identical shape is treated as a no-op.

Errors:

ClassNotFound: The referenced class_id (external identifier) has not been registered.
ShapeAlreadyDefined: The shape_id already exists for the class. Example:

{
  "op": "RegisterClassShape",
  "args": {
  "request": {
    "class_id": "class-200",
    "shape": {
      "height": 3,
      "width": 2
    }
  }
}
}

RegisterClassContinuousShape2d

Registers a continuous 2D rectangle for a class or class variant.

schema create single targeted

Defines the fixed-point rectangle for a class_id (external identifier) and optional stack_key so continuous 2D placements can validate collisions and rotations. Required before placing into continuous_grid_2d containers for that class. Re-registering an identical rectangle is treated as a no-op.

Errors:

ClassNotFound: The referenced class_id (external identifier) has not been registered.
ContinuousShapeAlreadyDefined: The continuous shape is already registered for the class/key. Example:

{
  "op": "RegisterClassContinuousShape2d",
  "args": {
  "request": {
    "class_id": "class-200",
    "rect": {
      "height": 8,
      "width": 10
    }
  }
}
}

RegisterClassContinuousShape1d

Registers a continuous 1D span for a class or class variant.

schema create single targeted

Defines the fixed-point span length for a class_id (external identifier) and optional stack_key so continuous 1D placements can validate collisions. Required before placing into continuous_line_1d containers for that class. Re-registering an identical span is treated as a no-op.

Errors:

ClassNotFound: The referenced class_id (external identifier) has not been registered.
ContinuousShapeAlreadyDefined: The continuous shape is already registered for the class/key. Example:

{
  "op": "RegisterClassContinuousShape1d",
  "args": {
  "request": {
    "class_id": "class-200",
    "span": {
      "length": 10
    }
  }
}
}

Recipes

Move Fungible Balance Between Containers

Move fungible quantity from one container to another in a single semantic operation.

Operations:

MoveFungible

Example:

{
  "namespace_id": 1,
  "operations": [
    {
      "op": "MoveFungible",
      "args": {
        "class_id": "class-100",
        "key": 1,
        "quantity": "50",
        "from": {
          "kind": "balance",
          "container_id": "container-1001"
        },
        "to": {
          "kind": "balance",
          "container_id": "container-1002"
        }
      }
    }
  ]
}

Move Instance Between Slots

Remove an instance from one slot and place it into another addressable slot within the same container while keeping the transaction atomic.

Operations:

RemoveFromSlot
PlaceInSlot

Example:

{
  "namespace_id": 1,
  "operations": [
    {
      "op": "RemoveFromSlot",
      "args": {
        "container_id": "container-1001",
        "slot_index": 1
      }
    },
    {
      "op": "PlaceInSlot",
      "args": {
        "container_id": "container-1001",
        "slot_index": 2,
        "instance_id": "instance-9001"
      }
    }
  ]
}

Register Class with Shape

Register a new asset class and immediately declare a grid shape so placement rules are available for structured containers.

Operations:

RegisterClass
RegisterClassShape

Example:

{
  "namespace_id": 1,
  "operations": [
    {
      "op": "RegisterClass",
      "args": {
        "request": {
          "class_id": "class-100",
          "name": "ExampleClass",
          "flags": 2
        }
      }
    },
    {
      "op": "RegisterClassShape",
      "args": {
        "request": {
          "class_id": "class-100",
          "shape": {
            "width": 2,
            "height": 3
          }
        }
      }
    }
  ]
}

Quick Reference

Operation	Domain	Action	Summary
CreateContainer	container	create	Creates a container (structured memory region) with the requested kind
RemoveContainer	container	destroy	Deletes a container after draining its contents
AddFungible	balance	create	Adds fungible quantity to a balance or an explicit grid cell
RemoveFungible	balance	destroy	Removes fungible quantity from a balance or an explicit grid cell
MoveFungible	balance	move	Moves fungible quantity between balances or grid cells
TransferFungible	balance	move	Transfers fungible quantity between structured containers
TransferMany	balance	move	Transfers multiple fungible quantities between containers in one batch
Distribute	balance	move	Distributes fungible quantity from one source to multiple destinations
MergeStacks	balance	consolidate	Merges one fungible stack into another within a container
ConsolidateStacks	balance	consolidate	Consolidates all matching fungible stacks inside a container
MoveMany	balance	move	Moves multiple stacks between Grid containers in one batch
AddInstance	instance	create	Mints a new instance and places it at a target location
MoveInstance	instance	move	Moves an existing instance to a new location
RemoveInstance	instance	destroy	Burns an instance from the world
BurnInstance	instance	destroy	Removes a unique instance permanently from the substrate
Attach	instance	link	Attaches a child instance to a parent for linked movement
Detach	instance	link	Detaches a child instance from its parent instance
PlaceInSlot	slot	move	Positions an instance into an addressable slot within a container
RemoveFromSlot	slot	move	Removes an instance from a container slot
SwapSlots	slot	move	Swaps the contents of two occupied slots atomically
RegisterClass	schema	create	Registers a class definition so future operations can reference it
RegisterClassShape	schema	create	Registers a grid shape footprint for a class or class variant
RegisterClassContinuousShape2d	schema	create	Registers a continuous 2D rectangle for a class or class variant
RegisterClassContinuousShape1d	schema	create	Registers a continuous 1D span for a class or class variant

This document was auto-generated from the AssetCore operation manifest.

AssetCore Transaction Operations Reference

Table of Contents

Overview

Commit Request Structure

Tag System

Domain

Action

Scope

Impact

Operations by Domain

Container Operations

CreateContainer

RemoveContainer

Balance Operations

AddFungible

RemoveFungible

MoveFungible

TransferFungible

TransferMany

Distribute

MergeStacks

ConsolidateStacks

MoveMany

Instance Operations

AddInstance

MoveInstance

RemoveInstance

BurnInstance

Attach

Detach

Slot Operations

PlaceInSlot

RemoveFromSlot

SwapSlots

Schema Operations

RegisterClass

RegisterClassShape

RegisterClassContinuousShape2d

RegisterClassContinuousShape1d

Recipes

Move Fungible Balance Between Containers

Move Instance Between Slots

Register Class with Shape

Quick Reference