@ottochain/sdk 0.2.0

package/dist/metakit/verify.js

@@ -0,0 +1,217 @@
+"use strict";
+/**
+ * Signature Verification
+ *
+ * Verify ECDSA signatures using secp256k1 curve via dag4js.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeSignatureToLowS = exports.verifySignature = exports.verifyHash = exports.verify = void 0;
+const dag4_1 = require("@stardust-collective/dag4");
+const js_sha256_1 = require("js-sha256");
+const binary_js_1 = require("./binary.js");
+// secp256k1 curve order (n) for signature normalization
+const SECP256K1_N = BigInt('0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141');
+const SECP256K1_HALF_N = SECP256K1_N / 2n;
+/**
+ * Verify a signed object
+ *
+ * @param signed - Signed object with value and proofs
+ * @param isDataUpdate - Whether the value was signed as a DataUpdate
+ * @returns VerificationResult with valid/invalid proof lists
+ *
+ * @example
+ * ```typescript
+ * const result = await verify(signedObject);
+ * if (result.isValid) {
+ *   console.log('All signatures valid');
+ * }
+ * ```
+ */
+async function verify(signed, isDataUpdate = false) {
+    // Compute the hash that should have been signed
+    const bytes = (0, binary_js_1.toBytes)(signed.value, isDataUpdate);
+    const hashHex = js_sha256_1.sha256.hex(bytes);
+    const validProofs = [];
+    const invalidProofs = [];
+    for (const proof of signed.proofs) {
+        try {
+            const isValid = await verifyHash(hashHex, proof.signature, proof.id);
+            if (isValid) {
+                validProofs.push(proof);
+            }
+            else {
+                invalidProofs.push(proof);
+            }
+        }
+        catch {
+            // Verification error = invalid
+            invalidProofs.push(proof);
+        }
+    }
+    return {
+        isValid: invalidProofs.length === 0 && validProofs.length > 0,
+        validProofs,
+        invalidProofs,
+    };
+}
+exports.verify = verify;
+/**
+ * Verify a signature against a SHA-256 hash
+ *
+ * Protocol:
+ * 1. Treat hash hex as UTF-8 bytes (NOT hex decode)
+ * 2. SHA-512 hash
+ * 3. Truncate to 32 bytes (handled internally by dag4)
+ * 4. Verify ECDSA signature
+ *
+ * @param hashHex - SHA-256 hash as 64-character hex string
+ * @param signature - DER-encoded signature in hex format
+ * @param publicKeyId - Public key in hex (with or without 04 prefix)
+ * @returns true if signature is valid
+ */
+async function verifyHash(hashHex, signature, publicKeyId) {
+    try {
+        // Normalize public key (add 04 prefix if needed)
+        const fullPublicKey = normalizePublicKey(publicKeyId);
+        // Normalize signature to low-S form for BIP 62/146 compatibility
+        // Some signing implementations produce high-S signatures which are
+        // mathematically valid but rejected by strict implementations
+        const normalizedSignature = normalizeSignatureToLowS(signature);
+        // Use dag4's verify which handles:
+        // 1. SHA-512 of hashHex (treating as UTF-8)
+        // 2. Internal truncation to 32 bytes
+        // 3. ECDSA verification
+        return dag4_1.dag4.keyStore.verify(fullPublicKey, hashHex, normalizedSignature);
+    }
+    catch {
+        return false;
+    }
+}
+exports.verifyHash = verifyHash;
+/**
+ * Verify a single signature proof against data
+ *
+ * @param data - The original data that was signed
+ * @param proof - The signature proof to verify
+ * @param isDataUpdate - Whether data was signed as DataUpdate
+ * @returns true if signature is valid
+ */
+async function verifySignature(data, proof, isDataUpdate = false) {
+    const bytes = (0, binary_js_1.toBytes)(data, isDataUpdate);
+    const hashHex = js_sha256_1.sha256.hex(bytes);
+    return verifyHash(hashHex, proof.signature, proof.id);
+}
+exports.verifySignature = verifySignature;
+/**
+ * Normalize public key to full format (with 04 prefix)
+ */
+function normalizePublicKey(publicKey) {
+    // If 128 chars (without 04 prefix), add prefix
+    if (publicKey.length === 128) {
+        return '04' + publicKey;
+    }
+    // If 130 chars (with 04 prefix), return as-is
+    if (publicKey.length === 130 && publicKey.startsWith('04')) {
+        return publicKey;
+    }
+    // Otherwise return as-is
+    return publicKey;
+}
+/**
+ * Normalize a DER-encoded signature to use low-S value.
+ *
+ * BIP 62/146 requires S values to be in the lower half of the curve order.
+ * Some signing implementations produce high-S signatures which are mathematically
+ * valid but rejected by strict verifiers. This normalizes high-S to low-S by
+ * computing S' = N - S where N is the curve order.
+ */
+function normalizeSignatureToLowS(signatureHex) {
+    const bytes = hexToBytes(signatureHex);
+    // Parse DER signature: 0x30 <total_len> 0x02 <r_len> <r> 0x02 <s_len> <s>
+    if (bytes[0] !== 0x30) {
+        return signatureHex; // Not a valid DER signature
+    }
+    let offset = 2; // Skip 0x30 and total length
+    // Parse R
+    if (bytes[offset] !== 0x02) {
+        return signatureHex;
+    }
+    const rLen = bytes[offset + 1];
+    const rStart = offset + 2;
+    const rEnd = rStart + rLen;
+    offset = rEnd;
+    // Parse S
+    if (bytes[offset] !== 0x02) {
+        return signatureHex;
+    }
+    const sLen = bytes[offset + 1];
+    const sStart = offset + 2;
+    const sEnd = sStart + sLen;
+    // Extract S value
+    const sBytes = bytes.slice(sStart, sEnd);
+    const s = bytesToBigInt(sBytes);
+    // Check if S is high (> N/2)
+    if (s <= SECP256K1_HALF_N) {
+        return signatureHex; // Already low-S
+    }
+    // Compute low-S: S' = N - S
+    const lowS = SECP256K1_N - s;
+    const lowSBytes = bigIntToBytes(lowS);
+    // Ensure proper DER encoding (no leading zeros unless needed for sign bit)
+    const normalizedSBytes = normalizeDerInteger(lowSBytes);
+    // Build new signature
+    const rBytes = bytes.slice(rStart, rEnd);
+    const normalizedRBytes = normalizeDerInteger(rBytes);
+    const newSigContent = new Uint8Array([
+        0x02,
+        normalizedRBytes.length,
+        ...normalizedRBytes,
+        0x02,
+        normalizedSBytes.length,
+        ...normalizedSBytes,
+    ]);
+    const newSig = new Uint8Array([0x30, newSigContent.length, ...newSigContent]);
+    return bytesToHex(newSig);
+}
+exports.normalizeSignatureToLowS = normalizeSignatureToLowS;
+/**
+ * Normalize a byte array for DER integer encoding
+ */
+function normalizeDerInteger(bytes) {
+    // Remove leading zeros, but keep one if the high bit is set
+    let start = 0;
+    while (start < bytes.length - 1 && bytes[start] === 0 && (bytes[start + 1] & 0x80) === 0) {
+        start++;
+    }
+    // Add leading zero if high bit is set (to indicate positive number)
+    if (bytes[start] & 0x80) {
+        const result = new Uint8Array(bytes.length - start + 1);
+        result[0] = 0;
+        result.set(bytes.slice(start), 1);
+        return result;
+    }
+    return bytes.slice(start);
+}
+function hexToBytes(hex) {
+    const bytes = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < hex.length; i += 2) {
+        bytes[i / 2] = parseInt(hex.substr(i, 2), 16);
+    }
+    return bytes;
+}
+function bytesToHex(bytes) {
+    return Array.from(bytes)
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('');
+}
+function bytesToBigInt(bytes) {
+    let result = 0n;
+    for (const byte of bytes) {
+        result = (result << 8n) | BigInt(byte);
+    }
+    return result;
+}
+function bigIntToBytes(n) {
+    const hex = n.toString(16).padStart(64, '0'); // 32 bytes = 64 hex chars
+    return hexToBytes(hex);
+}

