Aave V4 101: Building a Custom Spoke

Introduction

Aave V4 introduces a Hub and Spoke architecture where the Hub serves as the central liquidity layer and Spokes connect to it to access that liquidity.

The Hub stores assets, manages share-based accounting, and accrues interest. Each asset is identified by an assetId, and Spokes register on a per-asset basis with configured supply and borrow caps.

Any contract can become a Spoke without implementing a specific interface or inheriting from a base contract. Lending markets, swap contracts, treasuries, vaults, RWA integrations... The Hub doesn't impose constraints on internal logic.

Registering a Spoke

Before a Spoke can interact with the Hub, governance registers it via addSpoke. Registration is per-asset, so a Spoke working with both USDC and WETH needs two separate registrations with potentially different configurations.

The registration includes a SpokeConfig that defines operational limits:

struct SpokeConfig {
  uint40 addCap;              // max supply (whole units)
  uint40 drawCap;             // max borrow (whole units)
  uint24 riskPremiumThreshold; // max premium-to-debt ratio (BPS)
  bool active;
  bool paused;
}

These caps determine how much Hub liquidity a Spoke can access. A treasury that only collects fees might have a high addCap but zero drawCap. A lending market needs both. Setting either to type(uint40).max removes the limit. Governance can adjust these via updateSpokeConfig as conditions change.

Interacting with the Hub

Once registered, a Spoke interacts with the Hub through a set of operations. The Hub tracks everything in SpokeData:

struct SpokeData {
  uint120 addedShares;      // shares from supplying
  uint120 drawnShares;      // shares from borrowing
  uint120 premiumShares;    // risk premium interest shares
  int200 premiumOffsetRay;  // premium calculation offset
  uint200 deficitRay;       // reported bad debt
  // ... plus config fields (addCap, drawCap, etc.)
}

Spokes don't manage this state directly, the Hub updates it based on which methods are called.

Core Operations

Supply and borrow flows. Note the pattern: add and restore require transferring tokens to the Hub first, while remove and draw have the Hub transfer out.

Method	Purpose
`add`	Supply assets and receive shares. Transfer tokens to Hub first, then call
`remove`	Redeem shares for supplied assets plus accrued interest
`draw`	Borrow from Hub liquidity. Returns drawn shares tracking the debt
`restore`	Repay drawn shares (principal) plus accrued premium. Transfer tokens to Hub first

Bad Debt & Fees

When debt becomes unrecoverable, it needs to be reported and eventually covered. These methods handle that lifecycle and protocol fee collection.

Method	Purpose
`reportDeficit`	Report unrecoverable debt as bad debt
`payFeeShares`	Transfer shares to the protocol's fee receiver
`eliminateDeficit`	Burn supplied shares to cover bad debt

Risk premium adds extra interest based on collateral quality. Share transfers enable moving positions between Spokes without withdrawing.

Method	Purpose
`refreshPremium`	Update the Hub's premium accounting when a user's collateral composition changes
`transferShares`	Move supplied shares to another registered Spoke. Enables migrations without withdraw/re-deposit

View Functions

Query current balances and debt before making decisions.

Method	Returns
`getSpokeAddedAssets`	Total supplied assets converted from shares at current rate, includes accrued interest
`getSpokeAddedShares`	Raw supply shares. Multiply by share price to get asset value
`getSpokeTotalOwed`	Total debt in assets: principal plus accrued premium
`getSpokeDrawnShares`	Raw debt shares. Multiply by drawn index to get principal owed
`getSpokeDeficitRay`	Bad debt reported via `reportDeficit`, scaled by RAY (1e27)

ℹ️

The Hub validates every call: is the Spoke registered? Active? Within caps? It also accrues interest before processing, ensuring up-to-date values.

Next Steps

The best way to see these methods in action is Aave's own Spoke.sol, a full lending implementation with collateral management, liquidations, and risk premium calculations. It demonstrates how a production Spoke orchestrates Hub calls, manages user positions, and handles edge cases like bad debt.

A deep dive into that implementation is coming in a future post.