@ottochain/sdk 0.2.0

package/dist/types/metakit/hash.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Hashing Utilities
+ *
+ * SHA-256 and SHA-512 hashing for the Constellation signature protocol.
+ */
+import { Hash } from './types.js';
+/**
+ * Compute SHA-256 hash of canonical JSON data
+ *
+ * @param data - Any JSON-serializable object
+ * @returns Hash object with hex string and raw bytes
+ *
+ * @example
+ * ```typescript
+ * const hashResult = hash({ action: 'test' });
+ * console.log(hashResult.value); // 64-char hex string
+ * ```
+ */
+export declare function hash<T>(data: T): Hash;
+/**
+ * Compute SHA-256 hash of raw bytes
+ *
+ * @param bytes - Input bytes
+ * @returns Hash object with hex string and raw bytes
+ */
+export declare function hashBytes(bytes: Uint8Array): Hash;
+/**
+ * Compute the full signing digest according to Constellation protocol
+ *
+ * Protocol:
+ * 1. Serialize data to binary (with optional DataUpdate prefix)
+ * 2. Compute SHA-256 hash
+ * 3. Convert hash to hex string
+ * 4. Treat hex string as UTF-8 bytes (NOT hex decode)
+ * 5. Compute SHA-512 of those bytes
+ * 6. Truncate to 32 bytes for secp256k1 signing
+ *
+ * @param data - Any JSON-serializable object
+ * @param isDataUpdate - Whether to apply DataUpdate encoding
+ * @returns 32-byte digest ready for ECDSA signing
+ */
+export declare function computeDigest<T>(data: T, isDataUpdate?: boolean): Uint8Array;
+/**
+ * Compute SHA-256 hash of data with optional DataUpdate encoding
+ *
+ * @param data - Any JSON-serializable object
+ * @param isDataUpdate - Whether to apply DataUpdate encoding
+ * @returns Hash object
+ */
+export declare function hashData<T>(data: T, isDataUpdate?: boolean): Hash;

package/dist/types/metakit/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Metakit SDK
+ *
+ * Reusable signing, encoding, and network operations for Constellation metagraphs.
+ * This module is framework-level functionality, independent of any specific metagraph domain.
+ *
+ * @packageDocumentation
+ */
+export type { SignatureProof, Signed, KeyPair, Hash, VerificationResult, SigningOptions, } from './types.js';
+export { ALGORITHM, CONSTELLATION_PREFIX } from './types.js';
+export { canonicalize } from './canonicalize.js';
+export { toBytes, encodeDataUpdate } from './binary.js';
+export { hash, hashBytes, hashData, computeDigest } from './hash.js';
+export { decodeDataUpdate } from './codec.js';
+export { sign, signDataUpdate, signHash } from './sign.js';
+export { verify, verifyHash, verifySignature } from './verify.js';
+export { createSignedObject, addSignature, batchSign } from './signed-object.js';
+export { generateKeyPair, keyPairFromPrivateKey, getPublicKeyHex, getPublicKeyId, getAddress, isValidPrivateKey, isValidPublicKey, } from './wallet.js';
+export type { TransactionReference, CurrencyTransactionValue, CurrencyTransaction, TransferParams, } from './currency-types.js';
+export { TOKEN_DECIMALS } from './currency-types.js';
+export { createCurrencyTransaction, createCurrencyTransactionBatch, signCurrencyTransaction, verifyCurrencyTransaction, encodeCurrencyTransaction, hashCurrencyTransaction, getTransactionReference, isValidDagAddress, tokenToUnits, unitsToToken, } from './currency-transaction.js';
+export { CurrencyL1Client, DataL1Client, HttpClient, NetworkError } from './network/index.js';
+export type { NetworkConfig, RequestOptions, TransactionStatus, PendingTransaction, PostTransactionResponse, EstimateFeeResponse, PostDataResponse, } from './network/index.js';

package/dist/types/metakit/network/client.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Base HTTP client for network operations
+ *
+ * @packageDocumentation
+ */
+import { RequestOptions } from './types.js';
+/**
+ * Simple HTTP client using native fetch
+ */
+export declare class HttpClient {
+    private baseUrl;
+    private defaultTimeout;
+    constructor(baseUrl: string, timeout?: number);
+    /**
+     * Make a GET request
+     */
+    get<T>(path: string, options?: RequestOptions): Promise<T>;
+    /**
+     * Make a POST request
+     */
+    post<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    private request;
+}

