@aztec-labs/stdlib 6.0.0-nightly.20260829

package/src/deserialization/index.ts

@@ -0,0 +1,54 @@
+/**
+ * Constants for deserialization bounds checking.
+ * These constants define maximum allowed sizes during deserialization
+ * to prevent DoS attacks via maliciously crafted messages.
+ */
+import { BLOBS_PER_CHECKPOINT, FIELDS_PER_BLOB, MAX_BLOCKS_PER_CHECKPOINT } from '@aztec-labs/constants';
+
+/** Max transactions per block for deserialization validation */
+export const MAX_TXS_PER_BLOCK = 2 ** 16;
+
+/** Max committee size - theoretical max from bitmap design (256 bytes × 8 bits) */
+export const MAX_COMMITTEE_SIZE = 2048;
+
+/**
+ * Maximum number of L2 blocks in a provable checkpoint. Used for deserialization and when ingesting
+ * checkpoints already accepted by L1.
+ *
+ * This MUST be >= the number of blocks the proving system can carry, or a structurally-valid, provable
+ * checkpoint that L1 accepts would be rejected on ingest (`validateCheckpoint`) and wedge the archiver.
+ * The checkpoint root circuit caps a checkpoint at {@link MAX_BLOCKS_PER_CHECKPOINT} blocks, well under
+ * the looser ceiling the blob-field budget imposes:
+ *
+ *   budget = BLOBS_PER_CHECKPOINT * FIELDS_PER_BLOB = 6 * 4096 = 24,576 fields
+ *
+ *   per-block minimal blob footprint (every block carries a per-block l1-to-l2 root):
+ *     a block with no txs           = 7 fields   (NUM_BLOCK_END_BLOB_FIELDS)
+ *     a block with one minimal tx   = 7 + 4 = 11 fields
+ *                                     (NUM_BLOCK_END_BLOB_FIELDS + a 4-field minimal tx:
+ *                                      tx start marker + tx hash + fee + 1 mandatory nullifier)
+ *     + 1 checkpoint-end marker      (NUM_CHECKPOINT_END_MARKER_FIELDS)
+ *
+ *   max N:  7 + 11*(N - 1) + 1 <= 24,576  =>  11*(N - 1) <= 24,568  =>  N <= 2,234
+ *
+ * 2234 is kept as the deserialization bound: it is far above the circuit cap, so it never rejects a
+ * provable checkpoint, while still bounding how much a malformed blob payload can allocate. L1 carries
+ * no block count of its own, so an over-cap (and therefore unprovable) checkpoint can only reach it with
+ * a malicious committee supermajority — a terminal network compromise. Invariant checked by the unit
+ * test in deserialization.test.ts.
+ */
+export const MAX_CAPACITY_BLOCKS_PER_CHECKPOINT = 2234;
+
+/**
+ * Max blocks per checkpoint we are willing to build or attest to, and the default block-count limit for
+ * `validateCheckpoint`. This is the protocol cap the checkpoint root circuit enforces: anything above it
+ * is unprovable, so a node must never build or attest to it. Distinct from
+ * {@link MAX_CAPACITY_BLOCKS_PER_CHECKPOINT}, the looser bound used when deserializing untrusted payloads.
+ */
+export const MAX_ATTESTABLE_BLOCKS_PER_CHECKPOINT = MAX_BLOCKS_PER_CHECKPOINT;
+
+/** Max tx effects per body (based on blob capacity per checkpoint) */
+export const MAX_TX_EFFECTS_PER_BODY = BLOBS_PER_CHECKPOINT * FIELDS_PER_BLOB;
+
+/** Max block hash string length (hex: 0x + 64 chars, with generous headroom) */
+export const MAX_BLOCK_HASH_STRING_LENGTH = 128;

package/src/epoch-helpers/index.ts

