RAACMaturityVault¶

Overview¶

RAACMaturityVault is an upgradeable vault that accepts deposits of leRAAC and converts them into claimable RAAC over time as RAAC is distributed into the vault. The vault tracks each user's position as unrealised (still owed) and realised (claimable) amounts, and supports immediate or linear debt paydown depending on configuration.

Purpose¶

Allow users (or other protocol contracts) to deposit leRAAC for maturity conversion
Track maturity debt paydown using an efficient "fraction" accumulator
Convert distributed RAAC into user-claimable balances
Support periodic (linear) distributions with configurable period length
Support whitelisted distribution/harvest callers and protocol fee/bounty settings

Functions¶

User Functions¶

`deposit`¶

deposit(uint256 _amount)

Summary
Deposits leRAAC for the caller.

Access
External

Parameters

Name	Type	Description
_amount	uint256	The amount of leRAAC to deposit

Emits

Deposit(address account, uint256 amount)

JavaScript

// Approve leRAAC spending first
const amount = ethers.parseUnits("1000", 18);
await leRAAC.approve(maturityVaultAddress, amount);

// Deposit leRAAC into the maturity vault
const tx = await maturityVault.deposit(amount);
await tx.wait();

`depositFor`¶

depositFor(address _account, uint256 _amount)

Summary
Deposits leRAAC credited to _account.

Access
External

Parameters

Name	Type	Description
_account	address	The account to credit the deposit to
_amount	uint256	The amount of leRAAC to deposit

Emits

Deposit(address account, uint256 amount)

JavaScript

// Approve leRAAC spending first
const amount = ethers.parseUnits("500", 18);
await leRAAC.approve(maturityVaultAddress, amount);

// Deposit leRAAC on behalf of another account
const recipientAddress = "0x...";
const tx = await maturityVault.depositFor(recipientAddress, amount);
await tx.wait();

`withdraw`¶

withdraw(address _recipient, uint256 _amount)

Summary
Withdraws unrealised leRAAC back to a recipient.

Access
External

Parameters

Name	Type	Description
_recipient	address	The address to receive the withdrawn leRAAC
_amount	uint256	The amount of unrealised leRAAC to withdraw

Emits

Withdraw(address account, address recipient, uint256 amount)

Reverts

InsufficientBalance() — if withdraw amount exceeds unrealised balance

JavaScript

// Withdraw unrealised leRAAC to your own address
const amount = ethers.parseUnits("200", 18);
const tx = await maturityVault.withdraw(myAddress, amount);
await tx.wait();

`withdrawAll`¶

withdrawAll(address _recipient)

Summary
Withdraws all unrealised leRAAC.

Access
External

Parameters

Name	Type	Description
_recipient	address	The address to receive the withdrawn leRAAC

Emits

Withdraw(address account, address recipient, uint256 amount)

JavaScript

// Withdraw all unrealised leRAAC
const tx = await maturityVault.withdrawAll(myAddress);
await tx.wait();

`claim`¶

claim(address _recipient)

Summary
Claims all realised RAAC.

Access
External

Parameters

Name	Type	Description
_recipient	address	The address to receive the claimed RAAC

Emits

Claim(address account, address recipient, uint256 amount)

JavaScript

// Claim all realised RAAC to your address
const tx = await maturityVault.claim(myAddress);
await tx.wait();

`exit`¶

exit(address _recipient)

Summary
Withdraws all unrealised leRAAC and claims all realised RAAC.

Access
External

Parameters

Name	Type	Description
_recipient	address	The address to receive the leRAAC and RAAC

Emits

Withdraw(address account, address recipient, uint256 amount)
Claim(address account, address recipient, uint256 amount)

JavaScript

// Exit the vault completely - withdraw unrealised and claim realised
const tx = await maturityVault.exit(myAddress);
await tx.wait();

`getUserInfo`¶

getUserInfo(address _account) → (uint256 unrealised, uint256 realised)

Summary
Returns unrealised and realised amounts for a user.

Access
External View

Parameters

Name	Type	Description
_account	address	The account to query

Returns

Name	Type	Description
unrealised	uint256	Amount of leRAAC not yet converted
realised	uint256	Amount of RAAC available to claim

JavaScript

// Get user's current position
const [unrealised, realised] = await maturityVault.getUserInfo(myAddress);

console.log("Unrealised leRAAC:", ethers.formatUnits(unrealised, 18));
console.log("Claimable RAAC:", ethers.formatUnits(realised, 18));

`totalRAACInPool`¶

totalRAACInPool() → uint256

Summary
Returns RAAC held minus undistributed linear leftover.

Access
Public View

Returns

Type	Description
uint256	Total RAAC available in the pool

JavaScript

const totalRAAC = await maturityVault.totalRAACInPool();
console.log("Total RAAC in pool:", ethers.formatUnits(totalRAAC, 18));

