> ## Documentation Index
> Fetch the complete documentation index at: https://voltaire.tevm.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# 0x06 BN254 Add

> BN254 elliptic curve point addition

<Warning>
  **This page is a placeholder.** All examples on this page are currently AI-generated and are not correct. This documentation will be completed in the future with accurate, tested examples.
</Warning>

## Overview

**Address:** `0x0000000000000000000000000000000000000006`
**Introduced:** Byzantium (EIP-196)
**EIP:** [EIP-196](https://eips.ethereum.org/EIPS/eip-196), [EIP-1108](https://eips.ethereum.org/EIPS/eip-1108)

The BN254 Add precompile performs elliptic curve point addition on the BN254 (alt\_bn128) curve. It takes two G1 points and returns their sum. This is essential for zkSNARK verification and other zero-knowledge proof systems.

EIP-196 introduced BN254 operations in Byzantium. EIP-1108 (Istanbul) reduced gas costs by 91% to enable practical zkSNARK verification.

The BN254 curve is defined over a 254-bit prime field and is widely used in Zcash, Ethereum's zkSNARKs (Groth16), and other privacy protocols.

## Gas Cost

**Fixed:** `150` gas (reduced from 500 in Istanbul via EIP-1108)

## Input Format

```
Offset | Length | Description
-------|--------|-------------
0      | 32     | x1 (first point x-coordinate, big-endian)
32     | 32     | y1 (first point y-coordinate, big-endian)
64     | 32     | x2 (second point x-coordinate, big-endian)
96     | 32     | y2 (second point y-coordinate, big-endian)
```

Total input length: 128 bytes (padded/truncated to this size)

Points must satisfy the curve equation: `y^2 = x^3 + 3` over the BN254 field.
Point at infinity is represented as (0, 0).

## Output Format

```
Offset | Length | Description
-------|--------|-------------
0      | 32     | x (result point x-coordinate, big-endian)
32     | 32     | y (result point y-coordinate, big-endian)
```

Total output length: 64 bytes

## Usage Example

```typescript theme={null}
import { execute, PrecompileAddress } from '@tevm/voltaire/precompiles';
import { Hardfork } from '@tevm/voltaire/primitives/Hardfork';

// Add two G1 points on BN254 curve
// Point 1: Generator (1, 2)
const x1 = Bytes32('0x0000000000000000000000000000000000000000000000000000000000000001');
const y1 = Bytes32('0x0000000000000000000000000000000000000000000000000000000000000002');
// Point 2: Generator (1, 2) - will compute 2*G
const x2 = Bytes32('0x0000000000000000000000000000000000000000000000000000000000000001');
const y2 = Bytes32('0x0000000000000000000000000000000000000000000000000000000000000002');

const input = new Uint8Array(128);
input.set(x1, 0);
input.set(y1, 32);
input.set(x2, 64);
input.set(y2, 96);

const result = execute(
  PrecompileAddress.BN254_ADD,
  input,
  1000n,
  Hardfork.CANCUN
);

if (result.success) {
  const resultX = result.output.slice(0, 32);
  const resultY = result.output.slice(32, 64);
  console.log('Result point:', { x: resultX, y: resultY });
  console.log('Gas used:', result.gasUsed); // 150
} else {
  console.error('Error:', result.error);
}
```

## Error Conditions

* Out of gas (gasLimit \< 150)
* Point not on curve (x, y don't satisfy `y^2 = x^3 + 3`)
* Coordinate >= field modulus (`p = 0x30644e72e131a029b85045b68181585d97816a916871ca8d3c208c16d87cfd47`)

Invalid points cause the precompile to fail, returning error.

## Use Cases

* **zkSNARK verification:** Groth16 proof verification requires G1 point operations
* **Rollup verification:** zk-Rollups use BN254 for proof aggregation
* **Privacy protocols:** Zcash-style shielded transactions
* **Zero-knowledge applications:** zkEVMs, private DeFi, anonymous voting
* **Cryptographic commitments:** Pedersen commitments on BN254

## Implementation Details

* **Zig:** Pure Zig implementation using arkworks-rs for point arithmetic
* **TypeScript:** Wraps BN254 crypto module (arkworks bindings)
* **Integration:** Part of BN254 crypto suite (add, mul, pairing)
* **Curve:** BN254 (alt\_bn128) with embedding degree 12
* **Field modulus:** `0x30644e72e131a029b85045b68181585d97816a916871ca8d3c208c16d87cfd47`

## BN254 Curve Parameters

* **Curve equation:** y² = x³ + 3
* **Field modulus (p):** 21888242871839275222246405745257275088696311157297823662689037894645226208583
* **Group order (r):** 21888242871839275222246405745257275088548364400416034343698204186575808495617
* **Generator G1:** (1, 2)
* **Point at infinity:** (0, 0) by convention

## Point Addition Rules

* P + O = P (identity element)
* P + P = 2P (point doubling)
* P + (-P) = O (inverse)
* General addition uses elliptic curve addition formula

## Test Vectors

```typescript theme={null}
// Test 1: Identity + Identity = Identity
const input1 = new Uint8Array(128); // All zeros (point at infinity)
// Expected: (0, 0)
const expected1 = Bytes64(); // All zeros

// Test 2: Generator + Generator = 2*Generator (from geth tests)
const input2 = new Uint8Array(128);
// P1 = (1, 2), P2 = (1, 2)
input2[31] = 1;  // x1 = 1
input2[63] = 2;  // y1 = 2
input2[95] = 1;  // x2 = 1
input2[127] = 2; // y2 = 2
// Expected: 0x030644e72e131a029b85045b68181585d97816a916871ca8d3c208c16d87cfd3
//           15ed738c0e0a7c92e7845f96b2ae9c0a68a6a449e3538fc7ff3ebf7a5a18a2c4

// Test 3: Invalid point (not on curve)
const input3 = new Uint8Array(128);
input3[31] = 1;  // x1 = 1
input3[63] = 2;  // y1 = 2
// x2 = 0, y2 = 0 (second point is identity, valid)
// Expected: Success (returns first point)

// Test 4: Point outside field modulus
const input4 = new Uint8Array(128);
// Set coordinate >= field modulus
// Expected: Error (InvalidPoint)
```

## Gas Cost History

| Hardfork            | Gas Cost | Change  |
| ------------------- | -------- | ------- |
| Byzantium           | 500      | Initial |
| Istanbul (EIP-1108) | 150      | -70%    |

## References

### Specifications

* [Yellow Paper](https://ethereum.github.io/yellowpaper/paper.pdf) - Appendix E (Precompiled Contracts)
* [EIP-196: Precompiled Contracts for Addition and Scalar Multiplication on alt\_bn128](https://eips.ethereum.org/EIPS/eip-196)
* [EIP-1108: Reduce alt\_bn128 Gas Costs](https://eips.ethereum.org/EIPS/eip-1108)

### Related

* [Crypto: BN254](/crypto/bn254)
* [Precompile: BN254 Mul](/evm/precompiles/bn254-mul)
* [Precompile: BN254 Pairing](/evm/precompiles/bn254-pairing)
* [Precompiles Overview](/precompiles)