Deployments

A Deployment is a running instance of a world. It contains the actual runtime state - entity instances, event bindings, and execution history. Multiple deployments can exist for a single world, each with isolated state.

Creating a Deployment

Deployments are created with a first event binding:

POST /api/worlds/:worldAddress/deployments
{
  "name": "Season 1",
  "description": "First season of the racing simulation",
  "isLLMPublic": false,
  "aiModelId": "openai/gpt-oss-120b",
  "payToAddress": "6Q2...wallet",
  "bindings": [{
    "event": "race_result",
    "eventVersion": 1,
    "targetChains": ["solana-devnet"],
    "onchain": {
      "stateChanges": ["wins", "speed_rating"],
      "result": ["winner"]
    }
  }]
}

Fields

Use this table when creating a deployment payload.

Target Chains

Use targetChains on each binding to choose where execution records for that event are pushed.

The targetChains field is an array of network-specific chain identifiers. An empty array (default) means no on-chain storage.

You can specify multiple chains per binding:

{
  "bindings": [{
    "event": "race_result",
    "eventVersion": 1,
    "targetChains": ["solana-devnet", "near-testnet"]
  }]
}

When both Solana and NEAR chains are included, the stricter Solana size limit applies.

Public & Paid Execution

Deployments can expose execution publicly via /app/deployments/:address/execute when the bound event version has executionSettings.visibility = "public".

If executionSettings.priceUsd is set, public callers must include a valid x402 X-Payment header and the deployment must define payToAddress.

AI Model Selection

Each deployment can specify which AI model to use for event execution via aiModelId. Available models are listed at GET /api/ai-models. If not specified, the default model (openai/gpt-oss-120b) is used.

Selective On-Chain Push

The onchain config controls which fields from stateChanges and result get pushed to the blockchain. This is now configured per-binding:

{
  "bindings": [{
    "event": "race_result",
    "eventVersion": 1,
    "onchain": {
      "stateChanges": ["wins", "speed_rating"],
      "result": ["winner"]
    }
  }]
}

When set, only the specified keys are included in the on-chain push. When omitted or null, all data is pushed. This is useful for staying within Solana's 1232-byte per-field limit.

What a Deployment Contains

Deployment
├── Entity Instances (actual data)
│   ├── horse:HORSE_1 { name: "Midnight", speed: 0.85 }
│   ├── horse:HORSE_2 { name: "Thunder", speed: 0.78 }
│   └── ...
├── Event Bindings (which event versions to use)
│   ├── race_result -> version 1
│   └── ...
└── Event History (execution records)
    ├── History #1: race_result executed at 2024-06-15
    └── ...

Deployment Modes

Deployments operate in one of two modes: upgradable (default) or locked.

Upgradable Mode

The default mode for new deployments. All operations are permitted.

Allowed Operations:

• Execute events
• Create/update entity instances
• Add event bindings
• Update deployment metadata
• Transition to locked mode

Locked Mode

A frozen state where no modifications are allowed. This transition is irreversible.

Blocked Operations:

• Execute events
• Create/update/delete entity instances
• Add event bindings
• Delete the deployment

Allowed Operations:

• Read deployment data
• Read entity instances
• Read event history

Locking a Deployment

POST /api/worlds/:worldAddress/deployments/:deploymentAddress/lock

Mode Comparison

Snapshotting

Snapshotting allows you to create a new deployment by copying the state from an existing one. This is useful for forking simulations, creating test environments, or preserving state before major changes.

How It Works

When creating a deployment with a sourceDeploymentId, the system:

1. Creates the new deployment
2. Copies all entity instances from the source
3. Copies event bindings (except duplicates)
4. New deployment starts as upgradable

{
  "name": "Season 2",
  "bindings": [{ "event": "race_result", "eventVersion": 2 }],
  "sourceDeployment": "0x123...abc"
}

What Gets Copied

Use Cases

• Forking Simulations: Create parallel timelines from a common point
• Testing: Test new event versions without affecting production
• Pre-Lock Preservation: Create a snapshot before locking to continue later
• Version Migration: Upgrade to new event versions while preserving state

Related Concepts

• Architecture - Blueprint vs Live layer
• Entities - Data within deployments
• Events - Event versioning
• On-chain Oracle - On-chain verification
• AI Engine - Model selection and execution