Unlocking apyUSD for apxUSD

apyUSD holders can unlock their shares to receive apxUSD assets. apyUSD is a synchronous ERC-4626 vault — withdrawals and redeems execute immediately and return apxUSD_unlock tokens. apxUSD_unlock is redeemable 1:1 for apxUSD after a 30 day cooldown period but does not earn yield and is non-transferrable.

You cannot cancel unlocking once it has been initiated and will only be able to convert apxUSD_unlock to apxUSD after the cooldown period.

Understanding Unlock Methods

The vault provides standard ERC-4626 methods for unlocking, offering flexibility in how users specify amounts:

For Unlocking (Synchronous — returns apxUSD_unlock):

• withdraw(assets, receiver, owner): Specify the exact apxUSD amount to receive after cooldown; burn calculated apyUSD shares immediately

  • Use when: You know exactly how much apxUSD you want to unlock

  • Example: "I want to unlock 1000 apxUSD"

• redeem(shares, receiver, owner): Specify the exact apyUSD shares to burn; receive calculated apxUSD_unlock immediately

  • Use when: You know exactly how many apyUSD shares you want to exit

  • Example: "I want to redeem all 950 of my apyUSD shares"

After receiving apxUSD_unlock tokens, call UnlockToken.redeem() once the cooldown period has elapsed to receive apxUSD.

Prefer to use the withdrawForMaxShares and redeemForMinAssets methods to limit price risk when unlocking apyUSD.

Multiple unlocks reset the cooldown period. For example, if you unlock 100 apxUSD you will receive apxUSD_unlock that is convertable to apxUSD after the cooldown period. If you later unlock another 50 apxUSD the cooldown period will reset and you will have to wait the full period to completely unlock the 150 apxUSD.

Price Controls on Unlocking

The apyUSD vault exposes withdraw and redeem methods with price controls to limit price risk between submitting a transaction and the transaction being included in a block:

• withdrawForMaxShares(uint256 assets, uint256 maxShares, address receiver): Withdraws exact assets or reverts if more than max shares will be burned

• redeemForMinAssets(uint256 shares, uint256 minAssets, address receiver): Redeems exact shares or reverts if less than min assets will be received

Total Assets and Vested Yield

The apyUSD vault's totalAssets() function includes both:

• The vault's apxUSD balance (assets held directly in the vault)

• The vestedAmount() available in the LinearVestV0 contract

When a withdrawal is requested, the vault automatically pulls all vested yield from the vesting contract before processing the withdrawal, ensuring the exchange rate reflects the full accrued value and the vault has sufficient assets to fund the withdrawal.

Unlock Examples

1. Bob calls apyUSD.withdraw(1000e18, bob, bob)

2. apyUSD calculates shares based on totalAssets() which includes vested yield

3. apyUSD determines the exchange rate between assets and shares

4. Bob's apyUSD shares are burned immediately

5. 1000 apxUSD is deposited into the UnlockToken contract; Bob receives 1000 apxUSD_unlock

6. After the cooldown period, Bob calls UnlockToken.redeem(1000e18, bob, bob) to receive 1000 apxUSD

The UnlockToken: Tokenized Escrow During Cooldown

During the cooldown period, unlocked apxUSD assets are held in the UnlockToken contract.

How it works:

• User calls apyUSD.withdraw() or apyUSD.redeem() — apyUSD shares are burned synchronously

• The apxUSD assets are deposited into the UnlockToken contract by the vault

• The user immediately receives apxUSD_unlock tokens (UnlockToken shares), redeemable 1:1 for apxUSD after the cooldown period

• The apyUSD vault is configured as the operator for UnlockToken, allowing it to initiate the redeem request on behalf of the user immediately

• After the cooldown period, the user calls UnlockToken.redeem() to receive their apxUSD

There is only one instance of UnlockToken and it is used exclusively by the apyUSD vault.

Success & Failure Flows

Withdraw Success

Users specify the exact amount of apxUSD to receive after the cooldown period. apyUSD shares are burned immediately and apxUSD_unlock tokens are returned.

Redeem Success

Users specify the exact amount of apyUSD shares to burn. The calculated apxUSD amount is deposited into UnlockToken and redeemable after the cooldown period.

Withdrawal Failure — Slippage Exceeded

When the slippage is exceeded on withdraw or redeem.