@koralabs/kora-labs-common 6.16.0 → 6.18.0

package/chain/transport/fetchProviderJson.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.fetchProviderJson = exports.isRetriableError = void 0;
+exports.fetchProviderJson = exports.isRetriableError = exports.providerNotFoundError = void 0;
 const utils_1 = require("../../utils");
 const rateLimit_1 = require("./rateLimit");
 const DEFAULT_MAX_RPS = 5;
@@ -104,6 +104,9 @@ const createProviderError = ({ provider, status, statusText, payload, responseTe
     }
     return error;
 };
+/** A provider's "that does not exist" answer, shaped like a transport 404 (`status: 404`). */
+const providerNotFoundError = (provider, what) => createProviderError({ provider, status: 404, statusText: `${what} not found` });
+exports.providerNotFoundError = providerNotFoundError;
 const messageLooksRetriable = (value) => RETRIABLE_MESSAGE_SNIPPETS.some((snippet) => value.includes(snippet));
 const isRetriableError = (provider, error) => {
     var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@koralabs/kora-labs-common",
-    "version": "6.16.0",
+    "version": "6.18.0",
     "description": "Kora Labs Common Utilities",
     "main": "index.js",
     "types": "index.d.ts",

package/testing/blockfrost.d.ts

@@ -0,0 +1,12 @@
+export type LiveNetwork = 'preview' | 'preprod' | 'mainnet';
+export interface BlockfrostAccess {
+    network: LiveNetwork;
+    blockfrostApiKey: string;
+    /** Injectable for tests. Defaults to global fetch. */
+    fetchFn?: typeof fetch;
+}
+export declare const blockfrostBaseUrl: (network: LiveNetwork) => string;
+/** GET `path`; null when Blockfrost answers 404 (never used / not on chain yet). */
+export declare const blockfrostGet: <T>(access: BlockfrostAccess, path: string) => Promise<T | null>;
+/** POST a signed tx to `/tx/submit`; resolves to the tx hash, or throws with the node's reason. */
+export declare const blockfrostSubmit: (access: BlockfrostAccess, signedTxCbor: string) => Promise<string>;

package/testing/blockfrost.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.blockfrostSubmit = exports.blockfrostGet = exports.blockfrostBaseUrl = void 0;
+/**
+ * Blockfrost access for the live-suite harness. Every call goes through the shared rate-limited
+ * transport (`chain/transport/fetchProviderJson`): a stated wait (Retry-After and friends) is
+ * remembered process-wide and never undercut, and a wait too long to sit out surfaces as
+ * `RateLimitedError` instead of a retry.
+ */
+const fetchProviderJson_1 = require("../chain/transport/fetchProviderJson");
+const blockfrostBaseUrl = (network) => `https://cardano-${network}.blockfrost.io/api/v0`;
+exports.blockfrostBaseUrl = blockfrostBaseUrl;
+const request = (access, path, init = {}) => {
+    var _a;
+    return (0, fetchProviderJson_1.fetchProviderJson)({
+        provider: 'Blockfrost',
+        url: `${(0, exports.blockfrostBaseUrl)(access.network)}${path}`,
+        method: (_a = init.method) !== null && _a !== void 0 ? _a : 'GET',
+        headers: { project_id: access.blockfrostApiKey, ...(init.contentType ? { 'Content-Type': init.contentType } : {}) },
+        body: init.body,
+        fetcher: access.fetchFn
+    });
+};
+/** GET `path`; null when Blockfrost answers 404 (never used / not on chain yet). */
+const blockfrostGet = async (access, path) => {
+    try {
+        return await request(access, path);
+    }
+    catch (error) {
+        if (error.status === 404)
+            return null;
+        throw error;
+    }
+};
+exports.blockfrostGet = blockfrostGet;
+/** POST a signed tx to `/tx/submit`; resolves to the tx hash, or throws with the node's reason. */
+const blockfrostSubmit = async (access, signedTxCbor) => {
+    var _a, _b, _c;
+    try {
+        return await request(access, '/tx/submit', { method: 'POST', body: Buffer.from(signedTxCbor, 'hex'), contentType: 'application/cbor' });
+    }
+    catch (error) {
+        const e = error;
+        if (e.status === undefined)
+            throw error;
+        throw new Error(`Submit failed: ${e.status} ${(_c = (_b = (_a = e.blockfrostResponse) === null || _a === void 0 ? void 0 : _a.message) !== null && _b !== void 0 ? _b : e.responseText) !== null && _c !== void 0 ? _c : ''}`.trim(), { cause: error });
+    }
+};
+exports.blockfrostSubmit = blockfrostSubmit;

package/testing/index.d.ts

@@ -1,3 +1,4 @@
+export * from './blockfrost';
 export * from './liveWallet';
 export * from './installWallet';
 export * from './readOnlyGuard';

package/testing/index.js

@@ -17,6 +17,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 // Subpath module: `@koralabs/kora-labs-common/testing`. Node-only harness for live CIP-30 browser
 // journey suites. NOT re-exported from the root index. Requires the optional peer dependencies
 // @cardano-sdk/core, @cardano-sdk/crypto, bip39 (and @emurgo/cardano-message-signing-nodejs for signData).
+__exportStar(require("./blockfrost"), exports);
 __exportStar(require("./liveWallet"), exports);
 __exportStar(require("./installWallet"), exports);
 __exportStar(require("./readOnlyGuard"), exports);

package/testing/liveWallet.d.ts

@@ -1,4 +1,4 @@
-export type LiveNetwork = 'preview' | 'preprod' | 'mainnet';
+import { LiveNetwork } from './blockfrost';
 export interface LiveWalletConfig {
     mnemonic: string;
     network: LiveNetwork;
@@ -10,6 +10,17 @@ export interface LiveWalletConfig {
     /** Injectable for tests. Defaults to global fetch. */
     fetchFn?: typeof fetch;
 }
+/** One tx this wallet submitted, with the chaining facts a suite asserts on. */
+export interface LiveSubmission {
+    txHash: string;
+    /** Local clock (ms) when the submission was accepted. */
+    submittedAt: number;
+    /**
+     * Inputs (`txHash#index`) that were outputs of this wallet's OWN earlier submissions that were not
+     * in a block yet when this tx was submitted — i.e. the tx is chained on unconfirmed change.
+     */
+    chainedInputs: string[];
+}
 export interface LiveWallet {
     address: string;
     addressHex: string;
@@ -21,7 +32,10 @@ export interface LiveWallet {
     dRepId: string;
     call: (method: string, params?: unknown) => Promise<unknown>;
     submittedTxHashes: string[];
+    /** Every accepted submission, in order (`submittedTxHashes` is the hash-only view). */
+    submissions: LiveSubmission[];
+    /** Hashes of submitted txs this wallet has not yet seen in a block. */
+    pendingTxHashes: () => string[];
     countUtxos: () => Promise<number>;
 }
-export declare const blockfrostBaseUrl: (network: LiveNetwork) => string;
 export declare const createLiveWallet: (config: LiveWalletConfig) => Promise<LiveWallet>;

package/testing/liveWallet.js

@@ -33,13 +33,17 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createLiveWallet = exports.blockfrostBaseUrl = void 0;
+exports.createLiveWallet = void 0;
 /**
  * Live CIP-30 wallet emulator for browser journey suites (Playwright).
  *
  * Real keys derived from a mnemonic (CIP-1852), real UTxOs from Blockfrost, real signatures, real
  * submission. It behaves like a real CIP-30 wallet on purpose:
  *   - getUtxos returns the FULL paginated UTxO set (no hidden/"parked" collateral),
+ *   - it CHAINS like Eternl/Lace: once it has submitted a tx, getUtxos (and getBalance, and the
+ *     signing-key choice) return that tx's outputs to this wallet and drop the inputs it spent, until
+ *     the tx is in a block — then chain truth takes over. A dapp therefore receives UTxOs that exist
+ *     on no provider yet, exactly as real users' wallets hand them over (HAL minting depends on it),
  *   - getCollateral returns null (the common real-wallet case — the app must resolve collateral),
  *   - signTx returns a witness set holding ONLY this wallet's vkey witnesses (the app merges it),
  *   - signTx refuses non-canonical tx structure (hardware wallets / Eternl do).
@@ -48,6 +52,7 @@ exports.createLiveWallet = exports.blockfrostBaseUrl = void 0;
 const blakejs_1 = require("blakejs");
 const bech32_1 = require("bech32");
 const tx_1 = require("../tx");
+const blockfrost_1 = require("./blockfrost");
 const HARDENED = 0x80000000;
 let sdkPromise = null;
 // @cardano-sdk/crypto ships its own nested libsodium-wrappers-sumo; it must be `ready` before any
@@ -67,15 +72,12 @@ const loadSdk = () => {
     })());
     return sdkPromise;
 };
-const blockfrostBaseUrl = (network) => `https://cardano-${network}.blockfrost.io/api/v0`;
-exports.blockfrostBaseUrl = blockfrostBaseUrl;
 const createLiveWallet = async (config) => {
-    var _a, _b;
+    var _a;
     const { Cardano, Serialization, Crypto, bip39 } = await loadSdk();
-    const doFetch = (_a = config.fetchFn) !== null && _a !== void 0 ? _a : fetch;
+    const access = { network: config.network, blockfrostApiKey: config.blockfrostApiKey, fetchFn: config.fetchFn };
     const networkId = config.network === 'mainnet' ? 1 : 0;
-    const base = (0, exports.blockfrostBaseUrl)(config.network);
-    const account = (_b = config.accountIndex) !== null && _b !== void 0 ? _b : 0;
+    const account = (_a = config.accountIndex) !== null && _a !== void 0 ? _a : 0;
     const root = Crypto.Bip32PrivateKey.fromBip39Entropy(Buffer.from(bip39.mnemonicToEntropy(config.mnemonic), 'hex'), '');
     const accountKey = root.derive([1852 + HARDENED, 1815 + HARDENED, account + HARDENED]);
     const paymentKey = accountKey.derive([0, 0]).toRawKey();
@@ -96,25 +98,17 @@ const createLiveWallet = async (config) => {
     const dRepPubKeyHex = stakeKey.toPublic().hex();
     const dRepKeyHash = (0, blakejs_1.blake2b)(Buffer.from(dRepPubKeyHex, 'hex'), undefined, 28);
     const dRepId = bech32_1.bech32.encode('drep', bech32_1.bech32.toWords(Uint8Array.from([0x22, ...dRepKeyHash])), 128);
+    const ownAddresses = new Set([address, enterpriseStakeAddress]);
     const submittedTxHashes = [];
-    const fetchBlockfrost = async (path) => {
-        const res = await doFetch(`${base}${path}`, { headers: { project_id: config.blockfrostApiKey } });
-        if (!res.ok)
-            throw new Error(`Blockfrost ${path}: ${res.status} ${(await res.text()).slice(0, 200)}`);
-        return res;
-    };
+    const submissions = [];
+    const pending = new Map();
     const fetchAddressUtxos = async (addr) => {
         const all = [];
         for (let page = 1;; page++) {
-            const res = await doFetch(`${base}/addresses/${addr}/utxos?count=100&page=${page}`, {
-                headers: { project_id: config.blockfrostApiKey }
-            });
-            // 404 = the address has never been used — an empty set, not an error.
-            if (res.status === 404)
+            // null (404) = the address has never been used — an empty set, not an error.
+            const batch = await (0, blockfrost_1.blockfrostGet)(access, `/addresses/${addr}/utxos?count=100&page=${page}`);
+            if (!batch)
                 break;
-            if (!res.ok)
-                throw new Error(`Blockfrost /addresses/${addr}/utxos: ${res.status} ${(await res.text()).slice(0, 200)}`);
-            const batch = (await res.json());
             for (const u of batch)
                 u._sourceAddr = addr;
             all.push(...batch);
@@ -138,30 +132,50 @@ const createLiveWallet = async (config) => {
         };
         return new Serialization.TransactionUnspentOutput(Serialization.TransactionInput.fromCore({ txId: u.tx_hash, index: u.output_index }), Serialization.TransactionOutput.fromCore(output)).toCbor();
     };
-    const getUtxos = async () => {
-        const utxos = [...(await fetchAddressUtxos(address)), ...(await fetchAddressUtxos(enterpriseStakeAddress))];
-        return utxos.map(utxoToCborHex);
+    /** A pending tx that is now in a block leaves the overlay: chain truth takes over. */
+    const settlePending = async () => {
+        for (const txHash of [...pending.keys()]) {
+            if (await (0, blockfrost_1.blockfrostGet)(access, `/txs/${txHash}`))
+                pending.delete(txHash);
+        }
+    };
+    /** The wallet's own view: chain UTxOs, minus what its pending txs spent, plus their unspent change. */
+    const ownUtxos = async () => {
+        var _a, _b, _c;
+        await settlePending();
+        const chainUtxos = [...(await fetchAddressUtxos(address)), ...(await fetchAddressUtxos(enterpriseStakeAddress))];
+        const spent = new Set([...pending.values()].flatMap((p) => [...p.spends]));
+        const view = new Map();
+        for (const u of chainUtxos) {
+            const ref = `${u.tx_hash}#${u.output_index}`;
+            if (spent.has(ref))
+                continue;
+            view.set(ref, { cbor: utxoToCborHex(u), address: (_a = u._sourceAddr) !== null && _a !== void 0 ? _a : address, lovelace: BigInt((_c = (_b = u.amount.find((a) => a.unit === 'lovelace')) === null || _b === void 0 ? void 0 : _b.quantity) !== null && _c !== void 0 ? _c : '0') });
+        }
+        for (const p of pending.values()) {
+            for (const [ref, out] of p.outputs)
+                if (!spent.has(ref))
+                    view.set(ref, out);
+        }
+        return view;
     };
+    const getUtxos = async () => [...(await ownUtxos()).values()].map((u) => u.cbor);
     const getBalance = async () => {
-        const utxos = await fetchAddressUtxos(address);
-        const coins = utxos.reduce((sum, u) => { var _a, _b; return sum + BigInt((_b = (_a = u.amount.find((a) => a.unit === 'lovelace')) === null || _a === void 0 ? void 0 : _a.quantity) !== null && _b !== void 0 ? _b : '0'); }, BigInt(0));
+        const coins = [...(await ownUtxos()).values()].filter((u) => u.address === address).reduce((sum, u) => sum + u.lovelace, BigInt(0));
         return Serialization.Value.fromCore({ coins }).toCbor();
     };
-    // The stake key must sign when it is a required signer, or when the tx spends/collateralizes a
-    // UTxO whose PAYMENT credential is the stake key (EnterpriseAddress(stakeCredential)).
+    // The stake key must sign when it is a required signer, or when the tx spends/collateralizes one of
+    // this wallet's UTxOs whose PAYMENT credential is the stake key (EnterpriseAddress(stakeCredential)).
+    // Resolved from the wallet's own view, like a real wallet: chained inputs are on no provider yet.
     const needsStakeKeySignature = async (body) => {
-        var _a, _b, _c, _d;
+        var _a, _b, _c;
         if (((_a = body.requiredExtraSignatures) !== null && _a !== void 0 ? _a : []).some((s) => s === stakeKeyHash))
             return true;
         const inputs = [...((_b = body.inputs) !== null && _b !== void 0 ? _b : []), ...((_c = body.collaterals) !== null && _c !== void 0 ? _c : [])];
-        for (const input of inputs) {
-            const res = await fetchBlockfrost(`/txs/${input.txId}/utxos`);
-            const json = (await res.json());
-            const out = (_d = json.outputs) === null || _d === void 0 ? void 0 : _d.find((o, i) => { var _a; return ((_a = o.output_index) !== null && _a !== void 0 ? _a : i) === input.index; });
-            if ((out === null || out === void 0 ? void 0 : out.address) === enterpriseStakeAddress)
-                return true;
-        }
-        return false;
+        if (inputs.length === 0)
+            return false;
+        const view = await ownUtxos();
+        return inputs.some((input) => { var _a; return ((_a = view.get(`${input.txId}#${input.index}`)) === null || _a === void 0 ? void 0 : _a.address) === enterpriseStakeAddress; });
     };
     const signTx = async (txCborHex) => {
         (0, tx_1.assertCanonicalCbor)(txCborHex, 'signTx');
@@ -181,6 +195,23 @@ const createLiveWallet = async (config) => {
             out.push(await signTx(typeof entry === 'string' ? entry : ((_a = entry.cbor) !== null && _a !== void 0 ? _a : entry.tx)));
         return out;
     };
+    /** Record an accepted submission: its spent inputs leave the view, its own outputs join it. */
+    const trackSubmitted = (txHash, signedTxCbor) => {
+        const body = Serialization.Transaction.fromCbor(signedTxCbor).body();
+        const spends = new Set(body.inputs().values().map((i) => `${i.transactionId()}#${Number(i.index())}`));
+        const chainedInputs = [...spends].filter((ref) => pending.has(ref.split('#')[0]));
+        const outputs = new Map();
+        body.outputs().forEach((output, index) => {
+            const outAddress = output.address().toBech32();
+            if (!ownAddresses.has(outAddress))
+                return;
+            const cbor = new Serialization.TransactionUnspentOutput(Serialization.TransactionInput.fromCore({ txId: txHash, index }), output).toCbor();
+            outputs.set(`${txHash}#${index}`, { cbor, address: outAddress, lovelace: output.amount().coin() });
+        });
+        pending.set(txHash, { spends, outputs });
+        submittedTxHashes.push(txHash);
+        submissions.push({ txHash, submittedAt: Date.now(), chainedInputs });
+    };
     const submitTx = async (signedTxCbor) => {
         if (config.submitDumpDir) {
             const fs = await Promise.resolve().then(() => __importStar(require('node:fs')));
@@ -188,29 +219,14 @@ const createLiveWallet = async (config) => {
             fs.mkdirSync(config.submitDumpDir, { recursive: true });
             fs.writeFileSync(path.join(config.submitDumpDir, `submit-${Date.now()}.cbor.hex`), signedTxCbor);
         }
-        // Retry only transient failures (429/5xx). Any other 4xx is a real ledger rejection and
-        // surfaces immediately with Blockfrost's full reason.
-        const backoffsMs = [0, 1000, 4000, 10000];
-        let lastError = '';
-        for (const wait of backoffsMs) {
-            if (wait)
-                await new Promise((r) => setTimeout(r, wait));
-            const res = await doFetch(`${base}/tx/submit`, {
-                method: 'POST',
-                headers: { project_id: config.blockfrostApiKey, 'Content-Type': 'application/cbor' },
-                body: Buffer.from(signedTxCbor, 'hex')
-            });
-            const text = await res.text();
-            if (res.ok) {
-                const hash = text.replace(/"/g, '');
-                submittedTxHashes.push(hash);
-                return hash;
-            }
-            lastError = `${res.status} ${text.slice(0, 4000)}`;
-            if (!(res.status === 429 || res.status >= 500))
-                break;
-        }
-        throw new Error(`Submit failed: ${lastError}`);
+        // Transient failures (5xx) are retried by the transport; rate limits wait exactly the stated
+        // time; any other 4xx is a real ledger rejection and surfaces with Blockfrost's reason.
+        const hash = await (0, blockfrost_1.blockfrostSubmit)(access, signedTxCbor);
+        const expected = (0, tx_1.txHashFromCbor)(signedTxCbor);
+        if (hash !== expected)
+            throw new Error(`Submit returned ${hash} for tx ${expected}`);
+        trackSubmitted(hash, signedTxCbor);
+        return hash;
     };
     // CIP-8 COSE_Sign1 over the payload with the payment key (CIP-30 signData).
     const signData = async (addrHex, payloadHex) => {
@@ -279,7 +295,9 @@ const createLiveWallet = async (config) => {
         dRepId,
         call,
         submittedTxHashes,
-        countUtxos: async () => (await fetchAddressUtxos(address)).length
+        submissions,
+        pendingTxHashes: () => [...pending.keys()],
+        countUtxos: async () => [...(await ownUtxos()).values()].filter((u) => u.address === address).length
     };
 };
 exports.createLiveWallet = createLiveWallet;

package/testing/onChain.d.ts

@@ -1,14 +1,10 @@
-import { LiveNetwork } from './liveWallet';
+import { BlockfrostAccess } from './blockfrost';
 export declare const LBL_222 = "000de140";
 export declare const LBL_100 = "000643b0";
 export declare const LBL_000 = "00000000";
 export declare const LBL_444 = "001bc280";
 export declare const hexOf: (s: string) => string;
-export interface ChainConfig {
-    network: LiveNetwork;
-    blockfrostApiKey: string;
-    fetchFn?: typeof fetch;
-}
+export type ChainConfig = BlockfrostAccess;
 export interface TxUtxoOutput {
     address: string;
     amount: {

package/testing/onChain.js

@@ -6,22 +6,23 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.cip68Field = exports.fetchCip68ExtraFromTx = exports.fetchOutputDatumCbor = exports.assertAdaTransfer = exports.assertAssetBurned = exports.assertCip68Label = exports.waitForOutputConsumed = exports.waitForTxConfirmation = exports.lovelaceOf = exports.fetchTxUtxos = exports.hexOf = exports.LBL_444 = exports.LBL_000 = exports.LBL_100 = exports.LBL_222 = void 0;
 /**
  * On-chain EFFECT assertions for live journey suites. Chain truth via Blockfrost — never the
- * indexer or the UI. Each assertion throws on mismatch so the calling scope fails.
+ * indexer or the UI. Each assertion throws on mismatch so the calling scope fails. Blockfrost is
+ * reached through the shared rate-limited transport (./blockfrost).
  */
 const cbor_1 = __importDefault(require("cbor"));
-const liveWallet_1 = require("./liveWallet");
+const rateLimit_1 = require("../chain/transport/rateLimit");
+const blockfrost_1 = require("./blockfrost");
 exports.LBL_222 = '000de140'; // CIP-68 user/owner NFT
 exports.LBL_100 = '000643b0'; // CIP-68 reference token
 exports.LBL_000 = '00000000'; // virtual subhandle token
 exports.LBL_444 = '001bc280'; // CIP-68 RFT
 const hexOf = (s) => Buffer.from(s, 'utf8').toString('hex');
 exports.hexOf = hexOf;
-const get = async (chain, path) => { var _a; return ((_a = chain.fetchFn) !== null && _a !== void 0 ? _a : fetch)(`${(0, liveWallet_1.blockfrostBaseUrl)(chain.network)}${path}`, { headers: { project_id: chain.blockfrostApiKey } }); };
 const getJson = async (chain, path) => {
-    const res = await get(chain, path);
-    if (!res.ok)
-        throw new Error(`onChain: GET ${path} failed (${res.status})`);
-    return (await res.json());
+    const found = await (0, blockfrost_1.blockfrostGet)(chain, path);
+    if (found === null)
+        throw new Error(`onChain: GET ${path} failed (404)`);
+    return found;
 };
 const fetchTxUtxos = (chain, txHash) => getJson(chain, `/txs/${txHash}/utxos`);
 exports.fetchTxUtxos = fetchTxUtxos;
@@ -31,11 +32,14 @@ exports.lovelaceOf = lovelaceOf;
 const waitForTxConfirmation = async (chain, txHash, timeoutMs = 180000, pollMs = 5000) => {
     const start = Date.now();
     for (;;) {
-        const res = await get(chain, `/txs/${txHash}`).catch(() => null);
-        if (res === null || res === void 0 ? void 0 : res.ok) {
-            const data = (await res.json());
+        // A transient provider failure is another poll; a rate limit too long to sit out is returned.
+        const data = await (0, blockfrost_1.blockfrostGet)(chain, `/txs/${txHash}`).catch((error) => {
+            if (error instanceof rateLimit_1.RateLimitedError)
+                throw error;
+            return null;
+        });
+        if (data)
             return { confirmed: true, block: data.block, validContract: data.valid_contract };
-        }
         if (Date.now() - start >= timeoutMs)
             return { confirmed: false };
         await new Promise((r) => setTimeout(r, pollMs));
@@ -62,31 +66,27 @@ exports.waitForOutputConsumed = waitForOutputConsumed;
 const assertCip68Label = async (chain, policyId, name, opts) => {
     var _a, _b;
     const nameHex = (0, exports.hexOf)(name);
-    const present = await get(chain, `/assets/${policyId}${opts.hasLabel}${nameHex}`);
-    if (!present.ok)
-        throw new Error(`onChain: expected asset ${opts.hasLabel}+${name} under ${policyId} (${present.status})`);
-    const quantity = BigInt((_a = (await present.json()).quantity) !== null && _a !== void 0 ? _a : '0');
+    const present = await (0, blockfrost_1.blockfrostGet)(chain, `/assets/${policyId}${opts.hasLabel}${nameHex}`);
+    if (!present)
+        throw new Error(`onChain: expected asset ${opts.hasLabel}+${name} under ${policyId} (not found)`);
+    const quantity = BigInt((_a = present.quantity) !== null && _a !== void 0 ? _a : '0');
     if (quantity <= BigInt(0))
         throw new Error(`onChain: asset ${opts.hasLabel}+${name} has zero quantity`);
     if (opts.notLabel) {
-        const forbidden = await get(chain, `/assets/${policyId}${opts.notLabel}${nameHex}`);
-        if (forbidden.ok) {
-            const fq = BigInt((_b = (await forbidden.json()).quantity) !== null && _b !== void 0 ? _b : '0');
-            if (fq > BigInt(0))
-                throw new Error(`onChain: asset ${opts.notLabel}+${name} must NOT exist (quantity ${fq})`);
-        }
+        const forbidden = await (0, blockfrost_1.blockfrostGet)(chain, `/assets/${policyId}${opts.notLabel}${nameHex}`);
+        const fq = BigInt((_b = forbidden === null || forbidden === void 0 ? void 0 : forbidden.quantity) !== null && _b !== void 0 ? _b : '0');
+        if (fq > BigInt(0))
+            throw new Error(`onChain: asset ${opts.notLabel}+${name} must NOT exist (quantity ${fq})`);
     }
 };
 exports.assertCip68Label = assertCip68Label;
 /** Assert an asset's total on-chain quantity is 0 (burned). */
 const assertAssetBurned = async (chain, assetUnit) => {
     var _a;
-    const res = await get(chain, `/assets/${assetUnit}`);
-    if (res.status === 404)
+    const asset = await (0, blockfrost_1.blockfrostGet)(chain, `/assets/${assetUnit}`);
+    if (!asset)
         return;
-    if (!res.ok)
-        throw new Error(`onChain: asset lookup failed (${res.status})`);
-    const quantity = (_a = (await res.json()).quantity) !== null && _a !== void 0 ? _a : '0';
+    const quantity = (_a = asset.quantity) !== null && _a !== void 0 ? _a : '0';
     if (BigInt(quantity) !== BigInt(0))
         throw new Error(`onChain: expected ${assetUnit} burned, quantity is ${quantity}`);
 };

package/txBuild/blockfrost.d.ts

@@ -1,5 +1,6 @@
 import { Cardano } from '@cardano-sdk/core';
 import { ProviderRequestOptions } from '../chain/transport/fetchProviderJson';
+import { ChainProtocolParameters } from '../chain/failover/interfaces';
 import { ExUnits } from './fees';
 import { RedeemerKey, ScriptTxProtocolParameters } from './scriptTx';
 type BlockfrostAmount = {
@@ -30,6 +31,11 @@ export declare const toOgmiosUtxo: ([txIn, txOut]: Cardano.Utxo) => ({
     txId?: undefined;
     index?: undefined;
 })[];
+/**
+ * Tx-builder parameters from provider protocol parameters (Blockfrost `/epochs/latest/parameters`, or
+ * any `ChainProvider.getProtocolParameters()`, e.g. through `ChainProviderFailover`).
+ */
+export declare const protocolParametersFromChain: (p: ChainProtocolParameters) => ScriptTxProtocolParameters;
 export declare class BlockfrostTxClient {
     private readonly config;
     private readonly scripts;

package/txBuild/blockfrost.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BlockfrostTxClient = exports.toOgmiosUtxo = exports.valueFromBlockfrost = exports.BlockfrostEvaluationError = void 0;
+exports.BlockfrostTxClient = exports.protocolParametersFromChain = exports.toOgmiosUtxo = exports.valueFromBlockfrost = exports.BlockfrostEvaluationError = void 0;
 // Blockfrost access for building/evaluating/submitting script transactions, returning @cardano-sdk/core
 // types. Every call goes through the shared rate-limited transport (fetchProviderJson), which honors
 // Retry-After and friends process-wide.
@@ -59,6 +59,37 @@ const toOgmiosUtxo = ([txIn, txOut]) => {
     ];
 };
 exports.toOgmiosUtxo = toOgmiosUtxo;
+/**
+ * Tx-builder parameters from provider protocol parameters (Blockfrost `/epochs/latest/parameters`, or
+ * any `ChainProvider.getProtocolParameters()`, e.g. through `ChainProviderFailover`).
+ */
+const protocolParametersFromChain = (p) => {
+    var _a;
+    const raw = p.cost_models_raw;
+    if (!raw)
+        throw new Error('Protocol parameters carry no cost_models_raw');
+    // cost_models_raw is the LEDGER-ordered array; the named `cost_models` object is not (its
+    // alphabetical order produced script_data_hash mismatches once the models were extended).
+    const costModels = new Map();
+    for (const [name, model] of Object.entries(raw)) {
+        const language = PLUTUS_LANGUAGE[name.charAt(0).toLowerCase() + name.slice(1)];
+        if (language !== undefined)
+            costModels.set(language, model);
+    }
+    return {
+        minFeeA: BigInt(p.min_fee_a),
+        minFeeB: BigInt(p.min_fee_b),
+        priceMemory: (0, fees_1.ratio)(p.price_mem),
+        priceSteps: (0, fees_1.ratio)(p.price_step),
+        minFeeRefScriptCostPerByte: (0, fees_1.ratio)((_a = p.min_fee_ref_script_cost_per_byte) !== null && _a !== void 0 ? _a : 0),
+        coinsPerUtxoByte: BigInt(p.coins_per_utxo_size),
+        stakeKeyDeposit: BigInt(p.key_deposit),
+        maxTxSize: Number(p.max_tx_size),
+        maxTxExUnits: { memory: Number(p.max_tx_ex_mem), steps: Number(p.max_tx_ex_steps) },
+        costModels
+    };
+};
+exports.protocolParametersFromChain = protocolParametersFromChain;
 class BlockfrostTxClient {
     constructor(config) {
         this.config = config;
@@ -89,31 +120,7 @@ class BlockfrostTxClient {
         }
     }
     async getProtocolParameters() {
-        var _a;
-        const p = await this.request('epochs/latest/parameters');
-        const raw = p.cost_models_raw;
-        if (!raw)
-            throw new Error('Protocol parameters carry no cost_models_raw');
-        // cost_models_raw is the LEDGER-ordered array; the named `cost_models` object is not (its
-        // alphabetical order produced script_data_hash mismatches once the models were extended).
-        const costModels = new Map();
-        for (const [name, model] of Object.entries(raw)) {
-            const language = PLUTUS_LANGUAGE[name.charAt(0).toLowerCase() + name.slice(1)];
-            if (language !== undefined)
-                costModels.set(language, model);
-        }
-        return {
-            minFeeA: BigInt(p.min_fee_a),
-            minFeeB: BigInt(p.min_fee_b),
-            priceMemory: (0, fees_1.ratio)(p.price_mem),
-            priceSteps: (0, fees_1.ratio)(p.price_step),
-            minFeeRefScriptCostPerByte: (0, fees_1.ratio)((_a = p.min_fee_ref_script_cost_per_byte) !== null && _a !== void 0 ? _a : 0),
-            coinsPerUtxoByte: BigInt(p.coins_per_utxo_size),
-            stakeKeyDeposit: BigInt(p.key_deposit),
-            maxTxSize: Number(p.max_tx_size),
-            maxTxExUnits: { memory: Number(p.max_tx_ex_mem), steps: Number(p.max_tx_ex_steps) },
-            costModels
-        };
+        return (0, exports.protocolParametersFromChain)(await this.request('epochs/latest/parameters'));
     }
     getLatestBlock() {
         return this.request('blocks/latest');

package/txBuild/scriptTx.d.ts

@@ -73,6 +73,11 @@ export declare const computeScriptDataHash: ({ redeemersCbor, datumsCbor, costMo
 }) => string | undefined;
 /** Lovelace a certificate locks (positive) or releases (negative). */
 export declare const certificateDeposit: (certificate: Cardano.Certificate, stakeKeyDeposit: bigint) => bigint;
+/** The inputs cannot pay the outputs + fee (+ a min-UTxO change output); `shortfall` more lovelace would. */
+export declare class InsufficientInputsError extends Error {
+    readonly shortfall: bigint;
+    constructor(message: string, shortfall: bigint);
+}
 export declare const finalizeScriptTx: (plan: ScriptTxPlan, params: ScriptTxProtocolParameters, evaluate: Evaluator) => Promise<FinalizedScriptTx>;
 /**
  * Wallet inputs for a tx whose other inputs are fixed: ADA-only UTxOs first, largest first, until they
@@ -80,6 +85,27 @@ export declare const finalizeScriptTx: (plan: ScriptTxPlan, params: ScriptTxProt
  * UTxOs carrying tokens are only used when ADA-only ones do not suffice (their tokens go to change).
  */
 export declare const selectWalletInputs: (utxos: Cardano.Utxo[], lovelace: bigint, exclude?: Set<string>) => Cardano.Utxo[];
+export interface WalletFundedPlan extends Omit<ScriptTxPlan, 'inputs' | 'signerCount'> {
+    /** Inputs the tx spends regardless of funding (scripts, tokens being moved); none for a plain payment. */
+    inputs?: ScriptTxPlan['inputs'];
+    /**
+     * The wallet's UTxOs exactly as the wallet handed them over (CIP-30 `getUtxos`), which may include
+     * its own UNCONFIRMED change (tx chaining). They are never looked up on chain.
+     */
+    walletUtxos: Cardano.Utxo[];
+    /** vkey witnesses the signed tx carries once these wallet inputs are chosen. */
+    signerCount: (walletInputs: Cardano.Utxo[]) => number;
+}
+/**
+ * Coin selection + finalization in one: walks the `selectWalletInputs` order (ADA-only first, largest
+ * first) one UTxO at a time and returns the first selection `finalizeScriptTx` can balance: inputs
+ * covering outputs + fee with a min-UTxO change output. Pure: no chain reads, so chained (unconfirmed)
+ * wallet UTxOs are spendable. Throws `InsufficientInputsError` (shortfall vs. the whole wallet) when
+ * no selection works.
+ */
+export declare const finalizeWalletFundedTx: ({ walletUtxos, signerCount, inputs, ...plan }: WalletFundedPlan, params: ScriptTxProtocolParameters, evaluate: Evaluator) => Promise<FinalizedScriptTx & {
+    walletInputs: Cardano.Utxo[];
+}>;
 /**
  * Add vkey witnesses to an unsigned tx by splicing them into its witness set byte-for-byte
  * (`mergeWitnessSet`): the body (so the tx id and every signature) and the redeemer bytes the