Add bn254 native contract bindings and tests #4185

Jim8y · 2025-09-22T03:55:51Z

Description

Proposal neo-project/proposals#205 . Adds a bn254 native contract implementation that mirrors the Solidity/EVM precompile interface.
The contract now routes elliptic curve add, scalar multiplication, and pairing through Nethermind’s
MCL bindings, handling Ethereum’s big-endian payload layout and zero-on-error semantics. Unit
coverage includes the canonical Ethereum GeneralStateTests pairing vectors to ensure cross-chain
compatibility. The native manifest snapshot was refreshed so genesis exposes the new entry points.

Fixes # (issue)

Type of change

Optimization (the change is only an optimization)
Style (the change is only a code style for better maintenance or standard purpose)
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?

dotnet test tests/Neo.UnitTests/Neo.UnitTests.csproj --filter CryptoLib

Test Configuration:

OS: same as CI image
.NET SDK: 9.0.301
Tests reused Ethereum fixtures (GeneralStateTests/stZeroKnowledge/ecpairing_inputs.json, commit
c67e485ff8b5be9abc8ad15345ec21aa22e290d9)

Checklist:

My code follows the style guidelines of this project
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
My changes generate no new warnings
I have added tests that prove my fix is effective or that my feature works
New and existing unit tests pass locally with my changes
Any dependent changes have been merged and published in downstream modules

cschuchardt88 · 2025-09-22T05:25:37Z

BouncyCastle can do the curve

public static ECDomainParameters GetBN254G1DomainParameters()
{
    // Define the prime modulus 'p' of the base field.
    // p = 21888242871839275222246405745257275088696311157297823662689037894645226208583
    BigInteger p = new BigInteger("21888242871839275222246405745257275088696311157297823662689037894645226208583");

    // Define the curve equation y^2 = x^3 + a*x + b.
    // For BN254, a = 0 and b = 3.
    BigInteger a = BigInteger.Zero;
    BigInteger b = new BigInteger("3");

    // Define the order of the G1 group 'n'.
    // n = 21888242871839275222246405745257275088548364400416034343698204186575808495617
    BigInteger n = new BigInteger("21888242871839275222246405745257275088548364400416034343698204186575808495617");
    // The cofactor 'h' is usually a small integer. For BN254, it is (p+1-t)/n.
    BigInteger h = BigInteger.One;

    // Construct the finite field F_p.
    ECCurve curve = new FpCurve(p, a, b, n, h);

    // Define the G1 generator point coordinates (x, y).
    // x = 1, y = 2.
    BigInteger gx = new BigInteger("1");
    BigInteger gy = new BigInteger("2");

    // Create the ECPoint for the G1 generator.
    ECPoint g = curve.CreatePoint(gx, gy);

    // Combine parameters into an ECDomainParameters object.
    return new ECDomainParameters(curve, g, n, h);
}

src/Neo/Cryptography/BN254.cs

AnnaShaleva

Need some more time to verify the math.

src/Neo/SmartContract/Native/CryptoLib.BN254.cs

src/Neo/Cryptography/BN254.cs

Wi1l-B0t · 2025-10-18T16:12:44Z

No progress?

src/Neo/Neo.csproj

Jim8y · 2025-10-23T17:27:44Z

I’ve reworked the BN254 native contract so it no
longer relies on Nethermind.MclBindings—the entire G1/G2 arithmetic and
Miller loop now live in BN254.Managed.* and are backed by BouncyCastle.
The wrapper in BN254.cs uses those managed routines, and Neo.csproj no
longer references the Nethermind package. I also updated the docs and tests to
reflect the EVM-style 32-byte success word, and the pairing vectors all pass
(dotnet test tests/Neo.UnitTests/Neo.UnitTests.csproj). Please take another
look.

erikzhang · 2025-10-24T03:50:11Z

@neo-project/ngd-shanghai Need testing.

Copilot

Pull Request Overview

