@koralabs/kora-labs-common 6.13.3 → 6.14.0

package/chain/index.d.ts

@@ -1,4 +1,5 @@
 export * from './transport/fetchProviderJson';
+export * from './transport/rateLimit';
 export * from './failover/interfaces';
 export * from './failover/ChainProviderFailover';
 export * from './cache/ShortTermCache';

package/chain/index.js

@@ -18,6 +18,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 // NOT re-exported from the root index — this is a server-side chain-access layer and pulls Node-only
 // deps. Keeping it off the root barrel preserves the isomorphic root (same rule the `aws` module follows).
 __exportStar(require("./transport/fetchProviderJson"), exports);
+__exportStar(require("./transport/rateLimit"), exports);
 __exportStar(require("./failover/interfaces"), exports);
 __exportStar(require("./failover/ChainProviderFailover"), exports);
 __exportStar(require("./cache/ShortTermCache"), exports);

package/chain/transport/fetchProviderJson.d.ts

@@ -1,26 +1,30 @@
+import { HeaderReader } from './rateLimit';
 export type ProviderName = 'Koios' | 'Blockfrost';
 type ProviderFetcher = (url: string, init?: {
     method?: string;
     headers?: Record<string, string>;
-    body?: string;
+    body?: string | Uint8Array;
 }) => Promise<{
     ok: boolean;
     status: number;
     statusText: string;
     text: () => Promise<string>;
+    headers?: HeaderReader;
 }>;
 export interface ProviderRequestOptions {
     provider: ProviderName;
     url: string;
     method?: string;
     headers?: Record<string, string>;
-    body?: string;
+    body?: string | Uint8Array;
     maxRetries?: number;
     retryBaseDelayMs?: number;
     maxRps?: number;
     rateLimitKey?: string;
+    /** Longest server-stated rate-limit wait to sit out in-process; longer waits throw RateLimitedError. */
+    maxRateLimitWaitMs?: number;
     fetcher?: ProviderFetcher;
 }
 export declare const isRetriableError: (provider: ProviderName, error: any) => boolean;
-export declare const fetchProviderJson: <T>({ provider, url, method, headers, body, maxRetries, retryBaseDelayMs, maxRps, rateLimitKey, fetcher }: ProviderRequestOptions) => Promise<T>;
+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

@@ -2,20 +2,23 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.fetchProviderJson = exports.isRetriableError = void 0;
 const utils_1 = require("../../utils");
+const rateLimit_1 = require("./rateLimit");
 const DEFAULT_MAX_RPS = 5;
 const DEFAULT_MAX_RETRIES = 2;
 const DEFAULT_RETRY_BASE_DELAY_MS = 500;
-const RETRIABLE_STATUS_CODES = new Set([403, 408, 425, 429, 500, 502, 503, 504]);
+const DEFAULT_MAX_RATE_LIMIT_WAIT_MS = 30000;
+const MAX_RATE_LIMIT_WAITS = 3;
+// 429 is deliberately absent: a rate limit is retried only after the wait the server states (see
+// fetchProviderJson), never on a blind backoff.
+const RETRIABLE_STATUS_CODES = new Set([403, 408, 425, 500, 502, 503, 504]);
 const RETRIABLE_MESSAGE_SNIPPETS = [
     'terminated',
     'socket',
     'econnreset',
     'fetch failed',
     'gateway timeout',
-    'too many requests',
     'payload too large',
     'timed out acquiring connection from connection pool',
-    'rate limit',
     'service unavailable',
     'temporarily unavailable'
 ];
@@ -126,16 +129,25 @@ const isRetriableError = (provider, error) => {
 };
 exports.isRetriableError = isRetriableError;
 const defaultFetch = (url, init) => globalThis.fetch(url, init);