Distribution Functions¶

`distribute`¶

distribute(address _origin, uint256 _amount)

Summary
Distributes RAAC to pay down maturity debt.

Access
External — Whitelisted only

Parameters

Name	Type	Description
_origin	address	The origin address of the distribution
_amount	uint256	The amount of RAAC to distribute

Emits

Distribute(address origin, uint256 amount)

Reverts

Unauthorized() — if caller is not whitelisted

`harvest`¶

harvest(address _recipient, uint256 _minimumOut) → uint256

Summary
Harvests RAAC already in the vault and distributes it (fees/bounty apply).

Access
External — Whitelisted only

Parameters

Name	Type	Description
_recipient	address	The address to receive the harvest bounty
_minimumOut	uint256	Minimum output (currently unused)

Returns

Type	Description
uint256	Harvested amount (pre-fees)

Emits

Harvest(address caller, uint256 amount)

Reverts

Unauthorized() — if caller is not whitelisted

`updatePendingDistribution`¶

updatePendingDistribution()

Summary
Updates internal linear distribution progress.

Access
External

Admin Functions¶

`initialize`¶

initialize(address _raac, address _leRAAC, address _platform, address _zap, address _governor, uint256 _platformFeePercentage, uint256 _harvestBountyPercentage)

Summary
Initializes the contract (upgradeable pattern).

Access
External — Initializer

Parameters

Name	Type	Description
_raac	address	RAAC token address
_leRAAC	address	leRAAC token address
_platform	address	Platform fee recipient
_zap	address	Zap contract address
_governor	address	Governor address
_platformFeePercentage	uint256	Initial platform fee percentage
_harvestBountyPercentage	uint256	Initial harvest bounty percentage

`updateWhitelists`¶

updateWhitelists(address[] calldata _whitelists, bool _status)

Summary
Updates caller whitelist.

Access
External — Owner only

Parameters

Name	Type	Description
_whitelists	address[]	Array of addresses to update
_status	bool	`true` to whitelist, `false` to remove

Emits

UpdateWhitelist(address whitelist, bool status) — for each address

`updateGovernor`¶

updateGovernor(address _governor)

Summary
Updates governor address.

Access
External — Governor or Owner

Parameters

Name	Type	Description
_governor	address	New governor address

Emits

UpdateGovernor(address governor)

Reverts

ZeroAddress() — if zero address provided

`updatePlatformFeePercentage`¶

updatePlatformFeePercentage(uint256 _feePercentage)

Summary
Updates platform fee.

Access
External — Owner only

Parameters

Name	Type	Description
_feePercentage	uint256	New platform fee percentage

Emits

UpdatePlatformFeePercentage(uint256 feePercentage)

Reverts

InvalidPercentage() — if percentage exceeds MAX_PLATFORM_FEE

`updateHarvestBountyPercentage`¶

updateHarvestBountyPercentage(uint256 _percentage)

Summary
Updates harvest bounty.

Access
External — Owner only

Parameters

Name	Type	Description
_percentage	uint256	New harvest bounty percentage

Emits

UpdateHarvestBountyPercentage(uint256 percentage)

Reverts

InvalidPercentage() — if percentage exceeds MAX_HARVEST_BOUNTY

`updatePlatform`¶

updatePlatform(address _platform)

Summary
Updates platform fee recipient.

Access
External — Owner only

Parameters

Name	Type	Description
_platform	address	New platform recipient address

Emits

UpdatePlatform(address platform)

Reverts

ZeroAddress() — if zero address provided

`updateZap`¶

updateZap(address _zap)

Summary
Updates zap address.

Access
External — Governor or Owner

Parameters

Name	Type	Description
_zap	address	New zap address

Emits

UpdateZap(address zap)

Reverts

ZeroAddress() — if zero address provided

`updatePeriodLength`¶

updatePeriodLength(uint32 _length)

Summary
Updates reward period length.

Access
External — Governor or Owner

Parameters

Name	Type	Description
_length	uint32	New period length in seconds

Emits

UpdatePeriodLength(uint32 length)

Implementation Details¶

Unrealised vs Realised Accounting¶

Unrealised: portion of leRAAC deposit that has not yet been paid down by distributed RAAC
Realised: portion that has been paid down and can be claimed as RAAC

The vault maintains:

totalUnrealised, totalRealised
a multiplicative accumulator accUnrealisedFraction which represents the product of:

\[ \prod_i \frac{\text{totalUnrealised}_i - \text{reward}_i}{\text{totalUnrealised}_i} \]

Each user stores a checkpoint accUnrealisedFractionPaid, allowing their unrealised balance to be updated lazily on interaction.

Distribution Modes¶

