Compound V3 — Comet

MODULE 00 Architecture & why V3

The single-base-asset model, isolated collateral, account-level accounting — and the V2 problem each one solves.

The one-sentence mental model

A Compound V3 market (called a Comet) is a pool of one borrowable asset — the base asset (e.g. USDC) — that lenders supply and borrowers take out against a basket of isolated, non-yielding collateral assets. That's it. Everything else is bookkeeping on top of that single idea.

The four design pillars

Contract layout (reference implementation)

• Comet.sol — the main implementation: supply / withdraw / borrow / absorb / buyCollateral, accrual, health checks. Sits behind a TransparentUpgradeableProxy.
• CometCore.sol — internal math/accounting primitives: presentValue*, principalValue*, mulFactor, shared constants.
• CometStorage.sol — the storage layout (structs & mappings).
• CometMath.sol — safe casts (signed104, unsigned104, …) for moving between signed/unsigned without silent overflow.
• CometMainInterface.sol / CometInterface.sol — external interface, events, custom errors (Paused, NotCollateralized, NotLiquidatable, BorrowTooSmall, SupplyCapExceeded, …).
• CometExt.sol — an extension delegate. Because Comet is near the 24 KB EVM contract-size limit, some functions (ERC-20 metadata, allowances) are delegatecalled to CometExt via the fallback. So the "Comet you interact with" is really proxy → Comet implementation → (fallback) → CometExt.
• Configurator.sol + CometFactory.sol + CometProxyAdmin.sol — the upgrade/config pipeline. Per-asset config is compiled into the implementation as immutable variables, so changing a collateral factor means deploying a brand-new Comet implementation and re-pointing the proxy.
• CometRewards.sol — a separate contract for COMP distribution (Module 13).

MODULE 01 Scales & helper math

The fixed-point constants and the three multiply helpers that every other formula is built on.

The scale constants

Solidity has no floats. Comet represents fractions as integers multiplied by a fixed scale. Get these wrong and every downstream number is off by orders of magnitude.

Helper 1 — mulFactor

It multiplies a number by a ratio that's stored ×1e18 and divides the scale back out. Floor division (Solidity default for unsigned).

Helper 2 — mulPrice / signedMulPrice

Result is a USD value scaled by 1e8. The signed variant keeps the sign of q (needed for the negative base principal of a borrower).

Helper 3 — divBaseWei

Used inside reward-index updates (Module 13): it divides an emission by a pool size while preserving baseScale precision.

MODULE 02 Storage layout

Every packed global slot, the per-user struct, the collateral structs, and the immutables — with the bit-packing arithmetic.

The two packed global slots

Comet packs its hottest globals into two storage slots so a single SLOAD fetches several values. The TotalsBasic struct:

struct TotalsBasic {
    uint64  baseSupplyIndex;      // ×1e15, grows with supply interest
    uint64  baseBorrowIndex;      // ×1e15, grows with borrow interest
    uint64  trackingSupplyIndex;  // ×1e15, COMP accrual for suppliers
    uint64  trackingBorrowIndex;  // ×1e15, COMP accrual for borrowers
    uint104 totalSupplyBase;      // total positive principal
    uint104 totalBorrowBase;      // total negative principal (stored positive)
    uint40  lastAccrualTime;      // unix seconds of last accrue()
    uint8   pauseFlags;           // bitfield of pause toggles
}

The four uint64 indices fit one slot (4×64 = 256 bits). The two uint104 totals + uint40 time + uint8 flags fit the next (104+104+40+8 = 256 bits). Exact packing — no wasted bits.

The per-user struct — UserBasic

struct UserBasic {
    int104  principal;           // SIGNED: + = lender, − = borrower
    uint64  baseTrackingIndex;   // snapshot of trackingIndex at last update
    uint64  baseTrackingAccrued; // COMP banked but unclaimed (6-dec scaled)
    uint16  assetsIn;            // bitmap: which collateral assets are enabled
    uint8   _reserved;
}

The single int104 principal is the heart of V3: one signed number replaces V2's separate supply and borrow balances. assetsIn is a 16-bit bitmap — bit i set ⇔ the user holds collateral asset i — so health checks iterate only the assets actually held.

Collateral structs

struct UserCollateral   { uint128 balance; uint128 _reserved; }
struct TotalsCollateral { uint128 totalSupplyAsset; uint128 _reserved; }
struct LiquidatorPoints { uint32 numAbsorbs; uint64 numAbsorbed; uint128 approxSpend; uint32 _reserved; }

