@koralabs/kora-labs-common 6.13.4 → 6.14.0

package/txBuild/blockfrost.js

@@ -0,0 +1,209 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BlockfrostTxClient = 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.
+const core_1 = require("@cardano-sdk/core");
+const fetchProviderJson_1 = require("../chain/transport/fetchProviderJson");
+const fees_1 = require("./fees");
+const PLUTUS_LANGUAGE = {
+    plutusV1: core_1.Cardano.PlutusLanguageVersion.V1,
+    plutusV2: core_1.Cardano.PlutusLanguageVersion.V2,
+    plutusV3: core_1.Cardano.PlutusLanguageVersion.V3
+};
+const OGMIOS_PURPOSE = {
+    spend: 'spend',
+    mint: 'mint',
+    certificate: 'certificate',
+    withdrawal: 'withdrawal',
+    withdraw: 'withdrawal',
+    reward: 'withdrawal'
+};
+class BlockfrostEvaluationError extends Error {
+    constructor(failure) {
+        super(`Transaction failed evaluation: ${JSON.stringify(failure)}`);
+        this.failure = failure;
+        this.name = 'BlockfrostEvaluationError';
+    }
+}
+exports.BlockfrostEvaluationError = BlockfrostEvaluationError;
+const valueFromBlockfrost = (amount) => {
+    let coins = BigInt(0);
+    const assets = new Map();
+    for (const { unit, quantity } of amount) {
+        if (unit === 'lovelace')
+            coins = BigInt(quantity);
+        else
+            assets.set(core_1.Cardano.AssetId.fromParts(core_1.Cardano.PolicyId(unit.slice(0, 56)), core_1.Cardano.AssetName(unit.slice(56))), BigInt(quantity));
+    }
+    return { coins, ...(assets.size ? { assets } : {}) };
+};
+exports.valueFromBlockfrost = valueFromBlockfrost;
+/** Additional-UTxO shape Blockfrost's evaluator accepts: Ogmios value `{ ada: { lovelace }, [policy]: { [asset]: qty } }`. */
+const toOgmiosUtxo = ([txIn, txOut]) => {
+    var _a, _b;
+    const value = { ada: { lovelace: Number(txOut.value.coins) } };
+    for (const [id, qty] of (_a = txOut.value.assets) !== null && _a !== void 0 ? _a : []) {
+        const policy = core_1.Cardano.AssetId.getPolicyId(id);
+        value[policy] = { ...((_b = value[policy]) !== null && _b !== void 0 ? _b : {}), [core_1.Cardano.AssetId.getAssetName(id)]: Number(qty) };
+    }
+    return [
+        { txId: txIn.txId, index: txIn.index },
+        {
+            address: txOut.address,
+            value,
+            ...(txOut.datum ? { datum: core_1.Serialization.PlutusData.fromCore(txOut.datum).toCbor() } : {}),
+            ...(txOut.datumHash ? { datumHash: txOut.datumHash } : {})
+        }
+    ];
+};
+exports.toOgmiosUtxo = toOgmiosUtxo;
+class BlockfrostTxClient {
+    constructor(config) {
+        this.config = config;
+        this.scripts = new Map();
+        this.host = `https://cardano-${config.network.toLowerCase()}.blockfrost.io/api/v0`;
+    }
+    request(path, init = {}) {
+        var _a, _b;
+        return (0, fetchProviderJson_1.fetchProviderJson)({
+            provider: 'Blockfrost',
+            url: `${this.host}/${path.replace(/^\//, '')}`,
+            method: (_a = init.method) !== null && _a !== void 0 ? _a : 'GET',
+            headers: { project_id: this.config.blockfrostApiKey, 'Content-Type': (_b = init.contentType) !== null && _b !== void 0 ? _b : 'application/json' },
+            body: init.body,
+            fetcher: this.config.fetcher,
+            // Submission/evaluation are not idempotent-safe to blind-retry on 5xx; rate limits are still honored.
+            ...(init.method === 'POST' ? { maxRetries: 0 } : {})
+        });
+    }
+    async getOrNull(path) {
+        try {
+            return await this.request(path);
+        }
+        catch (error) {
+            if ((error === null || error === void 0 ? void 0 : error.status) === 404)
+                return null;
+            throw error;
+        }
+    }
+    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),
+            maxTxSize: Number(p.max_tx_size),
+            maxTxExUnits: { memory: Number(p.max_tx_ex_mem), steps: Number(p.max_tx_ex_steps) },
+            costModels
+        };
+    }
+    getLatestBlock() {
+        return this.request('blocks/latest');
+    }
+    /** Slot of a POSIX time (ms), from the tip (1-second slots since Shelley on every network). */
+    async slotAt(posixMs) {
+        const tip = await this.getLatestBlock();
+        return tip.slot + Math.floor((posixMs - tip.time * 1000) / 1000);
+    }
+    getScript(hash) {
+        let cached = this.scripts.get(hash);
+        if (!cached) {
+            cached = (async () => {
+                var _a, _b;
+                const info = await this.request(`scripts/${hash}`);
+                if (info.type === 'timelock')
+                    return { hash, language: 'native', size: Number((_a = info.serialised_size) !== null && _a !== void 0 ? _a : 0) };
+                const language = PLUTUS_LANGUAGE[info.type];
+                if (language === undefined)
+                    throw new Error(`Unknown script type ${info.type} for ${hash}`);
+                const { cbor } = await this.request(`scripts/${hash}/cbor`);
+                // Blockfrost's `cbor` is the script as the ledger hashes it (a CBOR byte string of the flat program).
+                const script = { __type: core_1.Cardano.ScriptType.Plutus, version: language, bytes: cbor };
+                if (core_1.Serialization.Script.fromCore(script).hash() !== hash)
+                    throw new Error(`Script ${hash} CBOR does not hash to ${hash}`);
+                return { hash, language, size: Number((_b = info.serialised_size) !== null && _b !== void 0 ? _b : cbor.length / 2), script };
+            })();
+            cached.catch(() => this.scripts.delete(hash));
+            this.scripts.set(hash, cached);
+        }
+        return cached;
+    }
+    async toUtxo(item, txHash, address) {
+        const scriptReference = item.reference_script_hash ? (await this.getScript(item.reference_script_hash)).script : undefined;
+        return [
+            { txId: core_1.Cardano.TransactionId(txHash), index: item.output_index, address: address },
+            {
+                address: address,
+                value: (0, exports.valueFromBlockfrost)(item.amount),
+                ...(item.inline_datum ? { datum: core_1.Serialization.PlutusData.fromCbor(item.inline_datum).toCore() } : {}),
+                ...(!item.inline_datum && item.data_hash ? { datumHash: item.data_hash } : {}),
+                ...(scriptReference ? { scriptReference } : {})
+            }
+        ];
+    }
+    /** Every UTxO at `address` (paginated). */
+    async getAddressUtxos(address) {
+        var _a;
+        const utxos = [];
+        for (let page = 1;; page++) {
+            const items = (_a = (await this.getOrNull(`addresses/${address}/utxos?page=${page}&count=100`))) !== null && _a !== void 0 ? _a : [];
+            for (const item of items)
+                utxos.push(await this.toUtxo(item, item.tx_hash, address));
+            if (items.length < 100)
+                return utxos;
+        }
+    }
+    /** UTxOs at `address` holding `unit`. */
+    async getAddressAssetUtxos(address, unit) {
+        var _a;
+        const items = (_a = (await this.getOrNull(`addresses/${address}/utxos/${unit}`))) !== null && _a !== void 0 ? _a : [];
+        return Promise.all(items.map((item) => this.toUtxo(item, item.tx_hash, address)));
+    }
+    /** The UTxO `txHash#index`; throws `already spent` when it has been consumed. */
+    async getUtxo(ref) {
+        const [txHash, index] = ref.split('#');
+        const tx = await this.request(`txs/${txHash}/utxos`);
+        const output = tx.outputs.find((o) => o.output_index === Number(index));
+        if (!output)
+            throw new Error(`${ref} does not exist`);
+        if (output.consumed_by_tx)
+            throw new Error(`${ref} already spent by ${output.consumed_by_tx}`);
+        return this.toUtxo(output, txHash, output.address);
+    }
+    /** Node (Ogmios) evaluation of every redeemer; `additionalUtxos` supplies inputs not yet on chain. */
+    async evaluateTx(cbor, additionalUtxos = []) {
+        var _a, _b, _c, _d, _e;
+        const response = await this.request('utils/txs/evaluate/utxos', { method: 'POST', body: JSON.stringify({ cbor, additionalUtxoSet: additionalUtxos.map(exports.toOgmiosUtxo) }) });
+        const result = (_a = response.result) === null || _a === void 0 ? void 0 : _a.EvaluationResult;
+        if (!result)
+            throw new BlockfrostEvaluationError((_d = (_c = (_b = response.result) === null || _b === void 0 ? void 0 : _b.EvaluationFailure) !== null && _c !== void 0 ? _c : response.fault) !== null && _d !== void 0 ? _d : response);
+        const units = new Map();
+        for (const [pointer, { memory, steps }] of Object.entries(result)) {
+            const [purpose, index] = pointer.split(':');
+            units.set(`${(_e = OGMIOS_PURPOSE[purpose]) !== null && _e !== void 0 ? _e : purpose}:${index}`, { memory, steps });
+        }
+        return units;
+    }
+    /** Submit a signed tx; returns its hash. */
+    submitTx(cbor) {
+        return this.request('tx/submit', { method: 'POST', body: Buffer.from(cbor, 'hex'), contentType: 'application/cbor' });
+    }
+}
+exports.BlockfrostTxClient = BlockfrostTxClient;

