@koralabs/kora-labs-common 6.14.2 → 6.15.0

package/cronLock/cqlCronLock.js

@@ -148,26 +148,41 @@ const acquireWithExecutor = async (executor, name, offline, topology, token = cr
             // The LWT timed out: it may have been applied WITH OUR TOKEN, in which case nobody (not even
             // us) could run until the lease expired. A read at the same serial consistency completes any
             // in-flight Paxos round, so it tells us the real owner.
-            const owner = await readOwner(executor, key, serialConsistency);
-            if (owner === token)
+            const read = await readOwner(executor, key, serialConsistency);
+            if (read.owner === token)
                 return { status: 'acquired', token };
-            if (owner)
+            if (read.owner)
                 return { status: 'held' };
+            if (read.error) {
+                // Still unknown and we will not run: retract our possibly-applied proposal so it cannot
+                // block every box for the whole lease. Conditional on our token, so it never frees another's lock.
+                const retracted = await deleteIfOwner(executor, key, token, serialConsistency, consistency);
+                return { status: 'unavailable', message: `${message}; owner read failed (${read.error}); ${retracted ? 'retracted our proposal' : 'retract failed, the lease will reclaim it'}` };
+            }
         }
         return { status: 'unavailable', message };
     }
 };
 exports.acquireWithExecutor = acquireWithExecutor;
-/** The lock's owner as a linearizable (serial) read sees it; undefined when absent or unreadable. */
+/** The lock's owner as a linearizable (serial) read sees it. */
 const readOwner = async (executor, key, serialConsistency) => {
     var _a;
     try {
         const result = await executor.execute(`SELECT owner FROM ${KEYSPACE}.${LOCK_TABLE} WHERE name = ?`, [key], { prepare: true, consistency: serialConsistency });
         const owner = (_a = result.rows[0]) === null || _a === void 0 ? void 0 : _a.owner;
-        return typeof owner === 'string' ? owner : undefined;
+        return typeof owner === 'string' ? { owner } : {};
     }
-    catch (_b) {
-        return undefined;
+    catch (error) {
+        return { error: error instanceof Error ? error.message : String(error) };
+    }
+};
+const deleteIfOwner = async (executor, key, token, serialConsistency, consistency) => {
+    try {
+        await executor.execute(`DELETE FROM ${KEYSPACE}.${LOCK_TABLE} WHERE name = ? IF owner = ?`, [key, token], { prepare: true, serialConsistency, consistency });
+        return true;
+    }
+    catch (_a) {
+        return false;
     }
 };
 const acquire = async (name, offline, options = {}) => {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@koralabs/kora-labs-common",
-    "version": "6.14.2",
+    "version": "6.15.0",
     "description": "Kora Labs Common Utilities",
     "main": "index.js",
     "types": "index.d.ts",
@@ -52,6 +52,7 @@
         "cassandra-driver": "^4.10.0",
         "eslint": "^8.57.1",
         "jest": "^30.4.2",
+        "scalus": "^0.15.0",
         "ts-jest": "^29.4.11",
         "typescript": "^5.9.3"
     },
@@ -77,7 +78,8 @@
         "@cardano-sdk/crypto": "^0.4.5",
         "@emurgo/cardano-message-signing-nodejs": "^1.1.0",
         "bip39": "^3.1.0",
-        "cassandra-driver": "^4.9.0"
+        "cassandra-driver": "^4.9.0",
+        "scalus": "^0.15.0"
     },
     "peerDependenciesMeta": {
         "@aiken-lang/merkle-patricia-forestry": {
@@ -97,6 +99,9 @@
         },
         "cassandra-driver": {
             "optional": true
+        },
+        "scalus": {
+            "optional": true
         }
     }
 }

package/txBuild/blockfrost.js

