@psavelis/enterprise-blockchain 0.1.0 → 1.1.1

package/dist/p2mr/script-leaf.js

@@ -0,0 +1,203 @@
+/**
+ * Script Leaf Creation and Validation
+ *
+ * Provides factory functions and validation for P2MR script leaves.
+ * Each leaf type has specific requirements for its parameters.
+ */
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+/**
+ * Validate a public key hash format.
+ *
+ * @param hash - Hash to validate.
+ * @returns true if the hash is 64 hex characters.
+ */
+function isValidPublicKeyHash(hash) {
+    return /^[a-f0-9]{64}$/i.test(hash);
+}
+/**
+ * Validate a script leaf for correctness.
+ *
+ * Checks:
+ * - Type is a valid ScriptLeafType
+ * - publicKeyHashes is non-empty and contains valid hashes
+ * - Condition-specific parameters are valid
+ *
+ * @param leaf - Script leaf to validate.
+ * @returns Validation result with error message if invalid.
+ */
+export function validateScriptLeaf(leaf) {
+    // Validate type
+    const validTypes = [
+        "ml-dsa-65-sig",
+        "timelock",
+        "multisig-ml-dsa",
+        "hsm-attested-sig",
+    ];
+    if (!validTypes.includes(leaf.type)) {
+        return { valid: false, error: `Invalid script leaf type: ${leaf.type}` };
+    }
+    // Validate publicKeyHashes
+    if (!Array.isArray(leaf.publicKeyHashes) ||
+        leaf.publicKeyHashes.length === 0) {
+        return { valid: false, error: "publicKeyHashes must be a non-empty array" };
+    }
+    for (let i = 0; i < leaf.publicKeyHashes.length; i++) {
+        if (!isValidPublicKeyHash(leaf.publicKeyHashes[i])) {
+            return {
+                valid: false,
+                error: `Invalid public key hash at index ${i}: must be 64 hex characters`,
+            };
+        }
+    }
+    // Type-specific validation
+    switch (leaf.type) {
+        case "ml-dsa-65-sig":
+            // Single signature requires exactly one public key hash
+            if (leaf.publicKeyHashes.length !== 1) {
+                return {
+                    valid: false,
+                    error: "ml-dsa-65-sig requires exactly one public key hash",
+                };
+            }
+            break;
+        case "timelock":
+            // Timelock requires exactly one public key hash and a locktime
+            if (leaf.publicKeyHashes.length !== 1) {
+                return {
+                    valid: false,
+                    error: "timelock requires exactly one public key hash",
+                };
+            }
+            if (typeof leaf.locktime !== "number" || leaf.locktime < 0) {
+                return {
+                    valid: false,
+                    error: "timelock requires a non-negative locktime",
+                };
+            }
+            break;
+        case "multisig-ml-dsa": {
+            // Multisig requires at least 2 public key hashes and valid threshold
+            if (leaf.publicKeyHashes.length < 2) {
+                return {
+                    valid: false,
+                    error: "multisig-ml-dsa requires at least 2 public key hashes",
+                };
+            }
+            const threshold = leaf.threshold ?? leaf.publicKeyHashes.length;
+            if (threshold < 1 || threshold > leaf.publicKeyHashes.length) {
+                return {
+                    valid: false,
+                    error: `threshold must be between 1 and ${leaf.publicKeyHashes.length}`,
+                };
+            }
+            break;
+        }
+        case "hsm-attested-sig":
+            // HSM-attested requires exactly one public key hash and an HSM slot ID
+            if (leaf.publicKeyHashes.length !== 1) {
+                return {
+                    valid: false,
+                    error: "hsm-attested-sig requires exactly one public key hash",
+                };
+            }
+            if (typeof leaf.hsmSlotId !== "string" || leaf.hsmSlotId.length === 0) {
+                return {
+                    valid: false,
+                    error: "hsm-attested-sig requires a non-empty hsmSlotId",
+                };
+            }
+            break;
+    }
+    return { valid: true };
+}
+// ---------------------------------------------------------------------------
+// Factory Functions
+// ---------------------------------------------------------------------------
+/**
+ * Create a simple ML-DSA-65 signature leaf.
+ *
+ * Requires a single valid signature from the specified public key.
+ *
+ * @param publicKeyHash - SHA-256 hash of the authorized ML-DSA-65 public key.
+ * @returns A validated ScriptLeaf.
+ * @throws Error if the hash is invalid.
+ */
+export function createSingleSigLeaf(publicKeyHash) {
+    const leaf = {
+        type: "ml-dsa-65-sig",
+        publicKeyHashes: [publicKeyHash],
+    };
+    const result = validateScriptLeaf(leaf);
+    if (!result.valid) {
+        throw new Error(result.error);
+    }
+    return leaf;
+}
+/**
+ * Create a time-locked signature leaf.
+ *
+ * Requires a valid signature from the specified public key, but only after
+ * the locktime has passed.
+ *
+ * @param publicKeyHash - SHA-256 hash of the authorized ML-DSA-65 public key.
+ * @param locktime - Unix timestamp (ms) after which spending is allowed.
+ * @returns A validated ScriptLeaf.
+ * @throws Error if parameters are invalid.
+ */
+export function createTimelockLeaf(publicKeyHash, locktime) {
+    const leaf = {
+        type: "timelock",
+        publicKeyHashes: [publicKeyHash],
+        locktime,
+    };
+    const result = validateScriptLeaf(leaf);
+    if (!result.valid) {
+        throw new Error(result.error);
+    }
+    return leaf;
+}
+/**
+ * Create a multisig leaf requiring k-of-n signatures.
+ *
+ * @param publicKeyHashes - SHA-256 hashes of all authorized ML-DSA-65 public keys.
+ * @param threshold - Minimum number of valid signatures required.
+ * @returns A validated ScriptLeaf.
+ * @throws Error if parameters are invalid.
+ */
+export function createMultisigLeaf(publicKeyHashes, threshold) {
+    const leaf = {
+        type: "multisig-ml-dsa",
+        publicKeyHashes: [...publicKeyHashes],
+        threshold,
+    };
+    const result = validateScriptLeaf(leaf);
+    if (!result.valid) {
+        throw new Error(result.error);
+    }
+    return leaf;
+}
+/**
+ * Create an HSM-attested signature leaf.
+ *
+ * Requires a valid signature from the specified public key, plus attestation
+ * proof that the signature was produced by the specified HSM slot.
+ *
+ * @param publicKeyHash - SHA-256 hash of the authorized ML-DSA-65 public key.
+ * @param hsmSlotId - Identifier of the required HSM slot.
+ * @returns A validated ScriptLeaf.
+ * @throws Error if parameters are invalid.
+ */
+export function createHsmAttestedLeaf(publicKeyHash, hsmSlotId) {
+    const leaf = {
+        type: "hsm-attested-sig",
+        publicKeyHashes: [publicKeyHash],
+        hsmSlotId,
+    };
+    const result = validateScriptLeaf(leaf);
+    if (!result.valid) {
+        throw new Error(result.error);
+    }
+    return leaf;
+}

