Arxi Decision Gate Asset Core
Docs
Asset Core Docs

Deterministic world-state engine documentation and API references.

Decision Gate docs

Recipes

Recipes are common multi-operation patterns that accomplish typical workflows. Use these as templates for your transactions, and adjust the IDs and metadata to fit your domain.

Prerequisites

These recipes assume you already have the basics in place. If you are missing any prerequisite, complete that step first to avoid validation failures.

  • Understanding of operations
  • Asset classes registered for your domain
  • Containers created for source and destination

Step 1 - Transfer Fungible Balance Between Containers

Move a fungible quantity from one container to another using remove and add operations. This is the safest pattern when you want explicit control over each step.

When to use: Moving resources, transferring balances, rebalancing inventory.

Operations: RemoveFungible, AddFungible

{
  "operations": [
    {
      "op": "RemoveFungible",
      "args": {
        "class_id": 200,
        "key": 1,
        "quantity": 150,
        "from": {
          "container_id": 1001,
          "kind": "balance"
        }
      }
    },
    {
      "op": "AddFungible",
      "args": {
        "class_id": 200,
        "key": 1,
        "quantity": 150,
        "location": {
          "container_id": 1002,
          "kind": "balance"
        }
      }
    }
  ],
  "idempotency_key": "transfer-balance-2026-01-15-1001-1002"
}

Alternatively, use TransferFungible for a single-operation transfer:

{
  "operations": [
    {
      "op": "TransferFungible",
      "args": {
        "from_container": 1001,
        "to_container": 1002,
        "class_id": 200,
        "key": 1,
        "quantity": 150
      }
    }
  ]
}

Step 2 - Move Instance Between Slots

Relocate a unique instance from one slot to another within the same or different containers. This pattern preserves auditability and avoids partial state during equipment changes.

When to use: Reorganizing inventory, moving equipment, repositioning items.

Operations: RemoveFromSlot, PlaceInSlot

{
  "operations": [
    {
      "op": "RemoveFromSlot",
      "args": {
        "container_id": 1001,
        "slot_index": 1
      }
    },
    {
      "op": "PlaceInSlot",
      "args": {
        "container_id": 1001,
        "slot_index": 2,
        "instance_id": 9001
      }
    }
  ],
  "idempotency_key": "slot-move-2026-01-15-9001"
}

For swapping two occupied slots, use SwapSlots instead.

Step 3 - Register Class with Shape

Define a new asset class and immediately configure its grid shape in a single transaction.

When to use: Setting up new asset types that will be placed in grid containers.

Operations: RegisterClass, RegisterClassShape

{
  "operations": [
    {
      "op": "RegisterClass",
      "args": {
        "request": {
          "class_id": 300,
          "flags": 2,
          "name": "Battle Tank"
        }
      }
    },
    {
      "op": "RegisterClassShape",
      "args": {
        "request": {
          "class_id": 300,
          "stack_key": null,
          "shape": {
            "width": 3,
            "height": 2
          }
        }
      }
    }
  ],
  "idempotency_key": "class-with-shape-2026-01-15-300"
}

Step 4 - Add and Place Instance

Create a new unique instance and immediately place it in a slot.

When to use: Spawning items, creating equipment, adding samples.

Operations: AddInstance

{
  "operations": [
    {
      "op": "AddInstance",
      "args": {
        "class_id": 200,
        "key": 1,
        "location": {
          "container_id": 1001,
          "kind": "slot",
          "slot_index": 1
        }
      }
    }
  ]
}

Note: The commit response lists created instance IDs under created_entities.instances, which you can use in follow-on operations.

Step 5 - Set Up Container with Initial Balance

Create a container and populate it with initial resources.

When to use: Initializing player inventories, creating new storage, setting up experiments.

Operations: CreateContainer, AddFungible

{
  "operations": [
    {
      "op": "CreateContainer",
      "args": {
        "container_id": 2001,
        "kind": { "type": "balance" },
        "owner": null,
        "policies": null
      }
    },
    {
      "op": "AddFungible",
      "args": {
        "class_id": 100,
        "key": 1,
        "quantity": 1000,
        "location": {
          "container_id": 2001,
          "kind": "balance"
        }
      }
    },
    {
      "op": "AddFungible",
      "args": {
        "class_id": 101,
        "key": 1,
        "quantity": 500,
        "location": {
          "container_id": 2001,
          "kind": "balance"
        }
      }
    }
  ],
  "idempotency_key": "init-container-2026-01-15-2001"
}

Step 6 - Attach Equipment to Character

Create parent-child relationships between instances for equipment or components.

When to use: Equipping items, attaching components, building hierarchies.

Operations: Attach

{
  "operations": [
    {
      "op": "Attach",
      "args": {
        "child_instance": 9002,
        "parent_instance": 9001
      }
    }
  ]
}

To remove equipment, use Detach followed by the desired placement.

Troubleshooting

Order matters

Operations execute sequentially. Ensure earlier operations create the state that later operations depend on.

Use idempotency keys

Always include idempotency keys for operations that modify state. This prevents duplicate commits on retry.

Check container kinds

Balance operations require balance or grid containers. Slot operations require slots containers. Mismatched kinds cause WrongContainerKind errors.

Validate quantities

Ensure source containers have sufficient balance before transfers. Insufficient balance causes the entire transaction to roll back.

Next steps