Vault Module

Overview

The satay::vault module contains the code for vault logic within the Satay protocol. This module manages vault creation, deposits, withdrawals, strategy integration, and overall vault state.

Structs

Vault

The Vault struct represents a vault in the protocol. It holds essential information about the vault's assets, state, and associated strategies.

struct Vault has key {
    total_debt: u64,
    is_paused: bool,
    total_idle: u64,
    protocol_fee: Option<u64>,
    deposit_limit: Option<u64>,
    base_metadata: Object<Metadata>,
    shares_metadata: Object<Metadata>,
    base_coin_type: Option<String>,
    last_report: u64,
    locked_profit: u64,
    strategies: SimpleMap<Object<Strategy>, StrategyState>,
}

VaultController

The VaultController struct holds control information for a vault, including the manager's address and the vault's extend ref.

struct VaultController has key {
    manager: address,
    extend_ref: ExtendRef
}

RegistryInfo

Tracks all vaults and strategies registered within the protocol.

struct RegistryInfo has key {
    vaults: vector<Object<Vault>>,
    strategies: vector<Object<Strategy>>,
}

WithdrawalRequest

Represents a request to withdraw assets from a vault.

struct WithdrawalRequest {
    to_withdraw: u64,
    account: address,
    vault: Object<Vault>,
    to_burn: FungibleAsset,
    withdrawn: FungibleAsset,
    debt_offsets: SimpleMap<Object<Strategy>, u64>,
}

Events

  • CreateVault: Emitted when a new vault is created.

  • Deposit: Emitted when assets are deposited into a vault.

  • Withdraw: Emitted when assets are withdrawn from a vault.

  • RegistryInitialized: Emitted when the registry is initialized.

  • VaultPaused: Emitted when a vault is paused.

  • VaultUnpaused: Emitted when a vault is unpaused.

  • SetDepositLimit: Emitted when the deposit limit of a vault is set.

  • SetProtocolFee: Emitted when the protocol fee of a vault is set.

  • StrategyAdded: Emitted when a strategy is added to a vault.

  • StrategyRemoved: Emitted when a strategy is removed from a vault.

  • StrategySharesDeposit: Emitted when strategy shares are deposited into a vault.

  • StrategySharesWithdraw: Emitted when strategy shares are withdrawn from a vault.

Constants

  • BPS_MAX: u64 = 10_000; (Maximum basis points)

  • DEBT_RATIO_MAX: u64 = 10_000; (Maximum debt ratio in basis points)

  • PROTOCOL_FEE_MAX: u64 = 5000; (Maximum protocol fee in basis points)

  • MANAGEMENT_FEE_MAX: u64 = 200; (Maximum management fee in basis points)

  • PERFORMANCE_FEE_MAX: u64 = 5000; (Maximum performance fee in basis points)

  • SECS_PER_YEAR: u64 = 31_556_952; (Number of seconds in a year)

  • U64_MAX: u64 = 18446744073709551615; (Maximum u64 value)

  • LOCK_DURATION: u64 = 6_000_000; (Duration for profit locking)

Error Codes

  • ENOT_GOVERNANCE: Caller is not the governance account.

  • EDEPOSIT_LIMIT_TOO_LOW: Deposit limit is too low.

  • EPROTOCOL_FEE_TOO_HIGH: Protocol fee exceeds the maximum allowed.

  • EVAULT_BASE_ASSET_MISMATCH: Asset does not match the vault's base asset.

  • EINSUFFICIENT_BALANCE: Insufficient balance for the operation.

  • EVAULT_NOT_PAUSED: Vault is not paused.

  • EVAULT_ALREADY_PAUSED: Vault is already paused.

  • ECANNOT_EXCEED_DEPOSIT_LIMIT: Deposit exceeds the vault's deposit limit.

  • ESTRATEGY_ALREADY_ADDED: Strategy is already added to the vault.

  • ESTRATEGY_NOT_EXISTS: Strategy does not exist.

  • EVAULT_ASSET_NOT_INITIALIZED: Vault's asset is not initialized.

  • EVAULT_SHARES_ASSET_MISMATCH: Shares asset does not match the vault's shares asset.

  • EDEBT_RATIO_TOO_HIGH: Debt ratio exceeds the maximum allowed.

  • ESTRATEGY_STATE_MISMATCH: Strategy state does not match.

  • ESTRATEGY_STATE_NOT_FOUND: Strategy state not found in the vault.

  • EVAULT_NOT_ACTIVE: Vault is not active.

  • ESTRATEGY_BASE_METADATA_MISMATCH: Strategy's base metadata does not match the vault's.

  • ESTRATEGY_HAS_DEBT: Strategy still has outstanding debt.

  • EVAULT_INSUFFICIENT_DEBT: Vault has insufficient debt.

  • EVAULT_WITHDRAWAL_AMOUNT_NOT_ZERO: Withdrawal amount is not zero.

  • EVAULT_DOES_NOT_EXIST: Vault does not exist.

  • ESTORE_DOES_NOT_EXIST: Asset store does not exist.

  • ENOT_GOVERNANCE_OR_MANAGER: Caller is neither governance nor manager.

  • ESTRATEGY_IMPL_ALREADY_ADDED: Strategy implementation is already added.

  • ESTRATEGY_IMPL_NOT_FOUND: Strategy implementation not found.

  • EALREADY_INITIALIZED: Registry is already initialized.

  • ESTRATEGY_SHARES_METADATA_MISMATCH: Strategy's shares metadata does not match.

  • ESTRATEGY_WITNESS_MISMATCH: Strategy witness does not match.

  • ETOO_MUCH_STRATEGY_LOSS: Strategy loss exceeds the allowable amount.

  • EINVALID_ASSESS_FEE_DURATION: Invalid duration for fee assessment.

  • EZERO_AMOUNT_DEPOSIT: Deposit amount cannot be zero.

  • EZERO_AMOUNT_WITHDRAWAL: Withdrawal amount cannot be zero.

  • EINVALID_TOTAL_SHARES: Total shares are invalid.

  • EVAULT_INSUFFICIENT_ASSETS: Vault has insufficient assets.

  • ECANNOT_EXCEED_DEBT_LIMIT: Debt limit exceeded.

  • EINVALID_TIMESTAMP: Invalid timestamp.

  • EWITHDRAWAL_ACCOUNT_MISMATCH: Withdrawal account does not match the requester.