package/txBuild/fees.d.ts

@@ -0,0 +1,32 @@
+/** A non-negative rational n/d. */
+export interface Ratio {
+    n: bigint;
+    d: bigint;
+}
+/** Exact rational from a decimal number/string as providers report it (0.0577, "0.0000721", 7.21e-5). */
+export declare const ratio: (value: number | string | bigint) => Ratio;
+export interface FeeParameters {
+    /** min_fee_a (lovelace per byte) */
+    minFeeA: bigint;
+    /** min_fee_b (constant lovelace) */
+    minFeeB: bigint;
+    priceMemory: Ratio;
+    priceSteps: Ratio;
+    /** min_fee_ref_script_cost_per_byte (Conway) */
+    minFeeRefScriptCostPerByte: Ratio;
+}
+export interface ExUnits {
+    memory: number | bigint;
+    steps: number | bigint;
+}
+/** ceiling(priceMem * Σmem + priceSteps * Σsteps) — the ledger prices the TOTAL, then rounds once. */
+export declare const scriptExecutionFee: (params: Pick<FeeParameters, "priceMemory" | "priceSteps">, exUnits: ExUnits[]) => bigint;
+/**
+ * Conway's tiered reference-script fee: every 25,600 bytes the per-byte price is multiplied by 1.2;
+ * the sum is floored. `totalBytes` counts every reference script of every spent AND referenced input.
+ */
+export declare const referenceScriptFee: (costPerByte: Ratio, totalBytes: number | bigint) => bigint;
+/** The ledger minimum fee for a tx of `sizeBytes` (as submitted, witnesses included). */
+export declare const minFee: (params: FeeParameters, sizeBytes: number, exUnits: ExUnits[], referenceScriptBytes: number) => bigint;
+/** Babbage/Conway min-UTxO: (160 + |serialized output|) * coinsPerUtxoByte. */
+export declare const minAdaForOutputSize: (coinsPerUtxoByte: bigint, outputSizeBytes: number) => bigint;

