Direct Earn

Two ways for passive capital to lend on a Bivium Direct app (Architecture), both in bivium-tbv-direct, and both completely oracle-free. Each splits lenders into a Senior tranche paid first and a Junior tranche that absorbs losses first. Instead of relying on external put hedges anchored to an off-chain index, Bivium Direct protects Senior capital through Junior's on-chain first-loss buffer and deterministic loan mandates.

DirectEarnPool

One continuous pool per GroupEngine app and loan token (tbvEarnPool on TbvDirectApp, erc20EarnPool on Erc20DirectApp). Lenders call depositSenior(assets) or depositJunior(assets) to mint tranche shares and withdrawSenior(shares) / withdrawJunior(shares) to redeem against that tranche's idle cash (seniorIdleCash / juniorIdleCash).

Curator quotes, contract enforces the mandate

The pool's CURATOR signs standard EIP-712 LendBids with lender = address(pool) and posts them to /api/direct-orders. A borrower takes a pool bid by:

1. Approving the pool as a lot operator on the app once (app.setOperator(pool, true));
2. Calling pool.borrow(vaultIds, bid, curatorSig, minPrincipal, receiver).

Inside pool.borrow, the contract verifies:

• The caller is the origin of every lot in vaultIds;
• bid.lender == address(pool) and bid.loanToken == address(LOAN_TOKEN);
• curatorSig is a valid signature by CURATOR (ECDSA or EIP-1271);
• The loan satisfies the pool's immutable and governance-bounded mandate:
  • maturity - block.timestamp <= MAX_LOAN_DURATION;
  • annualized rate meets MIN_APR_BPS (650 bps = 6.50% on Sepolia);
  • bid.debtPerBtc <= maxDebtPerBtc ($65,000 on Sepolia);
  • both Senior and Junior tranches have sufficient idle cash (deployablePrincipal) to fund their mandated split (JUNIOR_TRANCHE_BPS = 2000 = 20% Junior, 80% Senior).

The pool then sets a transient one-transaction authorization flag, approves principal to the app, and calls app.borrowWithBid(...). Outside of pool.borrow, the pool's EIP-1271 isValidSignature returns 0xffffffff, guaranteeing that a curator-signed LendBid can never bypass the pool's mandate checks by being submitted directly to app.borrowWithBid.

Waterfall and default auction

Every loan funded by DirectEarnPool is backed 80% by Senior principal and 20% by Junior principal (JUNIOR_TRANCHE_BPS):

• On repayment (settleRepaidLoan(groupId)) — Senior receives its principal plus its share of interest net of JUNIOR_YIELD_PREMIUM_BPS (20% of Senior's interest goes to Junior as a risk premium for standing first-loss).
• On default (claimDefaultedLoan(groupId) then buyDefaultedCollateral(groupId, maxPayment)) — once maturity passes unpaid, anyone triggers claimDefaultedLoan and a 24-hour (AUCTION_DURATION) Dutch auction that starts at debt and decays linearly toward 1. Auction proceeds pay Senior's principal + interest first, and any remainder goes to Junior.

DirectSeries: a fixed-term ZCB

A DirectSeries is a self-contained, closed-end credit series with fixed dates that sits on a GroupEngine app as an ordinary lender. It issues two ERC-20 tokens (SeriesToken):

• S_TOKEN (S) — Senior zero-coupon bond with a fixed target raise seniorTarget (S0) and a fixed maturity face value seniorFace (F >= S0).
• J_TOKEN (J) — Junior first-loss equity with a target raise juniorTarget (J0), entitled to 100% of the excess spread above F and absorbing defaults first.

Before activate(), SeriesToken transfers are locked (SeriesNotActive); once activate() succeeds, S and J are freely transferable ERC-20 tokens.

Lifecycle phases

The SeriesMath waterfall and four disclosure scenarios

At finalize(), SeriesMath.splitWaterfall(totalCash, unsoldCollateral, seniorFace, priceFloor, unit, hasDefault) computes the exact allocation between Senior S and Junior J:

1. Cash first to Senior — seniorCash = min(totalCash, seniorFace), juniorCash = totalCash - seniorCash.
2. Collateral shortfall cover at priceFloor — if seniorCash < seniorFace and unsoldCollateral > 0, the unpaid Senior shortfall seniorFace - seniorCash is converted into collateral at priceFloor (rounded up in Senior's favor via mulDivCeil, capped at unsoldCollateral). Junior receives any remaining unsoldCollateral.

Because no oracle is used, DeployDirectSeries.s.sol and the v3.cai.finance Earn Pro view compute and display four deterministic disclosure scenarios directly from the 24 immutable Terms:

0. 0. Zero deployment (all idle) — 0% lent; Senior receives min(S0 + J0, F) (the idle subsidy F - S0 is paid out of Junior's principal and capped at maxIdleSubsidy <= J0).
1. 1. Disclosed deployment, repaid at min APR — disclosedDeployBps of the pool lent at minAprBps and repaid in full; Senior receives full F in cash and Junior receives J0 + net interest.
2. 2. Disclosed deployment, 100% default at floor — disclosedDeployBps lent at maxDebtPerUnit and 100% defaulted at priceFloor.
3. 3. Worst case (max deployable), 100% default at floor — maximum deployable capital (min(100%, maxLoans * maxLoanBps)) lent at maxDebtPerUnit and 100% defaulted at priceFloor.

Configuration floors

• Every time window (fundingDeadline - now, investmentDeadline - fundingDeadline, gracePeriod, recoveryDeadline - maturity - gracePeriod, maxInvestmentWindow) must be >= MIN_WINDOW (1 hour).
• Loan term maturity - investmentDeadline must be >= MIN_LOAN_TERM (7 days), ensuring minAprBps always accrues over at least one week.
• seniorFace - seniorTarget <= maxIdleSubsidy <= juniorTarget.

On Sepolia, the canonical DirectSeries (0x9a3762FfcDA752EabA3d2b1BbFefBD2e8751f772, with S_TOKEN 0xc786346B585186B36763C49C20c2b6CB66cb0474 and J_TOKEN 0xC3827f27a4ee42d2e749D02678c98524ED7B3cba) was deployed from bivium-tbv-direct@bd7e8a8 with a 27-day loan window ($100,000 Senior target, $105,000 Senior face, $25,000 Junior target, 8.00% min APR, $60,000 max debt/BTC).