Locking

apxUSD holders can lock their tokens to receive apyUSD shares, which accrue yield from the preferred share dividend payments distributed to the apyUSD vault. Locking is synchronous and immediate, providing instant access to yield.

apyUSD is an ERC-4626 compliant tokenized vault with synchronous deposits. Withdrawals are handled synchronously but return apxUSD_unlock, which is non-transferrable and can be redeemed for apxUSD after a cooldown period. This makes unlocking effectively asynchronous.

Understanding Lock Methods

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

For Locking (Deposits - Synchronous):

• deposit(assets, receiver): Specify exact apxUSD amount to deposit, receive calculated apyUSD shares immediately

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

  • Example: "I want to lock 1000 apxUSD"

• mint(shares, receiver): Specify exact apyUSD shares to receive, deposit calculated apxUSD amount immediately

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

  • Example: "I want to mint 950 apyUSD shares"

Prefer to use the depositForMinShares and mintForMaxAssets methods to limit price risk when locking apxUSD.

Price Controls on Locking

The apyUSD also exposes deposit and mint methods with price controls to limit price risk between submitting a transaction and the transaction being included in a block:

• depositForMinShares(uint256 assets, uint256 minShares, address receiver): Deposits exact assets for shares or reverts if less than min shares will be minted

• mintForMaxAssets(uint256 shares, uint256 maxAssets, address receiver): Mint exact shares for assets or reverts if more than max assets will be deposited

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

This means that the exchange rate calculation for deposits accounts for vested yield that hasn't yet been transferred to the vault. Yield from minting operations is deposited into the YieldDistributor and then into the LinearVestV0 contract, where it vests linearly over a time. The apyUSD vault considers this vested yield as part of its total assets, ensuring that users receive shares that reflect the full value of the vault, including yield that is vesting.

When a withdrawal is requested, the vault automatically pulls all vested yield from the LinearVestV0 contract before processing the withdrawal, ensuring it has sufficient assets to fund the withdrawal.

Deposit Examples

1. Alice calls apyUSD.deposit(1000e18, alice)

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

3. apyUSD determine the exchange rate between assets and shares

4. apxUSD is transferred from Alice to apyUSD vault

5. apyUSD shares are minted to Alice immediately (no cooldown)

Protections & Controls

The following controls protect the locking system:

Pause Controls:

• Global Pause: The apyUSD vault can be paused, preventing all token transfers including deposits and mints

• Purpose: Emergency stop mechanism to halt all vault operations in case of security issues or critical bugs

Deny List Controls:

• Address Blocking: AddressList contract checks addresses at execution time

• Blocks: Deposits and mints

• No Cancellation: Denylisted addresses are rejected immediately (revert), not cancelled after the fact

Protections are implemented in the apyUSD vault contract and the AddressList deny list contract:

Methods have been omitted for brevity, but apxUSD will implement the full ERC-20 interface. The apyUSD contract will be upgradeable using the UUPS pattern, allowing for future improvements while maintaining security through AccessManager-based governance.

Success & Failure Flows

Deposit Success

Users specify the exact amount of apxUSD to deposit and receive calculated apyUSD shares immediately.

Mint Success

Users specify the exact amount of apyUSD shares to receive and deposit the calculated apxUSD amount immediately.

Deposit Failure - Slippage Exceeded

When the slippage is exceeded on deposit or mint.

Deposit Failure - Deny Listed

When the caller or receiver is on the deny list, the deposit operation reverts immediately.