@hazbase/simplicity 0.4.5 → 0.4.7

package/dist/domain/dampPset.d.ts

@@ -0,0 +1,51 @@
+import { type StrictPolicyNetwork } from "./damp";
+import { type StrictPolicyDecodedTransaction, type StrictPolicyProofBackedTransactionExpectation, type StrictPolicyProofBackedTransactionInspection } from "./dampTransaction";
+export declare const STRICT_POLICY_PSET_INSPECTION_SCHEMA: "hazbase_strict_policy_pset_inspection_v1";
+export interface StrictPolicySimplicityInputRequest {
+    inputIndex: number;
+    cmr: string;
+    genesisHash: string;
+}
+export interface StrictPolicySimplicityInputInspection extends StrictPolicySimplicityInputRequest {
+    sigAllHash: string;
+}
+export interface StrictPolicyPsetDecoderRequest {
+    psetBase64: string;
+    network: StrictPolicyNetwork;
+    simplicityInputs: StrictPolicySimplicityInputRequest[];
+}
+export type StrictPolicyPsetDecoder = (request: StrictPolicyPsetDecoderRequest) => Promise<unknown> | unknown;
+export interface StrictPolicyPsetInspection {
+    schema: typeof STRICT_POLICY_PSET_INSPECTION_SCHEMA;
+    psetVersion: 2;
+    inputCount: number;
+    outputCount: number;
+    inputSummaries: unknown[];
+    extractable: true;
+    canonicalPsetBase64: string;
+    psetHash: string;
+    canonicalPsetHash: string;
+    canonicalEncodingMatches: true;
+    unknownFieldCount: number;
+    proprietaryFieldCount: number;
+    decodedPset: Record<string, unknown>;
+    transaction: StrictPolicyDecodedTransaction;
+    simplicityInputs: StrictPolicySimplicityInputInspection[];
+}
+export interface StrictPolicyPsetSigningInspectionRequest {
+    psetBase64: string;
+    network: StrictPolicyNetwork;
+    simplicityInputs: StrictPolicySimplicityInputRequest[];
+    signingInputIndex: number;
+    serviceSighashHex?: string;
+    transactionExpectation: StrictPolicyProofBackedTransactionExpectation;
+    decodePset: StrictPolicyPsetDecoder;
+}
+export interface StrictPolicyPsetSigningInspection {
+    pset: StrictPolicyPsetInspection;
+    transaction: StrictPolicyProofBackedTransactionInspection;
+    signingInputIndex: number;
+    signingSighashHex: string;
+}
+export declare function normalizeStrictPolicyPsetInspection(value: unknown, expectedPsetBase64?: string): StrictPolicyPsetInspection;
+export declare function inspectStrictPolicyPsetForSigning(request: StrictPolicyPsetSigningInspectionRequest): Promise<StrictPolicyPsetSigningInspection>;

package/dist/domain/dampPset.js

