@aztec/stdlib 0.82.2 → 0.82.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aztec/stdlib",
-  "version": "0.82.2",
+  "version": "0.82.3",
   "type": "module",
   "inherits": [
     "../package.common.json",
@@ -46,7 +46,10 @@
     "./epoch-helpers": "./dest/epoch-helpers/index.js",
     "./config": "./dest/config/index.js",
     "./testing/jest": "./dest/tests/jest.js",
-    "./database-version": "./dest/database-version/index.js"
+    "./database-version": "./dest/database-version/index.js",
+    "./validators": "./dest/validators/index.js",
+    "./file-store": "./dest/file-store/index.js",
+    "./snapshots": "./dest/snapshots/index.js"
   },
   "typedocOptions": {
     "entryPoints": [
@@ -65,11 +68,12 @@
     "test": "NODE_NO_WARNINGS=1 node --experimental-vm-modules ../node_modules/.bin/jest --passWithNoTests --maxWorkers=${JEST_MAX_WORKERS:-8}"
   },
   "dependencies": {
-    "@aztec/bb.js": "0.82.2",
-    "@aztec/blob-lib": "0.82.2",
-    "@aztec/constants": "0.82.2",
-    "@aztec/ethereum": "0.82.2",
-    "@aztec/foundation": "0.82.2",
+    "@aztec/bb.js": "0.82.3",
+    "@aztec/blob-lib": "0.82.3",
+    "@aztec/constants": "0.82.3",
+    "@aztec/ethereum": "0.82.3",
+    "@aztec/foundation": "0.82.3",
+    "@google-cloud/storage": "^7.15.0",
     "lodash.chunk": "^4.2.0",
     "lodash.isequal": "^4.5.0",
     "lodash.omit": "^4.5.0",

package/src/avm/avm.ts

@@ -1,39 +1,22 @@
 import { Fr } from '@aztec/foundation/fields';
 import { jsonParseWithSchema, jsonStringify } from '@aztec/foundation/json-rpc';
 import { schemas } from '@aztec/foundation/schemas';
+import type { IndexedTreeLeaf } from '@aztec/foundation/trees';
 
 import { z } from 'zod';
 
 import { AztecAddress } from '../aztec-address/index.js';
 import { PublicKeys } from '../keys/public_keys.js';
-import { NullifierLeafPreimage } from '../trees/nullifier_leaf.js';
-import { PublicDataTreeLeafPreimage } from '../trees/public_data_leaf.js';
+import { AppendOnlyTreeSnapshot } from '../trees/append_only_tree_snapshot.js';
+import type { MerkleTreeId } from '../trees/merkle_tree_id.js';
+import { NullifierLeaf } from '../trees/nullifier_leaf.js';
+import { PublicDataTreeLeaf } from '../trees/public_data_leaf.js';
 import { AvmCircuitPublicInputs } from './avm_circuit_public_inputs.js';
 import { serializeWithMessagePack } from './message_pack.js';
 
-export class AvmEnqueuedCallHint {
-  constructor(
-    public readonly msgSender: AztecAddress,
-    public readonly contractAddress: AztecAddress,
-    public readonly calldata: Fr[],
-    public isStaticCall: boolean,
-  ) {}
-
-  static get schema() {
-    return z
-      .object({
-        msgSender: AztecAddress.schema,
-        contractAddress: AztecAddress.schema,
-        calldata: schemas.Fr.array(),
-        isStaticCall: z.boolean(),
-      })
-      .transform(
-        ({ msgSender, contractAddress, calldata, isStaticCall }) =>
-          new AvmEnqueuedCallHint(msgSender, contractAddress, calldata, isStaticCall),
-      );
-  }
-}
-
+////////////////////////////////////////////////////////////////////////////
+// Hints (contracts)
+////////////////////////////////////////////////////////////////////////////
 export class AvmContractClassHint {
   constructor(
     public readonly classId: Fr,
@@ -115,97 +98,145 @@ export class AvmContractInstanceHint {
   }
 }
 
-export class AvmAppendTreeHint {
-  constructor(public readonly leafIndex: Fr, public readonly value: Fr, public readonly siblingPath: Fr[]) {}
-
-  static get schema() {
-    return z
-      .object({
-        leafIndex: schemas.Fr,
-        value: schemas.Fr,
-        siblingPath: schemas.Fr.array(),
-      })
-      .transform(({ leafIndex, value, siblingPath }) => new AvmAppendTreeHint(leafIndex, value, siblingPath));
-  }
-}
-
-export class AvmNullifierWriteTreeHint {
-  constructor(public lowLeafRead: AvmNullifierReadTreeHint, public readonly insertionPath: Fr[]) {}
+////////////////////////////////////////////////////////////////////////////
+// Hints (merkle db)
+////////////////////////////////////////////////////////////////////////////
+// Hint for MerkleTreeDB.getSiblingPath.
+export class AvmGetSiblingPathHint {
+  constructor(
+    public readonly hintKey: AppendOnlyTreeSnapshot,
+    // params
+    public readonly treeId: MerkleTreeId,
+    public readonly index: bigint,
+    // return
+    public readonly path: Fr[],
+  ) {}
 
   static get schema() {
     return z
       .object({
-        lowLeafRead: AvmNullifierReadTreeHint.schema,
-        insertionPath: schemas.Fr.array(),
+        hintKey: AppendOnlyTreeSnapshot.schema,
+        treeId: z.number().int().nonnegative(),
+        index: schemas.BigInt,
+        path: schemas.Fr.array(),
       })
-      .transform(({ lowLeafRead, insertionPath }) => new AvmNullifierWriteTreeHint(lowLeafRead, insertionPath));
+      .transform(({ hintKey, treeId, index, path }) => new AvmGetSiblingPathHint(hintKey, treeId, index, path));
   }
 }
 
-export class AvmNullifierReadTreeHint {
+// Hint for MerkleTreeDB.getPreviousValueIndex.
+export class AvmGetPreviousValueIndexHint {
   constructor(
-    public readonly lowLeafPreimage: NullifierLeafPreimage,
-    public readonly lowLeafIndex: Fr,
-    public readonly lowLeafSiblingPath: Fr[],
+    public readonly hintKey: AppendOnlyTreeSnapshot,
+    // params
+    public readonly treeId: MerkleTreeId,
+    public readonly value: Fr,
+    // return
+    public readonly index: bigint,
+    public readonly alreadyPresent: boolean,
   ) {}
 
   static get schema() {
     return z
       .object({
-        lowLeafPreimage: NullifierLeafPreimage.schema,
-        lowLeafIndex: schemas.Fr,
-        lowLeafSiblingPath: schemas.Fr.array(),
+        hintKey: AppendOnlyTreeSnapshot.schema,
+        treeId: z.number().int().nonnegative(),
+        value: schemas.Fr,
+        index: schemas.BigInt,
+        alreadyPresent: z.boolean(),
       })
       .transform(
-        ({ lowLeafPreimage, lowLeafIndex, lowLeafSiblingPath }) =>
-          new AvmNullifierReadTreeHint(lowLeafPreimage, lowLeafIndex, lowLeafSiblingPath),
+        ({ hintKey, treeId, value, index, alreadyPresent }) =>
+          new AvmGetPreviousValueIndexHint(hintKey, treeId, value, index, alreadyPresent),
       );
   }
 }
 
-export class AvmPublicDataReadTreeHint {
+// Hint for MerkleTreeDB.getLeafPreimage.
+// NOTE: I need this factory because in order to get hold of the schema, I need an actual instance of the class,
+// having the type doesn't suffice since TS does type erasure in the end.
+function AvmGetLeafPreimageHintFactory<T extends IndexedTreeLeaf>(klass: {
+  schema: z.ZodSchema;
+  new (...args: any[]): T;
+}) {
+  return class AvmGetLeafPreimageHint {
+    constructor(
+      public readonly hintKey: AppendOnlyTreeSnapshot,
+      // params (tree id will be implicit)
+      public readonly index: bigint,
+      // return
+      public readonly leaf: T,
+      public readonly nextIndex: bigint,
+      public readonly nextValue: Fr,
+    ) {}
+
+    static get schema() {
+      return z
+        .object({
+          hintKey: AppendOnlyTreeSnapshot.schema,
+          index: schemas.BigInt,
+          leaf: klass.schema,
+          nextIndex: schemas.BigInt,
+          nextValue: schemas.Fr,
+        })
+        .transform(
+          ({ hintKey, index, leaf, nextIndex, nextValue }) =>
+            new AvmGetLeafPreimageHint(hintKey, index, leaf, nextIndex, nextValue),
+        );
+    }
+  };
+}
+
+// Note: only supported for PUBLIC_DATA_TREE and NULLIFIER_TREE.
+export class AvmGetLeafPreimageHintPublicDataTree extends AvmGetLeafPreimageHintFactory(PublicDataTreeLeaf) {}
+export class AvmGetLeafPreimageHintNullifierTree extends AvmGetLeafPreimageHintFactory(NullifierLeaf) {}
+
+// Hint for MerkleTreeDB.getLeafValue.
+// Note: only supported for NOTE_HASH_TREE and L1_TO_L2_MESSAGE_TREE.
+export class AvmGetLeafValueHint {
   constructor(
-    public readonly leafPreimage: PublicDataTreeLeafPreimage,
-    public readonly leafIndex: Fr,
-    public readonly siblingPath: Fr[],
+    public readonly hintKey: AppendOnlyTreeSnapshot,
+    // params
+    public readonly treeId: MerkleTreeId,
+    public readonly index: bigint,
+    // return
+    public readonly value: Fr,
   ) {}
 
-  static empty() {
-    return new AvmPublicDataReadTreeHint(PublicDataTreeLeafPreimage.empty(), Fr.ZERO, []);
-  }
-
   static get schema() {
     return z
       .object({
-        leafPreimage: PublicDataTreeLeafPreimage.schema,
-        leafIndex: schemas.Fr,
-        siblingPath: schemas.Fr.array(),
+        hintKey: AppendOnlyTreeSnapshot.schema,
+        treeId: z.number().int().nonnegative(),
+        index: schemas.BigInt,
+        value: schemas.Fr,
       })
-      .transform(
-        ({ leafPreimage, leafIndex, siblingPath }) =>
-          new AvmPublicDataReadTreeHint(leafPreimage, leafIndex, siblingPath),
-      );
+      .transform(({ hintKey, treeId, index, value }) => new AvmGetLeafValueHint(hintKey, treeId, index, value));
   }
 }
 
-export class AvmPublicDataWriteTreeHint {
+////////////////////////////////////////////////////////////////////////////
+// Hints (other)
+////////////////////////////////////////////////////////////////////////////
+export class AvmEnqueuedCallHint {
   constructor(
-    // To check the current slot has been written to
-    public readonly lowLeafRead: AvmPublicDataReadTreeHint,
-    public readonly newLeafPreimage: PublicDataTreeLeafPreimage,
-    public readonly insertionPath: Fr[],
+    public readonly msgSender: AztecAddress,
+    public readonly contractAddress: AztecAddress,
+    public readonly calldata: Fr[],
+    public isStaticCall: boolean,
   ) {}
 
   static get schema() {
     return z
       .object({
-        lowLeafRead: AvmPublicDataReadTreeHint.schema,
-        newLeafPreimage: PublicDataTreeLeafPreimage.schema,
-        insertionPath: schemas.Fr.array(),
+        msgSender: AztecAddress.schema,
+        contractAddress: AztecAddress.schema,
+        calldata: schemas.Fr.array(),
+        isStaticCall: z.boolean(),
       })
       .transform(
-        ({ lowLeafRead, newLeafPreimage, insertionPath }) =>
-          new AvmPublicDataWriteTreeHint(lowLeafRead, newLeafPreimage, insertionPath),
+        ({ msgSender, contractAddress, calldata, isStaticCall }) =>
+          new AvmEnqueuedCallHint(msgSender, contractAddress, calldata, isStaticCall),
       );
   }
 }
@@ -213,16 +244,16 @@ export class AvmPublicDataWriteTreeHint {
 export class AvmExecutionHints {
   constructor(
     public readonly enqueuedCalls: AvmEnqueuedCallHint[] = [],
+    // Contract hints.
     public readonly contractInstances: AvmContractInstanceHint[] = [],
     public readonly contractClasses: AvmContractClassHint[] = [],
     public readonly bytecodeCommitments: AvmBytecodeCommitmentHint[] = [],
-    public readonly publicDataReads: AvmPublicDataReadTreeHint[] = [],
-    public readonly publicDataWrites: AvmPublicDataWriteTreeHint[] = [],
-    public readonly nullifierReads: AvmNullifierReadTreeHint[] = [],
-    public readonly nullifierWrites: AvmNullifierWriteTreeHint[] = [],
-    public readonly noteHashReads: AvmAppendTreeHint[] = [],
-    public readonly noteHashWrites: AvmAppendTreeHint[] = [],
-    public readonly l1ToL2MessageReads: AvmAppendTreeHint[] = [],
+    // Merkle DB hints.
+    public readonly getSiblingPathHints: AvmGetSiblingPathHint[] = [],
+    public readonly getPreviousValueIndexHints: AvmGetPreviousValueIndexHint[] = [],
+    public readonly getLeafPreimageHintsPublicDataTree: AvmGetLeafPreimageHintPublicDataTree[] = [],
+    public readonly getLeafPreimageHintsNullifierTree: AvmGetLeafPreimageHintNullifierTree[] = [],
+    public readonly getLeafValueHints: AvmGetLeafValueHint[] = [],
   ) {}
 
   static empty() {
@@ -236,13 +267,11 @@ export class AvmExecutionHints {
         contractInstances: AvmContractInstanceHint.schema.array(),
         contractClasses: AvmContractClassHint.schema.array(),
         bytecodeCommitments: AvmBytecodeCommitmentHint.schema.array(),
-        publicDataReads: AvmPublicDataReadTreeHint.schema.array(),
-        publicDataWrites: AvmPublicDataWriteTreeHint.schema.array(),
-        nullifierReads: AvmNullifierReadTreeHint.schema.array(),
-        nullifierWrites: AvmNullifierWriteTreeHint.schema.array(),
-        noteHashReads: AvmAppendTreeHint.schema.array(),
-        noteHashWrites: AvmAppendTreeHint.schema.array(),
-        l1ToL2MessageReads: AvmAppendTreeHint.schema.array(),
+        getSiblingPathHints: AvmGetSiblingPathHint.schema.array(),
+        getPreviousValueIndexHints: AvmGetPreviousValueIndexHint.schema.array(),
+        getLeafPreimageHintsPublicDataTree: AvmGetLeafPreimageHintPublicDataTree.schema.array(),
+        getLeafPreimageHintsNullifierTree: AvmGetLeafPreimageHintNullifierTree.schema.array(),
+        getLeafValueHints: AvmGetLeafValueHint.schema.array(),
       })
       .transform(
         ({
@@ -250,26 +279,22 @@ export class AvmExecutionHints {
           contractInstances,
           contractClasses,
           bytecodeCommitments,
-          publicDataReads,
-          publicDataWrites,
-          nullifierReads,
-          nullifierWrites,
-          noteHashReads,
-          noteHashWrites,
-          l1ToL2MessageReads,
+          getSiblingPathHints,
+          getPreviousValueIndexHints,
+          getLeafPreimageHintsPublicDataTree,
+          getLeafPreimageHintsNullifierTree,
+          getLeafValueHints,
         }) =>
           new AvmExecutionHints(
             enqueuedCalls,
             contractInstances,
             contractClasses,
             bytecodeCommitments,
-            publicDataReads,
-            publicDataWrites,
-            nullifierReads,
-            nullifierWrites,
-            noteHashReads,
-            noteHashWrites,
-            l1ToL2MessageReads,
+            getSiblingPathHints,
+            getPreviousValueIndexHints,
+            getLeafPreimageHintsPublicDataTree,
+            getLeafPreimageHintsNullifierTree,
+            getLeafValueHints,
           ),
       );
   }

package/src/block/l2_block_downloader/l2_block_stream.ts

@@ -9,6 +9,7 @@ import type { PublishedL2Block } from '../published_l2_block.js';
 export class L2BlockStream {
   private readonly runningPromise: RunningPromise;
   private isSyncing = false;
+  private hasStarted = false;
 
   constructor(
     private l2BlockSource: Pick<L2BlockSource, 'getPublishedBlocks' | 'getBlockHeader' | 'getL2Tips'>,
@@ -76,7 +77,12 @@ export class L2BlockStream {
       // If we are just starting, use the starting block number from the options.
       if (latestBlockNumber === 0 && this.opts.startingBlock !== undefined) {
         latestBlockNumber = Math.max(this.opts.startingBlock - 1, 0);
+      }
+
+      // Only log this entry once (for sanity)
+      if (!this.hasStarted) {
         this.log.verbose(`Starting sync from block number ${latestBlockNumber}`);
+        this.hasStarted = true;
       }
 
       // Request new blocks from the source.

package/src/database-version/version_manager.ts

@@ -79,13 +79,15 @@ export class DatabaseVersion {
 
 export type DatabaseVersionManagerFs = Pick<typeof fs, 'readFile' | 'writeFile' | 'rm' | 'mkdir'>;
 
+export const DATABASE_VERSION_FILE_NAME = 'db_version';
+
 /**
  * A manager for handling database versioning and migrations.
  * This class will check the version of data in a directory and either
  * reset or upgrade based on version compatibility.
  */
 export class DatabaseVersionManager<T> {
-  public static readonly VERSION_FILE = 'db_version';
+  public static readonly VERSION_FILE = DATABASE_VERSION_FILE_NAME;
 
   private readonly versionFile: string;
   private readonly currentVersion: DatabaseVersion;
@@ -119,6 +121,11 @@ export class DatabaseVersionManager<T> {
     this.currentVersion = new DatabaseVersion(schemaVersion, rollupAddress);
   }
 
+  static async writeVersion(version: DatabaseVersion, dataDir: string, fileSystem: DatabaseVersionManagerFs = fs) {
+    await fileSystem.mkdir(dataDir, { recursive: true });
+    return fileSystem.writeFile(join(dataDir, DatabaseVersionManager.VERSION_FILE), version.toBuffer());
+  }
+
   /**
    * Checks the stored version against the current version and handles the outcome
    * by either resetting the data directory or calling an upgrade function
@@ -163,7 +170,7 @@ export class DatabaseVersionManager<T> {
         needsReset = true;
       }
     } else {
-      this.log.warn('Rollup address changed, resetting data directory');
+      this.log.warn('Rollup address changed, resetting data directory', { versionFile: this.versionFile });
       needsReset = true;
     }
 
@@ -181,17 +188,14 @@ export class DatabaseVersionManager<T> {
   /**
    * Writes the current version to the version file
    */
-  private async writeVersion(): Promise<void> {
-    // Ensure the directory exists
-    await this.fileSystem.mkdir(this.dataDirectory, { recursive: true });
-    // Write the version file
-    await this.fileSystem.writeFile(this.versionFile, this.currentVersion.toBuffer());
+  public writeVersion(dir?: string): Promise<void> {
+    return DatabaseVersionManager.writeVersion(this.currentVersion, dir ?? this.dataDirectory, this.fileSystem);
   }
 
   /**
    * Resets the data directory by deleting it and recreating it
    */
-  private async resetDataDirectory(): Promise<void> {
+  public async resetDataDirectory(): Promise<void> {
     try {
       await this.fileSystem.rm(this.dataDirectory, { recursive: true, force: true, maxRetries: 3 });
       await this.fileSystem.mkdir(this.dataDirectory, { recursive: true });

package/src/epoch-helpers/index.ts

@@ -26,6 +26,14 @@ export const L1RollupConstantsSchema = z.object({
   ethereumSlotDuration: z.number(),
 }) satisfies ZodFor<L1RollupConstants>;
 
+/** Returns the timestamp for a given L2 slot. */
+export function getTimestampForSlot(
+  slot: bigint,
+  constants: Pick<L1RollupConstants, 'l1GenesisTime' | 'slotDuration'>,
+) {
+  return constants.l1GenesisTime + slot * BigInt(constants.slotDuration);
+}
+
 /** Returns the slot number for a given timestamp. */
 export function getSlotAtTimestamp(ts: bigint, constants: Pick<L1RollupConstants, 'l1GenesisTime' | 'slotDuration'>) {
   return ts < constants.l1GenesisTime ? 0n : (ts - constants.l1GenesisTime) / BigInt(constants.slotDuration);

package/src/file-store/factory.ts

@@ -0,0 +1,61 @@
+import { type Logger, createLogger } from '@aztec/foundation/log';
+
+import { GoogleCloudFileStore } from './gcs.js';
+import { HttpFileStore } from './http.js';
+import type { FileStore, ReadOnlyFileStore } from './interface.js';
+import { LocalFileStore } from './local.js';
+
+const supportedExamples = [
+  `gs://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('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 (err) {
+      throw new Error(`Invalid google cloud 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): Promise<ReadOnlyFileStore>;
+export async function createReadOnlyFileStore(config: undefined, logger?: Logger): Promise<undefined>;
+export async function createReadOnlyFileStore(
+  config: string | undefined,
+  logger = createLogger('stdlib:file-store'),
+): 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);
+  } else {
+    return await createFileStore(config, logger);
+  }
+}

package/src/file-store/gcs.ts

@@ -0,0 +1,121 @@
+import { type Logger, createLogger } from '@aztec/foundation/log';
+
+import { File, Storage, type UploadOptions } from '@google-cloud/storage';
+import { join } from 'path';
+
+import type { FileStore, FileStoreSaveOptions } from './interface.js';
+
+export class GoogleCloudFileStore implements FileStore {
+  private readonly storage: Storage;
+
+  constructor(
+    private readonly bucketName: string,
+    private readonly basePath: string,
+    private readonly log: Logger = createLogger('stdlib:gcs-file-store'),
+  ) {
+    this.storage = new Storage();
+  }
+
+  public async checkCredentials() {
+    await this.storage.getServiceAccount();
+  }
+
+  public async save(
+    path: string,
+    data: Buffer,
+    opts: FileStoreSaveOptions = { public: false, metadata: {}, compress: false },
+  ): Promise<string> {
+    const fullPath = this.getFullPath(path);
+    try {
+      const bucket = this.storage.bucket(this.bucketName);
+      const file = bucket.file(fullPath);
+      await file.save(data, { metadata: opts.metadata, gzip: opts.compress });
+      return this.handleUploadedFile(file, opts);
+    } catch (err: any) {
+      throw new Error(`Error saving file to google cloud storage at ${fullPath}: ${err.message ?? err}`);
+    }
+  }
+
+  public async upload(
+    destPath: string,
+    srcPath: string,
+    opts: FileStoreSaveOptions = { compress: true, public: false, metadata: {} },
+  ): Promise<string> {
+    const fullPath = this.getFullPath(destPath);
+    try {
+      const bucket = this.storage.bucket(this.bucketName);
+      const file = bucket.file(fullPath);
+      const uploadOpts: UploadOptions = {
+        destination: file,
+        gzip: opts.compress,
+        metadata: opts.metadata,
+      };
+      await bucket.upload(srcPath, uploadOpts);
+      return this.handleUploadedFile(file, opts);
+    } catch (err: any) {
+      throw new Error(`Error saving file to google cloud storage at ${fullPath}: ${err.message ?? err}`);
+    }
+  }
+
+  private async handleUploadedFile(file: File, opts: { public?: boolean }): Promise<string> {
+    if (opts.public) {
+      try {
+        if (!(await file.isPublic())) {
+          await file.makePublic();
+        }
+      } catch (err: any) {
+        this.log.warn(
+          `Error making file ${file.name} public: ${
+            err.message ?? err
+          }. This is expected if we handle public access at the bucket level.`,
+        );
+      }
+      return file.publicUrl().replaceAll('%2F', '/');
+    } else {
+      return file.cloudStorageURI.toString();
+    }
+  }
+
+  public async read(pathOrUrlStr: string): Promise<Buffer> {
+    const file = await this.getFileObject(pathOrUrlStr);
+    const contents = await file.download();
+    return contents[0];
+  }
+
+  public async download(pathOrUrlStr: string, destPath: string): Promise<void> {
+    const file = await this.getFileObject(pathOrUrlStr);
+    await file.download({ destination: destPath });
+  }
+
+  public async exists(pathOrUrlStr: string): Promise<boolean> {
+    const { bucketName, fullPath } = this.getBucketAndFullPath(pathOrUrlStr);
+    const bucket = this.storage.bucket(bucketName);
+    const file = bucket.file(fullPath);
+    const [exists] = await file.exists();
+    return exists;
+  }
+
+  private async getFileObject(pathOrUrlStr: string): Promise<File> {
+    const { bucketName, fullPath } = this.getBucketAndFullPath(pathOrUrlStr);
+    const bucket = this.storage.bucket(bucketName);
+    const file = bucket.file(fullPath);
+    if (!(await file.exists())) {
+      throw new Error(`File at ${fullPath} in gcs bucket ${bucketName} does not exist`);
+    }
+    return file;
+  }
+
+  private getBucketAndFullPath(pathOrUrlStr: string): { bucketName: string; fullPath: string } {
+    if (URL.canParse(pathOrUrlStr)) {
+      const url = new URL(pathOrUrlStr);
+      // Note that we accept reading from anywhere, not just our bucket
+      return { fullPath: url.pathname.replace(/^\/+/, ''), bucketName: url.host };
+    } else {
+      return { fullPath: this.getFullPath(pathOrUrlStr), bucketName: this.bucketName };
+    }
+  }
+
+  private getFullPath(path: string): string {
+    return this.basePath && this.basePath.length > 0 ? join(this.basePath, path) : path;
+  }
+}