Skip to main content

The covenant queue

CovenantQueue is the protocol's ledger. It owns the accounting and lifecycle of every covenant — amounts, statuses, and FIFO order — and emits every lifecycle event. It never holds funds; custody lives in the vault. Mutations are hook-only.

Because it is the single contract that emits all covenant events, it is the one address you index to reconstruct full protocol state.

The covenant record​

Each covenant freezes its terms at creation:

  • id — sequential identifier.
  • seller — the address whose sell created it (for indexing).
  • tokenAmount — the CVN exit debt.
  • ethValueAtCreation — the reference value used to price absorption.
  • discountBps — the absorption discount, frozen between 5% and 20%.
  • expiresAt — creation time + the covenant duration (7 days).

Mutations (hook-only)​

FunctionCalled duringEffect
create(seller, tokenAmount, ethValue, discountBps)afterSwap (sell)Books a new covenant, returns its id.
absorb(buyer, ethAvailable)beforeSwap (buy)Consumes the FIFO queue at the discounted reference price. Returns tokensOut, ethUsed. Accounting only — the hook delivers tokens / takes ETH.
beginExpire(id)settlement, phase 1Flips a mature Active covenant to Expired, removes it from active accounting.
finalizeExpire(id, tokenAmount, ethPaired, destination)settlement, phase 2Emits CovenantExpired with the real settlement result.

Views (for the dApp and indexers)​

function nextMature() external view returns (bool exists, uint256 id);
function quoteAbsorb(uint256 ethIn) external view returns (uint256 tokensOut, uint256 ethUsed);
function getCovenant(uint256 id) external view returns (Covenant memory);
function covenantCount() external view returns (uint256);
function totalActiveCovenants() external view returns (uint256);
function covenantReserveTokens() external view returns (uint256);
function firstActiveCovenantId() external view returns (uint256);
function expiredLiquidity() external view returns (uint256);
function covenantDuration() external view returns (uint256);
function nextExpiry() external view returns (uint256);

quoteAbsorb is a read-only preview used by the dApp to show a buyer exactly how much CVN their ETH would absorb and at what discount, before they trade.

See the exact event signatures in Events & errors.