@@ -0,0 +1,237 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STRICT_POLICY_PSET_INSPECTION_SCHEMA = void 0;
+exports.normalizeStrictPolicyPsetInspection = normalizeStrictPolicyPsetInspection;
+exports.inspectStrictPolicyPsetForSigning = inspectStrictPolicyPsetForSigning;
+const node_crypto_1 = require("node:crypto");
+const errors_1 = require("../core/errors");
+const damp_1 = require("./damp");
+const dampTransaction_1 = require("./dampTransaction");
+exports.STRICT_POLICY_PSET_INSPECTION_SCHEMA = "hazbase_strict_policy_pset_inspection_v1";
+function invalid(field, message) {
+    throw new errors_1.ValidationError(`${field} ${message}`, {
+        code: "STRICT_POLICY_PSET_INVALID",
+        field,
+    });
+}
+function recordValue(value, field) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        invalid(field, "must be an object");
+    }
+    return value;
+}
+function stringValue(value, field) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        invalid(field, "must be a non-empty string");
+    }
+    return value.trim();
+}
+function hex32(value, field) {
+    const normalized = stringValue(value, field).toLowerCase().replace(/^0x/u, "");
+    if (!/^[0-9a-f]{64}$/u.test(normalized)) {
+        invalid(field, "must be 32 bytes of hex");
+    }
+    return normalized;
+}
+function uint(value, field) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        invalid(field, "must be a non-negative safe integer");
+    }
+    return value;
+}
+function uint32(value, field) {
+    const normalized = uint(value, field);
+    if (normalized > 0xffff_ffff)
+        invalid(field, "must be a uint32");
+    return normalized;
+}
+function trueValue(value, field) {
+    if (value !== true)
+        invalid(field, "must be true");
+    return true;
+}
+function strictBase64Bytes(value, field) {
+    const normalized = stringValue(value, field);
+    if (normalized.length % 4 !== 0
+        || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u.test(normalized)) {
+        invalid(field, "must be canonical standard base64");
+    }
+    const decoded = Buffer.from(normalized, "base64");
+    if (decoded.toString("base64") !== normalized) {
+        invalid(field, "must use canonical base64 encoding");
+    }
+    return decoded;
+}
+function psetHash(value, field) {
+    return (0, node_crypto_1.createHash)("sha256").update(strictBase64Bytes(value, field)).digest("hex");
+}
+function normalizeSimplicityInputRequest(value, field) {
+    const record = recordValue(value, field);
+    return {
+        inputIndex: uint32(record.inputIndex, `${field}.inputIndex`),
+        cmr: hex32(record.cmr, `${field}.cmr`),
+        genesisHash: hex32(record.genesisHash, `${field}.genesisHash`),
+    };
+}
+function normalizeSimplicityInputInspection(value, index) {
+    const field = `inspection.simplicityInputs[${index}]`;
+    const request = normalizeSimplicityInputRequest(value, field);
+    const record = value;
+    return {
+        ...request,
+        sigAllHash: hex32(record.sigAllHash, `${field}.sigAllHash`),
+    };
+}
+function normalizeNetwork(value, field) {
+    const network = stringValue(value, field);
+    if (!("liquid-regtest liquid-testnet liquid-mainnet".split(" ")).includes(network)) {
+        invalid(field, "is unsupported");
+    }
+    return network;
+}
+function normalizeStrictPolicyPsetInspection(value, expectedPsetBase64) {
+    const record = recordValue(value, "inspection");
+    if (typeof record.error === "string" && record.error.trim()) {
+        invalid("inspection.error", `reported ${record.error.trim()}`);
+    }
+    if (record.schema !== exports.STRICT_POLICY_PSET_INSPECTION_SCHEMA) {
+        invalid("inspection.schema", `must be ${exports.STRICT_POLICY_PSET_INSPECTION_SCHEMA}`);
+    }
+    if (record.psetVersion !== 2) {
+        invalid("inspection.psetVersion", "must be PSET v2");
+    }
+    const inputCount = uint(record.inputCount, "inspection.inputCount");
+    const outputCount = uint(record.outputCount, "inspection.outputCount");
+    if (!Array.isArray(record.inputs) || record.inputs.length !== inputCount) {
+        invalid("inspection.inputs", "must describe every PSET input exactly once");
+    }
+    if (record.extractable !== true) {
+        invalid("inspection.extractable", "must be true");
+    }
+    const canonicalPsetBase64 = stringValue(record.canonicalPsetBase64, "inspection.canonicalPsetBase64");
+    const canonicalPsetHash = hex32(record.canonicalPsetHash, "inspection.canonicalPsetHash");
+    const calculatedCanonicalHash = psetHash(canonicalPsetBase64, "inspection.canonicalPsetBase64");
+    if (canonicalPsetHash !== calculatedCanonicalHash) {
+        invalid("inspection.canonicalPsetHash", "does not match canonicalPsetBase64");
+    }
+    const inspectedPsetHash = hex32(record.psetHash, "inspection.psetHash");
+    trueValue(record.canonicalEncodingMatches, "inspection.canonicalEncodingMatches");
+    if (inspectedPsetHash !== canonicalPsetHash) {
+        invalid("inspection.psetHash", "does not match the canonical PSET hash");
+    }
+    if (expectedPsetBase64 !== undefined) {
+        const expectedHash = psetHash(expectedPsetBase64, "psetBase64");
+        if (inspectedPsetHash !== expectedHash) {
+            invalid("inspection.psetHash", "does not match the requested PSET");
+        }
+    }
+    const decodedPset = recordValue(record.decodedPset, "inspection.decodedPset");
+    const transaction = (0, dampTransaction_1.normalizeStrictPolicyDecodedTransaction)(record.transaction);
+    if (transaction.inputs.length !== inputCount) {
+        invalid("inspection.transaction.inputs", "count does not match the complete PSET");
+    }
+    if (transaction.outputs.length !== outputCount) {
+        invalid("inspection.transaction.outputs", "count does not match the complete PSET");
+    }
+    if (!Array.isArray(record.simplicityInputs)) {
+        invalid("inspection.simplicityInputs", "must be an array");
+    }
+    const simplicityInputs = record.simplicityInputs.map(normalizeSimplicityInputInspection);
+    const seenInputs = new Set();
+    for (const input of simplicityInputs) {
+        if (input.inputIndex >= inputCount) {
+            invalid("inspection.simplicityInputs", "contains an out-of-range input index");
+        }
+        if (seenInputs.has(input.inputIndex)) {
+            invalid("inspection.simplicityInputs", "must not contain duplicate input indexes");
+        }
+        seenInputs.add(input.inputIndex);
+    }
+    return {
+        schema: exports.STRICT_POLICY_PSET_INSPECTION_SCHEMA,
+        psetVersion: 2,
+        inputCount,
+        outputCount,
+        inputSummaries: record.inputs,
+        extractable: true,
+        canonicalPsetBase64,
+        psetHash: inspectedPsetHash,
+        canonicalPsetHash,
+        canonicalEncodingMatches: true,
+        unknownFieldCount: uint(record.unknownFieldCount, "inspection.unknownFieldCount"),
+        proprietaryFieldCount: uint(record.proprietaryFieldCount, "inspection.proprietaryFieldCount"),
+        decodedPset,
+        transaction,
+        simplicityInputs,
+    };
+}
+async function inspectStrictPolicyPsetForSigning(request) {
+    const psetBase64 = stringValue(request.psetBase64, "psetBase64");
+    const network = normalizeNetwork(request.network, "network");
+    if (typeof request.decodePset !== "function") {
+        invalid("decodePset", "must be a local complete-PSET decoder");
+    }
+    if (!Array.isArray(request.simplicityInputs) || request.simplicityInputs.length === 0) {
+        invalid("simplicityInputs", "must not be empty");
+    }
+    const simplicityInputs = request.simplicityInputs.map((input, index) => normalizeSimplicityInputRequest(input, `simplicityInputs[${index}]`));
+    const requestedIndexes = new Set();
+    for (const input of simplicityInputs) {
+        if (requestedIndexes.has(input.inputIndex)) {
+            invalid("simplicityInputs", "must not contain duplicate input indexes");
+        }
+        requestedIndexes.add(input.inputIndex);
+    }
+    const signingInputIndex = uint32(request.signingInputIndex, "signingInputIndex");
+    if (!requestedIndexes.has(signingInputIndex)) {
+        invalid("signingInputIndex", "must identify a requested Simplicity input");
+    }
+    const snapshot = (0, damp_1.normalizeStrictPolicySnapshotPayload)(request.transactionExpectation.snapshot);
+    if (network !== snapshot.network) {
+        invalid("network", "does not match the policy snapshot");
+    }
+    for (const input of simplicityInputs) {
+        if (input.genesisHash !== snapshot.liquidGenesisHash) {
+            invalid(`simplicityInputs[${input.inputIndex}].genesisHash`, "does not match the policy snapshot");
+        }
+    }
+    const signingRequest = simplicityInputs.find((input) => input.inputIndex === signingInputIndex);
+    if (signingRequest.cmr !== request.transactionExpectation.holderProgramCmr.toLowerCase()) {
+        invalid("signingInputIndex", "does not use the expected holder covenant CMR");
+    }
+    const decoded = await request.decodePset({
+        psetBase64,
+        network,
+        simplicityInputs,
+    });
+    const pset = normalizeStrictPolicyPsetInspection(decoded, psetBase64);
+    if (pset.transaction.network !== network) {
+        invalid("inspection.transaction.network", "does not match the signing request");
+    }
+    if (pset.simplicityInputs.length !== simplicityInputs.length) {
+        invalid("inspection.simplicityInputs", "must contain every requested input exactly once");
+    }
+    for (const expected of simplicityInputs) {
+        const inspected = pset.simplicityInputs.find((candidate) => candidate.inputIndex === expected.inputIndex);
+        if (!inspected || inspected.cmr !== expected.cmr || inspected.genesisHash !== expected.genesisHash) {
+            invalid(`inspection.simplicityInputs[${expected.inputIndex}]`, "does not match the requested input, CMR, and genesis hash");
+        }
+    }
+    const transaction = await (0, dampTransaction_1.inspectStrictPolicyTransactionWithProofs)(pset.transaction, request.transactionExpectation);
+    if (!transaction.summary.strictInputIndexes.includes(signingInputIndex)) {
+        invalid("signingInputIndex", "must identify a strict-asset input");
+    }
+    const signingInspection = pset.simplicityInputs.find((input) => input.inputIndex === signingInputIndex);
+    if (request.serviceSighashHex !== undefined) {
+        const serviceHint = hex32(request.serviceSighashHex, "serviceSighashHex");
+        if (serviceHint !== signingInspection.sigAllHash) {
+            invalid("serviceSighashHex", "does not match the locally recomputed sig_all_hash");
+        }
+    }
+    return {
+        pset,
+        transaction,
+        signingInputIndex,
+        signingSighashHex: signingInspection.sigAllHash,
+    };
+}

