@ottochain/sdk 2.2.4 → 2.3.0

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

@@ -0,0 +1,193 @@
+"use strict";
+/**
+ * Genesis Manifest Exporter
+ *
+ * The ottochain metagraph can boot from a NON-EMPTY genesis: a set of standard
+ * packages pre-registered in the registry before any user transaction. This SDK
+ * is the source of truth for those std apps (their proto schemas + JSON-Logic
+ * state-machine definitions), so it is also the source of truth for the
+ * *genesis manifest* — the per-app CONTENT the chain needs to pre-register each
+ * package at genesis.
+ *
+ * DESIGN — content, not consensus hashes:
+ * The manifest ships CONTENT only: the `schemaShape` (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:
+ *   - `logicHash` = `StateMachineDefinition.computeDigest(definition)`
+ *   - `schemaHash` = commitment over the FileDescriptorSet (off-chain/Bridge)
+ * We deliberately do NOT replicate the chain's canonical hashing here, so there
+ * is ZERO hash-parity risk. No advisory hashes are emitted (see HONESTY notes in
+ * the PR description); add them later only if an off-chain consumer needs them,
+ * clearly marked advisory.
+ *
+ * NAMING — the reserved `std` label:
+ * Each package is named `std.<app>.package`. `RegistryName` reserves the `std`
+ * label in-protocol (`RegistryName.isReserved`), so ordinary user registrations
+ * of `std.*` are rejected — only the privileged genesis path may claim them.
+ * That is exactly the point: users cannot squat the standard names.
+ *
+ * SCHEMA SHAPES — chain-verified ground truth:
+ * The three `stateMessage` shapes are reproduced verbatim from the chain's own
+ * conformance suite (`StandardAppsConformanceSuite`, the `identity` / `proposal`
+ * / `market` `MessageShape` vals), which proves the on-chain shape validator and
+ * the conformance gate accept them. `commands` is left EMPTY for this first cut —
+ * the conformance suite itself models all three apps with `SortedMap.empty`
+ * commands, and the proto `*Request` messages are transaction-layer DTOs that do
+ * not map cleanly onto the universal state machines' free-form JSON-Logic event
+ * 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
+ * `StateMachineDefinition`), whose magnolia config is camelCase with defaults.
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildGenesisManifest = exports.GENESIS_MANIFEST_VERSION = void 0;
+const identity_universal_js_1 = require("../apps/identity/state-machines/identity-universal.js");
+const governance_universal_js_1 = require("../apps/governance/state-machines/governance-universal.js");
+const market_universal_js_1 = require("../apps/markets/state-machines/market-universal.js");
+const fiber_app_js_1 = require("../schema/fiber-app.js");
+/** Manifest schema version. Bump on any breaking change to the shape. */
+exports.GENESIS_MANIFEST_VERSION = 1;
+// ─── Chain-verified state-message shapes ──────────────────────────────────────
+// Reproduced VERBATIM from ottochain
+// modules/shared-data/.../StandardAppsConformanceSuite.scala — the `identity`,
+// `proposal`, and `market` MessageShape vals. Keep these byte-for-byte in step
+// with that suite; it is what guarantees the chain accepts them.
+/** Helper: a FieldShape with the two boolean defaults made explicit. */
+function field(name, number, typeName, repeated = false, optional = false) {
+    return { name, number, typeName, repeated, optional };
+}
+/** ottochain.apps.identity.v1.Identity */
+const identityStateMessage = {
+    typeName: 'ottochain.apps.identity.v1.Identity',
+    fields: [
+        field('id', 1, 'string'),
+        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('reputation', 7, 'ottochain.apps.identity.v1.Reputation'),
+        field('stake', 8, 'int64'),
+        field('domains', 9, 'string', true),
+        field('platform_links', 10, 'ottochain.apps.identity.v1.PlatformLink', true),
+        field('penalty_history', 11, 'ottochain.apps.identity.v1.PenaltyEvent', true),
+        field('created_at', 12, 'google.protobuf.Timestamp'),
+        field('updated_at', 13, 'google.protobuf.Timestamp'),
+    ],
+};
+/** ottochain.apps.governance.v1.Proposal */
+const governanceStateMessage = {
+    typeName: 'ottochain.apps.governance.v1.Proposal',
+    fields: [
+        field('id', 1, 'string'),
+        field('title', 2, 'string'),
+        field('description', 3, 'string'),
+        field('action_type', 4, 'string'),
+        field('payload', 5, 'google.protobuf.Struct'),
+        field('proposer', 6, 'string'),
+        field('proposed_at', 7, 'google.protobuf.Timestamp'),
+        field('deadline', 8, 'google.protobuf.Timestamp'),
+        field('queued_at', 9, 'google.protobuf.Timestamp'),
+        field('executable_at', 10, 'google.protobuf.Timestamp'),
+    ],
+};
+/** ottochain.apps.markets.v1.Market */
+const marketStateMessage = {
+    typeName: 'ottochain.apps.markets.v1.Market',
+    fields: [
+        field('id', 1, 'string'),
+        field('market_type', 2, 'ottochain.apps.markets.v1.MarketType'),
+        field('creator', 3, 'string'),
+        field('title', 4, 'string'),
+        field('terms', 5, 'google.protobuf.Struct'),
+        field('deadline', 6, 'google.protobuf.Timestamp'),
+        field('threshold', 7, 'int64'),
+        field('commitments', 8, 'ottochain.apps.markets.v1.Commitment', true),
+        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('created_at', 13, 'google.protobuf.Timestamp'),
+        field('updated_at', 14, 'google.protobuf.Timestamp'),
+    ],
+};
+// ─── Definition projection (single source of truth = the exported defs) ───────
+/**
+ * Project a `FiberAppDefinition` into the chain's wire `StateMachineDefinition`,
+ * matching the `json-archive/*.json` convention exactly:
+ *   - states carry explicit `metadata: null`,
+ *   - transitions carry explicit `dependencies: []`,
+ *   - the TypeScript-only `FiberAppMetadata` is stripped (`metadata: null`).
+ *
+ * Built on the shared `toProtoDefinition` projector so the manifest never drifts
+ * from the SDK's own exported app definitions. The chain decodes `dependencies:
+ * []` / `metadata: null` identically to their absent forms (its codecs use
+ * defaults), so this is consensus-equivalent to the archives while staying
+ * byte-identical to the checked-in `json-archive/*.json` files.
+ */
+function toWireDefinition(def) {
+    const proto = (0, fiber_app_js_1.toProtoDefinition)(def);
+    const states = {};
+    for (const [key, st] of Object.entries(proto.states)) {
+        states[key] = { id: st.id, isFinal: st.isFinal, metadata: null };
+    }
+    return {
+        states,
+        initialState: proto.initialState,
+        transitions: proto.transitions.map((t) => ({
+            from: t.from,
+            to: t.to,
+            eventName: t.eventName,
+            guard: t.guard,
+            effect: t.effect,
+            dependencies: t.dependencies ?? [],
+        })),
+        // Strip FiberAppMetadata — the chain's `metadata` is `Option[JsonLogicValue]`.
+        metadata: null,
+    };
+}
+// ─── Builder ──────────────────────────────────────────────────────────────────
+/**
+ * Assemble the genesis manifest for the standard apps.
+ *
+ * Covers THREE apps in this first cut — identity, governance, markets (all the
+ * `universal` variant). The other std apps (contracts, oracles, corporate) and
+ * non-universal variants are a flagged follow-up.
+ *
+ * @returns a `GenesisManifest` whose JSON deserializes against the chain's circe
+ *   codecs. Hashes are intentionally absent — the chain derives them.
+ */
+function buildGenesisManifest() {
+    const packages = [
+        {
+            name: 'std.identity.package',
+            semver: '1.0.0',
+            strict: false,
+            metadata: {},
+            schemaShape: { stateMessage: identityStateMessage, commands: {} },
+            definition: toWireDefinition(identity_universal_js_1.identityUniversalDef),
+        },
+        {
+            name: 'std.governance.package',
+            semver: '1.0.0',
+            strict: false,
+            metadata: {},
+            schemaShape: { stateMessage: governanceStateMessage, commands: {} },
+            definition: toWireDefinition(governance_universal_js_1.govUniversalDef),
+        },
+        {
+            name: 'std.markets.package',
+            semver: '1.0.0',
+            strict: false,
+            metadata: {},
+            schemaShape: { stateMessage: marketStateMessage, commands: {} },
+            definition: toWireDefinition(market_universal_js_1.marketUniversalDef),
+        },
+    ];
+    return { version: exports.GENESIS_MANIFEST_VERSION, packages };
+}
+exports.buildGenesisManifest = buildGenesisManifest;