The mappings

• mapping(address => UserBasic) userBasic — each account's signed base position.
• mapping(address => mapping(address => UserCollateral)) userCollateral — per-user, per-asset collateral.
• mapping(address => mapping(address => bool)) isAllowed — operator permissions (Module 8).
• mapping(address => LiquidatorPoints) liquidatorPoints — keeper stats.
• mapping(address => TotalsCollateral) totalsCollateral — protocol-wide per-asset collateral.

Immutables (baked into bytecode)

baseToken, baseTokenPriceFeed, baseScale, numAssets, decimals, extensionDelegate (the CometExt address), every rate-model parameter, baseTrackingSupplySpeed / baseTrackingBorrowSpeed, storeFrontPriceFactor, targetReserves, baseBorrowMin, baseMinForRewards, trackingIndexScale, and the packed asset configs read via getAssetInfo(i) / getPackedAssetInternal. None of these cost an SLOAD — they're constants in code.

MODULE 03 Accounting primitives

principal ↔ present value, the asymmetric rounding, and why borrow debt rounds up.

The core idea

A user's stored principal is frozen at the index value when they last touched the protocol. Their present value — what they actually owe or own right now — is recovered by scaling that principal by how much the relevant index has grown since.

Present value (principal → present)

Principal value (present → principal) — the inverse, with a twist

Derivation of the ceiling trick

For positive integers, ⌈a/b⌉ = ⌊(a + b − 1)/b⌋. Proof: write a = qb + r with 0 ≤ r < b. If r = 0, (a+b−1)/b = q + (b−1)/b floors to q = a/b. If r > 0, a + b − 1 = qb + (r + b − 1) and since b ≤ r + b − 1 < 2b, the floor is q + 1 = ⌈a/b⌉. ∎

MODULE 04 Interest rate model

The kinked utilization curve, per-second compounding, the supply/borrow spread, and the implicit reserve factor.

Utilization — the input to everything

U ∈ [0, 1] in principle (1e18-scaled on-chain). At U = 0 nobody's borrowing; near U = 1 the pool is fully lent out and withdrawals can fail.

The kinked rate curves

Both supply and borrow rates are piecewise-linear in U with a single kink. Below the kink the slope is gentle; above it, steep — punishing high utilization so the pool keeps a withdrawal buffer.

Per-year ↔ per-second conversion

Governance configures rates per year; the contract stores them per second as immutables:

APR vs APY

Comet's index advances by a simple per-second rate inside each accrual gap (Module 5), but because gaps are tiny and frequent, the realized return compounds — so the APY a borrower truly pays is a touch above the quoted APR.

The spread → the implicit reserve factor

Borrowers pay r_b; suppliers receive r_s < r_b. The protocol keeps the difference as reserves. There's no explicit "reserveFactor" variable in V3 — it's implied by the gap between the two curves:

MODULE 05 Accrual engine

Lazy accrual, the index-update formula, the four indices, getReserves as a derived identity, and a live index trace.

"Lazy" accrual

Comet does not update interest every block. It stores lastAccrualTime and, whenever someone touches the protocol, computes the elapsed seconds and fast-forwards all four indices in one shot. Between touches, the stated balances are stale but the true balances are recoverable by re-deriving the indices.

The index update

Each index is multiplied by (1 + rate·Δt) — a simple per-second rate applied to the current index. Because the index itself already embeds past growth, applying simple interest to it repeatedly produces compounding across gaps. Utilization U is read once at the start of the gap, so the model is exact w.r.t. utilization within an unbroken interval; the only approximation is simple-vs-compound inside that single gap.

The four indices & what they bank

getReserves() as a derived identity

Reserves aren't stored — they're computed on demand as cash minus net liabilities. They can be negative (bad debt). We return to this in Module 12.

MODULE 06 Supply path

supply / supplyTo / supplyFrom, the base-vs-collateral branch, repayAndSupplyAmount, caps, and fee-on-transfer handling.

Entry points

supply(asset, amount), supplyTo(dst, asset, amount), supplyFrom(from, dst, asset, amount) all funnel into supplyInternal, gated by hasPermission(from, operator). The internal branches on whether asset == baseToken.

Base supply — the repay-then-supply split