This PR adds BN254 elliptic curve cryptography support to the Neo native CryptoLib contract, mirroring the Ethereum/EVM precompile interface. The implementation enables elliptic curve addition, scalar multiplication, and pairing operations through three new contract methods (bn254Add, bn254Mul, bn254Pairing) that handle Ethereum's big-endian payload layout and zero-on-error semantics. Unit tests include canonical Ethereum GeneralStateTests pairing vectors to ensure cross-chain compatibility.

Key Changes

Adds three BN254 native contract methods with Ethereum-compatible interfaces
Implements managed field arithmetic (Fp, Fp2, Fp6, Fp12) and curve operations for BN254
Includes comprehensive test coverage using Ethereum test vectors

Reviewed Changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/Neo.UnitTests/SmartContract/Native/UT_NativeContract.cs	Updates native contract manifest snapshot to include new bn254 methods
tests/Neo.UnitTests/SmartContract/Native/UT_CryptoLib.cs	Adds comprehensive unit tests for BN254 operations using Ethereum test vectors
src/Neo/SmartContract/Native/CryptoLib.BN254.cs	Implements the three public BN254 native contract methods with input validation
src/Neo/Cryptography/BN254.cs	Core BN254 implementation handling Add, Mul, and Pairing operations with BouncyCastle integration
src/Neo/Cryptography/BN254.Managed.Fields.cs	Implements field arithmetic for Fp and Fp2
src/Neo/Cryptography/BN254.Managed.Extensions.cs	Implements extension field arithmetic for Fp6 and Fp12
src/Neo/Cryptography/BN254.Managed.Curves.cs	Implements curve point operations and Miller loop for pairing
docs/native-contracts-api.md	Documents the three new BN254 contract methods

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

shargon · 2025-10-24T08:25:50Z

src/Neo/SmartContract/Native/CryptoLib.BN254.cs

+            if (input.Length % BN254.PairInputLength != 0)
+                throw new ArgumentException("Invalid BN254 pairing input length", nameof(input));


Seems already checked in Pairing method

src/Neo/SmartContract/Native/CryptoLib.BN254.cs

src/Neo/Cryptography/BN254.Managed.Fields.cs

txhsl · 2025-11-05T09:00:54Z

I briefly read through the implementation, and it looks compatible with the Solidity/EVM precompile interface.

To verify the equivalence, please consider using the EVM test data, ref https://github.com/ethereum/go-ethereum/tree/v1.16.7/core/vm/testdata/precompiles.

shargon · 2025-11-05T09:53:41Z

I briefly read through the implementation, and it looks compatible with the Solidity/EVM precompile interface.

To verify the equivalence, please consider using the EVM test data, ref https://github.com/ethereum/go-ethereum/tree/v1.16.7/core/vm/testdata/precompiles.

@Jim8y Nice, could you add them to test?

Jim8y · 2025-11-08T00:54:52Z

@txhsl please check again

txhsl

Only a performance concern, otherwise all good to me.

txhsl · 2025-11-10T09:06:53Z

src/Neo/Cryptography/BN254.cs

+                hasEffectivePair = true;
+
+                mclBnGT current = default;
+                Mcl.mclBn_pairing(ref current, g1, g2);


Maybe mclBn_millerLoop is better here, ref https://github.com/NethermindEth/nethermind/blob/1d85282f2d88b092469a57673dc8fb9a403b3a13/src/Nethermind/Nethermind.Evm.Precompiles/BN254.cs#L108 and https://github.com/herumi/mcl/blob/e4c8bbe4af0013e00244c661836f3a3676f21024/src/pairing_impl.hpp#L774.

The longer a correct input we have, the more times the finalExp is executed. Anyway, it depends on your design of the procedure.

AnnaShaleva

Please, consider also to update the price: https://github.com/neo-project/neo/pull/4185/files#r2399242679.

AnnaShaleva · 2025-11-10T11:14:52Z

src/Neo/SmartContract/Native/CryptoLib.BN254.cs

