@aztec/aztec-node 5.0.0-private.20260319 → 5.0.0-rc.2

package/src/modules/block_parameter.ts

@@ -0,0 +1,93 @@
+import type { BlockNumber, CheckpointNumber, SlotNumber } from '@aztec/foundation/branded-types';
+import { BadRequestError } from '@aztec/foundation/json-rpc';
+import {
+  BlockHash,
+  type BlockParameter,
+  BlockTag,
+  type L2BlockSource,
+  type NormalizedBlockParameter,
+} from '@aztec/stdlib/block';
+import type { CheckpointParameter, CheckpointTag } from '@aztec/stdlib/interfaces/client';
+
+/** True when `value` is a {@link BlockTag}. */
+export function isBlockTag(value: string): value is BlockTag {
+  return BlockTag.includes(value as BlockTag);
+}
+
+/** True when `value` is a {@link CheckpointTag}. */
+export function isCheckpointTag(value: unknown): value is CheckpointTag {
+  return value === 'checkpointed' || value === 'proven' || value === 'finalized';
+}
+
+/**
+ * Normalizes a {@link BlockParameter} (which may be a bare value) into a {@link NormalizedBlockParameter}
+ * object form. Performs no chain-tip resolution — tag lookups are deferred to the underlying block source.
+ */
+export function normalizeBlockParameter(param: BlockParameter): NormalizedBlockParameter {
+  if (BlockHash.isBlockHash(param)) {
+    return { hash: param };
+  }
+  if (typeof param === 'number') {
+    return { number: param as BlockNumber };
+  }
+  if (typeof param === 'string') {
+    if (isBlockTag(param)) {
+      return { tag: param === 'latest' ? 'proposed' : param };
+    }
+    throw new BadRequestError(`Invalid BlockParameter tag: ${param}`);
+  }
+  if (typeof param === 'object' && param !== null) {
+    if ('number' in param) {
+      return { number: param.number };
+    }
+    if ('hash' in param) {
+      return { hash: param.hash };
+    }
+    if ('archive' in param) {
+      return { archive: param.archive };
+    }
+    if ('tag' in param) {
+      if (isBlockTag(param.tag)) {
+        return { tag: param.tag };
+      }
+      throw new BadRequestError(`Invalid BlockParameter tag: ${param.tag}`);
+    }
+  }
+  throw new BadRequestError(`Invalid BlockParameter: ${JSON.stringify(param)}`);
+}
+
+/**
+ * Resolves a {@link CheckpointParameter} into a concrete `{ number }` or `{ slot }` query.
+ *
+ * Tag-based parameters (`'checkpointed'`, `'proven'`, `'finalized'`) are translated up-front to the
+ * corresponding tip's checkpoint number via {@link L2BlockSource.getL2Tips}. After resolution the unified
+ * `getCheckpoint` flow can perform a single confirmed→proposed lookup against either store.
+ */
+export async function resolveCheckpointParameter(
+  param: CheckpointParameter,
+  blockSource: L2BlockSource,
+): Promise<{ number: CheckpointNumber } | { slot: SlotNumber }> {
+  if (typeof param === 'number') {
+    return { number: param as CheckpointNumber };
+  }
+  if (isCheckpointTag(param)) {
+    const tips = await blockSource.getL2Tips();
+    switch (param) {
+      case 'checkpointed':
+        return { number: tips.checkpointed.checkpoint.number };
+      case 'proven':
+        return { number: tips.proven.checkpoint.number };
+      case 'finalized':
+        return { number: tips.finalized.checkpoint.number };
+    }
+  }
+  if (typeof param === 'object' && param !== null) {
+    if ('number' in param) {
+      return { number: param.number };
+    }
+    if ('slot' in param) {
+      return { slot: param.slot };
+    }
+  }
+  throw new BadRequestError(`Invalid CheckpointParameter: ${JSON.stringify(param)}`);
+}

package/src/modules/node_block_provider.ts