package/dist/cjs/ottochain/index.js

@@ -30,7 +30,7 @@ var __importStar = (this && this.__importStar) || function (mod) {
     return result;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.dropNulls = exports.normalizeMessage = exports.normalizeArchiveStateMachine = exports.normalizeTransitionStateMachine = exports.normalizeCreateStateMachine = exports.createDataTransactionRequest = exports.createScriptPayload = exports.createStateMachinePayload = exports.getPublicKeyForRegistration = exports.addTransactionSignature = exports.signTransaction = exports.createInvokeScriptPayload = exports.createArchivePayload = exports.createTransitionPayload = exports.MetagraphClient = exports.extractOnChainState = exports.getScriptInvocations = exports.getEventReceipts = exports.getLogsForFiber = exports.getLatestOnChainState = exports.getSnapshotOnChainState = exports.decodeOnChainState = exports.OTTOCHAIN_MESSAGE_TYPES = exports.proto = void 0;
+exports.GENESIS_MANIFEST_VERSION = exports.buildGenesisManifest = exports.dropNulls = exports.normalizeMessage = exports.normalizeArchiveStateMachine = exports.normalizeTransitionStateMachine = exports.normalizeCreateStateMachine = exports.createDataTransactionRequest = exports.createScriptPayload = exports.createStateMachinePayload = exports.getPublicKeyForRegistration = exports.addTransactionSignature = exports.signTransaction = exports.createInvokeScriptPayload = exports.createArchivePayload = exports.createTransitionPayload = exports.MetagraphClient = exports.extractOnChainState = exports.getScriptInvocations = exports.getEventReceipts = exports.getLogsForFiber = exports.getLatestOnChainState = exports.getSnapshotOnChainState = exports.decodeOnChainState = exports.OTTOCHAIN_MESSAGE_TYPES = exports.proto = void 0;
 // Re-export generated protobuf types (for binary encoding)
 exports.proto = __importStar(require("../generated/index.js"));
 // Runtime message type validation
@@ -65,5 +65,9 @@ Object.defineProperty(exports, "normalizeArchiveStateMachine", { enumerable: tru
 Object.defineProperty(exports, "normalizeMessage", { enumerable: true, get: function () { return normalize_js_1.normalizeMessage; } });
 var drop_nulls_js_1 = require("./drop-nulls.js");
 Object.defineProperty(exports, "dropNulls", { enumerable: true, get: function () { return drop_nulls_js_1.dropNulls; } });
+// Genesis manifest exporter (std-app pre-registration content)
+var genesis_manifest_js_1 = require("./genesis-manifest.js");
+Object.defineProperty(exports, "buildGenesisManifest", { enumerable: true, get: function () { return genesis_manifest_js_1.buildGenesisManifest; } });
+Object.defineProperty(exports, "GENESIS_MANIFEST_VERSION", { enumerable: true, get: function () { return genesis_manifest_js_1.GENESIS_MANIFEST_VERSION; } });
 // Note: Governance and Corporate types are now in src/apps/
 // Import from '@ottochain/sdk/apps' instead

package/dist/cjs/ottochain/normalize.js

@@ -3,41 +3,32 @@
  * Normalize OttoChain Messages for Signing
  *
  * Converts OttoChain message objects to the wire format expected by the
- * Scala metagraph. Metakit's JsonBinaryCodec (used by OttoChain for data
- * transaction signing) canonicalizes JSON with dropNullValues = true.
+ * Scala metagraph. Specifically, ensures all `Option[A]=None` fields are
+ * present as explicit `null` values, matching what circe's magnolia encoder
+ * produces on the Scala side.
  *
- * NOTE: This is Metakit's codec, NOT tessellation's JsonSerializer (which
- * uses Brotli compression for snapshots/consensus — a different layer).
- * Different layers use different byte-sequence encoders.
+ * This is necessary because metakit's `JsonBinaryCodec.deriveDataUpdate`
+ * (rc.8) canonicalizes the circe-encoded JSON **including null fields**.
+ * If the TypeScript client omits optional fields (undefined), the canonical
+ * JSON won't match and signature verification will fail.
  *
- * Because Metakit drops null fields during canonicalization, the canonical
- * JSON used for signature verification **omits** null fields entirely.
- * If the TypeScript client includes explicit nulls (e.g., `"metadata": null`),
- * the canonical form won't match and signature verification will fail.
- *
- * Schema mapping (Scala → TypeScript wire format):
- * - `Option[A] = None` → field OMITTED (not null, not undefined)
+ * Schema mapping (Scala → TypeScript):
+ * - `Option[A] = None` → `null` (must be explicit, not undefined/absent)
  * - `Option[A] = Some(v)` → `v`
- * - `List.empty` / `Set.empty` → `[]`
+ * - `List.empty` → `[]`
  * - `Map.empty` → `{}`
- * - `Boolean = false` → `false` (always include, not a null/Option)
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.normalizeMessage = exports.normalizeArchiveStateMachine = exports.normalizeTransitionStateMachine = exports.normalizeCreateStateMachine = void 0;
 /**
- * Normalize a State object for wire format.
- * State: id (required), isFinal (default false), metadata (Option = None)
- * Omit metadata when null/undefined (dropNullValues).
+ * Normalize a State object for wire format
  */
 function normalizeState(state) {
-    const result = {
+    return {
         id: state.id,
         isFinal: state.isFinal ?? false,
+        metadata: state.metadata ?? null,
     };
-    if (state.metadata != null) {
-        result.metadata = state.metadata;
-    }
-    return result;
 }
 /**
  * Normalize a Transition object for wire format
@@ -89,54 +80,41 @@ function normalizeDefinition(def) {
     }
     const transitions = def.transitions ?? [];
     // Strip FiberAppMetadata if present — it's TypeScript-only, not part of wire format.
-    // Omit metadata entirely when null/FiberAppMetadata (dropNullValues = true on Scala side).
-    const wireMetadata = isFiberAppMetadata(def.metadata) ? undefined : def.metadata;
-    const result = {
+    // The Scala schema has `metadata: Option[Json] = None`, so use null for wire format.
+    const wireMetadata = isFiberAppMetadata(def.metadata) ? null : (def.metadata ?? null);
+    return {
         states: normalizedStates,
         initialState: def.initialState,
         transitions: transitions.map(normalizeTransition),
+        metadata: wireMetadata,
     };
-    if (wireMetadata != null) {
-        result.metadata = wireMetadata;
-    }
-    return result;
 }
 /**
  * Normalize a CreateStateMachine message for wire format
  *
- * Metakit's JsonBinaryCodec uses dropNullValues = true for canonicalization.
- * Optional fields at their defaults must be OMITTED (not set to null)
- * to match the canonical JSON used for signature verification.
- *
- * - definition.metadata → OMITTED when absent/FiberAppMetadata
- * - definition.states[*].metadata → OMITTED when absent
- * - definition.transitions[*].dependencies → [] (Set.empty default, always included)
- * - parentFiberId → OMITTED when absent (Option[UUID] = None)
- * - participants → OMITTED when absent (Option[Set[Address]] = None)
+ * Ensures all Option/default fields are explicit in wire format:
+ * - definition.metadata → null when absent
+ * - definition.states[*].metadata → null when absent
+ * - definition.transitions[*].dependencies → [] when absent
+ * - parentFiberId → null when absent
  *
  * @example
  * ```typescript
  * const message = normalizeCreateStateMachine({
  *   fiberId: '...',
- *   definition: { states: { INIT: { id: 'INIT', isFinal: false } }, ... },
+ *   definition: { states: { INIT: { id: { value: 'INIT' }, isFinal: false } }, ... },
  *   initialData: {}
  * });
- * // Optional fields are absent (not null): no parentFiberId, no metadata, etc.
+ * // message now has parentFiberId: null, definition.metadata: null, etc.
  * ```
  */
 function normalizeCreateStateMachine(msg) {
-    const result = {
+    return {
         fiberId: msg.fiberId,
         definition: normalizeDefinition(msg.definition),
         initialData: msg.initialData ?? {},
+        parentFiberId: msg.parentFiberId ?? null,
     };
-    if (msg.parentFiberId != null) {
-        result.parentFiberId = msg.parentFiberId;
-    }
-    if (msg.participants != null) {
-        result.participants = msg.participants;
-    }
-    return result;
 }
 exports.normalizeCreateStateMachine = normalizeCreateStateMachine;
 /**

package/dist/cjs/ottochain/types.js

@@ -18,6 +18,10 @@ exports.OTTOCHAIN_MESSAGE_TYPES = [
     'CreateStateMachine',
     'TransitionStateMachine',
     'ArchiveStateMachine',
+    'UpgradeFiber',
     'CreateScript',
     'InvokeScript',
+    'PublishVersion',
+    'SetVersionStatus',
+    'RegisterAlias',
 ];

package/dist/esm/apps/contracts/state-machines/contract-agreement.js

@@ -84,12 +84,60 @@ export const contractAgreementDef = defineFiberApp({
         },
     },
     states: {
-        PROPOSED: { id: "PROPOSED", isFinal: false, metadata: null },
-        ACTIVE: { id: "ACTIVE", isFinal: false, metadata: null },
-        COMPLETED: { id: "COMPLETED", isFinal: true, metadata: null },
-        DISPUTED: { id: "DISPUTED", isFinal: false, metadata: null },
-        REJECTED: { id: "REJECTED", isFinal: true, metadata: null },
-        CANCELLED: { id: "CANCELLED", isFinal: true, metadata: null },
+        PROPOSED: {
+            id: "PROPOSED",
+            isFinal: false,
+            metadata: {
+                label: "Proposed",
+                description: "Agreement proposed; awaiting the counterparty",
+                category: "initial",
+            },
+        },
+        ACTIVE: {
+            id: "ACTIVE",
+            isFinal: false,
+            metadata: {
+                label: "Active",
+                description: "Agreement accepted and in effect",
+                category: "active",
+            },
+        },
+        COMPLETED: {
+            id: "COMPLETED",
+            isFinal: true,
+            metadata: {
+                label: "Completed",
+                description: "Agreement completed and attested (terminal)",
+                category: "terminal",
+            },
+        },
+        DISPUTED: {
+            id: "DISPUTED",
+            isFinal: false,
+            metadata: {
+                label: "Disputed",
+                description: "A party has raised a dispute; awaiting resolution",
+                category: "pending",
+            },
+        },
+        REJECTED: {
+            id: "REJECTED",
+            isFinal: true,
+            metadata: {
+                label: "Rejected",
+                description: "Proposal rejected by the counterparty (terminal)",
+                category: "terminal",
+            },
+        },
+        CANCELLED: {
+            id: "CANCELLED",
+            isFinal: true,
+            metadata: {
+                label: "Cancelled",
+                description: "Agreement cancelled before completion (terminal)",
+                category: "terminal",
+            },
+        },
     },
     initialState: "PROPOSED",
     transitions: [

package/dist/esm/apps/contracts/state-machines/contract-escrow.js

@@ -121,14 +121,78 @@ export const contractEscrowDef = defineFiberApp({
         cancel: {},
     },
     states: {
-        CREATED: { id: "CREATED", isFinal: false, metadata: null },
-        FUNDED: { id: "FUNDED", isFinal: false, metadata: null },
-        ACTIVE: { id: "ACTIVE", isFinal: false, metadata: null },
-        RELEASING: { id: "RELEASING", isFinal: false, metadata: null },
-        DISPUTED: { id: "DISPUTED", isFinal: false, metadata: null },
-        RELEASED: { id: "RELEASED", isFinal: true, metadata: null },
-        REFUNDED: { id: "REFUNDED", isFinal: true, metadata: null },
-        SPLIT: { id: "SPLIT", isFinal: true, metadata: null },
+        CREATED: {
+            id: "CREATED",
+            isFinal: false,
+            metadata: {
+                label: "Created",
+                description: "Escrow created; awaiting funding",
+                category: "initial",
+            },
+        },
+        FUNDED: {
+            id: "FUNDED",
+            isFinal: false,
+            metadata: {
+                label: "Funded",
+                description: "Funds deposited into escrow",
+                category: "active",
+            },
+        },
+        ACTIVE: {
+            id: "ACTIVE",
+            isFinal: false,
+            metadata: {
+                label: "Active",
+                description: "Escrow in effect while work is performed",
+                category: "active",
+            },
+        },
+        RELEASING: {
+            id: "RELEASING",
+            isFinal: false,
+            metadata: {
+                label: "Releasing",
+                description: "Release approved; payout in progress",
+                category: "pending",
+            },
+        },
+        DISPUTED: {
+            id: "DISPUTED",
+            isFinal: false,
+            metadata: {
+                label: "Disputed",
+                description: "A party disputed the escrow; awaiting arbitration",
+                category: "pending",
+            },
+        },
+        RELEASED: {
+            id: "RELEASED",
+            isFinal: true,
+            metadata: {
+                label: "Released",
+                description: "Funds released to the beneficiary (terminal)",
+                category: "terminal",
+            },
+        },
+        REFUNDED: {
+            id: "REFUNDED",
+            isFinal: true,
+            metadata: {
+                label: "Refunded",
+                description: "Funds refunded to the depositor (terminal)",
+                category: "terminal",
+            },
+        },
+        SPLIT: {
+            id: "SPLIT",
+            isFinal: true,
+            metadata: {
+                label: "Split",
+                description: "Funds split between parties per arbitration (terminal)",
+                category: "terminal",
+            },
+        },
     },
     initialState: "CREATED",
     transitions: [

package/dist/esm/apps/contracts/state-machines/contract-universal.js

@@ -27,10 +27,42 @@ export const contractUniversalDef = defineFiberApp({
         complete: {},
     },
     states: {
-        PROPOSED: { id: "PROPOSED", isFinal: false, metadata: null },
-        ACTIVE: { id: "ACTIVE", isFinal: false, metadata: null },
-        COMPLETED: { id: "COMPLETED", isFinal: true, metadata: null },
-        CANCELLED: { id: "CANCELLED", isFinal: true, metadata: null },
+        PROPOSED: {
+            id: "PROPOSED",
+            isFinal: false,
+            metadata: {
+                label: "Proposed",
+                description: "Contract proposed; awaiting acceptance",
+                category: "initial",
+            },
+        },
+        ACTIVE: {
+            id: "ACTIVE",
+            isFinal: false,
+            metadata: {
+                label: "Active",
+                description: "Contract accepted and in effect",
+                category: "active",
+            },
+        },
+        COMPLETED: {
+            id: "COMPLETED",
+            isFinal: true,
+            metadata: {
+                label: "Completed",
+                description: "Contract obligations fulfilled (terminal)",
+                category: "terminal",
+            },
+        },
+        CANCELLED: {
+            id: "CANCELLED",
+            isFinal: true,
+            metadata: {
+                label: "Cancelled",
+                description: "Contract cancelled before completion (terminal)",
+                category: "terminal",
+            },
+        },
     },
     initialState: "PROPOSED",
     transitions: [

package/dist/esm/apps/governance/state-machines/dao-multisig.js

@@ -117,9 +117,33 @@ export const daoMultisigDef = defineFiberApp({
         },
     },
     states: {
-        ACTIVE: { id: "ACTIVE", isFinal: false, metadata: null },
-        PENDING: { id: "PENDING", isFinal: false, metadata: null },
-        DISSOLVED: { id: "DISSOLVED", isFinal: true, metadata: null },
+        ACTIVE: {
+            id: "ACTIVE",
+            isFinal: false,
+            metadata: {
+                label: "Active",
+                description: "Multisig is idle and ready to propose an action",
+                category: "initial",
+            },
+        },
+        PENDING: {
+            id: "PENDING",
+            isFinal: false,
+            metadata: {
+                label: "Pending",
+                description: "An action is awaiting the required signature threshold",
+                category: "pending",
+            },
+        },
+        DISSOLVED: {
+            id: "DISSOLVED",
+            isFinal: true,
+            metadata: {
+                label: "Dissolved",
+                description: "Multisig DAO dissolved (terminal)",
+                category: "terminal",
+            },
+        },
     },
     initialState: "ACTIVE",
     transitions: [

package/dist/esm/apps/governance/state-machines/dao-reputation.js

@@ -124,9 +124,33 @@ export const daoReputationDef = defineFiberApp({
         },
     },
     states: {
-        ACTIVE: { id: "ACTIVE", isFinal: false, metadata: null },
-        VOTING: { id: "VOTING", isFinal: false, metadata: null },
-        DISSOLVED: { id: "DISSOLVED", isFinal: true, metadata: null },
+        ACTIVE: {
+            id: "ACTIVE",
+            isFinal: false,
+            metadata: {
+                label: "Active",
+                description: "DAO is idle and ready to accept a proposal",
+                category: "initial",
+            },
+        },
+        VOTING: {
+            id: "VOTING",
+            isFinal: false,
+            metadata: {
+                label: "Voting",
+                description: "Members vote with reputation-weighted power",
+                category: "pending",
+            },
+        },
+        DISSOLVED: {
+            id: "DISSOLVED",
+            isFinal: true,
+            metadata: {
+                label: "Dissolved",
+                description: "Reputation DAO dissolved (terminal)",
+                category: "terminal",
+            },
+        },
     },
     initialState: "ACTIVE",
     transitions: [

package/dist/esm/apps/governance/state-machines/dao-single.js

@@ -75,9 +75,33 @@ export const daoSingleDef = defineFiberApp({
         },
     },
     states: {
-        ACTIVE: { id: "ACTIVE", isFinal: false, metadata: null },
-        TRANSFERRING: { id: "TRANSFERRING", isFinal: false, metadata: null },
-        DISSOLVED: { id: "DISSOLVED", isFinal: true, metadata: null },
+        ACTIVE: {
+            id: "ACTIVE",
+            isFinal: false,
+            metadata: {
+                label: "Active",
+                description: "Single owner controls the DAO and may act or transfer ownership",
+                category: "initial",
+            },
+        },
+        TRANSFERRING: {
+            id: "TRANSFERRING",
+            isFinal: false,
+            metadata: {
+                label: "Transferring",
+                description: "Ownership transfer proposed; awaiting acceptance",
+                category: "pending",
+            },
+        },
+        DISSOLVED: {
+            id: "DISSOLVED",
+            isFinal: true,
+            metadata: {
+                label: "Dissolved",
+                description: "DAO dissolved by its owner (terminal)",
+                category: "terminal",
+            },
+        },
     },
     initialState: "ACTIVE",
     transitions: [