@aztec/kv-store 0.23.0 → 0.24.0

package/dest/lmdb/store.js

@@ -21,7 +21,7 @@ export class AztecLmdbStore {
             keyEncoding: 'ordered-binary',
         }), "f");
         __classPrivateFieldSet(this, _AztecLmdbStore_multiMapData, rootDb.openDB('data_dup_sort', {
-            encoding: 'msgpack',
+            encoding: 'ordered-binary',
             keyEncoding: 'ordered-binary',
             dupSort: true,
         }), "f");
@@ -94,4 +94,4 @@ export class AztecLmdbStore {
     }
 }
 _AztecLmdbStore_rootDb = new WeakMap(), _AztecLmdbStore_data = new WeakMap(), _AztecLmdbStore_multiMapData = new WeakMap();
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic3RvcmUuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvbG1kYi9zdG9yZS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOztBQUFBLE9BQU8sRUFBRSxpQkFBaUIsRUFBRSxNQUFNLHVCQUF1QixDQUFDO0FBRTFELE9BQU8sRUFBK0IsSUFBSSxFQUFFLE1BQU0sTUFBTSxDQUFDO0FBT3pELE9BQU8sRUFBRSxjQUFjLEVBQUUsTUFBTSxZQUFZLENBQUM7QUFDNUMsT0FBTyxFQUFFLGdCQUFnQixFQUFFLE1BQU0sY0FBYyxDQUFDO0FBQ2hELE9BQU8sRUFBRSxZQUFZLEVBQUUsTUFBTSxVQUFVLENBQUM7QUFDeEMsT0FBTyxFQUFFLGtCQUFrQixFQUFFLE1BQU0sZ0JBQWdCLENBQUM7QUFFcEQ7O0dBRUc7QUFDSCxNQUFNLE9BQU8sY0FBYztJQUt6QixZQUFZLE1BQW9CO1FBSmhDLHlDQUFzQjtRQUN0Qix1Q0FBOEI7UUFDOUIsK0NBQXNDO1FBR3BDLHVCQUFBLElBQUksMEJBQVcsTUFBTSxNQUFBLENBQUM7UUFFdEIsbUNBQW1DO1FBQ25DLHVCQUFBLElBQUksd0JBQVMsTUFBTSxDQUFDLE1BQU0sQ0FBQyxNQUFNLEVBQUU7WUFDakMsUUFBUSxFQUFFLFNBQVM7WUFDbkIsV0FBVyxFQUFFLGdCQUFnQjtTQUM5QixDQUFDLE1BQUEsQ0FBQztRQUVILHVCQUFBLElBQUksZ0NBQWlCLE1BQU0sQ0FBQyxNQUFNLENBQUMsZUFBZSxFQUFFO1lBQ2xELFFBQVEsRUFBRSxTQUFTO1lBQ25CLFdBQVcsRUFBRSxnQkFBZ0I7WUFDN0IsT0FBTyxFQUFFLElBQUk7U0FDZCxDQUFDLE1BQUEsQ0FBQztJQUNMLENBQUM7SUFFRDs7Ozs7Ozs7Ozs7T0FXRztJQUNILE1BQU0sQ0FBQyxJQUFJLENBQUMsSUFBYSxFQUFFLEdBQUcsR0FBRyxpQkFBaUIsQ0FBQyxxQkFBcUIsQ0FBQztRQUN2RSxHQUFHLENBQUMsSUFBSSxDQUFDLDRCQUE0QixJQUFJLElBQUksb0JBQW9CLEVBQUUsQ0FBQyxDQUFDO1FBQ3JFLE1BQU0sTUFBTSxHQUFHLElBQUksQ0FBQyxFQUFFLElBQUksRUFBRSxDQUFDLENBQUM7UUFDOUIsT0FBTyxJQUFJLGNBQWMsQ0FBQyxNQUFNLENBQUMsQ0FBQztJQUNwQyxDQUFDO0lBRUQ7Ozs7T0FJRztJQUNILE9BQU8sQ0FBK0IsSUFBWTtRQUNoRCxPQUFPLElBQUksWUFBWSxDQUFDLHVCQUFBLElBQUksNEJBQU0sRUFBRSxJQUFJLENBQUMsQ0FBQztJQUM1QyxDQUFDO0lBRUQ7Ozs7T0FJRztJQUNILFlBQVksQ0FBK0IsSUFBWTtRQUNyRCxPQUFPLElBQUksWUFBWSxDQUFDLHVCQUFBLElBQUksb0NBQWMsRUFBRSxJQUFJLENBQUMsQ0FBQztJQUNwRCxDQUFDO0lBRUQsV0FBVyxDQUFxRCxJQUFZO1FBQzFFLE9BQU8sSUFBSSxnQkFBZ0IsQ0FBQyx1QkFBQSxJQUFJLDRCQUFNLEVBQUUsSUFBSSxDQUFDLENBQUM7SUFDaEQsQ0FBQztJQUVEOzs7O09BSUc7SUFDSCxTQUFTLENBQUksSUFBWTtRQUN2QixPQUFPLElBQUksY0FBYyxDQUFDLHVCQUFBLElBQUksNEJBQU0sRUFBRSxJQUFJLENBQUMsQ0FBQztJQUM5QyxDQUFDO0lBRUQ7Ozs7T0FJRztJQUNILGFBQWEsQ0FBSSxJQUFZO1FBQzNCLE9BQU8sSUFBSSxrQkFBa0IsQ0FBQyx1QkFBQSxJQUFJLDRCQUFNLEVBQUUsSUFBSSxDQUFDLENBQUM7SUFDbEQsQ0FBQztJQUVEOzs7O09BSUc7SUFDSCxXQUFXLENBQUksUUFBaUI7UUFDOUIsT0FBTyx1QkFBQSxJQUFJLDhCQUFRLENBQUMsV0FBVyxDQUFDLFFBQVEsQ0FBQyxDQUFDO0lBQzVDLENBQUM7SUFFRDs7T0FFRztJQUNILEtBQUssQ0FBQyxLQUFLO1FBQ1QsTUFBTSx1QkFBQSxJQUFJLDhCQUFRLENBQUMsVUFBVSxFQUFFLENBQUM7SUFDbEMsQ0FBQztDQUNGIn0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic3RvcmUuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvbG1kYi9zdG9yZS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOztBQUFBLE9BQU8sRUFBRSxpQkFBaUIsRUFBRSxNQUFNLHVCQUF1QixDQUFDO0FBRTFELE9BQU8sRUFBK0IsSUFBSSxFQUFFLE1BQU0sTUFBTSxDQUFDO0FBT3pELE9BQU8sRUFBRSxjQUFjLEVBQUUsTUFBTSxZQUFZLENBQUM7QUFDNUMsT0FBTyxFQUFFLGdCQUFnQixFQUFFLE1BQU0sY0FBYyxDQUFDO0FBQ2hELE9BQU8sRUFBRSxZQUFZLEVBQUUsTUFBTSxVQUFVLENBQUM7QUFDeEMsT0FBTyxFQUFFLGtCQUFrQixFQUFFLE1BQU0sZ0JBQWdCLENBQUM7QUFFcEQ7O0dBRUc7QUFDSCxNQUFNLE9BQU8sY0FBYztJQUt6QixZQUFZLE1BQW9CO1FBSmhDLHlDQUFzQjtRQUN0Qix1Q0FBOEI7UUFDOUIsK0NBQXNDO1FBR3BDLHVCQUFBLElBQUksMEJBQVcsTUFBTSxNQUFBLENBQUM7UUFFdEIsbUNBQW1DO1FBQ25DLHVCQUFBLElBQUksd0JBQVMsTUFBTSxDQUFDLE1BQU0sQ0FBQyxNQUFNLEVBQUU7WUFDakMsUUFBUSxFQUFFLFNBQVM7WUFDbkIsV0FBVyxFQUFFLGdCQUFnQjtTQUM5QixDQUFDLE1BQUEsQ0FBQztRQUVILHVCQUFBLElBQUksZ0NBQWlCLE1BQU0sQ0FBQyxNQUFNLENBQUMsZUFBZSxFQUFFO1lBQ2xELFFBQVEsRUFBRSxnQkFBZ0I7WUFDMUIsV0FBVyxFQUFFLGdCQUFnQjtZQUM3QixPQUFPLEVBQUUsSUFBSTtTQUNkLENBQUMsTUFBQSxDQUFDO0lBQ0wsQ0FBQztJQUVEOzs7Ozs7Ozs7OztPQVdHO0lBQ0gsTUFBTSxDQUFDLElBQUksQ0FBQyxJQUFhLEVBQUUsR0FBRyxHQUFHLGlCQUFpQixDQUFDLHFCQUFxQixDQUFDO1FBQ3ZFLEdBQUcsQ0FBQyxJQUFJLENBQUMsNEJBQTRCLElBQUksSUFBSSxvQkFBb0IsRUFBRSxDQUFDLENBQUM7UUFDckUsTUFBTSxNQUFNLEdBQUcsSUFBSSxDQUFDLEVBQUUsSUFBSSxFQUFFLENBQUMsQ0FBQztRQUM5QixPQUFPLElBQUksY0FBYyxDQUFDLE1BQU0sQ0FBQyxDQUFDO0lBQ3BDLENBQUM7SUFFRDs7OztPQUlHO0lBQ0gsT0FBTyxDQUErQixJQUFZO1FBQ2hELE9BQU8sSUFBSSxZQUFZLENBQUMsdUJBQUEsSUFBSSw0QkFBTSxFQUFFLElBQUksQ0FBQyxDQUFDO0lBQzVDLENBQUM7SUFFRDs7OztPQUlHO0lBQ0gsWUFBWSxDQUErQixJQUFZO1FBQ3JELE9BQU8sSUFBSSxZQUFZLENBQUMsdUJBQUEsSUFBSSxvQ0FBYyxFQUFFLElBQUksQ0FBQyxDQUFDO0lBQ3BELENBQUM7SUFFRCxXQUFXLENBQXFELElBQVk7UUFDMUUsT0FBTyxJQUFJLGdCQUFnQixDQUFDLHVCQUFBLElBQUksNEJBQU0sRUFBRSxJQUFJLENBQUMsQ0FBQztJQUNoRCxDQUFDO0lBRUQ7Ozs7T0FJRztJQUNILFNBQVMsQ0FBSSxJQUFZO1FBQ3ZCLE9BQU8sSUFBSSxjQUFjLENBQUMsdUJBQUEsSUFBSSw0QkFBTSxFQUFFLElBQUksQ0FBQyxDQUFDO0lBQzlDLENBQUM7SUFFRDs7OztPQUlHO0lBQ0gsYUFBYSxDQUFJLElBQVk7UUFDM0IsT0FBTyxJQUFJLGtCQUFrQixDQUFDLHVCQUFBLElBQUksNEJBQU0sRUFBRSxJQUFJLENBQUMsQ0FBQztJQUNsRCxDQUFDO0lBRUQ7Ozs7T0FJRztJQUNILFdBQVcsQ0FBSSxRQUFpQjtRQUM5QixPQUFPLHVCQUFBLElBQUksOEJBQVEsQ0FBQyxXQUFXLENBQUMsUUFBUSxDQUFDLENBQUM7SUFDNUMsQ0FBQztJQUVEOztPQUVHO0lBQ0gsS0FBSyxDQUFDLEtBQUs7UUFDVCxNQUFNLHVCQUFBLElBQUksOEJBQVEsQ0FBQyxVQUFVLEVBQUUsQ0FBQztJQUNsQyxDQUFDO0NBQ0YifQ==

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aztec/kv-store",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "type": "module",
   "exports": {
     ".": "./dest/interfaces/index.js",
@@ -29,7 +29,7 @@
     "workerThreads": true
   },
   "dependencies": {
-    "@aztec/foundation": "0.23.0",
+    "@aztec/foundation": "0.24.0",
     "lmdb": "^2.9.2"
   },
   "devDependencies": {

package/src/interfaces/array.ts

@@ -0,0 +1,54 @@
+/**
+ * An array backed by a persistent store. Can not have any holes in it.
+ */
+export interface AztecArray<T> {
+  /**
+   * The size of the array
+   */
+  length: number;
+
+  /**
+   * Pushes values to the end of the array
+   * @param vals - The values to push to the end of the array
+   * @returns The new length of the array
+   */
+  push(...vals: T[]): Promise<number>;
+
+  /**
+   * Pops a value from the end of the array.
+   * @returns The value that was popped, or undefined if the array was empty
+   */
+  pop(): Promise<T | undefined>;
+
+  /**
+   * Gets the value at the given index. Index can be in the range [-length, length - 1).
+   * If the index is negative, it will be treated as an offset from the end of the array.
+   *
+   * @param index - The index to get the value from
+   * @returns The value at the given index or undefined if the index is out of bounds
+   */
+  at(index: number): T | undefined;
+
+  /**
+   * Updates the value at the given index. Index can be in the range [-length, length - 1).
+   * @param index - The index to set the value at
+   * @param val - The value to set
+   * @returns Whether the value was set
+   */
+  setAt(index: number, val: T): Promise<boolean>;
+
+  /**
+   * Iterates over the array with indexes.
+   */
+  entries(): IterableIterator<[number, T]>;
+
+  /**
+   * Iterates over the array.
+   */
+  values(): IterableIterator<T>;
+
+  /**
+   * Iterates over the array.
+   */
+  [Symbol.iterator](): IterableIterator<T>;
+}

package/src/interfaces/common.ts

@@ -0,0 +1,18 @@
+/**
+ * The key type for use with the kv-store
+ */
+export type Key = string | number | Array<string | number>;
+
+/**
+ * A range of keys to iterate over.
+ */
+export type Range<K extends Key = Key> = {
+  /** The key of the first item to include */
+  start?: K;
+  /** The key of the last item to include */
+  end?: K;
+  /** Whether to iterate in reverse */
+  reverse?: boolean;
+  /** The maximum number of items to iterate over */
+  limit?: number;
+};

package/src/interfaces/counter.ts

@@ -0,0 +1,43 @@
+import { Key, Range } from './common.js';
+
+/**
+ * A map that counts how many times it sees a key. Once 0 is reached,  that key is removed from the map.
+ * Iterating over the map will only return keys that have a count over 0.
+ *
+ * Keys are stored in sorted order
+ */
+export interface AztecCounter<K extends Key = Key> {
+  /**
+   * Resets the count of the given key to the given value.
+   * @param key - The key to reset
+   * @param value - The value to reset the key to
+   */
+  set(key: K, value: number): Promise<boolean>;
+
+  /**
+   * Updates the count of the given key by the given delta. This can be used to increment or decrement the count.
+   * Once a key's count reaches 0, it is removed from the map.
+   *
+   * @param key - The key to update
+   * @param delta - The amount to modify the key by
+   */
+  update(key: K, delta: number): Promise<boolean>;
+
+  /**
+   * Gets the current count.
+   * @param key - The key to get the count of
+   */
+  get(key: K): number;
+
+  /**
+   * Returns keys in the map in sorted order. Only returns keys that have been seen at least once.
+   * @param range - The range of keys to iterate over
+   */
+  keys(range: Range<K>): IterableIterator<K>;
+
+  /**
+   * Returns keys and their counts in the map sorted by the key. Only returns keys that have been seen at least once.
+   * @param range - The range of keys to iterate over
+   */
+  entries(range: Range<K>): IterableIterator<[K, number]>;
+}

package/src/interfaces/index.ts

@@ -0,0 +1,6 @@
+export * from './array.js';
+export * from './map.js';
+export * from './counter.js';
+export * from './singleton.js';
+export * from './store.js';
+export { Range } from './common.js';

package/src/interfaces/map.ts

@@ -0,0 +1,82 @@
+import { Key, Range } from './common.js';
+
+/**
+ * A map backed by a persistent store.
+ */
+export interface AztecMap<K extends Key, V> {
+  /**
+   * Gets the value at the given key.
+   * @param key - The key to get the value from
+   */
+  get(key: K): V | undefined;
+
+  /**
+   * Checks if a key exists in the map.
+   * @param key - The key to check
+   * @returns True if the key exists, false otherwise
+   */
+  has(key: K): boolean;
+
+  /**
+   * Sets the value at the given key.
+   * @param key - The key to set the value at
+   * @param val - The value to set
+   */
+  set(key: K, val: V): Promise<boolean>;
+
+  /**
+   * Atomically swap the value at the given key
+   * @param key - The key to swap the value at
+   * @param fn - The function to swap the value with
+   */
+  swap(key: K, fn: (val: V | undefined) => V): Promise<boolean>;
+
+  /**
+   * Sets the value at the given key if it does not already exist.
+   * @param key - The key to set the value at
+   * @param val - The value to set
+   */
+  setIfNotExists(key: K, val: V): Promise<boolean>;
+
+  /**
+   * Deletes the value at the given key.
+   * @param key - The key to delete the value at
+   */
+  delete(key: K): Promise<boolean>;
+
+  /**
+   * Iterates over the map's key-value entries in the key's natural order
+   * @param range - The range of keys to iterate over
+   */
+  entries(range?: Range<K>): IterableIterator<[K, V]>;
+
+  /**
+   * Iterates over the map's values in the key's natural order
+   * @param range - The range of keys to iterate over
+   */
+  values(range?: Range<K>): IterableIterator<V>;
+
+  /**
+   * Iterates over the map's keys in the key's natural order
+   * @param range - The range of keys to iterate over
+   */
+  keys(range?: Range<K>): IterableIterator<K>;
+}
+
+/**
+ * A map backed by a persistent store that can have multiple values for a single key.
+ */
+export interface AztecMultiMap<K extends Key, V> extends AztecMap<K, V> {
+  /**
+   * Gets all the values at the given key.
+   * @param key - The key to get the values from
+   */
+  getValues(key: K): IterableIterator<V>;
+
+  /**
+   * Deletes a specific value at the given key.
+   * @param key - The key to delete the value at
+   * @param val - The value to delete
+   */
+  deleteValue(key: K, val: V): Promise<void>;
+}

package/src/interfaces/singleton.ts

@@ -0,0 +1,21 @@
+/**
+ * Represents a singleton value in the database.
+ * Note: The singleton loses type info so it's recommended to serialize to buffer when storing it.
+ */
+export interface AztecSingleton<T> {
+  /**
+   * Gets the value.
+   */
+  get(): T | undefined;
+
+  /**
+   * Sets the value.
+   * @param val - The new value
+   */
+  set(val: T): Promise<boolean>;
+
+  /**
+   * Deletes the value.
+   */
+  delete(): Promise<boolean>;
+}

package/src/interfaces/store.ts

@@ -0,0 +1,53 @@
+import { AztecArray } from './array.js';
+import { Key } from './common.js';
+import { AztecCounter } from './counter.js';
+import { AztecMap, AztecMultiMap } from './map.js';
+import { AztecSingleton } from './singleton.js';
+
+/** A key-value store */
+export interface AztecKVStore {
+  /**
+   * Creates a new map.
+   * @param name - The name of the map
+   * @returns The map
+   */
+  openMap<K extends string | number, V>(name: string): AztecMap<K, V>;
+
+  /**
+   * Creates a new multi-map.
+   * @param name - The name of the multi-map
+   * @returns The multi-map
+   */
+  openMultiMap<K extends string | number, V>(name: string): AztecMultiMap<K, V>;
+
+  /**
+   * Creates a new array.
+   * @param name - The name of the array
+   * @returns The array
+   */
+  openArray<T>(name: string): AztecArray<T>;
+
+  /**
+   * Creates a new singleton.
+   * @param name - The name of the singleton
+   * @returns The singleton
+   */
+  openSingleton<T>(name: string): AztecSingleton<T>;
+
+  /**
+   * Creates a new count map.
+   * @param name - name of the counter
+   */
+  openCounter<K extends Key>(name: string): AztecCounter<K>;
+
+  /**
+   * Starts a transaction. All calls to read/write data while in a transaction are queued and executed atomically.
+   * @param callback - The callback to execute in a transaction
+   */
+  transaction<T extends Exclude<any, Promise<any>>>(callback: () => T): Promise<T>;
+
+  /**
+   * Clears the store
+   */
+  clear(): Promise<void>;
+}

package/src/lmdb/array.ts

@@ -0,0 +1,109 @@
+import { Database, Key } from 'lmdb';
+
+import { AztecArray } from '../interfaces/array.js';
+import { LmdbAztecSingleton } from './singleton.js';
+
+/** The shape of a key that stores a value in an array */
+type ArrayIndexSlot = ['array', string, 'slot', number];
+
+/**
+ * An persistent array backed by LMDB.
+ */
+export class LmdbAztecArray<T> implements AztecArray<T> {
+  #db: Database<T, ArrayIndexSlot>;
+  #name: string;
+  #length: LmdbAztecSingleton<number>;
+
+  constructor(db: Database<unknown, Key>, arrName: string) {
+    this.#name = arrName;
+    this.#length = new LmdbAztecSingleton(db, `${arrName}:meta:length`);
+    this.#db = db as Database<T, ArrayIndexSlot>;
+  }
+
+  get length(): number {
+    return this.#length.get() ?? 0;
+  }
+
+  push(...vals: T[]): Promise<number> {
+    return this.#db.childTransaction(() => {
+      let length = this.length;
+      for (const val of vals) {
+        void this.#db.put(this.#slot(length), val);
+        length += 1;
+      }
+
+      void this.#length.set(length);
+
+      return length;
+    });
+  }
+
+  pop(): Promise<T | undefined> {
+    return this.#db.childTransaction(() => {
+      const length = this.length;
+      if (length === 0) {
+        return undefined;
+      }
+
+      const slot = this.#slot(length - 1);
+      const val = this.#db.get(slot) as T;
+
+      void this.#db.remove(slot);
+      void this.#length.set(length - 1);
+
+      return val;
+    });
+  }
+
+  at(index: number): T | undefined {
+    if (index < 0) {
+      index = this.length + index;
+    }
+
+    // the Array API only accepts indexes in the range [-this.length, this.length)
+    // so if after normalizing the index is still out of range, return undefined
+    if (index < 0 || index >= this.length) {
+      return undefined;
+    }
+
+    return this.#db.get(this.#slot(index));
+  }
+
+  setAt(index: number, val: T): Promise<boolean> {
+    if (index < 0) {
+      index = this.length + index;
+    }
+
+    if (index < 0 || index >= this.length) {
+      return Promise.resolve(false);
+    }
+
+    return this.#db.put(this.#slot(index), val);
+  }
+
+  *entries(): IterableIterator<[number, T]> {
+    const values = this.#db.getRange({
+      start: this.#slot(0),
+      limit: this.length,
+    });
+
+    for (const { key, value } of values) {
+      const index = key[3];
+      yield [index, value];
+    }
+  }
+
+  *values(): IterableIterator<T> {
+    for (const [_, value] of this.entries()) {
+      yield value;
+    }
+  }
+
+  [Symbol.iterator](): IterableIterator<T> {
+    return this.values();
+  }
+
+  #slot(index: number): ArrayIndexSlot {
+    return ['array', this.#name, 'slot', index];
+  }
+}

