@koralabs/kora-labs-common 6.13.4 → 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.4",
+    "version": "6.14.0",
     "description": "Kora Labs Common Utilities",
     "main": "index.js",
     "types": "index.d.ts",
@@ -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",
@@ -74,8 +75,9 @@
         "@aiken-lang/merkle-patricia-forestry": "^1.2.0",
         "@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 {};