@aztec-labs/stdlib 6.0.0-nightly.20260829

package/src/interfaces/l2_logs_source.ts

@@ -0,0 +1,32 @@
+import type { BlockNumber } from '@aztec-labs/foundation/branded-types';
+
+import type { LogResult } from '../logs/log_result.js';
+import type { PrivateLogsQuery, PublicLogsQuery } from '../logs/logs_query.js';
+
+/**
+ * Interface of classes allowing for the retrieval of logs.
+ *
+ * The return type is always the widest {@link LogResult} shape (noteHashes/nullifiers optional). To
+ * narrow at the call site after passing `includeEffects: true`, use the typed wrapper functions in
+ * `pxe/src/tagging/get_all_logs_by_tags.ts` (or cast — the wire payload is the widest shape, so a
+ * stricter generic on this interface would not survive the JSON-RPC boundary anyway).
+ */
+export interface L2LogsSource {
+  /**
+   * Gets private logs matching the given tags. Returns one inner array per element of `query.tags`, in
+   * input order. An empty inner array means no logs matched that tag.
+   */
+  getPrivateLogsByTags(query: PrivateLogsQuery): Promise<LogResult[][]>;
+
+  /**
+   * Gets public logs matching the given tags for the given contract. Returns one inner array per element
+   * of `query.tags`, in input order. An empty inner array means no logs matched that tag.
+   */
+  getPublicLogsByTags(query: PublicLogsQuery): Promise<LogResult[][]>;
+
+  /**
+   * Gets the number of the latest L2 block processed by the implementation.
+   * @returns The number of the latest L2 block processed by the implementation.
+   */
+  getBlockNumber(): Promise<BlockNumber>;
+}

package/src/interfaces/merkle_tree_operations.ts