package/dist/metakit/wallet.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Wallet and Key Management Utilities
+ *
+ * Functions for generating and managing cryptographic keys.
+ */
+import { KeyPair } from './types.js';
+/**
+ * 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 declare function generateKeyPair(): KeyPair;
+/**
+ * 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 declare function keyPairFromPrivateKey(privateKey: string): KeyPair;
+/**
+ * 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 declare function getPublicKeyHex(privateKey: string, compressed?: boolean): string;
+/**
+ * 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 declare function getPublicKeyId(privateKey: string): string;
+/**
+ * Get DAG address from a public key
+ *
+ * @param publicKey - Public key in hex format (with or without 04 prefix)
+ * @returns DAG address string
+ */
+export declare function getAddress(publicKey: string): string;
+/**
+ * Validate that a private key is correctly formatted
+ *
+ * @param privateKey - Private key to validate
+ * @returns true if valid hex string of correct length
+ */
+export declare function isValidPrivateKey(privateKey: string): boolean;
+/**
+ * Validate that a public key is correctly formatted
+ *
+ * @param publicKey - Public key to validate
+ * @returns true if valid hex string of correct length
+ */
+export declare function isValidPublicKey(publicKey: string): boolean;

package/dist/metakit/wallet.js

@@ -0,0 +1,127 @@
+"use strict";
+/**
+ * Wallet and Key Management Utilities
+ *
+ * Functions for generating and managing cryptographic keys.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isValidPublicKey = exports.isValidPrivateKey = exports.getAddress = exports.getPublicKeyId = exports.getPublicKeyHex = exports.keyPairFromPrivateKey = exports.generateKeyPair = void 0;
+const dag4_1 = require("@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)
+ * ```
+ */
+function generateKeyPair() {
+    const privateKey = dag4_1.dag4.keyStore.generatePrivateKey();
+    return keyPairFromPrivateKey(privateKey);
+}
+exports.generateKeyPair = generateKeyPair;
+/**
+ * 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);
+ * ```
+ */
+function keyPairFromPrivateKey(privateKey) {
+    // Get uncompressed public key (with 04 prefix)
+    const publicKey = dag4_1.dag4.keyStore.getPublicKeyFromPrivate(privateKey, false);
+    // Derive DAG address
+    const address = dag4_1.dag4.keyStore.getDagAddressFromPublicKey(publicKey);
+    return {
+        privateKey,
+        publicKey: normalizePublicKey(publicKey),
+        address,
+    };
+}
+exports.keyPairFromPrivateKey = keyPairFromPrivateKey;
+/**
+ * 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
+ */
+function getPublicKeyHex(privateKey, compressed = false) {
+    return dag4_1.dag4.keyStore.getPublicKeyFromPrivate(privateKey, compressed);
+}
+exports.getPublicKeyHex = getPublicKeyHex;
+/**
+ * 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)
+ */
+function getPublicKeyId(privateKey) {
+    const publicKey = dag4_1.dag4.keyStore.getPublicKeyFromPrivate(privateKey, false);
+    // Remove 04 prefix if present
+    if (publicKey.length === 130 && publicKey.startsWith('04')) {
+        return publicKey.substring(2);
+    }
+    return publicKey;
+}
+exports.getPublicKeyId = getPublicKeyId;
+/**
+ * Get DAG address from a public key
+ *
+ * @param publicKey - Public key in hex format (with or without 04 prefix)
+ * @returns DAG address string
+ */
+function getAddress(publicKey) {
+    const normalizedKey = normalizePublicKey(publicKey);
+    return dag4_1.dag4.keyStore.getDagAddressFromPublicKey(normalizedKey);
+}
+exports.getAddress = getAddress;
+/**
+ * Validate that a private key is correctly formatted
+ *
+ * @param privateKey - Private key to validate
+ * @returns true if valid hex string of correct length
+ */
+function isValidPrivateKey(privateKey) {
+    if (typeof privateKey !== 'string')
+        return false;
+    if (privateKey.length !== 64)
+        return false;
+    return /^[0-9a-fA-F]+$/.test(privateKey);
+}
+exports.isValidPrivateKey = isValidPrivateKey;
+/**
+ * Validate that a public key is correctly formatted
+ *
+ * @param publicKey - Public key to validate
+ * @returns true if valid hex string of correct length
+ */
+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);
+}
+exports.isValidPublicKey = isValidPublicKey;
+/**
+ * Normalize public key to include 04 prefix
+ */
+function normalizePublicKey(publicKey) {
+    if (publicKey.length === 128) {
+        return '04' + publicKey;
+    }
+    return publicKey;
+}

