@balq/node 0.1.1

package/README.md

@@ -0,0 +1,80 @@
+# @balq/node
+
+Node.js bindings for [balq](../../README.md): a local, verified archive of
+contract storage built from EIP-7928 Block-Level Access Lists. In-process
+(napi-rs), no HTTP hop; reads stay available while `sync()` runs.
+
+```js
+const { Archive, Layout, NotAvailableError } = require("@balq/node");
+
+const ar = Archive.open("./balq.redb", { proofWindow: 0 });
+ar.watch("0x3582…53ce", 114563);            // from >= head + 1
+await ar.sync("http://localhost:8545");     // fetch → verify → apply; returns a SyncReport
+
+const v = ar.storageAt("0x3582…53ce", "0", 114591);
+// { value: "0x…0c", provenance: "bal", setAt: 114590, index: 125 }
+
+const layout = Layout.fromFile("./out/Playground.sol/Playground.json"); // forge artifact or bare storageLayout
+const loc = layout.locate("balances[0x61Cc…ca80]");
+layout.decode(loc, ar.storageAt("0x3582…53ce", loc.slot, 114591).value); // "37585"
+
+try {
+  ar.storageAt("0x3582…53ce", "0", 114500);
+} catch (e) {
+  if (e instanceof NotAvailableError) console.log(e.code); // "BeforeStart" — never null
+}
+```
+
+Every miss is a `NotAvailableError` with `code` ∈ `NotWatched | BeforeStart |
+AfterHead | NotSynced | NotBootstrapped | BootstrapPending | BootstrapLost |
+Internal`. Numbers are JS numbers (block heights fit); words, slots and
+addresses are 0x-hex strings.
+
+## API
+
+| | |
+|---|---|
+| `Archive.open(path, {proofWindow?, fullDetail?, allowUnverified?})` | open or create |
+| `watch(addr, fromBlock)` / `unwatch(addr)` / `watchlist()` / `head()` | watchlist and head |
+| `sync(rpcUrl, bootstrap = true, backupRpc?): Promise<SyncReport>` | one pass to the node's head; `backupRpc` (any archive provider) is asked only when `rpcUrl` lacks a BAL or cannot prove a slot, and is verified the same way |
+| `storageAt(addr, slot, block): StorageValue` | one ordered seek |
+| `history(addr, slot, from, to): HistoryEntry[]` | changes in `[from, to)` |
+| `changedSlots(addr, block): string[]` | from the block index |
+| `bootstrapSlot(rpcUrl, addr, slot, backupRpc?): Promise<void>` | prove a never-changed slot at head |
+| `Layout.fromFile(path)` / `Layout.fromJson(s)` | solc storageLayout |
+| `locate(path)` / `decode(loc, word)` / `describeSlot(slot)` / `fields()` | names ↔ slots |
+
+## Build locally
+
+```
+npm ci
+npx napi build --platform          # needs Node >= 20.12 for the CLI; the module itself runs on >= 18
+node test/smoke.mjs                # against ../../testbed/balq.redb
+```
+
+Zero logic lives in this crate — see `src/lib.rs`: argument conversion,
+one call into `bal-archive` / `bal-layout`, result conversion.
+
+## Reading by name: `view`
+
+```js
+const view = ar.view(proxy, layout).at(114591);   // storage as of the end of block 114591
+
+view.counter            // 12n
+view.balances[addr]     // 37585n
+view.nested[addr][7]    // 0x… (raw word if the layout cannot decode it)
+view.totals.index       // 5000000000000000146n
+view.items[3]           // …
+view.items.length       // 8n
+view.c                  // true
+view.lastPoker          // "0x61Cc…"
+```
+
+Integers are `bigint`, bools `boolean`, addresses / bytes / undecodable
+words `string`. A missing value throws `NotAvailableError` (never
+`undefined`); an unknown field throws at access time.
+
+Types: `balq typegen out/Playground.sol/Playground.json > Playground.d.ts`
+(or `layout.typescript("PlaygroundView")`), then
+`ar.view(proxy, layout).at<PlaygroundView>(block)` — misspelled fields
+fail at compile time.

package/index.d.ts

