@hazbase/simplicity 0.3.0 → 0.3.1

package/README.md

@@ -193,6 +193,22 @@ RECEIVABLE_OUTPUT_BINDING_MODE=script-bound npm run e2e:receivable-testnet
 RECEIVABLE_OUTPUT_BINDING_MODE=descriptor-bound npm run e2e:receivable-testnet
 ```
 
+Liquid x402 buyer smoke test:
+
+```bash
+npm install --no-save lwk_node@^0.17.1
+npm run e2e:x402-lwk-address -- --generate
+npm run e2e:x402-lwk-buyer -- https://share.example/v/slug --dry-run
+LIQUID_X402_E2E_MNEMONIC="..." npm run e2e:x402-lwk-buyer -- https://share.example/v/slug --no-submit
+LIQUID_X402_E2E_MNEMONIC="..." npm run e2e:x402-lwk-buyer -- https://share.example/v/slug --output unlocked.bin
+```
+
+The address script derives a confidential Liquid receive address for funding a
+test buyer wallet. The buyer script then uses LWK locally to scan, build, sign,
+and finalize a Liquid PSET, then sends the resulting `X-PAYMENT` header back to
+the protected URL. `--dry-run` only inspects the 402 requirements, while
+`--no-submit` signs a payment without broadcasting through the seller backend.
+
 These commands are useful both as reproducible checks and as examples of the SDK's current validated surface.
 
 ## Where To Go Next

package/dist/client/SimplicityClient.d.ts

@@ -22,6 +22,9 @@ export declare class SimplicityClient {
             encodePayment: typeof liquidX402.encodeLiquidXPayment;
             decodePayment: typeof liquidX402.decodeLiquidXPayment;
             preparePsetPayment: (input: liquidX402.LiquidX402PreparePsetPaymentInput) => Promise<liquidX402.LiquidX402PreparePsetPaymentResult>;
+            buildPaymentFromPset: typeof liquidX402.buildLiquidX402PaymentFromPset;
+            prepareLwkWasmPayment: typeof liquidX402.prepareLiquidX402LwkWasmPayment;
+            deriveLwkWasmAddress: typeof liquidX402.deriveLiquidX402LwkWasmAddress;
             verify: (input: liquidX402.LiquidX402VerifyPaymentInput) => Promise<liquidX402.LiquidX402VerifyPaymentResult>;
             settle: (input: liquidX402.LiquidX402SettlePaymentInput) => Promise<liquidX402.LiquidX402SettlePaymentResult>;
         };

package/dist/client/SimplicityClient.js

@@ -71,6 +71,9 @@ class SimplicityClient {
                 encodePayment: liquidX402.encodeLiquidXPayment,
                 decodePayment: liquidX402.decodeLiquidXPayment,
                 preparePsetPayment: async (input) => liquidX402.prepareLiquidX402PsetPayment(this.rpc, input),
+                buildPaymentFromPset: liquidX402.buildLiquidX402PaymentFromPset,
+                prepareLwkWasmPayment: liquidX402.prepareLiquidX402LwkWasmPayment,
+                deriveLwkWasmAddress: liquidX402.deriveLiquidX402LwkWasmAddress,
                 verify: async (input) => liquidX402.verifyLiquidX402Payment(this.rpc, input),
                 settle: async (input) => liquidX402.settleLiquidX402Payment(this.rpc, input),
             },

package/dist/x402/index.d.ts

@@ -75,6 +75,49 @@ export interface LiquidX402PreparePsetPaymentResult {
     psetBase64: string;
     summaryHash: string;
 }
+export interface LiquidX402BuildPaymentFromPsetInput {
+    requirements: LiquidX402PaymentRequirements | Record<string, unknown>;
+    psetBase64: string;
+    decoded?: DecodePsbtResult;
+    payer?: string;
+    summaryHash?: string;
+}
+export interface LiquidX402PrepareLwkWasmPaymentInput {
+    requirements: LiquidX402PaymentRequirements | Record<string, unknown>;
+    mnemonic: string;
+    payer?: string;
+    esploraUrl?: string;
+    waterfalls?: boolean;
+    concurrency?: number;
+    utxoOnly?: boolean;
+    scan?: boolean;
+    scanToIndex?: number;
+    feeRate?: number;
+    finalize?: boolean;
+    lwk?: LiquidX402LwkWasmModule;
+    importLwk?: () => Promise<LiquidX402LwkWasmModule>;
+}
+export type LiquidX402PrepareLwkWasmPaymentResult = LiquidX402PreparePsetPaymentResult & {
+    descriptor: string;
+    dwid?: string;
+};
+export interface LiquidX402DeriveLwkWasmAddressInput {
+    mnemonic: string;
+    network?: LiquidX402Network;
+    index?: number;
+    lwk?: LiquidX402LwkWasmModule;
+    importLwk?: () => Promise<LiquidX402LwkWasmModule>;
+}
+export interface LiquidX402DeriveLwkWasmAddressResult {
+    network: LiquidX402Network;
+    address: string;
+    unconfidentialAddress?: string;
+    index: number;
+    isBlinded?: boolean;
+    descriptor: string;
+    dwid?: string;
+    policyAsset?: string;
+}
 export interface LiquidX402VerifyPaymentInput {
     requirements: LiquidX402PaymentRequirements | Record<string, unknown>;
     paymentPayload: LiquidX402PaymentPayload | Record<string, unknown>;
@@ -100,7 +143,7 @@ export interface LiquidX402SettlePaymentResult {
     rawTxHex?: string;
     summaryHash?: string;
 }
-type DecodePsbtResult = {
+export type DecodePsbtResult = {
     fees?: Record<string, number>;
     outputs?: Array<{
         amount?: number;
@@ -111,6 +154,24 @@ type DecodePsbtResult = {
         };
     }>;
 };
+export type LiquidX402LwkWasmModule = {
+    Address: {
+        new (value: string): any;
+        parse?: (value: string, network: any) => any;
+    };
+    AssetId: {
+        new (value: string): any;
+        fromString?: (value: string) => any;
+    };
+    EsploraClient: new (network: any, url: string, waterfalls: boolean, concurrency: number, utxoOnly: boolean) => any;
+    Mnemonic: new (value: string) => any;
+    Network: {
+        mainnet: () => any;
+        testnet: () => any;
+    };
+    Signer: new (mnemonic: any, network: any) => any;
+    Wollet: new (network: any, descriptor: any) => any;
+};
 export declare const LIQUID_X402_ASSETS: Record<LiquidX402Network, Record<LiquidX402AssetKey, LiquidX402Asset>>;
 export declare function listLiquidX402Assets(network?: LiquidX402Network): LiquidX402Asset[];
 export declare function resolveLiquidX402Asset(asset: LiquidX402AssetKey | string, network?: LiquidX402Network): LiquidX402Asset;
@@ -118,8 +179,10 @@ export declare function buildLiquidX402Requirements(input: LiquidX402Requirement
 export declare function encodeLiquidXPayment(payload: LiquidX402PaymentPayload): string;
 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 prepareLiquidX402LwkWasmPayment(input: LiquidX402PrepareLwkWasmPaymentInput): Promise<LiquidX402PrepareLwkWasmPaymentResult>;
+export declare function deriveLiquidX402LwkWasmAddress(input: LiquidX402DeriveLwkWasmAddressInput): Promise<LiquidX402DeriveLwkWasmAddressResult>;
 export declare function verifyLiquidX402Payment(rpc: ElementsRpcClient | null, input: LiquidX402VerifyPaymentInput): Promise<LiquidX402VerifyPaymentResult>;
 export declare function settleLiquidX402Payment(rpc: ElementsRpcClient, input: LiquidX402SettlePaymentInput): Promise<LiquidX402SettlePaymentResult>;
 export declare function verifyLiquidX402PayloadFields(requirements: LiquidX402PaymentRequirements | Record<string, unknown>, payload: LiquidX402PaymentPayload | Record<string, unknown>, now?: Date): LiquidX402VerifyPaymentResult;
-export declare function buildLiquidPsetSummaryHash(decoded: DecodePsbtResult, requirements: LiquidX402PaymentRequirements | Record<string, unknown>): string;
-export {};
+export declare function buildLiquidPsetSummaryHash(_decoded: DecodePsbtResult, requirements: LiquidX402PaymentRequirements | Record<string, unknown>): string;

package/dist/x402/index.js

@@ -7,6 +7,9 @@ exports.buildLiquidX402Requirements = buildLiquidX402Requirements;
 exports.encodeLiquidXPayment = encodeLiquidXPayment;
 exports.decodeLiquidXPayment = decodeLiquidXPayment;
 exports.prepareLiquidX402PsetPayment = prepareLiquidX402PsetPayment;
+exports.buildLiquidX402PaymentFromPset = buildLiquidX402PaymentFromPset;
+exports.prepareLiquidX402LwkWasmPayment = prepareLiquidX402LwkWasmPayment;
+exports.deriveLiquidX402LwkWasmAddress = deriveLiquidX402LwkWasmAddress;
 exports.verifyLiquidX402Payment = verifyLiquidX402Payment;
 exports.settleLiquidX402Payment = settleLiquidX402Payment;
 exports.verifyLiquidX402PayloadFields = verifyLiquidX402PayloadFields;
@@ -18,13 +21,15 @@ exports.LIQUID_X402_DEFAULT_NETWORK = "liquidtestnet";
 exports.LIQUID_X402_DEFAULT_TIMEOUT_SECONDS = 60;
 const LIQUID_TESTNET_USDT_ASSET_ID = "b612eb46313a2cd6ebabd8b7a8eed5696e29898b87a43bff41c94f51acef9d73";
 const LIQUID_MAINNET_USDT_ASSET_ID = "ce091c998b83c78bb71a632313ba3760f1763d9cfcffae02258ffa9865a37bd2";
+const LIQUID_TESTNET_LBTC_ASSET_ID = "144c654344aa716d6f3abcc1ca90e5641e4e2a7f633bc09fe3baf64585819a49";
+const LIQUID_MAINNET_LBTC_ASSET_ID = "6f0279e9ed041c3d710a9f57d0c02928416460c4b722ae3457a11eec381c526d";
 exports.LIQUID_X402_ASSETS = {
     liquidtestnet: {
         lbtc: {
             key: "lbtc",
             label: "Liquid Bitcoin",
             network: "liquidtestnet",
-            assetId: "bitcoin",
+            assetId: LIQUID_TESTNET_LBTC_ASSET_ID,
             decimals: 8,
             isNative: true,
         },
@@ -42,7 +47,7 @@ exports.LIQUID_X402_ASSETS = {
             key: "lbtc",
             label: "Liquid Bitcoin",
             network: "liquidv1",
-            assetId: "bitcoin",
+            assetId: LIQUID_MAINNET_LBTC_ASSET_ID,
             decimals: 8,
             isNative: true,
         },
@@ -161,6 +166,100 @@ async function prepareLiquidX402PsetPayment(rpc, input) {
         summaryHash,
     };
 }
+function buildLiquidX402PaymentFromPset(input) {
+    const requirements = coerceRequirements(input.requirements);
+    const psetBase64 = String(input.psetBase64 ?? "").trim();
+    if (!psetBase64)
+        throw new Error("psetBase64 is required");
+    const summaryHash = input.summaryHash ?? buildLiquidPsetSummaryHash(input.decoded ?? {}, requirements);
+    const paymentPayload = {
+        scheme: exports.LIQUID_X402_SCHEME,
+        network: requirements.network,
+        paymentRequestId: requirements.extra.paymentRequestId,
+        asset: requirements.extra.asset,
+        assetId: requirements.asset,
+        amountAtomic: requirements.maxAmountRequired,
+        payTo: requirements.payTo,
+        psetBase64,
+        summaryHash,
+        ...(input.payer ? { payer: input.payer } : {}),
+        expiresAt: requirements.extra.expiresAt,
+    };
+    return {
+        paymentPayload,
+        xPayment: encodeLiquidXPayment(paymentPayload),
+        psetBase64,
+        summaryHash,
+    };
+}
+async function prepareLiquidX402LwkWasmPayment(input) {
+    const requirements = coerceRequirements(input.requirements);
+    ensureLwkWasmNodeTimerCompat();
+    const lwk = input.lwk ?? await loadLwkWasm(input.importLwk);
+    const network = requirements.network === "liquidv1" ? lwk.Network.mainnet() : lwk.Network.testnet();
+    const mnemonic = new lwk.Mnemonic(input.mnemonic);
+    const signer = new lwk.Signer(mnemonic, network);
+    const descriptor = signer.wpkhSlip77Descriptor();
+    const wollet = new lwk.Wollet(network, descriptor);
+    const client = input.esploraUrl
+        ? new lwk.EsploraClient(network, input.esploraUrl, input.waterfalls ?? false, input.concurrency ?? 4, input.utxoOnly ?? false)
+        : network.defaultEsploraClient();
+    if (input.scan !== false) {
+        const update = input.scanToIndex !== undefined
+            ? await client.fullScanToIndex(wollet, input.scanToIndex)
+            : await client.fullScan(wollet);
+        if (update)
+            wollet.applyUpdate(update);
+    }
+    let builder = network.txBuilder();
+    if (input.feeRate !== undefined)
+        builder = builder.feeRate(input.feeRate);
+    const recipient = parseLwkAddress(lwk, requirements.payTo, network);
+    const amount = BigInt(requirements.maxAmountRequired);
+    if (requirements.extra.asset === "lbtc") {
+        builder = builder.addLbtcRecipient(recipient, amount);
+    }
+    else {
+        builder = builder.addRecipient(recipient, amount, parseLwkAssetId(lwk, requirements.asset));
+    }
+    const unsigned = builder.finish(wollet);
+    const signed = signer.sign(unsigned);
+    const pset = input.finalize === false ? signed : wollet.finalize(signed);
+    const decoded = decodeLwkPsetForX402(pset, wollet);
+    const payment = buildLiquidX402PaymentFromPset({
+        requirements,
+        psetBase64: pset.toString(),
+        decoded,
+        payer: input.payer,
+    });
+    return {
+        ...payment,
+        descriptor: descriptor.toString(),
+        ...(typeof wollet.dwid === "function" ? { dwid: wollet.dwid() } : {}),
+    };
+}
+async function deriveLiquidX402LwkWasmAddress(input) {
+    const networkKey = normalizeNetwork(input.network ?? exports.LIQUID_X402_DEFAULT_NETWORK);
+    ensureLwkWasmNodeTimerCompat();
+    const lwk = input.lwk ?? await loadLwkWasm(input.importLwk);
+    const network = networkKey === "liquidv1" ? lwk.Network.mainnet() : lwk.Network.testnet();
+    const mnemonic = new lwk.Mnemonic(input.mnemonic);
+    const signer = new lwk.Signer(mnemonic, network);
+    const descriptor = signer.wpkhSlip77Descriptor();
+    const wollet = new lwk.Wollet(network, descriptor);
+    const addressResult = wollet.address(input.index ?? null);
+    const address = addressResult.address();
+    return {
+        network: networkKey,
+        address: address.toString(),
+        ...(typeof address.toUnconfidential === "function" ? { unconfidentialAddress: address.toUnconfidential().toString() } : {}),
+        index: typeof addressResult.index === "function" ? addressResult.index() : input.index ?? 0,
+        ...(typeof address.isBlinded === "function" ? { isBlinded: address.isBlinded() } : {}),
+        descriptor: descriptor.toString(),
+        ...(typeof wollet.dwid === "function" ? { dwid: wollet.dwid() } : {}),
+        ...(typeof network.policyAsset === "function" ? { policyAsset: network.policyAsset().toString() } : {}),
+    };
+}
 async function verifyLiquidX402Payment(rpc, input) {
     const requirements = coerceRequirements(input.requirements);
     const payload = coercePaymentPayload(input.paymentPayload);
@@ -257,7 +356,7 @@ function verifyLiquidX402PayloadFields(requirements, payload, now = new Date())
     }
     return { ...base, isValid: true };
 }
-function buildLiquidPsetSummaryHash(decoded, requirements) {
+function buildLiquidPsetSummaryHash(_decoded, requirements) {
     const req = coerceRequirements(requirements);
     return sha256Hex(stableStringify({
         scheme: exports.LIQUID_X402_SCHEME,
@@ -267,8 +366,14 @@ function buildLiquidPsetSummaryHash(decoded, requirements) {
         assetId: req.asset,
         amountAtomic: req.maxAmountRequired,
         payTo: req.payTo,
-        outputs: normalizeDecodedOutputs(decoded),
-        fees: decoded.fees ?? {},
+        expectedOutput: {
+            amountAtomic: req.maxAmountRequired,
+            assetId: req.asset,
+            payTo: req.payTo,
+        },
+        feeAsset: req.extra.feeAsset,
+        feeAssetId: req.extra.feeAssetId ?? exports.LIQUID_X402_ASSETS[req.network].lbtc.assetId,
+        maxFeeSat: req.extra.maxFeeSat ?? null,
     }));
 }
 function decodedContainsExpectedOutput(decoded, requirements) {
@@ -278,14 +383,6 @@ function decodedContainsExpectedOutput(decoded, requirements) {
             Math.round(expectedAmount * 10 ** requirements.extra.decimals) &&
         String(output.script?.address ?? "") === requirements.payTo));
 }
-function normalizeDecodedOutputs(decoded) {
-    return (decoded.outputs ?? []).map((output) => ({
-        amount: output.amount ?? null,
-        asset: output.asset ?? null,
-        address: output.script?.address ?? null,
-        scriptPubKey: output.script?.hex ?? null,
-    }));
-}
 function coerceRequirements(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         throw new Error("requirements must be an object");
@@ -293,6 +390,8 @@ function coerceRequirements(value) {
     const extra = raw.extra && typeof raw.extra === "object" && !Array.isArray(raw.extra) ? raw.extra : {};
     const network = normalizeNetwork(raw.network);
     const asset = resolveLiquidX402Asset(extra.asset ?? raw.asset, network);
+    const rawAssetId = String(raw.asset ?? extra.assetId ?? asset.assetId);
+    const assetId = isLiquidAssetAlias(rawAssetId) ? asset.assetId : rawAssetId;
     return {
         scheme: exports.LIQUID_X402_SCHEME,
         network,
@@ -302,11 +401,11 @@ function coerceRequirements(value) {
         mimeType: String(raw.mimeType ?? ""),
         payTo: String(raw.payTo ?? ""),
         maxTimeoutSeconds: normalizeTimeout(raw.maxTimeoutSeconds),
-        asset: String(raw.asset ?? extra.assetId ?? asset.assetId),
+        asset: assetId,
         extra: {
             paymentRequestId: String(extra.paymentRequestId ?? raw.paymentRequestId ?? ""),
             asset: asset.key,
-            assetId: String(extra.assetId ?? raw.asset ?? asset.assetId),
+            assetId,
             decimals: Number(extra.decimals ?? asset.decimals),
             expiresAt: String(extra.expiresAt ?? ""),
             feeAsset: "lbtc",
@@ -326,6 +425,56 @@ function decodedFeeWithinCap(decoded, requirements) {
     }, 0n);
     return feeSat <= maxFeeSat;
 }
+async function loadLwkWasm(importer) {
+    ensureLwkWasmNodeTimerCompat();
+    if (importer)
+        return importer();
+    const dynamicImport = new Function("specifier", "return import(specifier)");
+    const failures = [];
+    for (const specifier of ["lwk_wasm", "lwk_node"]) {
+        try {
+            const imported = await dynamicImport(specifier);
+            return imported.default ?? imported;
+        }
+        catch (error) {
+            failures.push(`${specifier}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    throw new Error("lwk_wasm or lwk_node is required for lightweight Liquid x402 payments. " +
+        "Install one of them in the consuming app and bundle its WASM artifact when needed. " +
+        `Import failed: ${failures.join("; ")}`);
+}
+function ensureLwkWasmNodeTimerCompat() {
+    const scope = globalThis;
+    if (typeof scope.window === "undefined" && typeof scope.setTimeout === "function") {
+        scope.window = scope;
+    }
+    if (typeof scope.Window === "undefined" && typeof scope.window !== "undefined") {
+        scope.Window = Object;
+    }
+}
+function parseLwkAddress(lwk, address, network) {
+    return typeof lwk.Address.parse === "function" ? lwk.Address.parse(address, network) : new lwk.Address(address);
+}
+function parseLwkAssetId(lwk, assetId) {
+    return typeof lwk.AssetId.fromString === "function" ? lwk.AssetId.fromString(assetId) : new lwk.AssetId(assetId);
+}
+function decodeLwkPsetForX402(pset, wollet) {
+    const details = wollet.psetDetails(pset);
+    const balance = details.balance();
+    const recipients = typeof balance.recipients === "function" ? balance.recipients() : [];
+    const fee = typeof balance.fee === "function" ? balance.fee() : 0n;
+    return {
+        fees: { bitcoin: atomicToDecimalNumber(String(fee), 8) },
+        outputs: recipients.map((recipient) => ({
+            amount: recipient.value() === undefined ? undefined : atomicToDecimalNumber(String(recipient.value()), 8),
+            asset: recipient.asset()?.toString(),
+            script: {
+                address: recipient.address()?.toString(),
+            },
+        })),
+    };
+}
 function coercePaymentPayload(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         throw new Error("payment payload must be an object");
@@ -352,12 +501,26 @@ function normalizeNetwork(input) {
 }
 function normalizeAssetKey(input) {
     const value = String(input ?? "").trim().toLowerCase();
-    if (value === "lbtc" || value === "bitcoin")
+    if (value === "lbtc" || value === "bitcoin" || value === LIQUID_TESTNET_LBTC_ASSET_ID || value === LIQUID_MAINNET_LBTC_ASSET_ID) {
         return "lbtc";
-    if (value === "usdt" || value === "usdt-liquid" || value === "tether")
+    }
+    if (value === "usdt" ||
+        value === "usdt-liquid" ||
+        value === "tether" ||
+        value === LIQUID_TESTNET_USDT_ASSET_ID ||
+        value === LIQUID_MAINNET_USDT_ASSET_ID) {
         return "usdt";
+    }
     throw new Error(`unsupported Liquid x402 asset: ${String(input)}`);
 }
+function isLiquidAssetAlias(input) {
+    const value = String(input ?? "").trim().toLowerCase();
+    return value === "lbtc" ||
+        value === "bitcoin" ||
+        value === "usdt" ||
+        value === "usdt-liquid" ||
+        value === "tether";
+}
 function normalizeAmountAtomic(input) {
     const raw = typeof input === "bigint" ? input.toString() : String(input ?? "").trim();
     if (!/^\d+$/u.test(raw))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hazbase/simplicity",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "An SDK for Simplicity on Liquid",
   "author": "IndieSquare Inc <info@hazbase.com>",
   "keywords": [
@@ -50,6 +50,8 @@
     "e2e:receivable-local": "npm run build && node scripts/e2e-receivable-local.mjs",
     "e2e:receivable-testnet": "npm run build && node scripts/e2e-receivable-testnet.mjs",
     "e2e:receivable-consumer": "npm run build && node scripts/e2e-receivable-consumer.mjs",
+    "e2e:x402-lwk-address": "npm run build && node scripts/e2e-x402-lwk-address.mjs",
+    "e2e:x402-lwk-buyer": "npm run build && node scripts/e2e-x402-lwk-buyer.mjs",
     "e2e:simplicity-relayer": "npm run build && node scripts/e2e-simplicity-relayer.mjs",
     "prepublishOnly": "npm run build"
   },