@koralabs/kora-labs-common 6.17.0 → 6.18.1

package/chain/datum/cip68Metadata.d.ts

@@ -0,0 +1,15 @@
+export type Cip68Standard = 'ft' | 'nft' | 'rft';
+/** CIP-67 labels (with checksum) of the CIP-68 user tokens Blockfrost resolves, and of the reference NFT. */
+export declare const CIP68_REFERENCE_LABEL = "000643b0";
+/** For a CIP-68 user token (222/333/444) asset-name hex: its standard and reference-NFT asset-name hex. */
+export declare const cip68ReferenceOf: (hex: string) => {
+    standard: Cip68Standard;
+    referenceHex: string;
+} | null;
+/** Port of the UTF-8 validator Blockfrost uses (websockets/utf-8-validate fallback). */
+export declare const isValidUTF8: (buf: Buffer) => boolean;
+/**
+ * Blockfrost's `onchain_metadata` for a CIP-68 token whose reference NFT carries `datumHex`, or null
+ * when the datum is not a CIP-68 `Constr [metadata_map, version, extra?]`.
+ */
+export declare const cip68OnchainMetadata: (datumHex: string, standard: Cip68Standard) => Record<string, unknown> | null;

package/chain/datum/cip68Metadata.js

@@ -0,0 +1,217 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cip68OnchainMetadata = exports.isValidUTF8 = exports.cip68ReferenceOf = exports.CIP68_REFERENCE_LABEL = void 0;
+// CIP-68 reference-datum -> `onchain_metadata`, exactly as Blockfrost reports it for `/assets/{unit}`.
+//
+// Ported from blockfrost-utils `src/cip68.ts` (getMetadataFromOutputDatum / convertDatumValue,
+// github.com/blockfrost/blockfrost-utils @ b467b2a). Providers without that endpoint (Koios) read the
+// reference token's datum and convert it here, so every consumer sees ONE metadata shape whichever
+// provider answered. Blockfrost's quirks are kept on purpose: only the CIP-68 schema fields of the
+// token's standard are decoded (bytes -> UTF-8, or hex when not valid UTF-8); every other field keeps
+// the value's ORIGINAL CBOR hex (consumers such as the HAL BFF decode those themselves).
+const cbor_1 = __importDefault(require("cbor"));
+const cbor_2 = require("../../tx/cbor");
+const FILES = {
+    type: 'array',
+    optional: true,
+    items: {
+        name: { type: 'bytestring', optional: true },
+        mediaType: { type: 'bytestring' },
+        src: { type: 'bytestring' }
+    }
+};
+const METADATA_SCHEME_MAP = {
+    ft: {
+        name: { type: 'bytestring' },
+        description: { type: 'bytestring' },
+        ticker: { type: 'bytestring', optional: true },
+        url: { type: 'bytestring', optional: true },
+        logo: { type: 'bytestring', optional: true },
+        decimals: { type: 'number', optional: true }
+    },
+    nft: {
+        name: { type: 'bytestring' },
+        image: { type: 'bytestring' },
+        mediaType: { type: 'bytestring', optional: true },
+        description: { type: 'bytestring', optional: true },
+        files: FILES
+    },
+    rft: {
+        name: { type: 'bytestring' },
+        image: { type: 'bytestring' },
+        mediaType: { type: 'bytestring', optional: true },
+        description: { type: 'bytestring', optional: true },
+        decimals: { type: 'number', optional: true },
+        files: FILES
+    }
+};
+/** CIP-67 labels (with checksum) of the CIP-68 user tokens Blockfrost resolves, and of the reference NFT. */
+exports.CIP68_REFERENCE_LABEL = '000643b0';
+const USER_TOKEN_STANDARDS = { '000de140': 'nft', '0014df10': 'ft', '001bc280': 'rft' };
+/** For a CIP-68 user token (222/333/444) asset-name hex: its standard and reference-NFT asset-name hex. */
+const cip68ReferenceOf = (hex) => {
+    const standard = USER_TOKEN_STANDARDS[hex.slice(0, 8)];
+    return standard ? { standard, referenceHex: `${exports.CIP68_REFERENCE_LABEL}${hex.slice(8)}` } : null;
+};
+exports.cip68ReferenceOf = cip68ReferenceOf;
+/** Port of the UTF-8 validator Blockfrost uses (websockets/utf-8-validate fallback). */
+const isValidUTF8 = (buf) => {
+    const len = buf.length;
+    let i = 0;
+    while (i < len) {
+        if ((buf[i] & 0x80) === 0x00) {
+            i++;
+        }
+        else if ((buf[i] & 0xe0) === 0xc0) {
+            if (i + 1 === len || (buf[i + 1] & 0xc0) !== 0x80 || (buf[i] & 0xfe) === 0xc0)
+                return false;
+            i += 2;
+        }
+        else if ((buf[i] & 0xf0) === 0xe0) {
+            if (i + 2 >= len ||
+                (buf[i + 1] & 0xc0) !== 0x80 ||
+                (buf[i + 2] & 0xc0) !== 0x80 ||
+                (buf[i] === 0xe0 && (buf[i + 1] & 0xe0) === 0x80) ||
+                (buf[i] === 0xed && (buf[i + 1] & 0xe0) === 0xa0)) {
+                return false;
+            }
+            i += 3;
+        }
+        else if ((buf[i] & 0xf8) === 0xf0) {
+            if (i + 3 >= len ||
+                (buf[i + 1] & 0xc0) !== 0x80 ||
+                (buf[i + 2] & 0xc0) !== 0x80 ||
+                (buf[i + 3] & 0xc0) !== 0x80 ||
+                (buf[i] === 0xf0 && (buf[i + 1] & 0xf0) === 0x80) ||
+                (buf[i] === 0xf4 && buf[i + 1] > 0x8f) ||
+                buf[i] > 0xf4) {
+                return false;
+            }
+            i += 4;
+        }
+        else {
+            return false;
+        }
+    }
+    return true;
+};
+exports.isValidUTF8 = isValidUTF8;
+const toUTF8OrHex = (buffer) => ((0, exports.isValidUTF8)(buffer) ? buffer.toString('utf8') : buffer.toString('hex'));
+const convertDatumValue = (decodedValue, schema) => {
+    var _a;
+    if (!schema)
+        return null;
+    const scheme = schema;
+    if (scheme.type === 'number' && typeof decodedValue === 'number')
+        return decodedValue;
+    if (scheme.type === 'bytestring' && Buffer.isBuffer(decodedValue))
+        return toUTF8OrHex(decodedValue);
+    if (scheme.type === 'bytestring' && Array.isArray(decodedValue))
+        return toUTF8OrHex(Buffer.concat(decodedValue));
+    if (Array.isArray(decodedValue)) {
+        const converted = [];
+        for (const item of decodedValue) {
+            const value = convertDatumValue(item, (_a = scheme.items) !== null && _a !== void 0 ? _a : null);
+            if (value === null)
+                return null;
+            converted.push(value);
+        }
+        return converted;
+    }
+    if (decodedValue instanceof Map) {
+        const metadataMap = {};
+        for (const [key, mapValue] of decodedValue.entries()) {
+            const convertedKey = Buffer.isBuffer(key) ? toUTF8OrHex(key) : key;
+            const valueSchema = schema && convertedKey in schema ? schema[convertedKey] : null;
+            const value = convertDatumValue(mapValue, valueSchema);
+            if (value === null)
+                return null;
+            metadataMap[convertedKey] = value;
+        }
+        return metadataMap;
+    }
+    return null;
+};
+/** Start/end of the constructor's fields list: `#6.121..127/1280..1400([fields])` or `#6.102([index, [fields]])`. */
+const constrFields = (bytes) => {
+    const tag = (0, cbor_2.readCborHeader)(bytes, 0);
+    if (tag.majorType !== 6)
+        return null;
+    const isCompact = (tag.length >= 121 && tag.length <= 127) || (tag.length >= 1280 && tag.length <= 1400);
+    if (isCompact)
+        return tag.headerEnd;
+    if (tag.length !== 102)
+        return null;
+    const pair = (0, cbor_2.readCborHeader)(bytes, tag.headerEnd);
+    return pair.majorType === 4 ? (0, cbor_2.skipCborItem)(bytes, pair.headerEnd) : null;
+};
+/** The CBOR items of the list starting at `start` (definite or indefinite), as [start, end) spans. */
+const listItems = (bytes, start) => {
+    const header = (0, cbor_2.readCborHeader)(bytes, start);
+    if (header.majorType !== 4)
+        return null;
+    const spans = [];
+    let cursor = header.headerEnd;
+    const indefinite = header.additionalInfo === 31;
+    for (let i = 0; indefinite ? bytes[cursor] !== 0xff : i < header.length; i++) {
+        const end = (0, cbor_2.skipCborItem)(bytes, cursor);
+        spans.push([cursor, end]);
+        cursor = end;
+    }
+    return spans;
+};
+/**
+ * Blockfrost's `onchain_metadata` for a CIP-68 token whose reference NFT carries `datumHex`, or null
+ * when the datum is not a CIP-68 `Constr [metadata_map, version, extra?]`.
+ */
+const cip68OnchainMetadata = (datumHex, standard) => {
+    const bytes = Buffer.from(datumHex, 'hex');
+    let fields;
+    try {
+        const fieldsStart = constrFields(bytes);
+        fields = fieldsStart === null ? null : listItems(bytes, fieldsStart);
+    }
+    catch (_a) {
+        return null;
+    }
+    // [metadata, version] are mandatory
+    if (!fields || fields.length < 2)
+        return null;
+    const [mapStart] = fields[0];
+    const map = (0, cbor_2.readCborHeader)(bytes, mapStart);
+    if (map.majorType !== 5)
+        return null;
+    const schema = METADATA_SCHEME_MAP[standard];
+    const metadata = {};
+    const seenKeys = new Set();
+    let cursor = map.headerEnd;
+    const indefinite = map.additionalInfo === 31;
+    for (let i = 0; indefinite ? bytes[cursor] !== 0xff : i < map.length; i++) {
+        const keyEnd = (0, cbor_2.skipCborItem)(bytes, cursor);
+        const valueEnd = (0, cbor_2.skipCborItem)(bytes, keyEnd);
+        const keyBytes = bytes.subarray(cursor, keyEnd);
+        const valueBytes = bytes.subarray(keyEnd, valueEnd);
+        cursor = valueEnd;
+        // CSL's PlutusMap groups a repeated key's values and Blockfrost reads the first one.
+        const keyId = keyBytes.toString('hex');
+        if (seenKeys.has(keyId))
+            continue;
+        seenKeys.add(keyId);
+        const decodedKey = cbor_1.default.decodeFirstSync(keyBytes);
+        const convertedKey = Buffer.isBuffer(decodedKey) ? toUTF8OrHex(decodedKey) : decodedKey;
+        const valueHex = valueBytes.toString('hex');
+        if (!(schema && convertedKey in schema)) {
+            // Custom field not covered by the CIP-68 standard: unparsed CBOR
+            metadata[convertedKey] = valueHex;
+        }
+        else {
+            const converted = convertDatumValue(cbor_1.default.decodeFirstSync(valueBytes), schema[convertedKey]);
+            metadata[convertedKey] = converted !== null ? converted : valueHex;
+        }
+    }
+    return metadata;
+};
+exports.cip68OnchainMetadata = cip68OnchainMetadata;