@@ -0,0 +1,165 @@
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+/** The archive. Safe to read from while `sync()` is in flight. */
+export declare class Archive {
+  /** Open (or create) an archive file. */
+  static open(path: string, options?: ArchiveOptions | undefined | null): Archive
+  /** Start accumulating `address` from `fromBlock` (must be > current head). */
+  watch(address: string, fromBlock: number): void
+  /** Stop watching and delete the address's data. */
+  unwatch(address: string): void
+  /** Watched addresses with their start blocks. */
+  watchlist(): Array<WatchEntry>
+  /** Last applied block, or null if nothing was synced yet. */
+  head(): Head | null
+  /**
+   * Fetch, verify and apply blocks from `rpcUrl` up to its head. Bootstraps
+   * first-seen slots via eth_getProof unless `bootstrap === false`.
+   * `backupRpc` (an archive endpoint, any provider) is asked only when the
+   * primary lacks a block's BAL or cannot prove a slot; its answers are
+   * verified exactly like the primary's.
+   */
+  sync(rpcUrl: string, bootstrap?: boolean | undefined | null, backupRpc?: string | undefined | null): Promise<SyncReport>
+  /** Value of `slot` at the end of `block`. Throws NotAvailableError, never returns null. */
+  storageAt(address: string, slot: string, block: number): StorageValue
+  /** Changes of `slot` in `[from, to)`. */
+  history(address: string, slot: string, from: number, to: number): Array<HistoryEntry>
+  /** Slots of `address` written in `block`. */
+  changedSlots(address: string, block: number): Array<string>
+  /** Prove a never-changed slot at the archive head (lazy bootstrap). */
+  bootstrapSlot(rpcUrl: string, address: string, slot: string, backupRpc?: string | undefined | null): Promise<void>
+}
+
+/** A parsed solc storage layout. */
+export declare class Layout {
+  /** From a solc storageLayout JSON string or a whole forge/hardhat artifact. */
+  static fromJson(json: string): Layout
+  /** From a file containing either of the above. */
+  static fromFile(path: string): Layout
+  /** Resolve `totals.index`, `balances[0xabc…]`, `items[2]`, `items.length`. */
+  locate(path: string): Location
+  /**
+   * Decode a 32-byte word at a location. Returns the value as a string
+   * (decimal for integers, "true"/"false", 0x-address, or the raw word).
+   */
+  decode(location: Location, wordHex: string): string
+  /** Every named field living in a raw slot (mapping entries excluded — keccak is one-way). */
+  describeSlot(slot: string): Array<NamedLocation>
+  /** Top-level variable names in declaration order. */
+  fields(): Array<string>
+  /**
+   * What a path names: "value:<uint|int|bool|address|bytes|raw>", "struct",
+   * "mapping", "array" or "fixedArray". Drives the `view` proxy in lib.js.
+   */
+  kindOf(path: string): string
+  /**
+   * Decode a word and say what the text is, so JS can turn it into
+   * `bigint` / `boolean` / `string` without guessing.
+   */
+  decodeValue(location: Location, wordHex: string): DecodedValue
+  /** TypeScript interface for this layout as the `view` proxy exposes it. */
+  typescript(name: string): string
+}
+
+/** Options for `Archive.open`. */
+export interface ArchiveOptions {
+  /**
+   * Blocks behind head the node still serves eth_getProof
+   * (reth: `--rpc.eth-proof-window`). Default 120.
+   */
+  proofWindow?: number
+  /** Store every intra-block change instead of the last one. Fixed at creation. */
+  fullDetail?: boolean
+  /** Apply blocks without a BAL hash in the header. Debug only. */
+  allowUnverified?: boolean
+}
+
+/** A decoded word with its kind. */
+export interface DecodedValue {
+  /** "uint" | "int" | "bool" | "address" | "bytes" | "raw" */
+  kind: string
+  /** Decimal for integers, "true"/"false", 0x-hex for addresses/bytes/raw. */
+  text: string
+}
+
+/** Archive head. */
+export interface Head {
+  /** Last applied block. */
+  number: number
+  /** Its hash. */
+  hash: string
+}
+
+/** One recorded change. */
+export interface HistoryEntry {
+  /** Block of the change. */
+  block: number
+  /** Position within the block. */
+  index: number
+  /** 0x-prefixed 32-byte post-value. */
+  value: string
+  /** "bal" for entries inside a valid range. */
+  provenance: string
+}
+
+/** Where a value lives. */
+export interface Location {
+  /** 0x-prefixed storage slot. */
+  slot: string
+  /** Byte offset from the low-order end of the word. */
+  offset: number
+  /** Size in bytes. */
+  size: number
+  /** solc type id, e.g. `t_uint128`. */
+  typeId: string
+}
+
+/** A field name with its location. */
+export interface NamedLocation {
+  /** Path such as `totals.index` or `items[3]`. */
+  name: string
+  /** Where it lives. */
+  location: Location
+}
+
+/** A stored word with its provenance. */
+export interface StorageValue {
+  /** 0x-prefixed 32-byte word. */
+  value: string
+  /** "bal" | "proof" | "imported" | "unverified" */
+  provenance: string
+  /** Block at which this value was set (watch start - 1 for proven pre-values). */
+  setAt: number
+  /** Position within `setAt`. */
+  index: number
+}
+
+/** What one `sync()` did. */
+export interface SyncReport {
+  /** First block this pass tried to apply. */
+  from?: number
+  /** Last block applied. */
+  to?: number
+  /** Blocks applied. */
+  blocksApplied: number
+  /** Fork point, if a reorg was rolled back. */
+  reorgedTo?: number
+  /** Slot records written. */
+  slotsWritten: number
+  /** Pre-values proven in this pass. */
+  bootstrapped: number
+  /** Slots still awaiting a proof. */
+  bootstrapPending: number
+  /** Slots whose pre-value became unobtainable. */
+  bootstrapLost: number
+  /** Blocks applied without a BAL hash (debug only). */
+  unverifiedBlocks: number
+}
+
+/** One watchlist entry. */
+export interface WatchEntry {
+  /** Watched address. */
+  address: string
+  /** First block covered. */
+  from: number
+}

