feat: Add nix flake for ffi

.cargo/config.toml

@@ -0,0 +1,2 @@
+[alias]
+build-static-ffi = "build --frozen --profile maxperf --package firewood-ffi --features ethhash,logger"

.github/dependabot.yml

@@ -12,3 +12,8 @@ updates:
       time: "05:00"
       timezone: "America/Los_Angeles"
     open-pull-requests-limit: 0 # Disable non-security version updates
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 0 # Disable non-security version updates

.github/workflows/attach-static-libs.yaml

@@ -63,7 +63,7 @@ jobs:
         run: cargo fetch --locked --verbose
 
       - name: Build for ${{ matrix.target }}
-        run: cargo build --frozen --profile maxperf --features ethhash,logger --target ${{ matrix.target }} -p firewood-ffi
+        run: cargo build-static-ffi --target ${{ matrix.target }}
 
       - name: Upload binary
         uses: actions/upload-artifact@v4

.github/workflows/ci.yaml

@@ -244,6 +244,25 @@ jobs:
         # cgocheck2 is expensive but provides complete pointer checks
         run: GOEXPERIMENT=cgocheck2 TEST_FIREWOOD_HASH_MODE=firewood go test -race ./...
 
+  ffi-nix:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: DeterminateSystems/nix-installer-action@786fff0690178f1234e4e1fe9b536e94f5433196 #v20
+      - uses: DeterminateSystems/magic-nix-cache-action@565684385bcd71bad329742eefe8d12f2e765b39 #v13
+      - name: Test build equivalency between Nix and Cargo
+        run: bash -x ./ffi/test-build-equivalency.sh
+      - name: Test Go FFI bindings
+        working-directory: ffi
+        # - cgocheck2 is expensive but provides complete pointer checks
+        # - use hash mode ethhash since the flake builds with `--features ethhash,logger`
+        # - run golang outside a nix shell to validate viability without the env setup performed by a nix shell
+        run: |
+          GOLANG="nix run $PWD#go"
+          cd result/ffi
+          GOEXPERIMENT=cgocheck2 TEST_FIREWOOD_HASH_MODE=ethhash ${GOLANG} test ./...
+        shell: bash
+
   firewood-ethhash-differential-fuzz:
     needs: build
     runs-on: ubuntu-latest

ffi/.gitignore

@@ -1,2 +1,5 @@
 dbtest
 _obj
+
+# Nix output
+result

ffi/flake.nix