package/src/lmdb/counter.ts

@@ -0,0 +1,57 @@
+import { Key as BaseKey, Database } from 'lmdb';
+
+import { Key, Range } from '../interfaces/common.js';
+import { AztecCounter } from '../interfaces/counter.js';
+import { LmdbAztecMap } from './map.js';
+
+/**
+ * A counter implementation backed by LMDB
+ */
+export class LmdbAztecCounter<K extends Key> implements AztecCounter<K> {
+  #db: Database;
+  #name: string;
+  #map: LmdbAztecMap<K, number>;
+
+  constructor(db: Database<unknown, BaseKey>, name: string) {
+    this.#db = db;
+    this.#name = name;
+    this.#map = new LmdbAztecMap(db, name);
+  }
+
+  set(key: K, value: number): Promise<boolean> {
+    return this.#map.set(key, value);
+  }
+
+  update(key: K, delta = 1): Promise<boolean> {
+    return this.#db.childTransaction(() => {
+      const current = this.#map.get(key) ?? 0;
+      const next = current + delta;
+
+      if (next < 0) {
+        throw new Error(`Cannot update ${key} in counter ${this.#name} below zero`);
+      }
+
+      if (next === 0) {
+        void this.#map.delete(key);
+      } else {
+        // store the key inside the entry because LMDB might return an internal representation
+        // of the key when iterating over the database
+        void this.#map.set(key, next);
+      }
+
+      return true;
+    });
+  }
+
+  get(key: K): number {
+    return this.#map.get(key) ?? 0;
+  }
+
+  entries(range: Range<K> = {}): IterableIterator<[K, number]> {
+    return this.#map.entries(range);
+  }
+
+  keys(range: Range<K> = {}): IterableIterator<K> {
+    return this.#map.keys(range);
+  }
+}