package/index.js

@@ -0,0 +1,704 @@
+// prettier-ignore
+/* eslint-disable */
+// @ts-nocheck
+/* auto-generated by NAPI-RS */
+
+const { readFileSync } = require('fs')
+let nativeBinding = null
+const loadErrors = []
+
+const isMusl = () => {
+  let musl = false
+  if (process.platform === 'linux') {
+    musl = isMuslFromFilesystem()
+    if (musl === null) {
+      musl = isMuslFromReport()
+    }
+    if (musl === null) {
+      musl = isMuslFromChildProcess()
+    }
+  }
+  return musl
+}
+
+const isFileMusl = (f) => f.includes('libc.musl-') || f.includes('ld-musl-')
+
+const isMuslFromFilesystem = () => {
+  try {
+    return readFileSync('/usr/bin/ldd', 'utf-8').includes('musl')
+  } catch {
+    return null
+  }
+}
+
+const isMuslFromReport = () => {
+  let report = null
+  if (process.report && typeof process.report.getReport === 'function') {
+    process.report.excludeNetwork = true
+    report = process.report.getReport()
+  }
+  if (!report) {
+    return null
+  }
+  if (report.header && report.header.glibcVersionRuntime) {
+    return false
+  }
+  if (Array.isArray(report.sharedObjects)) {
+    if (report.sharedObjects.some(isFileMusl)) {
+      return true
+    }
+  }
+  return false
+}
+
+const isMuslFromChildProcess = () => {
+  try {
+    return require('child_process').execSync('ldd --version', { encoding: 'utf8' }).includes('musl')
+  } catch (e) {
+    // If we reach this case, we don't know if the system is musl or not, so is better to just fallback to false
+    return false
+  }
+}
+
+function requireNative() {
+  if (process.env.NAPI_RS_NATIVE_LIBRARY_PATH) {
+    try {
+      return require(process.env.NAPI_RS_NATIVE_LIBRARY_PATH);
+    } catch (err) {
+      loadErrors.push(err)
+    }
+  } else if (process.platform === 'android') {
+    if (process.arch === 'arm64') {
+      try {
+        return require('./bal-node.android-arm64.node')
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      try {
+        const binding = require('balq-android-arm64')
+        const bindingPackageVersion = require('balq-android-arm64/package.json').version
+        if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
+      } catch (e) {
+        loadErrors.push(e)
+      }
+    } else if (process.arch === 'arm') {
+      try {
+        return require('./bal-node.android-arm-eabi.node')
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      try {
+        const binding = require('balq-android-arm-eabi')
+        const bindingPackageVersion = require('balq-android-arm-eabi/package.json').version
+        if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
+      } catch (e) {
+        loadErrors.push(e)
+      }
+    } else {
+      loadErrors.push(new Error(`Unsupported architecture on Android ${process.arch}`))
+    }
+  } else if (process.platform === 'win32') {
+    if (process.arch === 'x64') {
+      if ((process.config && process.config.variables && process.config.variables.shlib_suffix === 'dll.a') || (process.config && process.config.variables && process.config.variables.node_target_type === 'shared_library')) {
+        try {
+        return require('./bal-node.win32-x64-gnu.node')
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      try {
+        const binding = require('balq-win32-x64-gnu')
+        const bindingPackageVersion = require('balq-win32-x64-gnu/package.json').version
+        if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      } else {
+        try {
+        return require('./bal-node.win32-x64-msvc.node')
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      try {
+        const binding = require('balq-win32-x64-msvc')
+        const bindingPackageVersion = require('balq-win32-x64-msvc/package.json').version
+        if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      }
+    } else if (process.arch === 'ia32') {
+      try {
+        return require('./bal-node.win32-ia32-msvc.node')
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      try {
+        const binding = require('balq-win32-ia32-msvc')
+        const bindingPackageVersion = require('balq-win32-ia32-msvc/package.json').version
+        if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
+      } catch (e) {
+        loadErrors.push(e)
+      }
+    } else if (process.arch === 'arm64') {
+      try {
+        return require('./bal-node.win32-arm64-msvc.node')
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      try {
+        const binding = require('balq-win32-arm64-msvc')
+        const bindingPackageVersion = require('balq-win32-arm64-msvc/package.json').version
+        if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
+      } catch (e) {
+        loadErrors.push(e)
+      }
+    } else {
+      loadErrors.push(new Error(`Unsupported architecture on Windows: ${process.arch}`))
+    }
+  } else if (process.platform === 'darwin') {
+    try {
+      return require('./bal-node.darwin-universal.node')
+    } catch (e) {
+      loadErrors.push(e)
+    }
+    try {
+      const binding = require('balq-darwin-universal')
+      const bindingPackageVersion = require('balq-darwin-universal/package.json').version
+      if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+        throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+      }
+      return binding
+    } catch (e) {
+      loadErrors.push(e)
+    }
+    if (process.arch === 'x64') {
+      try {
+        return require('./bal-node.darwin-x64.node')
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      try {
+        const binding = require('balq-darwin-x64')
+        const bindingPackageVersion = require('balq-darwin-x64/package.json').version
+        if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
+      } catch (e) {
+        loadErrors.push(e)
+      }
+    } else if (process.arch === 'arm64') {
+      try {
+        return require('./bal-node.darwin-arm64.node')
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      try {
+        const binding = require('balq-darwin-arm64')
+        const bindingPackageVersion = require('balq-darwin-arm64/package.json').version
+        if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
+      } catch (e) {
+        loadErrors.push(e)
+      }
+    } else {
+      loadErrors.push(new Error(`Unsupported architecture on macOS: ${process.arch}`))
+    }
+  } else if (process.platform === 'freebsd') {
+    if (process.arch === 'x64') {
+      try {
+        return require('./bal-node.freebsd-x64.node')
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      try {
+        const binding = require('balq-freebsd-x64')
+        const bindingPackageVersion = require('balq-freebsd-x64/package.json').version
+        if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
+      } catch (e) {
+        loadErrors.push(e)
+      }
+    } else if (process.arch === 'arm64') {
+      try {
+        return require('./bal-node.freebsd-arm64.node')
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      try {
+        const binding = require('balq-freebsd-arm64')
+        const bindingPackageVersion = require('balq-freebsd-arm64/package.json').version
+        if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
+      } catch (e) {
+        loadErrors.push(e)
+      }
+    } else {
+      loadErrors.push(new Error(`Unsupported architecture on FreeBSD: ${process.arch}`))
+    }
+  } else if (process.platform === 'linux') {
+    if (process.arch === 'x64') {
+      if (isMusl()) {
+        try {
+          return require('./bal-node.linux-x64-musl.node')
+        } catch (e) {
+          loadErrors.push(e)
+        }
+        try {
+          const binding = require('balq-linux-x64-musl')
+          const bindingPackageVersion = require('balq-linux-x64-musl/package.json').version
+          if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
+        } catch (e) {
+          loadErrors.push(e)
+        }
+      } else {
+        try {
+          return require('./bal-node.linux-x64-gnu.node')
+        } catch (e) {
+          loadErrors.push(e)
+        }
+        try {
+          const binding = require('balq-linux-x64-gnu')
+          const bindingPackageVersion = require('balq-linux-x64-gnu/package.json').version
+          if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
+        } catch (e) {
+          loadErrors.push(e)
+        }
+      }
+    } else if (process.arch === 'arm64') {
+      if (isMusl()) {
+        try {
+          return require('./bal-node.linux-arm64-musl.node')
+        } catch (e) {
+          loadErrors.push(e)
+        }
+        try {
+          const binding = require('balq-linux-arm64-musl')
+          const bindingPackageVersion = require('balq-linux-arm64-musl/package.json').version
+          if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
+        } catch (e) {
+          loadErrors.push(e)
+        }
+      } else {
+        try {
+          return require('./bal-node.linux-arm64-gnu.node')
+        } catch (e) {
+          loadErrors.push(e)
+        }
+        try {
+          const binding = require('balq-linux-arm64-gnu')
+          const bindingPackageVersion = require('balq-linux-arm64-gnu/package.json').version
+          if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
+        } catch (e) {
+          loadErrors.push(e)
+        }
+      }
+    } else if (process.arch === 'arm') {
+      if (isMusl()) {
+        try {
+          return require('./bal-node.linux-arm-musleabihf.node')
+        } catch (e) {
+          loadErrors.push(e)
+        }
+        try {
+          const binding = require('balq-linux-arm-musleabihf')
+          const bindingPackageVersion = require('balq-linux-arm-musleabihf/package.json').version
+          if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
+        } catch (e) {
+          loadErrors.push(e)
+        }
+      } else {
+        try {
+          return require('./bal-node.linux-arm-gnueabihf.node')
+        } catch (e) {
+          loadErrors.push(e)
+        }
+        try {
+          const binding = require('balq-linux-arm-gnueabihf')
+          const bindingPackageVersion = require('balq-linux-arm-gnueabihf/package.json').version
+          if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
+        } catch (e) {
+          loadErrors.push(e)
+        }
+      }
+    } else if (process.arch === 'loong64') {
+      if (isMusl()) {
+        try {
+          return require('./bal-node.linux-loong64-musl.node')
+        } catch (e) {
+          loadErrors.push(e)
+        }
+        try {
+          const binding = require('balq-linux-loong64-musl')
+          const bindingPackageVersion = require('balq-linux-loong64-musl/package.json').version
+          if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
+        } catch (e) {
+          loadErrors.push(e)
+        }
+      } else {
+        try {
+          return require('./bal-node.linux-loong64-gnu.node')
+        } catch (e) {
+          loadErrors.push(e)
+        }
+        try {
+          const binding = require('balq-linux-loong64-gnu')
+          const bindingPackageVersion = require('balq-linux-loong64-gnu/package.json').version
+          if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
+        } catch (e) {
+          loadErrors.push(e)
+        }
+      }
+    } else if (process.arch === 'riscv64') {
+      if (isMusl()) {
+        try {
+          return require('./bal-node.linux-riscv64-musl.node')
+        } catch (e) {
+          loadErrors.push(e)
+        }
+        try {
+          const binding = require('balq-linux-riscv64-musl')
+          const bindingPackageVersion = require('balq-linux-riscv64-musl/package.json').version
+          if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
+        } catch (e) {
+          loadErrors.push(e)
+        }
+      } else {
+        try {
+          return require('./bal-node.linux-riscv64-gnu.node')
+        } catch (e) {
+          loadErrors.push(e)
+        }
+        try {
+          const binding = require('balq-linux-riscv64-gnu')
+          const bindingPackageVersion = require('balq-linux-riscv64-gnu/package.json').version
+          if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
+        } catch (e) {
+          loadErrors.push(e)
+        }
+      }
+    } else if (process.arch === 'ppc64') {
+      try {
+        return require('./bal-node.linux-ppc64-gnu.node')
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      try {
+        const binding = require('balq-linux-ppc64-gnu')
+        const bindingPackageVersion = require('balq-linux-ppc64-gnu/package.json').version
+        if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
+      } catch (e) {
+        loadErrors.push(e)
+      }
+    } else if (process.arch === 's390x') {
+      try {
+        return require('./bal-node.linux-s390x-gnu.node')
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      try {
+        const binding = require('balq-linux-s390x-gnu')
+        const bindingPackageVersion = require('balq-linux-s390x-gnu/package.json').version
+        if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
+      } catch (e) {
+        loadErrors.push(e)
+      }
+    } else {
+      loadErrors.push(new Error(`Unsupported architecture on Linux: ${process.arch}`))
+    }
+  } else if (process.platform === 'openharmony') {
+    if (process.arch === 'arm64') {
+      try {
+        return require('./bal-node.openharmony-arm64.node')
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      try {
+        const binding = require('balq-openharmony-arm64')
+        const bindingPackageVersion = require('balq-openharmony-arm64/package.json').version
+        if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
+      } catch (e) {
+        loadErrors.push(e)
+      }
+    } else if (process.arch === 'x64') {
+      try {
+        return require('./bal-node.openharmony-x64.node')
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      try {
+        const binding = require('balq-openharmony-x64')
+        const bindingPackageVersion = require('balq-openharmony-x64/package.json').version
+        if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
+      } catch (e) {
+        loadErrors.push(e)
+      }
+    } else if (process.arch === 'arm') {
+      try {
+        return require('./bal-node.openharmony-arm.node')
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      try {
+        const binding = require('balq-openharmony-arm')
+        const bindingPackageVersion = require('balq-openharmony-arm/package.json').version
+        if (bindingPackageVersion !== '0.1.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
+      } catch (e) {
+        loadErrors.push(e)
+      }
+    } else {
+      loadErrors.push(new Error(`Unsupported architecture on OpenHarmony: ${process.arch}`))
+    }
+  } else {
+    loadErrors.push(new Error(`Unsupported OS: ${process.platform}, architecture: ${process.arch}`))
+  }
+}
+
+function createLoadErrorChain(errors) {
+  return errors.reduce((previous, current) => {
+    let message
+    try {
+      message =
+        current && typeof current.message === 'string'
+          ? current.message
+          : String(current)
+    } catch {
+      message = 'Unknown error'
+    }
+    const error = new Error(message)
+    error.cause = previous
+    return error
+  }, null)
+}
+
+// NAPI_RS_FORCE_WASI is a tri-state flag:
+//   unset / any other value → native binding preferred, WASI is only a fallback
+//   'true'                   → prefer WASI, but retain native as a lazy fallback
+//   'error'                  → require WASI without initializing a native fallback
+// Treating any non-empty string as truthy (the historical behavior) meant
+// NAPI_RS_FORCE_WASI=false, NAPI_RS_FORCE_WASI=0, etc. inadvertently triggered
+// the WASI path, causing ENOENT for packages shipped without a .wasi.cjs file.
+//
+// NAPI_RS_WASI_FLAVOR selects one exact generated flavor and implies strict
+// WASI loading. It never crosses into another flavor or falls back to native.
+const __napiWasiFlavors = ["wasm32-wasi"]
+const __napiWasiFlavor = process.env.NAPI_RS_WASI_FLAVOR
+const __napiWasiFlavorRequested =
+  typeof __napiWasiFlavor === 'string' && __napiWasiFlavor.length > 0
+if (
+  __napiWasiFlavorRequested &&
+  __napiWasiFlavors.indexOf(__napiWasiFlavor) === -1
+) {
+  throw new Error(
+    'Unsupported WASI flavor "' +
+      __napiWasiFlavor +
+      '". Available flavors: ' +
+      __napiWasiFlavors.join(', '),
+  )
+}
+const forceWasiError = process.env.NAPI_RS_FORCE_WASI === 'error'
+const forceWasi =
+  process.env.NAPI_RS_FORCE_WASI === 'true' ||
+  forceWasiError ||
+  __napiWasiFlavorRequested
+
+if (!forceWasi) {
+  nativeBinding = requireNative()
+}
+
+if (!nativeBinding || forceWasi) {
+  let wasiBinding = null
+  let wasiBindingLoaded = false
+  const wasiBindingErrors = []
+  const __napiWasiResolveCandidate = (specifier, isPackage, localArtifacts) => {
+    try {
+      require.resolve(specifier)
+    } catch (resolveError) {
+      if (!resolveError || resolveError.code !== 'MODULE_NOT_FOUND') {
+        throw resolveError
+      }
+      if (isPackage) {
+        try {
+          require.resolve(specifier + '/package.json')
+        } catch (packageError) {
+          if (packageError && packageError.code === 'MODULE_NOT_FOUND') {
+            return resolveError
+          }
+          // An exports restriction proves the package exists even when its
+          // package.json is not public. Preserve the root resolution failure.
+          throw resolveError
+        }
+        // The package exists but its main/export target is broken.
+        throw resolveError
+      }
+      return resolveError
+    }
+    if (localArtifacts) {
+      let artifactError = null
+      for (let i = 0; i < localArtifacts.length; i++) {
+        try {
+          require.resolve(localArtifacts[i])
+          return null
+        } catch (resolveError) {
+          if (!resolveError || resolveError.code !== 'MODULE_NOT_FOUND') {
+            throw resolveError
+          }
+          artifactError = resolveError
+        }
+      }
+      return artifactError
+    }
+    return null
+  }
+  if (!wasiBindingLoaded && (!__napiWasiFlavorRequested || __napiWasiFlavor === "wasm32-wasi")) {
+    let candidateError = null
+    let candidateFailed = false
+    try {
+      candidateError = __napiWasiResolveCandidate('./bal-node.wasi.cjs', false, ["./bal-node.wasm32-wasi.debug.wasm","./bal-node.wasm32-wasi.wasm"])
+      candidateFailed = candidateError !== null
+      if (!candidateFailed) {
+        wasiBinding = require('./bal-node.wasi.cjs')
+        nativeBinding = wasiBinding
+        wasiBindingLoaded = true
+      }
+    } catch (err) {
+      candidateError = err
+      candidateFailed = true
+    }
+    if (candidateFailed) {
+      wasiBindingErrors.push(candidateError)
+      loadErrors.push(candidateError)
+    }
+  }
+  if (!wasiBindingLoaded && (!__napiWasiFlavorRequested || __napiWasiFlavor === "wasm32-wasi")) {
+    let candidateError = null
+    let candidateFailed = false
+    try {
+      candidateError = __napiWasiResolveCandidate('balq-wasm32-wasi', true, undefined)
+      candidateFailed = candidateError !== null
+      if (!candidateFailed) {
+        if (process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          const bindingPackageVersion = require('balq-wasm32-wasi/package.json').version
+          if (bindingPackageVersion !== '0.1.1') {
+            throw new Error(`WASI binding package version mismatch, expected 0.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+        }
+        wasiBinding = require('balq-wasm32-wasi')
+        nativeBinding = wasiBinding
+        wasiBindingLoaded = true
+      }
+    } catch (err) {
+      candidateError = err
+      candidateFailed = true
+    }
+    if (candidateFailed) {
+      wasiBindingErrors.push(candidateError)
+      loadErrors.push(candidateError)
+    }
+  }
+  if (
+    !wasiBindingLoaded &&
+    forceWasi &&
+    !forceWasiError &&
+    !__napiWasiFlavorRequested
+  ) {
+    nativeBinding = requireNative()
+  }
+  if ((forceWasiError || __napiWasiFlavorRequested) && !wasiBindingLoaded) {
+    const error = new Error(
+      __napiWasiFlavorRequested
+        ? 'WASI binding for flavor "' + __napiWasiFlavor + '" not found'
+        : 'WASI binding not found and NAPI_RS_FORCE_WASI is set to error',
+    )
+    error.cause = createLoadErrorChain(wasiBindingErrors)
+    throw error
+  }
+}
+
+if (!nativeBinding) {
+  if (loadErrors.length > 0) {
+    const error = new Error(
+      `Cannot find native binding. ` +
+        `npm has a bug related to optional dependencies (https://github.com/npm/cli/issues/4828). ` +
+        'Please try `npm i` again after removing both package-lock.json and node_modules directory.',
+    )
+    // assign instead of the `new Error(message, { cause })` options form,
+    // which Node < 16.9 silently ignores
+    error.cause = createLoadErrorChain(loadErrors)
+    throw error
+  }
+  throw new Error(`Failed to load native binding`)
+}
+
+module.exports = nativeBinding
+module.exports.Archive = nativeBinding.Archive
+module.exports.Layout = nativeBinding.Layout

package/lib.d.ts

@@ -0,0 +1,36 @@
+export * from "./index";
+import { Archive as NativeArchive, Layout } from "./index";
+
+/** Thrown by reads when there is no value — never `null`. */
+export class NotAvailableError extends Error {
+  name: "NotAvailableError";
+  code:
+    | "NotWatched"
+    | "BeforeStart"
+    | "AfterHead"
+    | "NotSynced"
+    | "InvalidRange"
+    | "NotBootstrapped"
+    | "BootstrapPending"
+    | "BootstrapLost"
+    | "Internal";
+}
+
+/**
+ * Storage of one contract at one block, read by variable name.
+ * Generate a precise type with `balq typegen <layout> --name MyContractView`
+ * (or `layout.typescript("MyContractView")`) and pass it as `T`.
+ */
+export type StorageView<T = any> = T;
+
+export interface ContractView {
+  /** Variables of the contract at the end of `block`. */
+  at<T = any>(block: number): StorageView<T>;
+}
+
+declare module "./index" {
+  interface Archive {
+    /** Read storage by name through a solc layout; see `at()`. */
+    view(address: string, layout: Layout): ContractView;
+  }
+}

package/lib.js

@@ -0,0 +1,119 @@
+// Thin wrapper over the generated `index.js`:
+//  - turns `[NotAvailable:Code] …` errors from Rust into `NotAvailableError`
+//    with a `.code`;
+//  - adds `archive.view(address, layout).at(block)`, a proxy that reads the
+//    contract's variables by name, the way they are written in Solidity.
+// No archive or layout logic lives here; every read goes through the native
+// `locate` / `kindOf` / `storageAt` / `decodeValue`.
+
+const native = require("./index.js");
+
+class NotAvailableError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = "NotAvailableError";
+    this.code = code;
+  }
+}
+
+const RE = /^\[NotAvailable:([A-Za-z]+)\] (.*)$/s;
+
+function convert(e) {
+  const m = typeof e?.message === "string" && RE.exec(e.message);
+  return m ? new NotAvailableError(m[1], m[2]) : e;
+}
+
+function wrap(obj, names) {
+  for (const n of names) {
+    const orig = obj[n];
+    obj[n] = function (...args) {
+      try {
+        const r = orig.apply(this, args);
+        return r instanceof Promise ? r.catch((e) => { throw convert(e); }) : r;
+      } catch (e) {
+        throw convert(e);
+      }
+    };
+  }
+}
+
+wrap(native.Archive.prototype, ["storageAt", "history", "changedSlots", "sync", "bootstrapSlot"]);
+
+// ---- view -----------------------------------------------------------------
+
+function toJs(decoded) {
+  switch (decoded.kind) {
+    case "uint":
+    case "int":
+      return BigInt(decoded.text);
+    case "bool":
+      return decoded.text === "true";
+    default:
+      return decoded.text; // address, bytes, raw: 0x-hex
+  }
+}
+
+// Properties JS itself probes on any object; never storage fields.
+const PASSTHROUGH = new Set(["then", "toJSON", "constructor", "valueOf", "toString", "inspect"]);
+
+function readLeaf(archive, address, layout, block, path) {
+  const loc = layout.locate(path);
+  const v = archive.storageAt(address, loc.slot, block);
+  return toJs(layout.decodeValue(loc, v.value));
+}
+
+/**
+ * A proxy for the container at `path` ("" = the contract itself).
+ * Property access extends the path according to the container's kind and
+ * either descends (struct / mapping / array) or reads a leaf value.
+ */
+function container(archive, address, layout, block, path, kind) {
+  const extend = (prop) => {
+    if (kind === "struct" || kind === "") return path ? `${path}.${prop}` : prop;
+    if (kind === "array" && prop === "length") return `${path}.length`;
+    return `${path}[${prop}]`; // mapping, array, fixedArray
+  };
+  return new Proxy(Object.create(null), {
+    get(_, prop) {
+      if (typeof prop === "symbol" || PASSTHROUGH.has(prop)) return undefined;
+      const next = extend(String(prop));
+      const k = layout.kindOf(next); // throws for unknown fields
+      if (k.startsWith("value:")) return readLeaf(archive, address, layout, block, next);
+      return container(archive, address, layout, block, next, k);
+    },
+    has(_, prop) {
+      if (typeof prop === "symbol") return false;
+      try {
+        layout.kindOf(extend(String(prop)));
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    ownKeys() {
+      return kind === "" || !path ? layout.fields() : [];
+    },
+    getOwnPropertyDescriptor(_, prop) {
+      return { enumerable: true, configurable: true, value: undefined };
+    },
+  });
+}
+
+/**
+ * `archive.view(address, layout)` → `{ at(block) }`.
+ * `at(block)` returns an object whose properties are the contract's storage
+ * variables at the end of `block`: `view.counter`, `view.balances[addr]`,
+ * `view.totals.index`, `view.items[3]`, `view.items.length`.
+ * Integers are `bigint`, bools `boolean`, addresses/bytes/raw words `string`.
+ * A missing value throws `NotAvailableError` — never `undefined`.
+ */
+native.Archive.prototype.view = function (address, layout) {
+  const archive = this;
+  return {
+    at(block) {
+      return container(archive, address, layout, block, "", "");
+    },
+  };
+};
+
+module.exports = { ...native, NotAvailableError };

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@balq/node",
+  "version": "0.1.1",
+  "description": "Local, verified archive of contract storage built from EIP-7928 BALs — Node.js bindings",
+  "main": "lib.js",
+  "types": "lib.d.ts",
+  "license": "MIT OR Apache-2.0",
+  "files": [
+    "lib.js",
+    "lib.d.ts",
+    "index.js",
+    "index.d.ts"
+  ],
+  "napi": {
+    "binaryName": "bal-node",
+    "targets": [
+      "x86_64-pc-windows-msvc",
+      "x86_64-unknown-linux-gnu",
+      "aarch64-unknown-linux-gnu",
+      "x86_64-apple-darwin",
+      "aarch64-apple-darwin"
+    ]
+  },
+  "engines": {
+    "node": ">= 18"
+  },
+  "scripts": {
+    "build": "napi build --release --platform",
+    "build:debug": "napi build --platform",
+    "test": "node test/smoke.mjs"
+  },
+  "devDependencies": {
+    "@napi-rs/cli": "^3"
+  },
+  "optionalDependencies": {
+    "@balq/node-win32-x64-msvc": "0.1.1",
+    "@balq/node-linux-x64-gnu": "0.1.1",
+    "@balq/node-linux-arm64-gnu": "0.1.1",
+    "@balq/node-darwin-x64": "0.1.1",
+    "@balq/node-darwin-arm64": "0.1.1"
+  }
+}