-const fetchProviderJson = async ({ provider, url, method = 'GET', headers, body, maxRetries = DEFAULT_MAX_RETRIES, retryBaseDelayMs = DEFAULT_RETRY_BASE_DELAY_MS, maxRps = DEFAULT_MAX_RPS, rateLimitKey = provider, fetcher = defaultFetch }) => {
+const fetchProviderJson = async ({ provider, url, method = 'GET', headers, body, maxRetries = DEFAULT_MAX_RETRIES, retryBaseDelayMs = DEFAULT_RETRY_BASE_DELAY_MS, maxRps = DEFAULT_MAX_RPS, rateLimitKey = provider, maxRateLimitWaitMs = DEFAULT_MAX_RATE_LIMIT_WAIT_MS, fetcher = defaultFetch }) => {
     var _a, _b, _c, _d;
     let attempt = 0;
+    let rateLimitWaits = 0;
     // Retry loop: exits only via return (success) or throw (non-retriable / retries exhausted).
     // eslint-disable-next-line no-constant-condition
     while (true) {
+        // A wait recorded by ANY earlier call on this key (this process) is honored before calling again.
+        await (0, rateLimit_1.waitForRateLimit)(rateLimitKey, maxRateLimitWaitMs);
+        let rateLimited;
         try {
             const response = await runRateLimitedTask(rateLimitKey, maxRps, () => fetcher(url, { method, headers, body }));
             const responseText = await response.text();
             const { value: parsed, parseError } = parseJson(responseText);
+            if (response.ok && isQuotaExhausted(response.headers)) {
+                const waitMs = (0, rateLimit_1.statedWaitMs)(response.headers, undefined);
+                if (waitMs !== null)
+                    (0, rateLimit_1.recordRateLimit)(rateLimitKey, waitMs);
+            }
             if (parseError && responseText) {
                 throw createProviderError({
                     provider,
@@ -149,9 +161,18 @@ const fetchProviderJson = async ({ provider, url, method = 'GET', headers, body,
             if (!response.ok || payloadError) {
                 const status = Number((_b = (_a = payloadError === null || payloadError === void 0 ? void 0 : payloadError.status_code) !== null && _a !== void 0 ? _a : payloadError === null || payloadError === void 0 ? void 0 : payloadError.status) !== null && _b !== void 0 ? _b : response.status);
                 const statusText = response.statusText || `${(_d = (_c = payloadError === null || payloadError === void 0 ? void 0 : payloadError.error) !== null && _c !== void 0 ? _c : payloadError === null || payloadError === void 0 ? void 0 : payloadError.message) !== null && _d !== void 0 ? _d : 'Request failed'}`;
-                throw createProviderError({ provider, status, statusText, payload: payloadError !== null && payloadError !== void 0 ? payloadError : parsed, responseText });
+                const error = createProviderError({ provider, status, statusText, payload: payloadError !== null && payloadError !== void 0 ? payloadError : parsed, responseText });
+                const waitMs = (0, rateLimit_1.statedWaitMs)(response.headers, parsed);
+                if (status === 429 || waitMs !== null) {
+                    rateLimited = { waitMs, error };
+                }
+                else {
+                    throw error;
+                }
+            }
+            else {
+                return parsed;
             }
-            return parsed;
         }
         catch (error) {
             if (attempt >= maxRetries || !(0, exports.isRetriableError)(provider, error)) {
@@ -159,7 +180,18 @@ const fetchProviderJson = async ({ provider, url, method = 'GET', headers, body,
             }
             attempt++;
             await delay(retryBaseDelayMs * attempt);
+            continue;
+        }
+        // Rate limited: never call again before the stated time; with no stated time, stop.
+        const { waitMs, error } = rateLimited;
+        if (waitMs === null)
+            throw error;
+        (0, rateLimit_1.recordRateLimit)(rateLimitKey, waitMs);
+        // Sitting out a stated wait is not a blind retry, so it does not spend `maxRetries` — but it is bounded.
+        if (++rateLimitWaits > MAX_RATE_LIMIT_WAITS || waitMs > maxRateLimitWaitMs) {
+            throw new rateLimit_1.RateLimitedError(rateLimitKey, waitMs, error.message);
         }
     }
 };
 exports.fetchProviderJson = fetchProviderJson;
+const isQuotaExhausted = (headers) => { var _a, _b; return ((_a = headers === null || headers === void 0 ? void 0 : headers.get('x-ratelimit-remaining')) === null || _a === void 0 ? void 0 : _a.trim()) === '0' || ((_b = headers === null || headers === void 0 ? void 0 : headers.get('ratelimit-remaining')) === null || _b === void 0 ? void 0 : _b.trim()) === '0'; };

package/chain/transport/rateLimit.d.ts

@@ -0,0 +1,21 @@
+export interface HeaderReader {
+    get(name: string): string | null | undefined;
+}
+export declare class RateLimitedError extends Error {
+    readonly key: string;
+    readonly retryAfterMs: number;
+    constructor(key: string, retryAfterMs: number, detail?: string);
+}
+/**
+ * The wait (ms) a response asks for, or null when it states none. Covers Retry-After (seconds or
+ * date), X-RateLimit-Reset-After, RateLimit-Reset, X-RateLimit-Remaining: 0 + X-RateLimit-Reset,
+ * and waits written in the body (Discord `retry_after`, Google `RetryInfo.retryDelay`).
+ */
+export declare const statedWaitMs: (headers: HeaderReader | undefined, body: unknown, now?: number) => number | null;
+/** Record that `key` must not be called for `waitMs` (only ever extends an existing block). */
+export declare const recordRateLimit: (key: string, waitMs: number, now?: number) => void;
+export declare const rateLimitWaitRemainingMs: (key: string, now?: number) => number;
+/** Wait out a recorded limit before calling `key`; throw (returning the wait) when it exceeds `maxWaitMs`. */
+export declare const waitForRateLimit: (key: string, maxWaitMs: number) => Promise<void>;
+/** Test seam: forget every recorded limit. */
+export declare const resetRateLimits: () => void;

package/chain/transport/rateLimit.js

@@ -0,0 +1,101 @@
+"use strict";
+// Rate-limit signals are law: every provider call honors the wait a server states, remembers it for
+// the whole process (so other callers don't hit the same limit), and never retries early. When the
+// stated wait is too long to hold the caller, it stops and hands the wait back (RateLimitedError).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resetRateLimits = exports.waitForRateLimit = exports.rateLimitWaitRemainingMs = exports.recordRateLimit = exports.statedWaitMs = exports.RateLimitedError = void 0;
+class RateLimitedError extends Error {
+    constructor(key, retryAfterMs, detail = '') {
+        super(`Rate limited by ${key}: retry after ${Math.ceil(retryAfterMs / 1000)}s${detail ? ` (${detail})` : ''}`);
+        this.key = key;
+        this.retryAfterMs = retryAfterMs;
+        this.name = 'RateLimitedError';
+    }
+}
+exports.RateLimitedError = RateLimitedError;
+const blockedUntilByKey = new Map();
+const toMs = (seconds) => Math.max(0, Math.ceil(seconds * 1000));
+const parseSeconds = (raw) => {
+    if (raw === null || raw === undefined || raw.trim() === '')
+        return null;
+    const value = Number(raw.trim().replace(/s$/i, ''));
+    return Number.isFinite(value) ? value : null;
+};
+/** `Retry-After` is either delta-seconds or an HTTP date. */
+const parseRetryAfter = (raw, now) => {
+    const seconds = parseSeconds(raw);
+    if (seconds !== null)
+        return toMs(seconds);
+    if (!raw)
+        return null;
+    const date = Date.parse(raw);
+    return Number.isFinite(date) ? Math.max(0, date - now) : null;
+};
+/** `X-RateLimit-Reset` is an epoch (seconds or ms) on most APIs, a delta on a few; disambiguate by size. */
+const parseReset = (raw, now) => {
+    const value = parseSeconds(raw);
+    if (value === null)
+        return null;
+    if (value > 1e12)
+        return Math.max(0, value - now); // epoch ms
+    if (value > 1e9)
+        return Math.max(0, value * 1000 - now); // epoch seconds
+    return toMs(value); // delta seconds
+};
+const bodyWaitMs = (body) => {
+    var _a, _b;
+    if (!body || typeof body !== 'object')
+        return null;
+    const record = body;
+    // Discord: { retry_after: seconds }
+    const retryAfter = parseSeconds(record.retry_after === undefined ? undefined : String(record.retry_after));
+    if (retryAfter !== null)
+        return toMs(retryAfter);
+    // Google: { error: { details: [{ '@type': '...RetryInfo', retryDelay: '1.5s' }] } }
+    const details = (_b = (_a = record.error) === null || _a === void 0 ? void 0 : _a.details) !== null && _b !== void 0 ? _b : [];
+    const retryInfo = details.find((d) => typeof (d === null || d === void 0 ? void 0 : d['@type']) === 'string' && d['@type'].endsWith('RetryInfo'));
+    const delay = parseSeconds(retryInfo === null || retryInfo === void 0 ? void 0 : retryInfo.retryDelay);
+    return delay === null ? null : toMs(delay);
+};
+/**
+ * The wait (ms) a response asks for, or null when it states none. Covers Retry-After (seconds or
+ * date), X-RateLimit-Reset-After, RateLimit-Reset, X-RateLimit-Remaining: 0 + X-RateLimit-Reset,
+ * and waits written in the body (Discord `retry_after`, Google `RetryInfo.retryDelay`).
+ */
+const statedWaitMs = (headers, body, now = Date.now()) => {
+    var _a;
+    const header = (name) => { var _a; return (_a = headers === null || headers === void 0 ? void 0 : headers.get(name)) !== null && _a !== void 0 ? _a : null; };
+    const candidates = [
+        parseRetryAfter(header('retry-after'), now),
+        parseSeconds(header('x-ratelimit-reset-after')) === null ? null : toMs(parseSeconds(header('x-ratelimit-reset-after'))),
+        parseSeconds(header('ratelimit-reset')) === null ? null : toMs(parseSeconds(header('ratelimit-reset'))),
+        ((_a = header('x-ratelimit-remaining')) === null || _a === void 0 ? void 0 : _a.trim()) === '0' ? parseReset(header('x-ratelimit-reset'), now) : null,
+        bodyWaitMs(body)
+    ].filter((ms) => ms !== null);
+    return candidates.length > 0 ? Math.max(...candidates) : null;
+};
+exports.statedWaitMs = statedWaitMs;
+/** Record that `key` must not be called for `waitMs` (only ever extends an existing block). */
+const recordRateLimit = (key, waitMs, now = Date.now()) => {
+    var _a;
+    const until = now + waitMs;
+    if (until > ((_a = blockedUntilByKey.get(key)) !== null && _a !== void 0 ? _a : 0))
+        blockedUntilByKey.set(key, until);
+};
+exports.recordRateLimit = recordRateLimit;
+const rateLimitWaitRemainingMs = (key, now = Date.now()) => { var _a; return Math.max(0, ((_a = blockedUntilByKey.get(key)) !== null && _a !== void 0 ? _a : 0) - now); };
+exports.rateLimitWaitRemainingMs = rateLimitWaitRemainingMs;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** Wait out a recorded limit before calling `key`; throw (returning the wait) when it exceeds `maxWaitMs`. */
+const waitForRateLimit = async (key, maxWaitMs) => {
+    const remaining = (0, exports.rateLimitWaitRemainingMs)(key);
+    if (remaining === 0)
+        return;
+    if (remaining > maxWaitMs)
+        throw new RateLimitedError(key, remaining);
+    await sleep(remaining);
+};
+exports.waitForRateLimit = waitForRateLimit;
+/** Test seam: forget every recorded limit. */
+const resetRateLimits = () => blockedUntilByKey.clear();
+exports.resetRateLimits = resetRateLimits;

package/cronLock/cqlCronLock.d.ts

@@ -0,0 +1,49 @@
+export interface CronLockTopology {
+    network: string;
+    nodeCode: string;
+    mintNodes: string[];
+    localDataCenter: string;
+    contactPoints: string[];
+}
+export interface CqlExecutor {
+    execute(query: string, params?: unknown[], options?: Record<string, unknown>): Promise<{
+        rows: unknown[];
+    }>;
+}
+export type AcquireResult = {
+    status: 'acquired';
+    token: string;
+} | {
+    status: 'held';
+} | {
+    status: 'peerUnavailable';
+    token: string;
+    message: string;
+} | {
+    status: 'unavailable';
+    message: string;
+};
+/** A missing or incoherent topology is unsafe: never infer a one-node cluster. */
+export declare const resolveTopology: (env?: NodeJS.ProcessEnv) => CronLockTopology;
+/**
+ * Lease (TTL) of a held lock: how long a crashed holder blocks the next run. Callers pass the lease
+ * their job needs (it must exceed the job's maximum run time); the default honors
+ * STALE_EXECUTING_CRON_LOCK_MS, else 30 minutes.
+ */
+export declare const leaseMs: (override?: number) => number;
+export declare const parseOffline: (raw: string | undefined | null) => string[];
+type Mode = 'serial' | 'localSerial' | 'standDown';
+export declare const resolveMode: (offline: string[], topology: CronLockTopology) => Mode;
+/** Only an UNAVAILABLE response proves that no SERIAL proposal was accepted. */
+export declare const isPeerUnavailableError: (error: unknown) => boolean;
+/**
+ * The directly testable LWT operation. Each invocation owns a unique token, so
+ * concurrent ticks on one node cannot both treat the node identity as ownership.
+ */
+export declare const acquireWithExecutor: (executor: CqlExecutor, name: string, offline: string | null | undefined, topology: CronLockTopology, token?: string, lease?: number) => Promise<AcquireResult>;
+export declare const acquire: (name: string, offline?: string | null, options?: {
+    leaseMs?: number;
+}) => Promise<AcquireResult>;
+/** Release only the exact acquisition token owned by this invocation. */
+export declare const release: (name: string, token: string, offline?: string | null) => Promise<void>;
+export {};

package/cronLock/cqlCronLock.js

@@ -0,0 +1,199 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.release = exports.acquire = exports.acquireWithExecutor = exports.isPeerUnavailableError = exports.resolveMode = exports.parseOffline = exports.leaseMs = exports.resolveTopology = void 0;
+/**
+ * Cross-datacenter cron mutex for the self-hosted, multi-DC Scylla topology.
+ * (Moved from minting.handle.me src/helpers/cronLock/cqlCronLock.ts @ 6ecb9c3 so every box cron
+ * — minting.handle.me, hal-minting-engine — shares one implementation.)
+ *
+ * Minting runs active/active across boxes, each in its own Scylla datacenter with
+ * RF=1 per DC. Alternator conditional writes use LOCAL_SERIAL, so each DC can win
+ * independently. CQL SERIAL is the cross-DC mutex.
+ *
+ * Operators declare unavailable boxes through the offline set:
+ *  - all boxes online: SERIAL / QUORUM;
+ *  - this box offline: stand down;
+ *  - this box is the only declared-online box: LOCAL_SERIAL / LOCAL_QUORUM;
+ *  - an undeclared peer outage: the caller normally fails closed. StateData may
+ *    use its DC-local fallback only for mintPaidSessions and only after a definite
+ *    CQL UNAVAILABLE response (never after a timeout or unknown failure).
+ *
+ * The row TTL recovers crashed holders. Unique per-invocation owner tokens prevent
+ * overlapping ticks on one box from mistaking node identity for lock ownership.
+ */
+const node_crypto_1 = require("node:crypto");
+const cassandra_driver_1 = require("cassandra-driver");
+const logger_1 = require("../logger");
+const KEYSPACE = 'kora_locks';
+const LOCK_TABLE = 'cron_lock';
+const DEFAULT_LEASE_MS = 30 * 60 * 1000;
+const required = (env, name) => {
+    var _a;
+    const value = (_a = env[name]) === null || _a === void 0 ? void 0 : _a.trim();
+    if (!value)
+        throw new Error(`${name} is required for cron-lock topology`);
+    return value;
+};
+const parseList = (value) => [...new Set(value.split(',').map((item) => item.trim().toLowerCase()).filter(Boolean))];
+/** A missing or incoherent topology is unsafe: never infer a one-node cluster. */
+const resolveTopology = (env = process.env) => {
+    const network = required(env, 'NETWORK').toLowerCase();
+    const nodeCode = required(env, 'KORA_NODE_CODE').toLowerCase();
+    const mintNodes = parseList(required(env, 'KORA_MINT_NODES'));
+    const localDataCenter = required(env, 'KORA_SCYLLA_DC');
+    const contactPoints = parseList(required(env, 'KORA_CQL_CONTACT_POINTS'));
+    if (!mintNodes.includes(nodeCode)) {
+        throw new Error(`KORA_NODE_CODE '${nodeCode}' is not present in KORA_MINT_NODES`);
+    }
+    if (contactPoints.length === 0) {
+        throw new Error('KORA_CQL_CONTACT_POINTS must contain at least one contact point');
+    }
+    return { network, nodeCode, mintNodes, localDataCenter, contactPoints };
+};
+exports.resolveTopology = resolveTopology;
+/**
+ * Lease (TTL) of a held lock: how long a crashed holder blocks the next run. Callers pass the lease
+ * their job needs (it must exceed the job's maximum run time); the default honors
+ * STALE_EXECUTING_CRON_LOCK_MS, else 30 minutes.
+ */
+const leaseMs = (override) => {
+    if (override !== undefined) {
+        if (!Number.isFinite(override) || override <= 0)
+            throw new Error(`Invalid cron-lock lease ${override}`);
+        return override;
+    }
+    const parsed = Number(process.env.STALE_EXECUTING_CRON_LOCK_MS);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_LEASE_MS;
+};
+exports.leaseMs = leaseMs;
+const leaseSeconds = (override) => Math.ceil((0, exports.leaseMs)(override) / 1000);
+const scopeName = (name, topology) => `${topology.network}:${name}`;
+let client = null;
+let clientTopologyKey = '';
+let ensured = false;
+const getClient = (topology) => {
+    const topologyKey = JSON.stringify([topology.contactPoints, topology.localDataCenter]);
+    if (!client || clientTopologyKey !== topologyKey) {
+        client = new cassandra_driver_1.Client({
+            contactPoints: topology.contactPoints,
+            localDataCenter: topology.localDataCenter,
+            socketOptions: { connectTimeout: 8000, readTimeout: 12000 }
+        });
+        clientTopologyKey = topologyKey;
+        ensured = false;
+    }
+    return client;
+};
+const ensureSchema = async (executor) => {
+    if (ensured)
+        return;
+    await executor.execute(`CREATE KEYSPACE IF NOT EXISTS ${KEYSPACE} WITH replication = ` +
+        `{'class':'NetworkTopologyStrategy','kora-dc1':1,'kora-dc2':1}`);
+    await executor.execute(`CREATE TABLE IF NOT EXISTS ${KEYSPACE}.${LOCK_TABLE} (name text PRIMARY KEY, owner text, acquired_at timestamp)`);
+    ensured = true;
+};
+const parseOffline = (raw) => {
+    const value = (raw !== null && raw !== void 0 ? raw : '').trim().toLowerCase();
+    if (!value || value === 'none')
+        return [];
+    return parseList(value);
+};
+exports.parseOffline = parseOffline;
+const resolveMode = (offline, topology) => {
+    const unknownNodes = offline.filter((node) => !topology.mintNodes.includes(node));
+    if (unknownNodes.length > 0) {
+        throw new Error(`Offline set contains unknown mint node(s): ${unknownNodes.join(',')}`);
+    }
+    if (offline.includes(topology.nodeCode))
+        return 'standDown';
+    const online = topology.mintNodes.filter((node) => !offline.includes(node));
+    return online.length === 1 ? 'localSerial' : 'serial';
+};
+exports.resolveMode = resolveMode;
+const createToken = (topology) => `${topology.nodeCode}:${(0, node_crypto_1.randomUUID)()}`;
+/** Only an UNAVAILABLE response proves that no SERIAL proposal was accepted. */
+const isPeerUnavailableError = (error) => error instanceof cassandra_driver_1.errors.ResponseError && error.code === cassandra_driver_1.types.responseErrorCodes.unavailableException;
+exports.isPeerUnavailableError = isPeerUnavailableError;
+/**
+ * The directly testable LWT operation. Each invocation owns a unique token, so
+ * concurrent ticks on one node cannot both treat the node identity as ownership.
+ */
+const acquireWithExecutor = async (executor, name, offline, topology, token = createToken(topology), lease) => {
+    const mode = (0, exports.resolveMode)((0, exports.parseOffline)(offline), topology);
+    if (mode === 'standDown')
+        return { status: 'held' };
+    const serialConsistency = mode === 'localSerial' ? cassandra_driver_1.types.consistencies.localSerial : cassandra_driver_1.types.consistencies.serial;
+    const consistency = mode === 'localSerial' ? cassandra_driver_1.types.consistencies.localQuorum : cassandra_driver_1.types.consistencies.quorum;
+    const key = scopeName(name, topology);
+    try {
+        const result = await executor.execute(`INSERT INTO ${KEYSPACE}.${LOCK_TABLE} (name, owner, acquired_at) VALUES (?, ?, ?) IF NOT EXISTS USING TTL ${leaseSeconds(lease)}`, [key, token, new Date()], { prepare: true, serialConsistency, consistency });
+        const row = result.rows[0];
+        if ((row === null || row === void 0 ? void 0 : row['[applied]']) === true)
+            return { status: 'acquired', token };
+        if ((row === null || row === void 0 ? void 0 : row.owner) !== token)
+            return { status: 'held' };
+        const refresh = await executor.execute(`UPDATE ${KEYSPACE}.${LOCK_TABLE} USING TTL ${leaseSeconds(lease)} SET owner = ?, acquired_at = ? WHERE name = ? IF owner = ?`, [token, new Date(), key, token], { prepare: true, serialConsistency, consistency });
+        const refreshRow = refresh.rows[0];
+        return (refreshRow === null || refreshRow === void 0 ? void 0 : refreshRow['[applied]']) === true ? { status: 'acquired', token } : { status: 'held' };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (mode === 'serial' && (0, exports.isPeerUnavailableError)(error)) {
+            return { status: 'peerUnavailable', token, message };
+        }
+        return { status: 'unavailable', message };
+    }
+};
+exports.acquireWithExecutor = acquireWithExecutor;
+const acquire = async (name, offline, options = {}) => {
+    try {
+        const topology = (0, exports.resolveTopology)();
+        const executor = getClient(topology);
+        await ensureSchema(executor);
+        const result = await (0, exports.acquireWithExecutor)(executor, name, offline, topology, undefined, options.leaseMs);
+        if (result.status === 'peerUnavailable') {
+            logger_1.Logger.log({
+                message: `cron lock '${name}' SERIAL unavailable because the configured peer quorum is unavailable: ${result.message}`,
+                event: 'cqlCronLock.acquire.peerUnavailable',
+                category: logger_1.LogCategory.WARN
+            });
+        }
+        else if (result.status === 'unavailable') {
+            logger_1.Logger.log({
+                message: `cron lock '${name}' failed without a positively identified peer-unavailable response: ${result.message}`,
+                event: 'cqlCronLock.acquire.unavailable',
+                category: logger_1.LogCategory.WARN
+            });
+        }
+        return result;
+    }
+    catch (error) {
+        logger_1.Logger.log({
+            message: `cron lock '${name}' is unavailable: ${error.message}`,
+            event: 'cqlCronLock.acquire.unavailable',
+            category: logger_1.LogCategory.WARN
+        });
+        return { status: 'unavailable', message: error.message };
+    }
+};
+exports.acquire = acquire;
+/** Release only the exact acquisition token owned by this invocation. */
+const release = async (name, token, offline) => {
+    try {
+        const topology = (0, exports.resolveTopology)();
+        const mode = (0, exports.resolveMode)((0, exports.parseOffline)(offline), topology);
+        if (mode === 'standDown')
+            return;
+        const serialConsistency = mode === 'localSerial' ? cassandra_driver_1.types.consistencies.localSerial : cassandra_driver_1.types.consistencies.serial;
+        const consistency = mode === 'localSerial' ? cassandra_driver_1.types.consistencies.localQuorum : cassandra_driver_1.types.consistencies.quorum;
+        await getClient(topology).execute(`DELETE FROM ${KEYSPACE}.${LOCK_TABLE} WHERE name = ? IF owner = ?`, [scopeName(name, topology), token], { prepare: true, serialConsistency, consistency });
+    }
+    catch (error) {
+        logger_1.Logger.log({
+            message: `cron lock '${name}' release best-effort failed (TTL will reclaim): ${error.message}`,
+            event: 'cqlCronLock.release.softfail',
+            category: logger_1.LogCategory.INFO
+        });
+    }
+};
+exports.release = release;

package/cronLock/index.d.ts

@@ -0,0 +1 @@
+export * from './cqlCronLock';

package/cronLock/index.js

@@ -0,0 +1,19 @@
+"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/cronLock`. Node-only (cassandra-driver, optional peer
+// dependency). NOT re-exported from the root index.
+__exportStar(require("./cqlCronLock"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@koralabs/kora-labs-common",
-    "version": "6.13.3",
+    "version": "6.14.0",
     "description": "Kora Labs Common Utilities",
     "main": "index.js",
     "types": "index.d.ts",
@@ -40,7 +40,7 @@
         "@aiken-lang/merkle-patricia-forestry": "^1.2.0",
         "@aws-sdk/client-dynamodb": "^3.549.0",
         "@aws-sdk/lib-dynamodb": "^3.549.0",
-        "@cardano-sdk/core": "^0.46.15",
+        "@cardano-sdk/core": "^0.47.0",
         "@cardano-sdk/crypto": "^0.4.7",
         "@emurgo/cardano-message-signing-nodejs": "^1.1.0",
         "@types/jest": "^30.0.0",
@@ -49,6 +49,7 @@
         "@typescript-eslint/eslint-plugin": "^8.67.0",
         "@typescript-eslint/parser": "^8.67.0",
         "bip39": "^3.1.0",
+        "cassandra-driver": "^4.10.0",
         "eslint": "^8.57.1",
         "jest": "^30.4.2",
         "ts-jest": "^29.4.11",
@@ -72,10 +73,11 @@
     },
     "peerDependencies": {
         "@aiken-lang/merkle-patricia-forestry": "^1.2.0",
-        "@cardano-sdk/core": "^0.46.12",
+        "@cardano-sdk/core": "^0.46.12 || ^0.47.0",
         "@cardano-sdk/crypto": "^0.4.5",
+        "@emurgo/cardano-message-signing-nodejs": "^1.1.0",
         "bip39": "^3.1.0",
-        "@emurgo/cardano-message-signing-nodejs": "^1.1.0"
+        "cassandra-driver": "^4.9.0"
     },
     "peerDependenciesMeta": {
         "@aiken-lang/merkle-patricia-forestry": {
@@ -92,6 +94,9 @@
         },
         "@emurgo/cardano-message-signing-nodejs": {
             "optional": true
+        },
+        "cassandra-driver": {
+            "optional": true
         }
     }
 }

package/txBuild/blockfrost.d.ts

@@ -0,0 +1,66 @@
+import { Cardano } from '@cardano-sdk/core';
+import { ProviderRequestOptions } from '../chain/transport/fetchProviderJson';
+import { ExUnits } from './fees';
+import { RedeemerKey, ScriptTxProtocolParameters } from './scriptTx';
+type BlockfrostAmount = {
+    unit: string;
+    quantity: string;
+}[];
+export interface BlockfrostScript {
+    hash: string;
+    language: Cardano.PlutusLanguageVersion | 'native';
+    /** Serialized size (the ledger's reference-script size). */
+    size: number;
+    script?: Cardano.Script;
+}
+export declare class BlockfrostEvaluationError extends Error {
+    readonly failure: unknown;
+    constructor(failure: unknown);
+}
+export declare const valueFromBlockfrost: (amount: BlockfrostAmount) => Cardano.Value;
+/** Additional-UTxO shape Blockfrost's evaluator accepts: Ogmios value `{ ada: { lovelace }, [policy]: { [asset]: qty } }`. */
+export declare const toOgmiosUtxo: ([txIn, txOut]: Cardano.Utxo) => ({
+    txId: any;
+    index: number;
+} | {
+    datumHash?: any;
+    datum?: any;
+    address: Tagged<string, T>;
+    value: Record<string, Record<string, number>>;
+    txId?: undefined;
+    index?: undefined;
+})[];
+export declare class BlockfrostTxClient {
+    private readonly config;
+    private readonly scripts;
+    private readonly host;
+    constructor(config: {
+        network: string;
+        blockfrostApiKey: string;
+        fetcher?: ProviderRequestOptions['fetcher'];
+    });
+    private request;
+    private getOrNull;
+    getProtocolParameters(): Promise<ScriptTxProtocolParameters>;
+    getLatestBlock(): Promise<{
+        slot: number;
+        time: number;
+        hash: string;
+        height: number;
+    }>;
+    /** Slot of a POSIX time (ms), from the tip (1-second slots since Shelley on every network). */
+    slotAt(posixMs: number): Promise<number>;
+    getScript(hash: string): Promise<BlockfrostScript>;
+    private toUtxo;
+    /** Every UTxO at `address` (paginated). */
+    getAddressUtxos(address: string): Promise<Cardano.Utxo[]>;
+    /** UTxOs at `address` holding `unit`. */
+    getAddressAssetUtxos(address: string, unit: string): Promise<Cardano.Utxo[]>;
+    /** The UTxO `txHash#index`; throws `already spent` when it has been consumed. */
+    getUtxo(ref: string): Promise<Cardano.Utxo>;
+    /** Node (Ogmios) evaluation of every redeemer; `additionalUtxos` supplies inputs not yet on chain. */
+    evaluateTx(cbor: string, additionalUtxos?: Cardano.Utxo[]): Promise<Map<RedeemerKey, ExUnits>>;
+    /** Submit a signed tx; returns its hash. */
+    submitTx(cbor: string): Promise<string>;
+}
+export {};

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.js

@@ -149,17 +149,13 @@ class JsonToDatumObject {
             indefiniteArrays: (_b = options === null || options === void 0 ? void 0 : options.indefiniteArrays) !== null && _b !== void 0 ? _b : true,
             defaultToText: options === null || options === void 0 ? void 0 : options.defaultToText
         };
-        if (Array.isArray(this.json)) {
-            for (let i = 0; i < this.json.length; i++) {
-                this.json[i] = new JsonToDatumObject(this.json[i], this.options);
-            }
+        // Wrap children into NEW containers: the caller's JSON must not be modified (re-encoding the
+        // same object used to produce garbage, since its children had been replaced by wrappers).
+        if (Array.isArray(json)) {
+            this.json = json.map((item) => new JsonToDatumObject(item, this.options));
         }
-        else if (typeof this.json === 'object') {
-            if (this.json !== null) {
-                Object.keys(this.json).map((key) => {
-                    this.json[key] = new JsonToDatumObject(this.json[key], this.options);
-                });
-            }
+        else if (typeof json === 'object' && json !== null && !(json instanceof Map)) {
+            this.json = Object.fromEntries(Object.keys(json).map((key) => [key, new JsonToDatumObject(json[key], this.options)]));
         }
     }
 }