@ottochain/sdk 1.0.3 → 1.1.1

package/dist/types/ottochain/metagraph-client.d.ts

@@ -16,6 +16,45 @@ export interface Checkpoint {
     ordinal: number;
     state: CalculatedState;
 }
+/**
+ * Options for subscribeFiberState polling behaviour.
+ */
+export interface SubscribeOptions {
+    /**
+     * Polling interval in milliseconds.
+     * @default 2000
+     */
+    pollIntervalMs?: number;
+    /**
+     * Called when a poll fails (network error, timeout, etc.) or when the
+     * user-supplied callback throws. The subscription continues after an error.
+     * @default (e) => console.warn('[subscribeFiberState]', e)
+     */
+    onError?: (error: Error) => void;
+    /**
+     * If true, fire the callback immediately after the very first poll even
+     * when no previous state exists (current vs. null).
+     * Set false to suppress the initial callback and only fire on changes.
+     *
+     * **Edge case:** When `fireImmediately` is false and the fiber never exists
+     * (getStateMachine always returns null), the callback will never fire because
+     * the sequence number stays null between polls (no change detected).
+     * @default true
+     */
+    fireImmediately?: boolean;
+}
+/**
+ * Callback invoked when fiber state is first observed or changes.
+ *
+ * @param current  - Current fiber state, or null if fiber not found
+ * @param previous - Previous fiber state, or null on first callback
+ */
+export type FiberStateCallback = (current: StateMachineFiberRecord | null, previous: StateMachineFiberRecord | null) => void;
+/**
+ * Unsubscribe function returned by subscribeFiberState.
+ * Stops polling immediately and prevents any further callbacks. Idempotent.
+ */
+export type Unsubscribe = () => void;
 /**
  * Configuration for the MetagraphClient.
  */
