feat: Plonky3 compatible poseidon2 hash function (#9)

* fix: Made Poseidon2KoalaBera const as public and added semantic versioning

* fix: Exported the koalabear16 module properly from root.zig

* fix: corrected lint errors

* fix: corrected error in ci workflow

* fix: Corrected the GH workflow to release a verion on the release branch

* feat: Add KoalaBear24 instance

* fix: Fixed lint errors

* fix: bug fixes in koalabear24 instance

* fix: correction to be rust compatible

* fix: bug fix of repeated patterns in hash

* fix: bug fix

* feat: Added hash-sig specific koalabear implementation

* chore: Updated .gitignore

* fix: Fixed tests

* feat: Added plonky3 compatible poseidon hash function which is compatible with rust implementation

* fix: lint errors

* fix: refactor and removed duplicate code

* fix: fixed inverse in montgomery form

Author: ch4r10t33r

build.zig

@@ -20,6 +20,10 @@ pub fn build(b: *std.Build) void {
 
     b.installArtifact(lib);
 
+    const lint_cmd = b.addSystemCommand(&.{ "zig", "fmt", "--check", "src" });
+    const lint_step = b.step("lint", "Run zig fmt --check on source files");
+    lint_step.dependOn(&lint_cmd.step);
+
     const main_tests = b.addTest(.{
         .root_source_file = b.path("src/main.zig"),
         .target = target,

src/fields/generic_montgomery.zig

@@ -40,6 +40,12 @@ pub fn MontgomeryField31(comptime modulus: u32) type {
             return montReduce(@as(u64, self.value));
         }
 
+        pub fn inverse(out: *MontFieldElem, value: MontFieldElem) void {
+            const normal = montReduce(@as(u64, value.value));
+            const inv_normal = modInverse(normal, modulus);
+            toMontgomery(out, inv_normal);
+        }
+
         fn montReduce(mont_value: u64) FieldElem {
             const tmp = mont_value + (((mont_value & 0xFFFFFFFF) * modulus_prime) & 0xFFFFFFFF) * modulus;
             std.debug.assert(tmp % R == 0);
@@ -79,3 +85,32 @@ fn euclideanAlgorithm(a: u64, b: u64) u64 {
     }
     return @intCast(t);
 }
+
+fn modInverse(a: u32, m: u32) u32 {
+    if (a == 0) return 0;
+
+    var old_r = a;
+    var r = m;
+    var old_s: i32 = 1;
+    var s: i32 = 0;
+
+    while (r != 0) {
+        const quotient = old_r / r;
+        const temp_r = r;
+        r = old_r - quotient * r;
+        old_r = temp_r;
+
+        const temp_s = s;
+        s = old_s - @as(i32, @intCast(quotient)) * s;
+        old_s = temp_s;
+    }
+
+    if (old_r > 1) {
+        return 0;
+    }
+
+    if (old_s < 0) {
+        return @as(u32, @intCast(old_s + @as(i32, @intCast(m))));
+    }
+    return @as(u32, @intCast(old_s));
+}

src/plonky3_poseidon2/README.md

@@ -0,0 +1,51 @@
+# Poseidon2 Implementation for Zig
+
+This module exposes the KoalaBear Poseidon2 instances that match Plonky3's parameters while reusing the shared `poseidon2/poseidon2.zig` core and the existing field arithmetic in `fields/koalabear/montgomery.zig`.
+
+## Features
+
+- **Plonky3 Compatible**: Re-exports the KoalaBear Poseidon2 instances and round constants used by Plonky3
+- **Shared Core**: Delegates to the generic `poseidon2` engine that powers the rest of this repository
+- **KoalaBear Field**: Uses the standard Montgomery formulation from `fields/koalabear/montgomery.zig`
+- **Poseidon2-16 and Poseidon2-24**: Provides ready-to-use 16- and 24-width permutations
+
+## Usage
+
+```zig
+const poseidon2 = @import("plonky3_poseidon2/root.zig");
+
+// Create Montgomery field elements (KoalaBear)
+var state16: [16]poseidon2.Field.MontFieldElem = undefined;
+// initialise state16...
+poseidon2.poseidon2_16(&state16);
+
+var state24: [24]poseidon2.Field.MontFieldElem = undefined;
+// initialise state24...
+poseidon2.poseidon2_24(&state24);
+```
+
+## API Reference
+
+### Field Alias
+- `Field`: Alias of `fields/koalabear/montgomery.zig`'s `MontgomeryField`
+
+### Poseidon2 Types
+- `Poseidon2KoalaBear16Plonky3`: The width-16 Poseidon2 instance (Plonky3 parameters)
+- `Poseidon2KoalaBear24Plonky3`: The width-24 Poseidon2 instance (Plonky3 parameters)
+
+### Convenience Functions
+- `poseidon2_16(state: *[16]Field.MontFieldElem)`: In-place width-16 permutation
+- `poseidon2_24(state: *[24]Field.MontFieldElem)`: In-place width-24 permutation
+
+## Implementation Details
+
+Both instances are generated by feeding the Plonky3 round constants into the shared `poseidon2.Poseidon2` template. This keeps the implementation identical to the other Poseidon variants in this repository while guaranteeing constant parity with Plonky3.
+
+## Testing
+
+The implementation has been tested against Plonky3's Poseidon2 implementation to ensure compatibility. All field operations, round constants, and permutation steps match exactly.
+
+## Files
+
+- `root.zig`: Main module exports and thin wrappers over shared instances
+

src/plonky3_poseidon2/root.zig

@@ -0,0 +1,20 @@
+// Poseidon2 implementation compatible with Plonky3 KoalaBear field
+
+const koalabear16 = @import("../instances/koalabear16_generic.zig");
+const koalabear24 = @import("../instances/koalabear24_generic.zig");
+const MontgomeryField = @import("../fields/koalabear/montgomery.zig").MontgomeryField;
+
+pub const Field = MontgomeryField;
+
+pub const Poseidon2KoalaBear16Plonky3 = koalabear16.Poseidon2KoalaBear;
+pub const Poseidon2KoalaBear24Plonky3 = koalabear24.Poseidon2KoalaBear;
+pub const Poseidon2KoalaBear16 = Poseidon2KoalaBear16Plonky3;
+pub const Poseidon2KoalaBear24 = Poseidon2KoalaBear24Plonky3;
+
+pub fn poseidon2_16(state: *[16]Field.MontFieldElem) void {
+    Poseidon2KoalaBear16Plonky3.permutation(state);
+}
+
+pub fn poseidon2_24(state: *[24]Field.MontFieldElem) void {
+    Poseidon2KoalaBear24Plonky3.permutation(state);
+}

src/root.zig

@@ -6,6 +6,7 @@ pub const koalabear = @import("instances/koalabear.zig");
 pub const koalabear16_generic = @import("instances/koalabear16_generic.zig");
 pub const koalabear24_generic = @import("instances/koalabear24_generic.zig");
 pub const poseidon2 = @import("poseidon2/poseidon2.zig");
+pub const plonky3_poseidon2 = @import("plonky3_poseidon2/root.zig");
 
 // Convenience type exports
 pub const Poseidon2BabyBear = babybear16.Poseidon2BabyBear;