package/dist/domain/dampTransaction.d.ts

@@ -0,0 +1,96 @@
+import { type StrictPolicyNetwork, type StrictPolicySnapshotPayload } from "./damp";
+import { type StrictPolicyWhitelistProofStep } from "./dampPolicy";
+export declare const STRICT_POLICY_TRANSACTION_SUMMARY_SCHEMA: "hazbase_strict_policy_transaction_summary_v1";
+export type StrictPolicyOperation = "purchase" | "transfer" | "redemption";
+export interface StrictPolicyTransactionOutpoint {
+    txid: string;
+    vout: number;
+}
+export interface StrictPolicyDecodedInput {
+    outpoint: StrictPolicyTransactionOutpoint;
+    assetId: string;
+    amountAtomic: string;
+    scriptHash: string;
+    hasIssuance: boolean;
+}
+export interface StrictPolicyDecodedOutput {
+    assetId: string;
+    amountAtomic: string;
+    scriptHash: string;
+    isFee: boolean;
+}
+export interface StrictPolicyDecodedTransaction {
+    network: StrictPolicyNetwork;
+    inputs: StrictPolicyDecodedInput[];
+    outputs: StrictPolicyDecodedOutput[];
+    feeAmountAtomic: string;
+}
+export interface StrictPolicyTransactionExpectation {
+    operation: StrictPolicyOperation;
+    snapshot: StrictPolicySnapshotPayload | unknown;
+    feeAssetId: string;
+    maxFeeAmountAtomic: string;
+    /** Derived locally from a verified policy proof; never trust a service hint here. */
+    allowedStrictOutputScriptHashes: string[];
+}
+export interface StrictPolicyOutputAuthorization {
+    outputIndex: number;
+    ownerXonly: string;
+    proof: StrictPolicyWhitelistProofStep[];
+}
+export interface StrictPolicyProofBackedTransactionExpectation {
+    operation: StrictPolicyOperation;
+    snapshot: StrictPolicySnapshotPayload | unknown;
+    feeAssetId: string;
+    maxFeeAmountAtomic: string;
+    holderProgramCmr: string;
+    holderNumsInternalKey: string;
+    strictOutputAuthorizations: StrictPolicyOutputAuthorization[];
+}
+export interface StrictPolicyVerifiedOutputAuthorization extends StrictPolicyOutputAuthorization {
+    derivedScriptHash: string;
+}
+export interface StrictPolicyTransactionSummary {
+    schema: typeof STRICT_POLICY_TRANSACTION_SUMMARY_SCHEMA;
+    operation: StrictPolicyOperation;
+    network: StrictPolicyNetwork;
+    snapshotHash: string;
+    transactionViewHash: string;
+    allowedStrictOutputSetHash: string;
+    verifierOutpoint: StrictPolicyTransactionOutpoint;
+    verifierAssetId: string;
+    verifierAmountAtomic: string;
+    strictAssetId: string;
+    strictInputIndexes: number[];
+    strictOutputIndexes: number[];
+    strictAmountAtomic: string;
+    feeAssetId: string;
+    feeAmountAtomic: string;
+    feeOutputIndex: number;
+    inputCount: number;
+    outputCount: number;
+}
+export interface StrictPolicyTransactionInspection {
+    transaction: StrictPolicyDecodedTransaction;
+    snapshot: StrictPolicySnapshotPayload;
+    summary: StrictPolicyTransactionSummary;
+    canonicalSummary: string;
+    summaryHash: string;
+}
+export interface StrictPolicyProofBackedTransactionInspection extends StrictPolicyTransactionInspection {
+    strictOutputAuthorizations: StrictPolicyVerifiedOutputAuthorization[];
+}
+export declare function normalizeStrictPolicyDecodedTransaction(value: StrictPolicyDecodedTransaction | unknown): StrictPolicyDecodedTransaction;
+/**
+ * Validates a complete, locally decoded transaction view. Callers must first
+ * verify the snapshot approval and must derive the allowed scripts from the
+ * snapshot's policy proof. This function does not decode a PSET or compute its
+ * Simplicity sighash.
+ */
+export declare function inspectStrictPolicyTransaction(transactionValue: StrictPolicyDecodedTransaction | unknown, expectation: StrictPolicyTransactionExpectation): StrictPolicyTransactionInspection;
+/**
+ * High-level wallet inspection. Every strict-asset output must carry a proof
+ * for its output index. The destination script is derived locally from the
+ * verified snapshot root, fixed holder CMR, NUMS key, and owner key.
+ */
+export declare function inspectStrictPolicyTransactionWithProofs(transactionValue: StrictPolicyDecodedTransaction | unknown, expectation: StrictPolicyProofBackedTransactionExpectation): Promise<StrictPolicyProofBackedTransactionInspection>;