+    partial class CryptoLib
+    {
+        [ContractMethod(Hardfork.HF_Gorgon, CpuFee = 1 << 19)]
+        public static byte[] Bn254Add(byte[] input)


We have a divergence from the CryptoLib interface. Existing BLS12-381 methods like bls12381Add and bls12381Mul work with InteropInterface which contains G1/G2/GT point instances under the hood:

neo/src/Neo/SmartContract/Native/CryptoLib.BLS12_381.cs

Line 108 in ac7ebab

public static InteropInterface Bls12381Mul(InteropInterface x, byte[] mul, bool neg)

I think compatibility with an existing CryptoLib interface is important, so it would be good to refactor BN254 methods to work with InteropInterface types instead of raw byte arrays. And we also should introduce bn254Serialize and bn254Deserialize for that.

Given this approach, user will deserialize input points once, then perform a set of operations, then serialize the result (also once per contract method). This approach is more effective when there's a set of BN254 operations (which is usually the case), we just won't perform deserialization/serialization on every BN254 operation.

Co-authored-by: Anna Shaleva <[email protected]>

Wi1l-B0t · 2025-11-11T00:15:35Z

Conflicts.

Jim8y · 2025-11-13T11:58:52Z

Conflicts.

i am waiting for erik to complete his refactoring.

AnnaShaleva · 2025-11-14T08:08:40Z

src/Neo/SmartContract/Native/CryptoLib.BN254.cs

+        }
+
+        [ContractMethod(Hardfork.HF_Faun, CpuFee = 1 << 19, Name = "bn254_add")]
+        public static byte[] Bn254AddRaw(byte[] input)


Please, remove Bn254*Raw methods. Standard methods that work with InteropInterface are sufficient.

I need @neo-project/core opinion on this issue. input here contains 2 serialized points (as in Ethereum, I suppose). To me, it's sufficient to have bn254Deserialize, bn254DeserializeEthereum and bn254Add(x, y) methods in CryptoLib API, and then input byte array in both Neo/Ethereum format may be parsed on the contract side using these methods, instead of exposing yet another bn254AddRaw from the CryptoLib.

Otherwise if we don't keep compatibility with the existing CryptoLib interface, it will turn into a mess.

AnnaShaleva · 2025-11-14T08:21:45Z

src/Neo/SmartContract/Native/CryptoLib.BN254.cs

+        }
+
+        [ContractMethod(Hardfork.HF_Faun, CpuFee = 1 << 21)]
+        public static byte[] Bn254Pairing(Array pairs)


This method should also return an InteropInterface.

Jim8y force-pushed the feature/bn254-curve-support branch from c796a25 to 3188ee3 Compare September 22, 2025 03:59

Jim8y requested review from AnnaShaleva and shargon September 22, 2025 04:00

Jim8y added the Waiting for Review label Sep 22, 2025

Wi1l-B0t reviewed Sep 26, 2025

View reviewed changes

src/Neo/Cryptography/BN254.cs Show resolved Hide resolved

roman-khimov mentioned this pull request Sep 29, 2025

Add BN254 curve support nspcc-dev/neo-go#4029

Open

AnnaShaleva reviewed Oct 2, 2025

View reviewed changes

src/Neo/SmartContract/Native/CryptoLib.BN254.cs Outdated Show resolved Hide resolved

src/Neo/SmartContract/Native/CryptoLib.BN254.cs Outdated Show resolved Hide resolved

src/Neo/SmartContract/Native/CryptoLib.BN254.cs Outdated Show resolved Hide resolved

AnnaShaleva added Hardfork Core labels Oct 2, 2025

Turalchik reviewed Oct 3, 2025

View reviewed changes

src/Neo/Cryptography/BN254.cs Show resolved Hide resolved

roman-khimov mentioned this pull request Oct 9, 2025

core: add BN254 curve support nspcc-dev/neo-go#4032

Open

erikzhang reviewed Oct 20, 2025

View reviewed changes

src/Neo/Neo.csproj Outdated Show resolved Hide resolved

