@ottochain/sdk 0.2.0

package/dist/esm/metakit/wallet.js

@@ -0,0 +1,117 @@
+/**
+ * Wallet and Key Management Utilities
+ *
+ * Functions for generating and managing cryptographic keys.
+ */
+import { dag4 } from '@stardust-collective/dag4';
+/**
+ * Generate a new random key pair
+ *
+ * @returns KeyPair with private key, public key, and DAG address
+ *
+ * @example
+ * ```typescript
+ * const keyPair = generateKeyPair();
+ * console.log(keyPair.address);    // DAG address
+ * console.log(keyPair.privateKey); // 64 char hex
+ * console.log(keyPair.publicKey);  // 130 char hex (with 04 prefix)
+ * ```
+ */
+export function generateKeyPair() {
+    const privateKey = dag4.keyStore.generatePrivateKey();
+    return keyPairFromPrivateKey(privateKey);
+}
+/**
+ * Derive a key pair from an existing private key
+ *
+ * @param privateKey - Private key in hex format (64 characters)
+ * @returns KeyPair with private key, public key, and DAG address
+ *
+ * @example
+ * ```typescript
+ * const keyPair = keyPairFromPrivateKey(existingPrivateKey);
+ * ```
+ */
+export function keyPairFromPrivateKey(privateKey) {
+    // Get uncompressed public key (with 04 prefix)
+    const publicKey = dag4.keyStore.getPublicKeyFromPrivate(privateKey, false);
+    // Derive DAG address
+    const address = dag4.keyStore.getDagAddressFromPublicKey(publicKey);
+    return {
+        privateKey,
+        publicKey: normalizePublicKey(publicKey),
+        address,
+    };
+}
+/**
+ * Get the public key hex from a private key
+ *
+ * @param privateKey - Private key in hex format
+ * @param compressed - If true, returns compressed public key (33 bytes)
+ * @returns Public key in hex format
+ */
+export function getPublicKeyHex(privateKey, compressed = false) {
+    return dag4.keyStore.getPublicKeyFromPrivate(privateKey, compressed);
+}
+/**
+ * Get the public key ID (without 04 prefix) from a private key
+ *
+ * This format is used in SignatureProof.id
+ *
+ * @param privateKey - Private key in hex format
+ * @returns Public key ID (128 characters, no 04 prefix)
+ */
+export function getPublicKeyId(privateKey) {
+    const publicKey = dag4.keyStore.getPublicKeyFromPrivate(privateKey, false);
+    // Remove 04 prefix if present
+    if (publicKey.length === 130 && publicKey.startsWith('04')) {
+        return publicKey.substring(2);
+    }
+    return publicKey;
+}
+/**
+ * Get DAG address from a public key
+ *
+ * @param publicKey - Public key in hex format (with or without 04 prefix)
+ * @returns DAG address string
+ */
+export function getAddress(publicKey) {
+    const normalizedKey = normalizePublicKey(publicKey);
+    return dag4.keyStore.getDagAddressFromPublicKey(normalizedKey);
+}
+/**
+ * Validate that a private key is correctly formatted
+ *
+ * @param privateKey - Private key to validate
+ * @returns true if valid hex string of correct length
+ */
+export function isValidPrivateKey(privateKey) {
+    if (typeof privateKey !== 'string')
+        return false;
+    if (privateKey.length !== 64)
+        return false;
+    return /^[0-9a-fA-F]+$/.test(privateKey);
+}
+/**
+ * Validate that a public key is correctly formatted
+ *
+ * @param publicKey - Public key to validate
+ * @returns true if valid hex string of correct length
+ */
+export function isValidPublicKey(publicKey) {
+    if (typeof publicKey !== 'string')
+        return false;
+    // With 04 prefix: 130 chars, without: 128 chars
+    if (publicKey.length !== 128 && publicKey.length !== 130)
+        return false;
+    return /^[0-9a-fA-F]+$/.test(publicKey);
+}
+/**
+ * Normalize public key to include 04 prefix
+ */
+function normalizePublicKey(publicKey) {
+    if (publicKey.length === 128) {
+        return '04' + publicKey;
+    }
+    return publicKey;
+}

package/dist/esm/ottochain/index.js

@@ -0,0 +1,13 @@
+/**
+ * Ottochain SDK
+ *
+ * Domain-specific types and clients for the ottochain metagraph.
+ *
+ * @packageDocumentation
+ */
+// Re-export generated protobuf types (for binary encoding)
+export * as proto from '../generated/index.js';
+export { decodeOnChainState, getSnapshotOnChainState, getLatestOnChainState, getLogsForFiber, getEventReceipts, getScriptInvocations, extractOnChainState, } from './snapshot.js';
+export { MetagraphClient } from './metagraph-client.js';
+// Note: Governance and Corporate types are now in src/apps/
+// Import from '@ottochain/sdk/apps' instead

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

