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

Co-authored-by: Will <[email protected]>

AnnaShaleva

Need some more time to verify the math.

AnnaShaleva · 2025-10-02T15:32:07Z

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

+{
+    partial class CryptoLib
+    {
+        [ContractMethod(Hardfork.HF_Gorgon, CpuFee = 1 << 19)]


Faun? I thought we need to include them into the upcoming release.

Maybe no hard fork is needed.

AnnaShaleva · 2025-10-02T15:33:27Z

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

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


Also need bn254Equal.

As far as bn254Serialize and bn254Deserialize.

AnnaShaleva · 2025-10-02T15:35:27Z

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

+            return BN254.Add(input);
+        }
+
+        [ContractMethod(Hardfork.HF_Gorgon, CpuFee = 1 << 19)]


Suggested change

[ContractMethod(Hardfork.HF_Gorgon, CpuFee = 1 << 19)]

[ContractMethod(Hardfork.HF_Gorgon, CpuFee = 1 << 21)]

Follow bls12381Mul, multiplication is more complicated.

Turalchik · 2025-10-03T08:24:08Z

src/Neo/Cryptography/BN254.cs

+            ReadOnlySpan<byte> xBytes = encoded[..FieldElementLength];
+            fixed (byte* ptr = xBytes)
+            {
+                if (Mcl.mclBnFp_setBigEndianMod(ref point.x, (nint)ptr, (nuint)xBytes.Length) != 0)


This call, in the case when the input has a non-canonical representation, takes the result modulo p (https://github.com/herumi/mcl/blob/master/include/mcl/bn.h#L310-L313), is this behavior correct and safe?

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

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

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

+            if (input.Length != BN254.G1EncodedLength * 2)
+                throw new ArgumentException("Invalid BN254 add input length", nameof(input));


Move this validation to Add method?

shargon · 2025-10-24T08:29:53Z

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

+            "2c145edbe7fd8aee9f3a80b03b0b1c923685d2ea1bdec763c13b4711cd2b8126",
+            "05b54f5e64eea80180f3c0b75a181e84d33365f7be94ec72848a1f55921ea762");
+
+        internal static bool IsAllZero(ReadOnlySpan<byte> data)


Use ByteExtensions.NotZero?

Add bn254 native contract bindings and tests

3188ee3

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

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

929a989

Wi1l-B0t reviewed Sep 26, 2025

View reviewed changes

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

Jim8y and others added 2 commits September 26, 2025 20:47

Update src/Neo/Cryptography/BN254.cs

f459bef

Co-authored-by: Will <[email protected]>

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

40a8169

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

AnnaShaleva added Hardfork Core labels Oct 2, 2025

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

b126987

Turalchik reviewed Oct 3, 2025

View reviewed changes

roman-khimov mentioned this pull request Oct 9, 2025

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

Open

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

0e767cd

erikzhang reviewed Oct 20, 2025

View reviewed changes

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

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

fa6f05d

erikzhang mentioned this pull request Oct 22, 2025

Dev meeting - 10-23-2025 #4236

Closed

Jim8y added 2 commits October 24, 2025 01:21

Implement managed BN254 arithmetic

07fab37

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

0298aad

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

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

8d4a9ea

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

	[ContractMethod(Hardfork.HF_Gorgon, CpuFee = 1 << 19)]
	[ContractMethod(Hardfork.HF_Gorgon, CpuFee = 1 << 21)]

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

		if (input.Length != BN254.G1EncodedLength * 2)
		throw new ArgumentException("Invalid BN254 add 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

Jim8y commented Sep 22, 2025 •

edited

Loading