# Balancer V2 — Contract Reference

Operational details for Balancer V2 weighted/stable pools: which canonical
contracts the Rust engine implements (the Python companions are thin shells
over it), how each contract generation is detected on-chain, and the
deployment lineage used as parity ground truth.

Sources scraped for this reference (2026-09):

- balancer-v2-monorepo @ `f8b6f44f21afaf3c802536ed478277f945e7f256`
  (2026-05-28, "Bump hardhat minor version (#2652)") — also the vendored
  reference for the Tier-3 oracle.
- balancer-labs/balancer-deployments @ HEAD (`addresses/base.json`,
  `addresses/mainnet.json`).

## Canonical math pin (Tier-3 oracle)

`tier3-oracle/src-balancer/BalancerSwapOracleHarness.sol` compiles the
canonical library sources fetched at the pinned commit into
`tier3-oracle/lib/balancer-src/`:

| Vendored source | Canonical package | Version at pin |
|-----------------|-------------------|----------------|
| `FixedPoint.sol`, `LogExpMath.sol`, `Math.sol` | `pkg/solidity-utils` | 4.0.0 |
| `WeightedMath.sol` | `pkg/pool-weighted` | 2.0.1 |
| `StableMath.sol` | `pkg/pool-stable` | 0.1.0 |
| (vault interfaces) | `pkg/vault` | 3.0.1 |

The harness reproduces the fee/scaling/direction sequence of the Rust engine
(`degenbot-pools::simulate_balancer_weighted_swap` /
`simulate_balancer_stable_swap`), which is the sole owner of Balancer swap
math; the Python companions are thin shells over it. Byte-exact parity is
asserted in
`rust/crates/foundation/degenbot-pools/tests/tier3_balancer_swap_vs_revm.rs`
(`just test-tier3 balancer`); artifact integrity is enforced by
`tier3_harness_artifacts.rs` + `verify-tier3-artifacts.sh`.

## Contract-generation matrix

| Contract | Deployment lineage → factory | Swap math | Rust engine | Python companion |
|----------|------------------------------|-----------|-------------|------------------|
| `WeightedPool2Tokens` (2021) | mainnet `20210418-weighted-pool` → `WeightedPool2TokensFactory` `0xA5bf2ddF098bb0Ef6d120C98217dD6B141c74EE0`, `WeightedPoolFactory` `0x8E9aa87E45e92bad84D5F8DD1bff34Fb92637dE9` (DEPRECATED) | pow **V1** (FixedPoint without the `TWO`/`FOUR` fast paths) | YES — `PowVersion.V1` | shell over Rust core |
| `WeightedPool` (current, post-2022) | Base `20230320-weighted-pool-v4` (ACTIVE) → `WeightedPoolFactory` `0x4C32a8a8fDa4E24139B51b456B42290f51d6A1c4`; mainnet `20230206-weighted-pool-v3` / `20230320-weighted-pool-v4` | pow **V2** (LogExpMath fast paths for `y == ONE/TWO/FOUR`) | YES — `PowVersion.V2` | shell over Rust core |
| `StablePool` (plain, 2021-06) | mainnet `20210624-stable-pool` | `StableMath._calculateInvariant(amp, balances, roundUp=true)` (`P_D` accumulation — the deployed inline revision shared with MetaStable) | YES — `InvariantVersion.V2` | shell over Rust core |
| `MetaStablePool` | mainnet `20210727-meta-stable-pool` → `MetaStablePoolFactory` `0x67d27634E44793fE63c467035E31ea8635117cd4` (DEPRECATED) | `StableMath._calculateInvariant(amp, balances, roundUp=true)` (`P_D` round up) | YES — `InvariantVersion.V2` | shell over Rust core |
| `ComposableStablePool` (incl. MetaStable-era V2/V3 and V5/V6 factories) | mainnet `20220906`–`20240223`; Base `20230711-composable-stable-pool-v5` / `20240223-composable-stable-pool-v6` (Base factories listed DEPRECATED — pools live in the V2 vault registry regardless) | `INVARIANT_V1` (round-down `D_P`) + BPT-in-balances | YES — `InvariantVersion.V1` + `bpt_idx` skip | shell over Rust core |
| **Balancer V3** (the 2024-12 vault + 2026 factories) | Base/mainnet `20241204-v3-vault` + `v3-weighted-pool*` / `v3-stable-pool*` tasks | hook-based, new vault | NOT in scope (V2-vault pools only) | — |

