# Locking apxUSD for apyUSD

apxUSD holders can lock their tokens to receive apyUSD tokens, 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"

{% hint style="info" %}
Prefer to use the `depositForMinShares` and `mintForMaxAssets` methods to limit price risk when locking apxUSD.
{% endhint %}

### 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](https://ethereum.org/developers/docs/standards/tokens/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.

```mermaid
sequenceDiagram
	actor alice as Alice
	participant offchain as Off Chain

	box On-chain
	participant vault as apyUSD<br/>Vault
	participant apxUSD
	end

	alice ->> vault: deposit(1000 apxUSD, alice)

	activate vault
  vault ->> vault: previewDeposit(1000 apxUSD) -> 970 apyUSD
	vault ->> apxUSD: transferFrom(alice, vault, 1000)
	vault ->> vault: mint 970 apyUSD to alice
	vault -->> offchain: emits Deposit(alice, alice, alice, 1000, 970)
	vault -->> alice: returns 970 apyUSD received
	deactivate vault

	note right of alice: Deposit complete immediately.<br/>No delay for locking.
```

#### Mint Success

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

```mermaid
sequenceDiagram
	actor alice as Alice
	participant vault as apyUSD<br/>Vault
	participant apxUSD
	participant offchain as Off Chain

	box On-chain
	participant vault
	participant apxUSD
	end

	alice ->> vault: mint(970 apyUSD, alice)

	activate vault
  vault ->> vault: previewMint(970 apyUSD) = 1000 apxUSD
	vault ->> apxUSD: transferFrom(alice, vault, 1000)
	vault ->> vault: mint 970 apyUSD to alice
	vault -->> offchain: emits Deposit(alice, alice, alice, 1000, 970)
	vault -->> alice: returns 1000 apxUSD spent
	deactivate vault

	note right of alice: Mint complete immediately.<br/>No delay for locking.
```

#### Deposit Failure - Slippage Exceeded

When the slippage is exceeded on deposit or mint.

```mermaid
sequenceDiagram
	actor alice as Alice

	box On-chain
  participant vault as apyUSD<br/>Vault
	end

	alice ->> vault: depositForMinShares(1000 apxUSD, alice, minSharesOut: 980 apyUSD)
  activate vault
  vault ->> vault: previewDeposit(1000 apxUSD) = 970 apyUSD
  vault ->> vault: check slippage: 970 < 980 apyUSD
  vault ->> alice: revert SlippageExceeded(980, 970)
  deactivate vault

	note right of alice: Transaction fails.<br/>Alice can adjust slippage<br/>and retry
```

#### Deposit Failure - Deny Listed

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

```mermaid
sequenceDiagram
	actor alice as Alice

	box On-chain
	participant vault as apyUSD<br/>Vault
	participant denylist as AddressList<br/>(Deny List)
	end

	alice ->> vault: deposit(1000 apxUSD, bob)

	activate vault
	vault ->> denylist: contains(alice) → false
  vault ->> denylist: contains(bob) → true
	vault ->> alice: revert Denied(bob)
	deactivate vault

	note right of alice: Transaction fails.<br/>Alice is on the deny list.
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.apyx.fi/technical-overview/locking.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.