@aztec/node-lib 0.82.3-nightly.20250330

package/README.md

@@ -0,0 +1,3 @@
+# Node Lib
+
+Shared code for Aztec Nodes and Prover Nodes.

package/dest/actions/index.d.ts

@@ -0,0 +1,3 @@
+export * from './snapshot-sync.js';
+export * from './upload-snapshot.js';
+//# sourceMappingURL=index.d.ts.map

package/dest/actions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/actions/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC"}

package/dest/actions/index.js

@@ -0,0 +1,2 @@
+export * from './snapshot-sync.js';
+export * from './upload-snapshot.js';

package/dest/actions/snapshot-sync.d.ts

@@ -0,0 +1,12 @@
+import { type ArchiverConfig } from '@aztec/archiver';
+import { type EthereumClientConfig } from '@aztec/ethereum';
+import type { Logger } from '@aztec/foundation/log';
+import type { DataStoreConfig } from '@aztec/kv-store/config';
+import type { ChainConfig } from '@aztec/stdlib/config';
+import type { SharedNodeConfig } from '../config/index.js';
+type SnapshotSyncConfig = Pick<SharedNodeConfig, 'syncMode' | 'snapshotsUrl'> & Pick<ChainConfig, 'l1ChainId' | 'version'> & Pick<ArchiverConfig, 'archiverStoreMapSizeKb' | 'maxLogs'> & Required<DataStoreConfig> & EthereumClientConfig & {
+    minL1BlocksToTriggerReplace?: number;
+};
+export declare function trySnapshotSync(config: SnapshotSyncConfig, log: Logger): Promise<boolean>;
+export {};
+//# sourceMappingURL=snapshot-sync.d.ts.map

package/dest/actions/snapshot-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-sync.d.ts","sourceRoot":"","sources":["../../src/actions/snapshot-sync.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,cAAc,EAGpB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,KAAK,oBAAoB,EAAmB,MAAM,iBAAiB,CAAC;AAG7E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAexD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAK3D,KAAK,kBAAkB,GAAG,IAAI,CAAC,gBAAgB,EAAE,UAAU,GAAG,cAAc,CAAC,GAC3E,IAAI,CAAC,WAAW,EAAE,WAAW,GAAG,SAAS,CAAC,GAC1C,IAAI,CAAC,cAAc,EAAE,wBAAwB,GAAG,SAAS,CAAC,GAC1D,QAAQ,CAAC,eAAe,CAAC,GACzB,oBAAoB,GAAG;IACrB,2BAA2B,CAAC,EAAE,MAAM,CAAC;CACtC,CAAC;AAEJ,wBAAsB,eAAe,CAAC,MAAM,EAAE,kBAAkB,EAAE,GAAG,EAAE,MAAM,oBAoJ5E"}

package/dest/actions/snapshot-sync.js