Shared across chains: the V2 Vault itself (`0xBA12222222228d8Ba445958a75a0704d566BF2C8`).

## Version detection at construction

- **Weighted pow version** — `detect_pow_version()` (`balancer/pools.py`) scans
  the deployed bytecode for the `TWO` constant (`0x1bc16d674ec80000`) used by
  the `y == TWO` fast path, absent from 2021-era contracts → `PowVersion.V1`.
- **Stable invariant version** — `resolve_invariant_version()`
  (`builders/balancer_builder_base.py`) maps the Vault pool specialization:
  `General = 0` → `ComposableStablePool` → `INVARIANT_V1`;
  `MinimalSwapInfo = 1` → `MetaStablePool` → `INVARIANT_V2`. Plain 2021
  `StablePool`s are `General` (3+ tokens) or `TwoToken` (2 tokens) with no
  BPT and also use `INVARIANT_V2`; the heuristic has no branch for them, so
  builds must pass the `BuildPoolRequest.invariant_version` override (see
  gaps).
- **BPT-in-balances** — `detect_bpt_index()` probes the token list; `None`
  marks MetaStable (no BPT token).

## Known deployed pools used as parity ground truth

Golden-oracle parity (mainnet, block 24,407,242 —
`tests/golden/data/tests/balancer/`):

| Pool | Notes |
|------|-------|
| `0x5c6Ee304…DB8F56` (80 BAL / 20 WETH) | 2021-era weighted (pow V1) |
| `0x3e5FA951…CAA32` (USDT / WETH) | weighted pair |
| `0xff083f57…1FBe88` (GTC / WETH) | weighted pair |
| `0x0b09deA16…2a35` | two-token weighted |
| `0x9D0D36cC…c30ed` | **multi-token** weighted (N > 2) |
| `0x32296969…130230` | stable (boosted/composable lineage) |

## Gaps / follow-ups

1. **Plain `StablePool` (2021) — covered, override still required.** The
   committed `20210624-stable-pool` build-info (solc 0.7.1) carries the
   deployed `StableMath._calculateInvariant(amp, balances, roundUp)` `P_D`
   revision with swaps on `roundUp=true` — exactly the engine's
   `InvariantVersion.V2` (`calculate_invariant_deployed(..., true)`). The
   Tier-3 companion gate exercises a 3-token plain-2021 configuration
   (`INVARIANT_V2`, no BPT) through both companion methods and both
   directions, and the Rust Tier-3 oracle pins that multi-token path
   byte-exact to the harness's verbatim deployed invariant. The builder's
   `resolve_invariant_version` heuristic still maps only specializations 0
   and 1 (plain 2021 pools are 0 or 2), so production builds of a plain 2021
   pool must pass the `BuildPoolRequest.invariant_version` override until the
   heuristic learns the no-BPT/no-rate-provider case.
2. **BalancerQueries on Base — resolved.** The two addresses are per-chain
   deployments of the same `20220721-balancer-queries` artifact:
   `0xE39B5e3B6D74016b2F6A9673D7d7493B6DF549d5` has code on Ethereum mainnet
   and none on Base, while `0x300Ab2038EAc391f26D9F895dc61F8F66a548833` has
   code on Base (its `vault()` is the canonical V2 Vault) and none on
   mainnet. The driver constant (`BALANCERQUERIES_CONTRACT_ADDRESS` in
   `balancer/deployments.py`) is intentionally mainnet-scoped for the
   mainnet parity tests; the deployments registry's `0x300Ab` is the Base
   counterpart. No Base-scoped constant is added because no consumer queries
   BalancerQueries on Base.