Bivium Protocol

The map of the Bivium Protocol stack: one oracle-free core, the products configured on top of it, and the off-chain tooling that quotes, curates and serves them.

Ten repositories make up this stack. Each one's README is authoritative for what that repository does and how far along it is. This repository documents what no single one of them owns: how they fit together.

One primitive

Everything on-chain is one object, a series, held in Core:

Series(lockedAsset A, lockedId, strikeAsset B, ratio, mintEnd, exerciseStart, exerciseEnd, controller)

Minting a series against a locked amount of A produces two fungible ERC-6909 tokens:

• the long — the right to pay ratio of B per unit of A and take that A, during the exercise window;
• the short — a pooled claim on whatever the series ends up holding: the B that longs paid in, plus whatever A was never taken.

That is the whole mechanism. Settlement is physical, collateral is always full, and nothing reads a price feed. There is no liquidation because there is nothing to liquidate against: a long either pays the strike or it does not, and the shorts receive exactly one of the two outcomes.

Lending is a configuration of it

A fixed-term loan is this object with the exercise window opened immediately:

The borrower locks collateral, keeps the long (the right to repay and take the collateral back) and sells the short (the lender's credit) for the loan. At maturity the lender holds either the repaid loan tokens or the delivered collateral. European and American options are the same object with a later exerciseStart.

This is the direction that matters. The option series is the primitive and lending is one of its configurations — not a lending protocol with options bolted on. One code path, one set of accounting invariants, one audit surface. A product repo contributes a controller and a mapping from human terms to series fields; it does not contribute a second core.

Two products, one core

The same core carries two products for two kinds of user. They share contracts, the Exchange and the relayer; they mostly do not share order books.

• Lending is for borrowers: fixed rate, fixed term, no liquidation. Economically a borrower buys a put (walking away at maturity delivers the collateral and ends the debt). It may also sell a call on its loan to lower the rate (collar), and close early by buying back the lender's credit or its call.
• Options trading is for option traders, and its market is the collar call market: the calls borrowers sell on their loans. Asks come only from collars, because a borrower's collateral is already locked by its loan, so writing the call needs no further capital, where a standard call locks a whole asset and a put its whole strike. Bids come from traders betting on the upside and from borrowers buying their call back to close a collar early. The market maker sits between, buying from borrowers and reselling. A holder takes the profit in the call's window without putting up the strike (CollarFlashExerciser, bivium-option). It is a product of its own, with its own pages (Frontend), not a step of the borrow flow.

The other side of lending is the market makers and the curated Earn pools (bivium-protocol-mm, bivium-curator). They supply its depth: they lend (they sell the put), they buy the calls borrowers sell, and for early closes they sell back calls and credit. They hedge what they take on wherever it is cheapest:

• Books are separate. A collar call locks a particular loan's long (L1), so it is a nested series of that loan: one book per loan market, strike and window, not a strike on the standard options chain. To a holder the call is the same whichever loan it locks (exercising pays K in all), so the options pages show the cheapest series per strike and window.
• Every on-chain hedge locks its full collateral. A put locks its whole strike in cash; a call locks the asset itself. Next to a margined venue such as Deribit, both cost a market maker capital it would not otherwise tie up, so a maker's hedges belong mostly off-chain, and so does the pools' cover — the HedgeDesk's off-chain path (Curator) — with on-chain options as a fallback.
• Where an on-chain market still works. A call is cheap to write for whoever holds the asset anyway (a covered call; the BTC Earn pool), so the standard call chain can have natural sellers. A maker can arbitrage a collar call it bought against a standard call it sells, but only when the spread pays for the asset it locks. On-chain puts have no such natural writer: locking the strike in cash is the whole cost.

Where to go

• Architecture — the core, the Exchange and the periphery in detail, and what the controller hook lets a product change.
• Lending — the first product as a configuration of the series: why selling the short is what makes a loan, what each side holds, collars, the controller's rules, what it can never do, and the Earn pool's contracts.
• Repositories — every repo, its role, and what it depends on.
• Lifecycle — a loan end to end, a TBV loan against whole BTC vaults and the calls written on them, and the Earn pool lane, naming which repository does each step.
• Native BTC swap — BTC ⇄ a token with TBVBTC as the unseen hop: the fast peg-out book's three ways to trade, the router, the market maker's two lanes, and withdrawing TBVBTC to a BTC wallet fast or standard — five repositories, each doing one step.
• Tooling — the SDK that defines the stack's vocabulary and publishes its pricing, and the market maker that is its first consumer and the curator's library.
• Curator — who decides what in an Earn pool, with what authority, and why the protection is a put rather than a sale.
• Frontend — the app and the offer relayer it carries: what it reads, the lend door, and the one place the stack keeps two implementations of the same arithmetic on purpose.
• Verification — the Lean models, the proofs and the conformance harness as three different claims, what they add up to, and the gap they leave.
• Integration — the rules that hold between repositories: deploy order, submodule bumps, frozen SDK releases, the spot feed contract, and what breaks when they drift.

Status

Unaudited, testnet only. Beyond that, this document deliberately does not restate what each repository says about itself — a status duplicated in two places is a status that disagrees with itself, and this stack has already produced one such disagreement inside a single README.