If you supply the base asset while you currently owe base (negative principal), the deposit first repays the debt and only the surplus becomes new supply. That split is repayAndSupplyAmount:

Mechanically: convert amount to a principal delta, add it to the signed principal (which may cross zero from negative to positive), update totalBorrowBase down by the repaid part and totalSupplyBase up by the supplied part.

doTransferIn & fee-on-transfer

doTransferIn measures the contract's balance before and after the transferFrom and credits the actual received amount — so a fee-on-transfer token credits only what truly arrived, never the requested amount.

function doTransferIn(address asset, address from, uint amount) internal returns (uint) {
    uint preBalance  = IERC20(asset).balanceOf(address(this));
    IERC20(asset).safeTransferFrom(from, address(this), amount);
    uint postBalance = IERC20(asset).balanceOf(address(this));
    return postBalance - preBalance;   // actual received, fee-on-transfer safe
}

Collateral supply

supplyCollateral increments userCollateral[user][asset].balance and totalsCollateral[asset], checks the supplyCap (revert SupplyCapExceeded), sets the asset's bit in assetsIn via updateAssetsIn, and is blocked when isSupplyPaused. Collateral never touches the base indices — it earns no interest.

MODULE 07 Withdraw / borrow path

There is no borrow function — borrowing is withdrawing base past zero. The split, the min-borrow floor, and the post-action health gate.

The unifying insight

V3 has no borrow(). You call withdraw(baseToken, amount); if you have supply it comes out of supply, and if you withdraw beyond your supply your principal goes negative — that negative balance is the loan. One function, one signed number.

The withdraw-then-borrow split

The withdraw part reduces totalSupplyBase; the borrow part increases totalBorrowBase. The signed principal can cross zero from positive to negative.

Two guards on borrowing

• baseBorrowMin — if the resulting borrow present value is below this floor, revert BorrowTooSmall. This stops dust borrows that would be unprofitable to ever liquidate.
• isBorrowCollateralized (Module 9) — checked after the action; if the account isn't collateralized post-withdraw, the whole call reverts NotCollateralized.

Collateral withdrawal

withdrawCollateral decrements userCollateral, runs the collateralization check on the source account, and clears the asset's assetsIn bit when the balance hits zero. doTransferOut sends the tokens; a base withdrawal is also liquidity-limited — you can't withdraw cash the pool doesn't physically hold.

MODULE 08 Transfers & permissions

The ERC-20 base surface, collateral transfers with a health check, and the boolean operator model via allow / allowBySig (EIP-712).

Base transfers

transfer / transferFrom on the base asset route to transferBase: the source principal decreases, the destination increases. A base transfer can therefore create a borrow on the sender (if they send more than they hold) — so it runs the same collateralization gate as a withdrawal.

Collateral transfers

transferAsset / transferAssetFrom → transferCollateral: moves userCollateral from src to dst and then checks isBorrowCollateralized(src) — you can't transfer away collateral that's backing your own loan.

The permission model (boolean, not allowance)

Unlike ERC-20 numeric allowances, Comet uses a boolean operator model: isAllowed[owner][operator] is simply true/false. An approved operator can act on the owner's entire position. Set it with allow(operator, bool) or off-chain via signature with allowBySig.

// EIP-712 typed-data authorization (gasless approval)
bytes32 internal constant AUTHORIZATION_TYPEHASH = keccak256(
    "Authorization(address owner,address manager,bool isAllowed,uint256 nonce,uint256 expiry)"
);

function allowBySig(
    address owner, address manager, bool isAllowed_,
    uint256 nonce, uint256 expiry, uint8 v, bytes32 r, bytes32 s
) external {
    require(uint256(s) <= 0x7FFF...A0, "invalid value s");   // malleability guard
    require(v == 27 || v == 28, "invalid value v");
    bytes32 structHash = keccak256(abi.encode(AUTHORIZATION_TYPEHASH, owner, manager, isAllowed_, nonce, expiry));
    bytes32 digest = keccak256(abi.encodePacked("\x19\x01", DOMAIN_SEPARATOR(), structHash));
    address signatory = ecrecover(digest, v, r, s);
    require(signatory != address(0) && owner == signatory, "bad signatory");
    require(nonce == userNonce[signatory]++, "bad nonce");
    require(block.timestamp < expiry, "signature expired");
    isAllowed[owner][manager] = isAllowed_;
}