@@ -0,0 +1,155 @@
+import { ARCHIVER_DB_VERSION, ARCHIVER_STORE_NAME, createArchiverStore } from '@aztec/archiver';
+import { INITIAL_L2_BLOCK_NUM } from '@aztec/constants';
+import { getPublicClient } from '@aztec/ethereum';
+import { tryRmDir } from '@aztec/foundation/fs';
+import { DatabaseVersionManager } from '@aztec/stdlib/database-version';
+import { createReadOnlyFileStore } from '@aztec/stdlib/file-store';
+import { downloadSnapshot, getLatestSnapshotMetadata, makeSnapshotLocalPaths } from '@aztec/stdlib/snapshots';
+import { NATIVE_WORLD_STATE_DBS, WORLD_STATE_DB_VERSION, WORLD_STATE_DIR } from '@aztec/world-state';
+import { mkdir, mkdtemp, rename } from 'fs/promises';
+import { join } from 'path';
+// Half day worth of L1 blocks
+const MIN_L1_BLOCKS_TO_TRIGGER_REPLACE = 86400 / 2 / 12;
+export async function trySnapshotSync(config, log) {
+    let archiverStore;
+    let downloadDir;
+    try {
+        const { syncMode, snapshotsUrl, dataDirectory, l1ChainId, version: l2Version, l1Contracts } = config;
+        if (syncMode === 'full') {
+            log.debug('Snapshot sync is disabled. Running full sync.', {
+                syncMode: syncMode
+            });
+            return false;
+        }
+        if (!snapshotsUrl) {
+            log.verbose('Snapshot sync is disabled. No snapshots URL provided.');
+            return false;
+        }
+        if (!dataDirectory) {
+            log.verbose('Snapshot sync is disabled. No local data directory defined.');
+            return false;
+        }
+        let fileStore;
+        try {
+            fileStore = await createReadOnlyFileStore(snapshotsUrl, log);
+        } catch (err) {
+            log.error(`Invalid config for downloading snapshots`, err);
+            return false;
+        }
+        // Create an archiver store to check the current sync state
+        archiverStore = await createArchiverStore(config);
+        const minL1BlocksToTriggerReplace = config.minL1BlocksToTriggerReplace ?? MIN_L1_BLOCKS_TO_TRIGGER_REPLACE;
+        const archiverL2BlockNumber = await archiverStore.getSynchedL2BlockNumber();
+        if (syncMode === 'snapshot' && archiverL2BlockNumber !== undefined && archiverL2BlockNumber >= INITIAL_L2_BLOCK_NUM) {
+            log.verbose(`Skipping non-forced snapshot sync as archiver is already synced to L2 block ${archiverL2BlockNumber}.`);
+            return false;
+        }
+        const currentL1BlockNumber = await getPublicClient(config).getBlockNumber();
+        const archiverL1BlockNumber = await archiverStore.getSynchPoint().then((s)=>s.blocksSynchedTo);
+        if (archiverL1BlockNumber && currentL1BlockNumber - archiverL1BlockNumber < minL1BlocksToTriggerReplace) {
+            log.verbose(`Skipping snapshot sync as archiver is less than ${currentL1BlockNumber - archiverL1BlockNumber} L1 blocks behind.`, {
+                archiverL1BlockNumber,
+                currentL1BlockNumber,
+                minL1BlocksToTriggerReplace
+            });
+            return false;
+        }
+        const indexMetadata = {
+            l1ChainId,
+            l2Version,
+            rollupAddress: l1Contracts.rollupAddress
+        };
+        let snapshot;
+        try {
+            snapshot = await getLatestSnapshotMetadata(indexMetadata, fileStore);
+        } catch (err) {
+            log.error(`Failed to get latest snapshot metadata. Skipping snapshot sync.`, err, {
+                ...indexMetadata,
+                snapshotsUrl
+            });
+            return false;
+        }
+        if (!snapshot) {
+            log.verbose(`No snapshot found. Skipping snapshot sync.`, {
+                ...indexMetadata,
+                snapshotsUrl
+            });
+            return false;
+        }
+        if (snapshot.schemaVersions.archiver !== ARCHIVER_DB_VERSION) {
+            log.warn(`Skipping snapshot sync as last snapshot has schema version ${snapshot.schemaVersions.archiver} but expected ${ARCHIVER_DB_VERSION}.`, snapshot);
+            return false;
+        }
+        if (snapshot.schemaVersions.worldState !== WORLD_STATE_DB_VERSION) {
+            log.warn(`Skipping snapshot sync as last snapshot has world state schema version ${snapshot.schemaVersions.worldState} but we expected ${WORLD_STATE_DB_VERSION}.`, snapshot);
+            return false;
+        }
+        if (archiverL1BlockNumber && snapshot.l1BlockNumber < archiverL1BlockNumber) {
+            log.verbose(`Skipping snapshot sync since local archiver is at L1 block ${archiverL1BlockNumber} which is further than last snapshot at ${snapshot.l1BlockNumber}`, {
+                snapshot,
+                archiverL1BlockNumber
+            });
+            return false;
+        }
+        if (archiverL1BlockNumber && snapshot.l1BlockNumber - Number(archiverL1BlockNumber) < minL1BlocksToTriggerReplace) {
+            log.verbose(`Skipping snapshot sync as archiver is less than ${snapshot.l1BlockNumber - Number(archiverL1BlockNumber)} L1 blocks behind latest snapshot.`, {
+                snapshot,
+                archiverL1BlockNumber
+            });
+            return false;
+        }
+        // Green light. Download the snapshot to a temp location.
+        downloadDir = await mkdtemp(join(dataDirectory, 'download-'));
+        const downloadPaths = makeSnapshotLocalPaths(downloadDir);
+        log.info(`Downloading snapshot at L1 block ${snapshot.l1BlockNumber} L2 block ${snapshot.l2BlockNumber} from ${snapshotsUrl} to ${downloadDir} for snapshot sync`, {
+            snapshot,
+            downloadPaths
+        });
+        await downloadSnapshot(snapshot, downloadPaths, fileStore);
+        log.info(`Snapshot downloaded at ${downloadDir}`, {
+            snapshotsUrl,
+            snapshot,
+            downloadPaths
+        });
+        // If download was successful, close the archiver store, clear lock and version, and move download there
+        await archiverStore.close();
+        archiverStore = undefined;
+        const archiverPath = join(dataDirectory, ARCHIVER_STORE_NAME);
+        await prepareTarget(archiverPath, ARCHIVER_DB_VERSION, l1Contracts.rollupAddress);
+        await rename(downloadPaths.archiver, join(archiverPath, 'data.mdb'));
+        log.info(`Archiver database set up from snapshot`, {
+            path: archiverPath
+        });
+        // Same for the world state dbs, only that we do not close them, since we assume they are not yet in use
+        const worldStateBasePath = join(dataDirectory, WORLD_STATE_DIR);
+        await prepareTarget(worldStateBasePath, WORLD_STATE_DB_VERSION, l1Contracts.rollupAddress);
+        for (const [name, dir] of NATIVE_WORLD_STATE_DBS){
+            const path = join(worldStateBasePath, dir);
+            await mkdir(path, {
+                recursive: true
+            });
+            await rename(downloadPaths[name], join(path, 'data.mdb'));
+            log.info(`World state database ${name} set up from snapshot`, {
+                path
+            });
+        }
+        log.info(`Snapshot synced to L1 block ${snapshot.l1BlockNumber} L2 block ${snapshot.l2BlockNumber}`, {
+            snapshot
+        });
+    } finally{
+        if (archiverStore) {
+            log.verbose(`Closing temporary archiver data store`);
+            await archiverStore.close();
+        }
+        if (downloadDir) {
+            await tryRmDir(downloadDir, log);
+        }
+    }
+    return true;
+}
+/** Deletes target dir and writes the new version file. */ async function prepareTarget(target, schemaVersion, rollupAddress) {
+    const noOpen = ()=>Promise.resolve(undefined);
+    const versionManager = new DatabaseVersionManager(schemaVersion, rollupAddress, target, noOpen);
+    await versionManager.resetDataDirectory();
+    await versionManager.writeVersion();
+}

