11 / 14 · docs

Architecture

how the bell is built.

The planned contracts and the flow of one night, from deposit to settlement.

simulation Simulation only. The protocol is not live. No transaction is ever sent.

This page describes the planned system. No contract is deployed and none has been written or audited. Names, boundaries and interfaces can change.

Contracts overview#

Five contracts, each with one job.

Planned contracts (none deployed)
Contract	Role	Address
`EvePool`	ERC-4626 style USDC vault. Pays advances, receives sale proceeds, holds depositor shares, parks idle USDC on Morpho.	not deployed todo
`EveSettlement`	Reads Chainlink after the open, averages the fresh price, runs the TWAP sale, computes each balance.	not deployed todo
`EveGuard`	Night-time checks: market closed, earnings calendar, corporate actions, per-ticker volume cap.	not deployed todo
`EveReserve`	Holds the reserve share of fees. Pays the pool when a gap exceeds the haircut.	not deployed todo
`EveStaking`	Staked $EVE and the stakers' share of fees.	not deployed todo

They rely on three external systems:

System	Used for
Chainlink price feeds	The reference price at night and the fresh price at the open. See Oracles.
A decentralized exchange on Base	Selling the night's stocks over the TWAP window.
Morpho	Holding idle USDC between sessions.

One night, from deposit to settlement#

drawing the diagram…

A night: the seller is paid an advance after the close; at the open the pool sells, the price is fixed, and the balance is paid.

The same night in words:

Deposit. After the close, the seller deposits tokenized stock into the pool.
Checks. The guard confirms the market is closed, the ticker is not blocked (earnings, corporate action) and tonight's volume cap has room.
Reference price. The pool reads the Chainlink feed, which is frozen at the closing price.
Advance. The pool pays the seller 90% of the reference value in USDC.
Night. Nothing happens until the next open.
Fresh price. After the bell, the settlement contract waits for the first fresh Chainlink round and averages the rounds in the window.
Sale. The pool sells the stock on a DEX in equal slices over 30 minutes.
Settlement. The settlement price is the lower of the oracle average and the realized TWAP. The balance is the settled value, minus the fee, minus the advance.
Distribution. The seller receives the balance. The fee is split between depositors, the reserve, stakers and buybacks.
Backstop. If the gap was larger than the haircut, the reserve pays the pool's shortfall.

The life of a sale#

drawing the diagram…

States of one sale.

Off-chain parts#

Not everything can live in a contract.

Part	What it does	Status
Keeper	Starts settlement after the open and executes the TWAP slices.	not decided todo
Events calendar	Supplies earnings dates and corporate actions to the guard.	not decided todo
Market calendar	NYSE holidays and early closes. Computed by rule, with unscheduled closures added by hand.	Implemented in this site's code
Governance	Changes parameters and upgrades contracts.	not decided todo

Each off-chain part is a point of trust or failure, and is listed as such in Risk and safeguards.

Parameters the contracts will hold#

Parameter	Value
Advance rate	90%
Earnings advance rate	75%
Fee per night	0.25%
Oracle window	10 min todo
TWAP window	30 min
Staleness limit	120 s todo
Volume cap	5% of depth todo
Pool utilization ceiling	not decided todo

How this site models it#

The site has no contracts to call, so it models the protocol in TypeScript. The model is a small, pure module with no dependency on React, the network or the system clock:

src/lib/protocol/
  time.ts         New York wall-clock time, daylight saving by rule
  calendar.ts     NYSE holidays, early closes, sessions
  clock.ts        market status, nights, bells, the countdown
  fees.ts         the per-night fee and the fee split
  settlement.ts   the sell quote, oracle averaging, TWAP, settlement
  prices.ts       seeded simulated opens (not market data)
  sim.ts          the simulator: a reducer and a ledger
  examples.ts     the worked examples in these docs

The simulator, the countdown and every worked example on these pages call this module. It is covered by unit tests, which are the closest thing to a specification the protocol has today.

npm test

All parameters are read from one file, src/eve.config.ts.