> For the complete documentation index, see [llms.txt](https://docs.apyx.fi/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.apyx.fi/technical-overview/locking.md). # Locking apxUSD holders can lock their tokens to receive apyUSD, which accrue yield from the preferred share dividend payments distributed to the apyUSD. Locking is synchronous and immediate, providing instant access to yield. apyUSD and aptUSD 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 amount to deposit, receive calculated apyUSD or aptUSD shares immediately * Use when: You know exactly how much apxUSD or alqUSD you want to lock * Example: "I want to lock 1000 apxUSD" * **`mint(shares, receiver)`**: Specify exact apyUSD or aptUSD shares to receive, deposit calculated apxUSD or alqUSD amount immediately * Use when: You know exactly how many apyUSD or aptUSD 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 and aptUSD 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 and aptUSD vault's `totalAssets()` function includes both: * The vault's apxUSD or alqUSD 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 and aptUSD 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 and aptUSD 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 and aptUSD vault contract and the AddressList deny list contract: Methods have been omitted for brevity, but apxUSD and alqUSD will implement the full [ERC-20](https://ethereum.org/developers/docs/standards/tokens/erc-20/) interface. The apyUSD and aptUSD 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 or alqUSD to deposit and receive calculated apyUSD or aptUSD shares immediately. ```mermaid sequenceDiagram actor alice as Alice participant offchain as Off Chain box On-chain participant vault as apyUSD
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.
No delay for locking. ``` #### Mint Success Users specify the exact amount of apyUSD and aptUSD shares to receive and deposit the calculated apxUSD amount immediately. ```mermaid sequenceDiagram actor alice as Alice participant vault as apyUSD
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.
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
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.
Alice can adjust slippage
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
Vault participant denylist as AddressList
(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.
Alice is on the deny list. ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.apyx.fi/technical-overview/locking.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.