@hazbase/simplicity 0.4.4 → 0.4.6

package/README.md

@@ -184,6 +184,16 @@ custom RWA asset, policy position, vault output, expiry, and summary hash into
 the `X-PAYMENT` payload, and rejects proposals that still require holder-side
 Simplicity witness construction.
 
+Services can prepare that policy-spend proposal with
+`sdk.policies.inspectTransfer(...)` or `sdk.policies.executeTransfer(...)`.
+When the current policy state carries a custom Liquid asset id, the policy
+executor automatically uses the SDK multi-asset PSET path instead of the legacy
+L-BTC-only spend path. Pass `extraInputs` for the L-BTC fee/sponsor inputs and
+`contractInput` when the policy position UTXO should be selected by outpoint,
+asset id, amount, blinding data, or sequence. If the policy UTXO amount is not
+fully transferred, pass an explicit `changeAddress`; exact-position redemptions
+do not need one.
+
 Typical entrypoints:
 - `sdk.rwaDvp.definePurchase(...)`
 - `sdk.rwaDvp.buildPaymentRequirements(...)`
@@ -232,6 +242,13 @@ These helpers model a Liquidex-style exchange:
 - the resulting `X-PAYMENT` payload commits to both the payment output and the
   delivery output through a summary hash
 
+When the delivered RWA output must go to a policy/Simplicity address instead of
+the taker's normal wallet receive address, pass `takerDeliveryAddress` (or the
+`deliveryAddress` alias) to `prepareLiquidAtomicDvpLwkWasmTakerPayment(...)`.
+The loaded LWK module must expose a recipient-aware `liquidexTake` variant; if
+it does not, the SDK fails explicitly instead of silently creating a PSET that
+delivers to the wrong address.
+
 The LWK convenience helpers dynamically load `lwk_node` or `lwk_wasm` from the
 consuming application. Install one of them in the application that prepares or
 takes proposals:

package/dist/core/executor.js

@@ -429,7 +429,7 @@ async function findContractUtxos(config, artifact) {
     return scanUtxosByAddress(config, artifact.compiled.contractAddress);
 }
 function findRequestedContractUtxo(utxos, input) {
-    if (!input)
+    if (!input?.txid)
         return null;
     const requested = utxos.find((utxo) => (utxo.txid === input.txid
         && (input.vout === undefined || utxo.vout === input.vout))) ?? null;
@@ -441,6 +441,28 @@ function findRequestedContractUtxo(utxos, input) {
         sat: input.amountSat ?? requested.sat,
     };
 }
