@odatano/x402 0.3.0 → 0.4.0

package/srv/client/fetch.js

@@ -57,8 +57,7 @@ function x402Fetch(opts) {
                     let body = lastBody;
                     if (!body) {
                         try {
-                            const raw = await res.clone().json();
-                            body = (0, errors_1.unwrapCapEnvelope)(raw);
+                            body = await res.clone().json();
                         }
                         catch { /* fall through */ }
                     }
@@ -75,13 +74,9 @@ function x402Fetch(opts) {
             }
             // Parse 402 body. If it's not a v2 PaymentRequirementsBody we
             // bail with the original response (or throw under errorOnFailure).
-            // Some servers (CAP-gated ones using req.reject) wrap the v2 body
-            // inside an OData error envelope, unwrap defensively before the
-            // x402Version check.
             let body;
             try {
-                const raw = await res.clone().json();
-                body = (0, errors_1.unwrapCapEnvelope)(raw);
+                body = await res.clone().json();
             }
             catch {
                 if (opts.errorOnFailure) {

package/srv/core/decode.js

@@ -17,42 +17,9 @@
  * `DecodedPayment` that downstream `validate.ts` checks against
  * `PaymentRequirementEntry` (the 6 mandatory checks).
  */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.decode = decode;
-const CSL = __importStar(require("@emurgo/cardano-serialization-lib-nodejs"));
+const bridge_1 = require("../bridge");
 const errors_1 = require("./errors");
 const SUPPORTED_VERSION = 2;
 const SUPPORTED_SCHEME = 'exact';
@@ -68,90 +35,45 @@ function decodeBase64ToBuffer(s, errCode) {
     }
     return buf;
 }
-function extractOutputs(txBody) {
-    const out = txBody.outputs();
-    const result = [];
-    for (let i = 0; i < out.len(); i++) {
-        const o = out.get(i);
-        const addr = o.address().to_bech32();
-        const value = o.amount();
-        const lovelace = value.coin().to_str();
-        const assets = [];
-        const ma = value.multiasset();
-        if (ma) {
-            const policies = ma.keys();
-            for (let p = 0; p < policies.len(); p++) {
-                const policy = policies.get(p);
-                const policyHex = Buffer.from(policy.to_bytes()).toString('hex').toLowerCase();
-                const assetMap = ma.get(policy);
-                if (!assetMap)
-                    continue;
-                const names = assetMap.keys();
-                for (let n = 0; n < names.len(); n++) {
-                    const name = names.get(n);
-                    const nameHex = Buffer.from(name.name()).toString('hex').toLowerCase();
-                    const qty = assetMap.get(name);
-                    if (!qty)
-                        continue;
-                    assets.push({
-                        unit: (policyHex + nameHex),
-                        policyId: policyHex,
-                        assetNameHex: nameHex,
-                        quantity: qty.to_str(),
-                    });
-                }
-            }
-        }
-        result.push({ outputIndex: i, address: addr, lovelace, assets });
-    }
-    return result;
-}
-function extractInputs(txBody) {
-    const ins = txBody.inputs();
-    const result = [];
-    for (let i = 0; i < ins.len(); i++) {
-        const inp = ins.get(i);
-        result.push({
-            txHash: Buffer.from(inp.transaction_id().to_bytes()).toString('hex').toLowerCase(),
-            outputIndex: inp.index(),
+function extractOutputs(outputs) {
+    return outputs.map((o, i) => {
+        const assets = o.assets.map(a => {
+            // core gives `unit` = policyId(56 hex) + assetNameHex; split it back
+            // into the (policyId, assetNameHex) pair x402's validate.ts expects.
+            const unit = a.unit.toLowerCase();
+            return {
+                unit,
+                policyId: unit.slice(0, 56),
+                assetNameHex: unit.slice(56),
+                quantity: a.quantity,
+            };
         });
-    }
-    return result;
+        return { outputIndex: i, address: o.address, lovelace: o.lovelace, assets };
+    });
+}
+function extractInputs(inputs) {
+    return inputs.map(inp => ({
+        txHash: inp.txHash.toLowerCase(),
+        outputIndex: inp.outputIndex,
+    }));
 }
 /**
- * Pull validity range bounds. CSL exposes `ttl()` (upper) since Shelley
- * and `validity_start_interval_bignum()` (lower) since Allegra. Both can
- * be absent, in which case we return null and the TTL check is skipped
- * (per v2 spec: only validate TTL if buyer set one).
+ * Convert core's decimal-string slot bounds to numbers. Both bounds can
+ * be null, in which case the downstream TTL check is skipped (per v2
+ * spec: only validate TTL if the buyer set one). Slots fit comfortably
+ * in a JS number (current preprod ~85M, max safe int 9e15).
  */
-function extractValidityRange(txBody) {
-    let ttlSlot = null;
-    let validityStartSlot = null;
-    try {
-        const ttl = txBody.ttl_bignum();
-        if (ttl) {
-            // BigNum → string → number; slots fit comfortably in JS number
-            // (current preprod ~85M, max safe int 9e15).
-            ttlSlot = Number(ttl.to_str());
-            if (!Number.isFinite(ttlSlot))
-                ttlSlot = null;
-        }
-    }
-    catch {
-        ttlSlot = null;
-    }
-    try {
-        const start = txBody.validity_start_interval_bignum();
-        if (start) {
-            validityStartSlot = Number(start.to_str());
-            if (!Number.isFinite(validityStartSlot))
-                validityStartSlot = null;
-        }
-    }
-    catch {
-        validityStartSlot = null;
-    }
-    return { ttlSlot, validityStartSlot };
+function extractValidityRange(parsed) {
+    const toSlot = (s) => {
+        if (s == null)
+            return null;
+        const n = Number(s);
+        return Number.isFinite(n) ? n : null;
+    };
+    return {
+        ttlSlot: toSlot(parsed.validityEnd),
+        validityStartSlot: toSlot(parsed.validityStart),
+    };
 }
 function parseNonceRef(nonce) {
     const m = NONCE_RE.exec(nonce);
@@ -200,28 +122,17 @@ function decode(paymentHeader) {
     if (typeof payload.nonce !== 'string' || payload.nonce.length === 0) {
         throw new errors_1.X402Error(errors_1.Codes.MISSING_FIELD, 'payload.nonce is required (v2 UTxO-ref)');
     }
-    // 3. Tx CBOR → CSL Transaction (parses both `transaction` and `fixed`
-    //    representation; we need both, Transaction for body access,
-    //    FixedTransaction for byte-stable hash).
+    // 3. Tx CBOR → structured fields via @odatano/core's pure Buildooor
+    //    parser. `parseTransaction` throws X402Error(INVALID_CBOR) on
+    //    malformed input, and its `txHash` (= body.hash) is byte-preserving,
+    //    the property the old CSL `FixedTransaction` path provided.
     const txBuf = decodeBase64ToBuffer(payload.transaction, errors_1.Codes.INVALID_CBOR);
-    let tx;
-    try {
-        tx = CSL.Transaction.from_bytes(txBuf);
-    }
-    catch {
-        throw new errors_1.X402Error(errors_1.Codes.INVALID_CBOR, 'transaction CBOR did not decode');
-    }
+    const txCborHex = txBuf.toString('hex');
+    const parsed = (0, bridge_1.parseTransaction)(txCborHex);
     // 4. Diagnostics
-    const txBody = tx.body();
-    const wits = tx.witness_set();
-    const vkeys = wits.vkeys();
-    const vkeyWitnessCount = vkeys ? vkeys.len() : 0;
-    const txHashBytes = CSL.FixedTransaction
-        .from_bytes(txBuf)
-        .transaction_hash()
-        .to_bytes();
-    const txHash = Buffer.from(txHashBytes).toString('hex').toLowerCase();
-    const validity = extractValidityRange(txBody);
+    const txHash = parsed.txHash.toLowerCase();
+    const vkeyWitnessCount = parsed.witnesses.vkeyCount;
+    const validity = extractValidityRange(parsed);
     const nonce = parseNonceRef(payload.nonce);
     const envelope = {
         x402Version: SUPPORTED_VERSION,
@@ -231,10 +142,10 @@ function decode(paymentHeader) {
     };
     return {
         envelope,
-        txCborHex: Buffer.from(txBuf).toString('hex'),
+        txCborHex,
         txHash,
-        outputs: extractOutputs(txBody),
-        inputs: extractInputs(txBody),
+        outputs: extractOutputs(parsed.outputs),
+        inputs: extractInputs(parsed.inputs),
         vkeyWitnessCount,
         ttlSlot: validity.ttlSlot,
         validityStartSlot: validity.validityStartSlot,

package/srv/helpers/address.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Minimal, CSL-free Shelley address introspection.
+ *
+ * The unsigned-tx builder needs two things from the buyer's bech32
+ * address that the (Buildooor-based) @odatano/core builder doesn't hand
+ * back: the payment-credential VKey hash (returned to the wallet as the
+ * `requiredSignerHex`), and a guard that the address is a Base/Enterprise
+ * key-cred address (script-cred and reward/stake addresses can't sign a
+ * normal spend). Rather than pull in a CBOR/address library, we decode
+ * the bech32 payload and read the 1-byte Shelley header directly.
+ *
+ * Shelley address header (CIP-19): the top nibble is the address type,
+ * the bottom nibble the network id. Payment credential is the 28 bytes
+ * following the header. Payment-cred kind by type:
+ *   0,2 base / 6 enterprise → key hash    (signable)
+ *   1,3 base / 7 enterprise → script hash (not signable)
+ *   4,5 pointer             → unsupported here
+ *   14,15 reward/stake      → not a payment address
+ */
+export interface ParsedPaymentAddress {
+    /** Buyer's payment-credential VKey hash (lowercase hex, 56 chars). */
+    paymentKeyHashHex: string;
+}
+/**
+ * Decode a bech32 Cardano address and extract its payment-credential
+ * VKey hash. Throws (with the same messages the old CSL path used) for
+ * malformed bech32, script-cred payment, or non-payment (reward/pointer)
+ * addresses.
+ */
+export declare function parsePaymentAddress(bech32Addr: string): ParsedPaymentAddress;
+//# sourceMappingURL=address.d.ts.map

package/srv/helpers/address.js

@@ -0,0 +1,57 @@
+"use strict";
+/**
+ * Minimal, CSL-free Shelley address introspection.
+ *
+ * The unsigned-tx builder needs two things from the buyer's bech32
+ * address that the (Buildooor-based) @odatano/core builder doesn't hand
+ * back: the payment-credential VKey hash (returned to the wallet as the
+ * `requiredSignerHex`), and a guard that the address is a Base/Enterprise
+ * key-cred address (script-cred and reward/stake addresses can't sign a
+ * normal spend). Rather than pull in a CBOR/address library, we decode
+ * the bech32 payload and read the 1-byte Shelley header directly.
+ *
+ * Shelley address header (CIP-19): the top nibble is the address type,
+ * the bottom nibble the network id. Payment credential is the 28 bytes
+ * following the header. Payment-cred kind by type:
+ *   0,2 base / 6 enterprise → key hash    (signable)
+ *   1,3 base / 7 enterprise → script hash (not signable)
+ *   4,5 pointer             → unsupported here
+ *   14,15 reward/stake      → not a payment address
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parsePaymentAddress = parsePaymentAddress;
+const bech32_1 = require("bech32");
+const PAYMENT_KEY_HASH_TYPES = new Set([0, 2, 6]); // base-key, base-key/script-stake, enterprise-key
+const SCRIPT_PAYMENT_TYPES = new Set([1, 3, 7]); // base-script*, enterprise-script
+/** Bech32 limit well above Cardano's longest (~103-char mainnet base addr). */
+const BECH32_LIMIT = 1023;
+/**
+ * Decode a bech32 Cardano address and extract its payment-credential
+ * VKey hash. Throws (with the same messages the old CSL path used) for
+ * malformed bech32, script-cred payment, or non-payment (reward/pointer)
+ * addresses.
+ */
+function parsePaymentAddress(bech32Addr) {
+    let bytes;
+    try {
+        const decoded = bech32_1.bech32.decode(bech32Addr, BECH32_LIMIT);
+        bytes = Uint8Array.from(bech32_1.bech32.fromWords(decoded.words));
+    }
+    catch {
+        throw new Error(`buildUnsignedPaymentTx: invalid bech32 address: ${bech32Addr}`);
+    }
+    // header (1 byte) + 28-byte payment credential.
+    if (bytes.length < 29) {
+        throw new Error(`buildUnsignedPaymentTx: invalid bech32 address: ${bech32Addr}`);
+    }
+    const addrType = bytes[0] >> 4;
+    if (SCRIPT_PAYMENT_TYPES.has(addrType)) {
+        throw new Error('buildUnsignedPaymentTx: payment credential must be a VKey hash, not a script');
+    }
+    if (!PAYMENT_KEY_HASH_TYPES.has(addrType)) {
+        // pointer (4,5), reward/stake (14,15), Byron-via-bech32, etc.
+        throw new Error('buildUnsignedPaymentTx: only Base / Enterprise addresses are supported');
+    }
+    const keyHash = bytes.slice(1, 29);
+    return { paymentKeyHashHex: Buffer.from(keyHash).toString('hex') };
+}

package/srv/helpers/build-unsigned-tx.d.ts

@@ -1,26 +1,27 @@
 /**
  * Server-side unsigned payment-tx builder for browser-buyer flows.
  *
- * The browser knows the buyer's bech32 (via CIP-30) but not the
- * signing keys. Replicating CSL coin-selection + protocol-params
- * fetch in the browser would mean shipping ~2 MB of WASM. So we
- * build the unsigned tx server-side, return the CBOR for the
- * wallet to sign, and let the browser submit the signed CBOR as
- * `payload.transaction` in the PAYMENT-SIGNATURE envelope.
+ * The browser knows the buyer's bech32 (via CIP-30) but not the signing
+ * keys, and shipping coin-selection + protocol-params logic to the
+ * browser would mean megabytes of WASM. So we build the unsigned tx
+ * server-side, return the CBOR for the wallet to sign, and let the
+ * browser submit the signed CBOR as `payload.transaction` in the
+ * PAYMENT-SIGNATURE envelope.
  *
- * Diff vs v1 of CHAINFEED's same-named helper:
- *   - Asset-agnostic, parses requirements.asset as a v2 string
- *     (`'lovelace'` or `'<policy>.<nameHex>'`).
- *   - Returns `nonceRef` alongside the unsigned CBOR, the server
- *     picks one of the buyer's chosen inputs as the v2 nonce UTxO,
- *     so the browser doesn't have to reason about it.
+ * The build itself (UTxO fetch, coin selection, change, min-ADA, fee) is
+ * delegated wholesale to `@odatano/core`'s Buildooor builder via
+ * `bridge.buildUnsignedTransfer`, x402 owns no tx-construction library.
+ * We add only the two x402-specific pieces core doesn't:
+ *   - the `requiredSignerHex` (buyer's payment-cred VKey hash), parsed
+ *     from the bech32 address (see `./address`);
+ *   - the v2 `nonceRef`, read back from the built tx's first input so it
+ *     is guaranteed to reference a UTxO the tx actually spends.
  *
- * **x402-spec deviation:** strict v2 has the buyer construct the
- * tx end-to-end. This helper is a "self-facilitator" pattern: the
- * server builds, the buyer signs, the server still validates the
- * signed tx against requirements before settling. Same security
- * model (the buyer's signature still authorises the spend), easier
- * browser ergonomics.
+ * **x402-spec deviation:** strict v2 has the buyer construct the tx
+ * end-to-end. This is the "self-facilitator" pattern: the server builds,
+ * the buyer signs, the server still validates the signed tx against
+ * requirements before settling. Same security model (the buyer's
+ * signature still authorises the spend), easier browser ergonomics.
  */
 import type { PaymentRequirementEntry } from '../core/types';
 export interface BuildUnsignedTxArgs {
@@ -29,7 +30,7 @@ export interface BuildUnsignedTxArgs {
     /** A single accepts[] entry, call `flatRequirements(body)` to extract. */
     requirements: PaymentRequirementEntry;
     /**
-     * Optional TTL in slots from "now" (= current chain tip slot).
+     * Optional TTL in slots from "now" (= current chain tip).
      * Default 1800 (≈30 min on Cardano's 1s-slot networks).
      */
     ttlSlotsFromNow?: number;
@@ -41,16 +42,16 @@ export interface UnsignedTxResult {
     txHashHex: string;
     /** Buyer's payment-cred VKey hash, wallet must sign for this. */
     requiredSignerHex: string;
-    /** v2 nonce reference `<txHash>#<index>`, picked from the buyer's chosen inputs. */
+    /** v2 nonce reference `<txHash>#<index>`, the tx's first spent input. */
     nonceRef: string;
-    /** Echo of the inputs chosen so the buyer's UI can show "spends these UTxOs". */
+    /** Echo of the inputs the builder selected so the buyer's UI can show "spends these UTxOs". */
     inputs: Array<{
         txHash: string;
         outputIndex: number;
         lovelace: string;
     }>;
-    /** TTL slot used for the validity-range upper bound. */
-    ttlSlot: number;
+    /** TTL slot used for the validity-range upper bound (as set by the builder). */
+    ttlSlot: number | null;
 }
 export declare function buildUnsignedPaymentTx(args: BuildUnsignedTxArgs): Promise<UnsignedTxResult>;
 //# sourceMappingURL=build-unsigned-tx.d.ts.map

package/srv/helpers/build-unsigned-tx.js

@@ -2,26 +2,27 @@
 /**
  * Server-side unsigned payment-tx builder for browser-buyer flows.
  *
- * The browser knows the buyer's bech32 (via CIP-30) but not the
- * signing keys. Replicating CSL coin-selection + protocol-params
- * fetch in the browser would mean shipping ~2 MB of WASM. So we
- * build the unsigned tx server-side, return the CBOR for the
- * wallet to sign, and let the browser submit the signed CBOR as
- * `payload.transaction` in the PAYMENT-SIGNATURE envelope.
+ * The browser knows the buyer's bech32 (via CIP-30) but not the signing
+ * keys, and shipping coin-selection + protocol-params logic to the
+ * browser would mean megabytes of WASM. So we build the unsigned tx
+ * server-side, return the CBOR for the wallet to sign, and let the
+ * browser submit the signed CBOR as `payload.transaction` in the
+ * PAYMENT-SIGNATURE envelope.
  *
- * Diff vs v1 of CHAINFEED's same-named helper:
- *   - Asset-agnostic, parses requirements.asset as a v2 string
- *     (`'lovelace'` or `'<policy>.<nameHex>'`).
- *   - Returns `nonceRef` alongside the unsigned CBOR, the server
- *     picks one of the buyer's chosen inputs as the v2 nonce UTxO,
- *     so the browser doesn't have to reason about it.
+ * The build itself (UTxO fetch, coin selection, change, min-ADA, fee) is
+ * delegated wholesale to `@odatano/core`'s Buildooor builder via
+ * `bridge.buildUnsignedTransfer`, x402 owns no tx-construction library.
+ * We add only the two x402-specific pieces core doesn't:
+ *   - the `requiredSignerHex` (buyer's payment-cred VKey hash), parsed
+ *     from the bech32 address (see `./address`);
+ *   - the v2 `nonceRef`, read back from the built tx's first input so it
+ *     is guaranteed to reference a UTxO the tx actually spends.
  *
- * **x402-spec deviation:** strict v2 has the buyer construct the
- * tx end-to-end. This helper is a "self-facilitator" pattern: the
- * server builds, the buyer signs, the server still validates the
- * signed tx against requirements before settling. Same security
- * model (the buyer's signature still authorises the spend), easier
- * browser ergonomics.
+ * **x402-spec deviation:** strict v2 has the buyer construct the tx
+ * end-to-end. This is the "self-facilitator" pattern: the server builds,
+ * the buyer signs, the server still validates the signed tx against
+ * requirements before settling. Same security model (the buyer's
+ * signature still authorises the spend), easier browser ergonomics.
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -58,146 +59,60 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildUnsignedPaymentTx = buildUnsignedPaymentTx;
-const CSL = __importStar(require("@emurgo/cardano-serialization-lib-nodejs"));
 const bridge = __importStar(require("../bridge"));
 const asset_1 = require("../core/asset");
+const address_1 = require("./address");
+/** ADA (lovelace) attached to a native-asset output to satisfy min-ADA. */
+const TOKEN_OUTPUT_LOVELACE = 2000000n;
+/** Cardano networks run 1-second slots, so TTL slots ≈ TTL seconds. */
+const SLOT_MS = 1000;
 async function buildUnsignedPaymentTx(args) {
     const { buyerBech32, requirements } = args;
-    // 1. Decode buyer address; derive payment-cred VKey hash.
-    let buyerAddress;
-    try {
-        buyerAddress = CSL.Address.from_bech32(buyerBech32);
-    }
-    catch {
-        throw new Error(`buildUnsignedPaymentTx: invalid bech32 address: ${buyerBech32}`);
-    }
-    const baseAddr = CSL.BaseAddress.from_address(buyerAddress);
-    const enterpriseAddr = CSL.EnterpriseAddress.from_address(buyerAddress);
-    const paymentCred = baseAddr?.payment_cred() ?? enterpriseAddr?.payment_cred();
-    if (!paymentCred) {
-        throw new Error('buildUnsignedPaymentTx: only Base / Enterprise addresses are supported');
-    }
-    const buyerVkeyHash = paymentCred.to_keyhash();
-    if (!buyerVkeyHash) {
-        throw new Error('buildUnsignedPaymentTx: payment credential must be a VKey hash, not a script');
-    }
-    const requiredSignerHex = Buffer.from(buyerVkeyHash.to_bytes()).toString('hex');
-    // 2. Fetch buyer UTxOs + protocol params + current slot in parallel.
-    const [utxos, params, currentSlot] = await Promise.all([
-        bridge.getUtxosAtAddress(buyerBech32),
-        bridge.getProtocolParameters(),
-        bridge.getCurrentSlot(),
-    ]);
-    if (utxos.length === 0) {
-        throw new Error(`buildUnsignedPaymentTx: no UTxOs at ${buyerBech32}`);
-    }
-    // 3. Pick the input(s) for coin-selection.
-    //    Strategy:
-    //      - If lovelace asset: pick largest-ADA UTxO; add second-largest as padding if first < 3 ADA.
-    //      - If native asset:   pick largest-ADA UTxO that ALSO holds enough of the asset;
-    //                           add padding the same way.
+    // 1. Validate the buyer address shape and derive the required signer.
+    //    Throws for bad bech32 / script-cred / non-payment addresses.
+    const { paymentKeyHashHex } = (0, address_1.parsePaymentAddress)(buyerBech32);
+    // 2. Translate the v2 requirement into a core transfer request.
     const parsedAsset = (0, asset_1.parseAsset)(requirements.asset);
     const required = BigInt(requirements.amount);
-    const sortedByAda = [...utxos].sort((a, b) => (BigInt(b.lovelace) - BigInt(a.lovelace) > 0n ? 1 : -1));
-    let inputs;
-    if (parsedAsset.isLovelace) {
-        // ADA payment: largest UTxO must cover required + fees + min-ADA change.
-        // Heuristic: required + 2_000_000 (≈2 ADA fee+change headroom).
-        const headroom = required + 2000000n;
-        const ok = sortedByAda.find(u => BigInt(u.lovelace) >= headroom);
-        if (!ok) {
-            throw new Error(`buildUnsignedPaymentTx: no UTxO at ${buyerBech32} with ≥ ${headroom} lovelace`);
-        }
-        inputs = [ok];
-    }
-    else {
-        const candidates = sortedByAda.filter(u => u.assets.some(a => a.unit === parsedAsset.unit && BigInt(a.quantity) >= required));
-        if (candidates.length === 0) {
-            throw new Error(`buildUnsignedPaymentTx: no UTxO at ${buyerBech32} holds ≥ ${required} of ${parsedAsset.unit}`);
+    const validityEndMs = Date.now() + (args.ttlSlotsFromNow ?? 1800) * SLOT_MS;
+    const req = parsedAsset.isLovelace
+        ? {
+            senderAddress: buyerBech32,
+            recipientAddress: requirements.payTo,
+            changeAddress: buyerBech32,
+            lovelaceAmount: required.toString(),
+            validityEndMs,
         }
-        const tokenInput = candidates[0];
-        inputs = [tokenInput];
-        if (BigInt(tokenInput.lovelace) < 3000000n) {
-            const padding = sortedByAda.find(u => u !== tokenInput);
-            if (!padding) {
-                throw new Error('buildUnsignedPaymentTx: no second UTxO available to fund fees');
-            }
-            inputs.push(padding);
-        }
-    }
-    // 4. Configure CSL TransactionBuilder from live protocol params.
-    const builder = CSL.TransactionBuilder.new(CSL.TransactionBuilderConfigBuilder.new()
-        .fee_algo(CSL.LinearFee.new(CSL.BigNum.from_str(String(params.minFeeA)), CSL.BigNum.from_str(String(params.minFeeB))))
-        .pool_deposit(CSL.BigNum.from_str(String(params.poolDeposit)))
-        .key_deposit(CSL.BigNum.from_str(String(params.keyDeposit)))
-        .max_value_size(Number(params.maxValSize))
-        .max_tx_size(Number(params.maxTxSize))
-        .coins_per_utxo_byte(CSL.BigNum.from_str(String(params.coinsPerUtxoSize)))
-        .build());
-    // 5. Wire inputs (preserve full multi-asset payload).
-    for (const u of inputs) {
-        const inMa = CSL.MultiAsset.new();
-        const byPolicy = new Map();
-        for (const a of u.assets) {
-            const arr = byPolicy.get(a.policyId) ?? [];
-            arr.push({ name: a.assetNameHex, qty: a.quantity });
-            byPolicy.set(a.policyId, arr);
-        }
-        for (const [policyHex, items] of byPolicy) {
-            const policyHash = CSL.ScriptHash.from_bytes(Buffer.from(policyHex, 'hex'));
-            const assetMap = CSL.Assets.new();
-            for (const { name, qty } of items) {
-                assetMap.insert(CSL.AssetName.new(Buffer.from(name, 'hex')), CSL.BigNum.from_str(qty));
-            }
-            inMa.insert(policyHash, assetMap);
-        }
-        const inV = CSL.Value.new(CSL.BigNum.from_str(u.lovelace));
-        if (u.assets.length)
-            inV.set_multiasset(inMa);
-        builder.add_key_input(buyerVkeyHash, CSL.TransactionInput.new(CSL.TransactionHash.from_bytes(Buffer.from(u.txHash, 'hex')), u.outputIndex), inV);
-    }
-    // 6. Output to payTo.
-    const payToAddr = CSL.Address.from_bech32(requirements.payTo);
-    let payOut;
-    if (parsedAsset.isLovelace) {
-        const v = CSL.Value.new(CSL.BigNum.from_str(required.toString()));
-        payOut = CSL.TransactionOutput.new(payToAddr, v);
-    }
-    else {
-        const payOutMa = CSL.MultiAsset.new();
-        const payAssets = CSL.Assets.new();
-        const policyHash = CSL.ScriptHash.from_bytes(Buffer.from(parsedAsset.policyId, 'hex'));
-        payAssets.insert(CSL.AssetName.new(Buffer.from(parsedAsset.assetNameHex, 'hex')), CSL.BigNum.from_str(required.toString()));
-        payOutMa.insert(policyHash, payAssets);
-        const payOutV = CSL.Value.new(CSL.BigNum.from_str('0'));
-        payOutV.set_multiasset(payOutMa);
-        const provisional = CSL.TransactionOutput.new(payToAddr, payOutV);
-        const minAda = CSL.min_ada_for_output(provisional, CSL.DataCost.new_coins_per_byte(CSL.BigNum.from_str(String(params.coinsPerUtxoSize))));
-        payOutV.set_coin(minAda);
-        payOut = CSL.TransactionOutput.new(payToAddr, payOutV);
+        : {
+            senderAddress: buyerBech32,
+            recipientAddress: requirements.payTo,
+            changeAddress: buyerBech32,
+            // Native-asset output rides a fixed min-ADA; change reconciles the rest.
+            lovelaceAmount: TOKEN_OUTPUT_LOVELACE.toString(),
+            assets: [{ unit: parsedAsset.unit, quantity: required.toString() }],
+            validityEndMs,
+        };
+    // 3. Delegate the build (UTxO fetch + coin selection + change + fee).
+    const result = await bridge.buildUnsignedTransfer(req);
+    // 4. Read the built tx back to recover the v2 nonce (first spent input,
+    //    guaranteed present) and the TTL slot the builder actually set.
+    const parsed = bridge.parseTransaction(result.unsignedTxCbor);
+    const nonceInput = parsed.inputs[0];
+    if (!nonceInput) {
+        throw new Error('buildUnsignedPaymentTx: builder produced a tx with no inputs');
     }
-    builder.add_output(payOut);
-    // 7. TTL (slot of upper bound). Default 1800 slots ≈ 30 min.
-    const ttlSlot = currentSlot + (args.ttlSlotsFromNow ?? 1800);
-    builder.set_ttl_bignum(CSL.BigNum.from_str(String(ttlSlot)));
-    // 8. Change to buyer.
-    builder.add_change_if_needed(buyerAddress);
-    // 9. Build body, compute hash, return unsigned tx.
-    const txBody = builder.build();
-    const txHash = CSL.FixedTransaction.new_from_body_bytes(txBody.to_bytes()).transaction_hash();
-    const emptyWits = CSL.TransactionWitnessSet.new();
-    const unsigned = CSL.Transaction.new(txBody, emptyWits);
-    // Pick the first input as the v2 nonce UTxO.
-    // It MUST appear in tx.inputs (which it does by construction) and be
-    // unspent (which it is, we just queried it from the buyer's UTxO set).
-    const nonceInput = inputs[0];
     const nonceRef = `${nonceInput.txHash}#${nonceInput.outputIndex}`;
+    const ttlSlot = parsed.validityEnd != null ? Number(parsed.validityEnd) : null;
     return {
-        unsignedTxCborHex: Buffer.from(unsigned.to_bytes()).toString('hex'),
-        txHashHex: Buffer.from(txHash.to_bytes()).toString('hex').toLowerCase(),
-        requiredSignerHex,
+        unsignedTxCborHex: result.unsignedTxCbor,
+        txHashHex: result.txBodyHash.toLowerCase(),
+        requiredSignerHex: paymentKeyHashHex,
         nonceRef,
-        inputs: inputs.map(i => ({ txHash: i.txHash, outputIndex: i.outputIndex, lovelace: i.lovelace })),
+        inputs: result.inputs.map(i => ({
+            txHash: i.txHash,
+            outputIndex: i.index,
+            lovelace: i.lovelace,
+        })),
         ttlSlot,
     };
 }