@ottochain/sdk 0.2.0

package/dist/metakit/currency-transaction.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Currency transaction operations for metagraph token transfers
+ *
+ * @packageDocumentation
+ */
+import type { CurrencyTransaction, TransactionReference, TransferParams } from './currency-types.js';
+import type { VerificationResult } from './types.js';
+/**
+ * Convert token amount to smallest units
+ *
+ * @param amount - Amount in token units (e.g., 100.5)
+ * @returns Amount in smallest units (1e-8)
+ *
+ * @example
+ * ```typescript
+ * const units = tokenToUnits(100.5); // 10050000000
+ * ```
+ */
+export declare function tokenToUnits(amount: number): number;
+/**
+ * Convert smallest units to token amount
+ *
+ * @param units - Amount in smallest units
+ * @returns Amount in token units
+ *
+ * @example
+ * ```typescript
+ * const tokens = unitsToToken(10050000000); // 100.5
+ * ```
+ */
+export declare function unitsToToken(units: number): number;
+/**
+ * Validate DAG address format
+ *
+ * @param address - DAG address to validate
+ * @returns True if address is valid
+ *
+ * @example
+ * ```typescript
+ * const valid = isValidDagAddress('DAG...');
+ * ```
+ */
+export declare function isValidDagAddress(address: string): boolean;
+/**
+ * Create a metagraph token transaction
+ *
+ * @param params - Transfer parameters
+ * @param privateKey - Private key to sign with (hex string)
+ * @param lastRef - Reference to last accepted transaction
+ * @returns Signed currency transaction
+ *
+ * @throws If addresses are invalid or amount is too small
+ *
+ * @example
+ * ```typescript
+ * const tx = await createCurrencyTransaction(
+ *   { destination: 'DAG...', amount: 100.5, fee: 0 },
+ *   privateKey,
+ *   { hash: 'abc123...', ordinal: 5 }
+ * );
+ * ```
+ */
+export declare function createCurrencyTransaction(params: TransferParams, privateKey: string, lastRef: TransactionReference): Promise<CurrencyTransaction>;
+/**
+ * Create multiple metagraph token transactions (batch)
+ *
+ * @param transfers - Array of transfer parameters
+ * @param privateKey - Private key to sign with
+ * @param lastRef - Reference to last accepted transaction
+ * @returns Array of signed currency transactions
+ *
+ * @throws If any address is invalid or amount is too small
+ *
+ * @example
+ * ```typescript
+ * const txns = await createCurrencyTransactionBatch(
+ *   [
+ *     { destination: 'DAG...1', amount: 10 },
+ *     { destination: 'DAG...2', amount: 20 },
+ *   ],
+ *   privateKey,
+ *   { hash: 'abc123...', ordinal: 5 }
+ * );
+ * ```
+ */
+export declare function createCurrencyTransactionBatch(transfers: TransferParams[], privateKey: string, lastRef: TransactionReference): Promise<CurrencyTransaction[]>;
+/**
+ * Add a signature to an existing currency transaction (for multi-sig)
+ *
+ * @param transaction - Transaction to sign
+ * @param privateKey - Private key to sign with
+ * @returns Transaction with additional signature
+ *
+ * @throws If sign-verify fails
+ *
+ * @example
+ * ```typescript
+ * const signedTx = await signCurrencyTransaction(tx, privateKey2);
+ * ```
+ */
+export declare function signCurrencyTransaction(transaction: CurrencyTransaction, privateKey: string): Promise<CurrencyTransaction>;
+/**
+ * Verify all signatures on a currency transaction
+ *
+ * @param transaction - Transaction to verify
+ * @returns Verification result with valid/invalid proofs
+ *
+ * @example
+ * ```typescript
+ * const result = await verifyCurrencyTransaction(tx);
+ * console.log('Valid:', result.isValid);
+ * ```
+ */
+export declare function verifyCurrencyTransaction(transaction: CurrencyTransaction): Promise<VerificationResult>;
+/**
+ * Encode a currency transaction for hashing
+ *
+ * @param transaction - Transaction to encode
+ * @returns Hex-encoded string
+ *
+ * @example
+ * ```typescript
+ * const encoded = encodeCurrencyTransaction(tx);
+ * ```
+ */
+export declare function encodeCurrencyTransaction(transaction: CurrencyTransaction): string;
+/**
+ * Hash a currency transaction
+ *
+ * @param transaction - Transaction to hash
+ * @returns Hash object with value and bytes
+ *
+ * @example
+ * ```typescript
+ * const hash = await hashCurrencyTransaction(tx);
+ * console.log('Hash:', hash.value);
+ * ```
+ */
+export declare function hashCurrencyTransaction(transaction: CurrencyTransaction): Promise<{
+    value: string;
+    bytes: Uint8Array;
+}>;
+/**
+ * Get transaction reference from a currency transaction
+ * Useful for chaining transactions
+ *
+ * @param transaction - Transaction to extract reference from
+ * @param ordinal - Ordinal number for this transaction
+ * @returns Transaction reference
+ *
+ * @example
+ * ```typescript
+ * const ref = await getTransactionReference(tx, 6);
+ * // Use ref as lastRef for next transaction
+ * ```
+ */
+export declare function getTransactionReference(transaction: CurrencyTransaction, ordinal: number): Promise<TransactionReference>;

