agentex-creator-sdk 1.0.0

package/dist/packages/providers/src/health.js

@@ -0,0 +1,505 @@
+import { createHash } from 'node:crypto';
+import { setTimeout as delay } from 'node:timers/promises';
+import { z } from 'zod';
+import { canonicalJson } from '../../contracts/src/index.js';
+export const ProviderHealthCategorySchema = z.enum(['provider-stale', 'chain-mismatch', 'snapshot-mismatch', 'provider-unavailable', 'rate-limited', 'timeout', 'history-unavailable', 'invalid-response', 'request-rejected', 'execution-result', 'cancelled']);
+export class ProviderHealthError extends Error {
+    category;
+    constructor(category, message) {
+        super(message);
+        this.category = category;
+        this.name = 'ProviderHealthError';
+    }
+}
+/** The caller's `beforeAttempt` permit refused an attempt. It is never retried or failed over; `original` is the caller's error. */
+export class AttemptRefusedError extends ProviderHealthError {
+    original;
+    constructor(original) {
+        super('cancelled', 'The runtime refused a provider attempt.');
+        this.original = original;
+        this.name = 'AttemptRefusedError';
+    }
+}
+const RETRYABLE = new Set(['provider-stale', 'provider-unavailable', 'rate-limited', 'timeout', 'history-unavailable']);
+function deepFreeze(value) { if (value && typeof value === 'object') {
+    Object.values(value).forEach(deepFreeze);
+    Object.freeze(value);
+} return value; }
+/** Thresholds leave wide margin over each chain's block interval so a merely slow endpoint is not excluded; only a head that stopped advancing is. */
+export const HEAD_FRESHNESS_POLICIES = deepFreeze({
+    ethereum: { family: 'evm', identity: '0x1', headTag: 'latest', maximumHeadAgeSeconds: 180, observedTypicalHeadAge: '12 s slots; a healthy latest block is under about 30 s old', observedAt: '2026-09-15' },
+    base: { family: 'evm', identity: '0x2105', headTag: 'latest', maximumHeadAgeSeconds: 120, observedTypicalHeadAge: '2 s blocks; a healthy latest block is seconds old', observedAt: '2026-09-15' },
+    robinhood: { family: 'evm', identity: '0x1237', headTag: 'latest', maximumHeadAgeSeconds: 300, observedTypicalHeadAge: 'latest was seconds old on the official endpoint (observed 2026-09-14)', observedAt: '2026-09-14' },
+    'robinhood-testnet': { family: 'evm', identity: '0xb626', headTag: 'latest', maximumHeadAgeSeconds: 300, observedTypicalHeadAge: 'latest was seconds old on the official endpoint (observed 2026-09-14)', observedAt: '2026-09-14' },
+    solana: { family: 'solana', identity: '5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d', headTag: 'confirmed', maximumHeadAgeSeconds: 120, observedTypicalHeadAge: 'about 0.4 s slots; a healthy confirmed slot is seconds old', observedAt: '2026-09-15' },
+    'solana-devnet': { family: 'solana', identity: 'EtWTRABZaYq6iMfeYKouRu166VU2xqa1wcaWoxPkrZBG', headTag: 'confirmed', maximumHeadAgeSeconds: 120, observedTypicalHeadAge: 'about 0.4 s slots; a healthy confirmed slot is seconds old', observedAt: '2026-09-15' },
+});
+export const endpointHost = (url) => { try {
+    const parsed = new URL(url);
+    return parsed.host || 'invalid-endpoint';
+}
+catch {
+    return 'invalid-endpoint';
+} };
+export function categorizeProviderError(error, signal) {
+    if (error instanceof ProviderHealthError)
+        return error.category;
+    if (signal?.aborted)
+        return signal.reason?.name === 'TimeoutError' ? 'timeout' : 'cancelled';
+    const parts = [];
+    let current = error;
+    let rejected = false;
+    for (let index = 0; current && typeof current === 'object' && index < 8; index++) {
+        const item = current;
+        if (item.status === 429 || item.code === -32005 || item.category === 'rate-limited')
+            return 'rate-limited';
+        // A contract revert is a definitive answer from a healthy endpoint: never retried, failed over or excluded. Keyed transports
+        // (keyed.ts KeyedProviderError) carry the JSON-RPC code as `rpcCode` and their own classification as `category`.
+        if (item.code === 3 || item.rpcCode === 3 || item.category === 'execution-result')
+            return 'execution-result';
+        if (item.code === -32602 || item.code === -32601)
+            rejected = true;
+        // A response over the run's byte cap is too large for every endpoint (they share the cap): failing over only repeats it. The caller
+        // receives the original error, which research tools read as `limit-exceeded` and answer with a narrower request.
+        if (item.category === 'limit-exceeded')
+            return 'request-rejected';
+        for (const part of [item.name, item.message, item.details])
+            if (typeof part === 'string')
+                parts.push(part);
+        current = item.cause;
+    }
+    const text = parts.join(' ').toLowerCase();
+    if (/responsebodysize|response body.*size limit|exceeds the byte limit/.test(text))
+        return 'request-rejected';
+    if (/429|rate limit|too many requests/.test(text))
+        return 'rate-limited';
+    if (/missing trie|historical state|state.*prun|archive|metadata is not found|header not found|minimum ledger|not available/.test(text))
+        return 'history-unavailable';
+    if (/execution reverted|revert|invalid opcode|out of gas|insufficient funds/.test(text))
+        return 'execution-result';
+    if (/timeout|timed out/.test(text))
+        return 'timeout';
+    // Load-balanced public endpoints answer policy refusals and backend lag with an invalid-params code; another endpoint can serve the same request.
+    if (/request blocked|beyond (the )?current head/.test(text))
+        return 'provider-unavailable';
+    if (rejected)
+        return 'request-rejected';
+    return 'provider-unavailable';
+}
+const METHOD_UNITS = { eth_getLogs: 5, eth_estimateGas: 2, getTransaction: 2, getSignaturesForAddress: 3, simulateTransaction: 5, getMultipleAccounts: 2, getBlock: 5 };
+/** Relative request weight for budgeting. It is not a price: every free public source remains unpriced. */
+export const methodCostUnits = (method) => METHOD_UNITS[method] ?? 1;
+export class ProviderTelemetry {
+    #stats = new Map();
+    #cache = { hits: 0, misses: 0, stores: 0, rejectedPrivate: 0 };
+    #entry(endpoint) {
+        const key = `${endpoint.chain}:${endpoint.id}`;
+        let entry = this.#stats.get(key);
+        if (!entry) {
+            if (this.#stats.size >= 64)
+                throw new ProviderHealthError('invalid-response', 'Telemetry endpoint limit reached.');
+            entry = { id: endpoint.id, chain: endpoint.chain, host: endpoint.host, status: 'unobserved', lastCategory: null, lastObservedAt: null, requests: 0, successes: 0, failures: {}, retries: 0, failovers: 0, identityChecks: 0, crossChecks: 0, crossCheckMismatches: 0, cacheHits: 0, costUnits: 0, latencyTotalMs: 0, latencyMaxMs: 0, lastLatencyMs: null, freshness: null };
+            this.#stats.set(key, entry);
+        }
+        return entry;
+    }
+    attempt(endpoint, event) {
+        const entry = this.#entry(endpoint);
+        const latency = Math.max(0, Math.round(event.latencyMs));
+        entry.requests++;
+        entry.costUnits += methodCostUnits(event.method);
+        entry.latencyTotalMs += latency;
+        entry.latencyMaxMs = Math.max(entry.latencyMaxMs, latency);
+        entry.lastLatencyMs = latency;
+        entry.lastObservedAt = (event.at ?? new Date()).toISOString();
+        if (event.retry)
+            entry.retries++;
+        if (event.purpose === 'identity')
+            entry.identityChecks++;
+        if (event.purpose === 'cross-check')
+            entry.crossChecks++;
+        if (event.outcome === 'success' || event.outcome === 'execution-result') {
+            entry.successes++;
+            if (entry.status !== 'excluded' && entry.status !== 'provider-stale')
+                entry.status = 'healthy';
+        }
+        else {
+            entry.failures[event.outcome] = (entry.failures[event.outcome] ?? 0) + 1;
+            entry.lastCategory = event.outcome;
+            if (entry.status !== 'excluded' && entry.status !== 'provider-stale')
+                entry.status = 'degraded';
+        }
+    }
+    mark(endpoint, status, category) { const entry = this.#entry(endpoint); entry.status = status; if (category)
+        entry.lastCategory = category; }
+    failover(endpoint) { this.#entry(endpoint).failovers++; }
+    crossCheckMismatch(endpoint) { this.#entry(endpoint).crossCheckMismatches++; }
+    cacheHit(endpoint) { this.#cache.hits++; if (endpoint)
+        this.#entry(endpoint).cacheHits++; }
+    cacheMiss() { this.#cache.misses++; }
+    cacheStore() { this.#cache.stores++; }
+    cachePrivateRefusal() { this.#cache.rejectedPrivate++; }
+    freshness(endpoint, observation) {
+        const { stale, ...freshness } = observation;
+        const entry = this.#entry(endpoint);
+        entry.freshness = freshness;
+        if (stale) {
+            entry.status = 'provider-stale';
+            entry.lastCategory = 'provider-stale';
+        }
+        else if (entry.status === 'provider-stale' || entry.status === 'unobserved')
+            entry.status = 'healthy';
+    }
+    snapshot(now = new Date()) {
+        return { schemaVersion: 'agentex.provider-health.v1', generatedAt: now.toISOString(), costStatus: 'unpriced',
+            note: 'Cost units are relative request weights for budgeting, not invoices. Free public endpoints carry no SLA, archive guarantee or rate commitment.',
+            cache: { scope: 'public-chain-data-only', ...this.#cache },
+            endpoints: [...this.#stats.values()].sort((a, b) => `${a.chain}:${a.id}` < `${b.chain}:${b.id}` ? -1 : 1).map((entry) => ({ ...structuredClone(entry), meanLatencyMs: entry.requests ? Math.round(entry.latencyTotalMs / entry.requests) : null })) };
+    }
+    reset() { this.#stats.clear(); Object.assign(this.#cache, { hits: 0, misses: 0, stores: 0, rejectedPrivate: 0 }); }
+}
+/** Process-wide operator telemetry. It holds hosts, counters and freshness only: no request parameters, results or tenant identifiers. */
+export const PROVIDER_TELEMETRY = new ProviderTelemetry();
+const digest = (value) => createHash('sha256').update(canonicalJson(JSON.parse(JSON.stringify(value, (_key, item) => typeof item === 'bigint' ? item.toString() : item)))).digest('hex');
+const numericTag = (tag) => typeof tag === 'string' && /^0x(?:0|[1-9a-fA-F][0-9a-fA-F]{0,15})$/.test(tag) ? BigInt(tag) : null;
+const PRIVATE_EVM_METHODS = new Set(['eth_estimateGas', 'eth_sendRawTransaction', 'eth_sendTransaction', 'eth_sign', 'eth_signTransaction', 'eth_accounts']);
+const PRIVATE_SOLANA_METHODS = new Set(['simulateTransaction', 'sendTransaction', 'requestAirdrop']);
+/** The block number a state request is pinned to, or null for moving tags and unpinned requests. */
+export function referencedBlockNumber(method, params) {
+    if (['eth_getCode', 'eth_getBalance', 'eth_getTransactionCount', 'eth_call', 'eth_estimateGas'].includes(method))
+        return numericTag(params.at(-1));
+    if (method === 'eth_getStorageAt')
+        return numericTag(params[2]);
+    if (method === 'eth_getLogs') {
+        const filter = params[0];
+        return numericTag(filter?.toBlock);
+    }
+    return null;
+}
+/**
+ * Shared cache key for public chain data only. Reads are not final, so a key always binds the exact block hash this transport observed
+ * at the referenced height: a reorg changes the hash and therefore the key. Block headers are never cached (they are the reorg check),
+ * Solana data is never cached (confirmed data can still roll back), and proposed payloads, sender-context calls, moving tags and unpinned
+ * reads are never cacheable, so one tenant's private request cannot be served to another.
+ */
+export function publicCacheKey(context, method, params) {
+    if (context.family !== 'evm' || PRIVATE_EVM_METHODS.has(method) || method === 'eth_getBlockByNumber')
+        return null;
+    if (method === 'eth_call') {
+        const call = params[0];
+        if (params.length !== 2 || !call || typeof call !== 'object' || Object.keys(call).some((key) => !['to', 'data', 'gas'].includes(key)))
+            return null;
+    }
+    else if (method === 'eth_getLogs') {
+        const filter = params[0];
+        if (params.length !== 1 || !filter || numericTag(filter.fromBlock) === null || 'blockHash' in filter)
+            return null;
+    }
+    else if (!['eth_getCode', 'eth_getStorageAt', 'eth_getBalance', 'eth_getTransactionCount'].includes(method))
+        return null;
+    const number = referencedBlockNumber(method, params);
+    const anchor = number === null ? undefined : context.anchors.get(number.toString());
+    return anchor ? `evm:${context.identity}:block:${number}:${anchor.hash}:${digest({ method, params })}` : null;
+}
+export class PublicDataCache {
+    maximumEntries;
+    maximumBytes;
+    maximumEntryBytes;
+    #entries = new Map();
+    #bytes = 0;
+    constructor(maximumEntries = 2000, maximumBytes = 32 * 1024 * 1024, maximumEntryBytes = 262144) {
+        this.maximumEntries = maximumEntries;
+        this.maximumBytes = maximumBytes;
+        this.maximumEntryBytes = maximumEntryBytes;
+    }
+    get(key) { const entry = this.#entries.get(key); if (!entry)
+        return undefined; this.#entries.delete(key); this.#entries.set(key, entry); return structuredClone(entry.value); }
+    set(key, value) {
+        const bytes = Buffer.byteLength(JSON.stringify(value ?? null, (_key, item) => typeof item === 'bigint' ? item.toString() : item));
+        if (bytes > this.maximumEntryBytes)
+            return false;
+        const prior = this.#entries.get(key);
+        if (prior) {
+            this.#bytes -= prior.bytes;
+            this.#entries.delete(key);
+        }
+        this.#entries.set(key, { value: structuredClone(value), bytes });
+        this.#bytes += bytes;
+        while (this.#entries.size > this.maximumEntries || this.#bytes > this.maximumBytes) {
+            const oldest = this.#entries.keys().next().value;
+            this.#bytes -= this.#entries.get(oldest).bytes;
+            this.#entries.delete(oldest);
+        }
+        return true;
+    }
+    get size() { return this.#entries.size; }
+    clear() { this.#entries.clear(); this.#bytes = 0; }
+}
+export const PUBLIC_DATA_CACHE = new PublicDataCache();
+export function createResilientTransport(options) {
+    const registered = HEAD_FRESHNESS_POLICIES[options.chain];
+    if (!registered)
+        throw new ProviderHealthError('invalid-response', `No head freshness policy is registered for ${options.chain}.`);
+    const policy = registered;
+    const endpoints = z.array(z.object({ id: z.string().regex(/^[a-z0-9][a-z0-9-]{0,31}$/), url: z.string() })).min(1).max(4).parse(options.endpoints.map(({ id, url }) => ({ id, url })));
+    if (new Set(endpoints.map((item) => item.id)).size !== endpoints.length)
+        throw new ProviderHealthError('invalid-response', 'Endpoint ids must be unique.');
+    const maximumAttempts = z.number().int().min(1).max(3).parse(options.maximumAttempts ?? (endpoints.length > 1 ? 2 : 1));
+    let retryBudget = z.number().int().min(0).max(16).parse(options.retryBudget ?? (endpoints.length > 1 ? 4 : 0));
+    const telemetry = options.telemetry ?? PROVIDER_TELEMETRY;
+    const now = options.now ?? (() => new Date());
+    const categorize = options.categorize ?? categorizeProviderError;
+    const cache = options.cache === undefined ? PUBLIC_DATA_CACHE : options.cache;
+    const state = options.endpoints.map((endpoint, index) => ({ ...endpoint, index, chain: options.chain, host: endpointHost(endpoint.url), excluded: null, identity: 'unverified', freshnessChecked: false }));
+    const anchors = new Map();
+    let active = 0;
+    const identityMethod = policy.family === 'evm' ? 'eth_chainId' : 'getGenesisHash';
+    const available = (item) => !item.excluded || (item.excluded.until !== null && item.excluded.until <= now().getTime());
+    const exclude = (item, category, cooldownMs) => { item.excluded = { category, until: cooldownMs === null ? null : now().getTime() + cooldownMs }; telemetry.mark(item, category === 'provider-stale' ? 'provider-stale' : 'excluded', category); };
+    const spend = () => { if (retryBudget <= 0)
+        return false; retryBudget--; return true; };
+    const crossChecked = new Set();
+    let attemptCounter = 0;
+    let lastServed = null;
+    const cachedFrom = new Map();
+    async function send(item, method, params, signal, purpose, retry) {
+        let complete;
+        try {
+            complete = await options.beforeAttempt?.({ endpointId: item.id, method, purpose, attempt: ++attemptCounter });
+        }
+        catch (error) {
+            throw new AttemptRefusedError(error);
+        }
+        // A runtime refusal while settling a hidden permit (for example a lost lease) is never retried or failed over.
+        const settle = async (outcome) => { if (!complete)
+            return; try {
+            await complete({ outcome });
+        }
+        catch (error) {
+            throw new AttemptRefusedError(error);
+        } };
+        const started = performance.now();
+        let result;
+        try {
+            result = await item.transport.request(method, params, signal);
+        }
+        catch (error) {
+            const outcome = categorize(error, signal);
+            telemetry.attempt(item, { method, outcome, latencyMs: performance.now() - started, purpose, retry, at: now() });
+            await settle(outcome);
+            throw error;
+        }
+        telemetry.attempt(item, { method, outcome: 'success', latencyMs: performance.now() - started, purpose, retry, at: now() });
+        await settle('success');
+        return result;
+    }
+    const identityOf = (value) => policy.family === 'evm' ? (typeof value === 'string' ? `0x${BigInt(value).toString(16)}` : null) : typeof value === 'string' ? value : null;
+    /** Passive checks on results that pass through anyway: no extra network call. Returns false when the endpoint's head is stale. */
+    function observe(item, method, params, result) {
+        if (method === identityMethod) {
+            const ok = identityOf(result) === policy.identity;
+            item.identity = ok ? 'verified' : 'mismatch';
+            if (!ok)
+                exclude(item, 'chain-mismatch', null);
+            return true;
+        }
+        if (policy.family === 'solana' || method !== 'eth_getBlockByNumber' || !result || typeof result !== 'object')
+            return true;
+        const header = result;
+        const number = numericTag(header.number);
+        if (number === null || typeof header.hash !== 'string' || !/^0x[a-fA-F0-9]{64}$/.test(header.hash))
+            return true;
+        const hash = header.hash.toLowerCase();
+        const prior = anchors.get(number.toString());
+        if (prior && prior.hash !== hash) {
+            telemetry.crossCheckMismatch(item);
+            return true;
+        }
+        if (!prior)
+            anchors.set(number.toString(), { hash, endpoint: item.id });
+        // Only the head a run pins (`latest`) is age-checked: a head that stopped advancing is stale. Nothing compares against finality.
+        if (params[0] === policy.headTag) {
+            const timestamp = numericTag(header.timestamp);
+            const age = timestamp === null ? null : Math.floor(now().getTime() / 1000) - Number(timestamp);
+            const stale = age !== null && age > policy.maximumHeadAgeSeconds;
+            telemetry.freshness(item, { headAgeSeconds: age, thresholdSeconds: policy.maximumHeadAgeSeconds, observedAt: now().toISOString(), stale });
+            if (stale) {
+                exclude(item, 'provider-stale', 60000);
+                anchors.delete(number.toString());
+                return false;
+            }
+        }
+        return true;
+    }
+    return {
+        get retryBudgetRemaining() { return retryBudget; },
+        servedBy: () => lastServed,
+        health: () => state.map((item) => ({ id: item.id, host: item.host, excluded: available(item) ? null : item.excluded.category, identity: item.identity })),
+        async request(method, params, signal) {
+            const key = cache ? publicCacheKey({ chain: options.chain, family: policy.family, identity: policy.identity, anchors }, method, params) : null;
+            if (cache && key) {
+                const hit = cache.get(key);
+                if (hit !== undefined) {
+                    telemetry.cacheHit(state[active] ?? null);
+                    lastServed = cachedFrom.get(key) ?? lastServed;
+                    return hit;
+                }
+                telemetry.cacheMiss();
+            }
+            else if (cache && (PRIVATE_EVM_METHODS.has(method) || PRIVATE_SOLANA_METHODS.has(method)))
+                telemetry.cachePrivateRefusal();
+            let lastError = new ProviderHealthError('provider-unavailable', 'No healthy configured endpoint is available.');
+            let previous = null;
+            for (let attempt = 0; attempt < maximumAttempts; attempt++) {
+                const serving = state.map((_, offset) => state[(active + offset) % state.length]).filter((candidate) => available(candidate) && (candidate.serves?.(method, params) ?? true));
+                // An endpoint that prefers this request (for example the keyed archive provider for a trace or a deep log range) answers it first.
+                const ordered = [...serving.filter((candidate) => candidate.prefers?.(method, params)), ...serving.filter((candidate) => !candidate.prefers?.(method, params))];
+                if (!ordered.length && attempt === 0 && !state.some((candidate) => candidate.serves?.(method, params) ?? true))
+                    throw new ProviderHealthError('request-rejected', `No configured ${options.chain} endpoint serves ${method}.`);
+                const item = ordered.find((candidate) => candidate !== previous) ?? ordered[0];
+                if (!item)
+                    break;
+                if (attempt > 0 && !spend())
+                    break;
+                const failover = previous !== null && item !== previous;
+                try {
+                    if (failover && item.identity === 'unverified' && method !== identityMethod) {
+                        if (!spend())
+                            break;
+                        const identity = await send(item, identityMethod, [], signal, 'identity', true);
+                        if (!observe(item, identityMethod, [], identity) || item.identity !== 'verified') {
+                            lastError = new ProviderHealthError('chain-mismatch', 'A failover endpoint reported a different chain identity.');
+                            previous = item;
+                            continue;
+                        }
+                    }
+                    const pinned = policy.family === 'evm' ? referencedBlockNumber(method, params) : null;
+                    const anchor = pinned === null ? undefined : anchors.get(pinned.toString());
+                    if (anchor && anchor.endpoint !== item.id && !crossChecked.has(`${pinned}:${item.id}`)) {
+                        if (!spend())
+                            break;
+                        const header = await send(item, 'eth_getBlockByNumber', [`0x${pinned.toString(16)}`, false], signal, 'cross-check', true);
+                        if (typeof header?.hash !== 'string' || header.hash.toLowerCase() !== anchor.hash) {
+                            telemetry.crossCheckMismatch(item);
+                            exclude(item, 'snapshot-mismatch', null);
+                            lastError = new ProviderHealthError('snapshot-mismatch', 'The failover endpoint does not share the pinned block hash; its data was not used.');
+                            previous = item;
+                            continue;
+                        }
+                        // One matching header check per endpoint and pinned block is enough; later reads at that block reuse it.
+                        crossChecked.add(`${pinned}:${item.id}`);
+                    }
+                    const result = await send(item, method, params, signal, 'request', attempt > 0);
+                    if (policy.family === 'solana' && method === 'getSlot' && params[0]?.commitment === policy.headTag && !item.freshnessChecked && state.length > 1
+                        && (typeof result === 'bigint' || typeof result === 'number') && spend()) {
+                        // A Solana endpoint whose confirmed head stopped advancing is recognised from that slot's block time and dropped before its data is used.
+                        item.freshnessChecked = true;
+                        const blockTime = await send(item, 'getBlockTime', [result], signal, 'freshness-probe', true);
+                        if (typeof blockTime === 'bigint' || typeof blockTime === 'number') {
+                            const age = Math.floor(now().getTime() / 1000) - Number(blockTime);
+                            const stale = age > policy.maximumHeadAgeSeconds;
+                            telemetry.freshness(item, { headAgeSeconds: age, thresholdSeconds: policy.maximumHeadAgeSeconds, observedAt: now().toISOString(), stale });
+                            if (stale) {
+                                exclude(item, 'provider-stale', 60000);
+                                lastError = new ProviderHealthError('provider-stale', `The ${item.host} confirmed slot is ${age} s old.`);
+                                previous = item;
+                                continue;
+                            }
+                        }
+                    }
+                    if (!observe(item, method, params, result)) {
+                        lastError = new ProviderHealthError('provider-stale', `The ${item.host} latest block exceeds the ${options.chain} head-age threshold.`);
+                        previous = item;
+                        continue;
+                    }
+                    // A preferred endpoint answering its own class of request is routing, not a failover away from the active endpoint.
+                    if (failover && !item.prefers?.(method, params)) {
+                        telemetry.failover(item);
+                        active = item.index;
+                    }
+                    lastServed = { id: item.id, host: item.host };
+                    if (cache && key) {
+                        cache.set(key, result);
+                        cachedFrom.set(key, lastServed);
+                        if (cachedFrom.size > 512)
+                            cachedFrom.delete(cachedFrom.keys().next().value);
+                        telemetry.cacheStore();
+                    }
+                    return result;
+                }
+                catch (error) {
+                    const category = categorize(error, signal);
+                    if (!RETRYABLE.has(category) || signal.aborted)
+                        throw error;
+                    lastError = error;
+                    previous = item;
+                    if (state.filter(available).length > 1 && category !== 'history-unavailable')
+                        exclude(item, category, 15000);
+                    if (options.backoffMs && attempt + 1 < maximumAttempts)
+                        await delay(options.backoffMs * (attempt + 1), undefined, { signal }).catch(() => { throw error; });
+                }
+            }
+            throw lastError;
+        },
+    };
+}
+/** Active three-call head freshness probe for operators and verification scripts: identity, the head and its age. No finality is read. */
+export async function probeFreshness(chain, endpoint, options = {}) {
+    const policy = HEAD_FRESHNESS_POLICIES[chain];
+    if (!policy)
+        throw new ProviderHealthError('invalid-response', `No head freshness policy is registered for ${chain}.`);
+    const now = options.now ?? (() => new Date());
+    const signal = options.signal ?? AbortSignal.timeout(20000);
+    const telemetry = options.telemetry ?? PROVIDER_TELEMETRY;
+    const item = { id: endpoint.id, chain, host: endpointHost(endpoint.url) };
+    const observation = { chain, host: item.host, observedAt: now().toISOString(), status: 'healthy', identity: null, expectedIdentity: policy.identity, tag: policy.headTag, head: null, headAgeSeconds: null, thresholdSeconds: policy.maximumHeadAgeSeconds, requests: 0 };
+    const call = async (method, params) => {
+        observation.requests++;
+        const started = performance.now();
+        try {
+            const result = await endpoint.transport.request(method, params, signal);
+            telemetry.attempt(item, { method, outcome: 'success', latencyMs: performance.now() - started, purpose: 'freshness-probe', at: now() });
+            return result;
+        }
+        catch (error) {
+            telemetry.attempt(item, { method, outcome: categorizeProviderError(error, signal), latencyMs: performance.now() - started, purpose: 'freshness-probe', at: now() });
+            throw error;
+        }
+    };
+    try {
+        const identity = await call(policy.family === 'evm' ? 'eth_chainId' : 'getGenesisHash', []);
+        observation.identity = policy.family === 'evm' && typeof identity === 'string' ? `0x${BigInt(identity).toString(16)}` : String(identity);
+        if (observation.identity !== policy.identity) {
+            observation.status = 'chain-mismatch';
+            telemetry.mark(item, 'excluded', 'chain-mismatch');
+            return observation;
+        }
+        if (policy.family === 'evm') {
+            const block = await call('eth_getBlockByNumber', [policy.headTag, false]);
+            const number = numericTag(block?.number);
+            if (number === null)
+                throw new ProviderHealthError('invalid-response', 'Malformed block header.');
+            const timestamp = numericTag(block?.timestamp);
+            observation.head = { number: number.toString(), hash: typeof block?.hash === 'string' ? block.hash.toLowerCase() : null, timestamp: timestamp?.toString() ?? null };
+            if (timestamp !== null)
+                observation.headAgeSeconds = Math.floor(now().getTime() / 1000) - Number(timestamp);
+        }
+        else {
+            const slot = await call('getSlot', [{ commitment: policy.headTag }]);
+            if (typeof slot !== 'bigint' && typeof slot !== 'number')
+                throw new ProviderHealthError('invalid-response', 'Malformed slot.');
+            const blockTime = await call('getBlockTime', [slot]);
+            observation.head = { number: BigInt(slot).toString(), hash: null, timestamp: typeof blockTime === 'bigint' || typeof blockTime === 'number' ? BigInt(blockTime).toString() : null };
+            if (observation.head.timestamp !== null)
+                observation.headAgeSeconds = Math.floor(now().getTime() / 1000) - Number(observation.head.timestamp);
+        }
+        const stale = observation.headAgeSeconds !== null && observation.headAgeSeconds > policy.maximumHeadAgeSeconds;
+        if (stale)
+            observation.status = 'provider-stale';
+        telemetry.freshness(item, { headAgeSeconds: observation.headAgeSeconds, thresholdSeconds: policy.maximumHeadAgeSeconds, observedAt: observation.observedAt, stale });
+    }
+    catch (error) {
+        observation.status = categorizeProviderError(error, signal);
+    }
+    return observation;
+}

package/dist/packages/providers/src/keyed.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Server-side keyed provider transports (E03). Keys come only from the server environment, are embedded only in the outbound
+ * request URL, and are never returned, logged or placed in errors or evidence: failures carry a category and a fixed message.
+ * Every request reserves provider units against a per-run budget and a process-wide daily cap well inside the free tier, is
+ * spaced to a conservative local request rate, and a 429 gets at most one bounded retry.
+ */
+export type KeyedProviderId = 'alchemy' | 'helius';
+export type KeyedFailure = 'credential-required' | 'unsupported' | 'history-unavailable' | 'budget-exhausted' | 'rate-limited' | 'plan-restricted' | 'provider-unavailable' | 'invalid-response' | 'request-rejected' | 'execution-result' | 'timeout' | 'cancelled' | 'limit-exceeded';
+export declare class KeyedProviderError extends Error {
+    readonly category: KeyedFailure;
+    readonly status: number | null;
+    readonly rpcCode: number | null;
+    constructor(category: KeyedFailure, message: string, status?: number | null, rpcCode?: number | null);
+}
+export interface KeyedProviderPolicy {
+    id: KeyedProviderId;
+    credentialReference: 'ALCHEMY_API_KEY' | 'HELIUS_API_KEY';
+    unit: 'compute-unit' | 'credit';
+    hosts: Readonly<Record<string, string>>;
+    unitCosts: Readonly<Record<string, number>>;
+    defaultUnitCost: number;
+    perRunUnits: number;
+    perDayUnits: number;
+    minimumSpacingMs: Readonly<Record<string, number>>;
+    defaultSpacingMs: number;
+    freeTier: string;
+    terms: string;
+    checkedAt: string;
+    /** How units are billed: Alchemy is on pay-as-you-go (owner-confirmed 26 Sep 2026); Helius stays on its free tier. */ billing: 'pay-as-you-go-units-metered' | 'free-tier-units-not-invoiced';
+}
+/** Free-tier figures and terms were read from provider pricing, CU-cost and legal pages on 2026-09-14. Caps stay far below them. */
+export declare const KEYED_PROVIDER_POLICIES: Readonly<Record<KeyedProviderId, KeyedProviderPolicy>>;
+/** Process-wide usage. It holds counters only: no request parameters, results, tenants or credentials. */
+export declare class KeyedUsageLedger {
+    #private;
+    reserve(policy: KeyedProviderPolicy, units: number, at: Date): void;
+    space(policy: KeyedProviderPolicy, method: string, signal: AbortSignal, now: () => number): Promise<void>;
+    count(provider: KeyedProviderId, event: {
+        units?: number;
+        rateLimited?: boolean;
+        failed?: boolean;
+    }): void;
+    snapshot(at?: Date): {
+        costUsd: null;
+        costStatus: "pay-as-you-go-units-metered" | "free-tier-units-not-invoiced";
+        requests: number;
+        units: number;
+        rateLimited: number;
+        failures: number;
+        provider: KeyedProviderId;
+        unit: "compute-unit" | "credit";
+        dayUnitsUsed: number;
+        dayUnitsCap: number;
+    }[];
+}
+export declare const KEYED_USAGE: KeyedUsageLedger;
+/** Server wiring replaces the process-local default with the database-backed ledger so the daily cap is shared and survives restarts. */
+export declare const setKeyedUsageLedger: (ledger: KeyedUsageLedger) => void;
+export declare const activeKeyedUsage: () => KeyedUsageLedger;
+export declare class RunUnitBudget {
+    #private;
+    readonly maximum: number;
+    constructor(maximum: number);
+    get used(): number;
+    reserve(units: number): void;
+}
+export declare const keyedCredentialAvailable: (provider: KeyedProviderId, env?: Record<string, string | undefined>) => boolean;
+export declare const keyedProviderHost: (provider: KeyedProviderId, chain: string) => string | null;
+/** Removes any configured credential from text before it can reach a log, error or artifact. */
+export declare function redactCredentials(text: string, env?: Record<string, string | undefined>): string;
+export interface KeyedTransportOptions {
+    env?: Record<string, string | undefined>;
+    fetch?: typeof fetch;
+    usage?: KeyedUsageLedger;
+    now?: () => Date;
+    timeoutMs?: number;
+    maximumResponseBytes?: number;
+    /** Mandatory: every keyed transport belongs to one run's unit budget, at most the provider's per-run policy. */
+    runBudget: RunUnitBudget;
+    /** 0 hands a 429 straight to the caller (for example a failover transport); 1, the default, makes one bounded retry. */
+    maximumRetries?: 0 | 1;
+    /** Optional durable permit hook for each network attempt, including a 429 retry. */
+    beforeAttempt?: (operation: {
+        provider: KeyedProviderId;
+        method: string;
+        attempt: number;
+        units: number;
+    }) => void | Promise<void>;
+}
+export interface KeyedTransport {
+    readonly provider: KeyedProviderId;
+    readonly host: string;
+    request(method: string, params: readonly unknown[], signal: AbortSignal): Promise<unknown>;
+    readonly unitsUsed: number;
+}
+export declare function createKeyedTransport(provider: KeyedProviderId, chain: string, options: KeyedTransportOptions): KeyedTransport;