package/dest/actions/upload-snapshot.d.ts

@@ -0,0 +1,13 @@
+import { type Archiver } from '@aztec/archiver';
+import type { Logger } from '@aztec/foundation/log';
+import type { DataStoreConfig } from '@aztec/kv-store/config';
+import type { ChainConfig } from '@aztec/stdlib/config';
+import type { WorldStateSynchronizer } from '@aztec/stdlib/interfaces/server';
+type UploadSnapshotConfig = Pick<ChainConfig, 'l1ChainId' | 'version'> & Pick<DataStoreConfig, 'dataDirectory'>;
+/**
+ * Pauses the archiver and world state sync, creates backups of the archiver and world state lmdb environments,
+ * and uploads them to the specified location. Location must be a URL supported by our file store (eg `gs://bucketname/path`).
+ */
+export declare function uploadSnapshot(location: string, archiver: Archiver, worldState: WorldStateSynchronizer, config: UploadSnapshotConfig, log: Logger): Promise<void>;
+export {};
+//# sourceMappingURL=upload-snapshot.d.ts.map

package/dest/actions/upload-snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload-snapshot.d.ts","sourceRoot":"","sources":["../../src/actions/upload-snapshot.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAErE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAU9E,KAAK,oBAAoB,GAAG,IAAI,CAAC,WAAW,EAAE,WAAW,GAAG,SAAS,CAAC,GAAG,IAAI,CAAC,eAAe,EAAE,eAAe,CAAC,CAAC;AAEhH;;;GAGG;AACH,wBAAsB,cAAc,CAClC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,QAAQ,EAClB,UAAU,EAAE,sBAAsB,EAClC,MAAM,EAAE,oBAAoB,EAC5B,GAAG,EAAE,MAAM,iBAoBZ"}

package/dest/actions/upload-snapshot.js

@@ -0,0 +1,86 @@
+import { ARCHIVER_DB_VERSION } from '@aztec/archiver';
+import { tryRmDir } from '@aztec/foundation/fs';
+import { createFileStore } from '@aztec/stdlib/file-store';
+import { uploadSnapshot as uploadSnapshotToStore } from '@aztec/stdlib/snapshots';
+import { WORLD_STATE_DB_VERSION } from '@aztec/world-state';
+import { existsSync } from 'fs';
+import { mkdtemp } from 'fs/promises';
+import { tmpdir } from 'os';
+import { join } from 'path';
+/**
+ * Pauses the archiver and world state sync, creates backups of the archiver and world state lmdb environments,
+ * and uploads them to the specified location. Location must be a URL supported by our file store (eg `gs://bucketname/path`).
+ */ export async function uploadSnapshot(location, archiver, worldState, config, log) {
+    const store = await createFileStore(location);
+    if (!store) {
+        throw new Error(`Failed to create file store for snapshot upload for location ${location}.`);
+    }
+    const backupDir = await mkdtemp(join(config.dataDirectory ?? tmpdir(), 'snapshot-'));
+    try {
+        const paths = await createBackups(backupDir, archiver, worldState, log);
+        const versions = {
+            archiver: ARCHIVER_DB_VERSION,
+            worldState: WORLD_STATE_DB_VERSION
+        };
+        const metadata = await buildSnapshotMetadata(archiver, config);
+        log.info(`Uploading snapshot to ${location}`, {
+            snapshot: metadata
+        });
+        const snapshot = await uploadSnapshotToStore(paths, versions, metadata, store);
+        log.info(`Snapshot uploaded successfully`, {
+            snapshot
+        });
+    } finally{
+        log.info(`Cleaning up backup dir ${backupDir}`);
+        await tryRmDir(backupDir, log);
+    }
+}
+async function buildSnapshotMetadata(archiver, config) {
+    const [rollupAddress, l1BlockNumber, { latest }] = await Promise.all([
+        archiver.getRollupAddress(),
+        archiver.getL1BlockNumber(),
+        archiver.getL2Tips()
+    ]);
+    const { number: l2BlockNumber, hash: l2BlockHash } = latest;
+    if (!l2BlockHash) {
+        throw new Error(`Failed to get L2 block hash from archiver.`);
+    }
+    return {
+        l1ChainId: config.l1ChainId,
+        l2Version: config.version,
+        rollupAddress,
+        l2BlockNumber,
+        l2BlockHash,
+        l1BlockNumber: Number(l1BlockNumber)
+    };
+}
+async function createBackups(backupDir, archiver, worldState, log) {
+    try {
+        log.info(`Pausing archiver and world state sync to start snapshot upload`);
+        await archiver.stop();
+        await worldState.stopSync();
+        log.info(`Creating backups of lmdb environments to ${backupDir}`);
+        const [archiverPath, worldStatePaths] = await Promise.all([
+            archiver.backupTo(join(backupDir, 'archiver')),
+            worldState.backupTo(join(backupDir, 'world-state'))
+        ]);
+        const paths = {
+            ...worldStatePaths,
+            archiver: archiverPath
+        };
+        const missing = Object.entries(paths).filter(([_key, path])=>!path || !existsSync(path));
+        if (missing.length > 0) {
+            throw new Error(`Missing backup files: ${missing.map(([key, path])=>`${path} (${key})`).join(', ')}`);
+        }
+        log.info(`Data stores backed up to ${backupDir}`, {
+            paths
+        });
+        return paths;
+    } catch (err) {
+        throw new Error(`Error creating backups for snapshot upload: ${err}`);
+    } finally{
+        log.info(`Resuming archiver and world state sync`);
+        worldState.resumeSync();
+        archiver.resume();
+    }
+}

