@koralabs/kora-labs-common 6.18.0 → 6.18.2

package/chain/transport/rateLimit.d.ts

@@ -15,7 +15,11 @@ export declare const statedWaitMs: (headers: HeaderReader | undefined, body: unk
 /** 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`. */
+/**
+ * Wait out a recorded limit before calling `key`; throw (returning the wait) when it exceeds `maxWaitMs`.
+ * A timer runs on the monotonic clock while the block is wall-clock ms (Date.now()), so it can fire a
+ * millisecond or more before Date.now() reaches the stated time: re-check and keep waiting until it has.
+ */
 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

@@ -86,14 +86,17 @@ 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`. */
+/**
+ * Wait out a recorded limit before calling `key`; throw (returning the wait) when it exceeds `maxWaitMs`.
+ * A timer runs on the monotonic clock while the block is wall-clock ms (Date.now()), so it can fire a
+ * millisecond or more before Date.now() reaches the stated time: re-check and keep waiting until it has.
+ */
 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);
+    for (let remaining = (0, exports.rateLimitWaitRemainingMs)(key); remaining > 0; remaining = (0, exports.rateLimitWaitRemainingMs)(key)) {
+        if (remaining > maxWaitMs)
+            throw new RateLimitedError(key, remaining);
+        await sleep(remaining);
+    }
 };
 exports.waitForRateLimit = waitForRateLimit;
 /** Test seam: forget every recorded limit. */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@koralabs/kora-labs-common",
-    "version": "6.18.0",
+    "version": "6.18.2",
     "description": "Kora Labs Common Utilities",
     "main": "index.js",
     "types": "index.d.ts",

package/testing/onChain.d.ts

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

package/testing/onChain.js

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