Docs

Recipes

Recipes are common multi-operation patterns that accomplish typical workflows. Use these as templates for your transactions.

Prerequisites

  • 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.

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

Operations: RemoveFungible, AddFungible

{
  "operations": [
    {
      "op": "RemoveFungible",
      "args": {
        "container_id": 1001,
        "class_id": 200,
        "key": 1,
        "quantity": 150
      }
    },
    {
      "op": "AddFungible",
      "args": {
        "container_id": 1002,
        "class_id": 200,
        "key": 1,
        "quantity": 150
      }
    }
  ],
  "idempotency_key": "transfer-balance-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.

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

Operations: RemoveFromSlot, PlaceInSlot

{
  "operations": [
    {
      "op": "RemoveFromSlot",
      "args": {
        "container_id": 1001,
        "slot_index": 0
      }
    },
    {
      "op": "PlaceInSlot",
      "args": {
        "container_id": 1001,
        "slot_index": 1,
        "instance_id": 9001
      }
    }
  ],
  "idempotency_key": "slot-move-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,
          "name": "Battle Tank",
          "fungible": false
        }
      }
    },
    {
      "op": "RegisterClassShape",
      "args": {
        "request": {
          "class_id": 300,
          "shape_id": 1,
          "width": 3,
          "height": 2
        }
      }
    }
  ],
  "idempotency_key": "class-with-shape-300"
}

Step 4 - Mint 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: MintInstance, PlaceInSlot

{
  "operations": [
    {
      "op": "MintInstance",
      "args": {
        "class_id": 200,
        "key": 1
      }
    },
    {
      "op": "PlaceInSlot",
      "args": {
        "container_id": 1001,
        "instance_id": 9001,
        "slot_index": 0
      }
    }
  ]
}

Note: You need to know the instance ID that will be minted. Either use a deterministic allocation scheme or send the mint and place as separate transactions.

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": "Standard",
        "owner": null
      }
    },
    {
      "op": "AddFungible",
      "args": {
        "container_id": 2001,
        "class_id": 100,
        "key": 1,
        "quantity": 1000
      }
    },
    {
      "op": "AddFungible",
      "args": {
        "container_id": 2001,
        "class_id": 101,
        "key": 1,
        "quantity": 500
      }
    }
  ],
  "idempotency_key": "init-container-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: MintInstance, Attach

{
  "operations": [
    {
      "op": "MintInstance",
      "args": {
        "class_id": 300,
        "key": 1
      }
    },
    {
      "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 Standard 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