Access Control

  • Governance Only: Certain functions are restricted to the governance account, such as initializing the registry, creating vaults, pausing/unpausing vaults, setting deposit limits, setting protocol fees, adding/removing strategies, updating strategy debt limits, and creating debts.

  • Governance or Manager: Functions that can be performed by either the governance account or the vault manager.

Functions

  1. Initialization

    • initialize(account: &signer): Initializes the registry. Can only be called by the governance account. Emits RegistryInitialized event.

  2. Vault Management

    • create(account: &signer, protocol_fee: Option<u64>, deposit_limit: Option<u64>, base_metadata: Object<Metadata>): Object<Vault>: Creates a new vault with specified parameters. Can only be called by the governance account. Emits CreateVault event.

    • pause(account: &signer, vault: Object<Vault>): Pauses a vault, preventing deposits but allowing withdrawals. Can only be called by the governance account. Emits VaultPaused event.

    • unpause(account: &signer, vault: Object<Vault>): Unpauses a vault, allowing deposits again. Can only be called by the governance account. Emits VaultUnpaused event.

    • set_deposit_limit(account: &signer, vault: Object<Vault>, deposit_limit: Option<u64>): Sets the deposit limit for a vault. Can only be called by the governance account. Emits SetDepositLimit event.

    • set_protocol_fee(account: &signer, vault: Object<Vault>, fee: Option<u64>): Sets the protocol fee for a vault. Can only be called by the governance account. Emits SetProtocolFee event.

  3. Deposits and Withdrawals

    • deposit(vault: Object<Vault>, asset: FungibleAsset): FungibleAsset: Deposits assets into the vault, minting shares for the depositor. Emits Deposit event.

    • initialize_withdrawal(account: &signer, vault: Object<Vault>, shares_asset: FungibleAsset): WithdrawalRequest: Initializes a withdrawal request by specifying the shares to burn.

    • withdraw(account: &signer, request: &mut WithdrawalRequest): Processes a withdrawal request by burning shares and preparing assets for withdrawal.

    • complete_withdrawal(account: &signer, request: WithdrawalRequest): FungibleAsset: Completes a withdrawal request and returns the withdrawn assets. Emits Withdraw event.

    • complete_coin_withdrawal<CoinType>(account: &signer, request: WithdrawalRequest): Coin<CoinType>: Completes a coin withdrawal request and returns the withdrawn coins.

  4. Strategy Management

    • add_strategy(account: &signer, vault: Object<Vault>, strategy: Object<Strategy>): Adds a strategy to the vault. Can only be called by the governance account. Emits StrategyAdded event.

    • remove_strategy(account: &signer, vault: Object<Vault>, strategy: Object<Strategy>, force: bool): Removes a strategy from the vault. Can only be called by the governance account. Emits StrategyRemoved event.

    • update_strategy_debt_limit(account: &signer, vault: Object<Vault>, strategy: Object<Strategy>, debt_limit: u64): Updates the debt limit for a strategy. Can only be called by the governance account.

  5. Debt Management

    • create_debt(account: &signer, vault: Object<Vault>, strategy: Object<Strategy>, amount: u64): FungibleAsset: Creates debt for a strategy by transferring assets from the vault to the strategy. Can only be called by the governance account.

  6. Strategy Shares Management

    • deposit_strategy_shares(vault: Object<Vault>, strategy: Object<Strategy>, asset: FungibleAsset): Deposits strategy shares into the vault. Emits StrategySharesDeposit event.

    • withdraw_strategy_shares<T>(vault: Object<Vault>, strategy: Object<Strategy>, amount: u64, _: &T): FungibleAsset: Withdraws strategy shares from the vault. Emits StrategySharesWithdraw event.

    • get_strategy_shares_balance(vault: Object<Vault>, strategy: Object<Strategy>): u64: Retrieves the balance of strategy shares held by the vault.

  7. Withdrawal Processing

    • apply_strategy_withdrawal(request: &mut WithdrawalRequest, strategy: Object<Strategy>, asset: FungibleAsset): Applies a strategy withdrawal to the withdrawal request.

    • apply_strategy_loss(request: &mut WithdrawalRequest, strategy: Object<Strategy>, loss: u64): Applies a strategy loss to the withdrawal request.

    • add_debt_offset(request: &mut WithdrawalRequest, strategy: Object<Strategy>, amount: u64): Adds a debt offset for a strategy in the withdrawal request.

    • withdrawn_amount(request: &WithdrawalRequest): u64: Retrieves the total amount withdrawn in the request.

    • withdrawn_asset(request: &WithdrawalRequest): &FungibleAsset: Retrieves the asset withdrawn in the request.

  8. Access Control Helpers

    • is_governance_or_manager(vault: Object<Vault>, account: address): bool: Checks if an account is either the governance account or the manager of the vault.