@@ -0,0 +1,175 @@
+import { EpochNumber, SlotNumber } from '@aztec-labs/foundation/branded-types';
+import { z } from 'zod';
+
+import { schemas, zodFor } from '../schemas/index.js';
+
+export type L1RollupConstants = {
+  l1StartBlock: bigint;
+  l1GenesisTime: bigint;
+  slotDuration: number;
+  epochDuration: number;
+  ethereumSlotDuration: number;
+  proofSubmissionEpochs: number;
+  targetCommitteeSize: number;
+  rollupManaLimit: number;
+};
+
+export const EmptyL1RollupConstants: L1RollupConstants = {
+  l1StartBlock: 0n,
+  l1GenesisTime: 0n,
+  epochDuration: 1, // Not 0 to pervent division by zero
+  slotDuration: 1,
+  ethereumSlotDuration: 1,
+  proofSubmissionEpochs: 1,
+  targetCommitteeSize: 48,
+  rollupManaLimit: Number.MAX_SAFE_INTEGER,
+};
+
+export const L1RollupConstantsSchema = zodFor<L1RollupConstants>()(
+  z.object({
+    l1StartBlock: schemas.BigInt,
+    l1GenesisTime: schemas.BigInt,
+    slotDuration: z.number(),
+    epochDuration: z.number(),
+    ethereumSlotDuration: z.number(),
+    proofSubmissionEpochs: z.number(),
+    targetCommitteeSize: z.number(),
+    rollupManaLimit: z.number(),
+  }),
+);
+
+/** Returns the timestamp for a given L2 slot. */
+export function getTimestampForSlot(
+  slot: SlotNumber,
+  constants: Pick<L1RollupConstants, 'l1GenesisTime' | 'slotDuration'>,
+) {
+  return constants.l1GenesisTime + BigInt(slot) * BigInt(constants.slotDuration);
+}
+
+/** Returns the slot number for a given timestamp. */
+export function getSlotAtTimestamp(
+  ts: bigint,
+  constants: Pick<L1RollupConstants, 'l1GenesisTime' | 'slotDuration'>,
+): SlotNumber {
+  return ts < constants.l1GenesisTime
+    ? SlotNumber.ZERO
+    : SlotNumber.fromBigInt((ts - constants.l1GenesisTime) / BigInt(constants.slotDuration));
+}
+
+/** Returns the timestamp of the next L1 slot boundary after the given wall-clock time. */
+export function getNextL1SlotTimestamp(
+  nowInSeconds: number,
+  constants: Pick<L1RollupConstants, 'l1GenesisTime' | 'ethereumSlotDuration'>,
+): bigint {
+  const now = BigInt(nowInSeconds);
+  const elapsed = now - constants.l1GenesisTime;
+  const currentL1Slot = elapsed / BigInt(constants.ethereumSlotDuration);
+  return constants.l1GenesisTime + (currentL1Slot + 1n) * BigInt(constants.ethereumSlotDuration);
+}
+
+/** Returns the timestamp of the last L1 slot within a given L2 slot. */
+export function getLastL1SlotTimestampForL2Slot(
+  slot: SlotNumber,
+  constants: Pick<L1RollupConstants, 'l1GenesisTime' | 'slotDuration' | 'ethereumSlotDuration'>,
+): bigint {
+  return getTimestampForSlot(slot, constants) + BigInt(constants.slotDuration - constants.ethereumSlotDuration);
+}
+
+/** Returns the L2 slot number at the next L1 block based on the current timestamp. */
+export function getSlotAtNextL1Block(
+  currentL1Timestamp: bigint,
+  constants: Pick<L1RollupConstants, 'l1GenesisTime' | 'slotDuration' | 'ethereumSlotDuration'>,
+): SlotNumber {
+  const nextL1BlockTimestamp = currentL1Timestamp + BigInt(constants.ethereumSlotDuration);
+  return getSlotAtTimestamp(nextL1BlockTimestamp, constants);
+}
+
+/** Returns the epoch number for a given timestamp. */
+export function getEpochNumberAtTimestamp(
+  ts: bigint,
+  constants: Pick<L1RollupConstants, 'epochDuration' | 'slotDuration' | 'l1GenesisTime'>,
+): EpochNumber {
+  return getEpochAtSlot(getSlotAtTimestamp(ts, constants), constants);
+}
+
+/** Returns the epoch number for a given slot. */
+export function getEpochAtSlot(slot: SlotNumber, constants: Pick<L1RollupConstants, 'epochDuration'>): EpochNumber {
+  return EpochNumber.fromBigInt(BigInt(slot) / BigInt(constants.epochDuration));
+}
+
+/** Returns the range of L2 slots (inclusive) for a given epoch number. */
+export function getSlotRangeForEpoch(
+  epochNumber: EpochNumber,
+  constants: Pick<L1RollupConstants, 'epochDuration'>,
+): [SlotNumber, SlotNumber] {
+  const startSlot = SlotNumber(Number(epochNumber) * constants.epochDuration);
+  return [startSlot, SlotNumber(startSlot + constants.epochDuration - 1)];
+}
+
+/**
+ * Returns the range of L1 timestamps (inclusive) for a given epoch number.
+ * Note that the endTimestamp is the start timestamp of the last L1 slot for the epoch.
+ */
+export function getTimestampRangeForEpoch(
+  epochNumber: EpochNumber,
+  constants: Pick<L1RollupConstants, 'l1GenesisTime' | 'slotDuration' | 'epochDuration' | 'ethereumSlotDuration'>,
+): [bigint, bigint] {
+  const [startSlot, endSlot] = getSlotRangeForEpoch(epochNumber, constants);
+  const ethereumSlotsPerL2Slot = constants.slotDuration / constants.ethereumSlotDuration;
+  return [
+    constants.l1GenesisTime + BigInt(startSlot) * BigInt(constants.slotDuration),
+    constants.l1GenesisTime +
+      BigInt(endSlot) * BigInt(constants.slotDuration) +
+      BigInt((ethereumSlotsPerL2Slot - 1) * constants.ethereumSlotDuration),
+  ];
+}
+
+/**
+ * Returns the start timestamp for a given epoch number.
+ */
+export function getStartTimestampForEpoch(
+  epochNumber: EpochNumber,
+  constants: Pick<L1RollupConstants, 'l1GenesisTime' | 'slotDuration' | 'epochDuration'>,
+) {
+  const [startSlot] = getSlotRangeForEpoch(epochNumber, constants);
+  return getTimestampForSlot(startSlot, constants);
+}
+
+/**
+ * Returns the epoch number at which proofs are no longer accepted for a given epoch.
+ * See l1-contracts/src/core/libraries/TimeLib.sol
+ */
+export function getProofSubmissionDeadlineEpoch(
+  epochNumber: EpochNumber,
+  constants: Pick<L1RollupConstants, 'proofSubmissionEpochs'>,
+): EpochNumber {
+  return EpochNumber(epochNumber + constants.proofSubmissionEpochs + 1);
+}
+
+/**
+ * Returns the deadline timestamp (in seconds) for submitting a proof for a given epoch.
+ * Computed as the start of the given epoch plus the proof submission window.
+ */
+export function getProofSubmissionDeadlineTimestamp(
+  epochNumber: EpochNumber,
+  constants: Pick<L1RollupConstants, 'l1GenesisTime' | 'slotDuration' | 'epochDuration' | 'proofSubmissionEpochs'>,
+) {
+  // See l1-contracts/src/core/libraries/TimeLib.sol:
+  // return toSlots(_a) + Slot.wrap(store.epochDuration * (store.proofSubmissionEpochs + 1));
+  const deadlineEpoch = getProofSubmissionDeadlineEpoch(epochNumber, constants);
+  const [deadlineSlot] = getSlotRangeForEpoch(deadlineEpoch, constants);
+  return getTimestampForSlot(deadlineSlot, constants);
+}
+
+/** Computes the quorum size required for a committee (⌊2n/3⌋ + 1). */
+export function computeQuorum(committeeSize: number): number {
+  return Math.floor((committeeSize * 2) / 3) + 1;
+}
+
+/** Returns the timestamp to start building a block for a given L2 slot. Computed as the start timestamp of the slot minus one L1 slot duration. */
+export function getSlotStartBuildTimestamp(
+  slotNumber: SlotNumber,
+  constants: Pick<L1RollupConstants, 'l1GenesisTime' | 'slotDuration' | 'ethereumSlotDuration'>,
+): number {
+  return Number(constants.l1GenesisTime) + slotNumber * constants.slotDuration - constants.ethereumSlotDuration;
+}