package/dist/metakit/currency-transaction.js

@@ -0,0 +1,319 @@
+"use strict";
+/**
+ * Currency transaction operations for metagraph token transfers
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getTransactionReference = exports.hashCurrencyTransaction = exports.encodeCurrencyTransaction = exports.verifyCurrencyTransaction = exports.signCurrencyTransaction = exports.createCurrencyTransactionBatch = exports.createCurrencyTransaction = exports.isValidDagAddress = exports.unitsToToken = exports.tokenToUnits = void 0;
+const dag4_keystore_1 = require("@stardust-collective/dag4-keystore");
+const currency_types_js_1 = require("./currency-types.js");
+const wallet_js_1 = require("./wallet.js");
+const verify_js_1 = require("./verify.js");
+/**
+ * Convert token amount to smallest units
+ *
+ * @param amount - Amount in token units (e.g., 100.5)
+ * @returns Amount in smallest units (1e-8)
+ *
+ * @example
+ * ```typescript
+ * const units = tokenToUnits(100.5); // 10050000000
+ * ```
+ */
+function tokenToUnits(amount) {
+    return Math.floor(amount * 1e8);
+}
+exports.tokenToUnits = tokenToUnits;
+/**
+ * Convert smallest units to token amount
+ *
+ * @param units - Amount in smallest units
+ * @returns Amount in token units
+ *
+ * @example
+ * ```typescript
+ * const tokens = unitsToToken(10050000000); // 100.5
+ * ```
+ */
+function unitsToToken(units) {
+    return units * currency_types_js_1.TOKEN_DECIMALS;
+}
+exports.unitsToToken = unitsToToken;
+/**
+ * Validate DAG address format
+ *
+ * @param address - DAG address to validate
+ * @returns True if address is valid
+ *
+ * @example
+ * ```typescript
+ * const valid = isValidDagAddress('DAG...');
+ * ```
+ */
+function isValidDagAddress(address) {
+    return dag4_keystore_1.keyStore.validateDagAddress(address);
+}
+exports.isValidDagAddress = isValidDagAddress;
+/**
+ * Create a metagraph token transaction
+ *
+ * @param params - Transfer parameters
+ * @param privateKey - Private key to sign with (hex string)
+ * @param lastRef - Reference to last accepted transaction
+ * @returns Signed currency transaction
+ *
+ * @throws If addresses are invalid or amount is too small
+ *
+ * @example
+ * ```typescript
+ * const tx = await createCurrencyTransaction(
+ *   { destination: 'DAG...', amount: 100.5, fee: 0 },
+ *   privateKey,
+ *   { hash: 'abc123...', ordinal: 5 }
+ * );
+ * ```
+ */
+async function createCurrencyTransaction(params, privateKey, lastRef) {
+    // Get source address from private key
+    const publicKey = dag4_keystore_1.keyStore.getPublicKeyFromPrivate(privateKey);
+    const source = (0, wallet_js_1.getAddress)(publicKey);
+    // Validate addresses
+    if (!isValidDagAddress(source)) {
+        throw new Error('Invalid source address');
+    }
+    if (!isValidDagAddress(params.destination)) {
+        throw new Error('Invalid destination address');
+    }
+    if (source === params.destination) {
+        throw new Error('Source and destination addresses cannot be the same');
+    }
+    // Convert amounts to smallest units
+    const amount = tokenToUnits(params.amount);
+    const fee = tokenToUnits(params.fee ?? 0);
+    // Validate amounts
+    if (amount < 1) {
+        throw new Error('Transfer amount must be greater than 1e-8');
+    }
+    if (fee < 0) {
+        throw new Error('Fee must be greater than or equal to zero');
+    }
+    // Use dag4.js TransactionV2 to create and encode the transaction
+    const txProps = {
+        fromAddress: source,
+        toAddress: params.destination,
+        amount,
+        fee,
+        lastTxRef: lastRef,
+    };
+    const tx = new dag4_keystore_1.TransactionV2(txProps);
+    // Get encoded transaction for hashing
+    const encodedTx = tx.getEncoded();
+    // Kryo serialize - v2 uses setReferences = false (matching dag4.js behavior)
+    const serializedTx = dag4_keystore_1.txEncode.kryoSerialize(encodedTx, false);
+    // Hash the serialized transaction
+    const hash = dag4_keystore_1.keyStore.sha256(Buffer.from(serializedTx, 'hex'));
+    // Sign the hash
+    const signature = await dag4_keystore_1.keyStore.sign(privateKey, hash);
+    // Get uncompressed public key
+    const uncompressedPublicKey = publicKey.length === 128 ? '04' + publicKey : publicKey;
+    // Verify signature
+    const success = dag4_keystore_1.keyStore.verify(uncompressedPublicKey, hash, signature);
+    if (!success) {
+        throw new Error('Sign-Verify failed');
+    }
+    // Add signature proof (remove '04' prefix from public key)
+    const proof = {
+        id: uncompressedPublicKey.substring(2),
+        signature,
+    };
+    tx.addSignature(proof);
+    return tx.getPostTransaction();
+}
+exports.createCurrencyTransaction = createCurrencyTransaction;
+/**
+ * Create multiple metagraph token transactions (batch)
+ *
+ * @param transfers - Array of transfer parameters
+ * @param privateKey - Private key to sign with
+ * @param lastRef - Reference to last accepted transaction
+ * @returns Array of signed currency transactions
+ *
+ * @throws If any address is invalid or amount is too small
+ *
+ * @example
+ * ```typescript
+ * const txns = await createCurrencyTransactionBatch(
+ *   [
+ *     { destination: 'DAG...1', amount: 10 },
+ *     { destination: 'DAG...2', amount: 20 },
+ *   ],
+ *   privateKey,
+ *   { hash: 'abc123...', ordinal: 5 }
+ * );
+ * ```
+ */
+async function createCurrencyTransactionBatch(transfers, privateKey, lastRef) {
+    const transactions = [];
+    let currentRef = { ...lastRef };
+    for (const transfer of transfers) {
+        const tx = await createCurrencyTransaction(transfer, privateKey, currentRef);
+        // Calculate hash for next transaction's parent reference
+        const hash = await hashCurrencyTransaction(tx);
+        // Update reference for next transaction
+        currentRef = {
+            hash: hash.value,
+            ordinal: currentRef.ordinal + 1,
+        };
+        transactions.push(tx);
+    }
+    return transactions;
+}
+exports.createCurrencyTransactionBatch = createCurrencyTransactionBatch;
+/**
+ * Add a signature to an existing currency transaction (for multi-sig)
+ *
+ * @param transaction - Transaction to sign
+ * @param privateKey - Private key to sign with
+ * @returns Transaction with additional signature
+ *
+ * @throws If sign-verify fails
+ *
+ * @example
+ * ```typescript
+ * const signedTx = await signCurrencyTransaction(tx, privateKey2);
+ * ```
+ */
+async function signCurrencyTransaction(transaction, privateKey) {
+    // Reconstruct TransactionV2 from PostTransaction
+    const tx = dag4_keystore_1.TransactionV2.fromPostTransaction(transaction);
+    // Restore existing proofs (fromPostTransaction doesn't copy them)
+    for (const existingProof of transaction.proofs) {
+        tx.addSignature(existingProof);
+    }
+    // Get encoded transaction
+    const encodedTx = tx.getEncoded();
+    // Kryo serialize - v2 uses setReferences = false (matching dag4.js behavior)
+    const serializedTx = dag4_keystore_1.txEncode.kryoSerialize(encodedTx, false);
+    const hash = dag4_keystore_1.keyStore.sha256(Buffer.from(serializedTx, 'hex'));
+    // Sign the hash
+    const publicKey = dag4_keystore_1.keyStore.getPublicKeyFromPrivate(privateKey);
+    const signature = await dag4_keystore_1.keyStore.sign(privateKey, hash);
+    // Verify signature
+    const uncompressedPublicKey = publicKey.length === 128 ? '04' + publicKey : publicKey;
+    const success = dag4_keystore_1.keyStore.verify(uncompressedPublicKey, hash, signature);
+    if (!success) {
+        throw new Error('Sign-Verify failed');
+    }
+    // Add new proof
+    const proof = {
+        id: uncompressedPublicKey.substring(2),
+        signature,
+    };
+    tx.addSignature(proof);
+    return tx.getPostTransaction();
+}
+exports.signCurrencyTransaction = signCurrencyTransaction;
+/**
+ * Verify all signatures on a currency transaction
+ *
+ * @param transaction - Transaction to verify
+ * @returns Verification result with valid/invalid proofs
+ *
+ * @example
+ * ```typescript
+ * const result = await verifyCurrencyTransaction(tx);
+ * console.log('Valid:', result.isValid);
+ * ```
+ */
+async function verifyCurrencyTransaction(transaction) {
+    // Reconstruct TransactionV2 to get encoded form
+    const tx = dag4_keystore_1.TransactionV2.fromPostTransaction(transaction);
+    // Get hash
+    const encodedTx = tx.getEncoded();
+    // Kryo serialize - v2 uses setReferences = false (matching dag4.js behavior)
+    const serializedTx = dag4_keystore_1.txEncode.kryoSerialize(encodedTx, false);
+    const hash = dag4_keystore_1.keyStore.sha256(Buffer.from(serializedTx, 'hex'));
+    const validProofs = [];
+    const invalidProofs = [];
+    // Verify each proof
+    for (const proof of transaction.proofs) {
+        const publicKey = '04' + proof.id; // Add back the '04' prefix
+        // Normalize signature to low-S form for BIP 62/146 compatibility
+        const normalizedSignature = (0, verify_js_1.normalizeSignatureToLowS)(proof.signature);
+        const isValid = dag4_keystore_1.keyStore.verify(publicKey, hash, normalizedSignature);
+        if (isValid) {
+            validProofs.push(proof);
+        }
+        else {
+            invalidProofs.push(proof);
+        }
+    }
+    return {
+        isValid: invalidProofs.length === 0 && validProofs.length > 0,
+        validProofs,
+        invalidProofs,
+    };
+}
+exports.verifyCurrencyTransaction = verifyCurrencyTransaction;
+/**
+ * Encode a currency transaction for hashing
+ *
+ * @param transaction - Transaction to encode
+ * @returns Hex-encoded string
+ *
+ * @example
+ * ```typescript
+ * const encoded = encodeCurrencyTransaction(tx);
+ * ```
+ */
+function encodeCurrencyTransaction(transaction) {
+    const tx = dag4_keystore_1.TransactionV2.fromPostTransaction(transaction);
+    return tx.getEncoded();
+}
+exports.encodeCurrencyTransaction = encodeCurrencyTransaction;
+/**
+ * Hash a currency transaction
+ *
+ * @param transaction - Transaction to hash
+ * @returns Hash object with value and bytes
+ *
+ * @example
+ * ```typescript
+ * const hash = await hashCurrencyTransaction(tx);
+ * console.log('Hash:', hash.value);
+ * ```
+ */
+async function hashCurrencyTransaction(transaction) {
+    const encoded = encodeCurrencyTransaction(transaction);
+    // Kryo serialize - v2 uses setReferences = false (matching dag4.js behavior)
+    const serialized = dag4_keystore_1.txEncode.kryoSerialize(encoded, false);
+    const hash = dag4_keystore_1.keyStore.sha256(Buffer.from(serialized, 'hex'));
+    return {
+        value: hash,
+        bytes: Buffer.from(hash, 'hex'),
+    };
+}
+exports.hashCurrencyTransaction = hashCurrencyTransaction;
+/**
+ * Get transaction reference from a currency transaction
+ * Useful for chaining transactions
+ *
+ * @param transaction - Transaction to extract reference from
+ * @param ordinal - Ordinal number for this transaction
+ * @returns Transaction reference
+ *
+ * @example
+ * ```typescript
+ * const ref = await getTransactionReference(tx, 6);
+ * // Use ref as lastRef for next transaction
+ * ```
+ */
+async function getTransactionReference(transaction, ordinal) {
+    const hash = await hashCurrencyTransaction(transaction);
+    return {
+        hash: hash.value,
+        ordinal,
+    };
+}
+exports.getTransactionReference = getTransactionReference;

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