erikzhang mentioned this pull request Oct 22, 2025

Dev meeting - 10-23-2025 #4236

Closed

shargon requested a review from Copilot October 24, 2025 08:22

shargon added the Need Testing label Oct 24, 2025

Copilot AI reviewed Oct 24, 2025

View reviewed changes

shargon reviewed Oct 24, 2025

View reviewed changes

neo-project deleted a comment from Copilot AI Oct 24, 2025

txhsl mentioned this pull request Nov 5, 2025

Add Ethereum-compatible aliases for BLS12-381 #4186

Open

10 tasks

Jim8y force-pushed the feature/bn254-curve-support branch from 654b38c to 3d61cbc Compare November 7, 2025 15:04

Jim8y changed the base branch from dev to master November 7, 2025 16:25

Jim8y force-pushed the feature/bn254-curve-support branch 2 times, most recently from ac43dc7 to b71f990 Compare November 7, 2025 17:07

Add BN254 native contract

9973b98

Jim8y force-pushed the feature/bn254-curve-support branch from b71f990 to 9973b98 Compare November 7, 2025 17:08

Jim8y added 4 commits November 8, 2025 01:10

Merge branch 'master' into feature/bn254-curve-support

9d30a2c

fix format

6b551be

Enable unsafe build for BN254

a08a87b

Document BN254 native methods

30603f9

Jim8y added Port-to-3.x Feature or PR must be ported to Neo 3.x branch and removed Need Testing labels Nov 8, 2025

txhsl reviewed Nov 10, 2025

View reviewed changes

AnnaShaleva reviewed Nov 10, 2025

View reviewed changes

Jim8y and others added 4 commits November 10, 2025 20:05

Reduce BN254 pairing final exponentiation overhead

0eee6d8

Apply suggestions from code review

35835ae

Co-authored-by: Anna Shaleva <[email protected]>

Refine BN254 CryptoLib API and tests

43799ea

Add bn254Equal and sync manifests

33ecb69

Activate BN254 API in Faun hardfork

546a6d0

AnnaShaleva reviewed Nov 14, 2025

View reviewed changes

Jim8y changed the base branch from master to master-n3 November 14, 2025 09:23

Jim8y changed the base branch from master-n3 to master November 14, 2025 09:24

		if (input.Length % BN254.PairInputLength != 0)
		throw new ArgumentException("Invalid BN254 pairing input length", nameof(input));

Add bn254 native contract bindings and tests #4185

Are you sure you want to change the base?

Add bn254 native contract bindings and tests #4185

Uh oh!

Conversation

Jim8y commented Sep 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Type of change

How Has This Been Tested?

Checklist:

Uh oh!

cschuchardt88 commented Sep 22, 2025

Uh oh!

Uh oh!

AnnaShaleva left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Wi1l-B0t commented Oct 18, 2025

Uh oh!

Uh oh!

Jim8y commented Oct 23, 2025

Uh oh!

erikzhang commented Oct 24, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Key Changes

Reviewed Changes

Uh oh!

shargon Oct 24, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

txhsl commented Nov 5, 2025

Uh oh!

shargon commented Nov 5, 2025

Uh oh!

Jim8y commented Nov 8, 2025

Uh oh!

txhsl left a comment

Choose a reason for hiding this comment

Uh oh!

txhsl Nov 10, 2025

Choose a reason for hiding this comment

Uh oh!

AnnaShaleva left a comment

Choose a reason for hiding this comment

Uh oh!

AnnaShaleva Nov 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Wi1l-B0t commented Nov 11, 2025

Uh oh!

Jim8y commented Nov 13, 2025

Uh oh!

AnnaShaleva Nov 14, 2025

Choose a reason for hiding this comment

Uh oh!

AnnaShaleva Nov 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AnnaShaleva Nov 14, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

Jim8y commented Sep 22, 2025 •

edited

Loading

AnnaShaleva Nov 10, 2025 •

edited

Loading

AnnaShaleva Nov 14, 2025 •

edited

Loading