Getter Functions

  1. Vault Information

    • get_vaults(): vector<Object<Vault>>: Retrieves all vaults registered in the protocol.

    • to_object(address: address): Object<Vault>: Converts an address to a Vault object.

    • vault_address(vault: Object<Vault>): address: Retrieves the address of a vault.

    • manager(vault: Object<Vault>): address: Retrieves the manager address of a vault.

    • is_manager(vault: Object<Vault>, account: address): bool: Checks if an account is the manager of a vault.

    • is_paused(vault: Object<Vault>): bool: Checks if a vault is paused.

    • deposit_limit(vault: Object<Vault>): Option<u64>: Retrieves the deposit limit of a vault.

    • protocol_fee(vault: Object<Vault>): Option<u64>: Retrieves the protocol fee of a vault.

    • total_assets(vault: Object<Vault>): u64: Retrieves the total assets managed by a vault.

    • total_idle(vault: Object<Vault>): u64: Retrieves the total idle assets in a vault.

    • total_debt(vault: Object<Vault>): u64: Retrieves the total debt of a vault.

    • total_shares(vault: Object<Vault>): u64: Retrieves the total shares issued by a vault.

    • last_report(vault: Object<Vault>): u64: Retrieves the last report timestamp of a vault.

    • base_metadata(vault: Object<Vault>): Object<Metadata>: Retrieves the base asset metadata of a vault.

    • shares_metadata(vault: Object<Vault>): Object<Metadata>: Retrieves the shares asset metadata of a vault.

    • base_store(vault: Object<Vault>): Object<FungibleStore>: Retrieves the base asset store of a vault.

    • shares_store(vault: Object<Vault>): Object<FungibleStore>: Retrieves the shares asset store of a vault.

    • max_deposit(vault: Object<Vault>): u64: Retrieves the maximum allowable deposit for a vault.

    • get_locked_profit(vault: Object<Vault>): u64: Retrieves the locked profit in a vault.

    • free_funds(vault: Object<Vault>): u64: Retrieves the free (unlocked) funds in a vault.

  2. Strategy Information

    • strategies(vault: Object<Vault>): vector<Object<Strategy>>: Retrieves all strategies associated with a vault.

    • get_strategies(): vector<Object<Strategy>>: Retrieves all strategies registered in the protocol.

    • has_strategy(vault: Object<Vault>, strategy: Object<Strategy>): bool: Checks if a vault has a specific strategy.

    • strategy_debt(vault: Object<Vault>, strategy: Object<Strategy>): u64: Retrieves the current debt of a strategy in a vault.

    • get_strategy_shares_balance(vault: Object<Vault>, strategy: Object<Strategy>): u64: Retrieves the balance of strategy shares held by the vault.

    • get_strategy_unrealized_loss_for_amount(vault: Object<Vault>, strategy: Object<Strategy>, amount: u64): u64: Calculates the unrealized loss for a strategy given an amount.

  3. Conversion Utilities

    • amount_to_shares(vault: Object<Vault>, amount: u64): u64: Converts an amount of base assets to vault shares.

    • shares_to_amount(vault: Object<Vault>, shares: u64): u64: Converts vault shares back to base asset amount.

    • to_withdraw(withdrawal: &WithdrawalRequest): u64: Retrieves the remaining amount to withdraw in a withdrawal request.

PreviousAsset ModuleNextStrategy Module

Last updated