Feat: multiset hash on OctoBear curve

[yelhousni]

Description

This PR adds native gnark support for the OctoBear curve over the degree-8 extension of KoalaBear field together with the circuit components needed to use both single-point and vector-point multiset hashes in KoalaBear-based SNARKs.

The main additions are:

• a native OctoBear field tower (Fp², Fp⁴, Fp⁸) under std/algebra/native/fields_octobear, with separate R1CS and Plonk multiplication/squaring paths
• native OctoBear affine curve arithmetic under std/algebra/native/sw_octobear (incomplete add, double, unified add, double-and-add, Brier–Joye variants)
• a native OctoBear y-increment map-to-curve gadget under std/algebra/native/maptocurve_octobear, plus two N-coordinate (N = 23) vector map-to-curve variants:
  • a linear-separator map (MapLinear)
  • a Poseidon2-sponge map (MapPoseidon2) over the KoalaBear field, width 16
• multiset-hash accumulators over OctoBear in sw_octobear:
  • a 1-point Accumulator (insert-only, fixed public offset point derived from the OctoBear generator)
  • a 23-coordinate LinearAccumulator using the linear vector map
  • a 23-coordinate Poseidon2Accumulator using the Poseidon2 vector map
• a new in-circuit Poseidon2 permutation for the KoalaBear field (std/permutation/poseidon2/poseidon2_koalabear.go), matching the native gnark-crypto round keys and M4
• new solver hints wired through std/hints.go, plus a bump to the matching gnark-crypto revision (go.mod / go.sum)
• minor internal/smallfields/tinyfield updates: Cbrt and Cube on Element, and a parallel.Execute vector decode path
• a .golangci.yml entry to keep the octobear token out of misspell

The multiset-hash circuits are aligned with the current gnark-crypto OctoBear construction and are intended for later use in zkVM memory-check arguments defined over the KoalaBear field. All three accumulators are insert-only and start from a fixed public offset point derived from the OctoBear generator, which preserves the incomplete-addition safety argument (acc ± Map(m) = 0 succeeds with negligible probability over the 2²⁴⁸ group) and keeps the in-circuit addition path simple and cheap.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How has this been tested?

• go test ./std/algebra/native/fields_octobear ./std/algebra/native/maptocurve_octobear ./std/algebra/native/sw_octobear
  • field arithmetic: add/sub/mul/square on E2/E4/E8, plus inverse on E8
  • curve arithmetic: incomplete add, double, unified add, double-and-add, Brier–Joye add (general / double / opposite)
  • map-to-curve: y-increment correctness vs native
  • multiset-hash: TestHash, TestHashInvalidDigest, TestLinearHash, TestLinearHashHomomorphic, TestPoseidon2Hash, TestPoseidon2HashHomomorphic
• go test ./std/permutation/poseidon2 — including the new TestPoseidon2KoalaBearMatchesNative
• go test ./internal/smallfields/tinyfield — covers the new Cbrt / Cube and the parallel vector decode path
• go test ./std/algebra/native/...

How has this been benchmarked?

• go test ./std/algebra/native/sw_octobear -run '^$' -bench BenchmarkMultisetHashCircuitSolve -benchtime=1x, on Apple M5, 24 GB RAM
• go test ./std/algebra/native/sw_octobear -run '^$' -bench BenchmarkLinearMultisetHashCircuitSolve -benchtime=1x
• go test ./std/algebra/native/sw_octobear -run '^$' -bench BenchmarkPoseidon2MultisetHashCircuitSolve -benchtime=1x

Current benchmark numbers on Apple M5:

• single OctoBear multiset-hash insert: 660 scs constraints, 268 r1cs constraints
  • solve: scs 261792 ns/op, r1cs 216833 ns/op
• 23-coordinate linear vector multiset-hash insert: 9580 scs constraints, 4022 r1cs constraints
  • solve: scs 1644375 ns/op, r1cs 941667 ns/op
