@aztec/archiver 0.0.1-commit.b655e406 → 0.0.1-commit.b9865e97

package/dest/l1/trace_tx.d.ts

@@ -0,0 +1,43 @@
+import type { ViemPublicDebugClient } from '@aztec/ethereum/types';
+import { EthAddress } from '@aztec/foundation/eth-address';
+import type { Logger } from '@aztec/foundation/log';
+import { type ZodFor } from '@aztec/foundation/schemas';
+import type { Hex } from 'viem';
+import { z } from 'zod';
+import type { CallInfo } from './types.js';
+/** Zod schema for a single trace from trace_transaction */
+export declare const traceSchema: z.ZodObject<{
+    action: z.ZodObject<{
+        from: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
+        to: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>>;
+        callType: z.ZodString;
+        gas: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>>;
+        input: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>>;
+        value: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>>;
+    }, z.core.$strip>;
+    result: z.ZodOptional<z.ZodObject<{
+        gasUsed: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>>;
+        output: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>>;
+    }, z.core.$strip>>;
+    error: z.ZodOptional<z.ZodString>;
+    subtraces: z.ZodNumber;
+    traceAddress: z.ZodArray<z.ZodNumber>;
+    type: z.ZodString;
+}, z.core.$strip>;
+/** Type for trace_transaction response */
+type TraceTransaction = z.infer<typeof traceSchema>;
+/** Zod schema for the full trace_transaction response (array of traces) */
+export declare const traceTransactionResponseSchema: ZodFor<TraceTransaction[]>;
+/**
+ * Traces a transaction and extracts all CALL operations to a specific contract and function selector.
+ * Uses the trace_transaction RPC method which returns a flat array of traces.
+ *
+ * @param client - The Viem public debug client
+ * @param txHash - The transaction hash to trace
+ * @param targetAddress - The contract address to filter for
+ * @param functionSelector - The 4-byte function selector to filter for (with or without 0x prefix)
+ * @returns Array of CallInfo objects containing from, gasUsed, input, and value for matching calls
+ */
+export declare function getSuccessfulCallsFromTrace(client: ViemPublicDebugClient, txHash: Hex, targetAddress: EthAddress, functionSelector: string, logger?: Logger): Promise<CallInfo[]>;
+export {};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidHJhY2VfdHguZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9sMS90cmFjZV90eC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssRUFBRSxxQkFBcUIsRUFBRSxNQUFNLHVCQUF1QixDQUFDO0FBQ25FLE9BQU8sRUFBRSxVQUFVLEVBQUUsTUFBTSwrQkFBK0IsQ0FBQztBQUMzRCxPQUFPLEtBQUssRUFBRSxNQUFNLEVBQUUsTUFBTSx1QkFBdUIsQ0FBQztBQUNwRCxPQUFPLEVBQUUsS0FBSyxNQUFNLEVBQVcsTUFBTSwyQkFBMkIsQ0FBQztBQUdqRSxPQUFPLEtBQUssRUFBRSxHQUFHLEVBQUUsTUFBTSxNQUFNLENBQUM7QUFDaEMsT0FBTyxFQUFFLENBQUMsRUFBRSxNQUFNLEtBQUssQ0FBQztBQUV4QixPQUFPLEtBQUssRUFBRSxRQUFRLEVBQUUsTUFBTSxZQUFZLENBQUM7QUFrQjNDLDJEQUEyRDtBQUMzRCxlQUFPLE1BQU0sV0FBVzs7Ozs7Ozs7Ozs7Ozs7Ozs7aUJBT3RCLENBQUM7QUFFSCwwQ0FBMEM7QUFDMUMsS0FBSyxnQkFBZ0IsR0FBRyxDQUFDLENBQUMsS0FBSyxDQUFDLE9BQU8sV0FBVyxDQUFDLENBQUM7QUFFcEQsMkVBQTJFO0FBQzNFLGVBQU8sTUFBTSw4QkFBOEIsRUFBRSxNQUFNLENBQUMsZ0JBQWdCLEVBQUUsQ0FBd0IsQ0FBQztBQUUvRjs7Ozs7Ozs7O0dBU0c7QUFDSCx3QkFBc0IsMkJBQTJCLENBQy9DLE1BQU0sRUFBRSxxQkFBcUIsRUFDN0IsTUFBTSxFQUFFLEdBQUcsRUFDWCxhQUFhLEVBQUUsVUFBVSxFQUN6QixnQkFBZ0IsRUFBRSxNQUFNLEVBQ3hCLE1BQU0sQ0FBQyxFQUFFLE1BQU0sR0FDZCxPQUFPLENBQUMsUUFBUSxFQUFFLENBQUMsQ0FvRXJCIn0=

package/dest/l1/trace_tx.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace_tx.d.ts","sourceRoot":"","sources":["../../src/l1/trace_tx.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AACnE,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAC3D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,KAAK,MAAM,EAAW,MAAM,2BAA2B,CAAC;AAGjE,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,MAAM,CAAC;AAChC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAkB3C,2DAA2D;AAC3D,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;iBAOtB,CAAC;AAEH,0CAA0C;AAC1C,KAAK,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEpD,2EAA2E;AAC3E,eAAO,MAAM,8BAA8B,EAAE,MAAM,CAAC,gBAAgB,EAAE,CAAwB,CAAC;AAE/F;;;;;;;;;GASG;AACH,wBAAsB,2BAA2B,CAC/C,MAAM,EAAE,qBAAqB,EAC7B,MAAM,EAAE,GAAG,EACX,aAAa,EAAE,UAAU,EACzB,gBAAgB,EAAE,MAAM,EACxB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,QAAQ,EAAE,CAAC,CAoErB"}