Immediate (rewardInfo.periodLength == 0): distribute() reduces global debt instantly
Linear (rewardInfo.periodLength > 0): distribute() sets/updates a ratePerSecond and debt is reduced over time when _updatePendingDistribution() is called (implicitly by most user actions)

Claim Semantics¶

When a user claims:

Their realised RAAC is transferred to the recipient
The vault burns the same amount of realised leRAAC via leRAAC.burn(amount)

Data Structures¶

UserInfo¶

Field	Type	Description
unrealised	uint128	User unrealised `leRAAC` amount
realised	uint128	User realised (claimable) RAAC amount
accUnrealisedFractionPaid	uint192	Checkpoint of `accUnrealisedFraction`
lastDistributeIndex	uint64	Last distribution index the user was updated at

LinearReward¶

Field	Type	Description
ratePerSecond	uint128	Debt paydown rate per second
periodLength	uint32	Period length in seconds; `0` means immediate
lastUpdate	uint48	Timestamp of last update
finishAt	uint48	End timestamp of current period

Constants¶

Constant	Value	Description
E128	\(2^{128}\)	Fraction scaling basis
FEE_PRECISION	1e9	Precision for fee percentages
MAX_PLATFORM_FEE	5e8	Max platform fee (50%)
MAX_HARVEST_BOUNTY	1e8	Max harvest bounty (10%)

Events¶

Event Name	Description	Parameters
Deposit	When `leRAAC` is deposited	`account`, `amount`
Withdraw	When unrealised `leRAAC` is withdrawn	`account`, `recipient`, `amount`
Claim	When realised RAAC is claimed	`account`, `recipient`, `amount`
Distribute	When RAAC is distributed for debt paydown	`origin`, `amount`
Harvest	When a harvest occurs	`caller`, `amount`
UpdateWhitelist	When whitelist is updated	`whitelist`, `status`
UpdatePlatformFeePercentage	When platform fee is updated	`feePercentage`
UpdateHarvestBountyPercentage	When harvest bounty is updated	`percentage`
UpdatePlatform	When platform recipient is updated	`platform`
UpdateZap	When zap is updated	`zap`
UpdateGovernor	When governor is updated	`governor`
UpdatePeriodLength	When period length is updated	`length`

Error Conditions¶

Error Name	Description
ZeroAddress	Zero address provided
InvalidPercentage	Percentage exceeds maximum
NonZeroValue	Value must be non-zero
Unauthorized	Not whitelisted / not owner / not governor
InsufficientBalance	Withdraw amount exceeds unrealised balance

Access Control Roles¶

Role / Mechanism	Description
Owner (`OwnableUpgradeable`)	Updates fee parameters, platform recipient, and whitelist
Whitelist (`isWhitelisted`)	Can call `distribute()` and `harvest()`
Governor (`governor`)	Can update some operational parameters (e.g. zap, period length) alongside owner

Usage Notes¶

deposit() and depositFor() transfer leRAAC into the vault; ensure ERC20 approvals are set
In linear distribution mode, realised balances increase over time; most user actions call into _updatePendingDistribution() implicitly
harvest() currently distributes the vault's RAAC balance (if any) and applies platform fee and bounty before calling internal distribution logic

Dependencies¶

OpenZeppelin: SafeERC20, OwnableUpgradeable
RAAC interfaces:
- IRAACMaturityVault
- ILiquidEscrowedRAAC (burning realised leRAAC)
- IERC20 (RAAC + leRAAC transfers)

RAACMaturityVault¶

Overview¶

Purpose¶

Functions¶

User Functions¶

deposit¶

depositFor¶

withdraw¶

withdrawAll¶

claim¶

exit¶

getUserInfo¶

totalRAACInPool¶

Distribution Functions¶

distribute¶

harvest¶

updatePendingDistribution¶

Admin Functions¶

initialize¶

updateWhitelists¶

updateGovernor¶

updatePlatformFeePercentage¶

updateHarvestBountyPercentage¶

updatePlatform¶

updateZap¶

updatePeriodLength¶

Implementation Details¶

Unrealised vs Realised Accounting¶

Distribution Modes¶

Claim Semantics¶

Data Structures¶

UserInfo¶

LinearReward¶

Constants¶

Events¶

Error Conditions¶

Access Control Roles¶

Usage Notes¶

Dependencies¶

`deposit`¶

`depositFor`¶

`withdraw`¶

`withdrawAll`¶

`claim`¶

`exit`¶

`getUserInfo`¶

`totalRAACInPool`¶

`distribute`¶

`harvest`¶

`updatePendingDistribution`¶

`initialize`¶

`updateWhitelists`¶

`updateGovernor`¶

`updatePlatformFeePercentage`¶

`updateHarvestBountyPercentage`¶

`updatePlatform`¶

`updateZap`¶

`updatePeriodLength`¶