Documentation
Overview
Urbanium is a production-ready decentralized finance protocol built on Solana, designed for capital efficiency and sustainable yield generation. The protocol combines single-asset vaults with oracle-priced swaps and adaptive yield routing to create efficient markets while maintaining complete non-custodial security.
How Urbanium Works
Urbanium operates through three interconnected systems that work together to provide optimal capital efficiency:
- Vault System: Users deposit single assets into program-controlled vaults. Each vault is managed by a PDA (Program Derived Address) authority, ensuring no centralized control exists. Vaults maintain full custody of user funds while enabling programmatic yield generation.
- Oracle Integration: External price oracles feed real-time market data into the protocol. The oracle adapter layer normalizes prices across different sources and enforces safety checks before executing any swap operations.
- Yield Routing: The adaptive yield router continuously analyzes available opportunities across the Solana ecosystem and automatically allocates capital to strategies offering optimal risk-adjusted returns.
Vault Lifecycle
1. Vault Creation
Any user can initialize a new vault by specifying the underlying asset. The program derives a unique PDA for the vault and its authority using deterministic seeds. No admin keys are involved in this process.
2. Deposits
Users transfer assets directly to the vault PDA. The program mints vault tokens representing proportional ownership. All deposits are atomic and immediately reflected on-chain.
3. Yield Generation
The yield router analyzes available strategies and executes rebalancing operations. All yield accrues directly to vault token holders proportionally. The vault authority signs these transactions programmatically.
4. Withdrawals & Redemptions
Users can redeem vault tokens at any time to receive their proportional share of vault assets including accrued yield.
Oracle Pricing Model
The oracle adapter layer integrates multiple external price feeds to ensure accuracy and prevent manipulation:
Price Aggregation
Multiple oracle sources are queried simultaneously. The adapter calculates a confidence-weighted median price, discarding outliers that exceed deviation thresholds.
Normalization
Different oracles may use different decimal precision and quote currencies. The adapter normalizes all prices to a standard format with consistent decimal places.
Safety Checks
Before executing swaps, the adapter verifies price freshness, confidence levels, and deviation from TWAP. Any swap failing these checks is rejected to protect user funds.
Yield Routing Logic
The adaptive yield router employs sophisticated algorithms to maximize risk-adjusted returns:
Strategy Analysis
The router continuously monitors available DeFi protocols on Solana, analyzing current APYs, historical performance, TVL, and smart contract risk scores.
Allocation Optimization
Using modern portfolio theory, the router calculates optimal allocations across multiple strategies to maximize expected returns while minimizing correlation and concentration risk.
Automatic Rebalancing
When market conditions change or better opportunities emerge, the router executes rebalancing transactions. Gas costs are factored into rebalancing decisions to ensure net positive returns.
Security Model
No Admin Custody
All vault authorities are PDAs with no corresponding private keys. No individual or entity can unilaterally access user funds. Only the program logic can sign transactions.
Explicit Authority Separation
Different PDAs control different operations. Vault PDAs hold assets, vault authority PDAs sign yield operations, and user position PDAs track ownership. This separation limits attack surface.
Deterministic Execution Paths
All program operations follow explicit, auditable code paths. There are no admin functions, upgrade authorities are renounced post-deployment, and all logic is transparent and verifiable on-chain.
Program Accounts
Vault Account
pub struct Vault {
pub authority: Pubkey, // Vault authority PDA
pub token_mint: Pubkey, // Underlying asset mint
pub total_shares: u64, // Total vault tokens minted
pub total_assets: u64, // Total underlying assets
pub bump: u8, // PDA bump seed
}User Position Account
pub struct UserPosition {
pub owner: Pubkey, // User wallet address
pub vault: Pubkey, // Associated vault
pub shares: u64, // User's vault tokens
pub last_deposit: i64, // Timestamp of last deposit
}Error Handling
The protocol implements comprehensive error handling to ensure safe operations:
Mainnet Usage Guide
- 1. Connect Wallet: Use any Solana-compatible wallet (Phantom, Solflare, etc.) and ensure you're connected to mainnet.
- 2. Select Vault: Browse available vaults and review their current APY, TVL, and underlying strategies.
- 3. Deposit Assets: Specify amount to deposit. The transaction will transfer your tokens to the vault and mint proportional vault tokens to your wallet.
- 4. Monitor Performance: Track your position's value over time. Yield accrues automatically and is reflected in your vault token value.
- 5. Withdraw: Redeem vault tokens at any time to receive your proportional share of vault assets including accrued yield.
Need help or have questions?