Smart Contract Architecture
Comprehensive overview of Teranium's on-chain program design, PDA structure, and security model built for Solana.
Teranium is implemented as a single Solana program using the Anchor framework for type safety and developer ergonomics. All protocol logic is contained within deterministic instruction handlers that ensure predictable state transitions and verifiable execution.
Program Type
Single Anchor Program
State Model
PDA-based accounts
Security
Non-custodial by design
Program Derived Address (PDA) Design
Seeds: ["vault", asset_mint] Purpose: Holds deposited SPL tokens Isolated per asset type Immutable mint binding Structure: - mint: PublicKey - total_deposited: u64 - total_shares: u64 - yield_earned: u64 - strategy_allocations: Vec<Allocation> - bump: u8
Key Properties
- One vault per SPL token mint - ensures complete asset isolation
- Deterministic address derivation - predictable on-chain location
- Immutable mint binding - vault can only hold its designated token
- No external signing authority - only program can move funds
Seeds: ["vault_authority", vault_pda] Purpose: Only signer allowed to move vault funds Enforced by program logic No external ownership Authorization: Used in CPI calls to token program Signs for vault's token account Validates yield routing operations
Security Model
The vault authority PDA ensures that only the Teranium program can authorize token transfers from vaults. No external keys exist that can sign for vault funds, eliminating admin key compromise risks and ensuring true non-custodial operation.
Seeds: ["position", vault_pda, user_pubkey] Tracks: - deposited_amount: u64 - share_balance: u64 - accrued_yield: u64 - last_update_timestamp: i64 - withdrawal_eligibility: bool Ensures: Cryptographic proof of ownership Accurate yield attribution Permissionless withdrawal rights
Position Accounting
Position PDAs maintain per-user accounting of deposits and accrued yield. The share-based system ensures fair yield distribution proportional to deposit size and duration. Users can verify their position on-chain at any time and execute withdrawals permissionlessly.
Oracle Adapter Architecture
Interface Design
The oracle adapter provides an abstraction layer over Pyth Network price feeds, allowing for future multi-oracle support while maintaining a consistent internal interface.
pub trait OracleAdapter {
fn get_price(asset: Pubkey) -> Result<Price>;
fn validate_price(price: Price) -> Result<()>;
}
pub struct Price {
value: u64,
confidence: u64,
timestamp: i64,
exponent: i32,
}Validation Rules
Staleness Check
Price timestamp must be within maximum age threshold (typically 60 seconds)
Confidence Bound
Confidence interval must be below maximum threshold (typically 2%)
Execution Flow
Swap Request
User initiates swap with slippage tolerance
Oracle Query
Program queries Pyth oracle account for price
Validation
On-chain staleness and confidence checks
Execution
If valid, execute swap at oracle price
Yield Routing Engine
Design Rationale
Yield routing decisions require complex optimization calculations that are impractical to perform on-chain. Teranium uses a hybrid model where routing strategies are computed off-chain but all capital movements are enforced on-chain with strict validation rules.
Off-Chain (Compute)
- • Yield opportunity scanning
- • Risk-adjusted return calculation
- • Portfolio optimization
- • Strategy composition
On-Chain (Enforce)
- • Solvency constraint validation
- • Maximum allocation limits
- • Whitelist protocol checks
- • Capital movement authorization
Solvency Guarantees
On-chain logic enforces that total allocated capital never exceeds available vault balance minus a safety reserve. This ensures users can always withdraw their proportional share, even if routing strategies underperform.
Security Model
All vault funds are controlled by PDAs with no external signing keys. Only the program's instruction handlers can authorize token transfers, eliminating admin key compromise risks.
All state transitions follow deterministic rules with no privileged admin operations. Protocol behavior is fully predictable and verifiable through on-chain transaction history.
Position PDAs provide cryptographic proof of user ownership. Users can independently verify their holdings on-chain and execute withdrawals without requiring protocol permission.
Vaults are permanently bound to their token mint at creation. This prevents token substitution attacks and ensures users always receive their original deposit token type.