package/chain/failover/ChainProviderFailover.d.ts

@@ -1,4 +1,4 @@
-import { AccountAsset, AddressInfo, BackgroundImageDetails, ChainProvider, ChainProviderAsset, ChainProviderUtxo } from './interfaces';
+import { AccountAsset, AddressInfo, BackgroundImageDetails, ChainProtocolParameters, ChainProvider, ChainProviderAsset, ChainProviderUtxo } from './interfaces';
 export interface FailoverOptions {
     /**
      * Cooldown (ms) during which a provider that just failed is skipped as the *start* provider,
@@ -42,9 +42,14 @@ export declare class ChainProviderFailover {
     getRefScriptCbor(tx: string, policyId: string, hex: string): Promise<string>;
     getTxUtxos(tx: string): Promise<ChainProviderUtxo>;
     getAssetUtxo(policyId: string, hex: string): Promise<ChainProviderAsset | null>;
+    /** Index of the Blockfrost provider, if configured (start provider for freshness-critical reads). */
+    private blockfrostIndex;
     getAssetsByStakeKey(stakeKey: string): Promise<AccountAsset[]>;
     getDatumFromHash(datumHash: string): Promise<string | null>;
     getBackgroundImageDetails(policyId: string, hex: string): Promise<BackgroundImageDetails>;
     getAddressInfo(bech32Address: string): Promise<AddressInfo>;
     getAddressUTxOs(bech32Address: string): Promise<ChainProviderAsset[]>;
+    getProtocolParameters(): Promise<ChainProtocolParameters>;
+    getTxOutputConsumer(txHash: string, outputIndex: number): Promise<string | null>;
+    getAssetOnchainMetadata(policyId: string, hex: string): Promise<Record<string, unknown> | null>;
 }