package/dest/l1/trace_tx.js

@@ -0,0 +1,91 @@
+import { EthAddress } from '@aztec/foundation/eth-address';
+import { schemas } from '@aztec/foundation/schemas';
+import { withHexPrefix } from '@aztec/foundation/string';
+import { z } from 'zod';
+/** Zod schema for trace action from trace_transaction */ const traceActionSchema = z.object({
+    from: schemas.HexStringWith0x,
+    to: schemas.HexStringWith0x.optional(),
+    callType: z.string(),
+    gas: schemas.HexStringWith0x.optional(),
+    input: schemas.HexStringWith0x.optional(),
+    value: schemas.HexStringWith0x.optional()
+});
+/** Zod schema for trace result from trace_transaction */ const traceResultSchema = z.object({
+    gasUsed: schemas.HexStringWith0x.optional(),
+    output: schemas.HexStringWith0x.optional()
+});
+/** Zod schema for a single trace from trace_transaction */ export const traceSchema = z.object({
+    action: traceActionSchema,
+    result: traceResultSchema.optional(),
+    error: z.string().optional(),
+    subtraces: z.number(),
+    traceAddress: z.array(z.number()),
+    type: z.string()
+});
+/** Zod schema for the full trace_transaction response (array of traces) */ export const traceTransactionResponseSchema = z.array(traceSchema);
+/**
+ * Traces a transaction and extracts all CALL operations to a specific contract and function selector.
+ * Uses the trace_transaction RPC method which returns a flat array of traces.
+ *
+ * @param client - The Viem public debug client
+ * @param txHash - The transaction hash to trace
+ * @param targetAddress - The contract address to filter for
+ * @param functionSelector - The 4-byte function selector to filter for (with or without 0x prefix)
+ * @returns Array of CallInfo objects containing from, gasUsed, input, and value for matching calls
+ */ export async function getSuccessfulCallsFromTrace(client, txHash, targetAddress, functionSelector, logger) {
+    // Normalize inputs for comparison
+    const normalizedTarget = targetAddress.toString().toLowerCase();
+    const normalizedSelector = withHexPrefix(functionSelector.toLowerCase());
+    // Call trace_transaction (no options needed)
+    const rawTrace = await client.request({
+        method: 'trace_transaction',
+        params: [
+            txHash
+        ]
+    });
+    if (rawTrace === null || rawTrace === undefined) {
+        throw new Error(`Failed to retrieve trace_transaction for ${txHash}`);
+    }
+    logger?.trace(`Retrieved trace_transaction for ${txHash}`, {
+        trace: rawTrace
+    });
+    // Validate the response with zod
+    const traces = traceTransactionResponseSchema.parse(rawTrace);
+    const results = [];
+    // Build a set of trace addresses that errored - we should skip their descendants
+    // A trace address is the path in the trace tree, represented as an array of indices
+    const erroredTraceAddresses = new Set();
+    for (const trace of traces){
+        if (trace.error) {
+            erroredTraceAddresses.add(JSON.stringify(trace.traceAddress));
+        }
+    }
+    // Helper to check if a trace is a descendant of an errored trace
+    function isDescendantOfError(traceAddress) {
+        // Check all possible ancestor paths
+        for(let i = 1; i < traceAddress.length; i++){
+            const ancestorAddress = traceAddress.slice(0, i);
+            if (erroredTraceAddresses.has(JSON.stringify(ancestorAddress))) {
+                return true;
+            }
+        }
+        return false;
+    }
+    // Process each trace
+    for (const trace of traces){
+        // Skip if this has an error or is a descendant of an errored trace
+        if (trace.error || isDescendantOfError(trace.traceAddress)) {
+            continue;
+        }
+        // Check if this is a CALL type trace to the target address with matching selector and result
+        if (trace.type === 'call' && trace.action.callType.toLowerCase() === 'call' && trace.action.to?.toLowerCase() === normalizedTarget && trace.action.input?.toLowerCase().startsWith(normalizedSelector) && trace.result) {
+            results.push({
+                from: EthAddress.fromString(trace.action.from),
+                gasUsed: trace.result.gasUsed === undefined ? undefined : BigInt(trace.result.gasUsed),
+                input: trace.action.input,
+                value: trace.action.value ? BigInt(trace.action.value) : 0n
+            });
+        }
+    }
+    return results;
+}

package/dest/l1/types.d.ts

