Volt Network is a professional-grade yield vault and reward distribution protocol designed for the Stellar ecosystem. Leveraging Soroban WebAssembly (WASM) smart contracts, the protocol enables secure token deposits, withdrawals, and deterministic reward payouts.

The system architecture facilitates interaction between user wallets, administrative addresses, the vault smart contract, on-chain token contracts, and storage events.

graph TD
    User[User Wallet] -->|Deposit/Withdraw| VC[Vault Contract]
    Admin[Admin Wallet] -->|Distribute Rewards| VC
    VC -->|Interact| SC[Stellar Asset Contract]
    VC -->|Emit| EV[On-chain Events]
    VC -->|Store| ST[Persistent Storage]

Each Vault Contract instance is dedicated to a single Stellar asset (e.g. USDC, XLM, or custom tokens).

• Balance Tracking: Uses Soroban persistent storage keys to track depositor balances.
• Initialization: Configures a dedicated administrative identity and sets the asset token upon instantiation.

Authorized vault administrators can inject rewards directly into the vault pool.

• Reward Mechanics: Rewards are transferred from the admin to the vault address and added to the total supply. User withdrawals automatically calculate payouts proportionally based on the user's relative stake in the total vault supply.
• Events: Distributing rewards, deposits, and withdrawals trigger verifiable, structured events on-chain.

• initialize(e: Env, admin: Address, token: Address) -> Result<(), VaultError> Configures the vault. Can only be invoked once.

• deposit(e: Env, user: Address, amount: i128) -> Result<(), VaultError> Transfers the specified asset amount from the user's balance to the vault contract, incrementing both the user balance and the vault total supply. Requires user authorization (require_auth).
• withdraw(e: Env, user: Address, amount: i128) -> Result<(), VaultError> Withdraws funds and a proportional share of distributed rewards. Decrements the user balance and the total supply. Requires user authorization (require_auth).

• distribute_rewards(e: Env, admin: Address, amount: i128) -> Result<(), VaultError> Deposits additional tokens to be distributed among depositors. Requires admin authorization.

• get_balance(e: Env, user: Address) -> i128 Returns the internal balance of the specified address.
• total_supply(e: Env) -> i128 Returns the total token supply managed by the vault.

• Rust (stable toolchain)
• Soroban CLI
• Node.js (v18+)

Clone this repository and install the development dependencies:

git clone https://github.com/your-org/volt-network.git
cd volt-network
npm install

Compile the contract to a WASM binary and execute the native unit tests:

# Navigate to the contract folder
cd contracts/vault-contract

# Compile to target WASM
cargo build --target wasm32-unknown-unknown --release

# Run Rust tests
cargo test

We provide TypeScript deployment scripts to deploy and initialize the contracts:

# Compile and deploy the contract WASM code on-chain
npm run deploy

# Configure the vault with the admin and token address
npm run initialize

JavaScript/TypeScript integration tests are located in the tests/ directory and use Jest:

# Run tests
npm run test

The smart contracts inside this repository are currently unaudited and intended for MVP evaluation and testnet environments. In production, ensure administrative actions are gated by a multi-signature account or a decentralized governance mechanism.

This project is licensed under the MIT License.