How do make durable objects for orchestration contracts?

[dckc]

An LLM just ran into Cannot pass non-frozen objects like {}. Use harden() and hypothesized that the solution is to harden the state record in an exo init method.

We don't seem to have docs to teach LLMs to make components for orchestration contexts. I tried to get an LLM to write such docs; it's taking a lot longer than I hoped.

I'll share what I've got so far...

[dckc]

Using the Exo API

The @agoric/zone API provides tools for constructing remotely callable objects with clearly defined interfaces and internal state. These "exos" support pattern-based argument validation through @endo/patterns, helping developers catch mistakes early and define strict boundaries for behavior.

The example below defines an exo that greets a nickname and lets a caller update it.

const GreeterI = M.interface('Greeter', {
  greet: M.call().optional(M.string()).returns(M.string()),
  setNick: M.call(M.string()).returns(),
});

/** @param {Zone} zone */
export const prepareGreeter = zone =>
  zone.exoClass('Greeter', GreeterI, nick => ({ nick }), {
    greet(greeting = 'Hello') {
      return `${greeting}, ${this.state.nick}`;
    },
    setNick(nick) {
      this.state.nick = nick;
    },
  });

The interface definition ensures callers must supply valid arguments:

bobGreeter.greet(123)

results in:

Error {
  message: 'In "greet" method of (Greeter): arg 0?: number 123 - Must be a string',
}

The M.interface() function defines a structural contract for an object’s methods, enabling runtime checks on arguments and return types.

The zone.exoClass() function defines an object whose methods are bound to a persistent state record; that state is initialized in the third argument and accessed within methods using this.state. While experienced JavaScript developers might expect state to live directly on this, exos isolate it under this.state to encapsulate internal data—code outside the exo methods cannot access or modify this.state.nick directly.

This design is well-suited to developers coming from strongly typed or RPC-driven frameworks: the behavior is precise, testable, and enforced at the method boundary.

Creating Multiple Instances

So far we've defined how to construct an exo, but not how to make more than one. In most frameworks, you'd instantiate a class or call a factory function. With @agoric/zone, you do that by calling your prepareFoo(zone) function within a vat or contract scope.

This is where the zone comes into play: it gives each instance its own durable storage and identity.

import { makeHeapZone } from '@agoric/zone';
import { prepareGreeter } from './greeter.js';

test('Greeter exoClass', t => {
  const zone = makeHeapZone();
  const makeGreeter = prepareGreeter(zone);
  const bobGreeter = makeGreeter('Bob');

  {
    const actual = bobGreeter.greet();
    t.is(actual, 'Hello, Bob');
  }
});

prepareGreeter(zone) defines a kind—a template for creating exo instances. It returns a maker function, and each call to that function produces a new, isolated exo. Its internal state is private to that instance, and each is fully independent of the others.

const greeterA = makeGreeter('Alice');
const greeterB = makeGreeter('Bob');

// Each greeter holds its own state
E(greeterA).greet(); // "Hello, Alice"
E(greeterB).greet(); // "Hello, Bob"

Notes on Kind Behavior

Kinds—whether created via exoClass or exoClassKit—enforce specific structural constraints that may be surprising to developers coming from class-based or mutable object models:

• The state record returned by the initializer (the third argument) must be a plain object.

• You may update the values of properties (e.g. state.nick = 'Bob'), but not mutate their internals. For example:

  state.jot = { x: 1 };   // ✅ allowed
  state.jot.x = 2;        // ❌ not allowed

• The state is automatically hardened on assignment, and all values must be serializable.

• Once defined, the set of state properties is fixed: you can update values but not add or delete keys.

• The tag (first argument) is used to form a durable identity key—take care to avoid collisions. Use zone.subZone() to namespace safely.

• Once defined, the set of state properties is fixed: you can update values but not add or delete keys.

• The tag (first argument) is used to form a durable identity key—take care to avoid collisions. Use zone.subZone() to namespace safely.

Key/Value Store with a Mutable Store

In contrast to the immutable this.state pattern, if you need internal state that can change deeply over time—like a growing collection—you should use a store. The typical idiom is to create the store inside the kind initializer (the third argument to exoClassKit) so that each instance gets its own store.

Below is a minimal key/value store with separate reader and writer facets. Only the writer can mutate the store.

import { M } from '@endo/patterns';

const StoreKitI = {
  reader: M.interface('ReaderFacet', {
    get: M.call(M.string()).returns(M.or(M.string(), M.undefined())),
  }),
  writer: M.interface('WriterFacet', {
    put: M.call(M.string(), M.string()).returns(),
    delete: M.call(M.string()).returns(),
  }),
};

export const prepareStoreKit = zone =>
  zone.exoClassKit(
    'StoreKit',
    StoreKitI,
    () => ({
      store: zone.detached().mapStore('kvStore', {
        keyShape: M.string(),
        valueShape: M.string(),
      }),
    }),
    {
      reader: {
        get(key) {
          return this.state.store.get(key);
        },
      },
      writer: {
        put(key, value) {
          this.state.store.init(key, value);
        },
        delete(key) {
          this.state.store.delete(key);
        },
      },
    },
  );