@@ -0,0 +1,316 @@
+import type { BlockNumber } from '@aztec-labs/foundation/branded-types';
+import type { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { createLogger } from '@aztec-labs/foundation/log';
+import { type IndexedTreeLeafPreimage, SiblingPath } from '@aztec-labs/foundation/trees';
+
+import type { BlockHash } from '../block/block_hash.js';
+import type { MerkleTreeId, TreeHeights } from '../trees/merkle_tree_id.js';
+import type { NullifierLeaf } from '../trees/nullifier_leaf.js';
+import type { PublicDataTreeLeaf } from '../trees/public_data_leaf.js';
+import type { BlockHeader } from '../tx/block_header.js';
+import type { StateReference } from '../tx/state_reference.js';
+import type { WorldStateRevision } from '../world-state/world_state_revision.js';
+
+/**
+ * Type alias for the nullifier tree ID.
+ */
+export type IndexedTreeId = MerkleTreeId.NULLIFIER_TREE | MerkleTreeId.PUBLIC_DATA_TREE;
+
+export type FrTreeId = Exclude<MerkleTreeId, IndexedTreeId>;
+
+/**
+ * Witness data for a leaf update.
+ */
+export interface LeafUpdateWitnessData<N extends number> {
+  /**
+   * Preimage of the leaf before updating.
+   */
+  leafPreimage: IndexedTreeLeafPreimage;
+  /**
+   * Sibling path to prove membership of the leaf.
+   */
+  siblingPath: SiblingPath<N>;
+  /**
+   * The index of the leaf.
+   */
+  index: bigint;
+}
+
+/**
+ * The result of a batch insertion in an indexed merkle tree.
+ */
+export interface BatchInsertionResult<TreeHeight extends number, SubtreeSiblingPathHeight extends number> {
+  /**
+   * Data for the leaves to be updated when inserting the new ones.
+   */
+  lowLeavesWitnessData?: LeafUpdateWitnessData<TreeHeight>[];
+  /**
+   * Sibling path "pointing to" where the new subtree should be inserted into the tree.
+   */
+  newSubtreeSiblingPath: SiblingPath<SubtreeSiblingPathHeight>;
+  /**
+   * The new leaves being inserted in high to low order. This order corresponds with the order of the low leaves witness.
+   */
+  sortedNewLeaves: Buffer[];
+  /**
+   * The indexes of the sorted new leaves to the original ones.
+   */
+  sortedNewLeavesIndexes: number[];
+}
+
+/**
+ * The result of a sequential insertion in an indexed merkle tree.
+ */
+export interface SequentialInsertionResult<TreeHeight extends number> {
+  /**
+   * Data for the leaves to be updated when inserting the new ones.
+   */
+  lowLeavesWitnessData: LeafUpdateWitnessData<TreeHeight>[];
+  /**
+   * Data for the inserted leaves
+   */
+  insertionWitnessData: LeafUpdateWitnessData<TreeHeight>[];
+}
+
+/**
+ *  Defines tree information.
+ */
+export interface TreeInfo {
+  /**
+   * The tree ID.
+   */
+  treeId: MerkleTreeId;
+  /**
+   * The tree root.
+   */
+  root: Buffer;
+  /**
+   * The number of leaves in the tree.
+   */
+  size: bigint;
+
+  /**
+   * The depth of the tree.
+   */
+  depth: number;
+}
+
+type LeafTypes = {
+  [MerkleTreeId.NULLIFIER_TREE]: Buffer;
+  [MerkleTreeId.NOTE_HASH_TREE]: Fr;
+  [MerkleTreeId.PUBLIC_DATA_TREE]: Buffer;
+  [MerkleTreeId.L1_TO_L2_MESSAGE_TREE]: Fr;
+  [MerkleTreeId.ARCHIVE]: BlockHash;
+};
+
+type LeafValueTypes = {
+  [MerkleTreeId.NULLIFIER_TREE]: NullifierLeaf;
+  [MerkleTreeId.NOTE_HASH_TREE]: Fr;
+  [MerkleTreeId.PUBLIC_DATA_TREE]: PublicDataTreeLeaf;
+  [MerkleTreeId.L1_TO_L2_MESSAGE_TREE]: Fr;
+  [MerkleTreeId.ARCHIVE]: BlockHash;
+};
+
+export type MerkleTreeLeafType<ID extends MerkleTreeId> = LeafTypes[ID];
+
+export type MerkleTreeLeafValue<ID extends MerkleTreeId> = LeafValueTypes[ID];
+
+/**
+ * Defines the interface for operations on a set of Merkle Trees.
+ */
+export interface MerkleTreeReadOperations {
+  /**
+   * Returns information about the given tree.
+   * @param treeId - The tree to be queried.
+   */
+  getTreeInfo(treeId: MerkleTreeId): Promise<TreeInfo>;
+
+  /**
+   * Gets the current state reference.
+   */
+  getStateReference(): Promise<StateReference>;
+
+  /**
+   * Gets the initial header.
+   */
+  getInitialHeader(): BlockHeader;
+
+  /**
+   * Gets the current revision.
+   */
+  getRevision(): WorldStateRevision;
+
+  /**
+   * Returns the IPC path of the underlying aztec-wsdb process. External AVM simulators use this to
+   * connect to the same world state instance that the TS layer is using.
+   */
+  getIpcPath(): string;
+
+  /**
+   * Gets sibling path for a leaf.
+   * @param treeId - The tree to be queried for a sibling path.
+   * @param index - The index of the leaf for which a sibling path should be returned.
+   */
+  getSiblingPath<ID extends MerkleTreeId>(treeId: ID, index: bigint): Promise<SiblingPath<TreeHeights[ID]>>;
+
+  /**
+   * Returns the previous index for a given value in an indexed tree.
+   * @param treeId - The tree for which the previous value index is required.
+   * @param value - The value to be queried.
+   */
+  getPreviousValueIndex<ID extends IndexedTreeId>(
+    treeId: ID,
+    value: bigint,
+  ): Promise<
+    | {
+        /** The index of the found leaf.*/
+        index: bigint;
+        /** A flag indicating if the corresponding leaf's value is equal to `newValue`. */
+        alreadyPresent: boolean;
+      }
+    | undefined
+  >;
+
+  /**
+   * Returns the data at a specific leaf.
+   * @param treeId - The tree for which leaf data should be returned.
+   * @param index - The index of the leaf required.
+   */
+  getLeafPreimage<ID extends IndexedTreeId>(treeId: ID, index: bigint): Promise<IndexedTreeLeafPreimage | undefined>;
+
+  /**
+   * Returns the index containing a leaf value.
+   * @param treeId - The tree for which the index should be returned.
+   * @param value - The value to search for in the tree.
+   */
+  findLeafIndices<ID extends MerkleTreeId>(
+    treeId: ID,
+    values: MerkleTreeLeafType<ID>[],
+  ): Promise<(bigint | undefined)[]>;
+
+  /**
+   * Returns the sibling paths for the given leaf values
+   * @param treeId - The tree for which the index should be returned.
+   * @param values - The values to search for in the tree.
+   */
+  findSiblingPaths<ID extends MerkleTreeId>(
+    treeId: ID,
+    values: MerkleTreeLeafType<ID>[],
+  ): Promise<({ path: SiblingPath<TreeHeights[ID]>; index: bigint } | undefined)[]>;
+
+  /**
+   * Returns the first index containing a leaf value after `startIndex`.
+   * @param treeId - The tree for which the index should be returned.
+   * @param value - The value to search for in the tree.
+   * @param startIndex - The index to start searching from (used when skipping nullified messages)
+   */
+  findLeafIndicesAfter<ID extends MerkleTreeId>(
+    treeId: ID,
+    values: MerkleTreeLeafType<ID>[],
+    startIndex: bigint,
+  ): Promise<(bigint | undefined)[]>;
+
+  /**
+   * Gets the value for a leaf in the tree.
+   * @param treeId - The tree for which the index should be returned.
+   * @param index - The index of the leaf.
+   */
+  getLeafValue<ID extends MerkleTreeId>(
+    treeId: ID,
+    index: bigint,
+  ): Promise<MerkleTreeLeafType<typeof treeId> | undefined>;
+
+  /**
+   * Get the block numbers for a set of leaf indices
+   * @param treeId - The tree for which the block numbers should be returned.
+   * @param leafIndices - The indices to be queried.
+   */
+  getBlockNumbersForLeafIndices<ID extends MerkleTreeId>(
+    treeId: ID,
+    leafIndices: bigint[],
+  ): Promise<(BlockNumber | undefined)[]>;
+}
+
+export interface MerkleTreeCheckpointOperations {
+  /** Checkpoints the current fork state. Returns the depth of the new checkpoint. */
+  createCheckpoint(): Promise<number>;
+
+  /** Commits the current checkpoint. */
+  commitCheckpoint(): Promise<void>;
+
+  /** Reverts the current checkpoint. */
+  revertCheckpoint(): Promise<void>;
+
+  /** Commits all checkpoints above the given depth, leaving checkpoint depth at the given value. */
+  commitAllCheckpointsTo(depth: number): Promise<void>;
+
+  /** Reverts all checkpoints above the given depth, leaving checkpoint depth at the given value. */
+  revertAllCheckpointsTo(depth: number): Promise<void>;
+}
+
+export interface MerkleTreeWriteOperations
+  extends MerkleTreeReadOperations,
+    MerkleTreeCheckpointOperations,
+    AsyncDisposable {
+  /**
+   * Appends leaves to a given tree.
+   * @param treeId - The tree to be updated.
+   * @param leaves - The set of leaves to be appended.
+   */
+  appendLeaves<ID extends MerkleTreeId>(treeId: ID, leaves: MerkleTreeLeafType<ID>[]): Promise<void>;
+
+  /**
+   * Inserts the block hash into the archive.
+   * This includes all of the current roots of all of the data trees and the current blocks global vars.
+   * @param header - The header to insert into the archive.
+   */
+  updateArchive(header: BlockHeader): Promise<void>;
+
+  /**
+   * Batch insert multiple leaves into the tree.
+   * @param leaves - Leaves to insert into the tree.
+   * @param treeId - The tree on which to insert.
+   * @param subtreeHeight - Height of the subtree.
+   * @returns The witness data for the leaves to be updated when inserting the new ones.
+   */
+  batchInsert<TreeHeight extends number, SubtreeSiblingPathHeight extends number, ID extends IndexedTreeId>(
+    treeId: ID,
+    leaves: Buffer[],
+    subtreeHeight: number,
+  ): Promise<BatchInsertionResult<TreeHeight, SubtreeSiblingPathHeight>>;
+
+  /**
+   * Inserts multiple leaves into the tree, getting witnesses at every step.
+   * Note: This method doesn't support inserting empty leaves.
+   * @param treeId - The tree on which to insert.
+   * @param leaves - The leaves to insert.
+   * @returns The witnesses for the low leaf updates and the insertions.
+   */
+  sequentialInsert<TreeHeight extends number, ID extends IndexedTreeId>(
+    treeId: ID,
+    leaves: Buffer[],
+  ): Promise<SequentialInsertionResult<TreeHeight>>;
+
+  /**
+   * Closes the database, discarding any uncommitted changes.
+   */
+  close(): Promise<void>;
+}
+
+/**
+ * Outputs a tree leaves using for debugging purposes.
+ */
+export async function inspectTree(
+  db: MerkleTreeReadOperations,
+  treeId: MerkleTreeId,
+  log = createLogger('types:inspect-tree'),
+) {
+  const info = await db.getTreeInfo(treeId);
+  const output = [`Tree id=${treeId} size=${info.size} root=0x${info.root.toString('hex')}`];
+  for (let i = 0; i < info.size; i++) {
+    output.push(
+      ` Leaf ${i}: ${await db.getLeafValue(treeId, BigInt(i)).then(x => x?.toString('hex') ?? '[undefined]')}`,
+    );
+  }
+  log.info(output.join('\n'));
+}

package/src/interfaces/p2p-bootstrap.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+
+import type { ApiSchemaFor } from '../schemas/index.js';
+
+/** Exposed API to the P2P bootstrap node. */
+export interface P2PBootstrapApi {
+  /**
+   * Returns the ENR for this node.
+   */
+  getEncodedEnr(): Promise<string>;
+
+  /**
+   * Returns ENRs for all nodes in the routing table.
+   */
+  getRoutingTable(): Promise<string[]>;
+}
+
+export const P2PBootstrapApiSchema: ApiSchemaFor<P2PBootstrapApi> = {
+  getEncodedEnr: z.function({ input: z.tuple([]), output: z.string() }),
+  getRoutingTable: z.function({ input: z.tuple([]), output: z.array(z.string()) }),
+};

package/src/interfaces/p2p.ts

@@ -0,0 +1,139 @@
+import type { CheckpointProposalHash, SlotNumber } from '@aztec-labs/foundation/branded-types';
+import { bufferSchemaFor } from '@aztec-labs/foundation/schemas';
+import { z } from 'zod';
+
+import { BlockProposal } from '../p2p/block_proposal.js';
+import { CheckpointAttestation } from '../p2p/checkpoint_attestation.js';
+import { CheckpointProposal, type CheckpointProposalCore } from '../p2p/checkpoint_proposal.js';
+import { type ApiSchemaFor, optional, schemas } from '../schemas/index.js';
+import { Tx } from '../tx/tx.js';
+import { TxHash } from '../tx/tx_hash.js';
+import { MAX_RPC_TXS_LEN } from './api_limit.js';
+import { type GetTxByHashOptions, GetTxByHashOptionsSchema } from './get_tx_by_hash_options.js';
+
+export type PeerInfo =
+  | { status: 'connected'; score: number; id: string }
+  | { status: 'dialing'; dialStatus: string; id: string; addresses: string[] }
+  | { status: 'cached'; id: string; addresses: string[]; enr: string; dialAttempts: number };
+
+export const PeerInfoSchema = z.discriminatedUnion('status', [
+  z.object({ status: z.literal('connected'), score: z.number(), id: z.string() }),
+  z.object({ status: z.literal('dialing'), dialStatus: z.string(), id: z.string(), addresses: z.array(z.string()) }),
+  z.object({
+    status: z.literal('cached'),
+    id: z.string(),
+    addresses: z.array(z.string()),
+    enr: z.string(),
+    dialAttempts: z.number(),
+  }),
+]);
+
+/** Connectivity of the p2p stack: whether it is enabled at all, and how many peers are currently connected. */
+export type P2PConnectivity = {
+  /** False when the node runs without a p2p stack (eg sandbox or single-node setups). */
+  enabled: boolean;
+  /** Number of peers currently connected. Always zero when p2p is disabled. */
+  connectedPeers: number;
+};
+
+export const P2PConnectivitySchema = z.object({
+  enabled: z.boolean(),
+  connectedPeers: z.number(),
+});
+
+/** Exposed API to the P2P module. */
+export interface P2PApi {
+  /**
+   * Returns all pending transactions in the transaction pool. The txs' proofs are stripped unless
+   * `includeProof` is set.
+   * @param limit - The number of items to returns
+   * @param after - The last known pending tx. Used for pagination
+   * @param options - Options for the returned txs (eg whether to include their proofs).
+   * @returns An array of Txs.
+   */
+  getPendingTxs(limit?: number, after?: TxHash, options?: GetTxByHashOptions): Promise<Tx[]>;
+
+  /** Returns the number of pending txs in the p2p tx pool. */
+  getPendingTxCount(): Promise<number>;
+
+  /**
+   * Returns the ENR for this node, if any.
+   */
+  getEncodedEnr(): Promise<string | undefined>;
+
+  /**
+   * Returns info for all connected, dialing, and cached peers.
+   */
+  getPeers(includePending?: boolean): Promise<PeerInfo[]>;
+
+  /**
+   * Returns whether the p2p stack is enabled on this node, and the number of peers it is connected to.
+   * Nodes running without p2p report `enabled: false`, so consumers can tell a disabled stack apart from a
+   * stack that is enabled but has no peers.
+   */
+  getP2PConnectivity(): Promise<P2PConnectivity>;
+
+  /**
+   * Queries the Attestation pool for checkpoint attestations for the given slot.
+   *
+   * @param slot - the slot to query
+   * @param proposalPayloadHash - hex-encoded keccak256 of the target proposal's signed
+   *        payload (`CheckpointProposal.getPayloadHash()`). When provided, only
+   *        attestations whose own signed payload hashes to the same value are returned.
+   *        When omitted, all attestations for the slot are returned.
+   * @returns CheckpointAttestations
+   */
+  getCheckpointAttestationsForSlot(
+    slot: SlotNumber,
+    proposalPayloadHash?: CheckpointProposalHash,
+  ): Promise<CheckpointAttestation[]>;
+}
+
+export type ProposalsForSlot = {
+  blockProposals: BlockProposal[];
+  checkpointProposals: CheckpointProposalCore[];
+};
+
+export interface P2PClient extends P2PApi {
+  /** Manually adds checkpoint attestations to the p2p client attestation pool. */
+  addOwnCheckpointAttestations(attestations: CheckpointAttestation[]): Promise<void>;
+
+  /** Returns retained signed proposals for a slot. */
+  getProposalsForSlot(slot: SlotNumber): Promise<ProposalsForSlot>;
+
+  /** Returns whether a checkpoint proposal was retained for a slot. */
+  hasCheckpointProposalForSlot(slot: SlotNumber): Promise<boolean>;
+}
+
+const MAX_PROPOSALS_FOR_SLOT_RPC_LEN = 256;
+
+export const BlockProposalSchema = bufferSchemaFor(BlockProposal);
+export const CheckpointProposalSchema = bufferSchemaFor(CheckpointProposal);
+
+export const ProposalsForSlotSchema = z.object({
+  blockProposals: z.array(BlockProposalSchema).max(MAX_PROPOSALS_FOR_SLOT_RPC_LEN),
+  checkpointProposals: z.array(CheckpointProposalSchema).max(MAX_PROPOSALS_FOR_SLOT_RPC_LEN),
+});
+
+export const P2PApiSchema: ApiSchemaFor<P2PApi> = {
+  getCheckpointAttestationsForSlot: z.function({
+    input: z.tuple([
+      schemas.SlotNumber,
+      optional(z.string().regex(/^0x[0-9a-fA-F]+$/) as unknown as z.ZodType<CheckpointProposalHash>),
+    ]),
+    output: z.array(CheckpointAttestation.schema),
+  }),
+  getPendingTxs: z.function({
+    input: z.tuple([
+      optional(z.number().gte(1).lte(MAX_RPC_TXS_LEN).default(MAX_RPC_TXS_LEN)),
+      optional(TxHash.schema),
+      optional(GetTxByHashOptionsSchema),
+    ]),
+    output: z.array(Tx.schema),
+  }),
+
+  getPendingTxCount: z.function({ input: z.tuple([]), output: schemas.Integer }),
+  getEncodedEnr: z.function({ input: z.tuple([]), output: z.string().optional() }),
+  getPeers: z.function({ input: z.tuple([optional(z.boolean())]), output: z.array(PeerInfoSchema) }),
+  getP2PConnectivity: z.function({ input: z.tuple([]), output: P2PConnectivitySchema }),
+};