• 23-coordinate Poseidon2 vector multiset-hash insert: 14117 scs constraints, 5890 r1cs constraints
  • solve: scs 936625 ns/op, r1cs 1088375 ns/op

Checklist:

• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• I have added tests that prove my fix is effective or that my feature works
• I did not modify files generated from templates
• golangci-lint does not output errors locally
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published in downstream modules

---

Note

Medium Risk
Large new cryptographic surface (Fp⁸ inverses, map-to-curve, incomplete EC adds, Poseidon2 sponge) with tight coupling to a bumped gnark-crypto revision; mistakes could break soundness of multiset-hash circuits, though changes are additive with broad tests.

Overview
Adds KoalaBear-native circuit support for the OctoBear curve and multiset-hash constructions, aimed at small-field SNARKs (e.g. zkVM memory checks).

New packages fields_octobear (Fp²/Fp⁴/Fp⁸ with R1CS vs Plonk mul/square paths), maptocurve_octobear (y-increment map plus linear and Poseidon2 23-point vector maps with hints), and sw_octobear (affine G1 ops, 1-point accumulator, linear and Poseidon2 vector accumulators starting from a fixed generator offset). std/permutation/poseidon2 gains a KoalaBear width-16 path (round keys, circulant M4, internal diagonal) aligned with gnark-crypto; std/hints.go registers the new hints. gnark-crypto is bumped to a pre-release revision that supplies OctoBear multiset-hash and extension APIs.

Smaller diffs: tinyfield adds Cbrt/Cube, switches vector decode to parallel.Execute, and assorted Go 1.22+ loop/any cleanups; .golangci.yml ignores misspell on octobear; koalabear_ext_test renames to MulByQuadraticNonResidue.

^{Reviewed by Cursor Bugbot for commit a27b2aa. Bugbot is set up for automated code reviews on this repo. Configure here.}

[Copilot]

Pull request overview

Adds native gnark circuit support for the kb8 curve over the KoalaBear field, including field-tower arithmetic, map-to-curve, and a 1-point multiset-hash accumulator intended for KoalaBear-based SNARK circuits.

Changes:

• Introduce fields_kb8 (KoalaBear-native E2/E4/E8 arithmetic) with solver hints and unit tests.
• Add sw_kb8 curve gadget with affine operations plus a multiset-hash accumulator and tests/benchmarks.
• Add maptocurve_kb8 y-increment map-to-curve gadget with hints and tests; register new hints in std/hints.go.

Reviewed changes

Copilot reviewed 21 out of 21 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
std/hints.go	Registers kb8-related hint functions with the global solver registry.
std/algebra/native/sw_kb8/doc.go	Package documentation for kb8 curve + multiset-hash gadgets.
std/algebra/native/sw_kb8/types.go	Defines kb8 circuit types (G1Affine and field aliases) and native assignment helpers.
std/algebra/native/sw_kb8/g1.go	Implements kb8 affine curve operations and on-curve/subgroup assertions.
std/algebra/native/sw_kb8/g1_test.go	Adds correctness tests for kb8 affine operations.
std/algebra/native/sw_kb8/hints.go	Exposes kb8-related hints (currently forwarded from fields_kb8).
std/algebra/native/sw_kb8/multisethash.go	Implements 1-point multiset-hash accumulator and Curve.Hash.
std/algebra/native/sw_kb8/multisethash_test.go	Adds multiset-hash circuit tests and a solve benchmark.
std/algebra/native/maptocurve_kb8/doc.go	Package documentation for kb8 y-increment map-to-curve gadget.
std/algebra/native/maptocurve_kb8/types.go	Defines map-to-curve types and helpers to assemble E8 from coefficients.
std/algebra/native/maptocurve_kb8/maptocurve.go	Implements y-increment map-to-curve gadget and compatibility check.
std/algebra/native/maptocurve_kb8/maptocurve_test.go	Adds a test against gnark-crypto’s native mapping.
std/algebra/native/maptocurve_kb8/hints.go	Adds hint implementation for y-increment mapping (k and x output).
std/algebra/native/fields_kb8/doc.go	Package documentation for KoalaBear-native field-tower arithmetic.
std/algebra/native/fields_kb8/e2.go	Implements E2 arithmetic for KoalaBear-native circuits.
std/algebra/native/fields_kb8/e2_test.go	Adds tests for E2 operations.
std/algebra/native/fields_kb8/e4.go	Implements E4 arithmetic built on E2.
std/algebra/native/fields_kb8/e4_test.go	Adds tests for E4 operations.
std/algebra/native/fields_kb8/e8.go	Implements E8 arithmetic built on E4, including hint-based inverse/div.
std/algebra/native/fields_kb8/e8_test.go	Adds tests for E8 operations.
std/algebra/native/fields_kb8/hints.go	Registers E8 inverse/div hints and provides native (de)serialization helpers.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[gbotrel]

