Repositories

Ten repositories, in two groups by how they are consumed: Solidity through git submodules under lib/, TypeScript through vendored npm tarballs. Each README is authoritative for its own contents and status.

Three more carry the third design, Bivium Direct (v3), and depend on none of the ten: bivium-tbv-direct (its contracts and TypeScript packages, one monorepo), bivium-v3-frontend (the v3 app on v3.cai.finance, which consumes its SDK) and bivium-v3-doc (this documentation, the copy the v3 app publishes). All three are private.

The dependency graph

Two groups, two mechanisms. Solidity depends through git submodules under lib/, so a dependency is pinned to a commit. TypeScript depends through vendored tarballs, so it is pinned to a hash.

bivium-protocol                 Core + Exchange + ratifiers + periphery
└── bivium-lending              lib/ bivium-protocol
    ├── bivium-option           lib/ bivium-protocol, bivium-lending
    └── bivium-protocol-tbv     lib/ bivium-protocol, bivium-lending

bivium-protocol-cli             @bivium/protocol-sdk + CLI + MCP
└── frozen release tarball
    ├── bivium-protocol-mm              quoting; also packs itself for ↓
    ├── bivium-curator                  vendors the SDK *and* mm
    └── bivium-protocol-frontend        app + the stack's offer relayer

bivium-tbv-direct               v3: apps, pools, series + @bivium/direct-sdk and packages
└── SDK tarball
    └── bivium-v3-frontend          the v3 app (v3.cai.finance); publishes bivium-v3-doc at /docs

Two edges are not imports and so are not drawn. bivium-protocol-spot is read over HTTP by the curator and the mm, and nothing depends on its code. bivium-protocol-lean4 reads the contracts the other way round: it vendors and hash-checks a pinned copy of them rather than being depended on.

The frontend reads contracts and logs directly — no indexer, no backend holding protocol state — and carries the relayer, so there is no separate relayer repository on this stack.

Contracts

| bivium-tbv-direct | v3, a separate design. GroupEngine with one custody per collateral — TbvDirectApp (Babylon vaults, TBVBTC) and Erc20DirectApp (WBTC, cbBTC, tBTC) — each one contract lending against whole lots, with covered calls, collars and call spreads on the loan's own record and auto-repay; DirectEarnPool and DirectSeries for Senior / Junior passive lending; its own FastPegOutBook, FastPegOutRouter, payout verifiers and Erc20DeliveryRouter. Uses no Core, Exchange or controller. See Bivium Direct (v3) and Direct Earn. | — (Babylon's vault contracts, OpenZeppelin) |

Solidity dependencies are git submodules under lib/, so a dependency is pinned to a commit and bumped deliberately.

Off-chain

TypeScript dependencies are vendored tarballs, not registry versions — see Integration for why, and for the release procedure.

Four things are called options

The word does the most damage of any in this stack, because it names four different things:

So a plain call or put does not go through bivium-option. It is a series, written straight on the protocol — Core, Exchange, a ratifier and the Router are the whole deployment, which is why the SDK can drive standard options with no lending addresses configured at all. The market maker's hedged option writer works exactly this way, and so do puts on TBVBTC: the keeper-side claim is an ordinary ERC-20, so a TBV lender's default hedge is a plain series.

bivium-option enters only when a strategy needs the lending position as a leg:

• OptionSeries turns human terms into series fields, plus the standard grid (nextExpiry, snapStrike) so that strikes and expiries land where a venue actually lists them — which is what makes an exact back-to-back hedge possible at all.
• CollarRouter is a borrower cutting financing cost: in one transaction it locks the borrower's lending long into a call series, sells that call into a market maker's bid, and pays the premium to the borrower, who keeps the call's short. It cannot serve a TBV loan: TBV's controller keeps L1 in the app, so TBV collars are TbvCallBook records instead (Lifecycle).
• CollarFlashExerciser is the call holder's way out in the window without holding the strike: it exercises the call (K − D, freeing L1), then L1 (D, freeing the collateral), sells the collateral through a swap adapter, pays K and sends the holder the profit. The protocol's FlashExerciser refuses nested series, and a collar call needs both exercises.
• HedgeRouter is the lender's side: buy lending credit and a put that opens at the lending maturity, in one transaction, under a total budget.

The repository holds itself to a rule worth repeating: options here are tools for lending, and each strategy must name its real surplus source and who receives it. The options product is built on exactly that: the calls traders buy are the collar calls borrowers sell, so the surplus source is the borrower's upside, sold to lower its rate (README). Plain calls and puts stay series on the core, quoted by the market maker for the Earn pools' and lenders' hedges, and are not listed on the options pages.

Roles carry over; two of the repos do not

The ops taxonomy has five roles, and reading it from the curator's README is where people go wrong, because two of the repos named there serve the old stack:

Neither bivium-solver nor bivium-keeper references bivium-protocol, and both target old-stack addresses. Do not wire either to anything here. The RFQ lane is unbuilt, not relocated. The keepers, the peg-out keeper included, run as lanes of bivium-protocol-mm rather than a repo of their own (Tooling). The contract lives with the product and the runner with the market maker, whose key and loan-token balance a keeper needs anyway.

Not this stack

These serve the earlier bivium-core protocol, or a separate prototype, and are a different codebase. Do not wire them to anything here, and do not treat their docs as describing this stack:

bivium-core, bivium-cli, bivium-mm, bivium-frontend, bivium-docs, bivium-keeper, bivium-solver, bivium-options, vault-contracts-bivium.

Four name collisions catch people, and three of them differ by one word:

The rule for the first three is simple: when a name does not say protocol, it is the old stack — with one exception: bivium-tbv-direct is new, and is the v3 design, not the old stack. The fourth is the dangerous one, because bivium-option and bivium-options differ by a single s and both are about options. bivium-protocol-tbv likewise replaces vault-contracts-bivium, which stays frozen with the old core.

Where each repo's own documentation lives