package/dist/types/metakit/network/currency-l1-client.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Currency L1 client for submitting and querying transactions
+ *
+ * @packageDocumentation
+ */
+import type { NetworkConfig, PendingTransaction, PostTransactionResponse, RequestOptions } from './types.js';
+import type { TransactionReference, CurrencyTransaction } from '../currency-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 declare class CurrencyL1Client {
+    private client;
+    /**
+     * Create a new CurrencyL1Client
+     *
+     * @param config - Network configuration with l1Url
+     * @throws Error if l1Url is not provided
+     */
+    constructor(config: NetworkConfig);
+    /**
+     * 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
+     */
+    getLastReference(address: string, options?: RequestOptions): Promise<TransactionReference>;
+    /**
+     * Submit a signed currency transaction to the L1 network
+     *
+     * @param transaction - Signed currency transaction
+     * @param options - Request options
+     * @returns Response containing the transaction hash
+     */
+    postTransaction(transaction: CurrencyTransaction, options?: RequestOptions): Promise<PostTransactionResponse>;
+    /**
+     * 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
+     */
+    getPendingTransaction(hash: string, options?: RequestOptions): Promise<PendingTransaction | null>;
+    /**
+     * Check the health/availability of the L1 node
+     *
+     * @param options - Request options
+     * @returns True if the node is healthy
+     */
+    checkHealth(options?: RequestOptions): Promise<boolean>;
+}

package/dist/types/metakit/network/data-l1-client.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Data L1 client for submitting data transactions to metagraphs
+ *
+ * @packageDocumentation
+ */
+import type { NetworkConfig, EstimateFeeResponse, PostDataResponse, RequestOptions } from './types.js';
+import type { Signed } from '../types.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 declare class DataL1Client {
+    private client;
+    /**
+     * Create a new DataL1Client
+     *
+     * @param config - Network configuration with dataL1Url
+     * @throws Error if dataL1Url is not provided
+     */
+    constructor(config: NetworkConfig);
+    /**
+     * 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
+     */
+    estimateFee<T>(data: Signed<T>, options?: RequestOptions): Promise<EstimateFeeResponse>;
+    /**
+     * 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
+     */
+    postData<T>(data: Signed<T>, options?: RequestOptions): Promise<PostDataResponse>;
+    /**
+     * Check the health/availability of the Data L1 node
+     *
+     * @param options - Request options
+     * @returns True if the node is healthy
+     */
+    checkHealth(options?: RequestOptions): Promise<boolean>;
+}

package/dist/types/metakit/network/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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';
+export type { NetworkConfig, RequestOptions, TransactionStatus, PendingTransaction, PostTransactionResponse, EstimateFeeResponse, PostDataResponse, } from './types.js';

package/dist/types/metakit/network/types.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Network types for L1 client operations
+ *
+ * @packageDocumentation
+ */
+import type { CurrencyTransaction } from '../currency-types.js';
+/**
+ * Network configuration for connecting to L1 nodes
+ */
+export interface NetworkConfig {
+    /** Currency L1 endpoint URL (e.g., 'http://localhost:9010') */
+    l1Url?: string;
+    /** Data L1 endpoint URL (e.g., 'http://localhost:8080') */
+    dataL1Url?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+}
+/**
+ * HTTP request options
+ */
+export interface RequestOptions {
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Additional headers */
+    headers?: Record<string, string>;
+}
+/**
+ * Transaction status in the network
+ */
+export type TransactionStatus = 'Waiting' | 'InProgress' | 'Accepted';
+/**
+ * Pending transaction response from L1
+ */
+export interface PendingTransaction {
+    /** Transaction hash */
+    hash: string;
+    /** Current status */
+    status: TransactionStatus;
+    /** The transaction value */
+    transaction: CurrencyTransaction;
+}
+/**
+ * Response from posting a transaction
+ */
+export interface PostTransactionResponse {
+    /** Transaction hash */
+    hash: string;
+}
+/**
+ * Response from estimating data transaction fee
+ */
+export interface EstimateFeeResponse {
+    /** Estimated fee in smallest units */
+    fee: number;
+    /** Fee destination address */
+    address: string;
+}
+/**
+ * Response from posting data
+ */
+export interface PostDataResponse {
+    /** Data hash */
+    hash: string;
+}
+/**
+ * Network error with status code and response details
+ */
+export declare class NetworkError extends Error {
+    /** HTTP status code if applicable */
+    statusCode?: number;
+    /** Raw response body */
+    responseBody?: string;
+    constructor(message: string, statusCode?: number, responseBody?: string);
+}