package/dist/ottochain/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Ottochain SDK
+ *
+ * Domain-specific types and clients for the ottochain metagraph.
+ *
+ * @packageDocumentation
+ */
+export * as proto from '../generated/index.js';
+export type { FiberOrdinal, SnapshotOrdinal, StateId, Address, HashValue, 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 { MetagraphClient } from './metagraph-client.js';

package/dist/ottochain/index.js

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * Ottochain SDK
+ *
+ * Domain-specific types and clients for the ottochain metagraph.
+ *
+ * @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;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MetagraphClient = exports.extractOnChainState = exports.getScriptInvocations = exports.getEventReceipts = exports.getLogsForFiber = exports.getLatestOnChainState = exports.getSnapshotOnChainState = exports.decodeOnChainState = exports.proto = void 0;
+// Re-export generated protobuf types
+exports.proto = __importStar(require("../generated/index.js"));
+var snapshot_js_1 = require("./snapshot.js");
+Object.defineProperty(exports, "decodeOnChainState", { enumerable: true, get: function () { return snapshot_js_1.decodeOnChainState; } });
+Object.defineProperty(exports, "getSnapshotOnChainState", { enumerable: true, get: function () { return snapshot_js_1.getSnapshotOnChainState; } });
+Object.defineProperty(exports, "getLatestOnChainState", { enumerable: true, get: function () { return snapshot_js_1.getLatestOnChainState; } });
+Object.defineProperty(exports, "getLogsForFiber", { enumerable: true, get: function () { return snapshot_js_1.getLogsForFiber; } });
+Object.defineProperty(exports, "getEventReceipts", { enumerable: true, get: function () { return snapshot_js_1.getEventReceipts; } });
+Object.defineProperty(exports, "getScriptInvocations", { enumerable: true, get: function () { return snapshot_js_1.getScriptInvocations; } });
+Object.defineProperty(exports, "extractOnChainState", { enumerable: true, get: function () { return snapshot_js_1.extractOnChainState; } });
+var metagraph_client_js_1 = require("./metagraph-client.js");
+Object.defineProperty(exports, "MetagraphClient", { enumerable: true, get: function () { return metagraph_client_js_1.MetagraphClient; } });

package/dist/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;
+    }>;
+}