@@ -109,6 +109,7 @@ class BlockfrostTxClient {
             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

package/txBuild/index.d.ts

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

package/txBuild/index.js

@@ -19,3 +19,4 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./fees"), exports);
 __exportStar(require("./scriptTx"), exports);
 __exportStar(require("./blockfrost"), exports);
+__exportStar(require("./scalus"), exports);

package/txBuild/scalus.d.ts

@@ -0,0 +1,26 @@
+import { Cardano, Serialization } from '@cardano-sdk/core';
+import { Evaluator } from './scriptTx';
+/**
+ * Scripts come in two forms: "single CBOR" — a CBOR byte string of the flat program, as Aiken
+ * blueprints, Blockfrost `/scripts/{hash}/cbor` and cardano-sdk's `PlutusScript.bytes` hold it — and
+ * "double CBOR" — that wrapped once more, as scalus reads and writes it.
+ */
+export declare const toDoubleCbor: (cborHex: string) => string;
+export declare const toSingleCbor: (cborHex: string) => string;
+/** Plutus data in the node's JSON form (what scalus.applyDataArgToScript reads). */
+export declare const plutusDataToJson: (data: Serialization.PlutusData) => unknown;
+/** Apply parameters (in order) to a compiled validator; returns the script in single-CBOR form. */
+export declare const applyParamsToScript: (compiledCode: string, params: Serialization.PlutusData[]) => string;
+/** A Plutus script (single- or double-CBOR) as a cardano-sdk Script. */
+export declare const plutusScript: (cborHex: string, version: Cardano.PlutusLanguageVersion) => Cardano.PlutusScript;
+/** The script hash of a (single- or double-CBOR) Plutus script of `version`. */
+export declare const plutusScriptHash: (cborHex: string, version: Cardano.PlutusLanguageVersion) => string;
+/**
+ * An Evaluator that runs the tx's scripts locally (scalus) against `utxos` — every spent AND
+ * referenced UTxO, reference scripts included. Offline stand-in for the node's evaluation.
+ */
+export declare const localEvaluator: ({ utxos, costModels, network }: {
+    utxos: Cardano.Utxo[];
+    costModels: Map<Cardano.PlutusLanguageVersion, number[]>;
+    network: "mainnet" | "preview" | "preprod";
+}) => Evaluator;

package/txBuild/scalus.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.localEvaluator = exports.plutusScriptHash = exports.plutusScript = exports.applyParamsToScript = exports.plutusDataToJson = exports.toSingleCbor = exports.toDoubleCbor = void 0;
+// Local UPLC work on scalus (optional peer dependency, loaded on first use): applying parameters to a
+// compiled validator (replaces Helios' UplcProgram.apply) and evaluating a tx's scripts offline.
+// Production code evaluates with the node (BlockfrostTxClient.evaluateTx); the local evaluator is for
+// tests and tooling that must run without a network.
+const core_1 = require("@cardano-sdk/core");
+let scalusModule;
+// Lazy: scalus is an optional peer, needed only by callers of these helpers.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const scalus = () => (scalusModule !== null && scalusModule !== void 0 ? scalusModule : (scalusModule = require('scalus')));
+const cborByteStringHeader = (length) => {
+    if (length <= 23)
+        return Buffer.from([0x40 | length]);
+    if (length <= 0xff)
+        return Buffer.from([0x58, length]);
+    if (length <= 0xffff)
+        return Buffer.from([0x59, length >> 8, length & 0xff]);
+    return Buffer.from([0x5a, (length >>> 24) & 0xff, (length >> 16) & 0xff, (length >> 8) & 0xff, length & 0xff]);
+};
+/** [header length, content length] of the CBOR byte string at the start of `bytes`. */
+const byteStringHeader = (bytes) => {
+    if (bytes.length === 0 || bytes[0] >> 5 !== 2)
+        throw new Error('expected a CBOR byte string');
+    const info = bytes[0] & 0x1f;
+    if (info <= 23)
+        return [1, info];
+    if (info === 24)
+        return [2, bytes[1]];
+    if (info === 25)
+        return [3, bytes.readUInt16BE(1)];
+    if (info === 26)
+        return [5, bytes.readUInt32BE(1)];
+    throw new Error(`unsupported CBOR byte string header 0x${bytes[0].toString(16)}`);
+};
+const isDoubleCbor = (bytes) => {
+    const [headerLength] = byteStringHeader(bytes);
+    return bytes[headerLength] >> 5 === 2;
+};
+/**
+ * Scripts come in two forms: "single CBOR" — a CBOR byte string of the flat program, as Aiken
+ * blueprints, Blockfrost `/scripts/{hash}/cbor` and cardano-sdk's `PlutusScript.bytes` hold it — and
+ * "double CBOR" — that wrapped once more, as scalus reads and writes it.
+ */
+const toDoubleCbor = (cborHex) => {
+    const bytes = Buffer.from(cborHex, 'hex');
+    return isDoubleCbor(bytes) ? cborHex : Buffer.concat([cborByteStringHeader(bytes.length), bytes]).toString('hex');
+};
+exports.toDoubleCbor = toDoubleCbor;
+const toSingleCbor = (cborHex) => {
+    const bytes = Buffer.from(cborHex, 'hex');
+    if (!isDoubleCbor(bytes))
+        return cborHex;
+    const [headerLength, length] = byteStringHeader(bytes);
+    return bytes.subarray(headerLength, headerLength + length).toString('hex');
+};
+exports.toSingleCbor = toSingleCbor;
+/** Plutus data in the node's JSON form (what scalus.applyDataArgToScript reads). */
+const plutusDataToJson = (data) => {
+    const c = data.asConstrPlutusData();
+    if (c) {
+        const fields = c.getData();
+        return { constructor: Number(c.getAlternative()), fields: Array.from({ length: fields.getLength() }, (_, i) => (0, exports.plutusDataToJson)(fields.get(i))) };
+    }
+    const bytes = data.asBoundedBytes();
+    if (bytes)
+        return { bytes: Buffer.from(bytes).toString('hex') };
+    const integer = data.asInteger();
+    if (integer !== undefined) {
+        if (integer > BigInt(Number.MAX_SAFE_INTEGER) || integer < BigInt(Number.MIN_SAFE_INTEGER))
+            throw new Error(`integer parameter ${integer} is outside the safe range scalus accepts`);
+        return { int: Number(integer) };
+    }
+    const items = data.asList();
+    if (items)
+        return { list: Array.from({ length: items.getLength() }, (_, i) => (0, exports.plutusDataToJson)(items.get(i))) };
+    const map = data.asMap();
+    if (map) {
+        const keys = map.getKeys();
+        return { map: Array.from({ length: keys.getLength() }, (_, i) => ({ k: (0, exports.plutusDataToJson)(keys.get(i)), v: (0, exports.plutusDataToJson)(map.get(keys.get(i))) })) };
+    }
+    throw new Error('unsupported Plutus data');
+};
+exports.plutusDataToJson = plutusDataToJson;
+/** Apply parameters (in order) to a compiled validator; returns the script in single-CBOR form. */
+const applyParamsToScript = (compiledCode, params) => (0, exports.toSingleCbor)(params.reduce((script, param) => scalus().Scalus.applyDataArgToScript(script, JSON.stringify((0, exports.plutusDataToJson)(param))), (0, exports.toDoubleCbor)(compiledCode)));
+exports.applyParamsToScript = applyParamsToScript;
+/** A Plutus script (single- or double-CBOR) as a cardano-sdk Script. */
+const plutusScript = (cborHex, version) => ({
+    __type: core_1.Cardano.ScriptType.Plutus,
+    version,
+    bytes: (0, exports.toSingleCbor)(cborHex)
+});
+exports.plutusScript = plutusScript;
+/** The script hash of a (single- or double-CBOR) Plutus script of `version`. */
+const plutusScriptHash = (cborHex, version) => core_1.Serialization.Script.fromCore((0, exports.plutusScript)(cborHex, version)).hash();
+exports.plutusScriptHash = plutusScriptHash;
+const PURPOSE = { spend: 'spend', mint: 'mint', cert: 'certificate', certificate: 'certificate', reward: 'withdrawal', withdraw: 'withdrawal', withdrawal: 'withdrawal' };
+/**
+ * An Evaluator that runs the tx's scripts locally (scalus) against `utxos` — every spent AND
+ * referenced UTxO, reference scripts included. Offline stand-in for the node's evaluation.
+ */
+const localEvaluator = ({ utxos, costModels, network }) => {
+    const writer = new core_1.Serialization.CborWriter();
+    writer.writeStartMap(utxos.length);
+    for (const [txIn, txOut] of utxos) {
+        writer.writeEncodedValue(Buffer.from(core_1.Serialization.TransactionInput.fromCore(txIn).toCbor(), 'hex'));
+        writer.writeEncodedValue(Buffer.from(core_1.Serialization.TransactionOutput.fromCore(txOut).toCbor(), 'hex'));
+    }
+    const utxoCbor = writer.encode();
+    const models = [core_1.Cardano.PlutusLanguageVersion.V1, core_1.Cardano.PlutusLanguageVersion.V2, core_1.Cardano.PlutusLanguageVersion.V3].map((v) => { var _a; return (_a = costModels.get(v)) !== null && _a !== void 0 ? _a : []; });
+    return async (txCbor) => {
+        const { Scalus, SlotConfig } = scalus();
+        const results = Scalus.evalPlutusScripts(Buffer.from(txCbor, 'hex'), utxoCbor, SlotConfig[network], models);
+        return new Map(results.map((r) => { var _a; return [`${(_a = PURPOSE[String(r.tag).toLowerCase()]) !== null && _a !== void 0 ? _a : String(r.tag).toLowerCase()}:${r.index}`, { memory: Number(r.budget.memory), steps: Number(r.budget.steps) }]; }));
+    };
+};
+exports.localEvaluator = localEvaluator;

package/txBuild/scriptTx.d.ts

@@ -3,6 +3,8 @@ import { ExUnits, FeeParameters } from './fees';
 export type PlutusData = Serialization.PlutusData;
 export interface ScriptTxProtocolParameters extends FeeParameters {
     coinsPerUtxoByte: bigint;
+    /** key_deposit: what a (pre-Conway-style) stake registration certificate locks. */
+    stakeKeyDeposit: bigint;
     maxTxSize: number;
     maxTxExUnits: {
         memory: number;
@@ -32,6 +34,8 @@ export interface ScriptTxPlan {
         quantity: bigint;
         redeemer?: PlutusData;
     }[];
+    /** Stake (de)registrations; their deposits/refunds are balanced into the change. No certificate redeemers. */
+    certificates?: Cardano.Certificate[];
     requiredSigners?: string[];
     nativeScripts?: Cardano.NativeScript[];
     validityInterval?: Cardano.ValidityInterval;
@@ -67,7 +71,15 @@ export declare const computeScriptDataHash: ({ redeemersCbor, datumsCbor, costMo
     costModels: Map<Cardano.PlutusLanguageVersion, number[]>;
     languages: Cardano.PlutusLanguageVersion[];
 }) => string | undefined;
+/** Lovelace a certificate locks (positive) or releases (negative). */
+export declare const certificateDeposit: (certificate: Cardano.Certificate, stakeKeyDeposit: bigint) => 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
+ * hold `lovelace` (callers include a fee/min-UTxO allowance; the finalizer returns the excess as change).
+ * 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[];
 /**
  * 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.finalizeScriptTx = exports.computeScriptDataHash = exports.withMinAda = void 0;
+exports.addVkeyWitnesses = exports.selectWalletInputs = exports.finalizeScriptTx = 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
@@ -60,6 +60,22 @@ const placeholderSignatures = (count) => {
         signatures.set((i + 1).toString(16).padStart(64, '0'), '0'.repeat(128));
     return signatures;
 };
+/** Lovelace a certificate locks (positive) or releases (negative). */
+const certificateDeposit = (certificate, stakeKeyDeposit) => {
+    switch (certificate.__typename) {
+        case core_1.Cardano.CertificateType.StakeRegistration:
+            return stakeKeyDeposit;
+        case core_1.Cardano.CertificateType.StakeDeregistration:
+            return -stakeKeyDeposit;
+        case core_1.Cardano.CertificateType.Registration:
+            return certificate.deposit;
+        case core_1.Cardano.CertificateType.Unregistration:
+            return -certificate.deposit;
+        default:
+            throw new Error(`Certificate ${certificate.__typename} is not supported by finalizeScriptTx`);
+    }
+};
+exports.certificateDeposit = certificateDeposit;
 const sumValues = (values) => {
     var _a, _b;
     let coins = BigInt(0);
@@ -72,7 +88,7 @@ const sumValues = (values) => {
     return { coins, assets };
 };
 const finalizeScriptTx = async (plan, params, evaluate) => {
-    var _a, _b;
+    var _a, _b, _c;
     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)));
@@ -90,10 +106,11 @@ const finalizeScriptTx = async (plan, params, evaluate) => {
     }
     const inValue = sumValues(inputs.map(({ utxo }) => utxo[1].value));
     const withdrawn = withdrawals.reduce((sum, w) => sum + w.quantity, BigInt(0));
+    const deposited = ((_c = plan.certificates) !== null && _c !== void 0 ? _c : []).reduce((sum, c) => sum + (0, exports.certificateDeposit)(c, params.stakeKeyDeposit), 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;
+        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`);
         const assets = new Map();
@@ -108,7 +125,7 @@ const finalizeScriptTx = async (plan, params, evaluate) => {
         return { address: plan.changeAddress, value: { coins, ...(assets.size ? { assets } : {}) } };
     };
     const assemble = (fee, exUnits, signatures) => {
-        var _a, _b, _c, _d;
+        var _a, _b, _c, _d, _e;
         const change = changeFor(fee);
         const redeemers = pointers.map(({ purpose, index, data }) => {
             const units = exUnits.get(key(purpose, index));
@@ -125,8 +142,9 @@ const finalizeScriptTx = async (plan, params, evaluate) => {
             ...(((_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 } : {}),
+            ...(((_c = plan.certificates) === null || _c === void 0 ? void 0 : _c.length) ? { certificates: plan.certificates } : {}),
             ...(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) } : {}),
+            ...(((_d = plan.requiredSigners) === null || _d === void 0 ? void 0 : _d.length) ? { requiredExtraSignatures: [...new Set(plan.requiredSigners)].sort(hexCompare) } : {}),
             ...(plan.validityInterval ? { validityInterval: plan.validityInterval } : {}),
             ...(scriptIntegrityHash ? { scriptIntegrityHash: scriptIntegrityHash } : {})
         };
@@ -136,7 +154,7 @@ const finalizeScriptTx = async (plan, params, evaluate) => {
             witness: {
                 signatures: signatures,
                 ...(redeemers.length ? { redeemers } : {}),
-                ...(((_d = plan.nativeScripts) === null || _d === void 0 ? void 0 : _d.length) ? { scripts: plan.nativeScripts } : {})
+                ...(((_e = plan.nativeScripts) === null || _e === void 0 ? void 0 : _e.length) ? { scripts: plan.nativeScripts } : {})
             },
             isValid: true
         });
@@ -183,6 +201,36 @@ const finalizeScriptTx = async (plan, params, evaluate) => {
     return { cbor: tx.toCbor(), txId: tx.getId(), fee, outputs: [...outputs, change], redeemers };
 };
 exports.finalizeScriptTx = finalizeScriptTx;
+/**
+ * Wallet inputs for a tx whose other inputs are fixed: ADA-only UTxOs first, largest first, until they
+ * hold `lovelace` (callers include a fee/min-UTxO allowance; the finalizer returns the excess as change).
+ * UTxOs carrying tokens are only used when ADA-only ones do not suffice (their tokens go to change).
+ */
+const selectWalletInputs = (utxos, lovelace, exclude = new Set()) => {
+    const key = ([txIn]) => `${txIn.txId}#${txIn.index}`;
+    const candidates = utxos
+        .filter((u) => !exclude.has(key(u)))
+        .sort((a, b) => {
+        var _a, _b;
+        const tokensA = ((_a = a[1].value.assets) === null || _a === void 0 ? void 0 : _a.size) ? 1 : 0;
+        const tokensB = ((_b = b[1].value.assets) === null || _b === void 0 ? void 0 : _b.size) ? 1 : 0;
+        if (tokensA !== tokensB)
+            return tokensA - tokensB;
+        return a[1].value.coins === b[1].value.coins ? 0 : a[1].value.coins > b[1].value.coins ? -1 : 1;
+    });
+    const selected = [];
+    let total = BigInt(0);
+    for (const utxo of candidates) {
+        if (total >= lovelace)
+            break;
+        selected.push(utxo);
+        total += utxo[1].value.coins;
+    }
+    if (total < lovelace)
+        throw new Error(`Wallet holds ${total} spendable lovelace; ${lovelace} needed`);
+    return selected;
+};
+exports.selectWalletInputs = selectWalletInputs;
 /**
  * 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