@ottochain/sdk 1.0.3 → 1.1.1

package/dist/esm/apps/oracles/state-machines/oracle.json

@@ -6,52 +6,36 @@
     },
     "states": {
         "UNREGISTERED": {
-            "id": {
-                "value": "UNREGISTERED"
-            },
+            "id": "UNREGISTERED",
             "isFinal": false,
             "metadata": null
         },
         "REGISTERED": {
-            "id": {
-                "value": "REGISTERED"
-            },
+            "id": "REGISTERED",
             "isFinal": false,
             "metadata": null
         },
         "ACTIVE": {
-            "id": {
-                "value": "ACTIVE"
-            },
+            "id": "ACTIVE",
             "isFinal": false,
             "metadata": null
         },
         "SLASHED": {
-            "id": {
-                "value": "SLASHED"
-            },
+            "id": "SLASHED",
             "isFinal": false,
             "metadata": null
         },
         "WITHDRAWN": {
-            "id": {
-                "value": "WITHDRAWN"
-            },
+            "id": "WITHDRAWN",
             "isFinal": true,
             "metadata": null
         }
     },
-    "initialState": {
-        "value": "UNREGISTERED"
-    },
+    "initialState": "UNREGISTERED",
     "transitions": [
         {
-            "from": {
-                "value": "UNREGISTERED"
-            },
-            "to": {
-                "value": "REGISTERED"
-            },
+            "from": "UNREGISTERED",
+            "to": "REGISTERED",
             "eventName": "register",
             "guard": {
                 ">=": [
@@ -95,12 +79,8 @@
             "dependencies": []
         },
         {
-            "from": {
-                "value": "REGISTERED"
-            },
-            "to": {
-                "value": "ACTIVE"
-            },
+            "from": "REGISTERED",
+            "to": "ACTIVE",
             "eventName": "activate",
             "guard": {
                 "or": [
@@ -135,12 +115,8 @@
             "dependencies": []
         },
         {
-            "from": {
-                "value": "ACTIVE"
-            },
-            "to": {
-                "value": "ACTIVE"
-            },
+            "from": "ACTIVE",
+            "to": "ACTIVE",
             "eventName": "add_stake",
             "guard": {
                 "and": [
@@ -189,12 +165,8 @@
             "dependencies": []
         },
         {
-            "from": {
-                "value": "ACTIVE"
-            },
-            "to": {
-                "value": "ACTIVE"
-            },
+            "from": "ACTIVE",
+            "to": "ACTIVE",
             "eventName": "record_resolution",
             "guard": {
                 "var": "event.marketId"
@@ -249,12 +221,8 @@
             "dependencies": []
         },
         {
-            "from": {
-                "value": "ACTIVE"
-            },
-            "to": {
-                "value": "SLASHED"
-            },
+            "from": "ACTIVE",
+            "to": "SLASHED",
             "eventName": "slash",
             "guard": {
                 "and": [
@@ -330,12 +298,8 @@
             "dependencies": []
         },
         {
-            "from": {
-                "value": "SLASHED"
-            },
-            "to": {
-                "value": "ACTIVE"
-            },
+            "from": "SLASHED",
+            "to": "ACTIVE",
             "eventName": "reactivate",
             "guard": {
                 "and": [
@@ -377,12 +341,8 @@
             "dependencies": []
         },
         {
-            "from": {
-                "value": "ACTIVE"
-            },
-            "to": {
-                "value": "WITHDRAWN"
-            },
+            "from": "ACTIVE",
+            "to": "WITHDRAWN",
             "eventName": "withdraw",
             "guard": {
                 "===": [
@@ -413,12 +373,8 @@
             "dependencies": []
         },
         {
-            "from": {
-                "value": "SLASHED"
-            },
-            "to": {
-                "value": "WITHDRAWN"
-            },
+            "from": "SLASHED",
+            "to": "WITHDRAWN",
             "eventName": "withdraw",
             "guard": {
                 "===": [

package/dist/esm/generated/index.js

@@ -2,9 +2,19 @@
  * Generated Protobuf Types
  *
  * Auto-generated from proto/ definitions using ts-proto.
- * DO NOT EDIT - regenerate with `pnpm run generate`
+ * DO NOT EDIT - regenerate with `npm run generate`
  *
  * @packageDocumentation
+ *
+ * NOTE — Dual-type architecture:
+ * These generated types use proto conventions (FIBER_STATUS_ACTIVE, plain string StateId).
+ * The wire-format REST API types in src/ottochain/types.ts use plain strings ('Active').
+ * Both coexist intentionally until PR #89 (Migrate fiber-engine to generated Scala types) merges.
+ *
+ * TODO PR #89 migration: after PR #89 merges and cluster confirms new format,
+ * migrate all state-machine JSON files in src/apps/ from Circe-format
+ * ({ value: '...' } wrapped initialState) to plain string format.
+ * See docs/type-architecture.md for full migration plan.
  */
 // Core types (primitives - no wrapper messages)
 // Type aliases are in src/types.ts

package/dist/esm/metakit/drop-nulls.js

@@ -0,0 +1,46 @@
+/**
+ * Drop Null Values from JSON Objects
+ *
+ * Recursively removes null-valued keys from objects to match
+ * the Scala-side `JsonBinaryCodec.dropNulls` behavior in metakit.
+ *
+ * This ensures that the canonical JSON used for signing on the
+ * TypeScript side matches what the Scala metagraph produces when
+ * verifying signatures.
+ *
+ * Note: null values inside arrays are preserved (to maintain index
+ * positions). Only object field values that are null are removed.
+ */
+/**
+ * Recursively remove null values from objects
+ *
+ * @param value - Any JSON-serializable value
+ * @returns A deep copy with null object fields removed
+ *
+ * @example
+ * ```typescript
+ * dropNulls({ a: 1, b: null, c: { d: null, e: 2 } })
+ * // => { a: 1, c: { e: 2 } }
+ *
+ * dropNulls([1, null, 3])
+ * // => [1, null, 3]  (array nulls preserved)
+ * ```
+ */
+export function dropNulls(value) {
+    if (value === null || value === undefined) {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map(dropNulls);
+    }
+    if (typeof value === 'object') {
+        const result = {};
+        for (const [k, v] of Object.entries(value)) {
+            if (v !== null && v !== undefined) {
+                result[k] = dropNulls(v);
+            }
+        }
+        return result;
+    }
+    return value;
+}

package/dist/esm/metakit/normalize.js

@@ -0,0 +1,140 @@
+/**
+ * Normalize OttoChain Messages for Signing
+ *
+ * Converts OttoChain message objects to the wire format expected by the
+ * 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.
+ *
+ * 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.
+ *
+ * Schema mapping (Scala → TypeScript):
+ * - `Option[A] = None` → `null` (must be explicit, not undefined/absent)
+ * - `Option[A] = Some(v)` → `v`
+ * - `List.empty` → `[]`
+ * - `Map.empty` → `{}`
+ */
+/**
+ * Normalize a State object for wire format
+ */
+function normalizeState(state) {
+    return {
+        id: state.id,
+        isFinal: state.isFinal ?? false,
+        metadata: state.metadata ?? null,
+    };
+}
+/**
+ * Normalize a Transition object for wire format
+ */
+function normalizeTransition(t) {
+    return {
+        from: t.from,
+        eventName: t.eventName,
+        to: t.to,
+        guard: t.guard ?? null,
+        actions: t.actions ?? null,
+        metadata: t.metadata ?? null,
+    };
+}
+/**
+ * Normalize a StateMachineDefinition for wire format
+ */
+function normalizeDefinition(def) {
+    const states = def.states;
+    const normalizedStates = {};
+    if (states) {
+        for (const [key, state] of Object.entries(states)) {
+            normalizedStates[key] = normalizeState(state);
+        }
+    }
+    const transitions = def.transitions ?? [];
+    return {
+        states: normalizedStates,
+        initialState: def.initialState,
+        transitions: transitions.map(normalizeTransition),
+        metadata: def.metadata ?? null,
+    };
+}
+/**
+ * Normalize a CreateStateMachine message for wire format
+ *
+ * Ensures all Option fields are explicit null:
+ * - definition.metadata
+ * - definition.states[*].metadata
+ * - definition.transitions[*].guard
+ * - definition.transitions[*].actions
+ * - definition.transitions[*].metadata
+ * - parentFiberId
+ *
+ * @example
+ * ```typescript
+ * const message = normalizeCreateStateMachine({
+ *   fiberId: '...',
+ *   definition: { states: { INIT: { id: { value: 'INIT' }, isFinal: false } }, ... },
+ *   initialData: {}
+ * });
+ * // message now has parentFiberId: null, definition.metadata: null, etc.
+ * ```
+ */
+export function normalizeCreateStateMachine(msg) {
+    return {
+        fiberId: msg.fiberId,
+        definition: normalizeDefinition(msg.definition),
+        initialData: msg.initialData ?? {},
+        parentFiberId: msg.parentFiberId ?? null,
+    };
+}
+/**
+ * Normalize a TransitionStateMachine message for wire format
+ */
+export function normalizeTransitionStateMachine(msg) {
+    return {
+        fiberId: msg.fiberId,
+        eventName: msg.eventName,
+        eventData: msg.eventData ?? null,
+        fiberOrdinal: msg.fiberOrdinal,
+    };
+}
+/**
+ * Normalize an ArchiveStateMachine message for wire format
+ */
+export function normalizeArchiveStateMachine(msg) {
+    return {
+        fiberId: msg.fiberId,
+        reason: msg.reason ?? null,
+    };
+}
+/**
+ * Normalize any OttochainMessage wrapper for wire format.
+ *
+ * Detects the message type from the wrapper key and applies the
+ * appropriate normalization.
+ *
+ * @param message - OttochainMessage in wrapper format: `{ CreateStateMachine: {...} }`
+ * @returns Normalized message with all Option fields as explicit null
+ *
+ * @example
+ * ```typescript
+ * const normalized = normalizeMessage({
+ *   CreateStateMachine: { fiberId: '...', definition: {...}, initialData: {} }
+ * });
+ * const signed = await signDataUpdate(normalized, privateKey);
+ * ```
+ */
+export function normalizeMessage(message) {
+    if ('CreateStateMachine' in message) {
+        return { CreateStateMachine: normalizeCreateStateMachine(message.CreateStateMachine) };
+    }
+    if ('TransitionStateMachine' in message) {
+        return { TransitionStateMachine: normalizeTransitionStateMachine(message.TransitionStateMachine) };
+    }
+    if ('ArchiveStateMachine' in message) {
+        return { ArchiveStateMachine: normalizeArchiveStateMachine(message.ArchiveStateMachine) };
+    }
+    // CreateScript and InvokeScript — pass through (no optional fields)
+    return message;
+}

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

@@ -135,6 +135,153 @@ export class MetagraphClient {
         return snapshot.value.ordinal;
     }
     // -------------------------------------------------------------------------
+    // Fiber state subscription
+    // -------------------------------------------------------------------------
+    /**
+     * Subscribe to state changes for a state machine fiber.
+     *
+     * Polls ML0 at the configured interval and compares `sequenceNumber` to
+     * detect changes. Fires the callback with `(current, previous)` on the
+     * first poll (if `fireImmediately` is true — the default) and on every
+     * subsequent change.
+     *
+     * ML0 consistency: state is read from snapshot-level `CalculatedState`
+     * (via `checkpointService.get`), so a poll never returns a mid-transition
+     * value — every observation is a fully committed state.
+     *
+     * Uses `setTimeout` recursion to prevent overlapping polls when a request
+     * takes longer than `pollIntervalMs`.
+     *
+     * @param fiberId  - UUID of the state machine fiber to watch
+     * @param callback - Called on first observation and on every state change
+     * @param options  - Polling interval, error handler, fireImmediately flag
+     * @returns Unsubscribe function — call to stop polling immediately
+     *
+     * @example
+     * ```typescript
+     * const unsub = client.subscribeFiberState(fiberId, (current, prev) => {
+     *   if (current?.currentState === 'Completed') {
+     *     unsub();
+     *   }
+     * });
+     * // Later:
+     * unsub();
+     * ```
+     */
+    subscribeFiberState(fiberId, callback, options) {
+        const intervalMs = options?.pollIntervalMs ?? 2000;
+        const onError = options?.onError ?? ((e) => console.warn('[subscribeFiberState]', e));
+        const fireImmediately = options?.fireImmediately ?? true;
+        let previous = null;
+        let lastSeqNum = null;
+        let firstPoll = true; // Track first poll separately — handles null seqNum on missing fiber
+        let active = true;
+        const invokeCallback = (current, prev) => {
+            try {
+                callback(current, prev);
+            }
+            catch (cbErr) {
+                try {
+                    onError(cbErr instanceof Error ? cbErr : new Error(String(cbErr)));
+                }
+                catch { /* ignore */ }
+            }
+        };
+        const poll = async () => {
+            if (!active)
+                return;
+            let current;
+            try {
+                current = await this.getStateMachine(fiberId);
+            }
+            catch (err) {
+                // Network / timeout error — notify and reschedule
+                if (!active)
+                    return;
+                try {
+                    onError(err instanceof Error ? err : new Error(String(err)));
+                }
+                catch { /* ignore */ }
+                if (active)
+                    setTimeout(poll, intervalMs);
+                return;
+            }
+            // Guard: unsubscribe may have been called while awaiting
+            if (!active)
+                return;
+            const currentSeq = current?.sequenceNumber ?? null;
+            if (firstPoll) {
+                firstPoll = false;
+                lastSeqNum = currentSeq;
+                previous = current;
+                if (fireImmediately) {
+                    invokeCallback(current, null);
+                }
+            }
+            else if (currentSeq !== lastSeqNum) {
+                // State changed — sequenceNumber differs (handles null → value and value → null)
+                const prev = previous;
+                previous = current;
+                lastSeqNum = currentSeq;
+                invokeCallback(current, prev);
+            }
+            // No change → no callback
+            // Schedule next poll (setTimeout recursion prevents overlapping polls)
+            if (active)
+                setTimeout(poll, intervalMs);
+        };
+        // Start first poll via setTimeout(0) so Jest fake-timer control works correctly:
+        // callers can unsubscribe before the first poll runs, and each
+        // jest.runOnlyPendingTimersAsync() advances exactly one poll cycle.
+        setTimeout(poll, 0);
+        return () => { active = false; };
+    }
+    /**
+     * Wait for a fiber to reach a specific state, with an optional timeout.
+     *
+     * Builds on `subscribeFiberState` — resolves with the fiber record once
+     * `currentState === targetState`, or resolves with `null` after `timeoutMs`.
+     * Always calls unsubscribe on resolution or timeout (no memory leaks).
+     *
+     * @param fiberId     - UUID of the state machine fiber
+     * @param targetState - State name to wait for (e.g. `'Completed'`)
+     * @param timeoutMs   - Maximum wait in milliseconds (default: 30 000)
+     * @returns Fiber record when target state reached, or `null` on timeout
+     *
+     * @example
+     * ```typescript
+     * const result = await client.waitForState(fiberId, 'Completed', 15_000);
+     * if (result === null) console.warn('Timed out waiting for Completed');
+     * ```
+     */
+    waitForState(fiberId, targetState, timeoutMs = 30000, options) {
+        return new Promise((resolve) => {
+            let resolved = false;
+            let timer = null;
+            // unsub starts as a no-op so it's safe to call even if subscribeFiberState
+            // invokes the callback synchronously (before returning the real unsubscribe).
+            let unsub = () => { };
+            const done = (result) => {
+                if (resolved)
+                    return;
+                resolved = true;
+                if (timer !== null)
+                    clearTimeout(timer);
+                unsub(); // safe: either the real unsub or the initial no-op
+                resolve(result);
+            };
+            unsub = this.subscribeFiberState(fiberId, (current) => {
+                if (current?.currentState === targetState) {
+                    done(current);
+                }
+            }, { fireImmediately: true, ...options });
+            // Only arm the timeout if the callback hasn't already resolved (synchronous case)
+            if (!resolved) {
+                timer = setTimeout(() => done(null), timeoutMs);
+            }
+        });
+    }
+    // -------------------------------------------------------------------------
     // DL1 data submission (framework POST /data)
     // -------------------------------------------------------------------------
     /**

package/dist/esm/validation.js

@@ -131,7 +131,7 @@ export const PlatformLinkSchema = z.object({
 /**
  * Schema for contract terms (flexible structure)
  */
-export const ContractTermsSchema = z.record(z.unknown());
+export const ContractTermsSchema = z.record(z.string(), z.unknown());
 /**
  * Schema for ProposeContractRequest
  */

package/dist/types/generated/index.d.ts

@@ -2,9 +2,19 @@
  * Generated Protobuf Types
  *
  * Auto-generated from proto/ definitions using ts-proto.
- * DO NOT EDIT - regenerate with `pnpm run generate`
+ * DO NOT EDIT - regenerate with `npm run generate`
  *
  * @packageDocumentation
+ *
+ * NOTE — Dual-type architecture:
+ * These generated types use proto conventions (FIBER_STATUS_ACTIVE, plain string StateId).
+ * The wire-format REST API types in src/ottochain/types.ts use plain strings ('Active').
+ * Both coexist intentionally until PR #89 (Migrate fiber-engine to generated Scala types) merges.
+ *
+ * TODO PR #89 migration: after PR #89 merges and cluster confirms new format,
+ * migrate all state-machine JSON files in src/apps/ from Circe-format
+ * ({ value: '...' } wrapped initialState) to plain string format.
+ * See docs/type-architecture.md for full migration plan.
  */
 export { FiberStatus, AccessControlPolicy, PublicAccess, WhitelistAccess, FiberOwnedAccess, StateMachineDefinition, EmittedEvent, EventReceipt, ScriptInvocation, FiberLogEntry, } from './ottochain/v1/fiber.js';
 export { CreateStateMachine, TransitionStateMachine, ArchiveStateMachine, CreateScript, InvokeScript, OttochainMessage, } from './ottochain/v1/messages.js';

package/dist/types/metakit/drop-nulls.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Drop Null Values from JSON Objects
+ *
+ * Recursively removes null-valued keys from objects to match
+ * the Scala-side `JsonBinaryCodec.dropNulls` behavior in metakit.
+ *
+ * This ensures that the canonical JSON used for signing on the
+ * TypeScript side matches what the Scala metagraph produces when
+ * verifying signatures.
+ *
+ * Note: null values inside arrays are preserved (to maintain index
+ * positions). Only object field values that are null are removed.
+ */
+/**
+ * Recursively remove null values from objects
+ *
+ * @param value - Any JSON-serializable value
+ * @returns A deep copy with null object fields removed
+ *
+ * @example
+ * ```typescript
+ * dropNulls({ a: 1, b: null, c: { d: null, e: 2 } })
+ * // => { a: 1, c: { e: 2 } }
+ *
+ * dropNulls([1, null, 3])
+ * // => [1, null, 3]  (array nulls preserved)
+ * ```
+ */
+export declare function dropNulls<T>(value: T): T;

package/dist/types/metakit/normalize.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Normalize OttoChain Messages for Signing
+ *
+ * Converts OttoChain message objects to the wire format expected by the
+ * 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.
+ *
+ * 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.
+ *
+ * Schema mapping (Scala → TypeScript):
+ * - `Option[A] = None` → `null` (must be explicit, not undefined/absent)
+ * - `Option[A] = Some(v)` → `v`
+ * - `List.empty` → `[]`
+ * - `Map.empty` → `{}`
+ */
+/**
+ * Normalize a CreateStateMachine message for wire format
+ *
+ * Ensures all Option fields are explicit null:
+ * - definition.metadata
+ * - definition.states[*].metadata
+ * - definition.transitions[*].guard
+ * - definition.transitions[*].actions
+ * - definition.transitions[*].metadata
+ * - parentFiberId
+ *
+ * @example
+ * ```typescript
+ * const message = normalizeCreateStateMachine({
+ *   fiberId: '...',
+ *   definition: { states: { INIT: { id: { value: 'INIT' }, isFinal: false } }, ... },
+ *   initialData: {}
+ * });
+ * // message now has parentFiberId: null, definition.metadata: null, etc.
+ * ```
+ */
+export declare function normalizeCreateStateMachine(msg: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Normalize a TransitionStateMachine message for wire format
+ */
+export declare function normalizeTransitionStateMachine(msg: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Normalize an ArchiveStateMachine message for wire format
+ */
+export declare function normalizeArchiveStateMachine(msg: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Normalize any OttochainMessage wrapper for wire format.
+ *
+ * Detects the message type from the wrapper key and applies the
+ * appropriate normalization.
+ *
+ * @param message - OttochainMessage in wrapper format: `{ CreateStateMachine: {...} }`
+ * @returns Normalized message with all Option fields as explicit null
+ *
+ * @example
+ * ```typescript
+ * const normalized = normalizeMessage({
+ *   CreateStateMachine: { fiberId: '...', definition: {...}, initialData: {} }
+ * });
+ * const signed = await signDataUpdate(normalized, privateKey);
+ * ```
+ */
+export declare function normalizeMessage(message: Record<string, unknown>): Record<string, unknown>;

package/dist/types/ottochain/index.d.ts

@@ -9,5 +9,5 @@ export * as proto from '../generated/index.js';
 export type { Address, FiberId, StateId, HashValue, FiberOrdinal, SnapshotOrdinal, JsonLogicValue, JsonLogicExpression, FiberStatus, AccessControlPolicy, StateMachineDefinition, EmittedEvent, EventReceipt, OracleInvocation, FiberLogEntry, StateMachineFiberRecord, ScriptFiberRecord, FiberRecord, FiberCommit, OnChain, CalculatedState, CreateStateMachine, TransitionStateMachine, ArchiveStateMachine, CreateScript, InvokeScript, OttochainMessage, } from './types.js';
 export type { CurrencySnapshotResponse } from './snapshot.js';
 export { decodeOnChainState, getSnapshotOnChainState, getLatestOnChainState, getLogsForFiber, getEventReceipts, getScriptInvocations, extractOnChainState, } from './snapshot.js';
-export type { Checkpoint, MetagraphClientConfig } from './metagraph-client.js';
+export type { Checkpoint, MetagraphClientConfig, SubscribeOptions, FiberStateCallback, Unsubscribe, } from './metagraph-client.js';
 export { MetagraphClient } from './metagraph-client.js';