@ottochain/sdk 0.2.0

package/dist/esm/metakit/network/client.js

@@ -0,0 +1,74 @@
+/**
+ * Base HTTP client for network operations
+ *
+ * @packageDocumentation
+ */
+import { NetworkError } from './types.js';
+const DEFAULT_TIMEOUT = 30000;
+/**
+ * Simple HTTP client using native fetch
+ */
+export class HttpClient {
+    constructor(baseUrl, timeout = DEFAULT_TIMEOUT) {
+        this.baseUrl = baseUrl.replace(/\/$/, '');
+        this.defaultTimeout = timeout;
+    }
+    /**
+     * Make a GET request
+     */
+    async get(path, options = {}) {
+        return this.request('GET', path, undefined, options);
+    }
+    /**
+     * Make a POST request
+     */
+    async post(path, body, options = {}) {
+        return this.request('POST', path, body, options);
+    }
+    async request(method, path, body, options = {}) {
+        const url = `${this.baseUrl}${path}`;
+        const timeout = options.timeout ?? this.defaultTimeout;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeout);
+        try {
+            const headers = {
+                'Content-Type': 'application/json',
+                Accept: 'application/json',
+                ...options.headers,
+            };
+            const response = await fetch(url, {
+                method,
+                headers,
+                body: body ? JSON.stringify(body) : undefined,
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            const text = await response.text();
+            if (!response.ok) {
+                throw new NetworkError(`HTTP ${response.status}: ${response.statusText}`, response.status, text);
+            }
+            if (!text) {
+                return undefined;
+            }
+            try {
+                return JSON.parse(text);
+            }
+            catch {
+                return text;
+            }
+        }
+        catch (error) {
+            clearTimeout(timeoutId);
+            if (error instanceof NetworkError) {
+                throw error;
+            }
+            if (error instanceof Error) {
+                if (error.name === 'AbortError') {
+                    throw new NetworkError(`Request timeout after ${timeout}ms`);
+                }
+                throw new NetworkError(error.message);
+            }
+            throw new NetworkError('Unknown network error');
+        }
+    }
+}

package/dist/esm/metakit/network/currency-l1-client.js

@@ -0,0 +1,97 @@
+/**
+ * Currency L1 client for submitting and querying transactions
+ *
+ * @packageDocumentation
+ */
+import { HttpClient } from './client.js';
+import { NetworkError } from './types.js';
+/**
+ * Client for interacting with Currency L1 nodes
+ *
+ * @example
+ * ```typescript
+ * const client = new CurrencyL1Client({ l1Url: 'http://localhost:9010' });
+ *
+ * // Get last reference for an address
+ * const lastRef = await client.getLastReference('DAG...');
+ *
+ * // Submit a transaction
+ * const result = await client.postTransaction(signedTx);
+ *
+ * // Check transaction status
+ * const pending = await client.getPendingTransaction(result.hash);
+ * ```
+ */
+export class CurrencyL1Client {
+    /**
+     * Create a new CurrencyL1Client
+     *
+     * @param config - Network configuration with l1Url
+     * @throws Error if l1Url is not provided
+     */
+    constructor(config) {
+        if (!config.l1Url) {
+            throw new Error('l1Url is required for CurrencyL1Client');
+        }
+        this.client = new HttpClient(config.l1Url, config.timeout);
+    }
+    /**
+     * Get the last accepted transaction reference for an address
+     *
+     * This is needed to create a new transaction that chains from
+     * the address's most recent transaction.
+     *
+     * @param address - DAG address to query
+     * @param options - Request options
+     * @returns Transaction reference with hash and ordinal
+     */
+    async getLastReference(address, options) {
+        return this.client.get(`/transactions/last-reference/${address}`, options);
+    }
+    /**
+     * Submit a signed currency transaction to the L1 network
+     *
+     * @param transaction - Signed currency transaction
+     * @param options - Request options
+     * @returns Response containing the transaction hash
+     */
+    async postTransaction(transaction, options) {
+        return this.client.post('/transactions', transaction, options);
+    }
+    /**
+     * Get a pending transaction by hash
+     *
+     * Use this to poll for transaction status after submission.
+     * Returns null if the transaction is not found (already confirmed or invalid).
+     *
+     * @param hash - Transaction hash
+     * @param options - Request options
+     * @returns Pending transaction details or null if not found
+     */
+    async getPendingTransaction(hash, options) {
+        try {
+            return await this.client.get(`/transactions/${hash}`, options);
+        }
+        catch (error) {
+            if (error instanceof NetworkError && error.statusCode === 404) {
+                return null;
+            }
+            throw error;
+        }
+    }
+    /**
+     * Check the health/availability of the L1 node
+     *
+     * @param options - Request options
+     * @returns True if the node is healthy
+     */
+    async checkHealth(options) {
+        try {
+            await this.client.get('/cluster/info', options);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}

package/dist/esm/metakit/network/data-l1-client.js

@@ -0,0 +1,72 @@
+/**
+ * Data L1 client for submitting data transactions to metagraphs
+ *
+ * @packageDocumentation
+ */
+import { HttpClient } from './client.js';
+/**
+ * Client for interacting with Data L1 nodes (metagraphs)
+ *
+ * @example
+ * ```typescript
+ * const client = new DataL1Client({ dataL1Url: 'http://localhost:8080' });
+ *
+ * // Estimate fee for data submission
+ * const feeInfo = await client.estimateFee(signedData);
+ *
+ * // Submit data
+ * const result = await client.postData(signedData);
+ * ```
+ */
+export class DataL1Client {
+    /**
+     * Create a new DataL1Client
+     *
+     * @param config - Network configuration with dataL1Url
+     * @throws Error if dataL1Url is not provided
+     */
+    constructor(config) {
+        if (!config.dataL1Url) {
+            throw new Error('dataL1Url is required for DataL1Client');
+        }
+        this.client = new HttpClient(config.dataL1Url, config.timeout);
+    }
+    /**
+     * Estimate the fee for submitting data
+     *
+     * Some metagraphs charge fees for data submissions.
+     * Call this before postData to know the required fee.
+     *
+     * @param data - Signed data object to estimate fee for
+     * @param options - Request options
+     * @returns Fee estimate with amount and destination address
+     */
+    async estimateFee(data, options) {
+        return this.client.post('/data/estimate-fee', data, options);
+    }
+    /**
+     * Submit signed data to the Data L1 node
+     *
+     * @param data - Signed data object to submit
+     * @param options - Request options
+     * @returns Response containing the data hash
+     */
+    async postData(data, options) {
+        return this.client.post('/data', data, options);
+    }
+    /**
+     * Check the health/availability of the Data L1 node
+     *
+     * @param options - Request options
+     * @returns True if the node is healthy
+     */
+    async checkHealth(options) {
+        try {
+            await this.client.get('/cluster/info', options);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}

package/dist/esm/metakit/network/index.js

@@ -0,0 +1,9 @@
+/**
+ * Network operations for L1 node interactions
+ *
+ * @packageDocumentation
+ */
+export { CurrencyL1Client } from './currency-l1-client.js';
+export { DataL1Client } from './data-l1-client.js';
+export { HttpClient } from './client.js';
+export { NetworkError } from './types.js';

package/dist/esm/metakit/network/types.js

@@ -0,0 +1,16 @@
+/**
+ * Network types for L1 client operations
+ *
+ * @packageDocumentation
+ */
+/**
+ * Network error with status code and response details
+ */
+export class NetworkError extends Error {
+    constructor(message, statusCode, responseBody) {
+        super(message);
+        this.name = 'NetworkError';
+        this.statusCode = statusCode;
+        this.responseBody = responseBody;
+    }
+}

package/dist/esm/metakit/sign.js

@@ -0,0 +1,114 @@
+/**
+ * Signing Functions
+ *
+ * ECDSA signing using secp256k1 curve via dag4js.
+ * Implements the Constellation signature protocol.
+ */
+import { dag4 } from '@stardust-collective/dag4';
+import { sha256 } from 'js-sha256';
+import { canonicalize } from './canonicalize.js';
+/**
+ * Sign data using the regular Constellation protocol (non-DataUpdate)
+ *
+ * Protocol:
+ * 1. Canonicalize JSON (RFC 8785)
+ * 2. SHA-256 hash the canonical JSON string
+ * 3. Sign using dag4.keyStore.sign
+ *
+ * @param data - Any JSON-serializable object
+ * @param privateKey - Private key in hex format
+ * @returns SignatureProof with public key ID and signature
+ *
+ * @example
+ * ```typescript
+ * const proof = await sign({ action: 'test' }, privateKeyHex);
+ * console.log(proof.id);        // public key (128 chars)
+ * console.log(proof.signature); // DER signature
+ * ```
+ */
+export async function sign(data, privateKey) {
+    // Step 1: Canonicalize JSON (RFC 8785)
+    const canonicalJson = canonicalize(data);
+    // Step 2-3: UTF-8 encode and SHA-256 hash (sha256 handles UTF-8 encoding internally)
+    // Returns 64-character hex string
+    const hashHex = sha256(canonicalJson);
+    // Step 4-6: dag4.keyStore.sign internally:
+    //   4. Treats hashHex as UTF-8 bytes
+    //   5. SHA-512 hashes those bytes, truncates to 32 bytes
+    //   6. Signs with ECDSA secp256k1
+    const signature = await dag4.keyStore.sign(privateKey, hashHex);
+    // Get public key ID (without 04 prefix)
+    const publicKey = dag4.keyStore.getPublicKeyFromPrivate(privateKey, false);
+    const id = normalizePublicKeyId(publicKey);
+    return { id, signature };
+}
+/**
+ * Sign data as a DataUpdate (with Constellation prefix)
+ *
+ * Protocol:
+ * 1. Canonicalize JSON (RFC 8785)
+ * 2. Base64 encode the canonical JSON
+ * 3. Sign using dag4.keyStore.dataSign (adds Constellation prefix internally)
+ *
+ * @param data - Any JSON-serializable object
+ * @param privateKey - Private key in hex format
+ * @returns SignatureProof
+ */
+export async function signDataUpdate(data, privateKey) {
+    // Step 1: Canonicalize JSON
+    const canonicalJson = canonicalize(data);
+    // Step 2: Base64 encode for dataSign
+    const base64String = Buffer.from(canonicalJson, 'utf-8').toString('base64');
+    // Step 3: Sign using dag4's dataSign (handles Constellation prefix internally)
+    const signature = await dag4.keyStore.dataSign(privateKey, base64String);
+    // Get public key ID
+    const publicKey = dag4.keyStore.getPublicKeyFromPrivate(privateKey, false);
+    const id = normalizePublicKeyId(publicKey);
+    return { id, signature };
+}
+/**
+ * Sign a pre-computed SHA-256 hash
+ *
+ * This is the low-level signing function. Use `sign()` or `signDataUpdate()`
+ * for most use cases.
+ *
+ * Protocol (performed by dag4.keyStore.sign):
+ * 1. Treat hashHex as UTF-8 bytes (64 ASCII characters = 64 bytes)
+ * 2. SHA-512 hash those bytes (produces 64 bytes)
+ * 3. Truncate to first 32 bytes (for secp256k1 curve order)
+ * 4. Sign with ECDSA secp256k1
+ * 5. Return DER-encoded signature
+ *
+ * @param hashHex - SHA-256 hash as 64-character hex string
+ * @param privateKey - Private key in hex format (64 characters)
+ * @returns DER-encoded signature in hex format
+ *
+ * @example
+ * ```typescript
+ * // Compute your own hash
+ * const hashHex = sha256(myData);
+ * const signature = await signHash(hashHex, privateKey);
+ * ```
+ */
+export async function signHash(hashHex, privateKey) {
+    // dag4.keyStore.sign performs:
+    // 1. SHA-512 of hashHex (treating 64 hex chars as UTF-8 bytes)
+    // 2. Truncation to 32 bytes (handled internally by crypto library)
+    // 3. ECDSA signing with secp256k1
+    return dag4.keyStore.sign(privateKey, hashHex);
+}
+/**
+ * Normalize public key to ID format (without 04 prefix, 128 chars)
+ */
+function normalizePublicKeyId(publicKey) {
+    // If 130 chars (with 04 prefix), remove prefix
+    if (publicKey.length === 130 && publicKey.startsWith('04')) {
+        return publicKey.substring(2);
+    }
+    // If 128 chars (without prefix), return as-is
+    if (publicKey.length === 128) {
+        return publicKey;
+    }
+    // Otherwise return as-is and let validation catch issues
+    return publicKey;
+}

package/dist/esm/metakit/signed-object.js

@@ -0,0 +1,94 @@
+/**
+ * High-Level Signed Object API
+ *
+ * Convenience functions for creating and managing signed objects.
+ */
+import { sign, signDataUpdate } from './sign.js';
+/**
+ * Create a signed object with a single signature
+ *
+ * @param value - Any JSON-serializable object
+ * @param privateKey - Private key in hex format
+ * @param options - Signing options
+ * @returns Signed object ready for submission
+ *
+ * @example
+ * ```typescript
+ * // Sign a regular data object
+ * const signed = await createSignedObject(myData, privateKey);
+ *
+ * // Sign as DataUpdate for L1 submission
+ * const signedUpdate = await createSignedObject(myData, privateKey, { isDataUpdate: true });
+ * ```
+ */
+export async function createSignedObject(value, privateKey, options = {}) {
+    const { isDataUpdate = false } = options;
+    const proof = isDataUpdate
+        ? await signDataUpdate(value, privateKey)
+        : await sign(value, privateKey);
+    return {
+        value,
+        proofs: [proof],
+    };
+}
+/**
+ * Add an additional signature to an existing signed object
+ *
+ * This allows building multi-signature objects where multiple parties
+ * need to sign the same data.
+ *
+ * @param signed - Existing signed object
+ * @param privateKey - Private key in hex format
+ * @param options - Signing options (must match original signing)
+ * @returns New signed object with additional proof
+ *
+ * @example
+ * ```typescript
+ * // First party signs
+ * let signed = await createSignedObject(data, party1Key);
+ *
+ * // Second party adds signature
+ * signed = await addSignature(signed, party2Key);
+ *
+ * // Now has 2 proofs
+ * console.log(signed.proofs.length); // 2
+ * ```
+ */
+export async function addSignature(signed, privateKey, options = {}) {
+    const { isDataUpdate = false } = options;
+    const newProof = isDataUpdate
+        ? await signDataUpdate(signed.value, privateKey)
+        : await sign(signed.value, privateKey);
+    return {
+        value: signed.value,
+        proofs: [...signed.proofs, newProof],
+    };
+}
+/**
+ * Create a signed object with multiple signatures at once
+ *
+ * Useful when you have access to multiple private keys and want
+ * to create a multi-sig object in one operation.
+ *
+ * @param value - Any JSON-serializable object
+ * @param privateKeys - Array of private keys in hex format
+ * @param options - Signing options
+ * @returns Signed object with multiple proofs
+ *
+ * @example
+ * ```typescript
+ * const signed = await batchSign(data, [key1, key2, key3]);
+ * console.log(signed.proofs.length); // 3
+ * ```
+ */
+export async function batchSign(value, privateKeys, options = {}) {
+    if (privateKeys.length === 0) {
+        throw new Error('At least one private key is required');
+    }
+    const { isDataUpdate = false } = options;
+    const proofs = await Promise.all(privateKeys.map((key) => (isDataUpdate ? signDataUpdate(value, key) : sign(value, key))));
+    return {
+        value,
+        proofs,
+    };
+}

package/dist/esm/metakit/types.js

@@ -0,0 +1,11 @@
+/**
+ * Core type definitions for the Ottochain SDK
+ */
+/**
+ * Supported signature algorithm
+ */
+export const ALGORITHM = 'SECP256K1_RFC8785_V1';
+/**
+ * Constellation prefix for DataUpdate signing
+ */
+export const CONSTELLATION_PREFIX = '\x19Constellation Signed Data:\n';

package/dist/esm/metakit/verify.js

@@ -0,0 +1,210 @@
+/**
+ * Signature Verification
+ *
+ * Verify ECDSA signatures using secp256k1 curve via dag4js.
+ */
+import { dag4 } from '@stardust-collective/dag4';
+import { sha256 } from 'js-sha256';
+import { toBytes } from './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');
+ * }
+ * ```
+ */
+export async function verify(signed, isDataUpdate = false) {
+    // Compute the hash that should have been signed
+    const bytes = toBytes(signed.value, isDataUpdate);
+    const hashHex = 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,
+    };
+}
+/**
+ * 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
+ */
+export 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.keyStore.verify(fullPublicKey, hashHex, normalizedSignature);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 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
+ */
+export async function verifySignature(data, proof, isDataUpdate = false) {
+    const bytes = toBytes(data, isDataUpdate);
+    const hashHex = sha256.hex(bytes);
+    return verifyHash(hashHex, proof.signature, proof.id);
+}
+/**
+ * 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.
+ */
+export 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);
+}
+/**
+ * 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);
+}