Review pass from 2026-05-07.

Findings:

• Blocking: the branch does not build against its current go.mod. Staticcheck CI is failing with missing github.com/consensys/gnark-crypto/ecc/kb8, missing github.com/consensys/gnark-crypto/ecc/kb8/multiset-hash, and undefined extensions.E8; I reproduced the same locally with go test ./std/algebra/native/fields_kb8 ./std/algebra/native/maptocurve_kb8 ./std/algebra/native/sw_kb8. This needs the gnark-crypto feat: add set operations #832 dependency wired in before the gnark PR can be reviewed/merged normally.
• Soundness concern in std/algebra/native/sw_kb8/multisethash.go: Accumulator.Insert relies on AddAssign, and AddAssign uses DivUnchecked(dy, dx) in std/algebra/native/sw_kb8/g1.go. The comment says exceptional P = +/-Q cases are rejected by division-by-zero, but that is not generally true for 0/0 in gnark; the R1CS builder has tests that accept DivUnchecked(0, 0). A circuit-facing multiset hash should not rely on overwhelming probability over witness-controlled inputs unless the domain/length analysis is made explicit and tested. I would use the unified addition path here, or add hard constraints/proofs/tests showing the exceptional cases are impossible for all admissible messages and accumulator states.

Verification run locally:

• go test ./std/algebra/native/fields_kb8 ./std/algebra/native/maptocurve_kb8 ./std/algebra/native/sw_kb8 (fails for the dependency issue above)

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit f6f5bed. Configure here.}

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	golang/​github.com/​consensys/​gnark-crypto@​v0.20.1 ⏵ v0.20.2-0.20260601192128-f6b0b478eda6	+1
	golang/​golang.org/​x/​sync@​v0.19.0 ⏵ v0.20.0

View full report

[Copilot]

Pull request overview

Copilot reviewed 35 out of 40 changed files in this pull request and generated 3 comments.

Files not reviewed (4)

• internal/smallfields/tinyfield/element.go: Language not supported
• internal/smallfields/tinyfield/element_test.go: Language not supported
• internal/smallfields/tinyfield/vector.go: Language not supported
• internal/smallfields/tinyfield/vector_test.go: Language not supported

[socket-security]

Warning

Review the following alerts detected in dependencies.

According to your organization's Security Policy, it is recommended to resolve "Warn" alerts. Learn more about Socket for GitHub.

Action	Severity	Alert  (click "▶" to expand/collapse)
Warn		Obfuscated code: golang golang.org/x/tools is 90.0% likely obfuscated Confidence: 0.90 Location: Package overview From: ? → golang/golang.org/x/tools@v0.43.0 ℹ Read more on: This package | This alert | What is obfuscated code? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Packages should not obfuscate their code. Consider not using packages with obfuscated code. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore golang/golang.org/x/tools@v0.43.0. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.

View full report