package/dist/p2mr/spend-proof.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Spend Proof Construction and Validation
+ *
+ * Provides functions for building and validating spend proofs.
+ * A spend proof demonstrates that:
+ * 1. The revealed leaf hashes to the output's Merkle root
+ * 2. The witness satisfies the leaf's spending condition
+ */
+import type { P2MROutput, SpendProof, SpendWitness, SpendVerificationResult } from "./types.js";
+import { MerkleTree } from "./merkle-tree.js";
+/**
+ * Options for building a spend proof.
+ */
+export interface BuildSpendProofOptions {
+    /**
+     * ID of the output being spent.
+     */
+    outputId: string;
+    /**
+     * The Merkle tree containing the spending conditions.
+     * This must be the same tree used to create the output.
+     */
+    tree: MerkleTree;
+    /**
+     * Index of the leaf (spending condition) to use.
+     */
+    leafIndex: number;
+    /**
+     * Witness data satisfying the spending condition.
+     */
+    witness: SpendWitness;
+}
+/**
+ * Build a spend proof for a P2MR output.
+ *
+ * The proof consists of:
+ * 1. The output ID being spent
+ * 2. The revealed script leaf (spending condition)
+ * 3. A Merkle proof from the leaf to the root
+ * 4. Witness data (public keys, signatures, etc.)
+ *
+ * @param options - Spend proof options.
+ * @returns A complete spend proof.
+ * @throws Error if leaf index is out of bounds.
+ *
+ * @example
+ * ```typescript
+ * const proof = buildSpendProof({
+ *   outputId: output.outputId,
+ *   tree: merkleTree,
+ *   leafIndex: 0,
+ *   witness: {
+ *     publicKeys: [myPublicKey],
+ *     signatures: [mySignature],
+ *   },
+ * });
+ * ```
+ */
+export declare function buildSpendProof(options: BuildSpendProofOptions): SpendProof;
+/**
+ * Validate the structural correctness of a spend proof.
+ *
+ * This performs preliminary checks that don't require cryptographic
+ * signature verification. Full validation requires the script interpreter.
+ *
+ * Checks:
+ * 1. Output ID is present
+ * 2. Revealed leaf passes structural validation
+ * 3. Merkle proof is structurally valid
+ * 4. Witness has required fields for the leaf type
+ *
+ * @param proof - The spend proof to validate.
+ * @returns Validation result with error if invalid.
+ */
+export declare function validateSpendProofStructure(proof: SpendProof): SpendVerificationResult;
+/**
+ * Verify that a spend proof's Merkle path leads to the expected root.
+ *
+ * @param proof - The spend proof.
+ * @param expectedRoot - The Merkle root from the P2MR output.
+ * @returns Verification result.
+ */
+export declare function verifyMerkleProof(proof: SpendProof, expectedRoot: string): SpendVerificationResult;
+/**
+ * Perform full structural and Merkle verification of a spend proof.
+ *
+ * This does NOT verify signatures - that requires the script interpreter
+ * which is implemented separately.
+ *
+ * @param proof - The spend proof.
+ * @param output - The P2MR output being spent.
+ * @returns Verification result.
+ */
+export declare function verifySpendProofStructure(proof: SpendProof, output: P2MROutput): SpendVerificationResult;
+//# sourceMappingURL=spend-proof.d.ts.map