@@ -0,0 +1,140 @@
+{
+  # To test with arbitrary firewood versions (alternative to firewood-go-ethhash):
+  #  - Install nix: https://github.com/DeterminateSystems/nix-installer?tab=readme-ov-file#install-nix
+  #  - Clone firewood locally at desired version/commit
+  #  - Build: `cd ffi && nix build`
+  #  - In your Go project: `go mod edit -replace github.com/ava-labs/firewood-go-ethhash/ffi=/path/to/firewood/ffi/result/ffi`
+
+  description = "Firewood FFI library and development environment";
+
+  inputs = {
+    nixpkgs.url = "https://flakehub.com/f/NixOS/nixpkgs/0.2505.*.tar.gz";
+    rust-overlay.url = "github:oxalica/rust-overlay";
+    crane.url = "github:ipetkov/crane";
+    flake-utils.url = "github:numtide/flake-utils";
+    golang.url = "github:ava-labs/avalanchego?dir=nix/go&ref=f10757d594eedf0f016bc1400739788c542f005f";
+  };
+
+  outputs = { self, nixpkgs, rust-overlay, crane, flake-utils, golang }:
+    flake-utils.lib.eachDefaultSystem (system:
+    let
+      overlays = [ (import rust-overlay) ];
+      pkgs = import nixpkgs { inherit system overlays; };
+      inherit (pkgs) lib;
+
+      go = golang.packages.${system}.default;
+
+      rustToolchain = pkgs.rust-bin.stable.latest.default.override {
+        extensions = [ "rust-src" "rustfmt" "clippy" ];
+      };
+
+      craneLib = (crane.mkLib pkgs).overrideToolchain rustToolchain;
+
+      # Extract crate info from Cargo.toml files
+      ffiCargoToml = builtins.fromTOML (builtins.readFile ./Cargo.toml);
+      workspaceCargoToml = builtins.fromTOML (builtins.readFile ../Cargo.toml);
+
+      src = lib.cleanSourceWith {
+        src = craneLib.path ./..;
+        filter = path: type:
+          (lib.hasSuffix "\.md" path) ||
+          (lib.hasSuffix "\.go" path) ||
+          (lib.hasSuffix "go.mod" path) ||
+          (lib.hasSuffix "go.sum" path) ||
+          (lib.hasSuffix "firewood.h" path) ||
+          (craneLib.filterCargoSources path type);
+      };
+
+      commonArgs = {
+        inherit src;
+        strictDeps = true;
+        dontStrip = true;
+
+        # Build only the firewood-ffi crate
+        pname = ffiCargoToml.package.name;
+        version = workspaceCargoToml.workspace.package.version;
+
+        nativeBuildInputs = with pkgs; [
+          pkg-config
+        ];
+
+        # Force sequential build of vendored jemalloc to avoid race conditions
+        # that cause non-deterministic symbol generation on x86_64
+        # MAKEFLAGS only affects make invocations (jemalloc), not cargo parallelism
+        # See: https://github.com/NixOS/nixpkgs/issues/380852
+        MAKEFLAGS = "-j1";
+      } // lib.optionalAttrs pkgs.stdenv.isDarwin {
+        # Set macOS deployment target for Darwin builds
+        MACOSX_DEPLOYMENT_TARGET = "13.0";
+      };
+
+      cargoArtifacts = craneLib.buildDepsOnly (commonArgs // {
+        # Use cargo alias defined in .cargo/config.toml
+        cargoBuildCommand = "cargo build-static-ffi";
+      });
+
+      firewood-ffi = craneLib.buildPackage (commonArgs // {
+        inherit cargoArtifacts;
+        # Use cargo alias defined in .cargo/config.toml
+        cargoBuildCommand = "cargo build-static-ffi";
+
+        # Disable tests - we only need to build the static library
+        doCheck = false;
+
+        # Install the static library and header
+        postInstall = ''
+          # Create a package structure compatible with FIREWOOD_LD_MODE=STATIC_LIBS
+          mkdir -p $out/ffi
+          cp -R ./ffi/* $out/ffi/
+          mkdir -p $out/ffi/libs/${pkgs.stdenv.hostPlatform.config}
+          cp target/maxperf/libfirewood_ffi.a $out/ffi/libs/${pkgs.stdenv.hostPlatform.config}/
+
+          # Run go generate to switch CGO directives to STATIC_LIBS mode
+          cd $out/ffi
+          HOME=$TMPDIR GOTOOLCHAIN=local FIREWOOD_LD_MODE=STATIC_LIBS ${go}/bin/go generate
+        '';
+
+        meta = with lib; {
+          description = "C FFI bindings for Firewood, an embedded key-value store";
+          homepage = "https://github.com/ava-labs/firewood";
+          license = {
+            fullName = "Ava Labs Ecosystem License 1.1";
+            url = "https://github.com/ava-labs/firewood/blob/main/LICENSE.md";
+          };
+          platforms = [ "x86_64-linux" "aarch64-linux" "x86_64-darwin" "aarch64-darwin" ];
+        };
+      });
+    in
+    {
+      packages = {
+        inherit firewood-ffi;
+        default = firewood-ffi;
+      };
+
+      apps.go = {
+        type = "app";
+        program = "${go}/bin/go";
+      };
+
+      devShells.default = craneLib.devShell {
+        inputsFrom = [ firewood-ffi ];
+
+        packages = with pkgs; [
+          firewood-ffi
+          rustToolchain
+          go
+        ];
+
+        shellHook = ''
+          # Ensure golang bin is in the path
+          GOBIN="$(go env GOPATH)/bin"
+          if [[ ":$PATH:" != *":$GOBIN:"* ]]; then
+            export PATH="$GOBIN:$PATH"
+          fi
+
+          # Force sequential build of vendored jemalloc for reproducibility
+          export MAKEFLAGS="-j1"
+        '';
+      };
+    });
+}

ffi/go.mod

@@ -2,6 +2,11 @@ module github.com/ava-labs/firewood/ffi
 
 go 1.24
 
+// Changes to the toolchain version should be replicated in:
+//   - ffi/go.mod (here)
+//   - ffi/flake.nix (update golang.url to a version of avalanchego's nix/go/flake.nix that uses the desired version)
+//   - ffi/tests/eth/go.mod
+//   - ffi/tests/firewood/go.mod
 toolchain go1.24.9
 
 require (