package/txBuild/fees.js

@@ -0,0 +1,62 @@
+"use strict";
+// Exact Conway fee / deposit arithmetic (BigInt rationals — no floating point anywhere a ledger rule
+// uses a ratio). Pure: no network, no cardano-sdk.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.minAdaForOutputSize = exports.minFee = exports.referenceScriptFee = exports.scriptExecutionFee = exports.ratio = void 0;
+/** Exact rational from a decimal number/string as providers report it (0.0577, "0.0000721", 7.21e-5). */
+const ratio = (value) => {
+    if (typeof value === 'bigint')
+        return { n: value, d: BigInt(1) };
+    const text = typeof value === 'number' ? value.toString() : value.trim();
+    const match = /^(\d+)(?:\.(\d+))?(?:e([+-]?\d+))?$/i.exec(text);
+    if (!match)
+        throw new Error(`Not a non-negative decimal: ${value}`);
+    const [, whole, fraction = '', exponent = '0'] = match;
+    let n = BigInt(whole + fraction);
+    let d = BigInt(10) ** BigInt(fraction.length);
+    const exp = Number(exponent);
+    if (exp > 0)
+        n *= BigInt(10) ** BigInt(exp);
+    if (exp < 0)
+        d *= BigInt(10) ** BigInt(-exp);
+    return { n, d };
+};
+exports.ratio = ratio;
+const ceilDiv = (n, d) => (n + d - BigInt(1)) / d;
+/** ceiling(priceMem * Σmem + priceSteps * Σsteps) — the ledger prices the TOTAL, then rounds once. */
+const scriptExecutionFee = (params, exUnits) => {
+    const memory = exUnits.reduce((sum, e) => sum + BigInt(e.memory), BigInt(0));
+    const steps = exUnits.reduce((sum, e) => sum + BigInt(e.steps), BigInt(0));
+    const { priceMemory: pm, priceSteps: ps } = params;
+    return ceilDiv(pm.n * memory * ps.d + ps.n * steps * pm.d, pm.d * ps.d);
+};
+exports.scriptExecutionFee = scriptExecutionFee;
+const REF_SCRIPT_SIZE_INCREMENT = BigInt(25600);
+const REF_SCRIPT_MULTIPLIER = { n: BigInt(6), d: BigInt(5) };
+/**
+ * Conway's tiered reference-script fee: every 25,600 bytes the per-byte price is multiplied by 1.2;
+ * the sum is floored. `totalBytes` counts every reference script of every spent AND referenced input.
+ */
+const referenceScriptFee = (costPerByte, totalBytes) => {
+    let remaining = BigInt(totalBytes);
+    let price = costPerByte;
+    let acc = { n: BigInt(0), d: BigInt(1) };
+    const add = (a, b) => ({ n: a.n * b.d + b.n * a.d, d: a.d * b.d });
+    while (remaining >= REF_SCRIPT_SIZE_INCREMENT) {
+        acc = add(acc, { n: price.n * REF_SCRIPT_SIZE_INCREMENT, d: price.d });
+        price = { n: price.n * REF_SCRIPT_MULTIPLIER.n, d: price.d * REF_SCRIPT_MULTIPLIER.d };
+        remaining -= REF_SCRIPT_SIZE_INCREMENT;
+    }
+    acc = add(acc, { n: price.n * remaining, d: price.d });
+    return acc.n / acc.d;
+};
+exports.referenceScriptFee = referenceScriptFee;
+/** The ledger minimum fee for a tx of `sizeBytes` (as submitted, witnesses included). */
+const minFee = (params, sizeBytes, exUnits, referenceScriptBytes) => params.minFeeA * BigInt(sizeBytes) +
+    params.minFeeB +
+    (0, exports.scriptExecutionFee)(params, exUnits) +
+    (0, exports.referenceScriptFee)(params.minFeeRefScriptCostPerByte, referenceScriptBytes);
+exports.minFee = minFee;
+/** Babbage/Conway min-UTxO: (160 + |serialized output|) * coinsPerUtxoByte. */
+const minAdaForOutputSize = (coinsPerUtxoByte, outputSizeBytes) => (BigInt(160) + BigInt(outputSizeBytes)) * coinsPerUtxoByte;
+exports.minAdaForOutputSize = minAdaForOutputSize;

