Smart Contracts

On-chain contract architecture for the Index protocol

On-Chain Contract Architecture

The contracts are the truth. Everything else is commentary.

7,300 lines of Solidity on an Arbitrum Orbit L3. UUPS proxies. BLS verification on every path that matters. No test modes, no owner overrides — because the moment you add a bypass, you have admitted the system does not believe in itself.

DTF Core Contracts

Contract	Description
Index.sol	Central entry point for order submission, batch/fill confirmation, and Dex Traded Fund (DTF) management. Houses createITP (converts weights to fixed per-share quantities), _getCurrentPrice (computes NAV from inventory), and updateWeights (rebalance that preserves NAV).
ITP.sol	ERC-4626 vault wrapping each DTF’s share token. Handles minting on buy, burning on sell, and exposes standard vault accounting.
BridgeProxy.sol	Cross-chain order routing between Arbitrum L1/L2 and the L3. Relays user orders submitted on Arbitrum down to the Index contract on L3.
BridgedItpFactory.sol	Factory that creates ERC-20 representations of DTF shares on Arbitrum, enabling L1/L2 composability without requiring users to interact with L3 directly.
Governance.sol	Administrative controls including global pause, per-DTF pause, and role management.
BLSCustody.sol	Executes custody operations (deposits, withdrawals) gated by BLS-signed consensus from oracle nodes.

Registry Contracts

Contract	Description
OracleRegistry.sol	Stores oracle node BLS public keys, manages the aggregated public key, and handles key rotation. New oracle nodes must register in OracleRegistry before participating in consensus.
CollateralRegistry.sol	Maintains the whitelist of accepted collateral tokens (currently USDC). Controls which tokens can back DTF creation and order settlement.
AssetPairRegistry.sol	Configures trading pairs available on the protocol — maps asset identifiers to on-chain and off-chain parameters.
FeeRegistry.sol	Defines fee tiers for different operations and manages deployer fee claiming. Protocol fees are accrued in FeeRegistry and claimable by authorized addresses.

Shared Libraries

Library	Purpose
TypesLib.sol	Shared struct definitions used across the protocol: LimitOrder, Fill, ITP, batch metadata, and more.
ErrorsLib.sol	Custom error definitions ranging from E001 through E069+. Every revert in the protocol uses a typed error from ErrorsLib.
EventsLib.sol	Event definitions emitted by core contracts — OrderSubmitted, BatchConfirmed, FillExecuted, ITPCreated, WeightsUpdated, etc.
BLSLib.sol	BLS signature verification using EVM precompiles on the BN254 curve. Called by every path that validates oracle node consensus.

Storage Layout

IndexStorage.sol holds _itpInventory[itpId] — the fixed per-share quantities for each asset. Set at creation. Changed only on rebalance. Buy and sell do not touch it. This is the invariant that makes everything else possible.

All upgradeable contracts use UUPS proxies (OpenZeppelin 5.x). Storage slots are managed to survive upgrades. The proxy address is permanent. Only the implementation changes.

DTF NAV Pricing Model

Every DTF starts at $1. Then the market takes over. The price drifts as underlying assets move — this is the point.

// At creation (or rebalance), weights become fixed quantities:
qty[i] = (weight[i] * 1e18) / price[i]

// NAV is always computed from quantities and current prices:
NAV = sum(qty[i] * price[i]) / 1e18

Invariants — violate any of these and the system is lying:

• Per-share quantities live in _itpInventory. They change only on rebalance.
• Buy and sell mint or burn shares proportionally. They never touch quantities.
• Rebalance preserves NAV: qty_new[i] = (w_new[i] * currentNAV) / price[i]
• NAV drifts from $1 as underlying prices move. Drift is the product, not a bug.

BLS Signature Security

Every state change that matters requires cryptographic proof that the machines agreed. There is no alternative path.

BLS verification is never bypassed. No test modes. No onlyOwner overrides. No aggregatedPubkey.length == 0 short circuits. If BLS is in the way, fix the BLS pipeline. Do not carve a hole in the wall.

• Curve: BN254 (alt_bn128) — precompiles at 0x06, 0x07, 0x08
• Threshold: ceil(2n/3) of registered oracle nodes
• Key management: Aggregated public key in OracleRegistry.sol, updated on join/leave/rotation
• Verification: BLSLib.verify(message, signature, aggregatedPubkey) in confirmBatch(), before any state change

DTF Order Lifecycle

User submits order (L3 or via BridgeProxy)
        │
        ▼
  Index.sol stores pending order
        │
        ▼
  Oracle nodes batch orders off-chain
        │
        ▼
  confirmBatch() called with BLS signature
        │
        ▼
  BLSLib verifies aggregated signature
        │
        ▼
  Batch confirmed → TradeRequest events emitted
        │
        ▼
  Authorized Participant (AP) executes fills → confirmFills() with BLS signature
        │
        ▼
  ITP shares minted/burned, collateral settled

Vision Prediction Market Contracts

Vision turns opinions into positions and positions into outcomes. Parimutuel — winners take from losers, and the pool does not lie about who was right.

Contract	Description
Vision.sol	Parimutuel prediction market contract. Manages batch creation, bet placement, outcome resolution, and payout distribution. Each batch defines a set of outcomes; users deposit USDC to back a chosen outcome, and winning bettors split the total pool proportionally.
BotRegistry.sol	Manages automated bot registration for Vision. Bots register with a wallet address and can participate in Vision batches programmatically. BotRegistry tracks bot metadata and enforces registration requirements.