@@ -0,0 +1,55 @@
+/**
+ * Currency transaction types for metagraph token transfers
+ *
+ * @packageDocumentation
+ */
+import type { Signed } from './types.js';
+/**
+ * Reference to a previous transaction for chaining
+ */
+export interface TransactionReference {
+    /** Transaction hash */
+    hash: string;
+    /** Transaction ordinal number */
+    ordinal: number;
+}
+/**
+ * Currency transaction value structure (v2)
+ * Contains the actual transaction data before signing
+ */
+export interface CurrencyTransactionValue {
+    /** Source DAG address */
+    source: string;
+    /** Destination DAG address */
+    destination: string;
+    /** Amount in smallest units (1e-8) */
+    amount: number;
+    /** Fee in smallest units (1e-8) */
+    fee: number;
+    /** Reference to parent transaction */
+    parent: TransactionReference;
+    /** Random salt for uniqueness (as string) */
+    salt: string;
+}
+/**
+ * Currency transaction structure (v2)
+ * A signed currency transaction value
+ * Used for metagraph token transfers
+ */
+export type CurrencyTransaction = Signed<CurrencyTransactionValue>;
+/**
+ * Parameters for creating a token transfer
+ */
+export interface TransferParams {
+    /** Destination DAG address */
+    destination: string;
+    /** Amount in token units (e.g., 100.5 tokens) */
+    amount: number;
+    /** Fee in token units (defaults to 0) */
+    fee?: number;
+}
+/**
+ * Token decimals constant (1e-8)
+ * Same as DAG_DECIMALS from dag4.js
+ */
+export declare const TOKEN_DECIMALS = 1e-8;