This pattern is especially useful when the state evolves over time and must remain durable between contract invocations.

---

Greeter Kit with Faceted Authority

In the previous example, a single object allowed both reading and updating the nickname. Here, we split those responsibilities across two separate objects—called facets—within a single exo kit.

Each facet has its own interface and only exposes the methods relevant to its role:

• The greeter facet can call greet() but has no access to setNick().
• The admin facet can update the nickname but cannot call greet().

This separation supports the principle of least authority: a caller with access to one facet cannot perform actions intended only for another.

There’s also a structural difference in how method definitions are organized. With exoClass, you return a single object whose methods are listed directly. But with exoClassKit, you return a record of named facets—each facet is its own object, and each one holds only the methods specific to that role. This extra layer of nesting can be easy to misplace, especially when first learning the pattern.

const GreeterOnlyI = M.interface('Greeter', {
  greet: M.call().optional(M.string()).returns(M.string()),
  setNick: M.call(M.string()).returns(),
});
const GreeterAdminI = M.interface('Greeter', {
  setNick: M.call(M.string()).returns(),
});

/** @param {Zone} zone */
export const prepareGreeterKit = zone =>
  zone.exoClassKit(
    'GreeterKit',
    { greeter: GreeterOnlyI, admin: GreeterAdminI },
    nick => ({ nick }),
    {
      greeter: {
        greet(greeting = 'Hello') {
          return `${greeting}, ${this.state.nick}`;
        },
      },
      admin: {
        setNick(nick) {
          this.state.nick = nick;
        },
      },
    },
  );

One additional difference to note is how the methods are structured. In exoClass, you return a single object of methods. In exoClassKit, you return a record of named facets, where each facet is its own object containing just the methods for that role. This extra layer of nesting can be subtle at first and easy to misplace.

[dckc]

Outline: Everything About Exos, Durable Objects, and Upgrade

1. Introduction
2. Kinds and Zones
3. State Management
4. Stores (Mutable Internal State)
5. Facets and Kits
6. Baggage and Tag Collisions
7. Contract Upgrade Constraints
8. Common Pitfalls and Debugging Clues
9. Further Reading and References

---

1. Introduction

If you’ve already built the greeter example, you’ve defined a kind—an exo with persistent state and clearly defined behavior. This guide builds on that foundation.

Exos are how the Agoric platform represents persistent, remotable, and upgradeable objects. They are created via zone.exoClass() or zone.exoClassKit(), which define kinds—reusable blueprints for creating durable object instances with interface validation and isolated internal state.

The exo system is key to structuring contracts that survive upgrades while enforcing clear separation of authority.

📚 Source: Zoe Contract Upgrade Guide, SwingSet Virtual Objects

---

2. Kinds and Zones

In practice, a kind is a function that makes durable objects. Each object has a stable identity, its own persistent state, and a fixed behavior surface defined once in advance.

A zone is where kinds live. You get one from your contract environment, and use it to define exos with durable state. Subzones can be used to isolate namespaces.

Here’s a familiar example:

const prepareGreeter = zone =>
  zone.exoClass('Greeter', GreeterI, nick => ({ nick }), {
    greet(greeting = 'Hello') {
      return `${greeting}, ${this.state.nick}`;
    },
  });

You call prepareGreeter(zone) once to define the kind. It returns a maker function. Calling that function (e.g. makeGreeter('Bob')) creates an instance with its own durable state and behavior.

🔍 Terminology: exoClass defines a single interface (facet); exoClassKit defines a bundle of named facets that share internal state.

📚 Source: SwingSet Virtual Objects

---

3. State Management

Every instance of a kind gets its own this.state object. This record is returned by the kind initializer—the third argument to exoClass or exoClassKit.

// ✅ OK:
this.state.nick = 'Bob';

// ❌ NOT OK:
this.state.nick = { x: 1 };
this.state.nick.x = 2; // runtime error!

// ❌ Also NOT OK:
this.state.list = harden([]);
this.state.list.push('item'); // runtime error!

Rules:

• The shape of this.state is fixed once returned.
• Values must be serializable and are automatically deeply hardened.
• You can replace values (this.state.foo = newThing), but cannot mutate their internals (this.state.foo.bar = ... or this.state.list.push(...)).

To manage evolving or nested state, consider using a store (see next section).

📚 Source: Zoe Upgrade Guide – Kinds

---

4. Stores (Mutable Internal State)

If you want to track internal data that must be updated deeply (e.g., a growing list or map), use a store.

Use zone.detached().mapStore(...) inside your kind initializer:

() => ({
  table: zone.detached().mapStore('table', {
    keyShape: M.string(),
    valueShape: M.string(),
  }),
})

A store is the sanctioned way to encapsulate durable internal data that changes over time. It supports operations like init, has, get, set, and delete, and can be safely mutated.

zone.detached() creates a store that is not tied to the zone’s baggage and is allocated per-instance. These stores live as long as the object instance does.

📚 Source: Patterns from transaction-feed.ts, settler.ts

---

5. Facets and Kits