The s-value and v checks are the standard ECDSA malleability guards — without them a second valid signature could be forged from a known one. The nonce is consumed monotonically to prevent replay; expiry bounds the signature's lifetime.

MODULE 09 Collateralization & health

The two health inequalities, the signed-liquidity summation, the early-exit loop, and Alice's exact liquidation price.

Two factors, two thresholds

Every collateral asset has two governance-set factors, both ×1e18: the borrow collateral factor f_i^b (the action gate) and the liquidate collateral factor f_i^l (the seizure trigger), with f_i^b < f_i^l always — leaving a deliberate buffer band.

isBorrowCollateralized is the action gate (must hold after borrowing or withdrawing collateral). isLiquidatable is the trigger. The loop walks the assetsIn bitmap, accumulating signed liquidity, and early-exits the instant liquidity turns positive — so a well-covered account never even reads the later oracles.

Worked example — Alice, and her exact liquidation price

Alice: 10 WETH collateral, present borrow $5,000 (USDC base). WETH BCF = 0.83, LCF = 0.90. Scales: WETH 1e18, baseScale 1e6, PRICE_SCALE 1e8, FACTOR_SCALE 1e18.

base:  signedMulPrice(-5e9, 1e8, 1e6) = -5e9 × 1e8 / 1e6 = -5e11        (= -$5,000)
WETH:  mulPrice(10e18, 3000e8, 1e18) = 10e18 × 3e11 / 1e18 = 3e12       (= $30,000)
 BCF:  mulFactor(3e12, 0.83e18) = 3e12 × 0.83 = 2.49e12                 (= $24,900)
 LCF:  mulFactor(3e12, 0.90e18) = 3e12 × 0.90 = 2.70e12                 (= $27,000)

isBorrowCollateralized: liquidity = -5e11 + 2.49e12 = 1.99e12 = $19,900 ≥ 0 → TRUE
isLiquidatable:         liquidity = -5e11 + 2.70e12 = 2.20e12 = $22,000 ≥ 0 → FALSE

Multi-asset behavior (aggregate + early exit)

Give Alice 10 WETH ($3,000) and 0.5 WBTC ($60,000), same $5,000 borrow:

i=0 WETH: liquidity -$5,000 < 0 → price it: $30,000 × 0.83 = $24,900 → liquidity = $19,900
i=1 WBTC: liquidity $19,900 ≥ 0 → EARLY EXIT (return true). WBTC oracle is NOT read.

Health is the aggregate of all collateral, but the loop stops once positive. Conversely, if WETH alone crashed, the loop continues to WBTC and adds its value — so one asset tanking doesn't liquidate Alice if her other collateral covers the debt.

MODULE 10 Liquidation · phase 1: absorb()

Seizing an underwater position, the liquidationFactor haircut, the bad-debt clamp, and the reserve impact.

What absorb does

Liquidation in V3 is two phases. Phase 1 — absorb(absorber, accounts[]) — lets anyone hand an underwater account to the protocol: the protocol clears the borrower's debt, seizes all their collateral into protocol reserves, and credits the borrower with any surplus as a base supply balance. No keeper capital is needed here; the protocol takes the position onto its own book.

The math

• V_i — USD value of seized collateral asset i
• f_i^l — the liquidationFactor (a haircut, distinct from LCF in some configs) applied when valuing seized collateral
• If the haircut collateral value exceeds the debt, the borrower keeps the surplus as base supply; if it falls short, the shortfall becomes protocol bad debt.

Bookkeeping & LiquidatorPoints

The absorber's liquidatorPoints[absorber] increments (numAbsorbs++, numAbsorbed += value, approxSpend += gas) — a reputation/accounting record. userCollateral and totalsCollateral zero out for the seized account; totalSupplyBase/totalBorrowBase adjust. Blocked when isAbsorbPaused.

MODULE 11 Liquidation · phase 2: buyCollateral()

The store-front discount, the storeFrontPriceFactor split, keeper profit, partial buys, and unsold collateral.

What buyCollateral does

Phase 2 sells the seized collateral to keepers at a discount, in exchange for base asset — recapitalizing reserves. A keeper calls buyCollateral(asset, minAmount, baseAmount, recipient): pays baseAmount of base in (doTransferIn), receives discounted collateral out (doTransferOut), with minAmount as a slippage guard. Blocked when isBuyPaused.

