@ottochain/sdk 0.2.0

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

@@ -0,0 +1,111 @@
+/**
+ * Ottochain Metagraph Client
+ *
+ * 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/data_l1/src/main/scala/xyz/kd5ujc/data_l1/DataL1CustomRoutes.scala
+ * @packageDocumentation
+ */
+import type { OnChain, CalculatedState, StateMachineFiberRecord, ScriptFiberRecord, EventReceipt, OracleInvocation, FiberStatus } from './types.js';
+/**
+ * Checkpoint response from the metagraph (ordinal + calculated state).
+ */
+export interface Checkpoint {
+    ordinal: number;
+    state: CalculatedState;
+}
+/**
+ * Configuration for the MetagraphClient.
+ */
+export interface MetagraphClientConfig {
+    /** ML0 node base URL (e.g., 'http://localhost:9200') */
+    ml0Url: string;
+    /** DL1 node base URL for data submission (e.g., 'http://localhost:9400') */
+    dl1Url?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+}
+/**
+ * Client for ottochain metagraph operations.
+ *
+ * Provides typed access to all ML0 custom routes (under /data-application/v1/)
+ * and framework snapshot endpoints.
+ *
+ * @example
+ * ```typescript
+ * const client = new MetagraphClient({
+ *   ml0Url: 'http://localhost:9200',
+ *   dl1Url: 'http://localhost:9400',
+ * });
+ *
+ * // Query on-chain state
+ * const onChain = await client.getOnChain();
+ *
+ * // Get all active state machines
+ * const machines = await client.getStateMachines('Active');
+ *
+ * // Get event receipts for a fiber
+ * const events = await client.getStateMachineEvents(fiberId);
+ * ```
+ */
+export declare class MetagraphClient {
+    private ml0;
+    private dl1?;
+    constructor(config: MetagraphClientConfig);
+    /**
+     * Get the current on-chain state (directly from L0 context).
+     */
+    getOnChain(): Promise<OnChain>;
+    /**
+     * Get the latest checkpoint (ordinal + calculated state).
+     */
+    getCheckpoint(): Promise<Checkpoint>;
+    /**
+     * Get all state machines, optionally filtered by status.
+     */
+    getStateMachines(status?: FiberStatus): Promise<Record<string, StateMachineFiberRecord>>;
+    /**
+     * Get a single state machine by fiber ID.
+     */
+    getStateMachine(fiberId: string): Promise<StateMachineFiberRecord | null>;
+    /**
+     * Get event receipts for a state machine from the current ordinal's logs.
+     */
+    getStateMachineEvents(fiberId: string): Promise<EventReceipt[]>;
+    /**
+     * Get all script oracles, optionally filtered by status.
+     */
+    getScripts(status?: FiberStatus): Promise<Record<string, ScriptFiberRecord>>;
+    /**
+     * Get a single script oracle by fiber ID.
+     */
+    getScript(scriptId: string): Promise<ScriptFiberRecord | null>;
+    /**
+     * Get oracle invocations from the current ordinal's logs.
+     */
+    getScriptInvocations(scriptId: string): Promise<OracleInvocation[]>;
+    /**
+     * Get the latest snapshot and decode its on-chain state.
+     */
+    getLatestSnapshotOnChainState(): Promise<OnChain | null>;
+    /**
+     * Get a snapshot by ordinal and decode its on-chain state.
+     */
+    getSnapshotOnChainState(ordinal: number): Promise<OnChain | null>;
+    /**
+     * Get the latest snapshot ordinal.
+     */
+    getLatestOrdinal(): Promise<number>;
+    /**
+     * Submit a signed data update to the DL1 node.
+     * The POST /data endpoint is framework-provided (no /v1 prefix).
+     *
+     * @param signedData - Signed OttochainMessage
+     * @returns Response hash
+     */
+    postData<T>(signedData: T): Promise<{
+        hash: string;
+    }>;
+}

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