package/dist/metakit/currency-types.js

@@ -0,0 +1,13 @@
+"use strict";
+/**
+ * Currency transaction types for metagraph token transfers
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TOKEN_DECIMALS = void 0;
+/**
+ * Token decimals constant (1e-8)
+ * Same as DAG_DECIMALS from dag4.js
+ */
+exports.TOKEN_DECIMALS = 1e-8;

package/dist/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/metakit/hash.js

@@ -0,0 +1,84 @@
+"use strict";
+/**
+ * Hashing Utilities
+ *
+ * SHA-256 and SHA-512 hashing for the Constellation signature protocol.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hashData = exports.computeDigest = exports.hashBytes = exports.hash = void 0;
+const js_sha256_1 = require("js-sha256");
+const js_sha512_1 = require("js-sha512");
+const binary_js_1 = require("./binary.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
+ * ```
+ */
+function hash(data) {
+    const bytes = (0, binary_js_1.toBytes)(data, false);
+    return hashBytes(bytes);
+}
+exports.hash = hash;
+/**
+ * Compute SHA-256 hash of raw bytes
+ *
+ * @param bytes - Input bytes
+ * @returns Hash object with hex string and raw bytes
+ */
+function hashBytes(bytes) {
+    const hashArray = js_sha256_1.sha256.array(bytes);
+    const hashUint8 = new Uint8Array(hashArray);
+    const hashHex = js_sha256_1.sha256.hex(bytes);
+    return {
+        value: hashHex,
+        bytes: hashUint8,
+    };
+}
+exports.hashBytes = hashBytes;
+/**
+ * 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
+ */
+function computeDigest(data, isDataUpdate = false) {
+    // Step 1: Serialize to binary
+    const dataBytes = (0, binary_js_1.toBytes)(data, isDataUpdate);
+    // Step 2: SHA-256 hash
+    const sha256Hash = hashBytes(dataBytes);
+    // Step 3-4: Hex string as UTF-8 bytes (critical: NOT hex decode)
+    const hexAsUtf8 = new TextEncoder().encode(sha256Hash.value);
+    // Step 5: SHA-512
+    const sha512Hash = js_sha512_1.sha512.array(hexAsUtf8);
+    // Step 6: Truncate to 32 bytes
+    return new Uint8Array(sha512Hash.slice(0, 32));
+}
+exports.computeDigest = computeDigest;
+/**
+ * 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
+ */
+function hashData(data, isDataUpdate = false) {
+    const bytes = (0, binary_js_1.toBytes)(data, isDataUpdate);
+    return hashBytes(bytes);
+}
+exports.hashData = hashData;