package/src/errors/index.ts

@@ -0,0 +1,2 @@
+export * from './proving_error.js';
+export * from './simulation_error.js';

package/src/errors/proving_error.ts

@@ -0,0 +1,22 @@
+/**
+ * An error thrown when generating a proof fails.
+ */
+export class ProvingError extends Error {
+  public static readonly NAME = 'ProvingError';
+
+  /**
+   * Creates a new instance
+   * @param message - The error message.
+   * @param cause - The cause of the error.
+   * @param retry - Whether the proof should be retried.
+   */
+  constructor(
+    message: string,
+    cause?: unknown,
+    public readonly retry: boolean = false,
+  ) {
+    super(message);
+    this.name = ProvingError.NAME;
+    this.cause = cause;
+  }
+}

package/src/errors/simulation_error.ts

@@ -0,0 +1,260 @@
+import type { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { z } from 'zod';
+
+import type { OpcodeLocation } from '../abi/abi.js';
+import { FunctionSelector } from '../abi/function_selector.js';
+import { AztecAddress } from '../aztec-address/index.js';
+import { type ZodFor, optional, schemas } from '../schemas/index.js';
+
+/**
+ * Address and selector of a function that failed during simulation.
+ */
+export interface FailingFunction {
+  /**
+   * The address of the contract that failed.
+   */
+  contractAddress: AztecAddress;
+  /**
+   * The name of the contract that failed.
+   */
+  contractName?: string;
+  /**
+   * The selector of the function that failed.
+   */
+  functionSelector?: FunctionSelector;
+  /**
+   * The name of the function that failed.
+   */
+  functionName?: string;
+}
+
+/**
+ * A pointer to a failing section of the noir source code.
+ */
+export interface SourceCodeLocation {
+  /**
+   * The path to the source file.
+   */
+  filePath: string;
+  /**
+   * The line number of the call.
+   */
+  line: number;
+  /**
+   * The column number of the call.
+   */
+  column: number;
+  /**
+   * The source code of the file.
+   */
+  fileSource: string;
+  /**
+   * The source code text of the failed constraint.
+   */
+  locationText: string;
+}
+
+const SourceCodeLocationSchema = z.object({
+  filePath: z.string(),
+  line: z.number().int().nonnegative(),
+  column: z.number().int().nonnegative(),
+  fileSource: z.string(),
+  locationText: z.string(),
+});
+
+/**
+ * A stack of noir source code locations.
+ */
+export type NoirCallStack = SourceCodeLocation[] | OpcodeLocation[];
+
+const NoirCallStackSchema: z.ZodType<NoirCallStack> = z.union([z.array(SourceCodeLocationSchema), z.array(z.string())]);
+
+/**
+ * Checks if a call stack is unresolved.
+ */
+export function isNoirCallStackUnresolved(callStack: NoirCallStack): callStack is OpcodeLocation[] {
+  return typeof callStack[0] === 'string';
+}
+
+/**
+ * An error during the simulation of a function call.
+ */
+export class SimulationError extends Error {
+  private aztecContext: string = '';
+
+  constructor(
+    private originalMessage: string,
+    private functionErrorStack: FailingFunction[],
+    public revertData: Fr[] = [],
+    private noirErrorStack?: NoirCallStack,
+    options?: ErrorOptions,
+  ) {
+    super(originalMessage, options);
+    const getMessage = () => this.getMessage();
+    const getStack = () => this.getStack();
+    Object.defineProperties(this, {
+      message: {
+        configurable: false,
+        enumerable: true,
+        /**
+         * Getter for the custom error message. It has to be defined here because JS errors have the message property defined
+         * in the error itself, not its prototype. Thus if we define it as a class getter will be shadowed.
+         * @returns The message.
+         */
+        get() {
+          return getMessage();
+        },
+      },
+      stack: {
+        configurable: false,
+        enumerable: true,
+        /**
+         * Getter for the custom error stack. It has to be defined here due to the same issue as the message.
+         * @returns The stack.
+         */
+        get() {
+          return getStack();
+        },
+        /**
+         * We need a setter to avoid the error "TypeError: Cannot set property stack of #<SimulationError> which has only a getter"
+         * whenever we are traversing a nested error chain. However, we don't want to allow setting the stack, since the simulation
+         * error is always gonna be the root of the error chain.
+         * @param value
+         */
+        set(_: string | undefined) {},
+      },
+    });
+  }
+
+  getMessage() {
+    if (this.noirErrorStack && !isNoirCallStackUnresolved(this.noirErrorStack) && this.noirErrorStack.length) {
+      return `${this.originalMessage} '${this.noirErrorStack[this.noirErrorStack.length - 1].locationText}'${
+        this.aztecContext
+      }`;
+    }
+    return this.originalMessage;
+  }
+
+  getOriginalMessage() {
+    return this.originalMessage;
+  }
+
+  setOriginalMessage(message: string) {
+    this.originalMessage = message;
+  }
+
+  /**
+   * Enriches the error with the name of a contract that failed.
+   * @param contractAddress - The address of the contract
+   * @param contractName - The corresponding name
+   */
+  enrichWithContractName(contractAddress: AztecAddress, contractName: string) {
+    this.functionErrorStack.forEach(failingFunction => {
+      if (failingFunction.contractAddress.equals(contractAddress)) {
+        failingFunction.contractName = contractName;
+      }
+    });
+  }
+
+  /**
+   * Enriches the error with the name of a function that failed.
+   * @param contractAddress - The address of the contract
+   * @param functionSelector - The selector of the function
+   * @param functionName - The corresponding name
+   */
+  enrichWithFunctionName(contractAddress: AztecAddress, functionSelector: FunctionSelector, functionName: string) {
+    this.functionErrorStack.forEach(failingFunction => {
+      if (
+        failingFunction.contractAddress.equals(contractAddress) &&
+        !!failingFunction.functionSelector &&
+        failingFunction.functionSelector.equals(functionSelector)
+      ) {
+        failingFunction.functionName = functionName;
+      }
+    });
+  }
+
+  getStack() {
+    const functionCallStack = this.getCallStack();
+    const noirCallStack = this.getNoirCallStack();
+
+    // Try to resolve the contract and function names of the stack of failing functions.
+    const stackLines: string[] = [
+      ...functionCallStack.map(failingFunction => {
+        return `at ${failingFunction.contractName ?? failingFunction.contractAddress.toString()}.${
+          failingFunction.functionName ?? failingFunction.functionSelector?.toString() ?? 'unknown'
+        }`;
+      }),
+      ...noirCallStack.map(errorLocation =>
+        typeof errorLocation === 'string'
+          ? `at opcode ${errorLocation}`
+          : `at ${errorLocation.locationText} (${errorLocation.filePath}:${errorLocation.line}:${errorLocation.column})`,
+      ),
+    ];
+
+    return [`Simulation error: ${this.message}`, ...stackLines.reverse()].join('\n');
+  }
+
+  /**
+   * The aztec function stack that failed during simulation.
+   */
+  getCallStack(): FailingFunction[] {
+    return this.functionErrorStack;
+  }
+
+  /**
+   * Returns the noir call stack inside the first function that failed during simulation.
+   * @returns The noir call stack.
+   */
+  getNoirCallStack(): NoirCallStack {
+    return this.noirErrorStack || [];
+  }
+
+  /**
+   * Sets the noir call stack.
+   * @param callStack - The noir call stack.
+   */
+  setNoirCallStack(callStack: NoirCallStack) {
+    this.noirErrorStack = callStack;
+  }
+
+  setAztecContext(context: string) {
+    this.aztecContext = context;
+  }
+
+  toJSON() {
+    return {
+      originalMessage: this.originalMessage,
+      functionErrorStack: this.functionErrorStack,
+      noirErrorStack: this.noirErrorStack,
+      revertData: this.revertData.map(fr => fr.toString()),
+    };
+  }
+
+  static get schema(): ZodFor<SimulationError> {
+    return z
+      .object({
+        originalMessage: z.string(),
+        functionErrorStack: z.array(
+          z.object({
+            contractAddress: schemas.AztecAddress,
+            contractName: z.string().optional(),
+            functionSelector: optional(schemas.FunctionSelector),
+            functionName: z.string().optional(),
+          }),
+        ),
+        noirErrorStack: NoirCallStackSchema.optional(),
+        revertData: z.array(schemas.Fr),
+      })
+      .transform(
+        ({ originalMessage, functionErrorStack, noirErrorStack, revertData }) =>
+          new SimulationError(originalMessage, functionErrorStack, revertData, noirErrorStack),
+      );
+  }
+
+  static async random() {
+    return new SimulationError('Random simulation error', [
+      { contractAddress: await AztecAddress.random(), functionSelector: FunctionSelector.random() },
+    ]);
+  }
+}

package/src/fees/index.ts

@@ -0,0 +1 @@
+export * from './transaction_fee.js';

package/src/fees/transaction_fee.ts

@@ -0,0 +1,40 @@
+import type { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { strict as assert } from 'assert';
+
+import type { Gas } from '../gas/gas.js';
+import { GasFees } from '../gas/gas_fees.js';
+import type { GasSettings } from '../gas/gas_settings.js';
+
+/**
+ * Compute the effective gas fees that should be used to compute the transaction fee.
+ * This is the sum of the gas fees and the priority fees, but capped at the max fees per gas.
+ */
+export function computeEffectiveGasFees(gasFees: GasFees, gasSettings: GasSettings): GasFees {
+  const { maxFeesPerGas, maxPriorityFeesPerGas } = gasSettings;
+  const minBigInt = (f1: bigint, f2: bigint) => (f1 < f2 ? f1 : f2);
+
+  assert(
+    maxFeesPerGas.feePerDaGas >= gasFees.feePerDaGas,
+    `maxFeesPerGas.feePerDaGas must be greater than or equal to gasFees.feePerDaGas, but got maxFeesPerGas.feePerDaGas=${maxFeesPerGas.feePerDaGas} and gasFees.feePerDaGas=${gasFees.feePerDaGas}`,
+  );
+  assert(
+    maxFeesPerGas.feePerL2Gas >= gasFees.feePerL2Gas,
+    `maxFeesPerGas.feePerL2Gas must be greater than or equal to gasFees.feePerL2Gas, but got maxFeesPerGas.feePerL2Gas=${maxFeesPerGas.feePerL2Gas} and gasFees.feePerL2Gas=${gasFees.feePerL2Gas}`,
+  );
+  const priorityFees = new GasFees(
+    minBigInt(maxPriorityFeesPerGas.feePerDaGas, maxFeesPerGas.feePerDaGas - gasFees.feePerDaGas),
+    minBigInt(maxPriorityFeesPerGas.feePerL2Gas, maxFeesPerGas.feePerL2Gas - gasFees.feePerL2Gas),
+  );
+
+  const effectiveFees = new GasFees(
+    gasFees.feePerDaGas + priorityFees.feePerDaGas,
+    gasFees.feePerL2Gas + priorityFees.feePerL2Gas,
+  );
+
+  return effectiveFees;
+}
+
+export function computeTransactionFee(gasFees: GasFees, gasSettings: GasSettings, gasUsed: Gas): Fr {
+  const effectiveFees = computeEffectiveGasFees(gasFees, gasSettings);
+  return gasUsed.computeFee(effectiveFees);
+}

package/src/file-store/factory.ts

@@ -0,0 +1,92 @@
+import { type Logger, createLogger } from '@aztec-labs/foundation/log';
+
+import { GoogleCloudFileStore } from './gcs.js';
+import { HttpFileStore, type HttpFileStoreOptions } from './http.js';
+import type { FileStore, ReadOnlyFileStore } from './interface.js';
+import { LocalFileStore } from './local.js';
+import { InMemoryFileStore } from './memory.js';
+import { S3FileStore } from './s3.js';
+
+const supportedExamples = [
+  `gs://bucket-name/path/to/store`,
+  `s3://bucket-name/path/to/store`,
+  `file:///absolute/local/path/to/store`,
+  `https://host/path`,
+];
+
+export async function createFileStore(config: string, logger?: Logger): Promise<FileStore>;
+export async function createFileStore(config: undefined, logger?: Logger): Promise<undefined>;
+export async function createFileStore(
+  config: string | undefined,
+  logger = createLogger('stdlib:file-store'),
+): Promise<FileStore | undefined> {
+  if (config === undefined) {
+    return undefined;
+  } else if (config.startsWith('mem://')) {
+    // In-memory store for tests (see InMemoryFileStore). The namespace is everything after the
+    // scheme, so `mem://X` and a later `mem://X` share data, like two file:// stores over one dir.
+    const namespace = config.slice('mem://'.length).replace(/\/+$/, '');
+    logger.info(`Creating in-memory file store at ${namespace}`);
+    return new InMemoryFileStore(namespace);
+  } else if (config.startsWith('file://')) {
+    const url = new URL(config);
+    if (url.host) {
+      throw new Error(`File store URL only supports local paths (got host ${url.host} from ${config})`);
+    }
+    const path = url.pathname;
+    logger.info(`Creating local file file store at ${path}`);
+    return new LocalFileStore(path);
+  } else if (config.startsWith('gs://')) {
+    try {
+      const url = new URL(config);
+      const bucket = url.host;
+      const path = url.pathname.replace(/^\/+/, '');
+      logger.info(`Creating google cloud file store at ${bucket} ${path}`);
+      const store = new GoogleCloudFileStore(bucket, path);
+      await store.checkCredentials();
+      return store;
+    } catch {
+      throw new Error(`Invalid google cloud store definition: '${config}'.`);
+    }
+  } else if (config.startsWith('s3://')) {
+    try {
+      const url = new URL(config);
+      const bucket = url.host;
+      const path = url.pathname.replace(/^\/+/, '');
+      const endpoint = url.searchParams.get('endpoint');
+      const publicBaseUrl = url.searchParams.get('publicBaseUrl') ?? undefined;
+      logger.info(`Creating S3 file store at ${bucket} ${path}`);
+      const store = new S3FileStore(bucket, path, { endpoint: endpoint ?? undefined, publicBaseUrl });
+      return store;
+    } catch {
+      throw new Error(`Invalid S3 store definition: '${config}'.`);
+    }
+  } else {
+    throw new Error(`Unknown file store config: '${config}'. Supported values are ${supportedExamples.join(', ')}.`);
+  }
+}
+
+export async function createReadOnlyFileStore(
+  config: string,
+  logger?: Logger,
+  options?: HttpFileStoreOptions,
+): Promise<ReadOnlyFileStore>;
+export async function createReadOnlyFileStore(
+  config: undefined,
+  logger?: Logger,
+  options?: HttpFileStoreOptions,
+): Promise<undefined>;
+export async function createReadOnlyFileStore(
+  config: string | undefined,
+  logger = createLogger('stdlib:file-store'),
+  options?: HttpFileStoreOptions,
+): Promise<ReadOnlyFileStore | undefined> {
+  if (config === undefined) {
+    return undefined;
+  } else if (config.startsWith('http://') || config.startsWith('https://')) {
+    logger.info(`Creating read-only HTTP file store at ${config}`);
+    return new HttpFileStore(config, logger, options);
+  } else {
+    return await createFileStore(config, logger);
+  }
+}