@@ -0,0 +1,12 @@
+import { EthAddress } from '@aztec/foundation/eth-address';
+import type { Hex } from 'viem';
+/**
+ * Information about a matching CALL
+ */
+export interface CallInfo {
+    from: EthAddress;
+    gasUsed?: bigint;
+    input: Hex;
+    value: bigint;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidHlwZXMuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9sMS90eXBlcy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsVUFBVSxFQUFFLE1BQU0sK0JBQStCLENBQUM7QUFFM0QsT0FBTyxLQUFLLEVBQUUsR0FBRyxFQUFFLE1BQU0sTUFBTSxDQUFDO0FBRWhDOztHQUVHO0FBQ0gsTUFBTSxXQUFXLFFBQVE7SUFDdkIsSUFBSSxFQUFFLFVBQVUsQ0FBQztJQUNqQixPQUFPLENBQUMsRUFBRSxNQUFNLENBQUM7SUFDakIsS0FBSyxFQUFFLEdBQUcsQ0FBQztJQUNYLEtBQUssRUFBRSxNQUFNLENBQUM7Q0FDZiJ9

package/dest/l1/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/l1/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAE3D,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,MAAM,CAAC;AAEhC;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,UAAU,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,GAAG,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;CACf"}

package/dest/l1/types.js

@@ -0,0 +1,3 @@
+/**
+ * Information about a matching CALL
+ */ export { };

package/dest/l1/validate_historical_logs.d.ts

@@ -0,0 +1,23 @@
+import type { L1ContractAddresses } from '@aztec/ethereum/l1-contract-addresses';
+import type { ViemPublicClient } from '@aztec/ethereum/types';
+import { type LoggerBindings } from '@aztec/foundation/log';
+/** Subset of L1 contract addresses whose historical logs the Aztec node relies on. */
+export type HistoricalLogsContractAddresses = Pick<L1ContractAddresses, 'rollupAddress' | 'inboxAddress' | 'registryAddress' | 'governanceProposerAddress'>;
+/**
+ * Validates that every configured L1 RPC URL returns historical logs for the Rollup contract.
+ *
+ * Some RPC providers prune old logs, which would cause L1 syncing to silently fail. To detect this,
+ * we query for the `OwnershipTransferred` event which every Rollup emits in its constructor (via
+ * Ownable) on the block it was deployed (`l1StartBlock`). The `client` is typically a viem fallback
+ * transport over several user-configured RPC URLs — checking only the first URL would miss a bad
+ * secondary, so we probe each URL independently. The first URL that fails aborts startup, unless
+ * the operator has explicitly opted out.
+ *
+ * @param client - The L1 public client built from the user-configured RPC URLs.
+ * @param addresses - The subset of L1 contract addresses we rely on for historical log retrieval.
+ * @param skipCheck - If true, log warnings instead of throwing.
+ * @param bindings - Optional logger bindings for context.
+ * @throws Error if any URL fails the probe and skipCheck is false.
+ */
+export declare function validateAndLogHistoricalLogsAvailability(client: ViemPublicClient, addresses: HistoricalLogsContractAddresses, skipCheck: boolean, bindings?: LoggerBindings): Promise<void>;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidmFsaWRhdGVfaGlzdG9yaWNhbF9sb2dzLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvbDEvdmFsaWRhdGVfaGlzdG9yaWNhbF9sb2dzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUVBLE9BQU8sS0FBSyxFQUFFLG1CQUFtQixFQUFFLE1BQU0sdUNBQXVDLENBQUM7QUFDakYsT0FBTyxLQUFLLEVBQUUsZ0JBQWdCLEVBQUUsTUFBTSx1QkFBdUIsQ0FBQztBQUM5RCxPQUFPLEVBQWUsS0FBSyxjQUFjLEVBQWdCLE1BQU0sdUJBQXVCLENBQUM7QUFFdkYsc0ZBQXNGO0FBQ3RGLE1BQU0sTUFBTSwrQkFBK0IsR0FBRyxJQUFJLENBQ2hELG1CQUFtQixFQUNuQixlQUFlLEdBQUcsY0FBYyxHQUFHLGlCQUFpQixHQUFHLDJCQUEyQixDQUNuRixDQUFDO0FBS0Y7Ozs7Ozs7Ozs7Ozs7OztHQWVHO0FBQ0gsd0JBQXNCLHdDQUF3QyxDQUM1RCxNQUFNLEVBQUUsZ0JBQWdCLEVBQ3hCLFNBQVMsRUFBRSwrQkFBK0IsRUFDMUMsU0FBUyxFQUFFLE9BQU8sRUFDbEIsUUFBUSxDQUFDLEVBQUUsY0FBYyxHQUN4QixPQUFPLENBQUMsSUFBSSxDQUFDLENBbUNmIn0=

package/dest/l1/validate_historical_logs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate_historical_logs.d.ts","sourceRoot":"","sources":["../../src/l1/validate_historical_logs.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uCAAuC,CAAC;AACjF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAe,KAAK,cAAc,EAAgB,MAAM,uBAAuB,CAAC;AAEvF,sFAAsF;AACtF,MAAM,MAAM,+BAA+B,GAAG,IAAI,CAChD,mBAAmB,EACnB,eAAe,GAAG,cAAc,GAAG,iBAAiB,GAAG,2BAA2B,CACnF,CAAC;AAKF;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,wCAAwC,CAC5D,MAAM,EAAE,gBAAgB,EACxB,SAAS,EAAE,+BAA+B,EAC1C,SAAS,EAAE,OAAO,EAClB,QAAQ,CAAC,EAAE,cAAc,GACxB,OAAO,CAAC,IAAI,CAAC,CAmCf"}

package/dest/l1/validate_historical_logs.js

@@ -0,0 +1,108 @@
+import { getPublicClient, getRpcUrlsFromClient } from '@aztec/ethereum/client';
+import { RollupContract } from '@aztec/ethereum/contracts';
+import { createLogger } from '@aztec/foundation/log';
+/**
+ * Validates that every configured L1 RPC URL returns historical logs for the Rollup contract.
+ *
+ * Some RPC providers prune old logs, which would cause L1 syncing to silently fail. To detect this,
+ * we query for the `OwnershipTransferred` event which every Rollup emits in its constructor (via
+ * Ownable) on the block it was deployed (`l1StartBlock`). The `client` is typically a viem fallback
+ * transport over several user-configured RPC URLs — checking only the first URL would miss a bad
+ * secondary, so we probe each URL independently. The first URL that fails aborts startup, unless
+ * the operator has explicitly opted out.
+ *
+ * @param client - The L1 public client built from the user-configured RPC URLs.
+ * @param addresses - The subset of L1 contract addresses we rely on for historical log retrieval.
+ * @param skipCheck - If true, log warnings instead of throwing.
+ * @param bindings - Optional logger bindings for context.
+ * @throws Error if any URL fails the probe and skipCheck is false.
+ */ export async function validateAndLogHistoricalLogsAvailability(client, addresses, skipCheck, bindings) {
+    const logger = createLogger('archiver:validate_historical_logs', bindings);
+    logger.debug('Validating historical log availability on L1 RPCs');
+    const urls = getRpcUrlsFromClient(client);
+    if (urls.length === 0) {
+        logger.warn('Could not determine L1 RPC URLs from the public client; skipping historical logs check.');
+        return;
+    }
+    const chainId = client.chain?.id;
+    if (chainId === undefined) {
+        logger.warn('Could not determine L1 chain ID from the public client; skipping historical logs check.');
+        return;
+    }
+    for (const url of urls){
+        const probeClient = getPublicClient({
+            l1RpcUrls: [
+                url
+            ],
+            l1ChainId: chainId
+        });
+        const rollup = new RollupContract(probeClient, addresses.rollupAddress.toString());
+        const result = await probeRpcUrl(rollup, probeClient, logger);
+        if (result.ok) {
+            logger.debug(`L1 RPC ${url} returned historical OwnershipTransferred log for the Rollup contract.`);
+            continue;
+        }
+        const errorMessage = buildErrorMessage(url, result, addresses);
+        if (skipCheck) {
+            logger.warn(`${errorMessage}\nContinuing because ARCHIVER_SKIP_HISTORICAL_LOGS_CHECK is true.`);
+            continue;
+        }
+        logger.error(errorMessage);
+        throw new Error(errorMessage);
+    }
+}
+/** Runs the OwnershipTransferred probe against a single RPC and queries its client version. */ async function probeRpcUrl(rollup, client, logger) {
+    let queryError;
+    try {
+        const logs = await rollup.getOwnershipTransferredEventsAtDeploy();
+        if (logs.length > 0) {
+            return {
+                ok: true
+            };
+        }
+    } catch (err) {
+        queryError = err;
+    }
+    const clientVersion = await getClientVersion(client, logger);
+    let reason;
+    if (queryError instanceof Error) {
+        reason = `Query for historical logs failed: ${queryError.message}`;
+    } else if (queryError !== undefined) {
+        reason = 'Query for historical logs failed with a non-Error value.';
+    } else {
+        reason = 'No OwnershipTransferred event was returned by the L1 RPC for the Rollup deploy block.';
+    }
+    return {
+        ok: false,
+        reason,
+        clientVersion
+    };
+}
+/** Builds the operator-facing error message for a failing RPC URL. */ function buildErrorMessage(url, result, addresses) {
+    return [
+        `L1 RPC at ${url} does not return historical logs for the Rollup contract. ${result.reason}`,
+        `This likely means this Ethereum RPC node prunes old logs, which would cause the archiver ` + `to silently miss data during L1 sync.`,
+        result.clientVersion ? `Detected L1 client version for ${url}: ${result.clientVersion}.` : `Could not determine L1 client version for ${url}.`,
+        `The following L1 contract addresses must have their historical logs retained by the RPC node:`,
+        `  - Rollup:             ${addresses.rollupAddress.toString()}`,
+        `  - Inbox:              ${addresses.inboxAddress.toString()}`,
+        `  - Registry:           ${addresses.registryAddress.toString()}`,
+        `  - GovernanceProposer: ${addresses.governanceProposerAddress.toString()}`,
+        isReth(result.clientVersion) ? `To retain logs for these contracts, configure reth with a ` + `prune.segments.receipts_log_filter entry for each address above ` + `so reth does not prune their receipts/logs. See https://reth.rs/run/pruning.html for details.` : `Point this RPC endpoint at a node that retains full log history for the addresses above.`,
+        `Set ARCHIVER_SKIP_HISTORICAL_LOGS_CHECK=true to bypass this check at your own risk.`
+    ].join('\n');
+}
+/** Queries `web3_clientVersion` on the L1 RPC. Returns undefined if the call fails or returns a non-string. */ async function getClientVersion(client, logger) {
+    try {
+        const result = await client.request({
+            method: 'web3_clientVersion'
+        });
+        return typeof result === 'string' ? result : undefined;
+    } catch (err) {
+        logger.debug(`Failed to query web3_clientVersion: ${err instanceof Error ? err.message : err}`);
+        return undefined;
+    }
+}
+/** Heuristic check for reth based on the web3_clientVersion string (reth returns e.g. "reth/v1.0.0-..."). */ function isReth(clientVersion) {
+    return !!clientVersion && /reth/i.test(clientVersion);
+}

package/dest/l1/validate_trace.d.ts

@@ -0,0 +1,32 @@
+import type { ViemPublicDebugClient } from '@aztec/ethereum/types';
+import { type LoggerBindings } from '@aztec/foundation/log';
+/** Result of trace availability checks */
+export interface TraceAvailability {
+    /** Whether debug_traceTransaction works for recent blocks */
+    debugTraceRecent: boolean;
+    /** Whether trace_transaction works for recent blocks */
+    traceTransactionRecent: boolean;
+    /** Whether debug_traceTransaction works for old blocks (512 blocks ago) */
+    debugTraceOld: boolean;
+    /** Whether trace_transaction works for old blocks (512 blocks ago) */
+    traceTransactionOld: boolean;
+}
+/**
+ * Validates the availability of debug/trace methods on the Ethereum client.
+ *
+ * @param client - The Viem public debug client
+ * @param bindings - Optional logger bindings for context
+ * @returns Object indicating which trace methods are available for recent and old blocks
+ */
+export declare function validateTraceAvailability(client: ViemPublicDebugClient, bindings?: LoggerBindings): Promise<TraceAvailability>;
+/**
+ * Validates trace availability and logs appropriate messages based on the results.
+ * Optionally throws an error if no trace methods are available and ethereumAllowNoDebugHosts is false.
+ *
+ * @param client - The Viem public debug client
+ * @param ethereumAllowNoDebugHosts - If false, throws an error when no trace methods are available
+ * @param bindings - Optional logger bindings for context
+ * @throws Error if ethereumAllowNoDebugHosts is false and no trace methods are available
+ */
+export declare function validateAndLogTraceAvailability(client: ViemPublicDebugClient, ethereumAllowNoDebugHosts: boolean, bindings?: LoggerBindings): Promise<void>;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidmFsaWRhdGVfdHJhY2UuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9sMS92YWxpZGF0ZV90cmFjZS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssRUFBRSxxQkFBcUIsRUFBRSxNQUFNLHVCQUF1QixDQUFDO0FBQ25FLE9BQU8sRUFBZSxLQUFLLGNBQWMsRUFBZ0IsTUFBTSx1QkFBdUIsQ0FBQztBQTRDdkYsMENBQTBDO0FBQzFDLE1BQU0sV0FBVyxpQkFBaUI7SUFDaEMsNkRBQTZEO0lBQzdELGdCQUFnQixFQUFFLE9BQU8sQ0FBQztJQUMxQix3REFBd0Q7SUFDeEQsc0JBQXNCLEVBQUUsT0FBTyxDQUFDO0lBQ2hDLDJFQUEyRTtJQUMzRSxhQUFhLEVBQUUsT0FBTyxDQUFDO0lBQ3ZCLHNFQUFzRTtJQUN0RSxtQkFBbUIsRUFBRSxPQUFPLENBQUM7Q0FDOUI7QUFFRDs7Ozs7O0dBTUc7QUFDSCx3QkFBc0IseUJBQXlCLENBQzdDLE1BQU0sRUFBRSxxQkFBcUIsRUFDN0IsUUFBUSxDQUFDLEVBQUUsY0FBYyxHQUN4QixPQUFPLENBQUMsaUJBQWlCLENBQUMsQ0FpRzVCO0FBTUQ7Ozs7Ozs7O0dBUUc7QUFDSCx3QkFBc0IsK0JBQStCLENBQ25ELE1BQU0sRUFBRSxxQkFBcUIsRUFDN0IseUJBQXlCLEVBQUUsT0FBTyxFQUNsQyxRQUFRLENBQUMsRUFBRSxjQUFjLEdBQ3hCLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0E2Q2YifQ==

package/dest/l1/validate_trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate_trace.d.ts","sourceRoot":"","sources":["../../src/l1/validate_trace.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AACnE,OAAO,EAAe,KAAK,cAAc,EAAgB,MAAM,uBAAuB,CAAC;AA4CvF,0CAA0C;AAC1C,MAAM,WAAW,iBAAiB;IAChC,6DAA6D;IAC7D,gBAAgB,EAAE,OAAO,CAAC;IAC1B,wDAAwD;IACxD,sBAAsB,EAAE,OAAO,CAAC;IAChC,2EAA2E;IAC3E,aAAa,EAAE,OAAO,CAAC;IACvB,sEAAsE;IACtE,mBAAmB,EAAE,OAAO,CAAC;CAC9B;AAED;;;;;;GAMG;AACH,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,qBAAqB,EAC7B,QAAQ,CAAC,EAAE,cAAc,GACxB,OAAO,CAAC,iBAAiB,CAAC,CAiG5B;AAMD;;;;;;;;GAQG;AACH,wBAAsB,+BAA+B,CACnD,MAAM,EAAE,qBAAqB,EAC7B,yBAAyB,EAAE,OAAO,EAClC,QAAQ,CAAC,EAAE,cAAc,GACxB,OAAO,CAAC,IAAI,CAAC,CA6Cf"}

package/dest/l1/validate_trace.js

@@ -0,0 +1,154 @@
+import { createLogger } from '@aztec/foundation/log';
+import { callTraceSchema } from './debug_tx.js';
+import { traceTransactionResponseSchema } from './trace_tx.js';
+/**
+ * Helper function to test a trace method with validation
+ *
+ * @param client - The Viem public debug client
+ * @param txHash - Transaction hash to trace
+ * @param schema - Zod schema to validate the response
+ * @param method - Name of the RPC method ('debug_traceTransaction' or 'trace_transaction')
+ * @param blockType - Type of block being tested ('recent' or 'old')
+ * @param logger - Logger instance
+ * @returns true if the method works and validation passes, false otherwise
+ */ async function testTraceMethod(client, txHash, schema, method, blockType, logger) {
+    try {
+        // Make request with appropriate params based on method name
+        const result = await client.request(method === 'debug_traceTransaction' ? {
+            method,
+            params: [
+                txHash,
+                {
+                    tracer: 'callTracer'
+                }
+            ]
+        } : {
+            method,
+            params: [
+                txHash
+            ]
+        });
+        schema.parse(result);
+        logger.debug(`${method} works for ${blockType} blocks`);
+        return true;
+    } catch (error) {
+        logger.warn(`${method} failed for ${blockType} blocks: ${error}`);
+        return false;
+    }
+}
+/**
+ * Validates the availability of debug/trace methods on the Ethereum client.
+ *
+ * @param client - The Viem public debug client
+ * @param bindings - Optional logger bindings for context
+ * @returns Object indicating which trace methods are available for recent and old blocks
+ */ export async function validateTraceAvailability(client, bindings) {
+    const logger = createLogger('archiver:validate_trace', bindings);
+    const result = {
+        debugTraceRecent: false,
+        traceTransactionRecent: false,
+        debugTraceOld: false,
+        traceTransactionOld: false
+    };
+    try {
+        // Get the latest block
+        let latestBlock = await client.getBlock({
+            blockTag: 'latest'
+        });
+        let attempts = 10;
+        // Loop back to find a block with transactions (handles dev/test scenarios)
+        while(!hasTxs(latestBlock) && latestBlock.number && latestBlock.number > 0n && --attempts > 0){
+            logger.debug(`Block ${latestBlock.number} has no transactions, checking previous block`);
+            latestBlock = await client.getBlock({
+                blockNumber: latestBlock.number - 1n
+            });
+        }
+        if (!hasTxs(latestBlock)) {
+            logger.warn('No blocks with transactions found from latest back to genesis, cannot validate trace availability');
+            return result;
+        }
+        // Get a transaction from the found block
+        const recentTxHash = latestBlock.transactions[0];
+        // Test debug_traceTransaction with recent block
+        result.debugTraceRecent = await testTraceMethod(client, recentTxHash, callTraceSchema, 'debug_traceTransaction', 'recent', logger);
+        // Test trace_transaction with recent block
+        result.traceTransactionRecent = await testTraceMethod(client, recentTxHash, traceTransactionResponseSchema, 'trace_transaction', 'recent', logger);
+        // Get a block from 512 blocks ago
+        const oldBlockNumber = latestBlock.number ? latestBlock.number - 512n : null;
+        if (!oldBlockNumber || oldBlockNumber < 0n) {
+            logger.debug('Cannot test old blocks, blockchain too short');
+            return result;
+        }
+        let oldBlock = await client.getBlock({
+            blockNumber: oldBlockNumber
+        });
+        attempts = 10;
+        // Loop back to find a block with transactions (handles dev/test scenarios)
+        while(!hasTxs(oldBlock) && oldBlock.number && oldBlock.number > 0n && --attempts > 0){
+            logger.debug(`Block ${oldBlock.number} has no transactions, checking previous block`);
+            oldBlock = await client.getBlock({
+                blockNumber: oldBlock.number - 1n
+            });
+        }
+        if (!hasTxs(oldBlock)) {
+            logger.debug('No blocks with transactions found from old block back to genesis, cannot validate trace availability for old blocks');
+            return result;
+        }
+        const oldTxHash = oldBlock.transactions[0];
+        // Test debug_traceTransaction with old block
+        result.debugTraceOld = await testTraceMethod(client, oldTxHash, callTraceSchema, 'debug_traceTransaction', 'old', logger);
+        // Test trace_transaction with old block
+        result.traceTransactionOld = await testTraceMethod(client, oldTxHash, traceTransactionResponseSchema, 'trace_transaction', 'old', logger);
+    } catch (error) {
+        logger.warn(`Error validating debug_traceTransaction and trace_transaction availability: ${error}`);
+    }
+    return result;
+}
+function hasTxs(block) {
+    return Array.isArray(block.transactions) && block.transactions.length > 0;
+}
+/**
+ * Validates trace availability and logs appropriate messages based on the results.
+ * Optionally throws an error if no trace methods are available and ethereumAllowNoDebugHosts is false.
+ *
+ * @param client - The Viem public debug client
+ * @param ethereumAllowNoDebugHosts - If false, throws an error when no trace methods are available
+ * @param bindings - Optional logger bindings for context
+ * @throws Error if ethereumAllowNoDebugHosts is false and no trace methods are available
+ */ export async function validateAndLogTraceAvailability(client, ethereumAllowNoDebugHosts, bindings) {
+    const logger = createLogger('archiver:validate_trace', bindings);
+    logger.debug('Validating trace/debug method availability...');
+    const availability = await validateTraceAvailability(client, bindings);
+    // Check if we have support for old blocks (either debug or trace)
+    const hasOldBlockSupport = availability.debugTraceOld || availability.traceTransactionOld;
+    if (hasOldBlockSupport) {
+        // Ideal case: we have trace support for old blocks
+        const methods = [];
+        if (availability.debugTraceOld) {
+            methods.push('debug_traceTransaction');
+        }
+        if (availability.traceTransactionOld) {
+            methods.push('trace_transaction');
+        }
+        logger.info(`Ethereum client supports trace methods for old blocks (${methods.join(', ')}). Archiver can retrieve historical transaction traces.`);
+    } else if (availability.debugTraceRecent || availability.traceTransactionRecent) {
+        // Warning case: only recent block support
+        const methods = [];
+        if (availability.debugTraceRecent) {
+            methods.push('debug_traceTransaction');
+        }
+        if (availability.traceTransactionRecent) {
+            methods.push('trace_transaction');
+        }
+        logger.warn(`Ethereum client only supports trace methods for recent blocks (${methods.join(', ')}). Historical transaction traces may not be available.`);
+    } else {
+        // Error case: no support at all
+        const errorMessage = 'Ethereum debug client does not support debug_traceTransaction or trace_transaction methods. Transaction tracing will not be available. This may impact archiver syncing.';
+        if (ethereumAllowNoDebugHosts) {
+            logger.warn(`${errorMessage} Continuing because ETHEREUM_ALLOW_NO_DEBUG_HOSTS is set to true.`);
+        } else {
+            logger.error(errorMessage);
+            throw new Error(`${errorMessage} Set ETHEREUM_ALLOW_NO_DEBUG_HOSTS=true to bypass this check.`);
+        }
+    }
+}

package/dest/modules/contract_data_source_adapter.d.ts

@@ -0,0 +1,25 @@
+import type { BlockNumber } from '@aztec/foundation/branded-types';
+import type { Fr } from '@aztec/foundation/curves/bn254';
+import type { FunctionSelector } from '@aztec/stdlib/abi';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+import type { ContractClassPublic, ContractDataSource, ContractInstanceWithAddress } from '@aztec/stdlib/contract';
+import type { UInt64 } from '@aztec/stdlib/types';
+import type { ArchiverDataStores } from '../store/data_stores.js';
+/**
+ * Thin {@link ContractDataSource} adapter over {@link ArchiverDataStores}.
+ *
+ * Used by contexts (e.g. offline epoch re-prover tools) that need a ContractDataSource
+ * but do not need a full archiver instance.
+ */
+export declare class ArchiverContractDataSourceAdapter implements ContractDataSource {
+    private readonly stores;
+    constructor(stores: ArchiverDataStores);
+    getBlockNumber(): Promise<BlockNumber>;
+    getContractClass(id: Fr): Promise<ContractClassPublic | undefined>;
+    getBytecodeCommitment(id: Fr): Promise<Fr | undefined>;
+    getContract(address: AztecAddress, maybeTimestamp?: UInt64): Promise<ContractInstanceWithAddress | undefined>;
+    getContractClassIds(): Promise<Fr[]>;
+    getDebugFunctionName(_address: AztecAddress, selector: FunctionSelector): Promise<string | undefined>;
+    registerContractFunctionSignatures(signatures: string[]): Promise<void>;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY29udHJhY3RfZGF0YV9zb3VyY2VfYWRhcHRlci5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL21vZHVsZXMvY29udHJhY3RfZGF0YV9zb3VyY2VfYWRhcHRlci50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssRUFBRSxXQUFXLEVBQUUsTUFBTSxpQ0FBaUMsQ0FBQztBQUNuRSxPQUFPLEtBQUssRUFBRSxFQUFFLEVBQUUsTUFBTSxnQ0FBZ0MsQ0FBQztBQUN6RCxPQUFPLEtBQUssRUFBRSxnQkFBZ0IsRUFBRSxNQUFNLG1CQUFtQixDQUFDO0FBQzFELE9BQU8sS0FBSyxFQUFFLFlBQVksRUFBRSxNQUFNLDZCQUE2QixDQUFDO0FBQ2hFLE9BQU8sS0FBSyxFQUFFLG1CQUFtQixFQUFFLGtCQUFrQixFQUFFLDJCQUEyQixFQUFFLE1BQU0sd0JBQXdCLENBQUM7QUFDbkgsT0FBTyxLQUFLLEVBQUUsTUFBTSxFQUFFLE1BQU0scUJBQXFCLENBQUM7QUFFbEQsT0FBTyxLQUFLLEVBQUUsa0JBQWtCLEVBQUUsTUFBTSx5QkFBeUIsQ0FBQztBQUVsRTs7Ozs7R0FLRztBQUNILHFCQUFhLGlDQUFrQyxZQUFXLGtCQUFrQjtJQUM5RCxPQUFPLENBQUMsUUFBUSxDQUFDLE1BQU07SUFBbkMsWUFBNkIsTUFBTSxFQUFFLGtCQUFrQixFQUFJO0lBRXBELGNBQWMsSUFBSSxPQUFPLENBQUMsV0FBVyxDQUFDLENBRTVDO0lBRU0sZ0JBQWdCLENBQUMsRUFBRSxFQUFFLEVBQUUsR0FBRyxPQUFPLENBQUMsbUJBQW1CLEdBQUcsU0FBUyxDQUFDLENBRXhFO0lBRU0scUJBQXFCLENBQUMsRUFBRSxFQUFFLEVBQUUsR0FBRyxPQUFPLENBQUMsRUFBRSxHQUFHLFNBQVMsQ0FBQyxDQUU1RDtJQUVZLFdBQVcsQ0FDdEIsT0FBTyxFQUFFLFlBQVksRUFDckIsY0FBYyxDQUFDLEVBQUUsTUFBTSxHQUN0QixPQUFPLENBQUMsMkJBQTJCLEdBQUcsU0FBUyxDQUFDLENBUWxEO0lBRU0sbUJBQW1CLElBQUksT0FBTyxDQUFDLEVBQUUsRUFBRSxDQUFDLENBRTFDO0lBRU0sb0JBQW9CLENBQUMsUUFBUSxFQUFFLFlBQVksRUFBRSxRQUFRLEVBQUUsZ0JBQWdCLEdBQUcsT0FBTyxDQUFDLE1BQU0sR0FBRyxTQUFTLENBQUMsQ0FFM0c7SUFFTSxrQ0FBa0MsQ0FBQyxVQUFVLEVBQUUsTUFBTSxFQUFFLEdBQUcsT0FBTyxDQUFDLElBQUksQ0FBQyxDQUU3RTtDQUNGIn0=

package/dest/modules/contract_data_source_adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract_data_source_adapter.d.ts","sourceRoot":"","sources":["../../src/modules/contract_data_source_adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AACnE,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,gCAAgC,CAAC;AACzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,KAAK,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,2BAA2B,EAAE,MAAM,wBAAwB,CAAC;AACnH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAElD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAElE;;;;;GAKG;AACH,qBAAa,iCAAkC,YAAW,kBAAkB;IAC9D,OAAO,CAAC,QAAQ,CAAC,MAAM;IAAnC,YAA6B,MAAM,EAAE,kBAAkB,EAAI;IAEpD,cAAc,IAAI,OAAO,CAAC,WAAW,CAAC,CAE5C;IAEM,gBAAgB,CAAC,EAAE,EAAE,EAAE,GAAG,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC,CAExE;IAEM,qBAAqB,CAAC,EAAE,EAAE,EAAE,GAAG,OAAO,CAAC,EAAE,GAAG,SAAS,CAAC,CAE5D;IAEY,WAAW,CACtB,OAAO,EAAE,YAAY,EACrB,cAAc,CAAC,EAAE,MAAM,GACtB,OAAO,CAAC,2BAA2B,GAAG,SAAS,CAAC,CAQlD;IAEM,mBAAmB,IAAI,OAAO,CAAC,EAAE,EAAE,CAAC,CAE1C;IAEM,oBAAoB,CAAC,QAAQ,EAAE,YAAY,EAAE,QAAQ,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAE3G;IAEM,kCAAkC,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAE7E;CACF"}

package/dest/modules/contract_data_source_adapter.js

@@ -0,0 +1,40 @@
+/**
+ * Thin {@link ContractDataSource} adapter over {@link ArchiverDataStores}.
+ *
+ * Used by contexts (e.g. offline epoch re-prover tools) that need a ContractDataSource
+ * but do not need a full archiver instance.
+ */ export class ArchiverContractDataSourceAdapter {
+    stores;
+    constructor(stores){
+        this.stores = stores;
+    }
+    getBlockNumber() {
+        return this.stores.blocks.getLatestL2BlockNumber();
+    }
+    getContractClass(id) {
+        return this.stores.contractClasses.getContractClass(id);
+    }
+    getBytecodeCommitment(id) {
+        return this.stores.contractClasses.getBytecodeCommitment(id);
+    }
+    async getContract(address, maybeTimestamp) {
+        let timestamp = maybeTimestamp;
+        if (timestamp === undefined) {
+            const latest = await this.stores.blocks.getLatestL2BlockNumber();
+            const blockData = latest > 0 ? await this.stores.blocks.getBlockData({
+                number: latest
+            }) : undefined;
+            timestamp = blockData ? blockData.header.globalVariables.timestamp : 0n;
+        }
+        return this.stores.contractInstances.getContractInstance(address, timestamp);
+    }
+    getContractClassIds() {
+        return this.stores.contractClasses.getContractClassIds();
+    }
+    getDebugFunctionName(_address, selector) {
+        return Promise.resolve(this.stores.functionNames.get(selector));
+    }
+    registerContractFunctionSignatures(signatures) {
+        return this.stores.functionNames.register(signatures);
+    }
+}