@hazbase/simplicity 0.4.3 → 0.4.4

package/README.md

@@ -175,6 +175,15 @@ testnet issuer or deployment uses a different USDt asset id, set
 payment requirements will preserve that asset id instead of replacing it with
 the SDK's default registry id.
 
+For policy-locked Liquid RWA positions, redemption can be represented as a
+Liquid x402 request with `extra.redemptionSource.type:
+"policy_locked_position"`. Wallets can use
+`buildLiquidPolicyLockedRedemptionPaymentFromProposal(...)` when a service has
+already prepared the Simplicity policy-spend PSET proposal. The helper binds the
+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.
+
 Typical entrypoints:
 - `sdk.rwaDvp.definePurchase(...)`
 - `sdk.rwaDvp.buildPaymentRequirements(...)`

package/dist/client/SimplicityClient.d.ts

@@ -24,6 +24,7 @@ export declare class SimplicityClient {
             decodePayment: typeof liquidX402.decodeLiquidXPayment;
             preparePsetPayment: (input: liquidX402.LiquidX402PreparePsetPaymentInput) => Promise<liquidX402.LiquidX402PreparePsetPaymentResult>;
             buildPaymentFromPset: typeof liquidX402.buildLiquidX402PaymentFromPset;
+            buildPolicyLockedRedemptionPaymentFromProposal: typeof liquidX402.buildLiquidPolicyLockedRedemptionPaymentFromProposal;
             prepareLwkWasmPayment: typeof liquidX402.prepareLiquidX402LwkWasmPayment;
             deriveLwkWasmAddress: typeof liquidX402.deriveLiquidX402LwkWasmAddress;
             verify: (input: liquidX402.LiquidX402VerifyPaymentInput) => Promise<liquidX402.LiquidX402VerifyPaymentResult>;

package/dist/client/SimplicityClient.js

@@ -74,6 +74,7 @@ class SimplicityClient {
                 decodePayment: liquidX402.decodeLiquidXPayment,
                 preparePsetPayment: async (input) => liquidX402.prepareLiquidX402PsetPayment(this.rpc, input),
                 buildPaymentFromPset: liquidX402.buildLiquidX402PaymentFromPset,
+                buildPolicyLockedRedemptionPaymentFromProposal: liquidX402.buildLiquidPolicyLockedRedemptionPaymentFromProposal,
                 prepareLwkWasmPayment: liquidX402.prepareLiquidX402LwkWasmPayment,
                 deriveLwkWasmAddress: liquidX402.deriveLiquidX402LwkWasmAddress,
                 verify: async (input) => liquidX402.verifyLiquidX402Payment(this.rpc, input),

package/dist/x402/index.d.ts

@@ -55,7 +55,7 @@ export interface LiquidX402PaymentPayload {
     scheme: typeof LIQUID_X402_SCHEME;
     network: LiquidX402Network;
     paymentRequestId: string;
-    asset: LiquidX402AssetKey;
+    asset: LiquidX402AssetKey | "custom" | string;
     assetId: string;
     amountAtomic: string;
     payTo: string;
@@ -84,6 +84,25 @@ export interface LiquidX402BuildPaymentFromPsetInput {
     payer?: string;
     summaryHash?: string;
 }
+export interface LiquidPolicyLockedRedemptionSpendProposal {
+    mode?: "service_prepared_policy_spend_v1" | string;
+    psetBase64?: string;
+    summaryHash?: string;
+    holderSignatureRequired?: boolean;
+    metadata?: Record<string, unknown>;
+}
+export interface LiquidPolicyLockedRedemptionPaymentFromProposalInput {
+    requirements: LiquidX402PaymentRequirements | Record<string, unknown>;
+    proposal?: LiquidPolicyLockedRedemptionSpendProposal | Record<string, unknown>;
+    proposalPsetBase64?: string;
+    summaryHash?: string;
+    payer?: string;
+    metadata?: Record<string, unknown>;
+}
+export type LiquidPolicyLockedRedemptionPaymentFromProposalResult = LiquidX402PreparePsetPaymentResult & {
+    proposalMode?: string;
+    redemptionSource: Record<string, unknown>;
+};
 export interface LiquidX402PrepareLwkWasmPaymentInput {
     requirements: LiquidX402PaymentRequirements | Record<string, unknown>;
     mnemonic: string;
@@ -186,6 +205,7 @@ export declare function encodeLiquidXPayment(payload: LiquidX402PaymentPayload):
 export declare function decodeLiquidXPayment(raw: string): LiquidX402PaymentPayload | null;
 export declare function prepareLiquidX402PsetPayment(rpc: ElementsRpcClient, input: LiquidX402PreparePsetPaymentInput): Promise<LiquidX402PreparePsetPaymentResult>;
 export declare function buildLiquidX402PaymentFromPset(input: LiquidX402BuildPaymentFromPsetInput): LiquidX402PreparePsetPaymentResult;
+export declare function buildLiquidPolicyLockedRedemptionPaymentFromProposal(input: LiquidPolicyLockedRedemptionPaymentFromProposalInput): LiquidPolicyLockedRedemptionPaymentFromProposalResult;
 export declare function prepareLiquidX402LwkWasmPayment(input: LiquidX402PrepareLwkWasmPaymentInput): Promise<LiquidX402PrepareLwkWasmPaymentResult>;
 export declare function deriveLiquidX402LwkWasmAddress(input: LiquidX402DeriveLwkWasmAddressInput): Promise<LiquidX402DeriveLwkWasmAddressResult>;
 export declare function verifyLiquidX402Payment(rpc: ElementsRpcClient | null, input: LiquidX402VerifyPaymentInput): Promise<LiquidX402VerifyPaymentResult>;

package/dist/x402/index.js

@@ -22,6 +22,7 @@ exports.encodeLiquidXPayment = encodeLiquidXPayment;
 exports.decodeLiquidXPayment = decodeLiquidXPayment;
 exports.prepareLiquidX402PsetPayment = prepareLiquidX402PsetPayment;
 exports.buildLiquidX402PaymentFromPset = buildLiquidX402PaymentFromPset;
+exports.buildLiquidPolicyLockedRedemptionPaymentFromProposal = buildLiquidPolicyLockedRedemptionPaymentFromProposal;
 exports.prepareLiquidX402LwkWasmPayment = prepareLiquidX402LwkWasmPayment;
 exports.deriveLiquidX402LwkWasmAddress = deriveLiquidX402LwkWasmAddress;
 exports.verifyLiquidX402Payment = verifyLiquidX402Payment;
@@ -208,6 +209,32 @@ function buildLiquidX402PaymentFromPset(input) {
         summaryHash,
     };
 }
+function buildLiquidPolicyLockedRedemptionPaymentFromProposal(input) {
+    const requirements = coercePolicyLockedRedemptionRequirements(input.requirements);
+    const proposal = coercePolicyLockedRedemptionProposal(input.proposal ?? getRecordValue(input.requirements, "policySpendProposal") ?? getExtraRecord(input.requirements).policySpendProposal, input.proposalPsetBase64);
+    const summaryHash = input.summaryHash ?? proposal.summaryHash ?? requirements.summaryHash ?? buildLiquidPolicyLockedRedemptionSummaryHash(requirements);
+    const paymentPayload = {
+        scheme: exports.LIQUID_X402_SCHEME,
+        network: requirements.network,
+        paymentRequestId: requirements.paymentRequestId,
+        asset: requirements.assetKey,
+        assetId: requirements.assetId,
+        amountAtomic: requirements.amountAtomic,
+        payTo: requirements.payTo,
+        psetBase64: proposal.psetBase64,
+        summaryHash,
+        ...(input.payer ? { payer: input.payer } : {}),
+        expiresAt: requirements.expiresAt,
+    };
+    return {
+        paymentPayload,
+        xPayment: encodeLiquidXPayment(paymentPayload),
+        psetBase64: proposal.psetBase64,
+        summaryHash,
+        ...(proposal.mode ? { proposalMode: proposal.mode } : {}),
+        redemptionSource: requirements.redemptionSource,
+    };
+}
 async function prepareLiquidX402LwkWasmPayment(input) {
     const requirements = coerceRequirements(input.requirements);
     ensureLwkWasmNodeTimerCompat();
@@ -453,6 +480,108 @@ function mempoolRejectReason(result) {
     const raw = result;
     return String(raw["reject-reason"] ?? raw.reject_reason ?? raw.error ?? "mempool_rejected").trim() || "mempool_rejected";
 }
+function coercePolicyLockedRedemptionRequirements(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("requirements must be an object");
+    const raw = value;
+    const extra = getExtraRecord(raw);
+    const network = normalizeNetwork(raw.network);
+    const paymentRequestId = stringValue(extra.paymentRequestId ?? raw.paymentRequestId, "paymentRequestId");
+    const payTo = stringValue(raw.payTo ?? extra.recipient ?? extra.payTo, "payTo");
+    const assetId = stringValue(raw.assetId ?? extra.assetId ?? raw.asset, "assetId");
+    const amountAtomic = normalizeAmountAtomic((raw.maxAmountRequired ?? extra.amount ?? raw.amountAtomic));
+    const assetKey = normalizePaymentAssetKey(extra.asset ?? raw.assetKey ?? "custom");
+    const expiresAt = stringValue(extra.expiresAt ?? raw.expiresAt, "expiresAt");
+    const redemptionSource = coercePolicyLockedRedemptionSource(raw.redemptionSource ?? extra.redemptionSource);
+    const feeAssetId = String(extra.feeAssetId ?? exports.LIQUID_X402_ASSETS[network].lbtc.assetId);
+    return {
+        network,
+        paymentRequestId,
+        resource: String(raw.resource ?? ""),
+        description: String(raw.description ?? ""),
+        mimeType: String(raw.mimeType ?? ""),
+        payTo,
+        maxTimeoutSeconds: normalizeTimeout(raw.maxTimeoutSeconds),
+        assetKey,
+        assetId,
+        amountAtomic,
+        decimals: Number(extra.decimals ?? raw.decimals ?? 0),
+        expiresAt,
+        feeAsset: "lbtc",
+        feeAssetId,
+        ...(extra.maxFeeSat !== undefined ? { maxFeeSat: normalizeAmountAtomic(extra.maxFeeSat) } : {}),
+        ...(typeof raw.x402SummaryHash === "string" ? { summaryHash: raw.x402SummaryHash } : {}),
+        ...(typeof raw.summaryHash === "string" ? { summaryHash: raw.summaryHash } : {}),
+        ...(typeof extra.x402SummaryHash === "string" ? { summaryHash: extra.x402SummaryHash } : {}),
+        ...(typeof extra.summaryHash === "string" ? { summaryHash: extra.summaryHash } : {}),
+        redemptionSource,
+    };
+}
+function coercePolicyLockedRedemptionSource(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("redemptionSource is required for policy-locked redemption");
+    }
+    const source = value;
+    const type = String(source.type ?? "").trim();
+    if (type !== "policy_locked_position") {
+        throw new Error("redemptionSource.type must be policy_locked_position");
+    }
+    return source;
+}
+function coercePolicyLockedRedemptionProposal(value, proposalPsetBase64) {
+    const raw = value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+    if (raw.holderSignatureRequired === true) {
+        throw new Error("policy-locked redemption proposal still requires holder-side Simplicity signing; provide a service-prepared spend proposal");
+    }
+    const psetBase64 = String(proposalPsetBase64 ?? raw.psetBase64 ?? "").trim();
+    if (!psetBase64)
+        throw new Error("policy spend proposal psetBase64 is required");
+    return {
+        psetBase64,
+        ...(raw.mode ? { mode: String(raw.mode) } : {}),
+        ...(raw.summaryHash ? { summaryHash: String(raw.summaryHash) } : {}),
+        ...(raw.holderSignatureRequired !== undefined ? { holderSignatureRequired: raw.holderSignatureRequired === true } : {}),
+        ...(raw.metadata && typeof raw.metadata === "object" && !Array.isArray(raw.metadata)
+            ? { metadata: raw.metadata }
+            : {}),
+    };
+}
+function buildLiquidPolicyLockedRedemptionSummaryHash(requirements) {
+    return sha256Hex(stableStringify({
+        scheme: exports.LIQUID_X402_SCHEME,
+        network: requirements.network,
+        paymentRequestId: requirements.paymentRequestId,
+        asset: requirements.assetKey,
+        assetId: requirements.assetId,
+        amountAtomic: requirements.amountAtomic,
+        payTo: requirements.payTo,
+        expectedOutput: {
+            amountAtomic: requirements.amountAtomic,
+            assetId: requirements.assetId,
+            payTo: requirements.payTo,
+        },
+        feeAsset: requirements.feeAsset,
+        feeAssetId: requirements.feeAssetId ?? exports.LIQUID_X402_ASSETS[requirements.network].lbtc.assetId,
+        maxFeeSat: requirements.maxFeeSat ?? null,
+    }));
+}
+function getRecordValue(value, key) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    return value[key];
+}
+function getExtraRecord(value) {
+    const extra = getRecordValue(value, "extra");
+    return extra && typeof extra === "object" && !Array.isArray(extra) ? extra : {};
+}
+function stringValue(value, name) {
+    const result = String(value ?? "").trim();
+    if (!result)
+        throw new Error(`${name} is required`);
+    return result;
+}
 function coerceRequirements(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         throw new Error("requirements must be an object");
@@ -563,7 +692,7 @@ function coercePaymentPayload(value) {
         scheme: exports.LIQUID_X402_SCHEME,
         network: normalizeNetwork(raw.network),
         paymentRequestId: String(raw.paymentRequestId ?? ""),
-        asset: normalizeAssetKey(String(raw.asset ?? "")),
+        asset: normalizePaymentAssetKey(String(raw.asset ?? "")),
         assetId: String(raw.assetId ?? ""),
         amountAtomic: normalizeAmountAtomic(raw.amountAtomic),
         payTo: String(raw.payTo ?? ""),
@@ -579,6 +708,19 @@ function normalizeNetwork(input) {
         return value;
     throw new Error(`unsupported Liquid x402 network: ${String(input)}`);
 }
+function normalizePaymentAssetKey(input) {
+    const value = String(input ?? "").trim().toLowerCase();
+    if (value === "custom")
+        return "custom";
+    try {
+        return normalizeAssetKey(value);
+    }
+    catch {
+        if (/^[a-z0-9_-]{1,64}$/u.test(value) || /^[0-9a-f]{64}$/u.test(value))
+            return value;
+        throw new Error(`unsupported Liquid x402 asset: ${String(input)}`);
+    }
+}
 function normalizeAssetKey(input) {
     const value = String(input ?? "").trim().toLowerCase();
     if (value === "lbtc" || value === "bitcoin" || value === LIQUID_TESTNET_LBTC_ASSET_ID || value === LIQUID_MAINNET_LBTC_ASSET_ID) {

package/package.json

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