@@ -0,0 +1,86 @@
+/**
+ * Snapshot decoder for ottochain on-chain state
+ *
+ * Fetches currency incremental snapshots from metagraph L0 and decodes the
+ * on-chain state from the DataApplicationPart's binary payload.
+ *
+ * The on-chain state is serialized using JsonBinaryCodec (canonical JSON → UTF-8 bytes).
+ *
+ * @see modules/models/src/main/scala/xyz/kd5ujc/schema/OnChain.scala
+ * @packageDocumentation
+ */
+import type { OnChain, EventReceipt, OracleInvocation, FiberLogEntry } from './types.js';
+/**
+ * Decode on-chain state from binary (JsonBinaryCodec format).
+ *
+ * JsonBinaryCodec serialization is: canonical JSON → UTF-8 bytes.
+ * So decoding is simply: UTF-8 bytes → JSON.parse.
+ *
+ * @param bytes - UTF-8 encoded canonical JSON bytes
+ * @returns Decoded OnChain state
+ */
+export declare function decodeOnChainState(bytes: Uint8Array): OnChain;
+/**
+ * Snapshot response shape from GET /snapshots/{ordinal} or /snapshots/latest
+ * on the metagraph L0 node (port 9200 by default).
+ */
+export interface CurrencySnapshotResponse {
+    value: {
+        ordinal: number;
+        dataApplication?: {
+            onChainState: number[];
+            blocks: unknown[];
+        };
+        [key: string]: unknown;
+    };
+    proofs: unknown[];
+}
+/**
+ * Fetch and decode the on-chain state from a specific snapshot ordinal.
+ *
+ * @param ml0BaseUrl - Metagraph L0 node base URL (e.g., 'http://localhost:9200')
+ * @param ordinal - Snapshot ordinal number
+ * @returns Decoded OnChain state, or null if no data application part
+ */
+export declare function getSnapshotOnChainState(ml0BaseUrl: string, ordinal: number): Promise<OnChain | null>;
+/**
+ * Fetch and decode the on-chain state from the latest snapshot.
+ *
+ * @param ml0BaseUrl - Metagraph L0 node base URL (e.g., 'http://localhost:9200')
+ * @returns Decoded OnChain state, or null if no data application part
+ */
+export declare function getLatestOnChainState(ml0BaseUrl: string): Promise<OnChain | null>;
+/**
+ * Extract and decode on-chain state from a snapshot response.
+ */
+export declare function extractOnChainState(snapshot: CurrencySnapshotResponse): OnChain | null;
+/**
+ * Get all log entries for a specific fiber from on-chain state.
+ *
+ * @param onChain - Decoded on-chain state
+ * @param fiberId - Fiber UUID to filter by
+ * @returns Array of log entries for the fiber, or empty array
+ */
+export declare function getLogsForFiber(onChain: OnChain, fiberId: string): FiberLogEntry[];
+/**
+ * Get EventReceipt log entries for a specific fiber.
+ *
+ * EventReceipts are distinguished from OracleInvocations by the presence
+ * of the `eventName` field.
+ *
+ * @param onChain - Decoded on-chain state
+ * @param fiberId - Fiber UUID to filter by
+ * @returns Array of EventReceipt entries
+ */
+export declare function getEventReceipts(onChain: OnChain, fiberId: string): EventReceipt[];
+/**
+ * Get OracleInvocation log entries for a specific fiber.
+ *
+ * OracleInvocations 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
+ */
+export declare function getScriptInvocations(onChain: OnChain, fiberId: string): OracleInvocation[];

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

