Architecture

Narrative Protocol uses a two-layer architecture that separates design-time definitions from runtime state.

Blueprint Layer (Design-Time)

The Blueprint layer contains definitions that describe the structure and behavior of your world. These don't hold runtime data.

Worlds

Top-level containers that group related definitions together.

World Definition

{
  "name": "Horse Racing",
  "description": "A horse racing simulation",
  "domainTags": ["sports", "simulation"],
  "promptSeed": "This world simulates realistic horse racing events."
}

Fields:

name - Human-readable identifier
description - What this world simulates
domainTags - Categories for organization
promptSeed - Base context for AI-driven event resolution

Entity Schemas

Define the shape of entities. They are templates, not data containers.

Entity Schema

{
  "name": "horse",
  "description": "A racing horse",
  "attributes": [
    { "name": "speed_rating", "type": "float", "defaultValue": 0.5 },
    { "name": "stamina", "type": "float", "defaultValue": 0.5 }
  ]
}

Attribute Types:

Type	Description
`string`	Text values
`integer`	Whole numbers
`float`	Floating-point numbers
`boolean`	True/false values
`json`	Complex nested data

Events

Define what can happen in the world. Events have versioned behavior.

Event Definition

{
  "name": "race_result",
  "description": "Resolves a race",
  "firstVersion": {
    "inputSchema": { "raceId": "string" },
    "stateChangeSchema": { "horse": "partial" },
    "mutationSettings": {
      "mode": "ai",
      "behaviorPrompt": "Determine the winner based on horse stats"
    }
  }
}

Live Layer (Runtime)

The Live layer contains actual runtime state and execution records.

Deployments

Running instances of a world with their own isolated state.

Deployment

{
  "worldAddress": "0xd36f777a077ff3825653f6d521f1437b4da69699",
  "name": "Season 1",
  "mode": "upgradable",
  "bindings": [{ "event": "race_result", "eventVersion": 1 }]
}

Entity Instances

Actual data belonging to a deployment. Multiple instances can share a schema.

Entity Instance

{
  "deploymentAddress": "0x123...abc",
  "entitySchema": "horse",
  "instanceId": "HORSE_1",
  "state": { "name": "Midnight Comet", "speed_rating": 0.85 }
}

Event Bindings

Connect deployments to specific event versions.

Event History

Records of every event execution with inputs, outputs, and attestations.

Relationship Diagram

Blueprint Layer                 Live Layer
────────────────              ─────────────────
World ─────────────────────── Deployment (targetChain)
  │                               │
  ├── Entity Schema ────────── Entity Instance
  │     └── Attribute             └── state (JSON)
  │
  └── Event ───────────────── Event Binding
        └── Event Version         └── History Record
                                        ├── Solana Record
                                        └── NEAR Record

Design Principles

Separation of Concerns: Definitions (what can exist) vs State (what does exist)
Immutability: Published versions and locked deployments cannot change
Auditability: Full history with cryptographic attestations
Verifiability: On-chain records for independent verification

Events - Event versioning
Deployments - Deployments
Entities - Entities
On-chain Oracle - On-chain verification