package/dest/config/index.d.ts

@@ -0,0 +1,13 @@
+import { type ConfigMappingsType } from '@aztec/foundation/config';
+export type SharedNodeConfig = {
+    /** Whether to populate the genesis state with initial fee juice for the test accounts */
+    testAccounts: boolean;
+    /** Whether to populate the genesis state with initial fee juice for the sponsored FPC */
+    sponsoredFPC: boolean;
+    /** Sync mode: full to always sync via L1, snapshot to download a snapshot if there is no local data, force-snapshot to download even if there is local data. */
+    syncMode: 'full' | 'snapshot' | 'force-snapshot';
+    /** Base URL for snapshots index. Index file will be searched at `SNAPSHOTS_BASE_URL/aztec-L1_CHAIN_ID-VERSION-ROLLUP_ADDRESS/index.json` */
+    snapshotsUrl?: string;
+};
+export declare const sharedNodeConfigMappings: ConfigMappingsType<SharedNodeConfig>;
+//# sourceMappingURL=index.d.ts.map

package/dest/config/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,kBAAkB,EAAuB,MAAM,0BAA0B,CAAC;AAExF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,yFAAyF;IACzF,YAAY,EAAE,OAAO,CAAC;IACtB,yFAAyF;IACzF,YAAY,EAAE,OAAO,CAAC;IACtB,gKAAgK;IAChK,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,gBAAgB,CAAC;IACjD,4IAA4I;IAC5I,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,kBAAkB,CAAC,gBAAgB,CAqBzE,CAAC"}

package/dest/config/index.js

@@ -0,0 +1,22 @@
+import { booleanConfigHelper } from '@aztec/foundation/config';
+export const sharedNodeConfigMappings = {
+    testAccounts: {
+        env: 'TEST_ACCOUNTS',
+        description: 'Whether to populate the genesis state with initial fee juice for the test accounts.',
+        ...booleanConfigHelper()
+    },
+    sponsoredFPC: {
+        env: 'SPONSORED_FPC',
+        description: 'Whether to populate the genesis state with initial fee juice for the sponsored FPC.',
+        ...booleanConfigHelper(false)
+    },
+    syncMode: {
+        env: 'SYNC_MODE',
+        description: 'Set sync mode to `full` to always sync via L1, `snapshot` to download a snapshot if there is no local data, `force-snapshot` to download even if there is local data.',
+        defaultValue: 'snapshot'
+    },
+    snapshotsUrl: {
+        env: 'SYNC_SNAPSHOTS_URL',
+        description: 'Base URL for snapshots index.'
+    }
+};

package/package.json