@@ -98,6 +137,57 @@ export declare class MetagraphClient {
      * Get the latest snapshot ordinal.
      */
     getLatestOrdinal(): Promise<number>;
+    /**
+     * 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: string, callback: FiberStateCallback, options?: SubscribeOptions): Unsubscribe;
+    /**
+     * 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: string, targetState: string, timeoutMs?: number, options?: Pick<SubscribeOptions, 'pollIntervalMs' | 'onError'>): Promise<StateMachineFiberRecord | null>;
     /**
      * Submit a signed data update to the DL1 node.
      * The POST /data endpoint is framework-provided (no /v1 prefix).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ottochain/sdk",
-  "version": "1.0.3",
+  "version": "1.1.1",
   "description": "TypeScript SDK for ottochain metagraph operations - signing, encoding, and network interactions",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -55,6 +55,11 @@
       "import": "./dist/esm/apps/index.js",
       "require": "./dist/cjs/apps/index.js",
       "types": "./dist/types/apps/index.d.ts"
+    },
+    "./generated": {
+      "import": "./dist/esm/generated/index.js",
+      "require": "./dist/cjs/generated/index.js",
+      "types": "./dist/types/generated/index.d.ts"
     }
   },
   "files": [
@@ -107,21 +112,16 @@
     "zod": "^3.22.0"
   },
   "devDependencies": {
-    "@bufbuild/buf": "^1.65.0",
-    "@bufbuild/protoc-gen-es": "^2.11.0",
-    "@protobuf-ts/plugin": "^2.11.1",
-    "@protobuf-ts/runtime": "^2.11.1",
-    "@types/jest": "^29.5.0",
+    "@types/jest": "^30.0.0",
     "@types/node": "^20.0.0",
-    "@typescript-eslint/eslint-plugin": "^7.0.0",
-    "@typescript-eslint/parser": "^7.0.0",
-    "eslint": "^8.0.0",
-    "grpc-tools": "^1.13.1",
-    "jest": "^29.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.56.1",
+    "@typescript-eslint/parser": "^8.56.1",
+    "eslint": "^9.39.3",
+    "jest": "^30.2.0",
     "prettier": "^3.0.0",
     "ts-jest": "^29.0.0",
     "ts-proto": "^2.11.2",
-    "typedoc": "^0.25.0",
+    "typedoc": "^0.28.17",
     "typescript": "^5.0.0"
   },
   "peerDependencies": {

package/dist/apps/contracts/index.d.ts

@@ -1,21 +0,0 @@
-/**
- * Contracts Application
- *
- * Types and utilities for the Contract system on OttoChain.
- *
- * @example
- * ```typescript
- * import { ContractState, ContractSchema } from '@ottochain/sdk/apps/contracts';
- * import { create } from '@bufbuild/protobuf';
- *
- * const contract = create(ContractSchema, {
- *   id: 'fiber-123',
- *   contractId: 'contract-001',
- *   state: ContractState.PROPOSED,
- * });
- * ```
- *
- * @packageDocumentation
- */
-export * from '../../generated/ottochain/apps/contracts/v1/contract_pb.js';
-export * from './types.js';

package/dist/apps/contracts/index.js

@@ -1,39 +0,0 @@
-"use strict";
-/**
- * Contracts Application
- *
- * Types and utilities for the Contract system on OttoChain.
- *
- * @example
- * ```typescript
- * import { ContractState, ContractSchema } from '@ottochain/sdk/apps/contracts';
- * import { create } from '@bufbuild/protobuf';
- *
- * const contract = create(ContractSchema, {
- *   id: 'fiber-123',
- *   contractId: 'contract-001',
- *   state: ContractState.PROPOSED,
- * });
- * ```
- *
- * @packageDocumentation
- */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-// Re-export generated protobuf types
-__exportStar(require("../../generated/ottochain/apps/contracts/v1/contract_pb.js"), exports);
-// Re-export convenience types and constants
-__exportStar(require("./types.js"), exports);

package/dist/apps/contracts/types.d.ts

@@ -1,24 +0,0 @@
-/**
- * Contract Utilities
- *
- * Constants and utilities for the Contract application.
- * Core types are generated from protobuf - see the generated exports.
- *
- * @packageDocumentation
- */
-import { ContractState } from '../../generated/ottochain/apps/contracts/v1/contract_pb.js';
-/**
- * Default contract configuration
- */
-export declare const DEFAULT_CONTRACT_CONFIG: {
-    readonly requireBothSignatures: false;
-    readonly disputeWindowEpochs: 10;
-};
-/**
- * Valid transitions for each contract state
- */
-export declare const CONTRACT_TRANSITIONS: Record<ContractState, readonly string[]>;
-/**
- * Check if a contract state is terminal (no further transitions allowed)
- */
-export declare function isTerminalState(state: ContractState): boolean;

package/dist/apps/contracts/types.js

@@ -1,48 +0,0 @@
-"use strict";
-/**
- * Contract Utilities
- *
- * Constants and utilities for the Contract application.
- * Core types are generated from protobuf - see the generated exports.
- *
- * @packageDocumentation
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.isTerminalState = exports.CONTRACT_TRANSITIONS = exports.DEFAULT_CONTRACT_CONFIG = void 0;
-const contract_pb_js_1 = require("../../generated/ottochain/apps/contracts/v1/contract_pb.js");
-// ---------------------------------------------------------------------------
-// Configuration Defaults
-// ---------------------------------------------------------------------------
-/**
- * Default contract configuration
- */
-exports.DEFAULT_CONTRACT_CONFIG = {
-    requireBothSignatures: false,
-    disputeWindowEpochs: 10,
-};
-// ---------------------------------------------------------------------------
-// State Machine Transitions
-// ---------------------------------------------------------------------------
-/**
- * Valid transitions for each contract state
- */
-exports.CONTRACT_TRANSITIONS = {
-    [contract_pb_js_1.ContractState.UNSPECIFIED]: [],
-    [contract_pb_js_1.ContractState.PROPOSED]: ['accept', 'reject', 'cancel'],
-    [contract_pb_js_1.ContractState.ACTIVE]: ['complete', 'dispute'],
-    [contract_pb_js_1.ContractState.DISPUTED]: ['resolve_for_completer', 'resolve_for_disputant'],
-    [contract_pb_js_1.ContractState.COMPLETED]: [], // Terminal state
-    [contract_pb_js_1.ContractState.REJECTED]: [], // Terminal state
-    [contract_pb_js_1.ContractState.CANCELLED]: [], // Terminal state
-};
-/**
- * Check if a contract state is terminal (no further transitions allowed)
- */
-function isTerminalState(state) {
-    return [
-        contract_pb_js_1.ContractState.COMPLETED,
-        contract_pb_js_1.ContractState.REJECTED,
-        contract_pb_js_1.ContractState.CANCELLED,
-    ].includes(state);
-}
-exports.isTerminalState = isTerminalState;

package/dist/apps/identity/index.d.ts

@@ -1,22 +0,0 @@
-/**
- * Agent Identity Application
- *
- * Types and utilities for the Agent Identity system on OttoChain.
- *
- * @example
- * ```typescript
- * import { AgentState, AttestationType, AgentIdentitySchema } from '@ottochain/sdk/apps/identity';
- * import { create } from '@bufbuild/protobuf';
- *
- * const agent = create(AgentIdentitySchema, {
- *   publicKey: '...',
- *   reputation: 10,
- *   state: AgentState.REGISTERED,
- * });
- * ```
- *
- * @packageDocumentation
- */
-export * from '../../generated/ottochain/apps/identity/v1/agent_pb.js';
-export * from '../../generated/ottochain/apps/identity/v1/attestation_pb.js';
-export * from './types.js';

package/dist/apps/identity/index.js

@@ -1,40 +0,0 @@
-"use strict";
-/**
- * Agent Identity Application
- *
- * Types and utilities for the Agent Identity system on OttoChain.
- *
- * @example
- * ```typescript
- * import { AgentState, AttestationType, AgentIdentitySchema } from '@ottochain/sdk/apps/identity';
- * import { create } from '@bufbuild/protobuf';
- *
- * const agent = create(AgentIdentitySchema, {
- *   publicKey: '...',
- *   reputation: 10,
- *   state: AgentState.REGISTERED,
- * });
- * ```
- *
- * @packageDocumentation
- */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-// Re-export generated protobuf types
-__exportStar(require("../../generated/ottochain/apps/identity/v1/agent_pb.js"), exports);
-__exportStar(require("../../generated/ottochain/apps/identity/v1/attestation_pb.js"), exports);
-// Re-export convenience types and constants
-__exportStar(require("./types.js"), exports);

package/dist/apps/identity/types.d.ts

@@ -1,30 +0,0 @@
-/**
- * Agent Identity Utilities
- *
- * Constants and utilities for the Agent Identity application.
- * Core types are generated from protobuf - see the generated exports.
- *
- * @packageDocumentation
- */
-import { AgentState } from '../../generated/ottochain/apps/identity/v1/agent_pb.js';
-import { AttestationType } from '../../generated/ottochain/apps/identity/v1/attestation_pb.js';
-/**
- * Default reputation configuration for agent identity
- */
-export declare const DEFAULT_REPUTATION_CONFIG: {
-    readonly baseReputation: 10;
-    readonly completionDelta: 5;
-    readonly vouchDelta: 2;
-    readonly violationDelta: -10;
-    readonly behavioralDelta: 3;
-    readonly minReputation: 0;
-    readonly challengeThreshold: 5;
-};
-/**
- * Valid transitions for each agent state
- */
-export declare const AGENT_TRANSITIONS: Record<AgentState, readonly string[]>;
-/**
- * Reputation delta by attestation type
- */
-export declare const ATTESTATION_DELTAS: Record<AttestationType, number>;

package/dist/apps/identity/types.js

@@ -1,53 +0,0 @@
-"use strict";
-/**
- * Agent Identity Utilities
- *
- * Constants and utilities for the Agent Identity application.
- * Core types are generated from protobuf - see the generated exports.
- *
- * @packageDocumentation
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ATTESTATION_DELTAS = exports.AGENT_TRANSITIONS = exports.DEFAULT_REPUTATION_CONFIG = void 0;
-const agent_pb_js_1 = require("../../generated/ottochain/apps/identity/v1/agent_pb.js");
-const attestation_pb_js_1 = require("../../generated/ottochain/apps/identity/v1/attestation_pb.js");
-// ---------------------------------------------------------------------------
-// Configuration Defaults
-// ---------------------------------------------------------------------------
-/**
- * Default reputation configuration for agent identity
- */
-exports.DEFAULT_REPUTATION_CONFIG = {
-    baseReputation: 10,
-    completionDelta: 5,
-    vouchDelta: 2,
-    violationDelta: -10,
-    behavioralDelta: 3,
-    minReputation: 0,
-    challengeThreshold: 5,
-};
-// ---------------------------------------------------------------------------
-// State Machine Transitions
-// ---------------------------------------------------------------------------
-/**
- * Valid transitions for each agent state
- */
-exports.AGENT_TRANSITIONS = {
-    [agent_pb_js_1.AgentState.UNSPECIFIED]: [],
-    [agent_pb_js_1.AgentState.REGISTERED]: ['activate', 'withdraw'],
-    [agent_pb_js_1.AgentState.ACTIVE]: ['challenge', 'withdraw'],
-    [agent_pb_js_1.AgentState.CHALLENGED]: ['uphold_challenge', 'dismiss_challenge'],
-    [agent_pb_js_1.AgentState.SUSPENDED]: ['begin_probation'],
-    [agent_pb_js_1.AgentState.PROBATION]: ['complete_probation'],
-    [agent_pb_js_1.AgentState.WITHDRAWN]: [], // Terminal state
-};
-/**
- * Reputation delta by attestation type
- */
-exports.ATTESTATION_DELTAS = {
-    [attestation_pb_js_1.AttestationType.UNSPECIFIED]: 0,
-    [attestation_pb_js_1.AttestationType.COMPLETION]: 5,
-    [attestation_pb_js_1.AttestationType.VOUCH]: 2,
-    [attestation_pb_js_1.AttestationType.VIOLATION]: -10,
-    [attestation_pb_js_1.AttestationType.BEHAVIORAL]: 3,
-};

package/dist/apps/index.d.ts

@@ -1,29 +0,0 @@
-/**
- * OttoChain Applications
- *
- * Application-specific types and utilities for OttoChain SDK.
- *
- * @example
- * ```typescript
- * import { identity, contracts, markets, oracles } from '@ottochain/sdk/apps';
- *
- * // Use identity types
- * const { AgentState, AGENT_TRANSITIONS } = identity;
- *
- * // Use market calculations
- * const payout = markets.calculatePayout(shares);
- *
- * // Check oracle reputation
- * const newRep = oracles.calculateReputation(current, delta);
- * ```
- *
- * @packageDocumentation
- */
-export * as identity from './identity/index.js';
-export * as contracts from './contracts/index.js';
-export * as markets from './markets/index.js';
-export * as oracles from './oracles/index.js';
-export * from './identity/index.js';
-export * from './contracts/index.js';
-export * from './markets/index.js';
-export * from './oracles/index.js';

package/dist/apps/index.js

@@ -1,60 +0,0 @@
-"use strict";
-/**
- * OttoChain Applications
- *
- * Application-specific types and utilities for OttoChain SDK.
- *
- * @example
- * ```typescript
- * import { identity, contracts, markets, oracles } from '@ottochain/sdk/apps';
- *
- * // Use identity types
- * const { AgentState, AGENT_TRANSITIONS } = identity;
- *
- * // Use market calculations
- * const payout = markets.calculatePayout(shares);
- *
- * // Check oracle reputation
- * const newRep = oracles.calculateReputation(current, delta);
- * ```
- *
- * @packageDocumentation
- */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.oracles = exports.markets = exports.contracts = exports.identity = void 0;
-// Re-export as namespaces for organized access
-exports.identity = __importStar(require("./identity/index.js"));
-exports.contracts = __importStar(require("./contracts/index.js"));
-exports.markets = __importStar(require("./markets/index.js"));
-exports.oracles = __importStar(require("./oracles/index.js"));
-// Also allow direct imports
-__exportStar(require("./identity/index.js"), exports);
-__exportStar(require("./contracts/index.js"), exports);
-__exportStar(require("./markets/index.js"), exports);
-__exportStar(require("./oracles/index.js"), exports);

package/dist/apps/markets/index.d.ts

@@ -1,26 +0,0 @@
-/**
- * Markets Application
- *
- * Types and utilities for the Markets system on OttoChain.
- * Supports prediction markets, auctions, crowdfunding, and group buys.
- *
- * @example
- * ```typescript
- * import {
- *   MarketState,
- *   MarketType,
- *   calculatePayout,
- *   DEFAULT_MARKET_CONFIG
- * } from '@ottochain/sdk/apps/markets';
- *
- * // Calculate payout for a winning prediction
- * const payout = calculatePayout({
- *   winningPool: 1000n,
- *   losingPool: 500n,
- *   userCommitment: 100n,
- * });
- * ```
- *
- * @packageDocumentation
- */
-export * from './types.js';

package/dist/apps/markets/index.js

@@ -1,46 +0,0 @@
-"use strict";
-/**
- * Markets Application
- *
- * Types and utilities for the Markets system on OttoChain.
- * Supports prediction markets, auctions, crowdfunding, and group buys.
- *
- * @example
- * ```typescript
- * import {
- *   MarketState,
- *   MarketType,
- *   calculatePayout,
- *   DEFAULT_MARKET_CONFIG
- * } from '@ottochain/sdk/apps/markets';
- *
- * // Calculate payout for a winning prediction
- * const payout = calculatePayout({
- *   winningPool: 1000n,
- *   losingPool: 500n,
- *   userCommitment: 100n,
- * });
- * ```
- *
- * @packageDocumentation
- */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-// Note: Once proto files are generated, uncomment these exports:
-// export * from '../../generated/ottochain/apps/markets/v1/market_pb.js';
-// export * from '../../generated/ottochain/apps/markets/v1/commitment_pb.js';
-// Export convenience types, constants, and helpers
-__exportStar(require("./types.js"), exports);