package/dist/types/metakit/sign.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Signing Functions
+ *
+ * ECDSA signing using secp256k1 curve via dag4js.
+ * Implements the Constellation signature protocol.
+ */
+import { SignatureProof } from './types.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 declare function sign<T>(data: T, privateKey: string): Promise<SignatureProof>;
+/**
+ * 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 declare function signDataUpdate<T>(data: T, privateKey: string): Promise<SignatureProof>;
+/**
+ * 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 declare function signHash(hashHex: string, privateKey: string): Promise<string>;

package/dist/types/metakit/signed-object.d.ts

@@ -0,0 +1,66 @@
+/**
+ * High-Level Signed Object API
+ *
+ * Convenience functions for creating and managing signed objects.
+ */
+import { Signed, SigningOptions } from './types.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 declare function createSignedObject<T>(value: T, privateKey: string, options?: SigningOptions): Promise<Signed<T>>;
+/**
+ * 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 declare function addSignature<T>(signed: Signed<T>, privateKey: string, options?: SigningOptions): Promise<Signed<T>>;
+/**
+ * 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 declare function batchSign<T>(value: T, privateKeys: string[], options?: SigningOptions): Promise<Signed<T>>;

package/dist/types/metakit/types.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Core type definitions for the Ottochain SDK
+ */
+/**
+ * A signature proof containing the signer's public key ID and signature
+ */
+export interface SignatureProof {
+    /** Public key hex (uncompressed, without 04 prefix) - 128 characters */
+    id: string;
+    /** DER-encoded ECDSA signature in hex format */
+    signature: string;
+}
+/**
+ * A signed object wrapping a value with one or more signature proofs
+ */
+export interface Signed<T> {
+    /** The signed value */
+    value: T;
+    /** Array of signature proofs */
+    proofs: SignatureProof[];
+}
+/**
+ * A key pair for signing operations
+ */
+export interface KeyPair {
+    /** Private key in hex format */
+    privateKey: string;
+    /** Public key in hex format (uncompressed, with 04 prefix) */
+    publicKey: string;
+    /** DAG address derived from the public key */
+    address: string;
+}
+/**
+ * A hash result containing both hex string and raw bytes
+ */
+export interface Hash {
+    /** SHA-256 hash as 64-character hex string */
+    value: string;
+    /** Raw 32-byte hash as Uint8Array */
+    bytes: Uint8Array;
+}
+/**
+ * Result of signature verification
+ */
+export interface VerificationResult {
+    /** Whether all signatures are valid */
+    isValid: boolean;
+    /** Proofs that passed verification */
+    validProofs: SignatureProof[];
+    /** Proofs that failed verification */
+    invalidProofs: SignatureProof[];
+}
+/**
+ * Options for signing operations
+ */
+export interface SigningOptions {
+    /** Whether to sign as a DataUpdate (with Constellation prefix) */
+    isDataUpdate?: boolean;
+}
+/**
+ * Supported signature algorithm
+ */
+export declare const ALGORITHM: "SECP256K1_RFC8785_V1";
+/**
+ * Constellation prefix for DataUpdate signing
+ */
+export declare const CONSTELLATION_PREFIX = "\u0019Constellation Signed Data:\n";

package/dist/types/metakit/verify.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Signature Verification
+ *
+ * Verify ECDSA signatures using secp256k1 curve via dag4js.
+ */
+import { Signed, SignatureProof, VerificationResult } from './types.js';
+/**
+ * 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 declare function verify<T>(signed: Signed<T>, isDataUpdate?: boolean): Promise<VerificationResult>;
+/**
+ * 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 declare function verifyHash(hashHex: string, signature: string, publicKeyId: string): Promise<boolean>;
+/**
+ * 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 declare function verifySignature<T>(data: T, proof: SignatureProof, isDataUpdate?: boolean): Promise<boolean>;
+/**
+ * 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 declare function normalizeSignatureToLowS(signatureHex: string): string;

package/dist/types/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/types/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 { Address, FiberId, StateId, HashValue, FiberOrdinal, SnapshotOrdinal, 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';