The discount math

Partial buys & unsold collateral

Partial: a keeper can buy any slice — e.g. 4 WETH for 4×530.75 = $2,123 (set minAmount = 3.98e18 for slippage). The other 6 WETH stays in getCollateralReserves(WETH) for the next buyer. Unsold: if nobody buys, the collateral simply sits in reserves indefinitely — base reserves remain depressed (or negative in the bad-debt case) until a keeper finds the spread profitable.

MODULE 12 Reserves & protocol accounting

getReserves as a live equity identity, how every action moves it, targetReserves as a recapitalization throttle, and withdrawReserves.

Reserves are derived, not stored

Cash held minus net base owed to users. It can be negative (bad debt). Collateral reserves are tracked separately by getCollateralReserves(asset) and are invisible to this base-only number until sold.

targetReserves — the counter-cyclical throttle

if (reserves >= 0 && uint(reserves) >= targetReserves) revert NotForSale();

Collateral is for sale only when base reserves are below targetReserves (or negative). The store front recapitalizes — once reserves are back at target, it closes. So the discount turns on precisely when the protocol needs base, and off in calm, well-reserved times. The check is at entry, so one large buy that overshoots target is allowed; the next call reverts.

withdrawReserves — three guards

Governor-only; cannot withdraw when reserves are negative (you can't harvest bad debt); cannot withdraw more than current reserves. It moves base only — collateral reserves are realized through buyCollateral or managed by governance separately. No Comet-level event; observers watch the base token's Transfer.

absorb:        Δbase reserves = -Δsupply + Δborrow = -115 + (-5,000) = -$5,115   (FALL)
               Δcollateral reserves(WETH) = +10 WETH
buyCollateral: keeper pays $5,307.50 base, receives 10 WETH
               Δbase reserves = +$5,307.50 ; Δcollateral reserves(WETH) = -10 WETH
NET:           base reserves +$192.50 ; collateral reserves 0

absorb:        deltaValue = 4,000×0.93 = $3,720 ; newBalance = -5,000+3,720 = -$1,280 → clamp 0
               Δbase reserves = -0 + (-5,000) = -$5,000   ;  Δcollateral(WETH) = +10 WETH ($4,000 mkt, invisible)
buyCollateral: discountedPrice = 400×(1-0.035)=$386 ; keeper pays $3,860 for 10 WETH
               Δbase reserves = +$3,860 ; collateral → 0
NET:           base reserves -$1,140

MODULE 13 COMP rewards

The two-stage tracking-index pipeline, the MasterChef reward-debt pattern, the rescaleFactor, and the fixed-pie emission property.

Two stages: accrue in Comet, claim in CometRewards

Comet itself only advances trackingSupplyIndex / trackingBorrowIndex and banks each user's baseTrackingAccrued. The actual COMP transfer happens in the separate CometRewards contract on claim(). COMP is never minted on claim — it's paid from a DAO-funded balance held by CometRewards.

The tracking index update

if (totalSupplyBase >= baseMinForRewards)
    trackingSupplyIndex += safe64(divBaseWei(baseTrackingSupplySpeed * timeElapsed, totalSupplyBase));
if (totalBorrowBase >= baseMinForRewards)
    trackingBorrowIndex += safe64(divBaseWei(baseTrackingBorrowSpeed * timeElapsed, totalBorrowBase));

Per-user accrual — the MasterChef reward-debt pattern

Each user stores a snapshot baseTrackingIndex (their "reward debt"). When their principal changes, the protocol banks the delta between the global index and their snapshot, then re-snapshots — exactly the MasterChef accounting that lets one global index serve all users in O(1).

The fixed-pie property (derivation)

Sum the per-user accrual over all suppliers (Σ principal = totalSupplyBase):

The totalSupplyBase cancels — the speed alone determines total emission; pool size only sets each person's slice. Double the pool and the pie is unchanged (each supplier earns half per dollar); double the speed and everyone's rewards double.

rescaleFactor

Accrued tracking units are 6-decimal-scaled (matching base); COMP is 18-decimal. CometRewards applies a rescaleFactor on claim to upscale 6→18 decimals so the right COMP amount transfers. Distribution is timestamp-driven per second (not per block), so emission is consistent across chains with different block times.

MODULE 14 Pause guardian & flags

The pauseFlags bitfield, the five independently-toggleable actions, and how each check reads a single bit.

One byte, five switches

Comet packs five pause toggles into the single uint8 pauseFlags field of TotalsBasic. A guardian (or governance) can freeze any subset of actions independently — e.g. pause borrowing during an oracle incident while still allowing repayment.

uint8 internal constant PAUSE_SUPPLY_OFFSET   = 0;
uint8 internal constant PAUSE_TRANSFER_OFFSET = 1;
uint8 internal constant PAUSE_WITHDRAW_OFFSET = 2;
uint8 internal constant PAUSE_ABSORB_OFFSET   = 3;
uint8 internal constant PAUSE_BUY_OFFSET      = 4;

function pause(bool supplyPaused, bool transferPaused, bool withdrawPaused,
               bool absorbPaused, bool buyPaused) external {
    require(hasPermission(msg.sender) || msg.sender == pauseGuardian, "Unauthorized");
    totals.pauseFlags =
        uint8(0)
        | (toUInt8(supplyPaused)   << PAUSE_SUPPLY_OFFSET)
        | (toUInt8(transferPaused) << PAUSE_TRANSFER_OFFSET)
        | (toUInt8(withdrawPaused) << PAUSE_WITHDRAW_OFFSET)
        | (toUInt8(absorbPaused)   << PAUSE_ABSORB_OFFSET)
        | (toUInt8(buyPaused)      << PAUSE_BUY_OFFSET);
}

function isSupplyPaused() public view returns (bool) {
    return toBool(totals.pauseFlags & (uint8(1) << PAUSE_SUPPLY_OFFSET));
}

Each entry point begins with its guard: supplyInternal checks isSupplyPaused, withdrawInternal checks isWithdrawPaused, absorb checks isAbsorbPaused, buyCollateral checks isBuyPaused, transfers check isTransferPaused. Note that repaying is a supply of base — so pausing supply also pauses repayment, a deliberate consideration in incident response.

MODULE 15 Price feeds & oracles

getPrice, the 8-decimal Chainlink convention, the base price feed, and staleness considerations.

The price surface

Every priced asset (each collateral and the base token) has an immutable priceFeed address. Comet reads it through getPrice(priceFeed), which calls the feed's latestRoundData() and returns the answer as a uint scaled by PRICE_SCALE = 1e8 — the Chainlink USD convention.

function getPrice(address priceFeed) public view returns (uint256) {
    (, int256 price, , , ) = IPriceFeed(priceFeed).latestRoundData();
    if (price <= 0) revert BadPrice();
    return uint256(price);   // already 1e8-scaled; feeds are validated at config time
}

Why 1e8 everywhere

Standardising on 1e8 means mulPrice (Module 1) can combine any token balance with any feed without per-asset scale juggling: USD_value = q · p / scale, where p is always 1e8 and scale is the token's own decimals. The base token also has its own baseTokenPriceFeed so a non-USD base (rare) is still priced.

MODULE 16 Config & upgrade pipeline

Why parameters are immutables, the Configurator → Factory → ProxyAdmin flow, and the Configuration struct.

Immutables, not storage

Recall from Module 0: per-asset risk parameters are compiled into the Comet implementation as immutable variables, baked into bytecode. Reads cost no SLOAD — but changing any parameter means deploying a brand-new implementation. This is the structural reason a "governance parameter change" in V3 is a redeploy, not a storage write.

The pipeline

governance
   │  setConfiguration(...) / updateAsset(...)        on Configurator.sol
   ▼
Configurator  ──holds──►  Configuration struct (the editable params, in storage)
   │  deploy()
   ▼
CometFactory  ──clone──►  new Comet implementation (params baked as immutables)
   │  returns address
   ▼
CometProxyAdmin.upgrade(proxy, newImpl)   ◄── proxy now points at the new code
   │
   ▼
TransparentUpgradeableProxy  →  users keep the same Comet address & storage

The Configuration struct (in CometConfiguration.sol) holds the editable source of truth: governor, pauseGuardian, baseToken, baseTokenPriceFeed, the rate-model params, the per-asset AssetConfig[] (priceFeed, decimals, borrowCF, liquidateCF, liquidationFactor, supplyCap), storeFrontPriceFactor, targetReserves, the tracking speeds, etc. Configurator reads this and CometFactory compiles it into a fresh implementation.

MODULE 17 CometExt & the ERC-20 surface

The delegatecall extension that dodges the size limit, and the ERC-20 view surface it serves.

The size-limit problem

The EVM caps deployed contracts at 24,576 bytes (EIP-170). Comet's core logic alone nearly fills that, so the ERC-20 niceties — name, symbol, decimals, totalSupply, balanceOf, allowance, approve — are moved into a companion contract, CometExt, reached via the fallback.

// Comet's fallback delegatecalls unknown selectors to the extension
fallback() external payable {
    address delegate = extensionDelegate;   // immutable CometExt address
    assembly {
        calldatacopy(0, 0, calldatasize())
        let result := delegatecall(gas(), delegate, 0, calldatasize(), 0, 0)
        returndatacopy(0, 0, returndatasize())
        switch result
        case 0 { revert(0, returndatasize()) }
        default { return(0, returndatasize()) }
    }
}

Because it's delegatecall, CometExt executes against Comet's storage — so balanceOf there reads the same userBasic mapping. The "Comet" address you interact with is functionally proxy → Comet → (fallback) → CometExt.

What the ERC-20 surface reports

• balanceOf(account) — the account's present-value supply (positive principal × supply index); a borrower reads 0 here.
• borrowBalanceOf(account) — the present-value borrow (the magnitude of negative principal).
• totalSupply() — PV_supply(totalSupplyBase); totalBorrow() the borrow side.
• decimals() — the base token's decimals; the Comet "token" mirrors the base asset.

MODULE 18 Rounding & precision

Every rounding direction in one place, why each protects reserves, and the signed-cast guards.

The rounding ledger

The single invariant behind every row: round so the protocol is never short. Credited collateral and supply round down; recorded debt rounds up. The asymmetry is deliberate and is what stops dust from leaking value over millions of operations.

The ceiling identity (re-derived)

Used only on the borrow principal. Everywhere else Solidity's native floor division already gives the protective direction.

Signed-cast guards (CometMath)

Because principal is int104 but many intermediates are unsigned, Comet uses explicit safe casts — signed104, unsigned104, signed256, safe64 — each of which reverts on overflow instead of silently wrapping. This matters at zero-crossings (a repay turning a borrow into a supply) where a naive cast could flip sign catastrophically.

MODULE 19 Attack vectors & edge cases

The donation edge, oracle-manipulation resistance, dust borrows, utilization extremes, paused states, and partial absorbs — collected with numbers.

Oracle manipulation — bounded by isolation

V3's biggest structural defense: collateral is isolated. A manipulated feed on one collateral asset only affects positions using that asset, and the borrow collateral factor (< 1) plus the liquidation buffer cap how much value a single bad print can extract. Compare V2, where a manipulated borrowable asset could drain the shared pool. The fix isn't perfect feeds — it's blast-radius containment.

The donation edge (benign)

You can inflate balanceOf(Comet) by sending tokens directly. getReserves rises with no offsetting liability — harmless, and useful for topping up a bad-debt market. The takeaway: balance can legitimately exceed what positions imply, so never assume balance == derivable reserves.

Utilization extremes

• U = 0%: getUtilization returns 0; r_s = supplyBase (often 0), r_b = borrowBase. Suppliers earn ~nothing; no reserve accrual.
• U → 100%: the steep upper slope makes borrowing very expensive; withdrawals can fail because the cash is lent out (liquidity-limited doTransferOut). The kink exists precisely to keep U off this edge.
• totalSupply = 0: utilization is defined as 0 to avoid divide-by-zero.

Dust borrows & baseBorrowMin

A loan below baseBorrowMin reverts BorrowTooSmall — tiny positions are uneconomical to liquidate (gas > bounty), so the floor prevents an accumulation of un-cleanable risk.

Paused states & partial absorb

• Pausing supply also pauses repay (repay is a base supply) — incident responders must weigh this.
• absorb always seizes the whole position (there's no partial absorb), but buyCollateral can be partial — keepers take any slice, leaving the rest in reserves.
• If reserves are healthy, buyCollateral reverts NotForSale, so seized collateral can sit unsold while getReserves understates true equity (Module 12).

Reentrancy posture

State mutations (principal, totals, indices) are written before external token transfers (doTransferOut) in the withdraw/buy paths, following checks-effects-interactions. Combined with the boolean operator model (no numeric allowance to race) this limits classic reentrancy surfaces; fee-on-transfer is handled by measuring received amounts (Module 6).