@aztec/archiver 0.0.0-test.1 → 0.0.1-commit.017a351

package/src/store/contract_class_store.ts

@@ -0,0 +1,108 @@
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { toArray } from '@aztec/foundation/iterable';
+import { BufferReader, numToUInt8, serializeToBuffer } from '@aztec/foundation/serialize';
+import type { AztecAsyncKVStore, AztecAsyncMap } from '@aztec/kv-store';
+import type {
+  ContractClassPublic,
+  ContractClassPublicWithBlockNumber,
+  ContractClassPublicWithCommitment,
+} from '@aztec/stdlib/contract';
+
+/**
+ * LMDB-based contract class storage for the archiver.
+ */
+export class ContractClassStore {
+  #contractClasses: AztecAsyncMap<string, Buffer>;
+  #bytecodeCommitments: AztecAsyncMap<string, Buffer>;
+
+  constructor(private db: AztecAsyncKVStore) {
+    this.#contractClasses = db.openMap('archiver_contract_classes');
+    this.#bytecodeCommitments = db.openMap('archiver_bytecode_commitments');
+  }
+
+  /**
+   * Adds multiple contract classes to the store.
+   * @param data - Contract classes (with bytecode commitments) to add.
+   * @param blockNumber - L2 block number where the classes were registered.
+   * @returns True if every insert succeeded.
+   */
+  async addContractClasses(data: ContractClassPublicWithCommitment[], blockNumber: number): Promise<boolean> {
+    return (await Promise.all(data.map(c => this.addContractClass(c, c.publicBytecodeCommitment, blockNumber)))).every(
+      Boolean,
+    );
+  }
+
+  /**
+   * Removes multiple contract classes from the store, but only if they were registered at or after the given block.
+   * @param data - Contract classes to delete.
+   * @param blockNumber - Lower bound on the block number at which the classes were registered.
+   * @returns True if every delete succeeded.
+   */
+  async deleteContractClasses(data: ContractClassPublic[], blockNumber: number): Promise<boolean> {
+    return (await Promise.all(data.map(c => this.deleteContractClass(c, blockNumber)))).every(Boolean);
+  }
+
+  async addContractClass(
+    contractClass: ContractClassPublic,
+    bytecodeCommitment: Fr,
+    blockNumber: number,
+  ): Promise<void> {
+    await this.db.transactionAsync(async () => {
+      const key = contractClass.id.toString();
+      if (await this.#contractClasses.hasAsync(key)) {
+        throw new Error(`Contract class ${key} already exists, cannot add again at block ${blockNumber}`);
+      }
+      await this.#contractClasses.set(
+        key,
+        serializeContractClassPublic({ ...contractClass, l2BlockNumber: blockNumber }),
+      );
+      await this.#bytecodeCommitments.set(key, bytecodeCommitment.toBuffer());
+    });
+  }
+
+  async deleteContractClass(contractClass: ContractClassPublic, blockNumber: number): Promise<void> {
+    const restoredContractClass = await this.#contractClasses.getAsync(contractClass.id.toString());
+    if (restoredContractClass && deserializeContractClassPublic(restoredContractClass).l2BlockNumber >= blockNumber) {
+      await this.db.transactionAsync(async () => {
+        await this.#contractClasses.delete(contractClass.id.toString());
+        await this.#bytecodeCommitments.delete(contractClass.id.toString());
+      });
+    }
+  }
+
+  async getContractClass(id: Fr): Promise<ContractClassPublic | undefined> {
+    const contractClass = await this.#contractClasses.getAsync(id.toString());
+    return contractClass && { ...deserializeContractClassPublic(contractClass), id };
+  }
+
+  async getBytecodeCommitment(id: Fr): Promise<Fr | undefined> {
+    const value = await this.#bytecodeCommitments.getAsync(id.toString());
+    return value === undefined ? undefined : Fr.fromBuffer(value);
+  }
+
+  async getContractClassIds(): Promise<Fr[]> {
+    return (await toArray(this.#contractClasses.keysAsync())).map(key => Fr.fromHexString(key));
+  }
+}
+
+function serializeContractClassPublic(contractClass: Omit<ContractClassPublicWithBlockNumber, 'id'>): Buffer {
+  return serializeToBuffer(
+    contractClass.l2BlockNumber,
+    numToUInt8(contractClass.version),
+    contractClass.artifactHash,
+    contractClass.packedBytecode.length,
+    contractClass.packedBytecode,
+    contractClass.privateFunctionsRoot,
+  );
+}
+
+function deserializeContractClassPublic(buffer: Buffer): Omit<ContractClassPublicWithBlockNumber, 'id'> {
+  const reader = BufferReader.asReader(buffer);
+  return {
+    l2BlockNumber: reader.readNumber(),
+    version: reader.readUInt8() as 1,
+    artifactHash: reader.readObject(Fr),
+    packedBytecode: reader.readBuffer(),
+    privateFunctionsRoot: reader.readObject(Fr),
+  };
+}

package/src/store/contract_instance_store.ts

@@ -0,0 +1,161 @@
+import type { Fr } from '@aztec/foundation/curves/bn254';
+import type { AztecAsyncKVStore, AztecAsyncMap } from '@aztec/kv-store';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+import {
+  type ContractInstanceUpdateWithAddress,
+  type ContractInstanceWithAddress,
+  SerializableContractInstance,
+  SerializableContractInstanceUpdate,
+} from '@aztec/stdlib/contract';
+import type { UInt64 } from '@aztec/stdlib/types';
+
+type ContractInstanceUpdateKey = [string, string] | [string, string, number];
+
+/**
+ * LMDB-based contract instance storage for the archiver.
+ */
+export class ContractInstanceStore {
+  #contractInstances: AztecAsyncMap<string, Buffer>;
+  #contractInstancePublishedAt: AztecAsyncMap<string, number>;
+  #contractInstanceUpdates: AztecAsyncMap<ContractInstanceUpdateKey, Buffer>;
+
+  constructor(private db: AztecAsyncKVStore) {
+    this.#contractInstances = db.openMap('archiver_contract_instances');
+    this.#contractInstancePublishedAt = db.openMap('archiver_contract_instances_publication_block_number');
+    this.#contractInstanceUpdates = db.openMap('archiver_contract_instance_updates');
+  }
+
+  /**
+   * Adds multiple contract instances to the store.
+   * @param data - Contract instances to add.
+   * @param blockNumber - L2 block number where the instances were deployed.
+   * @returns True if every insert succeeded.
+   */
+  async addContractInstances(data: ContractInstanceWithAddress[], blockNumber: number): Promise<boolean> {
+    return (await Promise.all(data.map(c => this.addContractInstance(c, blockNumber)))).every(Boolean);
+  }
+
+  /**
+   * Removes multiple contract instances from the store.
+   * @param data - Contract instances to delete.
+   * @returns True if every delete succeeded.
+   */
+  async deleteContractInstances(data: ContractInstanceWithAddress[]): Promise<boolean> {
+    return (await Promise.all(data.map(c => this.deleteContractInstance(c)))).every(Boolean);
+  }
+
+  /**
+   * Adds multiple contract instance updates to the store.
+   * @param data - Contract instance updates to add.
+   * @param timestamp - Timestamp at which the updates were scheduled.
+   * @returns True if every insert succeeded.
+   */
+  async addContractInstanceUpdates(data: ContractInstanceUpdateWithAddress[], timestamp: UInt64): Promise<boolean> {
+    return (
+      await Promise.all(data.map((update, logIndex) => this.addContractInstanceUpdate(update, timestamp, logIndex)))
+    ).every(Boolean);
+  }
+
+  /**
+   * Removes multiple contract instance updates from the store.
+   * @param data - Contract instance updates to delete.
+   * @param timestamp - Timestamp at which the updates were scheduled.
+   * @returns True if every delete succeeded.
+   */
+  async deleteContractInstanceUpdates(data: ContractInstanceUpdateWithAddress[], timestamp: UInt64): Promise<boolean> {
+    return (
+      await Promise.all(data.map((update, logIndex) => this.deleteContractInstanceUpdate(update, timestamp, logIndex)))
+    ).every(Boolean);
+  }
+
+  addContractInstance(contractInstance: ContractInstanceWithAddress, blockNumber: number): Promise<void> {
+    return this.db.transactionAsync(async () => {
+      const key = contractInstance.address.toString();
+      if (await this.#contractInstances.hasAsync(key)) {
+        throw new Error(
+          `Contract instance at ${key} already exists (deployed at block ${await this.#contractInstancePublishedAt.getAsync(key)}), cannot add again at block ${blockNumber}`,
+        );
+      }
+      await this.#contractInstances.set(key, new SerializableContractInstance(contractInstance).toBuffer());
+      await this.#contractInstancePublishedAt.set(key, blockNumber);
+    });
+  }
+
+  deleteContractInstance(contractInstance: ContractInstanceWithAddress): Promise<void> {
+    return this.db.transactionAsync(async () => {
+      await this.#contractInstances.delete(contractInstance.address.toString());
+      await this.#contractInstancePublishedAt.delete(contractInstance.address.toString());
+    });
+  }
+
+  getUpdateKey(contractAddress: AztecAddress, timestamp: UInt64, logIndex?: number): ContractInstanceUpdateKey {
+    if (logIndex === undefined) {
+      return [contractAddress.toString(), timestamp.toString()];
+    } else {
+      return [contractAddress.toString(), timestamp.toString(), logIndex];
+    }
+  }
+
+  addContractInstanceUpdate(
+    contractInstanceUpdate: ContractInstanceUpdateWithAddress,
+    timestamp: UInt64,
+    logIndex: number,
+  ): Promise<void> {
+    return this.#contractInstanceUpdates.set(
+      this.getUpdateKey(contractInstanceUpdate.address, timestamp, logIndex),
+      new SerializableContractInstanceUpdate(contractInstanceUpdate).toBuffer(),
+    );
+  }
+
+  deleteContractInstanceUpdate(
+    contractInstanceUpdate: ContractInstanceUpdateWithAddress,
+    timestamp: UInt64,
+    logIndex: number,
+  ): Promise<void> {
+    return this.#contractInstanceUpdates.delete(this.getUpdateKey(contractInstanceUpdate.address, timestamp, logIndex));
+  }
+
+  async getCurrentContractInstanceClassId(address: AztecAddress, timestamp: UInt64, originalClassId: Fr): Promise<Fr> {
+    // We need to find the last update before the given timestamp
+    const queryResult = await this.#contractInstanceUpdates
+      .valuesAsync({
+        reverse: true,
+        start: this.getUpdateKey(address, 0n), // Make sure we only look at updates for this contract
+        end: this.getUpdateKey(address, timestamp + 1n), // No update can match this key since it doesn't have a log index. We want the highest key <= timestamp
+        limit: 1,
+      })
+      .next();
+    if (queryResult.done) {
+      return originalClassId;
+    }
+
+    const serializedUpdate = queryResult.value;
+    const update = SerializableContractInstanceUpdate.fromBuffer(serializedUpdate);
+    if (timestamp < update.timestampOfChange) {
+      return update.prevContractClassId.isZero() ? originalClassId : update.prevContractClassId;
+    }
+    return update.newContractClassId;
+  }
+
+  async getContractInstance(
+    address: AztecAddress,
+    timestamp: UInt64,
+  ): Promise<ContractInstanceWithAddress | undefined> {
+    const contractInstance = await this.#contractInstances.getAsync(address.toString());
+    if (!contractInstance) {
+      return undefined;
+    }
+
+    const instance = SerializableContractInstance.fromBuffer(contractInstance).withAddress(address);
+    instance.currentContractClassId = await this.getCurrentContractInstanceClassId(
+      address,
+      timestamp,
+      instance.originalContractClassId,
+    );
+    return instance;
+  }
+
+  getContractInstanceDeploymentBlockNumber(address: AztecAddress): Promise<number | undefined> {
+    return this.#contractInstancePublishedAt.getAsync(address.toString());
+  }
+}