package/chain/failover/ChainProviderFailover.js

@@ -29,18 +29,22 @@ class ChainProviderFailover {
     getNextProviderIndex(currentIndex) {
         return (currentIndex + 1) % this.providers.length;
     }
-    async getResponse(funcName, args, currentIndex, runNum) {
+    async getResponse(funcName, args, currentIndex, runNum, notFound) {
         const num = runNum !== null && runNum !== void 0 ? runNum : 0;
         const index = currentIndex !== null && currentIndex !== void 0 ? currentIndex : this.getStartIndex();
         const chainProvider = this.providers[index];
         return await chainProvider[funcName](...args).catch((error) => {
+            // A 404 is an answer ("not on chain (yet)"), not a provider failure: it still falls
+            // through, but without benching the provider, and it outranks another provider's outage.
+            const isNotFound = (error === null || error === void 0 ? void 0 : error.status) === 404;
             // Mark the failed provider unhealthy for the cooldown window so it isn't chosen as the
             // start provider again immediately; it remains a valid fallback.
-            if (this.cooldownMs > 0)
+            if (this.cooldownMs > 0 && !isNotFound)
                 this.unhealthyUntil[index] = this.now() + this.cooldownMs;
+            const answer = notFound !== null && notFound !== void 0 ? notFound : (isNotFound ? error : undefined);
             if (num === this.providers.length - 1)
-                throw error;
-            return this.getResponse(funcName, args, this.getNextProviderIndex(index), num + 1);
+                throw answer !== null && answer !== void 0 ? answer : error;
+            return this.getResponse(funcName, args, this.getNextProviderIndex(index), num + 1, answer);
         });
     }
     async getLatestTransactionForAsset(policyId, hex) {
@@ -69,8 +73,12 @@ class ChainProviderFailover {
         // provider lagging a burn returns a stale UTxO and falsely resurrects a de-indexed handle.
         // Prefer Blockfrost (reads the latest asset tx live; Koios's tx index can lag a burn by
         // minutes). Koios stays the failover on error.
-        const preferredIndex = this.providers.findIndex((p) => { var _a; return ((_a = p.name) !== null && _a !== void 0 ? _a : '').toLowerCase().includes('blockfrost'); });
-        return this.getResponse('getAssetUtxo', [policyId, hex], preferredIndex >= 0 ? preferredIndex : undefined);
+        return this.getResponse('getAssetUtxo', [policyId, hex], this.blockfrostIndex());
+    }
+    /** Index of the Blockfrost provider, if configured (start provider for freshness-critical reads). */
+    blockfrostIndex() {
+        const index = this.providers.findIndex((p) => { var _a; return ((_a = p.name) !== null && _a !== void 0 ? _a : '').toLowerCase().includes('blockfrost'); });
+        return index >= 0 ? index : undefined;
     }
     async getAssetsByStakeKey(stakeKey) {
         return this.getResponse('getAssetsByStakeKey', [stakeKey]);
@@ -87,5 +95,15 @@ class ChainProviderFailover {
     async getAddressUTxOs(bech32Address) {
         return this.getResponse('getAddressUTxOs', [bech32Address]);
     }
+    async getProtocolParameters() {
+        return this.getResponse('getProtocolParameters', []);
+    }
+    async getTxOutputConsumer(txHash, outputIndex) {
+        // Blockfrost answers from its spent-by index in one call; Koios has to scan the address's txs.
+        return this.getResponse('getTxOutputConsumer', [txHash, outputIndex], this.blockfrostIndex());
+    }
+    async getAssetOnchainMetadata(policyId, hex) {
+        return this.getResponse('getAssetOnchainMetadata', [policyId, hex]);
+    }
 }
 exports.ChainProviderFailover = ChainProviderFailover;

package/chain/failover/interfaces.d.ts

@@ -28,6 +28,26 @@ export interface AddressInfo {
     stake_address?: string | null;
     script: boolean;
 }
+/**
+ * Current protocol parameters in Blockfrost's `/epochs/latest/parameters` field names (Koios's
+ * `/epoch_params` uses the same names and reports identical values; its `cost_models` is mapped to
+ * `cost_models_raw`). Cost models are ledger-ordered arrays keyed `PlutusV1`/`PlutusV2`/`PlutusV3`.
+ * `@koralabs/kora-labs-common/txBuild` `protocolParametersFromChain` turns this into tx-builder params.
+ */
+export interface ChainProtocolParameters {
+    epoch: number;
+    min_fee_a: number;
+    min_fee_b: number;
+    max_tx_size: number;
+    coins_per_utxo_size: string;
+    key_deposit: string;
+    price_mem: number;
+    price_step: number;
+    max_tx_ex_mem: string;
+    max_tx_ex_steps: string;
+    min_fee_ref_script_cost_per_byte: number | null;
+    cost_models_raw: Record<string, number[]>;
+}
 export interface BackgroundImageDetails {
     image: string;
     creatorDefaults?: ICreatorDefaults;
@@ -52,11 +72,24 @@ export interface ChainProvider {
     getAssetDatum(policyId: string, hex: string): Promise<string | null>;
     getCip25AssetImage(policyId: string, hex: string): Promise<string | null>;
     getRefScriptCbor(tx: string, policyId: string, hex: string): Promise<string>;
+    /** The tx's outputs. Rejects with `status: 404` when the tx is not on chain (not in a block yet). */
     getTxUtxos(tx: string): Promise<ChainProviderUtxo>;
     getAssetUtxo(policyId: string, hex: string): Promise<ChainProviderAsset | null>;
     getAssetsByStakeKey(stakeKey: string): Promise<AccountAsset[]>;
     getDatumFromHash(datumHash: string): Promise<string | null>;
     getBackgroundImageDetails(policyId: string, hex: string): Promise<BackgroundImageDetails>;
     getAddressInfo(bech32Address: string): Promise<AddressInfo>;
+    /** Every unspent output at the address (all pages). An address with no UTxOs has none. */
     getAddressUTxOs(bech32Address: string): Promise<ChainProviderAsset[]>;
+    getProtocolParameters(): Promise<ChainProtocolParameters>;
+    /**
+     * The tx that spent output `txHash#outputIndex`, or null while it is unspent. Rejects with
+     * `status: 404` when that output does not exist (e.g. the tx is not in a block yet).
+     */
+    getTxOutputConsumer(txHash: string, outputIndex: number): Promise<string | null>;
+    /**
+     * The asset's `onchain_metadata` as Blockfrost reports it (CIP-68 reference datum converted per
+     * `cip68OnchainMetadata`, else the CIP-25 721 entry), or null when it has none.
+     */
+    getAssetOnchainMetadata(policyId: string, hex: string): Promise<Record<string, unknown> | null>;
 }

package/chain/index.d.ts

@@ -8,3 +8,4 @@ export * from './config';
 export * from './datum/imageDatum';
 export * from './providers/Koios';
 export * from './providers/Blockfrost';
+export * from './datum/cip68Metadata';

package/chain/index.js

@@ -27,3 +27,4 @@ __exportStar(require("./config"), exports);
 __exportStar(require("./datum/imageDatum"), exports);
 __exportStar(require("./providers/Koios"), exports);
 __exportStar(require("./providers/Blockfrost"), exports);
+__exportStar(require("./datum/cip68Metadata"), exports);

package/chain/providers/Blockfrost.d.ts

@@ -1,5 +1,5 @@
 import { ICreatorDefaults } from '../../handles/interfaces';
-import { AccountAsset, AddressInfo, ChainProvider, ChainProviderAsset, ChainProviderUtxo } from '../failover/interfaces';
+import { AccountAsset, AddressInfo, ChainProtocolParameters, ChainProvider, ChainProviderAsset, ChainProviderUtxo } from '../failover/interfaces';
 import { ChainProviderConfig } from '../providerConfig';
 export interface DrepMetadataValue {
     '@value': string;
@@ -55,5 +55,8 @@ export declare class Blockfrost implements ChainProvider {
     }>;
     getAddressInfo(bech32Address: string): Promise<AddressInfo>;
     getAddressUTxOs(bech32Address: string): Promise<ChainProviderAsset[]>;
+    getProtocolParameters(): Promise<ChainProtocolParameters>;
+    getTxOutputConsumer(txHash: string, outputIndex: number): Promise<string | null>;
+    getAssetOnchainMetadata(policyId: string, hex: string): Promise<Record<string, unknown> | null>;
 }
 export {};

package/chain/providers/Blockfrost.js

@@ -138,7 +138,60 @@ class Blockfrost {
         };
     }
     async getAddressUTxOs(bech32Address) {
-        return await this.fetchBlockfrost(`/addresses/${bech32Address}/utxos`);
+        // Blockfrost pages at 100: never truncate. An address that never received funds is a 404.
+        const all = [];
+        for (let page = 1;; page++) {
+            let batch;
+            try {
+                batch = await this.fetchBlockfrost(`/addresses/${bech32Address}/utxos?count=100&page=${page}`);
+            }
+            catch (error) {
+                if ((error === null || error === void 0 ? void 0 : error.status) === 404)
+                    return all;
+                throw error;
+            }
+            all.push(...batch);
+            if (batch.length < 100)
+                return all;
+        }
+    }
+    async getProtocolParameters() {
+        var _a;
+        const p = await this.fetchBlockfrost('epochs/latest/parameters');
+        return {
+            epoch: p.epoch,
+            min_fee_a: p.min_fee_a,
+            min_fee_b: p.min_fee_b,
+            max_tx_size: p.max_tx_size,
+            coins_per_utxo_size: String(p.coins_per_utxo_size),
+            key_deposit: String(p.key_deposit),
+            price_mem: p.price_mem,
+            price_step: p.price_step,
+            max_tx_ex_mem: String(p.max_tx_ex_mem),
+            max_tx_ex_steps: String(p.max_tx_ex_steps),
+            min_fee_ref_script_cost_per_byte: (_a = p.min_fee_ref_script_cost_per_byte) !== null && _a !== void 0 ? _a : null,
+            cost_models_raw: p.cost_models_raw
+        };
+    }
+    async getTxOutputConsumer(txHash, outputIndex) {
+        var _a;
+        const { outputs } = await this.getTxUtxos(txHash);
+        const output = outputs.find((o) => o.output_index === outputIndex);
+        if (!output)
+            throw (0, fetchProviderJson_1.providerNotFoundError)('Blockfrost', `Output ${txHash}#${outputIndex}`);
+        return (_a = output.consumed_by_tx) !== null && _a !== void 0 ? _a : null;
+    }
+    async getAssetOnchainMetadata(policyId, hex) {
+        var _a;
+        try {
+            const asset = await this.fetchBlockfrost(`/assets/${policyId}${hex}`);
+            return (_a = asset === null || asset === void 0 ? void 0 : asset.onchain_metadata) !== null && _a !== void 0 ? _a : null;
+        }
+        catch (error) {
+            if ((error === null || error === void 0 ? void 0 : error.status) === 404)
+                return null;
+            throw error;
+        }
     }
 }
 exports.Blockfrost = Blockfrost;

package/chain/providers/Koios.d.ts

@@ -1,5 +1,5 @@
 import { ICreatorDefaults } from '../../handles/interfaces';
-import { AccountAsset, AddressInfo, ChainProvider, ChainProviderAsset, ChainProviderUtxo } from '../failover/interfaces';
+import { AccountAsset, AddressInfo, ChainProtocolParameters, ChainProvider, ChainProviderAsset, ChainProviderUtxo } from '../failover/interfaces';
 import { ChainProviderConfig } from '../providerConfig';
 interface KoiosAsset {
     quantity: string;
@@ -17,9 +17,11 @@ interface KoiosTxOutput {
         bytes: string | null;
         value: string | null;
     } | null;
-    payment_addr: {
+    /** tx_info outputs carry `payment_addr`; address_utxos / utxo_info rows carry `address` instead. */
+    payment_addr?: {
         bech32: string;
     };
+    address?: string;
     reference_script: {
         bytes: string | null;
         hash: string | null;
@@ -64,5 +66,8 @@ export declare class Koios implements ChainProvider {
     }>;
     getAddressInfo(bech32Address: string): Promise<AddressInfo>;
     getAddressUTxOs(bech32Address: string): Promise<ChainProviderAsset[]>;
+    getProtocolParameters(): Promise<ChainProtocolParameters>;
+    getTxOutputConsumer(txHash: string, outputIndex: number): Promise<string | null>;
+    getAssetOnchainMetadata(policyId: string, hex: string): Promise<Record<string, unknown> | null>;
 }
 export {};

package/chain/providers/Koios.js

@@ -4,7 +4,12 @@ exports.Koios = exports.buildKoiosAddressUtxoRequestBody = exports.buildKoiosHea
 const types_1 = require("../../types");
 const fetchProviderJson_1 = require("../transport/fetchProviderJson");
 const imageDatum_1 = require("../datum/imageDatum");
+const cip68Metadata_1 = require("../datum/cip68Metadata");
 const providerConfig_1 = require("../providerConfig");
+/** PostgREST page size Koios serves (its maximum). */
+const KOIOS_PAGE = 1000;
+/** Tx hashes per tx_info request when scanning for an output's consumer. */
+const TX_INFO_BATCH = 50;
 const buildKoiosHeaders = (bearerToken) => ({
     'Content-Type': 'application/json',
     ...(bearerToken ? { Authorization: `Bearer ${bearerToken}` } : {})
@@ -58,7 +63,7 @@ class Koios {
         }, [])) !== null && _a !== void 0 ? _a : []);
     }
     async getAssetUtxo(policyId, hex) {
-        var _a, _b, _c;
+        var _a, _b, _c, _d;
         const tx = await this.getLatestTransactionForAsset(policyId, hex);
         if (!tx)
             return null;
@@ -74,9 +79,9 @@ class Koios {
         }));
         amount.push({ unit: 'lovelace', quantity: output.value });
         const chainProviderAsset = {
-            address: output.payment_addr.bech32,
+            address: (_b = output.address) !== null && _b !== void 0 ? _b : output.payment_addr.bech32,
             amount,
-            inline_datum: (_c = (_b = output.inline_datum) === null || _b === void 0 ? void 0 : _b.bytes) !== null && _c !== void 0 ? _c : null,
+            inline_datum: (_d = (_c = output.inline_datum) === null || _c === void 0 ? void 0 : _c.bytes) !== null && _d !== void 0 ? _d : null,
             output_index: output.tx_index,
             tx_hash: firstTransaction.tx_hash,
             data_hash: output.datum_hash
@@ -105,7 +110,7 @@ class Koios {
         return (_a = output === null || output === void 0 ? void 0 : output.reference_script_cbor) !== null && _a !== void 0 ? _a : '';
     }
     async buildChainProviderAsset(output) {
-        var _a, _b, _c, _d, _e, _f, _g;
+        var _a, _b, _c, _d, _e, _f, _g, _h;
         const amount = output.asset_list.map((a) => ({
             unit: `${a.policy_id}${a.asset_name}`,
             quantity: a.quantity
@@ -115,20 +120,22 @@ class Koios {
             ? await this.getDatumFromHash(output.datum_hash)
             : (_c = (_b = output.inline_datum) === null || _b === void 0 ? void 0 : _b.bytes) !== null && _c !== void 0 ? _c : null;
         return {
-            address: output.payment_addr.bech32,
+            address: (_d = output.address) !== null && _d !== void 0 ? _d : output.payment_addr.bech32,
             amount,
             inline_datum,
             output_index: output.tx_index,
             tx_hash: output.tx_hash,
             data_hash: output.datum_hash,
-            reference_script_hash: (_e = (_d = output.reference_script) === null || _d === void 0 ? void 0 : _d.hash) !== null && _e !== void 0 ? _e : null,
-            reference_script_cbor: (_g = (_f = output.reference_script) === null || _f === void 0 ? void 0 : _f.bytes) !== null && _g !== void 0 ? _g : null
+            reference_script_hash: (_f = (_e = output.reference_script) === null || _e === void 0 ? void 0 : _e.hash) !== null && _f !== void 0 ? _f : null,
+            reference_script_cbor: (_h = (_g = output.reference_script) === null || _g === void 0 ? void 0 : _g.bytes) !== null && _h !== void 0 ? _h : null
         };
     }
     async getTxUtxos(tx) {
         var _a;
         const res = await this.fetchKoios(`/tx_info`, 'POST', JSON.stringify({ _tx_hashes: [tx], _metadata: true, _assets: true }));
         const [firstTransaction] = res;
+        if (!firstTransaction)
+            throw (0, fetchProviderJson_1.providerNotFoundError)('Koios', `Transaction ${tx}`);
         const outputs = [];
         for (const output of (_a = firstTransaction === null || firstTransaction === void 0 ? void 0 : firstTransaction.outputs) !== null && _a !== void 0 ? _a : []) {
             outputs.push(await this.buildChainProviderAsset(output));
@@ -205,12 +212,74 @@ class Koios {
         };
     }
     async getAddressUTxOs(bech32Address) {
-        const result = await this.fetchKoios(`/address_utxos`, 'POST', JSON.stringify((0, exports.buildKoiosAddressUtxoRequestBody)(bech32Address)));
         const utxos = [];
-        for (const output of result) {
-            utxos.push(await this.buildChainProviderAsset(output));
+        for (let offset = 0;; offset += KOIOS_PAGE) {
+            const page = await this.fetchKoios(`/address_utxos?offset=${offset}&limit=${KOIOS_PAGE}`, 'POST', JSON.stringify((0, exports.buildKoiosAddressUtxoRequestBody)(bech32Address)));
+            for (const output of page) {
+                utxos.push(await this.buildChainProviderAsset(output));
+            }
+            if (page.length < KOIOS_PAGE)
+                return utxos;
+        }
+    }
+    async getProtocolParameters() {
+        var _a;
+        // The tip's epoch, not the newest epoch_params row: rows for the next epoch can appear before it starts.
+        const [tip] = await this.fetchKoios('/tip');
+        const [p] = await this.fetchKoios(`/epoch_params?_epoch_no=${tip.epoch_no}`);
+        if (!p)
+            throw (0, fetchProviderJson_1.providerNotFoundError)('Koios', `Protocol parameters for epoch ${tip.epoch_no}`);
+        return {
+            epoch: p.epoch_no,
+            min_fee_a: p.min_fee_a,
+            min_fee_b: p.min_fee_b,
+            max_tx_size: p.max_tx_size,
+            coins_per_utxo_size: String(p.coins_per_utxo_size),
+            key_deposit: String(p.key_deposit),
+            price_mem: p.price_mem,
+            price_step: p.price_step,
+            max_tx_ex_mem: String(p.max_tx_ex_mem),
+            max_tx_ex_steps: String(p.max_tx_ex_steps),
+            min_fee_ref_script_cost_per_byte: (_a = p.min_fee_ref_script_cost_per_byte) !== null && _a !== void 0 ? _a : null,
+            cost_models_raw: p.cost_models
+        };
+    }
+    async getTxOutputConsumer(txHash, outputIndex) {
+        const ref = `${txHash}#${outputIndex}`;
+        const [utxo] = await this.fetchKoios('/utxo_info', 'POST', JSON.stringify({ _utxo_refs: [ref], _extended: false }));
+        if (!utxo)
+            throw (0, fetchProviderJson_1.providerNotFoundError)('Koios', `Output ${ref}`);
+        if (!utxo.is_spent)
+            return null;
+        // Koios has no spent-by index: scan the txs touching the output's address from its block on
+        // (inclusive: a chained spend can land in the same block) for the one that consumes it.
+        for (let offset = 0;; offset += KOIOS_PAGE) {
+            const txs = await this.fetchKoios(`/address_txs?order=block_height.asc&offset=${offset}&limit=${KOIOS_PAGE}`, 'POST', JSON.stringify({ _addresses: [utxo.address], _after_block_height: utxo.block_height }));
+            const candidates = txs.map((t) => t.tx_hash).filter((h) => h !== txHash);
+            for (let i = 0; i < candidates.length; i += TX_INFO_BATCH) {
+                const infos = await this.fetchKoios('/tx_info', 'POST', JSON.stringify({ _tx_hashes: candidates.slice(i, i + TX_INFO_BATCH), _inputs: true, _metadata: false, _assets: false, _withdrawals: false, _certs: false, _scripts: false, _bytecode: false, _governance: false }));
+                const consumer = infos.find((t) => { var _a; return (_a = t.inputs) === null || _a === void 0 ? void 0 : _a.some((input) => input.tx_hash === txHash && input.tx_index === outputIndex); });
+                if (consumer)
+                    return consumer.tx_hash;
+            }
+            if (txs.length < KOIOS_PAGE)
+                break;
+        }
+        throw new Error(`Koios reports ${ref} spent but no tx at ${utxo.address} consumes it`);
+    }
+    async getAssetOnchainMetadata(policyId, hex) {
+        var _a, _b, _c, _d;
+        // Blockfrost's precedence: a CIP-68 user token's reference datum, else the CIP-25 721 entry.
+        const cip68 = (0, cip68Metadata_1.cip68ReferenceOf)(hex);
+        if (cip68) {
+            const datum = await this.getAssetDatum(policyId, cip68.referenceHex);
+            const metadata = datum ? (0, cip68Metadata_1.cip68OnchainMetadata)(datum, cip68.standard) : null;
+            if (metadata)
+                return metadata;
         }
-        return utxos;
+        const [info] = await this.fetchKoios('/asset_info', 'POST', JSON.stringify({ _asset_list: [[policyId, hex]] }));
+        const byPolicy = (_b = (_a = info === null || info === void 0 ? void 0 : info.minting_tx_metadata) === null || _a === void 0 ? void 0 : _a['721']) === null || _b === void 0 ? void 0 : _b[policyId];
+        return (_d = (_c = byPolicy === null || byPolicy === void 0 ? void 0 : byPolicy[hex]) !== null && _c !== void 0 ? _c : byPolicy === null || byPolicy === void 0 ? void 0 : byPolicy[Buffer.from(hex, 'hex').toString('utf8')]) !== null && _d !== void 0 ? _d : null;
     }
 }
 exports.Koios = Koios;

package/chain/transport/fetchProviderJson.d.ts

@@ -25,6 +25,8 @@ export interface ProviderRequestOptions {
     maxRateLimitWaitMs?: number;
     fetcher?: ProviderFetcher;
 }
+/** A provider's "that does not exist" answer, shaped like a transport 404 (`status: 404`). */
+export declare const providerNotFoundError: (provider: ProviderName, what: string) => Error;
 export declare const isRetriableError: (provider: ProviderName, error: any) => boolean;
 export declare const fetchProviderJson: <T>({ provider, url, method, headers, body, maxRetries, retryBaseDelayMs, maxRps, rateLimitKey, maxRateLimitWaitMs, fetcher }: ProviderRequestOptions) => Promise<T>;
 export {};

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.17.0",
+    "version": "6.18.1",
     "description": "Kora Labs Common Utilities",
     "main": "index.js",
     "types": "index.d.ts",

package/testing/onChain.d.ts

@@ -33,7 +33,12 @@ export interface TxConfirmation {
     block?: string;
     validContract?: boolean;
 }
-/** Poll until the tx is in a block. A tx in a block with `valid_contract: false` is NOT a success. */
+/**
+ * Poll until the tx is in a block AND Blockfrost serves its UTxOs. Right after inclusion Blockfrost can
+ * answer /txs/<hash> while /txs/<hash>/utxos still 404s (seen on preview: the live suite's reads right
+ * after "confirmed" failed), so "confirmed" means every follow-up read of the tx will answer.
+ * A tx in a block with `valid_contract: false` is NOT a success.
+ */
 export declare const waitForTxConfirmation: (chain: ChainConfig, txHash: string, timeoutMs?: number, pollMs?: number) => Promise<TxConfirmation>;
 /** Poll a tx output until it is spent; returns the spending tx hash, or null on timeout. */
 export declare const waitForOutputConsumed: (chain: ChainConfig, txHash: string, outputIndex: number, timeoutMs: number, pollMs?: number) => Promise<string | null>;

package/testing/onChain.js

@@ -28,17 +28,23 @@ const fetchTxUtxos = (chain, txHash) => getJson(chain, `/txs/${txHash}/utxos`);
 exports.fetchTxUtxos = fetchTxUtxos;
 const lovelaceOf = (amount) => { var _a, _b; return BigInt((_b = (_a = amount.find((a) => a.unit === 'lovelace')) === null || _a === void 0 ? void 0 : _a.quantity) !== null && _b !== void 0 ? _b : '0'); };
 exports.lovelaceOf = lovelaceOf;
-/** Poll until the tx is in a block. A tx in a block with `valid_contract: false` is NOT a success. */
+/**
+ * Poll until the tx is in a block AND Blockfrost serves its UTxOs. Right after inclusion Blockfrost can
+ * answer /txs/<hash> while /txs/<hash>/utxos still 404s (seen on preview: the live suite's reads right
+ * after "confirmed" failed), so "confirmed" means every follow-up read of the tx will answer.
+ * A tx in a block with `valid_contract: false` is NOT a success.
+ */
 const waitForTxConfirmation = async (chain, txHash, timeoutMs = 180000, pollMs = 5000) => {
     const start = Date.now();
+    // A transient provider failure is another poll; a rate limit too long to sit out is returned.
+    const poll = (path) => (0, blockfrost_1.blockfrostGet)(chain, path).catch((error) => {
+        if (error instanceof rateLimit_1.RateLimitedError)
+            throw error;
+        return null;
+    });
     for (;;) {
-        // 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)
+        const data = await poll(`/txs/${txHash}`);
+        if (data && (await poll(`/txs/${txHash}/utxos`)))
             return { confirmed: true, block: data.block, validContract: data.valid_contract };
         if (Date.now() - start >= timeoutMs)
             return { confirmed: false };

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

package/txBuild/scriptTx.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.addVkeyWitnesses = exports.selectWalletInputs = exports.finalizeScriptTx = exports.certificateDeposit = exports.computeScriptDataHash = exports.withMinAda = void 0;
+exports.addVkeyWitnesses = exports.finalizeWalletFundedTx = exports.selectWalletInputs = exports.finalizeScriptTx = exports.InsufficientInputsError = exports.certificateDeposit = exports.computeScriptDataHash = exports.withMinAda = void 0;
 // Deterministic Plutus transaction finalizer on @cardano-sdk/core (no input selection, no Helios).
 //
 // The caller fixes every input; this module derives redeemer pointers from the ledger's canonical
@@ -87,6 +87,15 @@ const sumValues = (values) => {
     }
     return { coins, assets };
 };
+/** The inputs cannot pay the outputs + fee (+ a min-UTxO change output); `shortfall` more lovelace would. */
+class InsufficientInputsError extends Error {
+    constructor(message, shortfall) {
+        super(message);
+        this.shortfall = shortfall;
+        this.name = 'InsufficientInputsError';
+    }
+}
+exports.InsufficientInputsError = InsufficientInputsError;
 const finalizeScriptTx = async (plan, params, evaluate) => {
     var _a, _b, _c;
     const inputs = [...plan.inputs].sort((a, b) => byTxIn(a.utxo[0], b.utxo[0]));
@@ -112,7 +121,7 @@ const finalizeScriptTx = async (plan, params, evaluate) => {
         var _a, _b, _c;
         const coins = inValue.coins + withdrawn - deposited - produced.coins - fee;
         if (coins < BigInt(0))
-            throw new Error(`Inputs do not cover outputs + fee: ${-coins} lovelace short`);
+            throw new InsufficientInputsError(`Inputs do not cover outputs + fee: ${-coins} lovelace short`, -coins);
         const assets = new Map();
         const ids = new Set([...inValue.assets.keys(), ...tokenMap.keys(), ...produced.assets.keys()]);
         for (const id of ids) {
@@ -192,8 +201,9 @@ const finalizeScriptTx = async (plan, params, evaluate) => {
             throw new Error('Execution units did not converge');
     }
     const { tx, change, redeemers } = assemble(fee, exUnits, new Map());
-    if (change.value.coins < (0, fees_1.minAdaForOutputSize)(params.coinsPerUtxoByte, outputSize(change))) {
-        throw new Error(`Inputs do not cover outputs + fee: change of ${change.value.coins} lovelace is below min-UTxO`);
+    const changeMinAda = (0, fees_1.minAdaForOutputSize)(params.coinsPerUtxoByte, outputSize(change));
+    if (change.value.coins < changeMinAda) {
+        throw new InsufficientInputsError(`Inputs do not cover outputs + fee: change of ${change.value.coins} lovelace is below min-UTxO`, changeMinAda - change.value.coins);
     }
     const signedSize = sizeOf(fee, exUnits);
     if (signedSize > params.maxTxSize)
@@ -231,6 +241,35 @@ const selectWalletInputs = (utxos, lovelace, exclude = new Set()) => {
     return selected;
 };
 exports.selectWalletInputs = selectWalletInputs;
+const coinsOf = (utxos) => utxos.reduce((sum, [, out]) => sum + out.value.coins, BigInt(0));
+/**
+ * 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.
+ */
+const finalizeWalletFundedTx = async ({ walletUtxos, signerCount, inputs = [], ...plan }, params, evaluate) => {
+    const available = coinsOf(walletUtxos);
+    let required = plan.outputs.reduce((sum, o) => sum + o.value.coins, BigInt(0));
+    // Each selection is the previous one plus the next UTxO in order (+1 lovelace past its total).
+    for (let lovelace = BigInt(1); lovelace <= available;) {
+        const walletInputs = (0, exports.selectWalletInputs)(walletUtxos, lovelace);
+        const selected = coinsOf(walletInputs);
+        try {
+            const tx = await (0, exports.finalizeScriptTx)({ ...plan, inputs: [...inputs, ...walletInputs.map((utxo) => ({ utxo }))], signerCount: signerCount(walletInputs) }, params, evaluate);
+            return { ...tx, walletInputs };
+        }
+        catch (error) {
+            if (!(error instanceof InsufficientInputsError))
+                throw error;
+            required = selected + error.shortfall;
+            lovelace = selected + BigInt(1);
+        }
+    }
+    throw new InsufficientInputsError(`Wallet holds ${available} spendable lovelace; about ${required} needed`, required - available);
+};
+exports.finalizeWalletFundedTx = finalizeWalletFundedTx;
 /**
  * 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