package/txBuild/index.d.ts

@@ -0,0 +1,3 @@
+export * from './fees';
+export * from './scriptTx';
+export * from './blockfrost';

package/txBuild/index.js

@@ -0,0 +1,21 @@
+"use strict";
+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 __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Subpath module: `@koralabs/kora-labs-common/txBuild`. Server-side Plutus transaction building on
+// @cardano-sdk/core (optional peer dependency). NOT re-exported from the root index.
+__exportStar(require("./fees"), exports);
+__exportStar(require("./scriptTx"), exports);
+__exportStar(require("./blockfrost"), exports);

package/txBuild/scriptTx.d.ts

@@ -0,0 +1,79 @@
+import { Cardano, Serialization } from '@cardano-sdk/core';
+import { ExUnits, FeeParameters } from './fees';
+export type PlutusData = Serialization.PlutusData;
+export interface ScriptTxProtocolParameters extends FeeParameters {
+    coinsPerUtxoByte: bigint;
+    maxTxSize: number;
+    maxTxExUnits: {
+        memory: number;
+        steps: number;
+    };
+    /** Ledger-ordered cost models (Blockfrost `cost_models_raw`), keyed by Plutus language. */
+    costModels: Map<Cardano.PlutusLanguageVersion, number[]>;
+}
+export interface ScriptTxPlan {
+    /** Every spent input, resolved. A redeemer marks a Plutus script spend. */
+    inputs: {
+        utxo: Cardano.Utxo;
+        redeemer?: PlutusData;
+    }[];
+    referenceInputs?: Cardano.TxIn[];
+    collateral?: Cardano.TxIn[];
+    /** Kept in this order. Outputs below min-UTxO are topped up to it. */
+    outputs: Cardano.TxOut[];
+    /** One entry per policy. A redeemer marks a Plutus policy (native policies need `nativeScripts`). */
+    mint?: {
+        policyId: string;
+        assets: Map<string, bigint>;
+        redeemer?: PlutusData;
+    }[];
+    withdrawals?: {
+        rewardAccount: string;
+        quantity: bigint;
+        redeemer?: PlutusData;
+    }[];
+    requiredSigners?: string[];
+    nativeScripts?: Cardano.NativeScript[];
+    validityInterval?: Cardano.ValidityInterval;
+    changeAddress: string;
+    /** vkey witnesses the signed tx will carry (sizes the fee). */
+    signerCount: number;
+    /** Languages of every Plutus script the tx runs (from their reference scripts). */
+    plutusLanguages: Cardano.PlutusLanguageVersion[];
+    /** Σ size of every reference script on spent + referenced inputs (Conway ref-script fee). */
+    referenceScriptBytes: number;
+}
+/** Redeemer pointer key: `${purpose}:${index}` (e.g. `spend:1`, `mint:0`, `withdrawal:0`). */
+export type RedeemerKey = string;
+export type Evaluator = (unsignedTxCbor: string) => Promise<Map<RedeemerKey, ExUnits>>;
+export interface FinalizedScriptTx {
+    /** Unsigned tx CBOR (empty vkey witness set). */
+    cbor: string;
+    txId: string;
+    fee: bigint;
+    /** Final outputs, change last. */
+    outputs: Cardano.TxOut[];
+    redeemers: Cardano.Redeemer[];
+}
+/** Raise `output` to its min-UTxO (the coin's own CBOR width is part of the size, so iterate). */
+export declare const withMinAda: (output: Cardano.TxOut, coinsPerUtxoByte: bigint) => Cardano.TxOut;
+/**
+ * script_data_hash = blake2b-256(redeemers ‖ datums? ‖ language_views), over the exact bytes of the
+ * serialized witness-set fields. `datumsCbor` is only for witness-set datums (never inline datums).
+ */
+export declare const computeScriptDataHash: ({ redeemersCbor, datumsCbor, costModels, languages }: {
+    redeemersCbor?: string;
+    datumsCbor?: string;
+    costModels: Map<Cardano.PlutusLanguageVersion, number[]>;
+    languages: Cardano.PlutusLanguageVersion[];
+}) => string | undefined;
+export declare const finalizeScriptTx: (plan: ScriptTxPlan, params: ScriptTxProtocolParameters, evaluate: Evaluator) => Promise<FinalizedScriptTx>;
+/**
+ * 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
+ * script_data_hash covers are untouched.
+ */
+export declare const addVkeyWitnesses: (unsignedCbor: string, witnesses: {
+    vkey: string;
+    signature: string;
+}[]) => string;