+function filterContractUtxosByRequestedAsset(utxos, input) {
+    if (!input)
+        return utxos;
+    return utxos.filter((utxo) => {
+        const matchesRequestedOutpoint = Boolean(input.txid
+            && utxo.txid === input.txid
+            && (input.vout === undefined || utxo.vout === input.vout));
+        if (input.txid && utxo.txid !== input.txid)
+            return false;
+        if (input.vout !== undefined && utxo.vout !== input.vout)
+            return false;
+        if (input.asset) {
+            if (!utxo.asset)
+                return matchesRequestedOutpoint;
+            if (normalizeAssetId(utxo.asset) !== normalizeAssetId(input.asset))
+                return false;
+        }
+        if (input.amountSat !== undefined && utxo.sat !== input.amountSat)
+            return false;
+        return true;
+    });
+}
 function buildMultiAssetBlindingSecrets(input) {
     const secrets = [];
     if (input.contractInput?.rawTxHex && input.contractInput.blindingPrivateKey) {
@@ -472,9 +494,15 @@ async function buildMultiAssetExecutionState(config, artifact, input) {
     const contractUtxos = await scanUtxosByAddress(config, artifact.compiled.contractAddress);
     const feeSat = input.feeSat ?? config.defaults?.feeSat ?? DEFAULT_FEE_SAT;
     const requested = findRequestedContractUtxo(contractUtxos, input.contractInput);
-    const contractUtxo = requested ?? chooseUtxo(contractUtxos, 1, config.defaults?.utxoPolicy ?? "smallest_over");
+    const candidateContractUtxos = filterContractUtxosByRequestedAsset(contractUtxos, input.contractInput);
+    const contractUtxo = requested ?? chooseUtxo(candidateContractUtxos, 1, config.defaults?.utxoPolicy ?? "smallest_over");
     if (!contractUtxo) {
-        throw new errors_1.UtxoNotFoundError(`No contract UTXO found for address=${artifact.compiled.contractAddress}`);
+        throw new errors_1.UtxoNotFoundError(`No contract UTXO found for address=${artifact.compiled.contractAddress}`, {
+            requestedAsset: input.contractInput?.asset,
+            requestedAmountSat: input.contractInput?.amountSat,
+            requestedTxid: input.contractInput?.txid,
+            requestedVout: input.contractInput?.vout,
+        });
     }
     const extraInputs = input.extraInputs ?? [];
     const inputTotals = new Map();
@@ -521,7 +549,7 @@ async function buildMultiAssetExecutionState(config, artifact, input) {
         {
             txid: contractUtxo.txid,
             vout: contractUtxo.vout,
-            sequence: input.locktimeHeight ? DEFAULT_SEQUENCE : DEFAULT_SEQUENCE,
+            sequence: input.contractInput?.sequence ?? DEFAULT_SEQUENCE,
         },
         ...extraInputs.map((extra) => ({
             txid: extra.txid,

package/dist/core/types.d.ts

@@ -332,10 +332,11 @@ export interface MultiAssetContractCallInput {
     signer: SignerConfig;
     witness?: WitnessConfig;
     contractInput?: {
-        txid: string;
+        txid?: string;
         vout?: number;
         asset?: string;
         amountSat?: number;
+        sequence?: number;
         rawTxHex?: string;
         blindingPrivateKey?: string;
     };

package/dist/domain/policies.d.ts

@@ -1,5 +1,5 @@
 import type { SimplicityClient } from "../client/SimplicityClient";
-import type { BondOutputBindingMode, OutputRawFields, PolicyOutputAmountForm, PolicyOutputAssetForm, PolicyEvidenceBundle, PolicyEvidenceBundleSchemaVersion, PolicyOutputBindingReasonCode, PolicyOutputBindingSupportedForm, PolicyOutputDescriptor, PolicyOutputNonceForm, PolicyReceiver, PolicyOutputRangeProofForm, PolicyState, PolicyTemplateDocument, PolicyTemplateManifest, PolicyTemplateManifestValidationResult, PolicyTemplateManifestVersion, PolicyTemplateInput, PolicyTransferDescriptor, PolicyVerificationReportSchemaVersion, PropagationMode, SimplicityArtifact } from "../core/types";
+import type { BondOutputBindingMode, OutputRawFields, PolicyOutputAmountForm, PolicyOutputAssetForm, PolicyEvidenceBundle, PolicyEvidenceBundleSchemaVersion, PolicyOutputBindingReasonCode, PolicyOutputBindingSupportedForm, PolicyOutputDescriptor, PolicyOutputNonceForm, PolicyReceiver, PolicyOutputRangeProofForm, PolicyState, PolicyTemplateDocument, PolicyTemplateManifest, PolicyTemplateManifestValidationResult, PolicyTemplateManifestVersion, PolicyTemplateInput, PolicyTransferDescriptor, PolicyVerificationReportSchemaVersion, PropagationMode, MultiAssetContractCallInput, MultiAssetContractInput, SimplicityArtifact } from "../core/types";
 export declare const POLICY_TEMPLATE_MANIFEST_SCHEMA_VERSION: PolicyTemplateManifestVersion;
 export declare const POLICY_VERIFICATION_REPORT_SCHEMA_VERSION: PolicyVerificationReportSchemaVersion;
 export declare const POLICY_EVIDENCE_BUNDLE_SCHEMA_VERSION: PolicyEvidenceBundleSchemaVersion;
@@ -576,6 +576,10 @@ export declare function executeDirectTransfer(sdk: SimplicityClient, input: {
     broadcast?: boolean;
     feeSat?: number;
     utxoPolicy?: "smallest_over" | "largest" | "newest";
+    contractInput?: MultiAssetContractCallInput["contractInput"];
+    extraInputs?: MultiAssetContractInput[];
+    changeAddress?: string;
+    useMultiAssetExecutor?: boolean;
 }): Promise<{
     mode: "direct-hop";
     prepared: {
@@ -912,6 +916,10 @@ export declare function executeTransfer(sdk: SimplicityClient, input: {
     broadcast?: boolean;
     feeSat?: number;
     utxoPolicy?: "smallest_over" | "largest" | "newest";
+    contractInput?: MultiAssetContractCallInput["contractInput"];
+    extraInputs?: MultiAssetContractInput[];
+    changeAddress?: string;
+    useMultiAssetExecutor?: boolean;
 }): Promise<{
     mode: "plain-exit";
     prepared: {

package/dist/domain/policies.js

@@ -33,6 +33,7 @@ const node_fs_1 = require("node:fs");
 const node_path_1 = __importDefault(require("node:path"));
 const summary_1 = require("../core/summary");
 const errors_1 = require("../core/errors");
+const executor_1 = require("../core/executor");
 const outputBinding_1 = require("../core/outputBinding");
 const reporting_1 = require("../core/reporting");
 function resolvePolicyDocsAsset(filename) {
@@ -602,6 +603,53 @@ function buildPolicyRecursiveWitness(prepared) {
         },
     };
 }
+function isBitcoinPolicyAsset(assetId) {
+    return assetId.trim().toLowerCase() === "bitcoin";
+}
+function shouldUseMultiAssetPolicyExecutor(assetId, input) {
+    if (input.useMultiAssetExecutor === true)
+        return true;
+    if (!isBitcoinPolicyAsset(assetId))
+        return true;
+    if (input.contractInput?.asset)
+        return true;
+    if ((input.extraInputs?.length ?? 0) > 0)
+        return true;
+    return Boolean(input.changeAddress);
+}
+function buildPolicyMultiAssetCallInput(input) {
+    const contractAmountSat = input.contractInput?.amountSat ?? input.currentState.amountSat;
+    if (contractAmountSat !== input.outputAmountSat && !input.changeAddress) {
+        throw new errors_1.ValidationError("changeAddress is required when policy contract input amount differs from the transfer output amount", {
+            contractAmountSat,
+            outputAmountSat: input.outputAmountSat,
+            assetId: input.currentState.assetId,
+        });
+    }
+    return {
+        wallet: input.wallet,
+        signer: input.signer,
+        contractInput: {
+            ...(input.contractInput ?? {}),
+            asset: input.contractInput?.asset ?? input.currentState.assetId,
+            amountSat: contractAmountSat,
+            sequence: input.contractInput?.sequence ?? input.contractSequence,
+        },
+        ...(input.extraInputs ? { extraInputs: input.extraInputs } : {}),
+        outputs: [
+            {
+                address: input.outputAddress,
+                asset: input.currentState.assetId,
+                amountSat: input.outputAmountSat,
+            },
+        ],
+        feeSat: input.feeSat,
+        ...(input.changeAddress ? { changeAddress: input.changeAddress } : {}),
+        purpose: input.purpose,
+        ...(input.broadcast !== undefined ? { broadcast: input.broadcast } : {}),
+        witness: input.witness,
+    };
+}
 function camelToUpperSnake(value) {
     return value
         .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
@@ -1396,6 +1444,24 @@ async function inspectDirectTransfer(sdk, input) {
         });
     }
     const currentContract = sdk.fromArtifact(currentArtifact);
+    const currentState = prepared.current.stateValue;
+    const directWitness = buildPolicyDirectWitness(prepared);
+    if (shouldUseMultiAssetPolicyExecutor(currentState.assetId, input)) {
+        const inspect = await (0, executor_1.inspectMultiAssetContractCall)(sdk.config, currentArtifact, buildPolicyMultiAssetCallInput({
+            ...input,
+            currentState,
+            outputAddress: prepared.nextCompiled.contractAddress,
+            outputAmountSat: input.nextAmountSat,
+            contractSequence: resolvePolicySequence(currentState),
+            witness: directWitness,
+            purpose: "sdk_policy_direct_transfer",
+        }));
+        return {
+            mode: "direct-hop",
+            prepared,
+            inspect,
+        };
+    }
     const inspect = await currentContract.inspectCall({
         wallet: input.wallet,
         toAddress: prepared.nextCompiled.contractAddress,
@@ -1403,8 +1469,8 @@ async function inspectDirectTransfer(sdk, input) {
         sendAmount: satToBtcAmount(input.nextAmountSat),
         feeSat: input.feeSat,
         utxoPolicy: input.utxoPolicy,
-        sequence: resolvePolicySequence(prepared.current.stateValue),
-        witness: buildPolicyDirectWitness(prepared),
+        sequence: resolvePolicySequence(currentState),
+        witness: directWitness,
     });
     return {
         mode: "direct-hop",
@@ -1422,6 +1488,24 @@ async function executeDirectTransfer(sdk, input) {
         });
     }
     const currentContract = sdk.fromArtifact(currentArtifact);
+    const currentState = prepared.current.stateValue;
+    const directWitness = buildPolicyDirectWitness(prepared);
+    if (shouldUseMultiAssetPolicyExecutor(currentState.assetId, input)) {
+        const execution = await (0, executor_1.executeMultiAssetContractCall)(sdk.config, currentArtifact, buildPolicyMultiAssetCallInput({
+            ...input,
+            currentState,
+            outputAddress: prepared.nextCompiled.contractAddress,
+            outputAmountSat: input.nextAmountSat,
+            contractSequence: resolvePolicySequence(currentState),
+            witness: directWitness,
+            purpose: "sdk_policy_direct_transfer",
+        }));
+        return {
+            mode: "direct-hop",
+            prepared,
+            execution,
+        };
+    }
     const execution = await currentContract.execute({
         wallet: input.wallet,
         toAddress: prepared.nextCompiled.contractAddress,
@@ -1430,8 +1514,8 @@ async function executeDirectTransfer(sdk, input) {
         feeSat: input.feeSat,
         broadcast: input.broadcast,
         utxoPolicy: input.utxoPolicy,
-        sequence: resolvePolicySequence(prepared.current.stateValue),
-        witness: buildPolicyDirectWitness(prepared),
+        sequence: resolvePolicySequence(currentState),
+        witness: directWitness,
     });
     return {
         mode: "direct-hop",
@@ -1500,7 +1584,25 @@ async function inspectTransfer(sdk, input) {
         });
     }
     const currentContract = sdk.fromArtifact(currentArtifact);
+    const currentState = prepared.current.stateValue;
+    const recursiveWitness = buildPolicyRecursiveWitness(prepared);
     if (!prepared.nextCompiled) {
+        if (shouldUseMultiAssetPolicyExecutor(currentState.assetId, input)) {
+            const inspect = await (0, executor_1.inspectMultiAssetContractCall)(sdk.config, currentArtifact, buildPolicyMultiAssetCallInput({
+                ...input,
+                currentState,
+                outputAddress: input.nextReceiver.address,
+                outputAmountSat: input.nextAmountSat,
+                contractSequence: resolvePolicySequence(currentState),
+                witness: recursiveWitness,
+                purpose: "sdk_policy_transfer_plain_exit",
+            }));
+            return {
+                mode: "plain-exit",
+                prepared,
+                inspect,
+            };
+        }
         const inspect = await currentContract.inspectCall({
             wallet: input.wallet,
             toAddress: input.nextReceiver.address,
@@ -1508,8 +1610,8 @@ async function inspectTransfer(sdk, input) {
             sendAmount: satToBtcAmount(input.nextAmountSat),
             feeSat: input.feeSat,
             utxoPolicy: input.utxoPolicy,
-            sequence: resolvePolicySequence(prepared.current.stateValue),
-            witness: buildPolicyRecursiveWitness(prepared),
+            sequence: resolvePolicySequence(currentState),
+            witness: recursiveWitness,
         });
         return {
             mode: "plain-exit",
@@ -1517,6 +1619,22 @@ async function inspectTransfer(sdk, input) {
             inspect,
         };
     }
+    if (shouldUseMultiAssetPolicyExecutor(currentState.assetId, input)) {
+        const inspect = await (0, executor_1.inspectMultiAssetContractCall)(sdk.config, currentArtifact, buildPolicyMultiAssetCallInput({
+            ...input,
+            currentState,
+            outputAddress: prepared.nextCompiled.contractAddress,
+            outputAmountSat: input.nextAmountSat,
+            contractSequence: resolvePolicySequence(currentState),
+            witness: recursiveWitness,
+            purpose: "sdk_policy_transfer",
+        }));
+        return {
+            mode: prepared.verificationReport.enforcement,
+            prepared,
+            inspect,
+        };
+    }
     const inspect = await currentContract.inspectCall({
         wallet: input.wallet,
         toAddress: prepared.nextCompiled.contractAddress,
@@ -1524,8 +1642,8 @@ async function inspectTransfer(sdk, input) {
         sendAmount: satToBtcAmount(input.nextAmountSat),
         feeSat: input.feeSat,
         utxoPolicy: input.utxoPolicy,
-        sequence: resolvePolicySequence(prepared.current.stateValue),
-        witness: buildPolicyRecursiveWitness(prepared),
+        sequence: resolvePolicySequence(currentState),
+        witness: recursiveWitness,
     });
     return {
         mode: prepared.verificationReport.enforcement,
@@ -1543,7 +1661,25 @@ async function executeTransfer(sdk, input) {
         });
     }
     const currentContract = sdk.fromArtifact(currentArtifact);
+    const currentState = prepared.current.stateValue;
+    const recursiveWitness = buildPolicyRecursiveWitness(prepared);
     if (!prepared.nextCompiled) {
+        if (shouldUseMultiAssetPolicyExecutor(currentState.assetId, input)) {
+            const execution = await (0, executor_1.executeMultiAssetContractCall)(sdk.config, currentArtifact, buildPolicyMultiAssetCallInput({
+                ...input,
+                currentState,
+                outputAddress: input.nextReceiver.address,
+                outputAmountSat: input.nextAmountSat,
+                contractSequence: resolvePolicySequence(currentState),
+                witness: recursiveWitness,
+                purpose: "sdk_policy_transfer_plain_exit",
+            }));
+            return {
+                mode: "plain-exit",
+                prepared,
+                execution,
+            };
+        }
         const execution = await currentContract.execute({
             wallet: input.wallet,
             toAddress: input.nextReceiver.address,
@@ -1552,8 +1688,8 @@ async function executeTransfer(sdk, input) {
             feeSat: input.feeSat,
             broadcast: input.broadcast,
             utxoPolicy: input.utxoPolicy,
-            sequence: resolvePolicySequence(prepared.current.stateValue),
-            witness: buildPolicyRecursiveWitness(prepared),
+            sequence: resolvePolicySequence(currentState),
+            witness: recursiveWitness,
         });
         return {
             mode: "plain-exit",
@@ -1561,6 +1697,22 @@ async function executeTransfer(sdk, input) {
             execution,
         };
     }
+    if (shouldUseMultiAssetPolicyExecutor(currentState.assetId, input)) {
+        const execution = await (0, executor_1.executeMultiAssetContractCall)(sdk.config, currentArtifact, buildPolicyMultiAssetCallInput({
+            ...input,
+            currentState,
+            outputAddress: prepared.nextCompiled.contractAddress,
+            outputAmountSat: input.nextAmountSat,
+            contractSequence: resolvePolicySequence(currentState),
+            witness: recursiveWitness,
+            purpose: "sdk_policy_transfer",
+        }));
+        return {
+            mode: prepared.verificationReport.enforcement,
+            prepared,
+            execution,
+        };
+    }
     const execution = await currentContract.execute({
         wallet: input.wallet,
         toAddress: prepared.nextCompiled.contractAddress,
@@ -1569,8 +1721,8 @@ async function executeTransfer(sdk, input) {
         feeSat: input.feeSat,
         broadcast: input.broadcast,
         utxoPolicy: input.utxoPolicy,
-        sequence: resolvePolicySequence(prepared.current.stateValue),
-        witness: buildPolicyRecursiveWitness(prepared),
+        sequence: resolvePolicySequence(currentState),
+        witness: recursiveWitness,
     });
     return {
         mode: prepared.verificationReport.enforcement,

package/dist/x402/atomicDvp.d.ts

@@ -137,6 +137,16 @@ export interface LiquidAtomicDvpTakeProposalInput {
     proposal?: string;
     proposalPsetBase64?: string;
     proposalTxHex?: string;
+    /**
+     * Optional recipient for the maker-delivered asset when the taker PSET is
+     * completed. Use this for policy/Simplicity delivery addresses that are not a
+     * normal wallet receive address.
+     */
+    takerDeliveryAddress?: string;
+    /**
+     * Backwards-friendly alias for `takerDeliveryAddress`.
+     */
+    deliveryAddress?: string;
     payer?: string;
     esploraUrl?: string;
     waterfalls?: boolean;
@@ -154,6 +164,7 @@ export type LiquidAtomicDvpTakeProposalResult = ReturnType<typeof buildLiquidAto
     dwid?: string;
     proposalInput: LiquidAtomicDvpOutputRequirement;
     proposalOutput: LiquidAtomicDvpOutputRequirement;
+    takerDeliveryAddress?: string;
 };
 export interface LiquidAtomicDvpVerifyPayloadResult {
     isValid: boolean;

package/dist/x402/atomicDvp.js

@@ -113,7 +113,8 @@ async function prepareLiquidAtomicDvpLwkWasmTakerPayment(input) {
     let builder = network.txBuilder();
     if (input.feeRate !== undefined)
         builder = builder.feeRate(input.feeRate);
-    builder = builder.liquidexTake([validated]);
+    const takerDeliveryAddress = normalizeOptionalString(input.takerDeliveryAddress ?? input.deliveryAddress, "takerDeliveryAddress");
+    builder = applyLiquidexTake(lwk, builder, [validated], network, takerDeliveryAddress);
     const unsigned = builder.finish(wollet);
     const signed = signer.sign(unsigned);
     const pset = input.finalize === false ? signed : wollet.finalize(signed);
@@ -128,6 +129,7 @@ async function prepareLiquidAtomicDvpLwkWasmTakerPayment(input) {
         ...(typeof wollet.dwid === "function" ? { dwid: wollet.dwid() } : {}),
         proposalInput,
         proposalOutput,
+        ...(takerDeliveryAddress ? { takerDeliveryAddress } : {}),
     };
 }
 function buildLiquidAtomicDvpSummaryHash(input) {
@@ -360,6 +362,18 @@ function parseLwkTransaction(lwk, txHex) {
         return new lwk.Transaction(txHex);
     throw new Error("LWK Transaction support is required to validate a Liquidex proposal against a transaction.");
 }
+function applyLiquidexTake(lwk, builder, validatedProposals, network, takerDeliveryAddress) {
+    if (!takerDeliveryAddress)
+        return builder.liquidexTake(validatedProposals);
+    const deliveryAddress = parseLwkAddress(lwk, takerDeliveryAddress, network);
+    for (const method of ["liquidexTakeWithRecipient", "liquidexTakeToAddress", "liquidexTakeTo"]) {
+        if (typeof builder[method] === "function") {
+            return builder[method](validatedProposals, deliveryAddress);
+        }
+    }
+    throw new Error("Liquidex taker delivery address override is not supported by the loaded LWK module. " +
+        "Upgrade LWK or use a fixed-recipient/manual atomic DvP PSET builder.");
+}
 function parseLiquidexProposal(lwk, value) {
     const encoded = String(value ?? "").trim();
     if (!encoded)
@@ -435,6 +449,16 @@ function normalizeOutput(value, name) {
         recipient: requiredString(raw.recipient, `${name}.recipient`),
     };
 }
+function normalizeOptionalString(value, name) {
+    if (value === undefined || value === null)
+        return undefined;
+    const text = String(value).trim();
+    if (!text)
+        return undefined;
+    if (text.length > 2048)
+        throw new Error(`${name} is too long`);
+    return text;
+}
 function normalizeServiceSigner(value) {
     if (value === null || value === undefined)
         return null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hazbase/simplicity",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "description": "An SDK for Simplicity on Liquid",
   "author": "IndieSquare Inc <info@hazbase.com>",
   "keywords": [