@@ -0,0 +1,93 @@
+{
+  "name": "@aztec/node-lib",
+  "version": "0.82.3-nightly.20250330",
+  "type": "module",
+  "exports": {
+    "./actions": "./dest/actions/index.js",
+    "./config": "./dest/config/index.js"
+  },
+  "inherits": [
+    "../package.common.json"
+  ],
+  "scripts": {
+    "build": "yarn clean && tsc -b",
+    "build:dev": "tsc -b --watch",
+    "clean": "rm -rf ./dest .tsbuildinfo",
+    "formatting": "run -T prettier --check ./src && run -T eslint ./src",
+    "formatting:fix": "run -T eslint --fix ./src && run -T prettier -w ./src",
+    "bb": "node --no-warnings ./dest/bb/index.js",
+    "test": "NODE_NO_WARNINGS=1 node --experimental-vm-modules ../node_modules/.bin/jest --passWithNoTests --maxWorkers=${JEST_MAX_WORKERS:-8}"
+  },
+  "jest": {
+    "moduleNameMapper": {
+      "^(\\.{1,2}/.*)\\.[cm]?js$": "$1"
+    },
+    "testRegex": "./src/.*\\.test\\.(js|mjs|ts)$",
+    "rootDir": "./src",
+    "transform": {
+      "^.+\\.tsx?$": [
+        "@swc/jest",
+        {
+          "jsc": {
+            "parser": {
+              "syntax": "typescript",
+              "decorators": true
+            },
+            "transform": {
+              "decoratorVersion": "2022-03"
+            }
+          }
+        }
+      ]
+    },
+    "extensionsToTreatAsEsm": [
+      ".ts"
+    ],
+    "reporters": [
+      "default"
+    ],
+    "testTimeout": 120000,
+    "setupFiles": [
+      "../../foundation/src/jest/setup.mjs"
+    ]
+  },
+  "dependencies": {
+    "@aztec/archiver": "0.82.3-nightly.20250330",
+    "@aztec/bb-prover": "0.82.3-nightly.20250330",
+    "@aztec/blob-sink": "0.82.3-nightly.20250330",
+    "@aztec/constants": "0.82.3-nightly.20250330",
+    "@aztec/epoch-cache": "0.82.3-nightly.20250330",
+    "@aztec/ethereum": "0.82.3-nightly.20250330",
+    "@aztec/foundation": "0.82.3-nightly.20250330",
+    "@aztec/kv-store": "0.82.3-nightly.20250330",
+    "@aztec/merkle-tree": "0.82.3-nightly.20250330",
+    "@aztec/p2p": "0.82.3-nightly.20250330",
+    "@aztec/protocol-contracts": "0.82.3-nightly.20250330",
+    "@aztec/prover-client": "0.82.3-nightly.20250330",
+    "@aztec/sequencer-client": "0.82.3-nightly.20250330",
+    "@aztec/simulator": "0.82.3-nightly.20250330",
+    "@aztec/stdlib": "0.82.3-nightly.20250330",
+    "@aztec/telemetry-client": "0.82.3-nightly.20250330",
+    "@aztec/validator-client": "0.82.3-nightly.20250330",
+    "@aztec/world-state": "0.82.3-nightly.20250330",
+    "tslib": "^2.4.0"
+  },
+  "devDependencies": {
+    "@jest/globals": "^29.5.0",
+    "@types/jest": "^29.5.0",
+    "@types/node": "^18.7.23",
+    "jest": "^29.5.0",
+    "jest-mock-extended": "^3.0.3",
+    "ts-node": "^10.9.1",
+    "typescript": "^5.0.4"
+  },
+  "files": [
+    "dest",
+    "src",
+    "!*.test.*"
+  ],
+  "types": "./dest/index.d.ts",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/actions/index.ts

@@ -0,0 +1,2 @@
+export * from './snapshot-sync.js';
+export * from './upload-snapshot.js';

package/src/actions/snapshot-sync.ts

@@ -0,0 +1,198 @@
+import {
+  ARCHIVER_DB_VERSION,
+  ARCHIVER_STORE_NAME,
+  type ArchiverConfig,
+  type ArchiverDataStore,
+  createArchiverStore,
+} from '@aztec/archiver';
+import { INITIAL_L2_BLOCK_NUM } from '@aztec/constants';
+import { type EthereumClientConfig, getPublicClient } from '@aztec/ethereum';
+import type { EthAddress } from '@aztec/foundation/eth-address';
+import { tryRmDir } from '@aztec/foundation/fs';
+import type { Logger } from '@aztec/foundation/log';
+import type { DataStoreConfig } from '@aztec/kv-store/config';
+import type { ChainConfig } from '@aztec/stdlib/config';
+import { DatabaseVersionManager } from '@aztec/stdlib/database-version';
+import { type ReadOnlyFileStore, createReadOnlyFileStore } from '@aztec/stdlib/file-store';
+import {
+  type SnapshotMetadata,
+  type SnapshotsIndexMetadata,
+  downloadSnapshot,
+  getLatestSnapshotMetadata,
+  makeSnapshotLocalPaths,
+} from '@aztec/stdlib/snapshots';
+import { NATIVE_WORLD_STATE_DBS, WORLD_STATE_DB_VERSION, WORLD_STATE_DIR } from '@aztec/world-state';
+
+import { mkdir, mkdtemp, rename } from 'fs/promises';
+import { join } from 'path';
+
+import type { SharedNodeConfig } from '../config/index.js';
+
+// Half day worth of L1 blocks
+const MIN_L1_BLOCKS_TO_TRIGGER_REPLACE = 86400 / 2 / 12;
+
+type SnapshotSyncConfig = Pick<SharedNodeConfig, 'syncMode' | 'snapshotsUrl'> &
+  Pick<ChainConfig, 'l1ChainId' | 'version'> &
+  Pick<ArchiverConfig, 'archiverStoreMapSizeKb' | 'maxLogs'> &
+  Required<DataStoreConfig> &
+  EthereumClientConfig & {
+    minL1BlocksToTriggerReplace?: number;
+  };
+
+export async function trySnapshotSync(config: SnapshotSyncConfig, log: Logger) {
+  let archiverStore: ArchiverDataStore | undefined;
+  let downloadDir: string | undefined;
+
+  try {
+    const { syncMode, snapshotsUrl, dataDirectory, l1ChainId, version: l2Version, l1Contracts } = config;
+    if (syncMode === 'full') {
+      log.debug('Snapshot sync is disabled. Running full sync.', { syncMode: syncMode });
+      return false;
+    }
+
+    if (!snapshotsUrl) {
+      log.verbose('Snapshot sync is disabled. No snapshots URL provided.');
+      return false;
+    }
+
+    if (!dataDirectory) {
+      log.verbose('Snapshot sync is disabled. No local data directory defined.');
+      return false;
+    }
+
+    let fileStore: ReadOnlyFileStore;
+    try {
+      fileStore = await createReadOnlyFileStore(snapshotsUrl, log);
+    } catch (err) {
+      log.error(`Invalid config for downloading snapshots`, err);
+      return false;
+    }
+
+    // Create an archiver store to check the current sync state
+    archiverStore = await createArchiverStore(config);
+
+    const minL1BlocksToTriggerReplace = config.minL1BlocksToTriggerReplace ?? MIN_L1_BLOCKS_TO_TRIGGER_REPLACE;
+    const archiverL2BlockNumber = await archiverStore.getSynchedL2BlockNumber();
+    if (
+      syncMode === 'snapshot' &&
+      archiverL2BlockNumber !== undefined &&
+      archiverL2BlockNumber >= INITIAL_L2_BLOCK_NUM
+    ) {
+      log.verbose(
+        `Skipping non-forced snapshot sync as archiver is already synced to L2 block ${archiverL2BlockNumber}.`,
+      );
+      return false;
+    }
+
+    const currentL1BlockNumber = await getPublicClient(config).getBlockNumber();
+    const archiverL1BlockNumber = await archiverStore.getSynchPoint().then(s => s.blocksSynchedTo);
+    if (archiverL1BlockNumber && currentL1BlockNumber - archiverL1BlockNumber < minL1BlocksToTriggerReplace) {
+      log.verbose(
+        `Skipping snapshot sync as archiver is less than ${
+          currentL1BlockNumber - archiverL1BlockNumber
+        } L1 blocks behind.`,
+        { archiverL1BlockNumber, currentL1BlockNumber, minL1BlocksToTriggerReplace },
+      );
+      return false;
+    }
+
+    const indexMetadata: SnapshotsIndexMetadata = { l1ChainId, l2Version, rollupAddress: l1Contracts.rollupAddress };
+    let snapshot: SnapshotMetadata | undefined;
+    try {
+      snapshot = await getLatestSnapshotMetadata(indexMetadata, fileStore);
+    } catch (err) {
+      log.error(`Failed to get latest snapshot metadata. Skipping snapshot sync.`, err, {
+        ...indexMetadata,
+        snapshotsUrl,
+      });
+      return false;
+    }
+
+    if (!snapshot) {
+      log.verbose(`No snapshot found. Skipping snapshot sync.`, { ...indexMetadata, snapshotsUrl });
+      return false;
+    }
+
+    if (snapshot.schemaVersions.archiver !== ARCHIVER_DB_VERSION) {
+      log.warn(
+        `Skipping snapshot sync as last snapshot has schema version ${snapshot.schemaVersions.archiver} but expected ${ARCHIVER_DB_VERSION}.`,
+        snapshot,
+      );
+      return false;
+    }
+
+    if (snapshot.schemaVersions.worldState !== WORLD_STATE_DB_VERSION) {
+      log.warn(
+        `Skipping snapshot sync as last snapshot has world state schema version ${snapshot.schemaVersions.worldState} but we expected ${WORLD_STATE_DB_VERSION}.`,
+        snapshot,
+      );
+      return false;
+    }
+
+    if (archiverL1BlockNumber && snapshot.l1BlockNumber < archiverL1BlockNumber) {
+      log.verbose(
+        `Skipping snapshot sync since local archiver is at L1 block ${archiverL1BlockNumber} which is further than last snapshot at ${snapshot.l1BlockNumber}`,
+        { snapshot, archiverL1BlockNumber },
+      );
+      return false;
+    }
+
+    if (archiverL1BlockNumber && snapshot.l1BlockNumber - Number(archiverL1BlockNumber) < minL1BlocksToTriggerReplace) {
+      log.verbose(
+        `Skipping snapshot sync as archiver is less than ${
+          snapshot.l1BlockNumber - Number(archiverL1BlockNumber)
+        } L1 blocks behind latest snapshot.`,
+        { snapshot, archiverL1BlockNumber },
+      );
+      return false;
+    }
+
+    // Green light. Download the snapshot to a temp location.
+    downloadDir = await mkdtemp(join(dataDirectory, 'download-'));
+    const downloadPaths = makeSnapshotLocalPaths(downloadDir);
+    log.info(
+      `Downloading snapshot at L1 block ${snapshot.l1BlockNumber} L2 block ${snapshot.l2BlockNumber} from ${snapshotsUrl} to ${downloadDir} for snapshot sync`,
+      { snapshot, downloadPaths },
+    );
+    await downloadSnapshot(snapshot, downloadPaths, fileStore);
+    log.info(`Snapshot downloaded at ${downloadDir}`, { snapshotsUrl, snapshot, downloadPaths });
+
+    // If download was successful, close the archiver store, clear lock and version, and move download there
+    await archiverStore.close();
+    archiverStore = undefined;
+    const archiverPath = join(dataDirectory, ARCHIVER_STORE_NAME);
+    await prepareTarget(archiverPath, ARCHIVER_DB_VERSION, l1Contracts.rollupAddress);
+    await rename(downloadPaths.archiver, join(archiverPath, 'data.mdb'));
+    log.info(`Archiver database set up from snapshot`, { path: archiverPath });
+
+    // Same for the world state dbs, only that we do not close them, since we assume they are not yet in use
+    const worldStateBasePath = join(dataDirectory, WORLD_STATE_DIR);
+    await prepareTarget(worldStateBasePath, WORLD_STATE_DB_VERSION, l1Contracts.rollupAddress);
+    for (const [name, dir] of NATIVE_WORLD_STATE_DBS) {
+      const path = join(worldStateBasePath, dir);
+      await mkdir(path, { recursive: true });
+      await rename(downloadPaths[name], join(path, 'data.mdb'));
+      log.info(`World state database ${name} set up from snapshot`, { path });
+    }
+
+    log.info(`Snapshot synced to L1 block ${snapshot.l1BlockNumber} L2 block ${snapshot.l2BlockNumber}`, { snapshot });
+  } finally {
+    if (archiverStore) {
+      log.verbose(`Closing temporary archiver data store`);
+      await archiverStore.close();
+    }
+    if (downloadDir) {
+      await tryRmDir(downloadDir, log);
+    }
+  }
+
+  return true;
+}
+
+/** Deletes target dir and writes the new version file. */
+async function prepareTarget(target: string, schemaVersion: number, rollupAddress: EthAddress) {
+  const noOpen = () => Promise.resolve(undefined);
+  const versionManager = new DatabaseVersionManager<undefined>(schemaVersion, rollupAddress, target, noOpen);
+  await versionManager.resetDataDirectory();
+  await versionManager.writeVersion();
+}

package/src/actions/upload-snapshot.ts

@@ -0,0 +1,102 @@
+import { ARCHIVER_DB_VERSION, type Archiver } from '@aztec/archiver';
+import { tryRmDir } from '@aztec/foundation/fs';
+import type { Logger } from '@aztec/foundation/log';
+import type { DataStoreConfig } from '@aztec/kv-store/config';
+import type { ChainConfig } from '@aztec/stdlib/config';
+import { createFileStore } from '@aztec/stdlib/file-store';
+import type { WorldStateSynchronizer } from '@aztec/stdlib/interfaces/server';
+import type { SnapshotDataUrls, UploadSnapshotMetadata } from '@aztec/stdlib/snapshots';
+import { uploadSnapshot as uploadSnapshotToStore } from '@aztec/stdlib/snapshots';
+import { WORLD_STATE_DB_VERSION } from '@aztec/world-state';
+
+import { existsSync } from 'fs';
+import { mkdtemp } from 'fs/promises';
+import { tmpdir } from 'os';
+import { join } from 'path';
+
+type UploadSnapshotConfig = Pick<ChainConfig, 'l1ChainId' | 'version'> & Pick<DataStoreConfig, 'dataDirectory'>;
+
+/**
+ * Pauses the archiver and world state sync, creates backups of the archiver and world state lmdb environments,
+ * and uploads them to the specified location. Location must be a URL supported by our file store (eg `gs://bucketname/path`).
+ */
+export async function uploadSnapshot(
+  location: string,
+  archiver: Archiver,
+  worldState: WorldStateSynchronizer,
+  config: UploadSnapshotConfig,
+  log: Logger,
+) {
+  const store = await createFileStore(location);
+  if (!store) {
+    throw new Error(`Failed to create file store for snapshot upload for location ${location}.`);
+  }
+
+  const backupDir = await mkdtemp(join(config.dataDirectory ?? tmpdir(), 'snapshot-'));
+
+  try {
+    const paths = await createBackups(backupDir, archiver, worldState, log);
+    const versions = { archiver: ARCHIVER_DB_VERSION, worldState: WORLD_STATE_DB_VERSION };
+    const metadata = await buildSnapshotMetadata(archiver, config);
+    log.info(`Uploading snapshot to ${location}`, { snapshot: metadata });
+    const snapshot = await uploadSnapshotToStore(paths, versions, metadata, store);
+    log.info(`Snapshot uploaded successfully`, { snapshot });
+  } finally {
+    log.info(`Cleaning up backup dir ${backupDir}`);
+    await tryRmDir(backupDir, log);
+  }
+}
+
+async function buildSnapshotMetadata(
+  archiver: Archiver,
+  config: UploadSnapshotConfig,
+): Promise<UploadSnapshotMetadata> {
+  const [rollupAddress, l1BlockNumber, { latest }] = await Promise.all([
+    archiver.getRollupAddress(),
+    archiver.getL1BlockNumber(),
+    archiver.getL2Tips(),
+  ] as const);
+
+  const { number: l2BlockNumber, hash: l2BlockHash } = latest;
+  if (!l2BlockHash) {
+    throw new Error(`Failed to get L2 block hash from archiver.`);
+  }
+
+  return {
+    l1ChainId: config.l1ChainId,
+    l2Version: config.version,
+    rollupAddress,
+    l2BlockNumber,
+    l2BlockHash,
+    l1BlockNumber: Number(l1BlockNumber),
+  };
+}
+
+async function createBackups(backupDir: string, archiver: Archiver, worldState: WorldStateSynchronizer, log: Logger) {
+  try {
+    log.info(`Pausing archiver and world state sync to start snapshot upload`);
+    await archiver.stop();
+    await worldState.stopSync();
+
+    log.info(`Creating backups of lmdb environments to ${backupDir}`);
+    const [archiverPath, worldStatePaths] = await Promise.all([
+      archiver.backupTo(join(backupDir, 'archiver')),
+      worldState.backupTo(join(backupDir, 'world-state')),
+    ]);
+    const paths: SnapshotDataUrls = { ...worldStatePaths, archiver: archiverPath };
+
+    const missing = Object.entries(paths).filter(([_key, path]) => !path || !existsSync(path));
+    if (missing.length > 0) {
+      throw new Error(`Missing backup files: ${missing.map(([key, path]) => `${path} (${key})`).join(', ')}`);
+    }
+
+    log.info(`Data stores backed up to ${backupDir}`, { paths });
+    return paths;
+  } catch (err) {
+    throw new Error(`Error creating backups for snapshot upload: ${err}`);
+  } finally {
+    log.info(`Resuming archiver and world state sync`);
+    worldState.resumeSync();
+    archiver.resume();
+  }
+}

package/src/config/index.ts

@@ -0,0 +1,35 @@
+import { type ConfigMappingsType, booleanConfigHelper } from '@aztec/foundation/config';
+
+export type SharedNodeConfig = {
+  /** Whether to populate the genesis state with initial fee juice for the test accounts */
+  testAccounts: boolean;
+  /** Whether to populate the genesis state with initial fee juice for the sponsored FPC */
+  sponsoredFPC: boolean;
+  /** Sync mode: full to always sync via L1, snapshot to download a snapshot if there is no local data, force-snapshot to download even if there is local data. */
+  syncMode: 'full' | 'snapshot' | 'force-snapshot';
+  /** Base URL for snapshots index. Index file will be searched at `SNAPSHOTS_BASE_URL/aztec-L1_CHAIN_ID-VERSION-ROLLUP_ADDRESS/index.json` */
+  snapshotsUrl?: string;
+};
+
+export const sharedNodeConfigMappings: ConfigMappingsType<SharedNodeConfig> = {
+  testAccounts: {
+    env: 'TEST_ACCOUNTS',
+    description: 'Whether to populate the genesis state with initial fee juice for the test accounts.',
+    ...booleanConfigHelper(),
+  },
+  sponsoredFPC: {
+    env: 'SPONSORED_FPC',
+    description: 'Whether to populate the genesis state with initial fee juice for the sponsored FPC.',
+    ...booleanConfigHelper(false),
+  },
+  syncMode: {
+    env: 'SYNC_MODE',
+    description:
+      'Set sync mode to `full` to always sync via L1, `snapshot` to download a snapshot if there is no local data, `force-snapshot` to download even if there is local data.',
+    defaultValue: 'snapshot',
+  },
+  snapshotsUrl: {
+    env: 'SYNC_SNAPSHOTS_URL',
+    description: 'Base URL for snapshots index.',
+  },
+};