@ottochain/sdk 2.3.0 → 2.5.0

package/dist/esm/ottochain/genesis-manifest.js

@@ -9,7 +9,7 @@
  * package at genesis.
  *
  * DESIGN — content, not consensus hashes:
- * The manifest ships CONTENT only: the `schemaShape` (the typed, proto-faithful
+ * The manifest ships CONTENT only: the `machineShape` (the typed, proto-faithful
  * projection of the app's state message) and the `definition` (the JSON-Logic
  * `StateMachineDefinition`, verbatim — the same object the chain decodes for any
  * fiber). The CHAIN computes the consensus values itself from this content:
@@ -37,7 +37,7 @@
  * payloads. Deriving per-event command shapes is a flagged follow-up.
  *
  * The JSON shape emitted here is built to deserialize against the chain's circe
- * codecs (`SchemaShape` / `FieldShape` / `MessageShape` and
+ * codecs (`MachineShape` / `FieldShape` / `MessageShape` and
  * `StateMachineDefinition`), whose magnolia config is camelCase with defaults.
  *
  * @packageDocumentation
@@ -65,8 +65,8 @@ const identityStateMessage = {
         field('address', 2, 'string'),
         field('public_key', 3, 'string'),
         field('display_name', 4, 'string'),
-        field('identity_type', 5, 'ottochain.apps.identity.v1.IdentityType'),
-        field('state', 6, 'ottochain.apps.identity.v1.IdentityState'),
+        field('identity_type', 5, 'ottochain.apps.identity.v1.Type'),
+        field('state', 6, 'ottochain.apps.identity.v1.State'),
         field('reputation', 7, 'ottochain.apps.identity.v1.Reputation'),
         field('stake', 8, 'int64'),
         field('domains', 9, 'string', true),
@@ -97,7 +97,7 @@ const marketStateMessage = {
     typeName: 'ottochain.apps.markets.v1.Market',
     fields: [
         field('id', 1, 'string'),
-        field('market_type', 2, 'ottochain.apps.markets.v1.MarketType'),
+        field('market_type', 2, 'ottochain.apps.markets.v1.Type'),
         field('creator', 3, 'string'),
         field('title', 4, 'string'),
         field('terms', 5, 'google.protobuf.Struct'),
@@ -107,7 +107,7 @@ const marketStateMessage = {
         field('oracles', 9, 'string', true),
         field('quorum', 10, 'int32'),
         field('resolutions', 11, 'ottochain.apps.markets.v1.Resolution', true),
-        field('status', 12, 'ottochain.apps.markets.v1.MarketState'),
+        field('status', 12, 'ottochain.apps.markets.v1.State'),
         field('created_at', 13, 'google.protobuf.Timestamp'),
         field('updated_at', 14, 'google.protobuf.Timestamp'),
     ],
@@ -145,6 +145,12 @@ function toWireDefinition(def) {
         })),
         // Strip FiberAppMetadata — the chain's `metadata` is `Option[JsonLogicValue]`.
         metadata: null,
+        // Carry the fiber constitution through verbatim from the shared projector: PRESENT for
+        // `Constrained` (a bare object of set dials) and `Immutable` (the bare string
+        // `"Immutable"`), ABSENT for `Unconstrained`. The `policy` key is only set here when
+        // `toProtoDefinition` emitted one, so an unconstrained def keeps NO `policy` key
+        // (omit-on-unconstrained wire parity).
+        ...(proto.policy !== undefined ? { policy: proto.policy } : {}),
     };
 }
 // ─── Builder ──────────────────────────────────────────────────────────────────
@@ -165,7 +171,7 @@ export function buildGenesisManifest() {
             semver: '1.0.0',
             strict: false,
             metadata: {},
-            schemaShape: { stateMessage: identityStateMessage, commands: {} },
+            machineShape: { stateMessage: identityStateMessage, commands: {} },
             definition: toWireDefinition(identityUniversalDef),
         },
         {
@@ -173,7 +179,7 @@ export function buildGenesisManifest() {
             semver: '1.0.0',
             strict: false,
             metadata: {},
-            schemaShape: { stateMessage: governanceStateMessage, commands: {} },
+            machineShape: { stateMessage: governanceStateMessage, commands: {} },
             definition: toWireDefinition(govUniversalDef),
         },
         {
@@ -181,7 +187,7 @@ export function buildGenesisManifest() {
             semver: '1.0.0',
             strict: false,
             metadata: {},
-            schemaShape: { stateMessage: marketStateMessage, commands: {} },
+            machineShape: { stateMessage: marketStateMessage, commands: {} },
             definition: toWireDefinition(marketUniversalDef),
         },
     ];

package/dist/esm/ottochain/index.js

@@ -8,13 +8,12 @@
 // Re-export generated protobuf types (for binary encoding)
 export * as proto from '../generated/index.js';
 // Runtime message type validation
-export { OTTOCHAIN_MESSAGE_TYPES } from './types.js';
+export { OTTOCHAIN_MESSAGE_TYPES, TOKEN_BEHAVIOR_BITS } from './types.js';
 export { decodeOnChainState, getSnapshotOnChainState, getLatestOnChainState, getLogsForFiber, getEventReceipts, getScriptInvocations, extractOnChainState, } from './snapshot.js';
 export { MetagraphClient } from './metagraph-client.js';
 // Transaction helpers (state machine payloads, signing)
-export { createTransitionPayload, createArchivePayload, createInvokeScriptPayload, signTransaction, addTransactionSignature, getPublicKeyForRegistration, createStateMachinePayload, createScriptPayload, createDataTransactionRequest, } from './transaction.js';
+export { createTransitionPayload, createArchivePayload, createInvokeScriptPayload, signTransaction, addTransactionSignature, getPublicKeyForRegistration, createStateMachinePayload, createScriptPayload, createDataTransactionRequest, createAssetPolicyPayload, createMintAssetPayload, createApplyMorphismPayload, createAuthorizeComposePayload, } from './transaction.js';
 // Data utilities
-export { normalizeCreateStateMachine, normalizeTransitionStateMachine, normalizeArchiveStateMachine, normalizeMessage, } from './normalize.js';
 export { dropNulls } from './drop-nulls.js';
 // Genesis manifest exporter (std-app pre-registration content)
 export { buildGenesisManifest, GENESIS_MANIFEST_VERSION } from './genesis-manifest.js';

package/dist/esm/ottochain/metagraph-client.js

@@ -4,7 +4,7 @@
  * Client for interacting with ottochain ML0 custom routes (/v1 prefix)
  * and framework snapshot endpoints.
  *
- * @see modules/l0/src/main/scala/xyz/kd5ujc/metagraph_l0/ML0CustomRoutes.scala
+ * @see modules/l0/src/main/scala/xyz/kd5ujc/metagraph_l0/ML0Routes.scala
  * @see modules/data_l1/src/main/scala/xyz/kd5ujc/data_l1/DataL1CustomRoutes.scala
  * @packageDocumentation
  */
@@ -28,7 +28,7 @@ import { extractOnChainState } from './snapshot.js';
  * const onChain = await client.getOnChain();
  *
  * // Get all active state machines
- * const machines = await client.getStateMachines('Active');
+ * const machines = await client.getStateMachines('ACTIVE');
  *
  * // Get event receipts for a fiber
  * const events = await client.getStateMachineEvents(fiberId);
@@ -87,18 +87,18 @@ export class MetagraphClient {
         return this.ml0.get(`/data-application/v1/state-machines/${fiberId}/events`);
     }
     /**
-     * Get all script oracles, optionally filtered by status.
+     * Get all scripts, optionally filtered by status.
      */
     async getScripts(status) {
         const query = status ? `?status=${status}` : '';
-        return this.ml0.get(`/data-application/v1/oracles${query}`);
+        return this.ml0.get(`/data-application/v1/scripts${query}`);
     }
     /**
-     * Get a single script oracle by fiber ID.
+     * Get a single script by fiber ID.
      */
     async getScript(scriptId) {
         try {
-            return await this.ml0.get(`/data-application/v1/oracles/${scriptId}`);
+            return await this.ml0.get(`/data-application/v1/scripts/${scriptId}`);
         }
         catch (error) {
             if (error instanceof NetworkError && error.statusCode === 404) {
@@ -108,10 +108,67 @@ export class MetagraphClient {
         }
     }
     /**
-     * Get oracle invocations from the current ordinal's logs.
+     * Get script invocations from the current ordinal's logs.
      */
     async getScriptInvocations(scriptId) {
-        return this.ml0.get(`/data-application/v1/oracles/${scriptId}/invocations`);
+        return this.ml0.get(`/data-application/v1/scripts/${scriptId}/invocations`);
+    }
+    // -------------------------------------------------------------------------
+    // Registry, audit, state-proofs, fee estimates (ML0 /data-application/v1/*)
+    // -------------------------------------------------------------------------
+    /** Get the metagraph version string. */
+    async getVersion() {
+        return this.ml0.get('/data-application/v1/version');
+    }
+    /** Get the full registry namespace, keyed by full registry name `labels.tld`. */
+    async getRegistry() {
+        return this.ml0.get('/data-application/v1/registry');
+    }
+    /** Resolve a single registry entry by full name (`labels.tld`), or null if unregistered. */
+    async getRegistryEntry(name) {
+        try {
+            return await this.ml0.get(`/data-application/v1/registry/${encodeURIComponent(name)}`);
+        }
+        catch (error) {
+            if (error instanceof NetworkError && error.statusCode === 404)
+                return null;
+            throw error;
+        }
+    }
+    /** Reverse-resolve a fiber UUID to its canonical registered name (#29), or null. */
+    async getReverseName(fiberId) {
+        try {
+            return await this.ml0.get(`/data-application/v1/registry/reverse/${fiberId}`);
+        }
+        catch (error) {
+            if (error instanceof NetworkError && error.statusCode === 404)
+                return null;
+            throw error;
+        }
+    }
+    /** Get the rendered audit-trail lines for a state-machine fiber. */
+    async getStateMachineAudit(fiberId) {
+        return this.ml0.get(`/data-application/v1/state-machines/${fiberId}/audit`);
+    }
+    /** Light-client state proof for a field of a state-machine fiber, against the committed root. */
+    async getStateMachineStateProof(fiberId, field) {
+        return this.ml0.get(`/data-application/v1/state-machines/${fiberId}/state-proof?field=${encodeURIComponent(field)}`);
+    }
+    /** Light-client state proof for a field of a script fiber. */
+    async getScriptStateProof(fiberId, field) {
+        return this.ml0.get(`/data-application/v1/scripts/${fiberId}/state-proof?field=${encodeURIComponent(field)}`);
+    }
+    /** Light-client state proof for a field of an asset instance. */
+    async getAssetStateProof(assetId, field) {
+        return this.ml0.get(`/data-application/v1/assets/${assetId}/state-proof?field=${encodeURIComponent(field)}`);
+    }
+    /** Estimate the fee/gas for a transition event on a state-machine fiber. */
+    async estimateTransitionFee(fiberId, eventName) {
+        return this.ml0.get(`/data-application/v1/state-machines/${fiberId}/estimate-fee?event=${encodeURIComponent(eventName)}`);
+    }
+    /** Estimate the fee/gas for invoking a script fiber. */
+    async estimateScriptFee(fiberId) {
+        return this.ml0.get(`/data-application/v1/scripts/${fiberId}/estimate-fee`);
     }
     // -------------------------------------------------------------------------
     // Framework snapshot endpoints (ML0 /snapshots/*)
@@ -187,7 +244,9 @@ export class MetagraphClient {
                 try {
                     onError(cbErr instanceof Error ? cbErr : new Error(String(cbErr)));
                 }
-                catch { /* ignore */ }
+                catch {
+                    /* ignore */
+                }
             }
         };
         const poll = async () => {
@@ -204,7 +263,9 @@ export class MetagraphClient {
                 try {
                     onError(err instanceof Error ? err : new Error(String(err)));
                 }
-                catch { /* ignore */ }
+                catch {
+                    /* ignore */
+                }
                 if (active)
                     setTimeout(poll, intervalMs);
                 return;
@@ -237,7 +298,9 @@ export class MetagraphClient {
         // callers can unsubscribe before the first poll runs, and each
         // jest.runOnlyPendingTimersAsync() advances exactly one poll cycle.
         setTimeout(poll, 0);
-        return () => { active = false; };
+        return () => {
+            active = false;
+        };
     }
     /**
      * Wait for a fiber to reach a specific state, with an optional timeout.
@@ -335,14 +398,16 @@ export class MetagraphClient {
             let settled = false;
             let pending = this.dl1Clients.length;
             for (const client of this.dl1Clients) {
-                client.post('/data', request).then((result) => { if (!settled) {
-                    settled = true;
-                    resolve(result);
-                } }, (err) => {
+                client.post('/data', request).then((result) => {
+                    if (!settled) {
+                        settled = true;
+                        resolve(result);
+                    }
+                }, (err) => {
                     errors.push(err instanceof Error ? err : new Error(String(err)));
                     pending--;
                     if (pending === 0 && !settled) {
-                        reject(new Error('All DL1 nodes failed: ' + errors.map(e => e.message).join('; ')));
+                        reject(new Error('All DL1 nodes failed: ' + errors.map((e) => e.message).join('; ')));
                     }
                 });
             }

package/dist/esm/ottochain/snapshot.js

@@ -73,7 +73,7 @@ export function getLogsForFiber(onChain, fiberId) {
 /**
  * Get EventReceipt log entries for a specific fiber.
  *
- * EventReceipts are distinguished from OracleInvocations by the presence
+ * EventReceipts are distinguished from ScriptInvocations by the presence
  * of the `eventName` field.
  *
  * @param onChain - Decoded on-chain state
@@ -81,20 +81,18 @@ export function getLogsForFiber(onChain, fiberId) {
  * @returns Array of EventReceipt entries
  */
 export function getEventReceipts(onChain, fiberId) {
-    return getLogsForFiber(onChain, fiberId)
-        .filter((entry) => 'eventName' in entry && 'success' in entry);
+    return getLogsForFiber(onChain, fiberId).filter((entry) => 'eventName' in entry && 'success' in entry);
 }
 /**
- * Get OracleInvocation log entries for a specific fiber.
+ * Get ScriptInvocation log entries for a specific fiber.
  *
- * OracleInvocations are distinguished from EventReceipts by the presence
+ * ScriptInvocations are distinguished from EventReceipts by the presence
  * of the `method` field.
  *
  * @param onChain - Decoded on-chain state
  * @param fiberId - Fiber UUID to filter by
- * @returns Array of OracleInvocation entries
+ * @returns Array of ScriptInvocation entries
  */
 export function getScriptInvocations(onChain, fiberId) {
-    return getLogsForFiber(onChain, fiberId)
-        .filter((entry) => 'method' in entry && 'result' in entry);
+    return getLogsForFiber(onChain, fiberId).filter((entry) => 'method' in entry && 'result' in entry);
 }

package/dist/esm/ottochain/transaction.js

@@ -4,10 +4,18 @@
  * These helpers create properly formatted payloads for the bridge's
  * self-signed mode, where clients sign their own transactions.
  */
-import { signDataUpdate, getPublicKeyId } from '@constellation-network/metagraph-sdk';
+import { getPublicKeyId } from '@constellation-network/metagraph-sdk';
+import { signDataUpdate } from '../signing.js';
 /**
  * Create a new state machine fiber payload.
  *
+ * @remarks
+ * `params.definition` is signed VERBATIM. Pass the output of `toProtoDefinition(def)` (the
+ * allowlisted wire shape) — NOT a raw `FiberAppDefinition`: extra authoring fields
+ * (`createSchema` / `stateSchema` / `eventSchemas` / per-transition `emits`) would be signed
+ * but re-encoded away by the chain, diverging the canonical → opaque `InvalidSignature`.
+ * See `tests/ottochain/signing-parity.test.ts`.
+ *
  * @param params - State machine creation parameters
  * @returns A CreateStateMachine message ready for signing
  *
@@ -94,7 +102,7 @@ export function createArchivePayload(params) {
  *     },
  *   },
  *   initialState: { value: 0 },
- *   accessControl: { type: 'open' },
+ *   accessControl: { Public: {} },
  * });
  * const signed = await signTransaction(script, privateKey);
  * ```
@@ -105,7 +113,7 @@ export function createScriptPayload(params) {
             fiberId: params.fiberId,
             scriptProgram: params.scriptProgram,
             initialState: params.initialState ?? null,
-            accessControl: params.accessControl ?? { type: 'open' },
+            accessControl: params.accessControl ?? { Public: {} },
         },
     };
 }
@@ -125,12 +133,49 @@ export function createInvokeScriptPayload(params) {
         },
     };
 }
+// ============================================================================
+// Asset Operations (asset-model.md §7)
+// ============================================================================
+//
+// Thin typed wrappers: the chain message types ({@link CreateAssetPolicy}, etc.) already model
+// every field (required vs `Option`), so these builders just apply the `{ MessageName: ... }`
+// envelope, for API parity with the state-machine/script `create*Payload` helpers. Sign the result
+// with {@link signTransaction} (the canonical `JCS(dropNulls)` path drops any omitted optionals).
+/** Wrap a {@link CreateAssetPolicy} (publish an asset-policy package version). */
+export function createAssetPolicyPayload(params) {
+    return { CreateAssetPolicy: params };
+}
+/** Wrap a {@link MintAsset} (mint a new asset instance against a resolved policy version). */
+export function createMintAssetPayload(params) {
+    return { MintAsset: params };
+}
+/** Wrap an {@link ApplyMorphism} (apply a typed morphism to an asset instance). */
+export function createApplyMorphismPayload(params) {
+    return { ApplyMorphism: params };
+}
+/** Wrap an {@link AuthorizeCompose} (commit half of the symmetric-compose handshake). */
+export function createAuthorizeComposePayload(params) {
+    return { AuthorizeCompose: params };
+}
+/** Wrap a {@link PublishMachineVersion} (create-or-append a STATE-MACHINE registry version). */
+export function createPublishMachineVersionPayload(params) {
+    return { PublishMachineVersion: params };
+}
+/** Wrap an {@link UpgradeFiber} (re-pin a fiber to another registered version of the SAME package). */
+export function createUpgradeFiberPayload(params) {
+    return { UpgradeFiber: params };
+}
 /**
  * Sign a transaction payload for self-signed mode.
  *
  * This creates a Signed<T> object with the exact format expected by the bridge's
  * `/agent/transition` endpoint when using self-signed mode.
  *
+ * The signature is computed over the null-dropped canonical bytes (null
+ * object fields removed recursively, array nulls preserved, then RFC 8785),
+ * matching metakit's content-hash rule. Explicit-null and absent optional
+ * fields therefore produce identical signatures.
+ *
  * @param message - The message to sign (e.g., from createTransitionPayload)
  * @param privateKey - The private key in hex format (64 characters)
  * @returns A signed object ready for submission to the bridge
@@ -199,6 +244,9 @@ export function createDataTransactionRequest(signed) {
  * Use this for multi-signature scenarios where multiple parties
  * need to sign the same transaction.
  *
+ * The new signature is computed over the null-dropped canonical bytes,
+ * matching metakit's content-hash rule (see {@link signTransaction}).
+ *
  * @param signed - The already-signed transaction
  * @param privateKey - Additional signer's private key
  * @returns Transaction with additional signature

package/dist/esm/ottochain/types.js

@@ -7,6 +7,14 @@
  * @see modules/models/src/main/scala/xyz/kd5ujc/schema/
  * @packageDocumentation
  */
+/** Bit weights for {@link TokenBehavior} (T=16, S=8, C=4, E=2, G=1). */
+export const TOKEN_BEHAVIOR_BITS = {
+    transferable: 16,
+    splittable: 8,
+    combinable: 4,
+    expirable: 2,
+    governable: 1,
+};
 /**
  * Names of all valid OttochainMessage types.
  * Use this for runtime validation (e.g., in API routes).
@@ -18,7 +26,13 @@ export const OTTOCHAIN_MESSAGE_TYPES = [
     'UpgradeFiber',
     'CreateScript',
     'InvokeScript',
-    'PublishVersion',
+    'UpgradeScript',
+    'PublishMachineVersion',
+    'PublishScriptVersion',
     'SetVersionStatus',
     'RegisterAlias',
+    'CreateAssetPolicy',
+    'MintAsset',
+    'ApplyMorphism',
+    'AuthorizeCompose',
 ];

package/dist/esm/privacy/index.js

@@ -0,0 +1,6 @@
+/**
+ * Privacy: shield any fiber app into a zk-jlvm-shielded private-state pool.
+ * See docs/design/zk-private-contract-state-rfc.md.
+ */
+export { shieldApp, SHIELDED_POOL_STATE } from './shield-app.js';
+export { sealedBidAccountDef, shieldedSealedBidDef, vickreyAuctionDef } from './sealed-bid.js';

package/dist/esm/privacy/sealed-bid.js

@@ -0,0 +1,209 @@
+/**
+ * Sealed-bid (Vickrey) auction — the worked example for the privacy stack.
+ *
+ * Two pieces (RFC §4):
+ *  1. `sealedBidAccountDef` — the PRIVATE per-bidder bid. `shieldApp` turns it into a shielded
+ *     pool (`shieldedSealedBidDef`): a bidder commits a bid note and proves it well-formed with a
+ *     zk-jlvm-shielded Groth16 proof, so the amount stays sealed *until the deadline*. This is the
+ *     mechanical per-instance / single-owner case.
+ *  2. `vickreyAuctionDef` — the PUBLIC settlement (reveal-then-tally). After the deadline bidders
+ *     open their notes; the combine computes winner = argmax and clearingPrice = second-highest
+ *     (the Vickrey price). This is the one shared-state step, kept simple for v1; a zk settlement
+ *     proof that seals losers' amounts forever is the deferred upgrade (RFC §10).
+ */
+import { defineFiberApp } from '../schema/fiber-app.js';
+import { shieldApp } from './shield-app.js';
+// ── 1. The private bid (base app, shielded by shieldApp) ──────────────────────
+/** The per-bidder PRIVATE state: a bid note `{ amount, bidder, nonce }`. */
+export const sealedBidAccountDef = defineFiberApp({
+    metadata: {
+        name: 'SealedBidAccount',
+        app: 'markets',
+        type: 'sealed-bid-account',
+        version: '1.0.0',
+        description: "A single bidder's sealed bid (private amount). Shielded via shieldApp.",
+    },
+    stateSchema: {
+        properties: {
+            amount: { type: 'number', description: 'the (private) bid amount' },
+            bidder: { type: 'address' },
+            nonce: { type: 'number', description: 'per-note randomness; keeps the commitment hiding' },
+        },
+    },
+    eventSchemas: {
+        place_bid: {
+            description: 'Set the sealed bid amount',
+            required: ['amount'],
+            properties: { amount: { type: 'number', minimum: 1 } },
+        },
+    },
+    states: {
+        OPEN: { id: 'OPEN', isFinal: false, metadata: { label: 'Open', description: 'No bid yet', category: 'initial' } },
+        BID: { id: 'BID', isFinal: false, metadata: { label: 'Bid', description: 'Bid committed', category: 'active' } },
+    },
+    initialState: 'OPEN',
+    transitions: [
+        {
+            // This effect is what the zk-jlvm-shielded circuit runs in-zkVM; `exprHash` pins it.
+            from: 'OPEN',
+            to: 'BID',
+            eventName: 'place_bid',
+            guard: { '>': [{ var: 'event.amount' }, 0] },
+            effect: { merge: [{ var: 'state' }, { amount: { var: 'event.amount' } }] },
+            dependencies: [],
+        },
+    ],
+});
+/**
+ * The shielded sealed-bid pool. `vkey`/`exprHash` come from the built zk-jlvm-shielded circuit
+ * (these are placeholders until the circuit's program vkey + the keccak of the `place_bid` effect
+ * are wired in by the genesis/build step).
+ */
+export function shieldedSealedBidDef(opts) {
+    return shieldApp(sealedBidAccountDef, opts);
+}
+// ── 2. The public Vickrey settlement ──────────────────────────────────────────
+/**
+ * Public reveal-then-tally settlement. `reveal` appends an opened bid (in a full build the opening
+ * is checked against the recorded commitment in the shielded pool); `settle` computes the winner
+ * and the Vickrey (second-price) clearing price over the revealed bids in one reduce.
+ */
+export const vickreyAuctionDef = defineFiberApp({
+    metadata: {
+        name: 'VickreyAuction',
+        app: 'markets',
+        type: 'vickrey-auction',
+        version: '1.0.0',
+        description: 'Sealed-bid second-price auction: public reveal-then-tally over shielded bids.',
+        crossReferences: { bidPool: 'the ShieldedSealedBidAccount pool holding the sealed bids' },
+    },
+    createSchema: {
+        required: ['seller', 'deadline'],
+        properties: {
+            seller: { type: 'address', immutable: true },
+            deadline: { type: 'timestamp', immutable: true },
+        },
+    },
+    stateSchema: {
+        properties: {
+            seller: { type: 'address', immutable: true },
+            deadline: { type: 'timestamp', immutable: true },
+            status: { type: 'string', computed: true },
+            revealed: { type: 'array', computed: true, description: 'opened bids [{bidder, amount}]' },
+            winner: { type: 'address', computed: true },
+            clearingPrice: { type: 'number', computed: true, description: 'second-highest bid (Vickrey)' },
+        },
+    },
+    eventSchemas: {
+        reveal: {
+            description: 'Open a sealed bid after the deadline',
+            required: ['bidder', 'amount'],
+            properties: { bidder: { type: 'address' }, amount: { type: 'number', minimum: 1 } },
+        },
+        settle: { description: 'Tally the revealed bids (winner + second price)' },
+    },
+    states: {
+        OPEN: {
+            id: 'OPEN',
+            isFinal: false,
+            metadata: { label: 'Open', description: 'Bidding (sealed)', category: 'initial' },
+        },
+        REVEAL: {
+            id: 'REVEAL',
+            isFinal: false,
+            metadata: { label: 'Reveal', description: 'Opening bids', category: 'active' },
+        },
+        SETTLED: {
+            id: 'SETTLED',
+            isFinal: true,
+            metadata: { label: 'Settled', description: 'Winner + price set', category: 'terminal' },
+        },
+    },
+    initialState: 'OPEN',
+    transitions: [
+        {
+            from: 'OPEN',
+            to: 'REVEAL',
+            eventName: 'reveal',
+            guard: { '>=': [{ var: '$timestamp' }, { var: 'state.deadline' }] },
+            effect: {
+                merge: [
+                    { var: 'state' },
+                    {
+                        status: 'REVEAL',
+                        revealed: {
+                            cat: [{ var: 'state.revealed' }, [{ bidder: { var: 'event.bidder' }, amount: { var: 'event.amount' } }]],
+                        },
+                    },
+                ],
+            },
+            dependencies: [],
+        },
+        {
+            from: 'REVEAL',
+            to: 'REVEAL',
+            eventName: 'reveal',
+            guard: { '>=': [{ var: '$timestamp' }, { var: 'state.deadline' }] },
+            effect: {
+                merge: [
+                    { var: 'state' },
+                    {
+                        revealed: {
+                            cat: [{ var: 'state.revealed' }, [{ bidder: { var: 'event.bidder' }, amount: { var: 'event.amount' } }]],
+                        },
+                    },
+                ],
+            },
+            dependencies: [],
+        },
+        {
+            // Vickrey tally: fold the revealed bids tracking (max, second, winner).
+            from: 'REVEAL',
+            to: 'SETTLED',
+            eventName: 'settle',
+            guard: { '>': [{ reduce: [{ var: 'state.revealed' }, { '+': [{ var: 'accumulator' }, 1] }, 0] }, 0] },
+            effect: {
+                merge: [
+                    { var: 'state' },
+                    {
+                        status: 'SETTLED',
+                        settledAt: { var: '$timestamp' },
+                        winner: {
+                            var: ['tally.winner', null],
+                        },
+                        clearingPrice: { var: ['tally.second', 0] },
+                        // compute the tally once and expose it for the two fields above
+                        tally: {
+                            reduce: [
+                                { var: 'state.revealed' },
+                                {
+                                    if: [
+                                        { '>': [{ var: 'current.amount' }, { var: 'accumulator.max' }] },
+                                        {
+                                            max: { var: 'current.amount' },
+                                            second: { var: 'accumulator.max' },
+                                            winner: { var: 'current.bidder' },
+                                        },
+                                        {
+                                            if: [
+                                                { '>': [{ var: 'current.amount' }, { var: 'accumulator.second' }] },
+                                                {
+                                                    max: { var: 'accumulator.max' },
+                                                    second: { var: 'current.amount' },
+                                                    winner: { var: 'accumulator.winner' },
+                                                },
+                                                { var: 'accumulator' },
+                                            ],
+                                        },
+                                    ],
+                                },
+                                { max: 0, second: 0, winner: null },
+                            ],
+                        },
+                    },
+                ],
+            },
+            dependencies: [],
+        },
+    ],
+});