package/src/store/data_stores.ts

@@ -0,0 +1,104 @@
+import type { L1BlockId } from '@aztec/ethereum/l1-types';
+import type { AztecAsyncKVStore } from '@aztec/kv-store';
+import type { BlockHash } from '@aztec/stdlib/block';
+import type { ContractDataSource } from '@aztec/stdlib/contract';
+
+import { join } from 'path';
+
+import { ArchiverContractDataSourceAdapter } from '../modules/contract_data_source_adapter.js';
+import { BlockStore } from './block_store.js';
+import { ContractClassStore } from './contract_class_store.js';
+import { ContractInstanceStore } from './contract_instance_store.js';
+import { FunctionNamesCache } from './function_names_cache.js';
+import { LogStore } from './log_store.js';
+import { MessageStore } from './message_store.js';
+
+export const ARCHIVER_DB_VERSION = 7;
+
+/**
+ * Represents the latest L1 block processed by the archiver for various objects in L2.
+ */
+export type ArchiverL1SynchPoint = {
+  /** Number of the last L1 block that added a new L2 checkpoint metadata.  */
+  blocksSynchedTo?: bigint;
+  /** Last L1 block checked for L1 to L2 messages. */
+  messagesSynchedTo?: L1BlockId;
+};
+
+/**
+ * Bundle of archiver-owned LMDB substores plus the in-memory caches that span them.
+ *
+ * Replaces the former `KVArchiverDataStore` pass-through wrapper. Callers reach into
+ * the relevant substore directly (e.g. `stores.blocks.getBlock`) and use
+ * {@link createArchiverDataStores} to wire them up against a shared KV store.
+ */
+export type ArchiverDataStores = {
+  /** The underlying key-value store. Use {@link AztecAsyncKVStore.transactionAsync} to compose updates atomically. */
+  db: AztecAsyncKVStore;
+  /** Blocks, checkpoints, tx effects, proven/finalized state. */
+  blocks: BlockStore;
+  /** Public, private and contract class logs. */
+  logs: LogStore;
+  /** L1 to L2 messages and message sync state. */
+  messages: MessageStore;
+  /** Contract classes (with bytecode commitments). */
+  contractClasses: ContractClassStore;
+  /** Contract instances and contract instance updates. */
+  contractInstances: ContractInstanceStore;
+  /** In-memory cache of public function selectors -> names. */
+  functionNames: FunctionNamesCache;
+};
+
+/**
+ * Wires up the archiver substores against a shared KV store and returns the
+ * {@link ArchiverDataStores} bundle.
+ *
+ * @param genesisBlockHash - Hash of the synthetic genesis block, forwarded to the {@link LogStore} so it
+ *   can resolve a genesis `referenceBlock` (used by the PXE during early sync) instead of treating it as a
+ *   reorg.
+ */
+export function createArchiverDataStores(db: AztecAsyncKVStore, genesisBlockHash: BlockHash): ArchiverDataStores {
+  const blocks = new BlockStore(db);
+  return {
+    db,
+    blocks,
+    logs: new LogStore(db, blocks, genesisBlockHash),
+    messages: new MessageStore(db),
+    contractClasses: new ContractClassStore(db),
+    contractInstances: new ContractInstanceStore(db),
+    functionNames: new FunctionNamesCache(),
+  };
+}
+
+/**
+ * Returns the L1 sync point of the archiver, combining the block sync point from {@link BlockStore}
+ * and the message sync point from {@link MessageStore}.
+ */
+export async function getArchiverSynchPoint(stores: ArchiverDataStores): Promise<ArchiverL1SynchPoint> {
+  const [blocksSynchedTo, messagesSynchedTo] = await Promise.all([
+    stores.blocks.getSynchedL1BlockNumber(),
+    stores.messages.getSynchedL1Block(),
+  ]);
+  return { blocksSynchedTo, messagesSynchedTo };
+}
+
+/**
+ * Backs up the underlying KV store to the given folder. Returns the path to the resulting db file.
+ */
+export async function backupArchiverDataStores(
+  stores: ArchiverDataStores,
+  path: string,
+  compress = true,
+): Promise<string> {
+  await stores.db.backupTo(path, compress);
+  return join(path, 'data.mdb');
+}
+
+/**
+ * Returns a {@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 function createContractDataSource(stores: ArchiverDataStores): ContractDataSource {
+  return new ArchiverContractDataSourceAdapter(stores);
+}

package/src/store/function_names_cache.ts

@@ -0,0 +1,37 @@
+import { createLogger } from '@aztec/foundation/log';
+import { FunctionSelector } from '@aztec/stdlib/abi';
+
+const MAX_FUNCTION_SIGNATURES = 1000;
+const MAX_FUNCTION_NAME_LEN = 256;
+
+/**
+ * In-memory cache mapping public function selectors to function names.
+ *
+ * Populated opportunistically (e.g. by PXE registering signatures from artifacts) so the
+ * archiver can attach human-readable names to logs and traces. Bounded by
+ * {@link MAX_FUNCTION_SIGNATURES} to avoid unbounded growth from untrusted callers.
+ */
+export class FunctionNamesCache {
+  private readonly log = createLogger('archiver:data-stores');
+  private readonly names: Map<string, string> = new Map();
+
+  /** Adds the given public function signatures to the cache. */
+  public async register(signatures: string[]): Promise<void> {
+    for (const sig of signatures) {
+      if (this.names.size > MAX_FUNCTION_SIGNATURES) {
+        return;
+      }
+      try {
+        const selector = await FunctionSelector.fromSignature(sig);
+        this.names.set(selector.toString(), sig.slice(0, sig.indexOf('(')).slice(0, MAX_FUNCTION_NAME_LEN));
+      } catch {
+        this.log.warn(`Failed to parse signature: ${sig}. Ignoring`);
+      }
+    }
+  }
+
+  /** Looks up a function name for the given selector, or returns undefined if not registered. */
+  public get(selector: FunctionSelector): string | undefined {
+    return this.names.get(selector.toString());
+  }
+}

