usage

Author: ozgunozerk

content/stellar-contracts/tokens/vault/vault.mdx

@@ -147,7 +147,7 @@ The vault module implements the ERC-4626 tokenized vault standard with one minor
 ### ERC-4626 Deviation
 
 <Callout type="warning">
-**DEVIATION FROM ERC-4626**: The `query_asset()` function will panic if the asset address is not set, whereas ERC-4626 requires it to never revert.
+The `query_asset()` function will **panic if the asset address is not set**, whereas ERC-4626 requires it to never revert.
 
 **Rationale**: Soroban doesn't have a "zero address" concept like EVM. Returning `Option<Address>` would break ERC-4626 compatibility.
 
@@ -159,3 +159,218 @@ Aside from this deviation, the vault implementation for Soroban provides:
 - **Cross-ecosystem familiarity**: Ethereum developers will recognize the interface
 - **Standard compliance**: Compatible with ERC-4626 tooling and integrations
 - **Stellar optimizations**: Leverages Soroban's unique capabilities
+
+## Usage
+
+### Basic Implementation
+
+To create a vault contract, implement both the `FungibleToken` and `FungibleVault` traits:
+
+```rust
+use soroban_sdk::{contract, contractimpl, Address, Env, String};
+use stellar_macros::default_impl;
+use stellar_tokens::{
+    fungible::{Base, FungibleToken},
+    vault::{FungibleVault, Vault},
+};
+
+#[contract]
+pub struct VaultContract;
+
+#[contractimpl]
+impl VaultContract {
+    pub fn __constructor(e: &Env, asset: Address, decimals_offset: u32) {
+        // Set the underlying asset address (immutable after initialization)
+        Vault::set_asset(e, asset);
+
+        // Set the decimals offset for precision (immutable after initialization)
+        Vault::set_decimals_offset(e, decimals_offset);
+
+        // Initialize token metadata
+        // Note: Vault overrides the decimals function, so set offset first
+        Base::set_metadata(
+            e,
+            Vault::decimals(e),
+            String::from_str(e, "Vault Token"),
+            String::from_str(e, "VLT"),
+        );
+    }
+}
+
+#[default_impl]
+#[contractimpl]
+impl FungibleToken for VaultContract {
+    type ContractType = Vault;
+
+    fn decimals(e: &Env) -> u32 {
+        Vault::decimals(e)
+    }
+}
+
+#[contractimpl]
+impl FungibleVault for VaultContract {
+    fn deposit(
+        e: &Env,
+        assets: i128,
+        receiver: Address,
+        from: Address,
+        operator: Address,
+    ) -> i128 {
+        operator.require_auth();
+        Vault::deposit(e, assets, receiver, from, operator)
+    }
+
+    fn withdraw(
+        e: &Env,
+        assets: i128,
+        receiver: Address,
+        owner: Address,
+        operator: Address,
+    ) -> i128 {
+        operator.require_auth();
+        Vault::withdraw(e, assets, receiver, owner, operator)
+    }
+
+    // Implement other required methods...
+}
+```
+
+### Initialization
+
+The vault **must** be properly initialized in the constructor:
+
+1. **Set the underlying asset**: Call `Vault::set_asset(e, asset)` with the address of the token contract that the vault will manage
+2. **Set the decimals offset**: Call `Vault::set_decimals_offset(e, offset)` to configure precision (0-10 recommended)
+3. **Initialize metadata**: Call `Base::set_metadata()` with appropriate token information
+
+**Important**: The asset address and decimals offset are immutable once set and cannot be changed.
+
+### Core Operations
+
+#### Depositing Assets
+
+Users can deposit underlying assets to receive vault shares:
+
+```rust
+// Deposit 1000 assets and receive shares
+let shares_received = vault_client.deposit(
+    &1000,              // Amount of assets to deposit
+    &user_address,      // Address to receive shares
+    &user_address,      // Address providing assets
+    &user_address,      // Operator (requires auth)
+);
+```
+
+Alternatively, mint a specific amount of shares:
+
+```rust
+// Mint exactly 500 shares by depositing required assets
+let assets_required = vault_client.mint(
+    &500,               // Amount of shares to mint
+    &user_address,      // Address to receive shares
+    &user_address,      // Address providing assets
+    &user_address,      // Operator (requires auth)
+);
+```
+
+#### Withdrawing Assets
+
+Users can withdraw assets by burning their shares:
+
+```rust
+// Withdraw 500 assets by burning required shares
+let shares_burned = vault_client.withdraw(
+    &500,               // Amount of assets to withdraw
+    &user_address,      // Address to receive assets
+    &user_address,      // Owner of shares
+    &user_address,      // Operator (requires auth)
+);
+```
+
+Or redeem a specific amount of shares:
+
+```rust
+// Redeem 200 shares for underlying assets
+let assets_received = vault_client.redeem(
+    &200,               // Amount of shares to redeem
+    &user_address,      // Address to receive assets
+    &user_address,      // Owner of shares
+    &user_address,      // Operator (requires auth)
+);
+```
+
+### Preview Functions
+
+Preview functions allow you to simulate operations without executing them:
+
+```rust
+let expected_shares = vault_client.preview_deposit(&1000);
+
+let required_assets = vault_client.preview_mint(&500);
+
+let shares_to_burn = vault_client.preview_withdraw(&500);
+
+let expected_assets = vault_client.preview_redeem(&200);
+```
+
+### Conversion Functions
+
+Convert between assets and shares at the current exchange rate:
+
+```rust
+// Convert assets to shares
+let shares = vault_client.convert_to_shares(&1000);
+
+// Convert shares to assets
+let assets = vault_client.convert_to_assets(&500);
+```
+
+### Query Functions
+
+Check vault state and limits:
+
+```rust
+// Get the underlying asset address
+let asset_address = vault_client.query_asset();
+
+// Get total assets held by the vault
+let total_assets = vault_client.total_assets();
+
+// Check maximum amounts for operations
+let max_deposit = vault_client.max_deposit(&user_address);
+let max_mint = vault_client.max_mint(&user_address);
+let max_withdraw = vault_client.max_withdraw(&user_address);
+let max_redeem = vault_client.max_redeem(&user_address);
+```
+
+### Operator Pattern
+
+The vault supports an operator pattern where one address can perform operations on behalf of another:
+
+```rust
+// User approves operator to spend their assets on the underlying token
+asset_client.approve(&user, &operator, &1000, &expiration_ledger);
+
+// Operator deposits user's assets to a receiver
+vault_client.deposit(
+    &1000,
+    &receiver,      // Receives the shares
+    &user,          // Provides the assets
+    &operator,      // Performs the operation (requires auth)
+);
+```
+
+For withdrawals, the operator must have allowance on the **vault shares**:
+
+```rust
+// User approves operator to spend their vault shares
+vault_client.approve(&user, &operator, &500, &expiration_ledger);
+
+// Operator withdraws on behalf of user
+vault_client.withdraw(
+    &500,
+    &receiver,      // Receives the assets
+    &user,          // Owns the shares
+    &operator,      // Performs the operation (requires auth)
+);
+```