package/src/lmdb/index.ts

@@ -0,0 +1 @@
+export { AztecLmdbStore } from './store.js';

package/src/lmdb/map.ts

@@ -0,0 +1,129 @@
+import { Database, RangeOptions } from 'lmdb';
+
+import { Key, Range } from '../interfaces/common.js';
+import { AztecMultiMap } from '../interfaces/map.js';
+
+/** The slot where a key-value entry would be stored */
+type MapValueSlot<K extends Key | Buffer> = ['map', string, 'slot', K];
+
+/**
+ * A map backed by LMDB.
+ */
+export class LmdbAztecMap<K extends Key, V> implements AztecMultiMap<K, V> {
+  protected db: Database<[K, V], MapValueSlot<K>>;
+  protected name: string;
+
+  #startSentinel: MapValueSlot<Buffer>;
+  #endSentinel: MapValueSlot<Buffer>;
+
+  constructor(rootDb: Database, mapName: string) {
+    this.name = mapName;
+    this.db = rootDb as Database<[K, V], MapValueSlot<K>>;
+
+    // sentinels are used to define the start and end of the map
+    // with LMDB's key encoding, no _primitive value_ can be "less than" an empty buffer or greater than Byte 255
+    // these will be used later to answer range queries
+    this.#startSentinel = ['map', this.name, 'slot', Buffer.from([])];
+    this.#endSentinel = ['map', this.name, 'slot', Buffer.from([255])];
+  }
+
+  close(): Promise<void> {
+    return this.db.close();
+  }
+
+  get(key: K): V | undefined {
+    return this.db.get(this.#slot(key))?.[1];
+  }
+
+  *getValues(key: K): IterableIterator<V> {
+    const values = this.db.getValues(this.#slot(key));
+    for (const value of values) {
+      yield value?.[1];
+    }
+  }
+
+  has(key: K): boolean {
+    return this.db.doesExist(this.#slot(key));
+  }
+
+  set(key: K, val: V): Promise<boolean> {
+    return this.db.put(this.#slot(key), [key, val]);
+  }
+
+  swap(key: K, fn: (val: V | undefined) => V): Promise<boolean> {
+    return this.db.childTransaction(() => {
+      const slot = this.#slot(key);
+      const entry = this.db.get(slot);
+      void this.db.put(slot, [key, fn(entry?.[1])]);
+
+      return true;
+    });
+  }
+
+  setIfNotExists(key: K, val: V): Promise<boolean> {
+    const slot = this.#slot(key);
+    return this.db.ifNoExists(slot, () => {
+      void this.db.put(slot, [key, val]);
+    });
+  }
+
+  delete(key: K): Promise<boolean> {
+    return this.db.remove(this.#slot(key));
+  }
+
+  async deleteValue(key: K, val: V): Promise<void> {
+    await this.db.remove(this.#slot(key), [key, val]);
+  }
+
+  *entries(range: Range<K> = {}): IterableIterator<[K, V]> {
+    const { reverse = false, limit } = range;
+    // LMDB has a quirk where it expects start > end when reverse=true
+    // in that case, we need to swap the start and end sentinels
+    const start = reverse
+      ? range.end
+        ? this.#slot(range.end)
+        : this.#endSentinel
+      : range.start
+      ? this.#slot(range.start)
+      : this.#startSentinel;
+
+    const end = reverse
+      ? range.start
+        ? this.#slot(range.start)
+        : this.#startSentinel
+      : range.end
+      ? this.#slot(range.end)
+      : this.#endSentinel;
+
+    const lmdbRange: RangeOptions = {
+      start,
+      end,
+      reverse,
+      limit,
+    };
+
+    const iterator = this.db.getRange(lmdbRange);
+
+    for (const {
+      value: [key, value],
+    } of iterator) {
+      yield [key, value];
+    }
+  }
+
+  *values(range: Range<K> = {}): IterableIterator<V> {
+    for (const [_, value] of this.entries(range)) {
+      yield value;
+    }
+  }
+
+  *keys(range: Range<K> = {}): IterableIterator<K> {
+    for (const [key, _] of this.entries(range)) {
+      yield key;
+    }
+  }
+
+  #slot(key: K): MapValueSlot<K> {
+    return ['map', this.name, 'slot', key];
+  }
+}

package/src/lmdb/singleton.ts

@@ -0,0 +1,31 @@
+import { Database, Key } from 'lmdb';
+
+import { AztecSingleton } from '../interfaces/singleton.js';
+
+/** The slot where this singleton will store its value */
+type ValueSlot = ['singleton', string, 'value'];
+
+/**
+ * Stores a single value in LMDB.
+ */
+export class LmdbAztecSingleton<T> implements AztecSingleton<T> {
+  #db: Database<T, ValueSlot>;
+  #slot: ValueSlot;
+
+  constructor(db: Database<unknown, Key>, name: string) {
+    this.#db = db as Database<T, ValueSlot>;
+    this.#slot = ['singleton', name, 'value'];
+  }
+
+  get(): T | undefined {
+    return this.#db.get(this.#slot);
+  }
+
+  set(val: T): Promise<boolean> {
+    return this.#db.put(this.#slot, val);
+  }
+
+  delete(): Promise<boolean> {
+    return this.#db.remove(this.#slot);
+  }
+}

package/src/lmdb/store.ts

@@ -0,0 +1,112 @@
+import { createDebugLogger } from '@aztec/foundation/log';
+
+import { Database, Key, RootDatabase, open } from 'lmdb';
+
+import { AztecArray } from '../interfaces/array.js';
+import { AztecCounter } from '../interfaces/counter.js';
+import { AztecMap, AztecMultiMap } from '../interfaces/map.js';
+import { AztecSingleton } from '../interfaces/singleton.js';
+import { AztecKVStore } from '../interfaces/store.js';
+import { LmdbAztecArray } from './array.js';
+import { LmdbAztecCounter } from './counter.js';
+import { LmdbAztecMap } from './map.js';
+import { LmdbAztecSingleton } from './singleton.js';
+
+/**
+ * A key-value store backed by LMDB.
+ */
+export class AztecLmdbStore implements AztecKVStore {
+  #rootDb: RootDatabase;
+  #data: Database<unknown, Key>;
+  #multiMapData: Database<unknown, Key>;
+
+  constructor(rootDb: RootDatabase) {
+    this.#rootDb = rootDb;
+
+    // big bucket to store all the data
+    this.#data = rootDb.openDB('data', {
+      encoding: 'msgpack',
+      keyEncoding: 'ordered-binary',
+    });
+
+    this.#multiMapData = rootDb.openDB('data_dup_sort', {
+      encoding: 'ordered-binary',
+      keyEncoding: 'ordered-binary',
+      dupSort: true,
+    });
+  }
+
+  /**
+   * Creates a new AztecKVStore backed by LMDB. The path to the database is optional. If not provided,
+   * the database will be stored in a temporary location and be deleted when the process exists.
+   *
+   * The `rollupAddress` passed is checked against what is stored in the database. If they do not match,
+   * the database is cleared before returning the store. This way data is not accidentally shared between
+   * different rollup instances.
+   *
+   * @param path - A path on the disk to store the database. Optional
+   * @param log - A logger to use. Optional
+   * @returns The store
+   */
+  static open(path?: string, log = createDebugLogger('aztec:kv-store:lmdb')): AztecLmdbStore {
+    log.info(`Opening LMDB database at ${path || 'temporary location'}`);
+    const rootDb = open({ path });
+    return new AztecLmdbStore(rootDb);
+  }
+
+  /**
+   * Creates a new AztecMap in the store.
+   * @param name - Name of the map
+   * @returns A new AztecMap
+   */
+  openMap<K extends string | number, V>(name: string): AztecMap<K, V> {
+    return new LmdbAztecMap(this.#data, name);
+  }
+
+  /**
+   * Creates a new AztecMultiMap in the store. A multi-map stores multiple values for a single key automatically.
+   * @param name - Name of the map
+   * @returns A new AztecMultiMap
+   */
+  openMultiMap<K extends string | number, V>(name: string): AztecMultiMap<K, V> {
+    return new LmdbAztecMap(this.#multiMapData, name);
+  }
+
+  openCounter<K extends string | number | Array<string | number>>(name: string): AztecCounter<K> {
+    return new LmdbAztecCounter(this.#data, name);
+  }
+
+  /**
+   * Creates a new AztecArray in the store.
+   * @param name - Name of the array
+   * @returns A new AztecArray
+   */
+  openArray<T>(name: string): AztecArray<T> {
+    return new LmdbAztecArray(this.#data, name);
+  }
+
+  /**
+   * Creates a new AztecSingleton in the store.
+   * @param name - Name of the singleton
+   * @returns A new AztecSingleton
+   */
+  openSingleton<T>(name: string): AztecSingleton<T> {
+    return new LmdbAztecSingleton(this.#data, name);
+  }
+
+  /**
+   * Runs a callback in a transaction.
+   * @param callback - Function to execute in a transaction
+   * @returns A promise that resolves to the return value of the callback
+   */
+  transaction<T>(callback: () => T): Promise<T> {
+    return this.#rootDb.transaction(callback);
+  }
+
+  /**
+   * Clears the store
+   */
+  async clear() {
+    await this.#rootDb.clearAsync();
+  }
+}

package/src/utils.ts

@@ -0,0 +1,41 @@
+import { EthAddress } from '@aztec/foundation/eth-address';
+import { Logger } from '@aztec/foundation/log';
+
+import { AztecKVStore } from './interfaces/store.js';
+import { AztecLmdbStore } from './lmdb/store.js';
+
+/**
+ * Clears the store if the rollup address does not match the one stored in the database.
+ * This is to prevent data from being accidentally shared between different rollup instances.
+ * @param store - The store to check
+ * @param rollupAddress - The ETH address of the rollup contract
+ * @returns A promise that resolves when the store is cleared, or rejects if the rollup address does not match
+ */
+export async function initStoreForRollup<T extends AztecKVStore>(
+  store: T,
+  rollupAddress: EthAddress,
+  log?: Logger,
+): Promise<T> {
+  const rollupAddressValue = store.openSingleton<ReturnType<EthAddress['toString']>>('rollupAddress');
+  const rollupAddressString = rollupAddress.toString();
+  const storedRollupAddressString = rollupAddressValue.get();
+
+  if (typeof storedRollupAddressString !== 'undefined' && storedRollupAddressString !== rollupAddressString) {
+    log?.warn(
+      `Rollup address mismatch: expected ${rollupAddress}, found ${rollupAddressValue}. Clearing entire database...`,
+    );
+
+    await store.clear();
+  }
+
+  await rollupAddressValue.set(rollupAddressString);
+  return store;
+}
+
+/**
+ * Opens a temporary store for testing purposes.
+ * @returns A new store
+ */
+export function openTmpStore(): AztecKVStore {
+  return AztecLmdbStore.open();
+}