@rolly-dev/witness-core 0.1.0

package/README.md

@@ -0,0 +1,80 @@
+# @rolly-dev/witness-core
+
+Authoritative native witness-state engine for the Rolly ZK-Rollup, shipped to
+Node.js as a [Node-API](https://nodejs.org/api/n-api.html) addon via
+[napi-rs](https://napi.rs).
+
+It is the single source of truth for the rollup witness state (Merkle tree,
+server-seed chain, TL) and processes each transaction **exactly once**. Node
+keeps only IO / RPC / orchestration. See the migration plan for the full
+rationale (removing the TS/Rust double-recompute and the wasm Poseidon
+bottleneck).
+
+> Status: **scaffolding stage**. The Node-API surface and a placeholder
+> `MerkleEngine` handle exist; the real state, `process_tx`, and `flush_block`
+> land in later stages.
+
+## Design
+
+One crate, `crate-type = ["cdylib", "rlib"]` with napi bindings inline (no
+separate binding crate), mirroring how `wasm-signer` ships `cdylib` + `rlib`:
+
+- `cdylib` -> the `.node` addon consumed by the backend.
+- `rlib`   -> native unit tests + (later) circuit differential tests live in
+  this same crate, so engine logic is testable without going through Node.
+
+## Build
+
+Host platform (release):
+
+```bash
+npm install     # installs @napi-rs/cli
+npm run build   # -> witness-core.<platform>.node, index.js, index.d.ts
+```
+
+or `bash build.sh`.
+
+### Prebuild for Linux x64 (production target)
+
+Production likely runs Linux x64, so the package is configured to emit a
+`x86_64-unknown-linux-gnu` artifact:
+
+```bash
+npm run build:linux-x64
+```
+
+Cross-compiling from macOS requires a Linux linker and the Rust target:
+
+```bash
+rustup target add x86_64-unknown-linux-gnu
+```
+
+Then pick one of:
+
+- **GNU cross-linker (used here):** install the GNU cross toolchain so
+  `x86_64-linux-gnu-gcc` is on `PATH`. `.cargo/config.toml` already points the
+  target's linker at it, so `npm run build:linux-x64` produces a stripped
+  `witness-core.linux-x64-gnu.node` ELF directly.
+- **Linux x64 CI runner:** run `npm run build:linux-x64` there natively
+  (`.cargo/config.toml`'s cross-linker entry is simply unused). Recommended for
+  release.
+- **zig:** `cargo install cargo-zigbuild` + a `zig` on `PATH`, then add
+  `--cross-compile` to the napi build.
+
+The release flow uses `napi prepublish` / `napi artifacts` to collect the
+per-platform `.node` files before publishing.
+
+## Test
+
+```bash
+npm test   # builds nothing; runs ./test.js against the already-built addon
+```
+
+## Consuming from the backend
+
+Same pattern as `@rolly-dev/wasm-signer`:
+
+```js
+const { MerkleEngine, engineVersion } = require('@rolly-dev/witness-core');
+const engine = new MerkleEngine();
+```

package/index.d.ts

@@ -0,0 +1,318 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/* auto-generated by NAPI-RS */
+
+/** Caller-tunable flush inputs. */
+export interface FlushOptions {
+  /**
+   * Block timestamp (unix seconds, decimal string). Defaults to `now - 10`,
+   * mirroring the engine's safety margin under the contract's upper bound.
+   */
+  blockTimestamp?: string
+  /**
+   * When true, the per-batch delta tree is reset AFTER this block (the batch
+   * boundary). Defaults to false (mid-batch).
+   */
+  closeBatch?: boolean
+}
+/**
+ * Block-level result of a flush. Monetary / root values are little-endian
+ * `Buffer`s or decimal `BigInt`s. `witness_json` is the prover input; the
+ * `*_json` strings are the block-pubdata records Node stores on the pipeline
+ * block doc; `ops_data_hex` is the raw withdrawal calldata. After awaiting
+ * this and persisting, Node MUST call `commit_flush` (or `rollback_flush` on
+ * persist failure) to finalize / undo the engine's running flush state.
+ */
+export interface FlushResult {
+  blockId: bigint
+  txCount: number
+  depositCount: number
+  hasDeposit: boolean
+  hasWithdrawal: boolean
+  oldRoot: Buffer
+  newRoot: Buffer
+  tl: bigint
+  multisetOld: Buffer
+  multisetNew: Buffer
+  oldDepositChainHash: Buffer
+  newDepositChainHash: Buffer
+  oldOpsHash: Buffer
+  newOpsHash: Buffer
+  opsDataHex: string
+  blockTimestamp: bigint
+  witnessJson: string
+  deltasJson: string
+  addressRecordsJson: string
+  pkHashRecordsJson: string
+}
+/**
+ * Result of [`MerkleEngine::verify_root`], surfaced to Node for the post-load
+ * integrity check.
+ */
+export interface VerifyRootResult {
+  valid: boolean
+  computed: Buffer
+  stored: Buffer
+}
+/** One dirty user leaf (32-byte little-endian hash). */
+export interface DirtyLeaf {
+  userId: number
+  leaf: Buffer
+}
+/** One dirty internal node (`level:index` key + 32-byte hash). */
+export interface DirtyNode {
+  level: number
+  index: number
+  hash: Buffer
+}
+/** One dirty raw balance leaf (56-byte little-endian, 7 limbs). */
+export interface DirtyRaw {
+  userId: number
+  raw: Buffer
+}
+/** One dirty 32-byte hash field (pk / address). */
+export interface DirtyHash {
+  userId: number
+  hash: Buffer
+}
+/** One dirty locked-balance entry (frozen buckets, NOT in the leaf hash). */
+export interface DirtyLocked {
+  userId: number
+  wd: bigint
+  game: bigint
+}
+/** One dirty full server seed (64-byte little-endian, 8 limbs). */
+export interface DirtySeed {
+  userId: number
+  seed: Buffer
+}
+/**
+ * Snapshot of everything changed since the last flush, for Node to upsert to
+ * Mongo (merkle leaves / nodes / raws / pk / address / locked + server seeds).
+ * Values are little-endian buffers; locked buckets are decimal `BigInt`s.
+ */
+export interface DirtyData {
+  leaves: Array<DirtyLeaf>
+  nodes: Array<DirtyNode>
+  balanceRaws: Array<DirtyRaw>
+  pkHashes: Array<DirtyHash>
+  addressHashes: Array<DirtyHash>
+  lockedBalances: Array<DirtyLocked>
+  serverSeeds: Array<DirtySeed>
+}
+/**
+ * Per-tx request from Node. Opaque field groups arrive as little-endian
+ * `Buffer`s (`session_key` / `new_pk_hash` / `user_secret_random` = 32 bytes =
+ * 4 limbs; `user_address` = 20 bytes); monetary values arrive as decimal
+ * strings to dodge JS `Number` precision and `BigInt`-in-object quirks. Node
+ * keeps all hex/string parsing (incl. deriving `user_secret_random` from the
+ * raw user-seed source via wasm-signer); the engine takes only parsed bytes.
+ */
+export interface ProcessTxRequest {
+  txType: number
+  userId: number
+  amount: string
+  winAmount?: string
+  userAddress?: Buffer
+  sessionKey?: Buffer
+  sessionExpiry?: string
+  newPkHash?: Buffer
+  gameId?: number
+  gameMode?: number
+  predictionLo?: number
+  predictionHi?: number
+  userSecretRandom?: Buffer
+  useGameLock?: boolean
+  maxBlockTimestamp?: string
+}
+/**
+ * Authoritative post-tx result returned to Node. Monetary values are decimal
+ * strings; field-element groups are little-endian hex (`random` / `user_seed`
+ * = 32 hex-encoded bytes, `next_seed_hash` = 24, `server_seed` = 64). The
+ * rejected case is surfaced as a thrown error carrying the typed reason.
+ */
+export interface ProcessTxResult {
+  newBalance: string
+  available: string
+  newCredit: string
+  winAmount: string
+  random?: string
+  nextSeedHash?: string
+  /**
+   * Pre-tx leaf seed hash (24 little-endian hex). Persisted by Node as the
+   * block-explorer `server_seed_hash`. `None` only when all-zero.
+   */
+  oldSeedHash?: string
+  serverSeed?: string
+  userSeedHex?: string
+  gameResultJson?: string
+}
+/**
+ * Returns the native engine version. Lets the Node layer verify the loaded
+ * addon matches the expected npm package version at startup.
+ */
+export declare function engineVersion(): string
+/**
+ * Authoritative witness-state engine handle held on the Node side. Owns the
+ * Merkle tree, the TL accumulator and the per-user server-seed chain in native
+ * memory (no V8 GC, no wasm 4 GB ceiling), plus the in-progress block's slot
+ * buffer. Node drives it via this Node-API surface.
+ */
+export declare class MerkleEngine {
+  /**
+   * Close the in-progress block: drain the buffered slots, pad with noops,
+   * fold the multiset / deposit / ops chains and per-batch delta tree, and
+   * (off the event loop) serialize + gzip the block witness / write-set.
+   * Resolves to a [`FlushResult`].
+   */
+  flushBlock(options?: FlushOptions | undefined | null): Promise<unknown>
+  /**
+   * Finalize a pending flush after Node has durably persisted the block
+   * (Mongo merkle + meta + CH + pipeline). Accepts the delta-tree mutations
+   * and, at a batch boundary (`close_batch`), resets the per-batch delta
+   * tree. No-op when no flush is pending.
+   */
+  commitFlush(): void
+  /**
+   * Undo a pending flush when the durable persist failed: restore the running
+   * accumulators / block-open tracking, re-buffer the block's real slots at
+   * the front of the queue (so they re-flush as the same block), and roll the
+   * per-batch delta tree back. No-op when no flush is pending.
+   */
+  rollbackFlush(): void
+  /** True iff a flush is awaiting commit / rollback. */
+  hasPendingFlush(): boolean
+  /**
+   * Per-batch pubdata delta entries (one per touched user) as the JSON the
+   * `pipeline_batches.delta_entries` field stores. Call at batch close
+   * BEFORE `reset_delta_tree`.
+   */
+  deltaExportEntriesJson(): string
+  /** Estimated raw delta-entry calldata size (bytes) for the open batch. */
+  deltaEstimatePubdataBytes(): bigint
+  /** Number of touched users in the open batch (= number of pubdata entries). */
+  deltaEntryCount(): number
+  getBlockId(): bigint
+  /** Adopt the persisted block id (startup / recovery). */
+  setBlockId(blockId: bigint): void
+  /** Running multiset accumulator as a 32-byte little-endian buffer. */
+  getMultiset(): Buffer
+  setMultiset(multiset: Buffer): void
+  getDepositChain(): Buffer
+  setDepositChain(chain: Buffer): void
+  getOpsHash(): Buffer
+  setOpsHash(opsHash: Buffer): void
+  /** Current per-batch delta-tree root (32-byte little-endian buffer). */
+  getDeltaRoot(): Buffer
+  /** Reset the per-batch delta tree to empty (the batch boundary). */
+  resetDeltaTree(): void
+  /**
+   * Replay one already-persisted block's slots into the per-batch delta tree
+   * (startup recovery of an open batch). Parses the block `witness_json` and
+   * advances the delta tree by each non-noop slot, so the next block's
+   * `old_delta_root` continues the batch exactly where the pre-restart run
+   * left off. Must be called in block order, after `reset_delta_tree`.
+   */
+  replayDeltaBlock(witnessJson: string): void
+  /**
+   * Creates an empty engine (all-empty root, zero TL). Startup then streams
+   * in the persisted tree via the `load*` methods + `set_root`.
+   */
+  constructor()
+  loadLeaf(userId: number, leaf: Buffer): void
+  loadNode(level: number, nodeIndex: number, hash: Buffer): void
+  loadBalanceLeafRaw(userId: number, raw: Buffer): void
+  loadPkHash(userId: number, pkHash: Buffer): void
+  loadAddressHash(userId: number, addressHash: Buffer): void
+  loadLockedBalance(userId: number, wd: bigint, game: bigint): void
+  /**
+   * Load a persisted full server seed for `user_id` (startup / recovery). Not
+   * marked dirty — the loaded value already matches the store.
+   */
+  loadServerSeed(userId: number, seed: Buffer): void
+  /**
+   * Adopt the persisted block-meta root after the full tree is loaded. The
+   * loaded leaves/nodes must reproduce it — verify with [`Self::verify_root`].
+   */
+  setRoot(root: Buffer): void
+  /** Adopt the persisted total liability from block meta. */
+  setTl(tl: bigint): void
+  /**
+   * Rebuild every internal node from the leaves and refresh the root. Used in
+   * recovery when persisted nodes are missing or suspect.
+   */
+  rebuildNodesFromLeaves(): void
+  /**
+   * Recompute the root bottom-up and compare against the cached one — the
+   * post-load integrity check.
+   */
+  verifyRoot(): VerifyRootResult
+  getRoot(): Buffer
+  getTl(): bigint
+  getBalance(userId: number): bigint
+  getCredit(userId: number): bigint
+  /** Spendable balance minus all frozen buckets (withdrawal + game locks). */
+  getAvailable(userId: number): bigint
+  getSeedHash(userId: number): Buffer
+  getPkHash(userId: number): Buffer
+  getAddressHash(userId: number): Buffer
+  getLockedTotal(userId: number): bigint
+  getLocked(userId: number, purpose: number): bigint
+  hasLeaf(userId: number): boolean
+  leafCount(): number
+  nodeCount(): number
+  /** Freeze `amount` more in a bucket. Errors on u64 overflow. */
+  lockBalance(userId: number, purpose: number, amount: bigint): void
+  /** Release `amount` from a bucket. Errors if it would go negative. */
+  unlockBalance(userId: number, purpose: number, amount: bigint): void
+  /** Set a bucket's absolute frozen amount. */
+  setLockedBalance(userId: number, purpose: number, locked: bigint): void
+  addTl(amount: bigint): void
+  subTl(amount: bigint): void
+  dirtyLeafCount(): number
+  dirtyNodeCount(): number
+  dirtyServerSeedCount(): number
+  /** Number of slot witnesses buffered for the in-progress block. */
+  bufferedSlotCount(): number
+  /**
+   * True iff a full server seed is loaded for `user_id` (needed before any
+   * `in_house_bet` on that user).
+   */
+  hasServerSeed(userId: number): boolean
+  clearDirty(): void
+  /**
+   * Snapshot the dirty merkle state + dirty server seeds for Node to persist.
+   * Does NOT clear the dirty markers — Node calls `clear_dirty` after a
+   * successful flush and `restore_dirty` on persist failure.
+   */
+  collectDirty(): DirtyData
+  /**
+   * Re-mark the keys in `dirty` as dirty after a failed flush (values stay
+   * the live post-block ones), so the next flush re-persists them. Buffer
+   * payloads are ignored — only the ids matter.
+   */
+  restoreDirty(dirty: DirtyData): void
+  dirtyLockedBalanceCount(): number
+  /**
+   * Snapshot the dirty locked buckets (fully-unlocked users emit zeros).
+   * Does NOT clear — call `clear_dirty_locked_balances` after persisting.
+   */
+  collectDirtyLockedBalances(): Array<DirtyLocked>
+  clearDirtyLockedBalances(): void
+  restoreDirtyLockedBalances(userIds: Array<number>): void
+  /**
+   * One-line status string (root, TL, leaf/node counts, dirty counts) for
+   * startup logging and health checks.
+   */
+  getStatus(): string
+  /**
+   * Process one transaction against live state: snapshot the leaf, generate
+   * any fairness fields, run the differentially-tested validator (the single
+   * compute + validation pass), apply the returned effects to the tree / TL /
+   * server-seed chain, and buffer the slot. Returns the authoritative post-tx
+   * result, or throws with the typed rejection reason (the slot never
+   * mutates state on rejection).
+   */
+  processTx(req: ProcessTxRequest): ProcessTxResult
+}

package/index.js

@@ -0,0 +1,316 @@
+/* tslint:disable */
+/* eslint-disable */
+/* prettier-ignore */
+
+/* auto-generated by NAPI-RS */
+
+const { existsSync, readFileSync } = require('fs')
+const { join } = require('path')
+
+const { platform, arch } = process
+
+let nativeBinding = null
+let localFileExisted = false
+let loadError = null
+
+function isMusl() {
+  // For Node 10
+  if (!process.report || typeof process.report.getReport !== 'function') {
+    try {
+      const lddPath = require('child_process').execSync('which ldd').toString().trim()
+      return readFileSync(lddPath, 'utf8').includes('musl')
+    } catch (e) {
+      return true
+    }
+  } else {
+    const { glibcVersionRuntime } = process.report.getReport().header
+    return !glibcVersionRuntime
+  }
+}
+
+switch (platform) {
+  case 'android':
+    switch (arch) {
+      case 'arm64':
+        localFileExisted = existsSync(join(__dirname, 'witness-core.android-arm64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./witness-core.android-arm64.node')
+          } else {
+            nativeBinding = require('@rolly-dev/witness-core-android-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm':
+        localFileExisted = existsSync(join(__dirname, 'witness-core.android-arm-eabi.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./witness-core.android-arm-eabi.node')
+          } else {
+            nativeBinding = require('@rolly-dev/witness-core-android-arm-eabi')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Android ${arch}`)
+    }
+    break
+  case 'win32':
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(
+          join(__dirname, 'witness-core.win32-x64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./witness-core.win32-x64-msvc.node')
+          } else {
+            nativeBinding = require('@rolly-dev/witness-core-win32-x64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'ia32':
+        localFileExisted = existsSync(
+          join(__dirname, 'witness-core.win32-ia32-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./witness-core.win32-ia32-msvc.node')
+          } else {
+            nativeBinding = require('@rolly-dev/witness-core-win32-ia32-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'witness-core.win32-arm64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./witness-core.win32-arm64-msvc.node')
+          } else {
+            nativeBinding = require('@rolly-dev/witness-core-win32-arm64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Windows: ${arch}`)
+    }
+    break
+  case 'darwin':
+    localFileExisted = existsSync(join(__dirname, 'witness-core.darwin-universal.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./witness-core.darwin-universal.node')
+      } else {
+        nativeBinding = require('@rolly-dev/witness-core-darwin-universal')
+      }
+      break
+    } catch {}
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(join(__dirname, 'witness-core.darwin-x64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./witness-core.darwin-x64.node')
+          } else {
+            nativeBinding = require('@rolly-dev/witness-core-darwin-x64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'witness-core.darwin-arm64.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./witness-core.darwin-arm64.node')
+          } else {
+            nativeBinding = require('@rolly-dev/witness-core-darwin-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on macOS: ${arch}`)
+    }
+    break
+  case 'freebsd':
+    if (arch !== 'x64') {
+      throw new Error(`Unsupported architecture on FreeBSD: ${arch}`)
+    }
+    localFileExisted = existsSync(join(__dirname, 'witness-core.freebsd-x64.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./witness-core.freebsd-x64.node')
+      } else {
+        nativeBinding = require('@rolly-dev/witness-core-freebsd-x64')
+      }
+    } catch (e) {
+      loadError = e
+    }
+    break
+  case 'linux':
+    switch (arch) {
+      case 'x64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'witness-core.linux-x64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./witness-core.linux-x64-musl.node')
+            } else {
+              nativeBinding = require('@rolly-dev/witness-core-linux-x64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'witness-core.linux-x64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./witness-core.linux-x64-gnu.node')
+            } else {
+              nativeBinding = require('@rolly-dev/witness-core-linux-x64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'witness-core.linux-arm64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./witness-core.linux-arm64-musl.node')
+            } else {
+              nativeBinding = require('@rolly-dev/witness-core-linux-arm64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'witness-core.linux-arm64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./witness-core.linux-arm64-gnu.node')
+            } else {
+              nativeBinding = require('@rolly-dev/witness-core-linux-arm64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'witness-core.linux-arm-musleabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./witness-core.linux-arm-musleabihf.node')
+            } else {
+              nativeBinding = require('@rolly-dev/witness-core-linux-arm-musleabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'witness-core.linux-arm-gnueabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./witness-core.linux-arm-gnueabihf.node')
+            } else {
+              nativeBinding = require('@rolly-dev/witness-core-linux-arm-gnueabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'riscv64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'witness-core.linux-riscv64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./witness-core.linux-riscv64-musl.node')
+            } else {
+              nativeBinding = require('@rolly-dev/witness-core-linux-riscv64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'witness-core.linux-riscv64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./witness-core.linux-riscv64-gnu.node')
+            } else {
+              nativeBinding = require('@rolly-dev/witness-core-linux-riscv64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 's390x':
+        localFileExisted = existsSync(
+          join(__dirname, 'witness-core.linux-s390x-gnu.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./witness-core.linux-s390x-gnu.node')
+          } else {
+            nativeBinding = require('@rolly-dev/witness-core-linux-s390x-gnu')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Linux: ${arch}`)
+    }
+    break
+  default:
+    throw new Error(`Unsupported OS: ${platform}, architecture: ${arch}`)
+}
+
+if (!nativeBinding) {
+  if (loadError) {
+    throw loadError
+  }
+  throw new Error(`Failed to load native binding`)
+}
+
+const { MerkleEngine, engineVersion } = nativeBinding
+
+module.exports.MerkleEngine = MerkleEngine
+module.exports.engineVersion = engineVersion

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@rolly-dev/witness-core",
+  "version": "0.1.0",
+  "description": "Authoritative native witness-state engine for Rolly ZK-Rollup (Node-API addon)",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "license": "MIT",
+  "engines": {
+    "node": ">=16"
+  },
+  "napi": {
+    "name": "witness-core",
+    "triples": {
+      "defaults": false,
+      "additional": [
+        "x86_64-unknown-linux-gnu",
+        "aarch64-apple-darwin"
+      ]
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "*.node"
+  ],
+  "scripts": {
+    "build": "napi build --platform --release",
+    "build:debug": "napi build --platform",
+    "build:linux-x64": "napi build --platform --release --target x86_64-unknown-linux-gnu",
+    "artifacts": "napi artifacts",
+    "prepublishOnly": "napi prepublish -t npm",
+    "test": "node test.js"
+  },
+  "devDependencies": {
+    "@napi-rs/cli": "^2.18.4"
+  },
+  "keywords": [
+    "napi",
+    "node-api",
+    "zk-rollup",
+    "witness",
+    "merkle",
+    "rolly"
+  ],
+  "optionalDependencies": {
+    "@rolly-dev/witness-core-linux-x64-gnu": "0.1.0",
+    "@rolly-dev/witness-core-darwin-arm64": "0.1.0"
+  }
+}