package/dist/p2mr/spend-proof.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spend-proof.d.ts","sourceRoot":"","sources":["../../src/p2mr/spend-proof.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,UAAU,EAEV,UAAU,EACV,YAAY,EAEZ,uBAAuB,EAExB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,UAAU,EAAkB,MAAM,kBAAkB,CAAC;AAO9D;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,IAAI,EAAE,UAAU,CAAC;IAEjB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,OAAO,EAAE,YAAY,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,UAAU,CAmB3E;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,UAAU,GAChB,uBAAuB,CA0GzB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,UAAU,EACjB,YAAY,EAAE,MAAM,GACnB,uBAAuB,CA0CzB;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,UAAU,GACjB,uBAAuB,CAiDzB"}

package/dist/p2mr/spend-proof.js

@@ -0,0 +1,358 @@
+/**
+ * Spend Proof Construction and Validation
+ *
+ * Provides functions for building and validating spend proofs.
+ * A spend proof demonstrates that:
+ * 1. The revealed leaf hashes to the output's Merkle root
+ * 2. The witness satisfies the leaf's spending condition
+ */
+import { MerkleTree, hashScriptLeaf } from "./merkle-tree.js";
+import { validateScriptLeaf } from "./script-leaf.js";
+/**
+ * Build a spend proof for a P2MR output.
+ *
+ * The proof consists of:
+ * 1. The output ID being spent
+ * 2. The revealed script leaf (spending condition)
+ * 3. A Merkle proof from the leaf to the root
+ * 4. Witness data (public keys, signatures, etc.)
+ *
+ * @param options - Spend proof options.
+ * @returns A complete spend proof.
+ * @throws Error if leaf index is out of bounds.
+ *
+ * @example
+ * ```typescript
+ * const proof = buildSpendProof({
+ *   outputId: output.outputId,
+ *   tree: merkleTree,
+ *   leafIndex: 0,
+ *   witness: {
+ *     publicKeys: [myPublicKey],
+ *     signatures: [mySignature],
+ *   },
+ * });
+ * ```
+ */
+export function buildSpendProof(options) {
+    const { outputId, tree, leafIndex, witness } = options;
+    const leaves = tree.leaves;
+    if (leafIndex < 0 || leafIndex >= leaves.length) {
+        throw new Error(`Leaf index ${leafIndex} out of bounds [0, ${leaves.length - 1}]`);
+    }
+    const revealedLeaf = leaves[leafIndex];
+    const merkleProof = tree.getProof(leafIndex);
+    return {
+        outputId,
+        revealedLeaf,
+        merkleProof,
+        witness,
+    };
+}
+// ---------------------------------------------------------------------------
+// Spend Proof Validation (Structural)
+// ---------------------------------------------------------------------------
+/**
+ * Validate the structural correctness of a spend proof.
+ *
+ * This performs preliminary checks that don't require cryptographic
+ * signature verification. Full validation requires the script interpreter.
+ *
+ * Checks:
+ * 1. Output ID is present
+ * 2. Revealed leaf passes structural validation
+ * 3. Merkle proof is structurally valid
+ * 4. Witness has required fields for the leaf type
+ *
+ * @param proof - The spend proof to validate.
+ * @returns Validation result with error if invalid.
+ */
+export function validateSpendProofStructure(proof) {
+    const auditTrail = [];
+    // Step 1: Validate output ID
+    if (!proof.outputId || proof.outputId.length === 0) {
+        auditTrail.push({
+            step: "Output ID check",
+            passed: false,
+            detail: "Output ID is required",
+        });
+        return {
+            valid: false,
+            reason: "Missing output ID",
+            auditTrail,
+        };
+    }
+    auditTrail.push({
+        step: "Output ID check",
+        passed: true,
+        detail: `Output ID: ${proof.outputId}`,
+    });
+    // Step 2: Validate revealed leaf structure
+    const leafResult = validateScriptLeaf(proof.revealedLeaf);
+    if (!leafResult.valid) {
+        const errorMsg = leafResult.error ?? "Unknown validation error";
+        auditTrail.push({
+            step: "Leaf structure check",
+            passed: false,
+            detail: errorMsg,
+        });
+        return {
+            valid: false,
+            reason: `Invalid leaf: ${errorMsg}`,
+            auditTrail,
+        };
+    }
+    auditTrail.push({
+        step: "Leaf structure check",
+        passed: true,
+        detail: `Type: ${proof.revealedLeaf.type}`,
+    });
+    // Step 3: Validate Merkle proof structure
+    if (!Array.isArray(proof.merkleProof)) {
+        auditTrail.push({
+            step: "Merkle proof structure",
+            passed: false,
+            detail: "Merkle proof must be an array",
+        });
+        return {
+            valid: false,
+            reason: "Invalid Merkle proof structure",
+            auditTrail,
+        };
+    }
+    for (let i = 0; i < proof.merkleProof.length; i++) {
+        const node = proof.merkleProof[i];
+        if (!isValidMerkleProofNode(node)) {
+            auditTrail.push({
+                step: `Merkle proof node ${i}`,
+                passed: false,
+                detail: "Invalid node structure",
+            });
+            return {
+                valid: false,
+                reason: `Invalid Merkle proof node at index ${i}`,
+                auditTrail,
+            };
+        }
+    }
+    auditTrail.push({
+        step: "Merkle proof structure",
+        passed: true,
+        detail: `Proof length: ${proof.merkleProof.length}`,
+    });
+    // Step 4: Validate witness structure for leaf type
+    const witnessResult = validateWitnessStructure(proof.revealedLeaf, proof.witness);
+    if (!witnessResult.valid) {
+        auditTrail.push({
+            step: "Witness structure check",
+            passed: false,
+            detail: witnessResult.reason,
+        });
+        return {
+            valid: false,
+            reason: witnessResult.reason,
+            auditTrail,
+        };
+    }
+    auditTrail.push({
+        step: "Witness structure check",
+        passed: true,
+        detail: `${proof.witness.publicKeys.length} keys, ${proof.witness.signatures.length} signatures`,
+    });
+    return {
+        valid: true,
+        reason: "Spend proof structure is valid",
+        auditTrail,
+    };
+}
+/**
+ * Verify that a spend proof's Merkle path leads to the expected root.
+ *
+ * @param proof - The spend proof.
+ * @param expectedRoot - The Merkle root from the P2MR output.
+ * @returns Verification result.
+ */
+export function verifyMerkleProof(proof, expectedRoot) {
+    const auditTrail = [];
+    // Compute leaf hash
+    const leafHash = hashScriptLeaf(proof.revealedLeaf);
+    auditTrail.push({
+        step: "Compute leaf hash",
+        passed: true,
+        detail: `Hash: ${leafHash.substring(0, 16)}...`,
+    });
+    // Verify Merkle path
+    const verified = MerkleTree.verify(proof.revealedLeaf, proof.merkleProof, expectedRoot);
+    if (!verified) {
+        auditTrail.push({
+            step: "Merkle path verification",
+            passed: false,
+            detail: `Expected root: ${expectedRoot.substring(0, 16)}...`,
+        });
+        return {
+            valid: false,
+            reason: "Merkle proof does not verify to expected root",
+            auditTrail,
+        };
+    }
+    auditTrail.push({
+        step: "Merkle path verification",
+        passed: true,
+        detail: `Root: ${expectedRoot.substring(0, 16)}...`,
+    });
+    return {
+        valid: true,
+        reason: "Merkle proof verified successfully",
+        auditTrail,
+    };
+}
+/**
+ * Perform full structural and Merkle verification of a spend proof.
+ *
+ * This does NOT verify signatures - that requires the script interpreter
+ * which is implemented separately.
+ *
+ * @param proof - The spend proof.
+ * @param output - The P2MR output being spent.
+ * @returns Verification result.
+ */
+export function verifySpendProofStructure(proof, output) {
+    const auditTrail = [];
+    // Step 1: Verify output ID matches
+    if (proof.outputId !== output.outputId) {
+        auditTrail.push({
+            step: "Output ID match",
+            passed: false,
+            detail: `Proof: ${proof.outputId}, Output: ${output.outputId}`,
+        });
+        return {
+            valid: false,
+            reason: "Spend proof output ID does not match output",
+            auditTrail,
+        };
+    }
+    auditTrail.push({
+        step: "Output ID match",
+        passed: true,
+        detail: output.outputId,
+    });
+    // Step 2: Validate proof structure
+    const structureResult = validateSpendProofStructure(proof);
+    auditTrail.push(...(structureResult.auditTrail ?? []));
+    if (!structureResult.valid) {
+        return {
+            valid: false,
+            reason: structureResult.reason,
+            auditTrail,
+        };
+    }
+    // Step 3: Verify Merkle proof
+    const merkleResult = verifyMerkleProof(proof, output.merkleRoot);
+    auditTrail.push(...(merkleResult.auditTrail ?? []));
+    if (!merkleResult.valid) {
+        return {
+            valid: false,
+            reason: merkleResult.reason,
+            auditTrail,
+        };
+    }
+    return {
+        valid: true,
+        reason: "Spend proof structure and Merkle path verified",
+        auditTrail,
+    };
+}
+// ---------------------------------------------------------------------------
+// Helper Functions
+// ---------------------------------------------------------------------------
+/**
+ * Check if a value is a valid MerkleProofNode.
+ */
+function isValidMerkleProofNode(node) {
+    if (typeof node !== "object" || node === null) {
+        return false;
+    }
+    const n = node;
+    if (typeof n.hash !== "string" || !/^[a-f0-9]{64}$/i.test(n.hash)) {
+        return false;
+    }
+    if (n.position !== "left" && n.position !== "right") {
+        return false;
+    }
+    return true;
+}
+/**
+ * Validate witness structure for a given leaf type.
+ */
+function validateWitnessStructure(leaf, witness) {
+    // Check basic witness requirements
+    if (!Array.isArray(witness.publicKeys) || witness.publicKeys.length === 0) {
+        return {
+            valid: false,
+            reason: "Witness must include at least one public key",
+        };
+    }
+    if (!Array.isArray(witness.signatures) || witness.signatures.length === 0) {
+        return {
+            valid: false,
+            reason: "Witness must include at least one signature",
+        };
+    }
+    // Type-specific validation
+    switch (leaf.type) {
+        case "ml-dsa-65-sig":
+            if (witness.publicKeys.length !== 1 || witness.signatures.length !== 1) {
+                return {
+                    valid: false,
+                    reason: "ml-dsa-65-sig requires exactly 1 public key and 1 signature",
+                };
+            }
+            break;
+        case "timelock":
+            if (witness.publicKeys.length !== 1 || witness.signatures.length !== 1) {
+                return {
+                    valid: false,
+                    reason: "timelock requires exactly 1 public key and 1 signature",
+                };
+            }
+            if (typeof witness.timestamp !== "number") {
+                return {
+                    valid: false,
+                    reason: "timelock requires a timestamp in the witness",
+                };
+            }
+            break;
+        case "multisig-ml-dsa": {
+            const threshold = leaf.threshold ?? leaf.publicKeyHashes.length;
+            if (witness.signatures.length < threshold) {
+                return {
+                    valid: false,
+                    reason: `multisig-ml-dsa requires at least ${threshold} signatures`,
+                };
+            }
+            if (witness.publicKeys.length < threshold) {
+                return {
+                    valid: false,
+                    reason: `multisig-ml-dsa requires at least ${threshold} public keys`,
+                };
+            }
+            break;
+        }
+        case "hsm-attested-sig":
+            if (witness.publicKeys.length !== 1 || witness.signatures.length !== 1) {
+                return {
+                    valid: false,
+                    reason: "hsm-attested-sig requires exactly 1 public key and 1 signature",
+                };
+            }
+            if (typeof witness.hsmAttestation !== "string" ||
+                witness.hsmAttestation.length === 0) {
+                return {
+                    valid: false,
+                    reason: "hsm-attested-sig requires HSM attestation in the witness",
+                };
+            }
+            break;
+    }
+    return { valid: true, reason: "Witness structure valid" };
+}