feat: add official bun binding

.github/workflows/test.yml

@@ -61,22 +61,21 @@ jobs:
           echo "$HOME/.bun/bin" >> $GITHUB_PATH
           bun --version
 
-      # (Optional) Install dependencies if you use bun install.
       - name: Bun - Install Dependencies
         run: bun install
-        working-directory: ./test/bun
+        working-directory: ./bun
 
       - name: Bun - Lint Code
         run: bun lint
-        working-directory: ./test/bun
+        working-directory: ./bun
 
       - name: Bun - Unit Tests
         run: bun test:unit
-        working-directory: ./test/bun
+        working-directory: ./bun
 
       - name: Benchmark
         run: bun benchmark
-        working-directory: ./test/bun
+        working-directory: ./bun
         env:
           # To write to PRs and commits
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -4,4 +4,8 @@ zig-out/
 
 test/bun/node_modules/
 
-test/bun/benchmark_data/
+test/bun/benchmark_data/
+
+bun/node_modules/
+
+bun/benchmark_data/

bun/README.md

@@ -0,0 +1,6 @@
+# state-transition-utils-bun
+State transition utilities for Bun, which is Bun binding using [state-transition-z](https://github.com/ChainSafe/state-transition-z)
+
+To consume this libraries, application needs to call these apis:
+- `initBinding()`: at application startup, before calling any apis of this library
+- `closeBinding()`: at application close()

test/bun/package.json → bun/package.json

@@ -1,7 +1,10 @@
 {
-	"name": "state-transition-bun",
+	"name": "@chainsafe/state-transition-bun",
 	"module": "src/index.ts",
 	"type": "module",
+	"dependencies": {
+		"@chainsafe/bun-ffi-z": "https://github.com/twoeths/bun-ffi-z.git#te/fix_open_library"
+	},
 	"devDependencies": {
 		"@types/bun": "latest",
 		"@types/js-yaml": "^4.0.9",
@@ -18,10 +21,24 @@
 		"typescript": "^5.0.0"
 	},
 	"scripts": {
+		"build": "bun ./node_modules/.bin/bun-ffi-z build --zig-cwd '..'",
 		"test:unit": "bun test test/unit",
 		"lint": "biome check",
 		"benchmark": "bun benchmark:files 'test/perf/*.test.ts'",
 		"benchmark:files": "bun ./node_modules/.bin/benchmark --config .benchrc.yaml --defaultBranch main",
 		"lint:fix": "yarn lint --write"
+	},
+	"bun-ffi-z": {
+		"name": "state-transition-utils",
+		"targets": [
+			"linux-x64-gnu",
+			"linux-arm64-gnu",
+			"linux-x64-musl",
+			"linux-arm64-musl",
+			"darwin-x64",
+			"darwin-arm64"
+		],
+		"optimize": "ReleaseSafe",
+		"zigCwd": ".."
 	}
 }

test/bun/src/binding.ts → bun/src/binding.ts

@@ -1,11 +1,8 @@
-import { dlopen } from "bun:ffi";
-import { getBinaryName, getPrebuiltBinaryPath } from "../utils/index.js";
+import type { ConvertFns } from "bun:ffi";
+import path from "node:path";
+import { openLibrary } from "@chainsafe/bun-ffi-z";
 
-const binaryName = getBinaryName();
-const binaryPath = getPrebuiltBinaryPath(binaryName);
-
-// Load the compiled Zig shared library
-const lib = dlopen(binaryPath, {
+const fns = {
 	createPubkeyIndexMap: {
 		args: [],
 		returns: "ptr",
@@ -116,10 +113,36 @@ const lib = dlopen(binaryPath, {
 		],
 		returns: "u32",
 	},
-});
+};
+
+let binding: ConvertFns<typeof fns> | null = null;
+
+// Load the compiled Zig shared library
+const libPromise = await openLibrary(path.resolve("../bun"), fns);
+
+/**
+ * Call this api to initialize the binding.
+ */
+export async function initBinding(): Promise<void> {
+	const lib = await libPromise;
+	binding = lib.symbols;
+}
 
-export const binding = lib.symbols;
+/**
+ * Get the binding.
+ */
+export function getBinding(): ConvertFns<typeof fns> {
+	if (binding == null) {
+		throw new Error("Binding not initialized. Call init() first.");
+	}
+	return binding;
+}
 
-export function closeBinding(): void {
+/**
+ * Call this api to close the binding.
+ */
+export async function closeBinding(): Promise<void> {
+	const lib = await libPromise;
 	lib.close();
+	binding = null;
 }

test/bun/src/committeeIndices.ts → bun/src/committeeIndices.ts

@@ -1,8 +1,8 @@
-import { binding } from "./binding.js";
+import { getBinding } from "./binding.js";
 import { validateShufflingParams } from "./shuffle.js";
 
 // this is to sync the constant from zig to Bun which is 0xffffffff
-const ERROR_INDEX = binding.getErrorIndex();
+const ERROR_INDEX = 0xffffffff;
 
 /** Pre-electra, byte count for random value is 1, post-electra, byte count for random value is 2 */
 export declare enum ByteCount {
@@ -20,6 +20,7 @@ export function computeProposerIndex(
 	rounds: number,
 ): number {
 	validateShufflingParams(activeIndices, seed, rounds);
+	const binding = getBinding();
 
 	const result = binding.computeProposerIndex(
 		seed,
@@ -48,6 +49,7 @@ export function computeProposerIndexElectra(
 	rounds: number,
 ): number {
 	validateShufflingParams(activeIndices, seed, rounds);
+	const binding = getBinding();
 
 	const result = binding.computeProposerIndexElectra(
 		seed,
@@ -77,6 +79,7 @@ export function computeSyncCommitteeIndices(
 	rounds: number,
 ): Uint32Array {
 	validateShufflingParams(activeIndices, seed, rounds);
+	const binding = getBinding();
 
 	const out = new Uint32Array(syncCommitteeSize);
 	const result = binding.computeSyncCommitteeIndices(
@@ -111,6 +114,7 @@ export function computeSyncCommitteeIndicesElectra(
 	rounds: number,
 ): Uint32Array {
 	validateShufflingParams(activeIndices, seed, rounds);
+	const binding = getBinding();
 
 	const out = new Uint32Array(syncCommitteeSize);
 	const result = binding.computeSyncCommitteeIndicesElectra(

test/bun/src/index.ts → bun/src/index.ts

@@ -1,3 +1,4 @@
 export * from "./pubkeyIndexMap.js";
 export * from "./shuffle.js";
 export * from "./committeeIndices.js";
+export * from "./binding.js";