9lives

9lives is a prediction market protocol built on Arbitrum Stylus, supporting both a Dynamic Pari-Mutuel Prediction Market (DPPM) model and a Constant Product AMM model. The core contracts are written in Rust and compiled to WASM, with supporting Solidity contracts for proxies, the Vault, and the TradingBeacon.

If you’re interested in running prediction markets using 9lives (including hosted graph infrastructure), reach out via this form.

How the contracts work

The system follows a factory/proxy pattern. The Factory deploys Trading contract proxies and Share ERC20 proxies for each market. Each Trading contract is a beacon proxy that delegates calls to one of four implementation facets (mint, extras, quotes, price) based on the function selector, looked up via the TradingBeacon. There are separate implementations for DPPM and AMM backends, selected at deploy time.

flowchart TD
    Creator -->|Calls newTrading with outcomes, oracle, fees, backend type| Factory
    Factory -->|Deploys beacon proxy via CREATE2| TradingProxy[Trading Proxy]
    Factory -->|Deploys ERC20 proxy per outcome via CREATE2| ShareERC20s[Share ERC20s]
    Factory -->|Borrows seed liquidity for DPPM markets| Vault
    TradingProxy -->|Delegates to facet based on selector| TradingBeacon
    TradingBeacon -->|Routes to| MintImpl[Mint Impl]
    TradingBeacon -->|Routes to| ExtrasImpl[Extras Impl]
    TradingBeacon -->|Routes to| QuotesImpl[Quotes Impl]
    TradingBeacon -->|Routes to| PriceImpl[Price Impl]
    ShareERC20s -->|Minted/burned by| MintImpl
    Oracle[Oracle: Beauty Contest / Price Resolver] -->|Calls decide on| TradingProxy

Contract facets

Each Trading contract is split into four facets, each compiled as a separate WASM binary with either the trading-backend-dppm or trading-backend-amm feature flag. The TradingBeacon maps function selectors to the correct facet address using a byte in the selector:

Trading backends

DPPM (Dynamic Pari-Mutuel Prediction Market) – implemented in trading_dppm.rs:

• Supports exactly 2 outcomes
• Seed liquidity is borrowed from the Vault at creation time and repaid at resolution
• Share prices are determined by the ratio of funds invested in each outcome
• Includes a “Ninetails” time-weighted bonus: earlier buyers receive boosted shares that entitle them to a larger portion of the losing side’s funds
• Only whitelisted creator addresses (DPPM_HOUR_CREATOR_ADDR, DPPM_15_MIN_CREATOR_ADDR, DPPM_5_MIN_CREATOR_ADDR) can create DPPM markets
• No selling/burning of shares – positions are held until resolution

AMM (Automated Market Maker) – implemented in trading_amm.rs:

• Supports 2+ outcomes
• Uses a constant-product invariant across outcome share pools
• Liquidity providers can add/remove liquidity and earn fees
• Shares can be both minted (bought) and burned (sold) before resolution
• A “shortterm AMM” variant exists for markets using the price resolver oracle, where the Vault provides and reclaims liquidity at resolution

Oracles (resolution mechanisms)

Markets must specify an oracle at creation time. The oracle is the only address allowed to call decide() on a Trading contract, which locks in the winning outcome.

Beauty Contest (contract_beauty_contest.rs):

• The simplest oracle – anyone can call resolve() after the market’s deadline passes
• For DPPM: picks the outcome with the most shares purchased
• For AMM: picks the outcome with the highest price
• Pays a fee to the caller who triggers resolution

Price Resolver Oracle (external contract at ORACLE_ADDR):

• Used for short-term markets where the outcome is determined by an external data source (e.g., asset prices via LayerZero)
• The oracle contract calls decide() when the condition is met
• If not activated by the deadline, defaults to a preconfigured outcome

Supporting contracts

Vault (Vault.sol):

• A shared liquidity pool that lends seed capital to DPPM markets at creation and is repaid at resolution
• For DPPM: the Factory calls borrow() at market creation; the Trading contract calls repay() at resolution, returning DAO-earned fees to cover the loan
• For shortterm AMM: the Factory calls ammRegister(); at resolution the Trading contract either calls ammReceive() (if there’s a shortfall) or ammGift() (if there’s a surplus)
• The operator can drain() excess funds above outstanding debt

Share ERC20s (Share.sol):

• Minimal ERC20 tokens deployed per outcome via CREATE2
• Minted/burned exclusively by the associated Trading contract
• The CREATE2 salt is derived from the trading address + outcome identifier, making addresses deterministic

Factory (contract_factory_1.rs, contract_factory_2.rs):