package/txBuild/scriptTx.js

@@ -0,0 +1,197 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addVkeyWitnesses = exports.finalizeScriptTx = 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
+// orderings, tops outputs up to min-UTxO, asks the NODE (via `evaluate`) for each redeemer's
+// execution units, converges the fee to the exact ledger minimum, puts the remainder in one change
+// output, and computes script_data_hash over the exact redeemer bytes it serializes.
+//
+// Lessons baked in (handle.me docs/spec/live-tx-lessons-learned.md):
+//  - Conway redeemers are map-encoded; script_data_hash must hash the bytes actually shipped (#1).
+//  - inline datums never enter script_data_hash (#2).
+//  - reference inputs / inputs / policies / withdrawals are indexed in ledger-sorted order (#3).
+//  - execution units come from the node's evaluator, re-checked after the fee settles (the fee and
+//    change are part of the ScriptContext, so a fee change can change the cost).
+const core_1 = require("@cardano-sdk/core");
+const blakejs_1 = require("blakejs");
+const tx_1 = require("../tx");
+const fees_1 = require("./fees");
+(0, core_1.setInConwayEra)(true);
+const byTxIn = (a, b) => (a.txId === b.txId ? a.index - b.index : a.txId < b.txId ? -1 : 1);
+const hexCompare = (a, b) => (a === b ? 0 : a < b ? -1 : 1);
+const rewardAccountBytes = (account) => core_1.Cardano.Address.fromBech32(account).toBytes();
+const outputSize = (output) => core_1.Serialization.TransactionOutput.fromCore(output).toCbor().length / 2;
+/** Raise `output` to its min-UTxO (the coin's own CBOR width is part of the size, so iterate). */
+const withMinAda = (output, coinsPerUtxoByte) => {
+    let current = output;
+    for (let i = 0; i < 5; i++) {
+        const required = (0, fees_1.minAdaForOutputSize)(coinsPerUtxoByte, outputSize(current));
+        if (current.value.coins >= required)
+            return current;
+        current = { ...current, value: { ...current.value, coins: required } };
+    }
+    throw new Error('min-UTxO did not converge');
+};
+exports.withMinAda = withMinAda;
+/**
+ * script_data_hash = blake2b-256(redeemers ‖ datums? ‖ language_views), over the exact bytes of the
+ * serialized witness-set fields. `datumsCbor` is only for witness-set datums (never inline datums).
+ */
+const computeScriptDataHash = ({ redeemersCbor, datumsCbor, costModels, languages }) => {
+    if (!redeemersCbor && !datumsCbor)
+        return undefined;
+    const views = new core_1.Serialization.Costmdls();
+    for (const language of new Set(languages)) {
+        const model = costModels.get(language);
+        if (!model)
+            throw new Error(`No cost model for Plutus language ${language}`);
+        views.insert(new core_1.Serialization.CostModel(language, model));
+    }
+    const EMPTY_MAP = 'a0';
+    const preimage = redeemersCbor ? redeemersCbor + (datumsCbor !== null && datumsCbor !== void 0 ? datumsCbor : '') + views.languageViewsEncoding() : EMPTY_MAP + datumsCbor + EMPTY_MAP;
+    return (0, blakejs_1.blake2bHex)(Buffer.from(preimage, 'hex'), undefined, 32);
+};
+exports.computeScriptDataHash = computeScriptDataHash;
+const placeholderSignatures = (count) => {
+    const signatures = new Map();
+    for (let i = 0; i < count; i++)
+        signatures.set((i + 1).toString(16).padStart(64, '0'), '0'.repeat(128));
+    return signatures;
+};
+const sumValues = (values) => {
+    var _a, _b;
+    let coins = BigInt(0);
+    const assets = new Map();
+    for (const value of values) {
+        coins += value.coins;
+        for (const [id, qty] of (_a = value.assets) !== null && _a !== void 0 ? _a : [])
+            assets.set(id, ((_b = assets.get(id)) !== null && _b !== void 0 ? _b : BigInt(0)) + qty);
+    }
+    return { coins, assets };
+};
+const finalizeScriptTx = async (plan, params, evaluate) => {
+    var _a, _b;
+    const inputs = [...plan.inputs].sort((a, b) => byTxIn(a.utxo[0], b.utxo[0]));
+    const mint = [...((_a = plan.mint) !== null && _a !== void 0 ? _a : [])].sort((a, b) => hexCompare(a.policyId, b.policyId));
+    const withdrawals = [...((_b = plan.withdrawals) !== null && _b !== void 0 ? _b : [])].sort((a, b) => hexCompare(rewardAccountBytes(a.rewardAccount), rewardAccountBytes(b.rewardAccount)));
+    const outputs = plan.outputs.map((output) => (0, exports.withMinAda)(output, params.coinsPerUtxoByte));
+    const pointers = [
+        ...inputs.flatMap(({ redeemer }, index) => (redeemer ? [{ purpose: core_1.Cardano.RedeemerPurpose.spend, index, data: redeemer }] : [])),
+        ...mint.flatMap(({ redeemer }, index) => (redeemer ? [{ purpose: core_1.Cardano.RedeemerPurpose.mint, index, data: redeemer }] : [])),
+        ...withdrawals.flatMap(({ redeemer }, index) => (redeemer ? [{ purpose: core_1.Cardano.RedeemerPurpose.withdrawal, index, data: redeemer }] : []))
+    ];
+    const key = (purpose, index) => `${purpose}:${index}`;
+    const tokenMap = new Map();
+    for (const { policyId, assets } of mint) {
+        for (const [name, qty] of assets)
+            tokenMap.set(core_1.Cardano.AssetId.fromParts(core_1.Cardano.PolicyId(policyId), core_1.Cardano.AssetName(name)), qty);
+    }
+    const inValue = sumValues(inputs.map(({ utxo }) => utxo[1].value));
+    const withdrawn = withdrawals.reduce((sum, w) => sum + w.quantity, BigInt(0));
+    const produced = sumValues(outputs.map((o) => o.value));
+    const changeFor = (fee) => {
+        var _a, _b, _c;
+        const coins = inValue.coins + withdrawn - produced.coins - fee;
+        if (coins < BigInt(0))
+            throw new Error(`Inputs do not cover outputs + fee: ${-coins} lovelace short`);
+        const assets = new Map();
+        const ids = new Set([...inValue.assets.keys(), ...tokenMap.keys(), ...produced.assets.keys()]);
+        for (const id of ids) {
+            const qty = ((_a = inValue.assets.get(id)) !== null && _a !== void 0 ? _a : BigInt(0)) + ((_b = tokenMap.get(id)) !== null && _b !== void 0 ? _b : BigInt(0)) - ((_c = produced.assets.get(id)) !== null && _c !== void 0 ? _c : BigInt(0));
+            if (qty < BigInt(0))
+                throw new Error(`Outputs carry more ${id} than the inputs and mint provide`);
+            if (qty > BigInt(0))
+                assets.set(id, qty);
+        }
+        return { address: plan.changeAddress, value: { coins, ...(assets.size ? { assets } : {}) } };
+    };
+    const assemble = (fee, exUnits, signatures) => {
+        var _a, _b, _c, _d;
+        const change = changeFor(fee);
+        const redeemers = pointers.map(({ purpose, index, data }) => {
+            const units = exUnits.get(key(purpose, index));
+            if (!units)
+                throw new Error(`No execution units for redeemer ${key(purpose, index)}`);
+            return { purpose, index, data: data.toCore(), executionUnits: { memory: Number(units.memory), steps: Number(units.steps) } };
+        });
+        const redeemersCbor = redeemers.length ? core_1.Serialization.Redeemers.fromCore(redeemers).toCbor() : undefined;
+        const scriptIntegrityHash = (0, exports.computeScriptDataHash)({ redeemersCbor, costModels: params.costModels, languages: plan.plutusLanguages });
+        const body = {
+            inputs: inputs.map(({ utxo: [txIn] }) => ({ txId: txIn.txId, index: txIn.index })),
+            outputs: [...outputs, change],
+            fee,
+            ...(((_a = plan.referenceInputs) === null || _a === void 0 ? void 0 : _a.length) ? { referenceInputs: [...plan.referenceInputs].sort(byTxIn) } : {}),
+            ...(((_b = plan.collateral) === null || _b === void 0 ? void 0 : _b.length) ? { collaterals: [...plan.collateral].sort(byTxIn) } : {}),
+            ...(tokenMap.size ? { mint: tokenMap } : {}),
+            ...(withdrawals.length ? { withdrawals: withdrawals.map((w) => ({ stakeAddress: w.rewardAccount, quantity: w.quantity })) } : {}),
+            ...(((_c = plan.requiredSigners) === null || _c === void 0 ? void 0 : _c.length) ? { requiredExtraSignatures: [...new Set(plan.requiredSigners)].sort(hexCompare) } : {}),
+            ...(plan.validityInterval ? { validityInterval: plan.validityInterval } : {}),
+            ...(scriptIntegrityHash ? { scriptIntegrityHash: scriptIntegrityHash } : {})
+        };
+        const tx = core_1.Serialization.Transaction.fromCore({
+            id: '0'.repeat(64),
+            body,
+            witness: {
+                signatures: signatures,
+                ...(redeemers.length ? { redeemers } : {}),
+                ...(((_d = plan.nativeScripts) === null || _d === void 0 ? void 0 : _d.length) ? { scripts: plan.nativeScripts } : {})
+            },
+            isValid: true
+        });
+        return { tx, change, redeemers };
+    };
+    // Evaluation budget placeholder: the node evaluates against the protocol maximum, not the declared units.
+    const share = Math.max(1, pointers.length);
+    const placeholder = new Map(pointers.map(({ purpose, index }) => [key(purpose, index), {
+            memory: Math.floor(params.maxTxExUnits.memory / share),
+            steps: Math.floor(params.maxTxExUnits.steps / share)
+        }]));
+    const sizeOf = (fee, exUnits) => assemble(fee, exUnits, placeholderSignatures(plan.signerCount)).tx.toCbor().length / 2;
+    let exUnits = pointers.length ? await evaluate(assemble(BigInt(0), placeholder, new Map()).tx.toCbor()) : new Map();
+    let fee = BigInt(0);
+    for (let round = 0; round < 6; round++) {
+        // Converge the fee for these units: the fee's own CBOR width changes the size it pays for.
+        for (let i = 0; i < 6; i++) {
+            const needed = (0, fees_1.minFee)(params, sizeOf(fee, exUnits), [...exUnits.values()], plan.referenceScriptBytes);
+            if (needed <= fee)
+                break;
+            fee = needed;
+        }
+        if (!pointers.length)
+            break;
+        // The fee and change are part of the ScriptContext: re-evaluate the tx we would actually submit.
+        const reevaluated = await evaluate(assemble(fee, exUnits, new Map()).tx.toCbor());
+        const unchanged = [...reevaluated].every(([k, u]) => {
+            const prior = exUnits.get(k);
+            return prior && BigInt(prior.memory) === BigInt(u.memory) && BigInt(prior.steps) === BigInt(u.steps);
+        });
+        exUnits = reevaluated;
+        if (unchanged && (0, fees_1.minFee)(params, sizeOf(fee, exUnits), [...exUnits.values()], plan.referenceScriptBytes) <= fee)
+            break;
+        if (round === 5)
+            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 signedSize = sizeOf(fee, exUnits);
+    if (signedSize > params.maxTxSize)
+        throw new Error(`Transaction is ${signedSize} bytes, above the ${params.maxTxSize} byte limit`);
+    return { cbor: tx.toCbor(), txId: tx.getId(), fee, outputs: [...outputs, change], redeemers };
+};
+exports.finalizeScriptTx = finalizeScriptTx;
+/**
+ * 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
+ * script_data_hash covers are untouched.
+ */
+const addVkeyWitnesses = (unsignedCbor, witnesses) => {
+    const witnessSet = core_1.Serialization.TransactionWitnessSet.fromCore({
+        signatures: new Map(witnesses.map(({ vkey, signature }) => [vkey, signature]))
+    });
+    return (0, tx_1.mergeWitnessSet)(unsignedCbor, witnessSet.toCbor());
+};
+exports.addVkeyWitnesses = addVkeyWitnesses;

package/utils/cbor/index.d.ts

@@ -1,3 +1,4 @@
+import * as cbor from 'cbor';
 export { designerSchema } from './schema/designer';
 export { handleDatumSchema } from './schema/handleData';
 export { marketplaceDatumSchema } from './schema/marketplaceDatum';
@@ -52,6 +53,7 @@ export declare class DupeKey extends JsonToDatumObject {
     constructor(key: string);
 }
 export declare const encodeJsonToDatum: (json: any, options?: EncodeOptions) => Promise<string>;
+export declare const constrToTagged: (index: number, fields: unknown) => cbor.Tagged;
 export declare const decodeCborToJson: ({ cborString, schema, defaultKeyType, forJson }: {
     cborString: string;
     schema?: any;