@@ -0,0 +1,149 @@
+import type { BlockNumber, CheckpointNumber } from '@aztec/foundation/branded-types';
+import { BadRequestError } from '@aztec/foundation/json-rpc';
+import type { BlockData, BlockParameter, CommitteeAttestation, L2BlockSource } from '@aztec/stdlib/block';
+import type { CheckpointData, L1PublishedData, PublishedCheckpoint } from '@aztec/stdlib/checkpoint';
+import type {
+  BlockIncludeOptions,
+  BlockResponse,
+  BlocksIncludeOptions,
+  CheckpointIncludeOptions,
+  CheckpointParameter,
+  CheckpointResponse,
+} from '@aztec/stdlib/interfaces/client';
+
+import {
+  blockResponseFromBlockData,
+  blockResponseFromL2Block,
+  checkpointResponseFromCheckpointData,
+  checkpointResponseFromPublishedCheckpoint,
+  projectProposedToCheckpointResponse,
+} from '../aztec-node/block_response_helpers.js';
+import { normalizeBlockParameter, resolveCheckpointParameter } from './block_parameter.js';
+
+/**
+ * Serves the node's block and checkpoint read queries, assembling RPC responses (optionally including
+ * transactions, L1 publish info, and attestations) from the underlying block source. Extracted from
+ * `AztecNodeService` to keep `server.ts` smaller.
+ */
+export class NodeBlockProvider {
+  constructor(private readonly blockSource: L2BlockSource) {}
+
+  public async getBlock<Opts extends BlockIncludeOptions = {}>(
+    param: BlockParameter,
+    options: Opts = {} as Opts,
+  ): Promise<BlockResponse<Opts> | undefined> {
+    const query = normalizeBlockParameter(param);
+    const wantTxs = !!options.includeTransactions;
+    const wantContext = !!options.includeL1PublishInfo || !!options.includeAttestations;
+
+    if (wantTxs) {
+      const block = await this.blockSource.getBlock(query);
+      if (!block) {
+        return undefined;
+      }
+      const ctx = wantContext ? await this.#getCheckpointContext(block.checkpointNumber) : undefined;
+      return (await blockResponseFromL2Block(block, options, ctx)) as BlockResponse<Opts>;
+    }
+    const data = await this.blockSource.getBlockData(query);
+    if (!data) {
+      return undefined;
+    }
+    const ctx = wantContext ? await this.#getCheckpointContext(data.checkpointNumber) : undefined;
+    return blockResponseFromBlockData(data, options, ctx) as BlockResponse<Opts>;
+  }
+
+  public getBlockData(param: BlockParameter): Promise<BlockData | undefined> {
+    const query = normalizeBlockParameter(param);
+    return this.blockSource.getBlockData(query);
+  }
+
+  public async getBlocks<Opts extends BlocksIncludeOptions = {}>(
+    from: BlockNumber,
+    limit: number,
+    options: Opts = {} as Opts,
+  ): Promise<BlockResponse<Opts>[]> {
+    const wantTxs = !!options.includeTransactions;
+    const wantContext = !!options.includeL1PublishInfo || !!options.includeAttestations;
+    const onlyCheckpointed = !!options.onlyCheckpointed;
+    if (wantTxs) {
+      const blocks = await this.blockSource.getBlocks({ from, limit, onlyCheckpointed });
+      const ctxByCheckpoint = await this.#getCheckpointContextsForBlocks(wantContext ? blocks : []);
+      return (await Promise.all(
+        blocks.map(block => blockResponseFromL2Block(block, options, ctxByCheckpoint.get(block.checkpointNumber))),
+      )) as BlockResponse<Opts>[];
+    }
+    const dataItems = await this.blockSource.getBlocksData({ from, limit, onlyCheckpointed });
+    const ctxByCheckpoint = await this.#getCheckpointContextsForBlocks(wantContext ? dataItems : []);
+    return (await Promise.all(
+      dataItems.map(data => blockResponseFromBlockData(data, options, ctxByCheckpoint.get(data.checkpointNumber))),
+    )) as BlockResponse<Opts>[];
+  }
+
+  public async getCheckpoint<Opts extends CheckpointIncludeOptions = {}>(
+    param: CheckpointParameter,
+    options: Opts = {} as Opts,
+  ): Promise<CheckpointResponse<Opts> | undefined> {
+    const query = await resolveCheckpointParameter(param, this.blockSource);
+
+    // Try the confirmed store first.
+    const confirmed = options.includeBlocks
+      ? await this.blockSource.getCheckpoint(query)
+      : await this.blockSource.getCheckpointData(query);
+    if (confirmed) {
+      return (await (options.includeBlocks
+        ? checkpointResponseFromPublishedCheckpoint(confirmed as PublishedCheckpoint, options)
+        : checkpointResponseFromCheckpointData(confirmed as CheckpointData, options))) as CheckpointResponse<Opts>;
+    }
+
+    // Fall back to the proposed store.
+    const proposed = await this.blockSource.getProposedCheckpointData(query);
+    if (proposed) {
+      if (options.includeAttestations || options.includeL1PublishInfo) {
+        throw new BadRequestError(
+          `Options includeL1PublishInfo or includeAttestations cannot be satisfied for a proposed checkpoint`,
+        );
+      }
+      const blocks = options.includeBlocks
+        ? await this.blockSource.getBlocks({ from: proposed.startBlock, limit: proposed.blockCount })
+        : undefined;
+      return (await projectProposedToCheckpointResponse(proposed, options, blocks)) as CheckpointResponse<Opts>;
+    }
+
+    return undefined;
+  }
+
+  public async getCheckpoints<Opts extends CheckpointIncludeOptions = {}>(
+    from: CheckpointNumber,
+    limit: number,
+    options: Opts = {} as Opts,
+  ): Promise<CheckpointResponse<Opts>[]> {
+    if (options.includeBlocks) {
+      const checkpoints = await this.blockSource.getCheckpoints({ from, limit });
+      return (await Promise.all(
+        checkpoints.map(cp => checkpointResponseFromPublishedCheckpoint(cp, options)),
+      )) as CheckpointResponse<Opts>[];
+    }
+    const datas = await this.blockSource.getCheckpointsData({ from, limit });
+    return datas.map(d => checkpointResponseFromCheckpointData(d, options)) as CheckpointResponse<Opts>[];
+  }
+
+  /** Fetches checkpoint-level L1 and attestation data for use as block response context. */
+  async #getCheckpointContext(
+    checkpointNumber: CheckpointNumber,
+  ): Promise<{ l1?: L1PublishedData; attestations?: CommitteeAttestation[] } | undefined> {
+    const checkpoint = await this.blockSource.getCheckpointData({ number: checkpointNumber });
+    if (!checkpoint) {
+      return undefined;
+    }
+    return { l1: checkpoint.l1, attestations: checkpoint.attestations };
+  }
+
+  /** Fetches checkpoint context for a set of blocks, deduplicating shared checkpoints. */
+  async #getCheckpointContextsForBlocks(
+    blocks: { checkpointNumber: CheckpointNumber }[],
+  ): Promise<Map<CheckpointNumber, { l1?: L1PublishedData; attestations?: CommitteeAttestation[] } | undefined>> {
+    const unique = Array.from(new Set(blocks.map(b => b.checkpointNumber)));
+    const entries = await Promise.all(unique.map(async n => [n, await this.#getCheckpointContext(n)] as const));
+    return new Map(entries);
+  }
+}

package/src/modules/node_tx_receipt.ts

@@ -0,0 +1,115 @@
+import type { BlockNumber } from '@aztec/foundation/branded-types';
+import type { P2P } from '@aztec/p2p';
+import type { L2BlockSource, L2Tips } from '@aztec/stdlib/block';
+import { getEpochAtSlot } from '@aztec/stdlib/epoch-helpers';
+import type { DebugLogStore } from '@aztec/stdlib/logs';
+import {
+  DroppedTxReceipt,
+  type GetTxReceiptOptions,
+  type IndexedTxEffect,
+  MinedTxReceipt,
+  type MinedTxStatus,
+  PendingTxReceipt,
+  type Tx,
+  type TxHash,
+  type TxReceipt,
+  TxStatus,
+} from '@aztec/stdlib/tx';
+
+/** Dependencies required to build a {@link NodeTxReceiptBuilder}. */
+export interface NodeTxReceiptBuilderDeps {
+  p2pClient: P2P;
+  blockSource: L2BlockSource;
+  debugLogStore: DebugLogStore;
+}
+
+/**
+ * Builds transaction receipts by reconciling the archiver's mined tx effects with the tx pool's view,
+ * deriving the finalization status from the cached L2 tips. Extracted from `AztecNodeService` to keep
+ * `server.ts` smaller.
+ */
+export class NodeTxReceiptBuilder {
+  private readonly p2pClient: P2P;
+  private readonly blockSource: L2BlockSource;
+  private readonly debugLogStore: DebugLogStore;
+
+  constructor(deps: NodeTxReceiptBuilderDeps) {
+    this.p2pClient = deps.p2pClient;
+    this.blockSource = deps.blockSource;
+    this.debugLogStore = deps.debugLogStore;
+  }
+
+  public async getTxReceipt<TGetTxReceiptOptions extends GetTxReceiptOptions = {}>(
+    txHash: TxHash,
+    options?: TGetTxReceiptOptions,
+  ): Promise<TxReceipt<TGetTxReceiptOptions>> {
+    // Check the tx pool status first. If the tx is known to the pool (pending or mined), we'll use that
+    // as a fallback if we don't find a mined tx effect in the archiver.
+    const txPoolStatus = await this.p2pClient.getTxStatus(txHash);
+    const isKnownToPool = txPoolStatus === 'pending' || txPoolStatus === 'mined';
+
+    // Then get the raw tx effect from the archiver, which tracks every tx in a mined block.
+    const indexed = await this.blockSource.getTxEffect(txHash);
+
+    let receipt: TxReceipt;
+    if (indexed) {
+      receipt = await this.#assembleMinedReceipt(indexed, options);
+    } else if (isKnownToPool) {
+      // If the tx is in the pool but not in the archiver, it's pending.
+      // This handles race conditions between archiver and p2p, where the archiver
+      // has pruned the block in which a tx was mined, but p2p has not caught up yet.
+      let tx: Tx | undefined;
+      if (options?.includePendingTx) {
+        // The tx may have left the pool since we checked its status (mined or dropped); in that case we
+        // leave `tx` unset and still return a pending receipt.
+        tx = await this.p2pClient.getTxByHashFromPool(txHash, { includeProof: !!options.includeProof });
+      }
+      receipt = new PendingTxReceipt(txHash, tx);
+    } else {
+      // Otherwise, if we don't know the tx, we consider it dropped.
+      receipt = new DroppedTxReceipt(txHash, 'Tx dropped by P2P node');
+    }
+
+    this.debugLogStore.decorateReceiptWithLogs(txHash.toString(), receipt);
+
+    return receipt;
+  }
+
+  /**
+   * Assembles a {@link MinedTxReceipt} from a raw {@link IndexedTxEffect}, deriving the finalization status from the
+   * cached L2 tips and the epoch from the block's slot number.
+   */
+  async #assembleMinedReceipt(indexed: IndexedTxEffect, options?: GetTxReceiptOptions): Promise<MinedTxReceipt> {
+    const blockNumber = indexed.l2BlockNumber;
+    const [tips, l1Constants] = await Promise.all([this.blockSource.getL2Tips(), this.blockSource.getL1Constants()]);
+
+    const status = this.#deriveMinedStatus(blockNumber, tips);
+    const epochNumber = getEpochAtSlot(indexed.slotNumber, l1Constants);
+
+    return new MinedTxReceipt(
+      indexed.data.txHash,
+      status,
+      MinedTxReceipt.executionResultFromRevertCode(indexed.data.revertCode),
+      indexed.data.transactionFee.toBigInt(),
+      indexed.l2BlockHash,
+      blockNumber,
+      indexed.slotNumber,
+      indexed.txIndexInBlock,
+      epochNumber,
+      options?.includeTxEffect ? indexed.data : undefined,
+      /*debugLogs=*/ undefined,
+    );
+  }
+
+  #deriveMinedStatus(blockNumber: BlockNumber, tips: L2Tips): MinedTxStatus {
+    if (blockNumber <= tips.finalized.block.number) {
+      return TxStatus.FINALIZED;
+    } else if (blockNumber <= tips.proven.block.number) {
+      return TxStatus.PROVEN;
+    } else if (blockNumber <= tips.checkpointed.block.number) {
+      return TxStatus.CHECKPOINTED;
+    } else {
+      return TxStatus.PROPOSED;
+    }
+  }
+}