• Split across two facets for code size reasons
• Factory 1: newTrading – deploys trading proxies, share ERC20s, seeds liquidity, registers with oracles
• Factory 2: constructor, admin functions, address lookups, legacy compatibility methods

Fee structure

Fees are configured per-market at creation time (each capped at <10%):

Project structure

src/
  lib.rs                          # Crate root, feature-gated entrypoint selection
  contract_factory_1.rs           # Factory: market creation (newTrading)
  contract_factory_2.rs           # Factory: admin, queries, legacy compat
  storage_factory.rs              # Factory storage layout
  contract_trading.rs             # Trading: feature gate that selects the active facet
  contract_trading_mint.rs        # Trading facet: mint/burn shares
  contract_trading_extras.rs      # Trading facet: ctor, state, decide
  contract_trading_quotes.rs      # Trading facet: quotes, payoff, fees
  contract_trading_price.rs       # Trading facet: price, liquidity, fee claiming
  contract_trading_extras_admin.rs # Trading facet: admin-only operations
  contract_trading_dumper.rs      # Trading facet: emergency dumper
  storage_trading.rs              # Trading storage layout
  trading_dppm.rs                 # DPPM backend: mint, payoff, price logic
  trading_amm.rs                  # AMM backend: mint, burn, liquidity, price logic
  trading_private.rs              # Shared trading internals: ctor, decide, fees, shutdown
  contract_beauty_contest.rs      # Beauty Contest oracle: resolve by popularity
  storage_beauty_contest.rs       # Beauty Contest storage layout
  immutables.rs                   # Compile-time addresses and constants
  fees.rs                         # Fee constants (bonds, incentives, protocol %)
  maths.rs                        # Math helpers (DPPM share calc, sqrt, mul_div)
  proxy.rs                        # CREATE2 proxy deployment helpers
  error.rs                        # Error types and codes (see ERRORS.md)
  events.rs                       # Event definitions
  Vault.sol                       # Vault: shared liquidity pool (Solidity)
  TradingBeacon.sol               # Beacon: maps selectors to facet impls (Solidity)
  Share.sol                       # Share ERC20 (Solidity, compiled with Foundry)
  NineLivesPaymaster.sol          # Paymaster for gasless transactions (Solidity)
tests/                            # Property tests, e2e tests, reference implementations
db/                               # Database migrations (PostgreSQL)
cmd/                              # Backend services (Go): GraphQL API, ingestor, paymaster, etc.
web/                              # Frontend (TypeScript)

Feature flags

Each contract facet is compiled as a separate WASM binary using Cargo feature flags. Exactly one contract-* feature must be enabled per build, and trading facets additionally require either trading-backend-dppm or trading-backend-amm:

Building

Build all contract WASM binaries and Solidity artifacts:

make build

This compiles each facet separately (see the Makefile for the full list of targets). Solidity contracts are built with Foundry:

forge build

Environment variables

The Rust contracts read deployment addresses at compile time from environment variables (see immutables.rs). Key variables include:

• SPN_FUSDC_ADDR – fUSDC token address
• SPN_STAKED_ARB_ADDR – Staked ARB token address
• SPN_TRADING_BEACON_ADDR – TradingBeacon contract address
• SPN_VAULT_ADDR – Vault contract address
• SPN_SHARE_IMPL_ADDR – Share ERC20 implementation address
• SPN_DAO_EARN_ADDR – DAO fee recipient
• SPN_DAO_OP_ADDR – DAO operator (admin)

See immutables.rs for the full list. When the testing feature is enabled, these are replaced with hardcoded test addresses from testing_addrs.rs.

Testing

Unit and property tests run natively (not in WASM). The testing feature must be enabled:

./tests.sh

Mutation testing with cargo-mutants and cargo-nextest (slow, resource-intensive):

./mutants.sh

PROPTEST_CASES controls the number of property test iterations (default in CI: 10, proptest default: 256).

End-to-end tests in tests/ use a bespoke harness that deploys contracts to a local Arbitrum node. The build.rs script reads environment.lst files to track deployment addresses:

# List all recorded environment variables from a fresh deploy
sort $(find target -name environment.lst) | uniq

# Clear recorded variables
find target -name environment.lst -delete

For debugging reverts, build with debug info and use stylus-interpreter to simulate calldata against the WASM binary.

Errors

See ERRORS.md for the full error code table. Generate it with:

./print-error-table.sh

Audits

• Dadekuma (December 2024)
• OpenZeppelin (November 2025)

See audits/README.md for details.

Deployments

Superposition mainnet

Several “precompiles” are in use, provided by superposition-precompiles.

License

See LICENSE.