@ar.io/sdk 3.24.0 → 4.0.0-alpha.1

package/lib/esm/solana/rpc-circuit-breaker.js

@@ -0,0 +1,258 @@
+/**
+ * Copyright (C) 2022-2024 Permanent Data Solutions, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Circuit-breaker wrapper for Solana RPC transports using
+ * [opossum](https://nodeshift.dev/opossum/).
+ *
+ * When the primary RPC endpoint starts failing (rate-limits, downtime, etc.)
+ * the circuit opens and subsequent calls are routed transparently to a
+ * fallback RPC until the primary recovers.
+ *
+ * Works at the **transport level** — no Proxy magic required. Every RPC
+ * method (`getAccountInfo`, `sendTransaction`, etc.) goes through the same
+ * transport function, so a single circuit breaker covers them all.
+ *
+ * Usage:
+ * ```ts
+ * import { ARIO, createCircuitBreakerRpc } from '@ar.io/sdk';
+ *
+ * const rpc = createCircuitBreakerRpc({
+ *   primaryUrl: 'https://my-premium-rpc.example.com',
+ *   fallbackUrl: 'https://api.mainnet-beta.solana.com',
+ * });
+ *
+ * const ario = ARIO.init({ rpc });
+ * ```
+ */
+import { createDefaultRpcTransport, createSolanaRpcFromTransport, } from '@solana/kit';
+import CircuitBreaker from 'opossum';
+import { Logger } from '../common/logger.js';
+const logger = new Logger({ level: 'error' });
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+const DEFAULT_MAINNET_RPC = 'https://api.mainnet-beta.solana.com';
+const DEFAULT_DEVNET_RPC = 'https://api.devnet.solana.com';
+// ---------------------------------------------------------------------------
+// Adaptive rate gate (token bucket + cooldown)
+// ---------------------------------------------------------------------------
+/** Default ceiling when `maxRequestsPerSecond` is not provided. */
+const DEFAULT_MAX_RPS = 10;
+/** Multiply the current rate by this on a 429 with no usable header. */
+const AIMD_DECREASE = 0.5;
+/** Never throttle below this many requests/second. */
+const MIN_RATE = 1;
+/** Consecutive successes before nudging the rate up by 1 (additive recovery). */
+const RECOVERY_SUCCESSES = 20;
+/** Fraction of a provider-advertised limit to actually use (safety margin). */
+const RATE_SAFETY_FACTOR = 0.9;
+/** Cooldown applied on a 429 that carries no `Retry-After`. */
+const DEFAULT_COOLDOWN_MS = 1_000;
+/**
+ * Token-bucket throttle whose rate can be retuned at runtime and which can be
+ * paused on demand. Tokens refill continuously at the current rate, capped at
+ * one second's worth (the burst allowance); waiters are released FIFO.
+ */
+function createRateGate(initialRate) {
+    let rate = Math.max(MIN_RATE, initialRate);
+    let capacity = Math.max(1, rate);
+    let tokens = capacity;
+    let lastRefill = Date.now();
+    let pausedUntil = 0;
+    const queue = [];
+    let timer = null;
+    const schedule = (ms) => {
+        if (timer !== null)
+            return;
+        timer = setTimeout(() => {
+            timer = null;
+            pump();
+        }, Math.max(ms, 1));
+    };
+    const refill = () => {
+        const now = Date.now();
+        const elapsed = (now - lastRefill) / 1000;
+        if (elapsed > 0) {
+            tokens = Math.min(capacity, tokens + elapsed * rate);
+            lastRefill = now;
+        }
+    };
+    const pump = () => {
+        const now = Date.now();
+        if (pausedUntil > now) {
+            schedule(pausedUntil - now);
+            return;
+        }
+        refill();
+        while (tokens >= 1) {
+            const release = queue.shift();
+            if (!release)
+                break;
+            tokens -= 1;
+            release();
+        }
+        if (queue.length > 0) {
+            // Wake when the next whole token will have accrued.
+            schedule(Math.ceil(((1 - tokens) / rate) * 1000));
+        }
+    };
+    return {
+        acquire: () => new Promise((resolve) => {
+            queue.push(resolve);
+            pump();
+        }),
+        setRate: (ratePerSecond) => {
+            rate = Math.max(MIN_RATE, ratePerSecond);
+            capacity = Math.max(1, rate);
+            tokens = Math.min(tokens, capacity);
+            lastRefill = Date.now();
+            pump();
+        },
+        pauseFor: (ms) => {
+            const until = Date.now() + Math.max(0, ms);
+            if (until > pausedUntil)
+                pausedUntil = until;
+            schedule(ms);
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// 429 / rate-limit header parsing
+// ---------------------------------------------------------------------------
+/**
+ * If `err` is a transport HTTP 429, return its response `Headers`; else null.
+ * Duck-typed against the `@solana/errors` HTTP-error context
+ * (`{ statusCode, headers }`) so we avoid a hard dependency on the error code.
+ */
+function http429Headers(err) {
+    const ctx = err
+        ?.context;
+    if (ctx?.statusCode === 429 && ctx.headers instanceof Headers) {
+        return ctx.headers;
+    }
+    return null;
+}
+/** Parse `Retry-After` (delta-seconds or HTTP-date) into ms, or null. */
+function parseRetryAfterMs(headers) {
+    const v = headers.get('retry-after');
+    if (v === null || v === '')
+        return null;
+    const secs = Number(v);
+    if (Number.isFinite(secs))
+        return Math.max(0, secs * 1000);
+    const when = Date.parse(v);
+    return Number.isNaN(when) ? null : Math.max(0, when - Date.now());
+}
+/** Provider-advertised requests/second limit (`x-ratelimit-rps-limit`), or null. */
+function parseRpsLimit(headers) {
+    const v = Number(headers.get('x-ratelimit-rps-limit'));
+    return Number.isFinite(v) && v > 0 ? v : null;
+}
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+/**
+ * Create a {@link SolanaRpc} whose transport is backed by an opossum circuit
+ * breaker. Reads and writes flow through the primary transport; when it
+ * becomes unhealthy the circuit opens and subsequent calls are routed to
+ * the fallback transport until the primary recovers.
+ */
+export function createCircuitBreakerRpc({ primaryUrl, fallbackUrl, circuitBreakerOptions: opts = {}, }) {
+    const primaryTransport = createDefaultRpcTransport({ url: primaryUrl });
+    const fallbackTransport = createDefaultRpcTransport({ url: fallbackUrl });
+    // Throttling is always on. `maxRequestsPerSecond` is the *ceiling*: every
+    // request flows through an adaptive token bucket that backs off on HTTP 429
+    // (honoring `Retry-After` and `x-ratelimit-rps-limit` when present, AIMD
+    // otherwise) and recovers back toward the ceiling on sustained success.
+    const ceilingRate = opts.maxRequestsPerSecond !== undefined && opts.maxRequestsPerSecond > 0
+        ? opts.maxRequestsPerSecond
+        : DEFAULT_MAX_RPS;
+    const gate = createRateGate(ceilingRate);
+    let currentRate = ceilingRate;
+    let successStreak = 0;
+    const onError = (err) => {
+        const headers = http429Headers(err);
+        if (!headers)
+            return; // only adapt to rate-limit (429) failures
+        successStreak = 0;
+        const advertised = parseRpsLimit(headers);
+        const next = advertised !== null
+            ? Math.min(ceilingRate, Math.max(MIN_RATE, advertised * RATE_SAFETY_FACTOR))
+            : Math.max(MIN_RATE, currentRate * AIMD_DECREASE);
+        if (next !== currentRate) {
+            currentRate = next;
+            gate.setRate(currentRate);
+        }
+        const retryAfter = parseRetryAfterMs(headers);
+        gate.pauseFor(retryAfter ?? DEFAULT_COOLDOWN_MS);
+        logger.warn(`[rpc-circuit-breaker] 429 — throttling to ${currentRate.toFixed(1)} req/s` +
+            `, cooling down ${retryAfter ?? DEFAULT_COOLDOWN_MS}ms`);
+    };
+    const onSuccess = () => {
+        if (currentRate >= ceilingRate)
+            return;
+        if (++successStreak >= RECOVERY_SUCCESSES) {
+            successStreak = 0;
+            currentRate = Math.min(ceilingRate, currentRate + 1);
+            gate.setRate(currentRate);
+        }
+    };
+    const breaker = new CircuitBreaker((request) => primaryTransport(request), {
+        timeout: opts.timeout ?? 10_000,
+        errorThresholdPercentage: opts.errorThresholdPercentage ?? 25,
+        resetTimeout: opts.resetTimeout ?? 60_000,
+        volumeThreshold: opts.volumeThreshold ?? 3,
+        ...(opts.maxConcurrent !== undefined && opts.maxConcurrent > 0
+            ? { capacity: opts.maxConcurrent }
+            : {}),
+    });
+    breaker.fallback((request) => fallbackTransport(request));
+    breaker.on('open', () => {
+        logger.warn('[rpc-circuit-breaker] circuit OPEN — routing to fallback RPC');
+    });
+    breaker.on('halfOpen', () => {
+        logger.info('[rpc-circuit-breaker] circuit HALF-OPEN — probing primary RPC');
+    });
+    breaker.on('close', () => {
+        logger.info('[rpc-circuit-breaker] circuit CLOSED — primary RPC recovered');
+    });
+    // Adapt the rate to the *primary's* health via opossum's events: `failure`
+    // fires whenever the primary call rejects (a 429 included) even when the
+    // fallback then masks it by resolving `fire()`, and `success` fires on a
+    // healthy primary call. A plain try/catch around `fire()` would miss the
+    // fallback-masked 429s entirely.
+    breaker.on('failure', (err) => onError(err));
+    breaker.on('success', () => onSuccess());
+    const transport = (async (request) => {
+        // Throttle entry to the breaker so we stay under the provider's rate
+        // limit; the queue wait sits outside `fire`, so opossum's per-request
+        // timeout only measures the actual transport call.
+        await gate.acquire();
+        return breaker.fire(request);
+    });
+    return createSolanaRpcFromTransport(transport);
+}
+/**
+ * Convenience: pick a sensible public fallback URL based on the primary URL.
+ *
+ * - Primary contains `devnet` → devnet public RPC
+ * - Everything else → mainnet-beta public RPC
+ */
+export function defaultFallbackUrl(primaryUrl) {
+    if (/devnet/i.test(primaryUrl))
+        return DEFAULT_DEVNET_RPC;
+    return DEFAULT_MAINNET_RPC;
+}

package/lib/esm/solana/send.js

@@ -0,0 +1,372 @@
+/**
+ * Copyright (C) 2022-2024 Permanent Data Solutions, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Shared helpers for building, signing, and sending Solana transactions
+ * with @solana/kit. Used by SolanaARIOWriteable and SolanaANTWriteable.
+ *
+ * Compute budget instruction builders come from `@solana-program/compute-budget`
+ * (kit-flavored Codama client); the previous hand-rolled
+ * `setComputeUnitLimitIx` / `setComputeUnitPriceIx` helpers were removed in
+ * favor of the official package. See `sendAndConfirm` below for why we always
+ * pin BOTH instructions (even with a 0 priority fee).
+ */
+import { ADDRESS_LOOKUP_TABLE_PROGRAM_ADDRESS, getCloseLookupTableInstruction, getCreateLookupTableInstructionAsync, getDeactivateLookupTableInstruction, getExtendLookupTableInstruction, } from '@solana-program/address-lookup-table';
+import { getSetComputeUnitLimitInstruction, getSetComputeUnitPriceInstruction, } from '@solana-program/compute-budget';
+import { appendTransactionMessageInstructions, compileTransaction, compressTransactionMessageUsingAddressLookupTables, createTransactionMessage, getAddressDecoder, getBase64EncodedWireTransaction, getSignatureFromTransaction, pipe, sendAndConfirmTransactionFactory, setTransactionMessageFeePayerSigner, setTransactionMessageLifetimeUsingBlockhash, signTransactionMessageWithSigners, } from '@solana/kit';
+/**
+ * Build, sign, send, and confirm a transaction in one call.
+ *
+ * The caller supplies the core instructions; a compute-unit-limit instruction
+ * is prepended automatically.
+ */
+export async function sendAndConfirm({ rpc, rpcSubscriptions, signer, instructions, commitment = 'confirmed', computeUnitLimit = 400_000, addressLookupTables, }) {
+    const { value: latestBlockhash } = await rpc.getLatestBlockhash().send();
+    const baseMessage = pipe(createTransactionMessage({ version: 0 }), (tx) => setTransactionMessageFeePayerSigner(signer, tx), (tx) => setTransactionMessageLifetimeUsingBlockhash(latestBlockhash, tx), (tx) => appendTransactionMessageInstructions([
+        getSetComputeUnitLimitInstruction({ units: computeUnitLimit }),
+        // Always pin the priority fee (even at 0) so wallets like Phantom
+        // don't silently *append* their own compute-budget instructions
+        // when the transaction is missing either limit or price. That
+        // mutation invalidates signatures already attached by paired
+        // keypair signers (e.g. the ANT mint signer in `spawnSolanaANT`),
+        // producing `Transaction did not pass signature verification` on
+        // the validator. Pre-supplying both keeps the wallet from
+        // rewriting the message, so signatures over the original bytes
+        // still verify.
+        getSetComputeUnitPriceInstruction({ microLamports: 0n }),
+        ...instructions,
+    ], tx));
+    // Compress against any supplied lookup tables (v0). No-op when none given.
+    const message = addressLookupTables
+        ? compressTransactionMessageUsingAddressLookupTables(baseMessage, addressLookupTables)
+        : baseMessage;
+    const signedTx = await signTransactionMessageWithSigners(message);
+    const sendAndConfirmFactory = sendAndConfirmTransactionFactory({
+        rpc,
+        rpcSubscriptions,
+    });
+    // Cast narrows the transaction type to what sendAndConfirmFactory expects —
+    // the kit signer pipeline produces a fully-signed transaction with a blockhash
+    // lifetime, but the factory's argument type doesn't quite line up with the
+    // inferred union. The runtime object is correct.
+    try {
+        await sendAndConfirmFactory(signedTx, { commitment });
+    }
+    catch (err) {
+        logSolanaErrorContext(err);
+        await logSimulationDiagnostics(rpc, message, err);
+        throw err;
+    }
+    return getSignatureFromTransaction(signedTx);
+}
+/**
+ * Walk the chain of `cause`s on a thrown `SolanaError` and log each one's
+ * `.context` (kit packs the server-provided `err`, `logs`, `unitsConsumed`,
+ * etc. there). This usually contains the program logs we want without having
+ * to re-simulate.
+ */
+function logSolanaErrorContext(err) {
+    let current = err;
+    let depth = 0;
+    while (current && depth < 10) {
+        const e = current;
+        const ctx = e?.context;
+        if (ctx && typeof ctx === 'object') {
+            // eslint-disable-next-line no-console
+            console.warn(`[solana-send] error[${depth}] ${e.name ?? 'Error'}: ${e.message ?? ''}`, { context: ctx });
+            const logs = ctx.logs;
+            if (Array.isArray(logs) && logs.length > 0) {
+                // eslint-disable-next-line no-console
+                console.warn(`[solana-send] error[${depth}] program logs:\n` + logs.join('\n'));
+            }
+        }
+        current = e?.cause;
+        depth += 1;
+    }
+}
+/**
+ * On send/confirm failure, re-simulate the transaction with sig-verify off so
+ * we can surface program logs + the failed instruction index. Kit's default
+ * `SolanaError` only carries the bare `Custom program error: #N (instruction
+ * #M)` summary; we also log the full simulation result and the wire-format
+ * transaction so the underlying `msg!` lines and account list can be inspected
+ * in the browser console.
+ *
+ * Best-effort and side-effect free aside from console output.
+ */
+async function logSimulationDiagnostics(rpc, message, originalError) {
+    try {
+        const compiled = compileTransaction(message);
+        const wire = getBase64EncodedWireTransaction(compiled);
+        // eslint-disable-next-line no-console
+        console.warn('[solana-send] sendAndConfirm failed; re-running simulateTransaction for diagnostics', { error: originalError });
+        const sim = await rpc
+            .simulateTransaction(wire, {
+            sigVerify: false,
+            replaceRecentBlockhash: true,
+            encoding: 'base64',
+        })
+            .send();
+        // eslint-disable-next-line no-console
+        console.warn('[solana-send] simulateTransaction result:', sim.value);
+        if (sim.value.err) {
+            // eslint-disable-next-line no-console
+            console.warn('[solana-send] simulation err:', sim.value.err);
+        }
+        if (sim.value.logs) {
+            // eslint-disable-next-line no-console
+            console.warn('[solana-send] program logs:\n' + sim.value.logs.join('\n'));
+        }
+    }
+    catch (diagErr) {
+        // eslint-disable-next-line no-console
+        console.warn('[solana-send] failed to collect diagnostics', diagErr);
+    }
+}
+/**
+ * Submit `instruction` in a v0 transaction whose `lookupAddresses` (read-only
+ * accounts) are served from a freshly-created, ephemeral Address Lookup Table,
+ * so an instruction touching far more accounts than fit inline (e.g.
+ * `prescribe_epoch` with ≤50 observer PDAs + NameRegistry, ~2 KB of keys) still
+ * fits Solana's 1232-byte transaction-size limit.
+ *
+ * Three confirmed steps: create the table, extend it with the addresses (in
+ * ≤20-address batches to stay within the extend tx size), then send
+ * `instruction` compressed against the table. The sequential confirmations
+ * satisfy the rule that appended addresses are only usable the slot AFTER they
+ * are added. `signer` is the table's authority + payer; the table's (tiny) rent
+ * is left allocated — a future cleanup pass can deactivate + close it.
+ */
+export async function sendWithEphemeralLookupTable({ rpc, rpcSubscriptions, signer, instruction, lookupAddresses, commitment = 'confirmed', computeUnitLimit = 1_000_000, }) {
+    const recentSlot = await rpc.getSlot({ commitment: 'finalized' }).send();
+    const createIx = await getCreateLookupTableInstructionAsync({
+        authority: signer.address,
+        payer: signer,
+        recentSlot,
+    });
+    const tableAddress = createIx.accounts[0].address;
+    // Create the (empty) table.
+    await sendAndConfirm({
+        rpc,
+        rpcSubscriptions,
+        signer,
+        instructions: [createIx],
+        commitment,
+        computeUnitLimit: 60_000,
+    });
+    // Fill it, ≤20 addresses per extend tx.
+    const BATCH = 20;
+    for (let i = 0; i < lookupAddresses.length; i += BATCH) {
+        const extendIx = getExtendLookupTableInstruction({
+            address: tableAddress,
+            authority: signer,
+            payer: signer,
+            addresses: lookupAddresses.slice(i, i + BATCH),
+        });
+        await sendAndConfirm({
+            rpc,
+            rpcSubscriptions,
+            signer,
+            instructions: [extendIx],
+            commitment,
+            computeUnitLimit: 60_000,
+        });
+    }
+    // Wait until the table holds every address AND one slot has elapsed since —
+    // addresses appended to a lookup table are only usable the slot AFTER they're
+    // added, and the validator that processes the prescribe must already see
+    // them. Skipping this yields "address table lookup uses an invalid index".
+    await waitForLookupTableActive(rpc, tableAddress, lookupAddresses.length);
+    // Send the real instruction, compressed against the now-active table.
+    return sendAndConfirm({
+        rpc,
+        rpcSubscriptions,
+        signer,
+        instructions: [instruction],
+        commitment,
+        computeUnitLimit,
+        addressLookupTables: { [tableAddress]: lookupAddresses },
+    });
+}
+/**
+ * Poll until an Address Lookup Table holds at least `expectedCount` addresses
+ * AND at least one slot has elapsed since they all landed. Lookup-table entries
+ * are only usable the slot AFTER they are appended, and the leader processing
+ * the consuming tx must already see them — otherwise the runtime rejects the tx
+ * with "address table lookup uses an invalid index". ALT account layout is a
+ * 56-byte metadata header followed by 32-byte addresses.
+ */
+async function waitForLookupTableActive(rpc, table, expectedCount, maxWaitMs = 30_000) {
+    const META = 56;
+    const start = Date.now();
+    let slotAllPresent = null;
+    while (Date.now() - start < maxWaitMs) {
+        const acc = await rpc.getAccountInfo(table, { encoding: 'base64' }).send();
+        const slot = acc.context.slot;
+        if (acc.value) {
+            const len = Buffer.from(acc.value.data[0], 'base64').length;
+            const count = len >= META ? Math.floor((len - META) / 32) : 0;
+            if (count >= expectedCount) {
+                if (slotAllPresent === null) {
+                    slotAllPresent = slot;
+                }
+                else if (slot > slotAllPresent) {
+                    return; // all addresses present + a slot has elapsed → warm
+                }
+            }
+        }
+        await new Promise((r) => setTimeout(r, 800));
+    }
+    throw new Error(`lookup table ${table} not active (≥${expectedCount} addresses + 1 slot) within ${maxWaitMs}ms`);
+}
+/**
+ * Reclaim rent from the ephemeral Address Lookup Tables `signer` created for
+ * prescribe (see {@link sendWithEphemeralLookupTable}). Each prescribe leaves a
+ * single-use table allocated (~0.0126 SOL of rent); reclaiming needs a
+ * deactivate → ~513-slot cooldown → close sequence, so it can't run inline — a
+ * throttled permissionless cleanup pass (cranker / observer) calls this.
+ *
+ * Discovery is RPC-portable. `getProgramAccounts` on the Address Lookup Table
+ * program is rejected by Agave RPCs (`Invalid param: WrongSize`, on public
+ * devnet/mainnet-beta and dedicated providers alike — the ALT program can't be
+ * enumerated), so instead we read the signer's own transaction history
+ * (`getSignaturesForAddress` + `getTransaction`) and collect the tables it
+ * referenced via `message.addressTableLookups` — a prescribe ALT is used in
+ * exactly one transaction.
+ *
+ * Safety fingerprint: a candidate is only touched when EVERY one of its entries
+ * is owned by a program in `allowedEntryOwners` (the GAR + ArNS programs — i.e.
+ * observer Gateway PDAs + the ArNS NameRegistry). That composition uniquely
+ * identifies a prescribe ephemeral, so the pass never deactivates/closes an
+ * unrelated table even if `signer` is also used to author Address Lookup Tables
+ * for other purposes.
+ *
+ * DEACTIVATES still-active matches (starts the cooldown) and CLOSES deactivated
+ * matches past the cooldown (refunding rent to `signer`). At most `maxTables`
+ * submissions per call; scans at most `scanLimit` recent signatures. Best-effort:
+ * per-table failures are skipped and retried on the next pass.
+ */
+export async function reclaimLookupTablesForSigner({ rpc, rpcSubscriptions, signer, allowedEntryOwners, commitment = 'confirmed', maxTables = 10, scanLimit = 500, }) {
+    const ALT_META = 56; // metadata header before the 32-byte address array
+    const ACTIVE = 0xffffffffffffffffn; // u64::MAX = not yet deactivated
+    const COOLDOWN_SLOTS = 513n; // deactivation_slot must age out of SlotHashes
+    const allowed = new Set(allowedEntryOwners);
+    const addressDecoder = getAddressDecoder();
+    // getTransaction only honours 'confirmed' | 'finalized'.
+    const historyCommitment = commitment === 'finalized' ? 'finalized' : 'confirmed';
+    // --- Discover candidate tables from the signer's transaction history -------
+    const sigs = await rpc
+        .getSignaturesForAddress(signer.address, { limit: scanLimit })
+        .send();
+    const candidates = new Set();
+    for (const { signature } of sigs) {
+        // A little headroom over maxTables so already-closed candidates don't
+        // starve the budget; the rest get picked up next pass.
+        if (candidates.size >= maxTables * 3)
+            break;
+        const tx = await rpc
+            .getTransaction(signature, {
+            encoding: 'json',
+            maxSupportedTransactionVersion: 0,
+            commitment: historyCommitment,
+        })
+            .send();
+        const lookups = tx?.transaction?.message?.addressTableLookups ?? [];
+        for (const l of lookups)
+            candidates.add(l.accountKey);
+    }
+    // --- Reclaim ----------------------------------------------------------------
+    const currentSlot = await rpc.getSlot().send();
+    let deactivated = 0;
+    let closed = 0;
+    for (const table of candidates) {
+        if (deactivated + closed >= maxTables)
+            break;
+        const address = table;
+        try {
+            const info = await rpc
+                .getAccountInfo(address, { encoding: 'base64' })
+                .send();
+            const value = info.value;
+            if (!value)
+                continue; // already closed
+            if (value.owner !==
+                ADDRESS_LOOKUP_TABLE_PROGRAM_ADDRESS) {
+                continue;
+            }
+            const data = Buffer.from(value.data[0], 'base64');
+            if (data.length < ALT_META)
+                continue;
+            const deactivationSlot = data.readBigUInt64LE(4);
+            // Fingerprint: every entry must be owned by an allowed program. A prescribe
+            // ALT is exclusively observer Gateway PDAs (GAR) + the NameRegistry (ArNS).
+            const entries = [];
+            for (let off = ALT_META; off + 32 <= data.length; off += 32) {
+                entries.push(addressDecoder.decode(data.subarray(off, off + 32)));
+            }
+            if (entries.length === 0)
+                continue;
+            const owners = await rpc
+                .getMultipleAccounts(entries, {
+                encoding: 'base64',
+                dataSlice: { offset: 0, length: 0 },
+            })
+                .send();
+            const allOwned = owners.value.every((a) => a != null && allowed.has(a.owner));
+            if (!allOwned)
+                continue; // not a prescribe ephemeral — leave it alone
+            if (deactivationSlot === ACTIVE) {
+                await sendAndConfirm({
+                    rpc,
+                    rpcSubscriptions,
+                    signer,
+                    commitment,
+                    computeUnitLimit: 30_000,
+                    instructions: [
+                        getDeactivateLookupTableInstruction({ address, authority: signer }),
+                    ],
+                });
+                deactivated += 1;
+            }
+            else if (currentSlot > deactivationSlot + COOLDOWN_SLOTS) {
+                await sendAndConfirm({
+                    rpc,
+                    rpcSubscriptions,
+                    signer,
+                    commitment,
+                    computeUnitLimit: 30_000,
+                    instructions: [
+                        getCloseLookupTableInstruction({
+                            address,
+                            authority: signer,
+                            recipient: signer.address,
+                        }),
+                    ],
+                });
+                closed += 1;
+            }
+        }
+        catch {
+            // best-effort: a racing close / not-yet-cooled table just gets retried
+            // on the next cleanup pass.
+        }
+    }
+    return {
+        deactivated,
+        closed,
+        candidates: candidates.size,
+        scannedSignatures: sigs.length,
+    };
+}