package/src/store/l2_tips_cache.ts

@@ -0,0 +1,35 @@
+import type { BlockHash, L2Tips } from '@aztec/stdlib/block';
+
+import type { BlockStore } from './block_store.js';
+
+/**
+ * In-memory cache for L2 chain tips (proposed, checkpointed, proven, finalized).
+ * Populated from the BlockStore on first access, then kept up-to-date by the ArchiverDataStoreUpdater.
+ * Refresh calls should happen *after* the store transaction that mutates block data has committed,
+ * so the cache loads from committed state and is never replaced if the writer aborts.
+ */
+export class L2TipsCache {
+  #tipsPromise: Promise<L2Tips> | undefined;
+
+  /**
+   * The genesis block hash is dynamic — derived from the injected initial header, which depends on
+   * `genesisTimestamp` and any prefilled state — so it is supplied here rather than read from store.
+   * The genesis checkpoint hash, by contrast, is the static protocol constant and is resolved
+   * inside the block store.
+   */
+  constructor(
+    private blockStore: BlockStore,
+    private readonly initialBlockHash: BlockHash,
+  ) {}
+
+  /** Returns the cached L2 tips. Loads from the block store on first call. */
+  public getL2Tips(): Promise<L2Tips> {
+    return (this.#tipsPromise ??= this.blockStore.getL2TipsData(this.initialBlockHash));
+  }
+
+  /** Reloads the L2 tips from the block store. Should be called after the writer transaction has committed. */
+  public async refresh(): Promise<void> {
+    this.#tipsPromise = this.blockStore.getL2TipsData(this.initialBlockHash);
+    await this.#tipsPromise;
+  }
+}