@psavelis/enterprise-blockchain 0.1.0 → 1.1.1

package/dist/p2mr/p2mr-output.js

@@ -0,0 +1,150 @@
+/**
+ * P2MR Output Management
+ *
+ * Provides factory functions and storage patterns for P2MR outputs.
+ * Outputs are created by committing to a Merkle root and tracked
+ * in an output store for spending.
+ */
+import { randomUUID } from "node:crypto";
+import { InMemoryStore } from "../shared/store.js";
+import { MerkleTree } from "./merkle-tree.js";
+/**
+ * Create a P2MR output from spending conditions.
+ *
+ * The output stores only the Merkle root; the actual spending conditions
+ * (script leaves) are kept off-chain by the creator. This prevents
+ * quantum adversaries from harvesting public keys from unspent outputs.
+ *
+ * @param options - Output creation options.
+ * @returns The P2MR output and its Merkle tree.
+ * @throws Error if leaves array is empty or value is negative.
+ *
+ * @example
+ * ```typescript
+ * import { createP2MROutput, createSingleSigLeaf, createTimelockLeaf } from "@enterprise-blockchain/p2mr";
+ *
+ * const primaryKey = "a1b2c3..."; // SHA-256 hash of ML-DSA-65 public key
+ * const backupKey = "d4e5f6...";
+ *
+ * const { output, tree } = createP2MROutput({
+ *   leaves: [
+ *     createSingleSigLeaf(primaryKey),           // Spend path 0: primary key
+ *     createTimelockLeaf(backupKey, futureTime), // Spend path 1: backup after 1 year
+ *   ],
+ *   value: 1_000_000n,
+ * });
+ *
+ * // Store `output` on-chain (only merkleRoot exposed)
+ * // Keep `tree` off-chain for generating spend proofs
+ * ```
+ */
+export function createP2MROutput(options) {
+    const { leaves, value, outputId, createdAt, metadataHash } = options;
+    if (leaves.length === 0) {
+        throw new Error("P2MR output requires at least one spending condition");
+    }
+    if (value < BigInt(0)) {
+        throw new Error("P2MR output value must be non-negative");
+    }
+    const tree = new MerkleTree(leaves);
+    const output = {
+        outputId: outputId ?? randomUUID(),
+        merkleRoot: tree.root,
+        value,
+        createdAt: createdAt ?? Date.now(),
+    };
+    if (metadataHash) {
+        output.metadataHash = metadataHash;
+    }
+    return { output, tree };
+}
+// ---------------------------------------------------------------------------
+// P2MR Output Store
+// ---------------------------------------------------------------------------
+/**
+ * A store for P2MR outputs indexed by outputId.
+ *
+ * Provides methods for tracking unspent outputs (UTXOs).
+ */
+export class P2MROutputStore {
+    #store;
+    #spentSet;
+    /**
+     * Create a new P2MR output store.
+     *
+     * @param store - Optional backing store. Defaults to in-memory.
+     */
+    constructor(store) {
+        this.#store = store ?? new InMemoryStore();
+        this.#spentSet = new Set();
+    }
+    /**
+     * Add an output to the store.
+     *
+     * @param output - The P2MR output to store.
+     * @throws Error if output with same ID already exists.
+     */
+    add(output) {
+        const existing = this.#store.get(output.outputId);
+        if (existing) {
+            throw new Error(`Output ${output.outputId} already exists`);
+        }
+        this.#store.set(output.outputId, output);
+    }
+    /**
+     * Get an output by ID.
+     *
+     * @param outputId - The output ID.
+     * @returns The output, or undefined if not found.
+     */
+    get(outputId) {
+        return this.#store.get(outputId);
+    }
+    /**
+     * Check if an output is unspent.
+     *
+     * @param outputId - The output ID.
+     * @returns true if the output exists and has not been spent.
+     */
+    isUnspent(outputId) {
+        if (this.#spentSet.has(outputId)) {
+            return false;
+        }
+        const output = this.#store.get(outputId);
+        return output !== undefined;
+    }
+    /**
+     * Mark an output as spent.
+     *
+     * @param outputId - The output ID.
+     * @throws Error if output does not exist or is already spent.
+     */
+    markSpent(outputId) {
+        const output = this.#store.get(outputId);
+        if (!output) {
+            throw new Error(`Output ${outputId} does not exist`);
+        }
+        if (this.#spentSet.has(outputId)) {
+            throw new Error(`Output ${outputId} is already spent`);
+        }
+        this.#spentSet.add(outputId);
+    }
+    /**
+     * Get all unspent outputs.
+     *
+     * @returns Array of unspent P2MR outputs.
+     */
+    getUnspent() {
+        const all = Array.from(this.#store.values());
+        return all.filter((output) => !this.#spentSet.has(output.outputId));
+    }
+    /**
+     * Get total value of all unspent outputs.
+     *
+     * @returns Sum of all unspent output values.
+     */
+    getUnspentBalance() {
+        const unspent = this.getUnspent();
+        return unspent.reduce((sum, output) => sum + output.value, BigInt(0));
+    }
+}

package/dist/p2mr/ports.d.ts

@@ -0,0 +1,52 @@
+/**
+ * P2MR Module Ports (Hexagonal Architecture)
+ *
+ * These ports define the boundaries between the P2MR domain and infrastructure.
+ * Domain code MUST only depend on these interfaces, never on concrete implementations.
+ *
+ * @see docs/adr/ADR-0001-hexagonal-architecture.md
+ */
+/**
+ * Supported post-quantum signature algorithms.
+ */
+export type SignatureAlgorithm = "ml-dsa-65" | "ml-dsa-44" | "ml-dsa-87";
+/**
+ * Port for post-quantum signature verification.
+ *
+ * The P2MR domain requires signature verification for:
+ * - Single signature script leaves (ml-dsa-65-sig)
+ * - Timelock script leaves (signature + time condition)
+ * - Multisig script leaves (k-of-n threshold signatures)
+ * - HSM-attested signatures
+ *
+ * Implementations MUST use NIST-approved post-quantum algorithms.
+ */
+export interface SignatureVerificationPort {
+    /**
+     * Verify a post-quantum signature.
+     *
+     * @param message The message that was signed.
+     * @param signature The signature bytes.
+     * @param publicKey The signer's public key.
+     * @param algorithm The signature algorithm used.
+     * @returns True if the signature is valid, false otherwise.
+     */
+    verify(message: Uint8Array, signature: Uint8Array, publicKey: Uint8Array, algorithm: SignatureAlgorithm): boolean;
+}
+/**
+ * Port for cryptographic hashing operations.
+ *
+ * The P2MR domain uses hashing for:
+ * - Computing public key hashes for script leaves
+ * - Building Merkle trees from script leaves
+ * - Creating spend transaction digests
+ */
+export interface HashingPort {
+    /**
+     * Compute SHA-256 hash of a hex string.
+     * @param data Hex-encoded input data.
+     * @returns Hex-encoded hash.
+     */
+    sha256hex(data: string): string;
+}
+//# sourceMappingURL=ports.d.ts.map

package/dist/p2mr/ports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.d.ts","sourceRoot":"","sources":["../../src/p2mr/ports.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,WAAW,GAAG,WAAW,CAAC;AAEzE;;;;;;;;;;GAUG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;;;;;;OAQG;IACH,MAAM,CACJ,OAAO,EAAE,UAAU,EACnB,SAAS,EAAE,UAAU,EACrB,SAAS,EAAE,UAAU,EACrB,SAAS,EAAE,kBAAkB,GAC5B,OAAO,CAAC;CACZ;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;CACjC"}

package/dist/p2mr/ports.js

@@ -0,0 +1,9 @@
+/**
+ * P2MR Module Ports (Hexagonal Architecture)
+ *
+ * These ports define the boundaries between the P2MR domain and infrastructure.
+ * Domain code MUST only depend on these interfaces, never on concrete implementations.
+ *
+ * @see docs/adr/ADR-0001-hexagonal-architecture.md
+ */
+export {};

package/dist/p2mr/script-interpreter.d.ts

@@ -0,0 +1,92 @@
+/**
+ * P2MR Script Interpreter
+ *
+ * Executes spending conditions by verifying witness data against script leaves.
+ * Each leaf type has specific verification rules:
+ *
+ * - ml-dsa-65-sig: Single ML-DSA-65 signature verification
+ * - timelock: ML-DSA-65 signature + timestamp >= locktime
+ * - multisig-ml-dsa: k-of-n threshold ML-DSA-65 signatures
+ * - hsm-attested-sig: ML-DSA-65 signature + HSM attestation (placeholder)
+ *
+ * The interpreter returns a detailed audit trail for compliance.
+ */
+import type { SignatureVerificationPort, HashingPort } from "./ports.js";
+import type { ScriptLeaf, SpendWitness, ScriptVerificationResult, VerificationStep } from "./types.js";
+/**
+ * Configure the script interpreter with custom implementations.
+ * Primarily useful for testing with mock implementations.
+ *
+ * @param options Configuration options.
+ */
+export declare function configureInterpreter(options: {
+    signatureVerifier?: SignatureVerificationPort;
+    hasher?: HashingPort;
+}): void;
+/**
+ * Reset interpreter to default implementations.
+ */
+export declare function resetInterpreter(): void;
+/**
+ * Options for script interpretation.
+ */
+export interface InterpretScriptOptions {
+    /**
+     * The spending condition to verify.
+     */
+    leaf: ScriptLeaf;
+    /**
+     * Witness data (public keys, signatures, etc.).
+     */
+    witness: SpendWitness;
+    /**
+     * Message that was signed (typically a spend transaction hash).
+     */
+    message: Uint8Array;
+    /**
+     * Optional current block time for timelock verification.
+     * If not provided, uses the timestamp from the witness.
+     */
+    currentTime?: number;
+}
+/**
+ * Result of script interpretation with audit trail.
+ */
+export interface InterpretScriptResult extends ScriptVerificationResult {
+    /** Detailed audit trail of verification steps. */
+    auditTrail: VerificationStep[];
+}
+/**
+ * Interpret (execute) a P2MR script leaf against witness data.
+ *
+ * This function performs full cryptographic verification of the spending
+ * condition using ML-DSA-65 signatures.
+ *
+ * @param options - Interpretation options.
+ * @returns Verification result with audit trail.
+ *
+ * @example
+ * ```typescript
+ * const result = interpretScript({
+ *   leaf: singleSigLeaf,
+ *   witness: {
+ *     publicKeys: [myPublicKey],
+ *     signatures: [mySignature],
+ *   },
+ *   message: transactionHash,
+ * });
+ *
+ * if (result.valid) {
+ *   console.log("Spending condition satisfied");
+ * }
+ * ```
+ */
+export declare function interpretScript(options: InterpretScriptOptions): InterpretScriptResult;
+/**
+ * Compute SHA-256 hash of a public key.
+ *
+ * The public key is converted to hex, then hashed.
+ * This matches the format stored in ScriptLeaf.publicKeyHashes.
+ */
+export declare function hashPublicKey(publicKey: Uint8Array): string;
+//# sourceMappingURL=script-interpreter.d.ts.map

package/dist/p2mr/script-interpreter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"script-interpreter.d.ts","sourceRoot":"","sources":["../../src/p2mr/script-interpreter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,yBAAyB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzE,OAAO,KAAK,EACV,UAAU,EACV,YAAY,EACZ,wBAAwB,EACxB,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAMpB;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE;IAC5C,iBAAiB,CAAC,EAAE,yBAAyB,CAAC;IAC9C,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,GAAG,IAAI,CAOP;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAGvC;AAMD;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,IAAI,EAAE,UAAU,CAAC;IAEjB;;OAEG;IACH,OAAO,EAAE,YAAY,CAAC;IAEtB;;OAEG;IACH,OAAO,EAAE,UAAU,CAAC;IAEpB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAsB,SAAQ,wBAAwB;IACrE,kDAAkD;IAClD,UAAU,EAAE,gBAAgB,EAAE,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,sBAAsB,GAC9B,qBAAqB,CAiCvB;AAyhBD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,UAAU,GAAG,MAAM,CAE3D"}