@@ -0,0 +1,153 @@
+/**
+ * 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 { HttpClient } from '../metakit/network/client.js';
+import { NetworkError } from '../metakit/network/types.js';
+import { extractOnChainState } from './snapshot.js';
+/**
+ * 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 class MetagraphClient {
+    constructor(config) {
+        this.ml0 = new HttpClient(config.ml0Url, config.timeout);
+        if (config.dl1Url) {
+            this.dl1 = new HttpClient(config.dl1Url, config.timeout);
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Custom routes (ML0 /data-application/v1/*)
+    // -------------------------------------------------------------------------
+    /**
+     * Get the current on-chain state (directly from L0 context).
+     */
+    async getOnChain() {
+        return this.ml0.get('/data-application/v1/onchain');
+    }
+    /**
+     * Get the latest checkpoint (ordinal + calculated state).
+     */
+    async getCheckpoint() {
+        return this.ml0.get('/data-application/v1/checkpoint');
+    }
+    /**
+     * Get all state machines, optionally filtered by status.
+     */
+    async getStateMachines(status) {
+        const query = status ? `?status=${status}` : '';
+        return this.ml0.get(`/data-application/v1/state-machines${query}`);
+    }
+    /**
+     * Get a single state machine by fiber ID.
+     */
+    async getStateMachine(fiberId) {
+        try {
+            return await this.ml0.get(`/data-application/v1/state-machines/${fiberId}`);
+        }
+        catch (error) {
+            if (error instanceof NetworkError && error.statusCode === 404) {
+                return null;
+            }
+            throw error;
+        }
+    }
+    /**
+     * Get event receipts for a state machine from the current ordinal's logs.
+     */
+    async getStateMachineEvents(fiberId) {
+        return this.ml0.get(`/data-application/v1/state-machines/${fiberId}/events`);
+    }
+    /**
+     * Get all script oracles, optionally filtered by status.
+     */
+    async getScripts(status) {
+        const query = status ? `?status=${status}` : '';
+        return this.ml0.get(`/data-application/v1/oracles${query}`);
+    }
+    /**
+     * Get a single script oracle by fiber ID.
+     */
+    async getScript(scriptId) {
+        try {
+            return await this.ml0.get(`/data-application/v1/oracles/${scriptId}`);
+        }
+        catch (error) {
+            if (error instanceof NetworkError && error.statusCode === 404) {
+                return null;
+            }
+            throw error;
+        }
+    }
+    /**
+     * Get oracle invocations from the current ordinal's logs.
+     */
+    async getScriptInvocations(scriptId) {
+        return this.ml0.get(`/data-application/v1/oracles/${scriptId}/invocations`);
+    }
+    // -------------------------------------------------------------------------
+    // Framework snapshot endpoints (ML0 /snapshots/*)
+    // -------------------------------------------------------------------------
+    /**
+     * Get the latest snapshot and decode its on-chain state.
+     */
+    async getLatestSnapshotOnChainState() {
+        const snapshot = await this.ml0.get('/snapshots/latest');
+        return extractOnChainState(snapshot);
+    }
+    /**
+     * Get a snapshot by ordinal and decode its on-chain state.
+     */
+    async getSnapshotOnChainState(ordinal) {
+        const snapshot = await this.ml0.get(`/snapshots/${ordinal}`);
+        return extractOnChainState(snapshot);
+    }
+    /**
+     * Get the latest snapshot ordinal.
+     */
+    async getLatestOrdinal() {
+        const snapshot = await this.ml0.get('/snapshots/latest');
+        return snapshot.value.ordinal;
+    }
+    // -------------------------------------------------------------------------
+    // DL1 data submission (framework POST /data)
+    // -------------------------------------------------------------------------
+    /**
+     * 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
+     */
+    async postData(signedData) {
+        if (!this.dl1) {
+            throw new Error('dl1Url is required for postData');
+        }
+        return this.dl1.post('/data', signedData);
+    }
+}

package/dist/esm/ottochain/snapshot.js

@@ -0,0 +1,100 @@
+/**
+ * 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 { HttpClient } from '../metakit/network/client.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 function decodeOnChainState(bytes) {
+    const json = new TextDecoder().decode(bytes);
+    return JSON.parse(json);
+}
+/**
+ * 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 async function getSnapshotOnChainState(ml0BaseUrl, ordinal) {
+    const client = new HttpClient(ml0BaseUrl);
+    const snapshot = await client.get(`/snapshots/${ordinal}`);
+    return extractOnChainState(snapshot);
+}
+/**
+ * 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 async function getLatestOnChainState(ml0BaseUrl) {
+    const client = new HttpClient(ml0BaseUrl);
+    const snapshot = await client.get('/snapshots/latest');
+    return extractOnChainState(snapshot);
+}
+/**
+ * Extract and decode on-chain state from a snapshot response.
+ */
+export function extractOnChainState(snapshot) {
+    const dataPart = snapshot.value?.dataApplication;
+    if (!dataPart?.onChainState) {
+        return null;
+    }
+    const bytes = new Uint8Array(dataPart.onChainState);
+    return decodeOnChainState(bytes);
+}
+// ---------------------------------------------------------------------------
+// Log filtering helpers
+// ---------------------------------------------------------------------------
+/**
+ * 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 function getLogsForFiber(onChain, fiberId) {
+    return onChain.latestLogs[fiberId] ?? [];
+}
+/**
+ * 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 function getEventReceipts(onChain, fiberId) {
+    return getLogsForFiber(onChain, fiberId)
+        .filter((entry) => 'eventName' in entry && 'success' in entry);
+}
+/**
+ * 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 function getScriptInvocations(onChain, fiberId) {
+    return getLogsForFiber(onChain, fiberId)
+        .filter((entry) => 'method' in entry && 'result' in entry);
+}

package/dist/esm/ottochain/types.js

@@ -0,0 +1,10 @@
+/**
+ * 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 {};

package/dist/esm/package.json

@@ -0,0 +1 @@
+{"type":"module"}

package/dist/esm/types.js

@@ -0,0 +1,20 @@
+/**
+ * OttoChain Type Aliases
+ *
+ * Semantic type aliases for common primitive types.
+ * These match the wire format used by the metagraph's JSON Logic engine.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Validate a DAG address format.
+ */
+export function isValidAddress(value) {
+    return /^DAG[0-9a-zA-Z]+$/.test(value);
+}
+/**
+ * Validate a UUID format.
+ */
+export function isValidFiberId(value) {
+    return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value);
+}