@@ -0,0 +1,210 @@
+/**
+ * Ottochain-specific type definitions
+ *
+ * TypeScript interfaces matching the wire format from the Scala metagraph.
+ * The JSON Logic engine stores state as plain JSON - no wrapper objects.
+ *
+ * @see modules/models/src/main/scala/xyz/kd5ujc/schema/
+ * @packageDocumentation
+ */
+export type { Address, FiberId, StateId, HashValue, FiberOrdinal, SnapshotOrdinal, Timestamp, } from '../types.js';
+/**
+ * JSON logic value - arbitrary JSON data used for state data and payloads.
+ */
+export type JsonLogicValue = unknown;
+/**
+ * JSON logic expression - a JsonLogic program definition.
+ */
+export type JsonLogicExpression = unknown;
+/**
+ * Lifecycle status of a fiber.
+ * Wire format: plain string.
+ */
+export type FiberStatus = 'Active' | 'Archived' | 'Failed';
+/**
+ * Access control policy for script oracles.
+ * Wire format: discriminated union with type key.
+ */
+export type AccessControlPolicy = {
+    Public: Record<string, never>;
+} | {
+    Whitelist: {
+        addresses: string[];
+    };
+} | {
+    FiberOwned: {
+        fiberId: string;
+    };
+};
+/**
+ * Definition of a state machine's structure and transitions.
+ * Wire format: plain JSON object with string initialState.
+ */
+export interface StateMachineDefinition {
+    states: Record<string, unknown>;
+    initialState: string;
+    transitions: unknown[];
+    metadata?: JsonLogicValue;
+}
+/**
+ * Event emitted by a state machine transition trigger.
+ */
+export interface EmittedEvent {
+    name: string;
+    data: JsonLogicValue;
+    destination?: string;
+}
+/**
+ * Receipt of a state machine event processing.
+ * Wire format: all ordinals/states are plain primitives.
+ */
+export interface EventReceipt {
+    fiberId: string;
+    sequenceNumber: number;
+    eventName: string;
+    ordinal: number;
+    fromState: string;
+    toState: string;
+    success: boolean;
+    gasUsed: number;
+    triggersFired: number;
+    errorMessage?: string;
+    sourceFiberId?: string;
+    emittedEvents: EmittedEvent[];
+}
+/**
+ * Log entry for a script oracle invocation.
+ */
+export interface OracleInvocation {
+    fiberId: string;
+    method: string;
+    args: JsonLogicValue;
+    result: JsonLogicValue;
+    gasUsed: number;
+    invokedAt: number;
+    invokedBy: string;
+}
+/**
+ * Union type for all fiber log entries.
+ */
+export type FiberLogEntry = EventReceipt | OracleInvocation;
+/**
+ * On-chain record for a state machine fiber.
+ * Wire format: all ordinals/states/hashes are plain primitives.
+ */
+export interface StateMachineFiberRecord {
+    fiberId: string;
+    creationOrdinal: number;
+    previousUpdateOrdinal: number;
+    latestUpdateOrdinal: number;
+    definition: StateMachineDefinition;
+    currentState: string;
+    stateData: JsonLogicValue;
+    stateDataHash: string;
+    sequenceNumber: number;
+    owners: string[];
+    status: FiberStatus;
+    lastReceipt?: EventReceipt;
+    parentFiberId?: string;
+    childFiberIds: string[];
+}
+/**
+ * On-chain record for a script oracle fiber.
+ */
+export interface ScriptFiberRecord {
+    fiberId: string;
+    creationOrdinal: number;
+    latestUpdateOrdinal: number;
+    scriptProgram: JsonLogicExpression;
+    stateData?: JsonLogicValue;
+    stateDataHash?: string;
+    accessControl: AccessControlPolicy;
+    sequenceNumber: number;
+    owners: string[];
+    status: FiberStatus;
+    lastInvocation?: OracleInvocation;
+}
+/**
+ * Union type for all fiber records.
+ */
+export type FiberRecord = StateMachineFiberRecord | ScriptFiberRecord;
+/**
+ * Commit hash for a single fiber in the on-chain state.
+ */
+export interface FiberCommit {
+    recordHash: string;
+    stateDataHash?: string;
+    sequenceNumber: number;
+}
+/**
+ * Full on-chain state of the ottochain metagraph.
+ */
+export interface OnChain {
+    fiberCommits: Record<string, FiberCommit>;
+    latestLogs: Record<string, FiberLogEntry[]>;
+}
+/**
+ * Full calculated state (served by ML0 /v1/ endpoints).
+ */
+export interface CalculatedState {
+    stateMachines: Record<string, StateMachineFiberRecord>;
+    scripts: Record<string, ScriptFiberRecord>;
+}
+/**
+ * Create a new state machine fiber.
+ */
+export interface CreateStateMachine {
+    fiberId: string;
+    definition: StateMachineDefinition;
+    initialData: JsonLogicValue;
+    parentFiberId?: string;
+}
+/**
+ * Trigger a state machine transition.
+ */
+export interface TransitionStateMachine {
+    fiberId: string;
+    eventName: string;
+    payload: JsonLogicValue;
+    targetSequenceNumber: number;
+}
+/**
+ * Archive a state machine fiber.
+ */
+export interface ArchiveStateMachine {
+    fiberId: string;
+    targetSequenceNumber: number;
+}
+/**
+ * Create a new script oracle fiber.
+ */
+export interface CreateScript {
+    fiberId: string;
+    scriptProgram: JsonLogicExpression;
+    initialState?: JsonLogicValue;
+    accessControl: AccessControlPolicy;
+}
+/**
+ * Invoke a script oracle.
+ */
+export interface InvokeScript {
+    fiberId: string;
+    method: string;
+    args: JsonLogicValue;
+    targetSequenceNumber: number;
+}
+/**
+ * Union type for all ottochain messages.
+ * JSON is wrapped as `{ MessageName: { ...fields } }`.
+ */
+export type OttochainMessage = {
+    CreateStateMachine: CreateStateMachine;
+} | {
+    TransitionStateMachine: TransitionStateMachine;
+} | {
+    ArchiveStateMachine: ArchiveStateMachine;
+} | {
+    CreateScript: CreateScript;
+} | {
+    InvokeScript: InvokeScript;
+};

package/dist/types/types.d.ts

@@ -0,0 +1,51 @@
+/**
+ * OttoChain Type Aliases
+ *
+ * Semantic type aliases for common primitive types.
+ * These match the wire format used by the metagraph's JSON Logic engine.
+ *
+ * @packageDocumentation
+ */
+/**
+ * DAG address (Constellation network address).
+ * Format: DAG followed by alphanumeric characters.
+ * @example "DAG4o8VX63jPFLQ6pZ5XE7qT8vGp8gkgBHj1QL5c"
+ */
+export type Address = string;
+/**
+ * Fiber UUID identifier.
+ * @example "550e8400-e29b-41d4-a716-446655440000"
+ */
+export type FiberId = string;
+/**
+ * State machine state identifier.
+ * @example "ACTIVE", "PENDING", "REGISTERED"
+ */
+export type StateId = string;
+/**
+ * Hex-encoded hash value.
+ * @example "a1b2c3d4e5f6..."
+ */
+export type HashValue = string;
+/**
+ * Fiber sequence number (non-negative integer).
+ * Increments with each state update.
+ */
+export type FiberOrdinal = number;
+/**
+ * Constellation snapshot ordinal (non-negative integer).
+ * Global ordering of snapshots on the DAG network.
+ */
+export type SnapshotOrdinal = number;
+/**
+ * Unix timestamp in milliseconds.
+ */
+export type Timestamp = number;
+/**
+ * Validate a DAG address format.
+ */
+export declare function isValidAddress(value: string): value is Address;
+/**
+ * Validate a UUID format.
+ */
+export declare function isValidFiberId(value: string): value is FiberId;