Each object created by exoClassKit returns a bundle of objects, called facets. Each facet exposes a specific set of methods while sharing access to the same internal state.

exoClassKit defines a kind with multiple named facets (e.g. reader, admin) that share internal state but expose different methods. This pattern supports separation of authority by giving each facet limited and specific behavior.

Here's a basic example that builds on the greeter concept:

const prepareGreeterKit = zone => {
  const GreeterKitI = {
    reader: M.interface('ReaderFacet', {
      greet: M.call().returns(M.string()),
    }),
    admin: M.interface('AdminFacet', {
      setNick: M.call(M.string()).returns(M.undefined()),
    }),
  };

  return zone.exoClassKit(
    'GreeterKit',
    GreeterKitI,
    nick => ({ nick }),
    {
      reader: {
        greet() {
          return `Hello, ${this.state.nick}`;
        },
      },
      admin: {
        setNick(newNick) {
          this.state.nick = newNick;
        },
      },
    }
  );
};

When you call the maker returned by prepareGreeterKit, you get a record like { reader, admin }, where each facet object has a durable identity and shared access to this.state.

Note that in this structure, the method definitions are grouped under the facet keys. Each method implementation still uses this.state, just as in the single-facet exoClass case.

📚 Source: patterns from transaction-feed.ts, liquidity-pool.ts

---

6. Baggage and Tag Collisions

The tag (first argument to exoClass or exoClassKit) is used to form a key in the system’s durable object table ("baggage"). If you reuse a tag across kinds or modules, you’ll trigger collisions—either runtime errors or silent corruption.

To avoid this, use subzones:

const subZone = zone.subZone('kv');
const prepareStore = subZone.exoClass(...);

This ensures unique namespaces and prevents kind identity clashes.

📚 Source: Zoe Upgrade Guide

---

7. Contract Upgrade Constraints

When a contract is upgraded, all durable kinds must preserve their state shape and behavior contracts. SwingSet restores each object by re-running the kind definition (via prepareFoo), then rehydrates stored state into that shape.

Upgrade constraints:

• The tag (first argument) must match the previous deployment
• The number and names of facets (if using kits) must remain unchanged
• The shape of this.state must not change (no added/removed properties)
• Store tags and shapes must remain stable

📌 You may refactor code and reorder logic, but kinds must remain compatible at the interface and state level.

📚 Source: Zoe Contract Upgrade Guide

---

8. Common Pitfalls and Debugging Clues

🔸 Deep mutation

this.state.foo = harden({ x: 1 });
this.state.foo.x = 2; // ❌ runtime error

Always reassign the outer object (this.state.foo = {...}) instead.

🔸 Array updates

this.state.list = harden([]);
this.state.list.push('x'); // ❌ also fails

Use stores if you need mutable collections.

🔸 Facet confusion If your method isn’t showing up, check which facet it’s in.

🔸 Baggage collisions Reusing the same zone or tag across upgrades without a subZone will cause identity mismatches.

📌 Use vatData.getKindID() and console.log() (in devnets) to inspect state structure.

---

9. Further Reading and References

• Zoe Contract Upgrade Guide
• SwingSet Virtual Objects
• transaction-feed.ts
• liquidity-pool.ts
• settler.ts
• endo patterns and baggage APIs

[dckc]

AI Code Generation: Context and Constraints

Modern AI code generation tools—such as GitHub Copilot, ChatGPT, and Claude—are trained primarily on high-volume, mainstream open-source codebases. As a result, they perform best in ecosystems with strong conventions and broad representation in training data. These include:

• Web frameworks like Django, Rails, Express, and Spring
• Frontend stacks like React, Vue, or Next.js
• Infrastructure-as-code tools like Terraform, CloudFormation, or Pulumi
• Routine backend tasks: CRUD APIs, form validation, ORM usage, etc.

These environments provide:

• Readily available public examples
• Clear conventions and naming patterns
• Limited need for reasoning about fine-grained authority or distributed object persistence

---

Why Agoric Patterns Are Different

In contrast, the Agoric ecosystem—particularly the @agoric/zone API and the exoClass/exoClassKit family—presents challenges for AI tools:

• Low public representation in training data
• Object-capability discipline, which requires careful authority separation
• Durable state models and SwingSet persistence semantics
• Faceted interfaces that encode fine-grained permission models
• Input guards that rely on @endo/patterns, which are sparsely documented outside Agoric

This means that:

AI tools don’t yet know Agoric—they can only learn from examples.

The audience for these docs isn’t expecting autocomplete or boilerplate—they’re teaching patterns to the AI, not retrieving them.

---

Intended Audience

The primary audience is:

• Engineers already familiar with JavaScript/TypeScript
• Developers comfortable with asynchronous and distributed programming
• Contributors building secure smart contracts or support libraries within Agoric

They are not looking for tutorials on syntax—but they do value:

• Small, correct, idiomatic examples
• Naming consistency that matches the real codebase
• Explicit patterns for authority separation and validation

These docs aim to enable AI tools to assist usefully, by first showing them what correctness looks like.

[dckc]

see also:

• teach exo's from the start? documentation#1033