Documentation

Welcome to the Threeium technical documentation. This guide covers everything you need to understand, integrate, and build with Threeium—a Solana-native infrastructure system that unifies execution routing and liquidity management.

What is Threeium?

Threeium is a Solana-native infrastructure system that unifies execution routing and liquidity management to generate sustainable, real yield. Unlike traditional approaches that treat execution and liquidity as separate concerns, Threeium recognizes that they are fundamentally interconnected—optimal execution requires dynamic liquidity, and effective liquidity provisioning depends on execution patterns.

The system is designed for protocols, DAOs, and institutional participants who need sophisticated execution capabilities combined with intelligent liquidity management, all while maintaining full transparency and non-custodial security.

Why Threeium?

Design Goals

Threeium was designed with specific principles to ensure reliability, transparency, and sustainability:

• Sustainable Yield: Generate real returns through execution efficiency and liquidity optimization, not speculation or unsustainable incentives.
• Composability: Integrate seamlessly with existing Solana protocols, DEXs, and infrastructure without requiring custom modifications.
• Transparency: All logic, parameters, and yield sources are verifiable on-chain. No black boxes or opaque processes.
• Solana-Native: Built specifically for Solana's unique capabilities and performance characteristics, not a port from EVM.
• Risk Management: Built-in guardrails and circuit breakers to protect against market anomalies and edge cases.

Core Concepts

Execution vs Liquidity vs Yield

Execution refers to how orders are routed, split, and filled across different venues and strategies. Liquidity is the capital positioned to facilitate trades and capture fees. Yield is the return generated from both execution efficiency (better prices, lower slippage) and liquidity provisioning (fees, rewards).

Threeium's insight is that these three components form a feedback loop: better execution requires responsive liquidity, effective liquidity needs to understand execution patterns, and both contribute to sustainable yield generation.

Living Liquidity

Traditional liquidity provisioning is static—positions are set and only adjusted manually. "Living Liquidity" refers to Threeium's approach where liquidity positions adapt automatically based on:

• Market conditions (volatility, volume, spreads)
• Execution demand patterns from integrated protocols
• Opportunity identification (fee capture, arbitrage)
• Risk constraints and parameter boundaries

// Liquidity adapts to market conditions
interface LiquidityPosition {
  asset: string;
  rangeWidth: number;  // Adjusts based on volatility
  concentration: number;  // Focuses capital where needed
  rebalanceFrequency: number;  // Increases during active markets
}

// Example: High volatility → wider ranges, lower concentration
// Low volatility → tighter ranges, higher concentration

Yield Integrity

Yield integrity means every basis point of return can be traced to its source and verified on-chain. The Yield Engine maintains a complete audit trail of:

• Trading fees earned from liquidity provision
• Execution efficiency gains (price improvement vs benchmark)
• Arbitrage and MEV capture where applicable
• Protocol incentives and rewards
• All costs (transaction fees, impermanent loss, gas)

Architecture Overview

Threeium consists of four primary modules that work together to provide execution, liquidity, and yield optimization:

Execution Engine

The Execution Engine is responsible for intelligent order routing and execution. It analyzes market conditions, liquidity availability, and execution constraints to determine optimal routing strategies.

Key Features

• Smart Order Routing: Split orders across multiple venues for best execution
• Real-Time Adaptation: Adjust routing mid-execution based on fill rates
• Slippage Protection: Enforce maximum slippage bounds with automatic rejection
• TWAP/VWAP: Time or volume-weighted execution strategies for large orders

Execution Flow Example

// Submit an execution request
const executionRequest = {
  asset: 'SOL/USDC',
  side: 'buy',
  amount: 10000,  // $10k worth
  constraints: {
    maxSlippage: 0.005,  // 0.5% max slippage
    minFillRate: 0.95,   // At least 95% filled
    timeLimit: 60,       // Complete within 60s
    strategy: 'adaptive' // Let system optimize
  }
};

// Engine plans the execution
const plan = await executionEngine.planExecution(executionRequest);

// Example plan output:
// {
//   routes: [
//     { venue: 'Jupiter', percentage: 60, expectedSlippage: 0.002 },
//     { venue: 'Orca', percentage: 30, expectedSlippage: 0.003 },
//     { venue: 'Internal Liquidity', percentage: 10, expectedSlippage: 0 }
//   ],
//   estimatedExecutionTime: 8,
//   estimatedCost: 0.25  // SOL
// }

// Execute the plan
const result = await executionEngine.execute(plan);

// Result includes:
// - Actual fill price vs expected
// - Total slippage incurred
// - Execution time
// - Transaction signatures for verification

Liquidity Engine

The Liquidity Engine manages dynamic liquidity positioning across venues. It monitors market conditions, execution patterns, and opportunity signals to continuously adjust liquidity positions for optimal capital efficiency and fee capture.

Liquidity Strategies

Configuration Example

// Configure liquidity management
await liquidityEngine.configure({
  asset: 'SOL/USDC',
  strategy: 'adaptive-bands',
  capital: 100000,  // $100k allocated
  parameters: {
    baseWidth: 0.02,           // 2% base range width
    volatilityMultiplier: 1.5, // Expand range 1.5x during volatility
    rebalanceThreshold: 0.01,  // Rebalance when price moves 1%
    minLiquidity: 0.2,         // Keep 20% minimum in range
    feeTarget: 0.0005          // Target 5bps per trade
  },
  riskLimits: {
    maxImpermanentLoss: 0.05,  // Max 5% IL before adjustment
    maxDrawdown: 0.1           // Max 10% drawdown trigger pause
  }
});

// The engine handles:
// - Initial position creation
// - Continuous monitoring and rebalancing
// - Fee collection and reinvestment
// - Risk limit enforcement

Yield Engine

The Yield Engine tracks all sources of returns, calculates net yields after costs, and provides transparent accounting. Every basis point of yield can be traced to its on-chain source.

Yield Sources

Yield Calculation

// Yield is calculated continuously
interface YieldBreakdown {
  liquidityFees: number;      // Fees from LP positions
  executionSavings: number;   // Price improvement
  protocolRewards: number;    // External incentives
  mevCapture: number;         // Arbitrage profits
  
  totalRevenue: number;
  
  // Costs deducted
  transactionCosts: number;   // Gas fees
  impermanentLoss: number;    // IL from LP positions
  slippage: number;           // Execution slippage
  
  totalCosts: number;
  
  netYield: number;           // Revenue - Costs
  apy: number;                // Annualized percentage yield
}

// Query yield for a position
const yield = await yieldEngine.getYieldBreakdown({
  position: 'SOL-USDC-LP-001',
  timeframe: '30d'
});

// Everything is verifiable on-chain
console.log(`Net Yield: ${yield.netYield} USDC`);
console.log(`APY: ${yield.apy.toFixed(2)}%`);
console.log(`Sources: ${JSON.stringify(yield, null, 2)}`);

Telemetry & Observability

The Telemetry module records comprehensive metrics and events on-chain, providing full visibility into system operations and performance:

Metrics Tracked

• Execution metrics: fill rates, slippage, timing, routing decisions
• Liquidity performance: fees earned, impermanent loss, position health
• Yield attribution: source breakdown, cost analysis, net returns
• System health: latency, error rates, capacity utilization

// Query telemetry data
const metrics = await telemetry.query({
  startTime: Date.now() - 86400000,  // Last 24h
  endTime: Date.now(),
  metrics: [
    'execution.fill_rate',
    'execution.avg_slippage',
    'liquidity.fees_earned',
    'yield.net_apy'
  ]
});

// All data is timestamped and on-chain
metrics.forEach(metric => {
  console.log(`${metric.name}: ${metric.value} at ${metric.timestamp}`);
});

Risk Controls & Guardrails

Built-in risk management ensures safe operation under all market conditions:

maxPositionSize: {
  perAsset: 1000000,  // $1M per asset
  perVenue: 500000,   // $500k per venue
  total: 5000000      // $5M total exposure
}

slippageProtection: {
  maxSlippage: 0.005,        // 0.5% hard limit
  warningThreshold: 0.003,   // Alert at 0.3%
  autoReject: true           // Reject if exceeded
}

circuitBreakers: {
  priceDeviation: 0.1,      // Pause if 10% price swing
  volumeAnomaly: 5.0,       // Pause if 5x normal volume
  errorRate: 0.05,          // Pause if 5% error rate
  manualOverride: true      // Allow manual pause
}

oracleConfig: {
  sources: ['Pyth', 'Switchboard', 'Chainlink'],
  minSources: 2,            // Require 2+ agreeing sources
  maxStaleness: 30,         // 30s max stale data
  deviationThreshold: 0.02  // 2% max deviation between sources
}

End-to-End Flow

Here's how a typical interaction flows through the Threeium system, from initial signal to final yield accounting:

const signal = await threeium.submitSignal({
  asset: 'SOL/USDC',
  side: 'buy',
  amount: 50000,
  maxSlippage: 0.005,
  timeLimit: 120
});

// Engine creates execution plan
plan: {
  routes: [
    { venue: 'Jupiter', amount: 30000 },
    { venue: 'Orca', amount: 15000 },
    { venue: 'Internal', amount: 5000 }
  ],
  expectedSlippage: 0.003,
  estimatedTime: 45
}

Integration Guide

Threeium is designed to integrate seamlessly with existing Solana protocols, vaults, and applications. Here's how different types of projects can leverage the system:

For Protocols & DAOs

Protocols can integrate Threeium for treasury management, protocol-owned liquidity (POL) optimization, or as execution infrastructure for their users.

// Treasury integration
const treasury = await threeium.initializeTreasury({
  authority: dao.governanceProgram,
  assets: ['SOL', 'USDC', 'BONK'],
  strategy: 'conservative',
  yieldTarget: 0.05  // 5% APY target
});

// POL deployment
const pol = await threeium.deployLiquidity({
  protocol: 'MyProtocol',
  asset: 'PROTOCOL/USDC',
  amount: 500000,
  strategy: 'execution-aware',  // Adapt to user demand
  feeEarnings: 'compound'       // Reinvest fees
});

For Vault Managers

Vault strategies can leverage Threeium's execution and liquidity engines to improve performance. The system can act as a sub-strategy or handle the entire vault operation.

// Integrate Threeium into your vault
import { ThreeiumVaultStrategy } from '@threeium/sdk';

const strategy = new ThreeiumVaultStrategy({
  vault: vaultPubkey,
  allocation: 0.3,  // 30% of vault TVL
  assets: ['SOL-USDC', 'SOL-USDT'],
  riskProfile: 'moderate',
  rebalanceFrequency: '24h'
});

await strategy.initialize();

// Strategy handles:
// - Optimal execution for rebalancing
// - Dynamic liquidity positioning
// - Yield optimization
// - Risk management

// Query performance
const performance = await strategy.getPerformance();
console.log(`Net APY: ${performance.apy}%`);
console.log(`Sharpe Ratio: ${performance.sharpe}`);

For Applications

Applications can use Threeium as execution infrastructure to provide users with better prices and lower slippage.

// Use Threeium for swap execution
import { ThreeiumSwap } from '@threeium/sdk';

const swap = await ThreeiumSwap.execute({
  userWallet: wallet.publicKey,
  inputToken: 'SOL',
  outputToken: 'USDC',
  amount: 10,  // 10 SOL
  slippageTolerance: 0.005
});

// Threeium routes across venues for best execution
console.log(`Filled at: ${swap.executionPrice}`);
console.log(`Slippage: ${swap.actualSlippage}%`);
console.log(`Saved vs Jupiter: ${swap.savingsVsBenchmark} USDC`);

Parameters & Configuration

Threeium exposes several configurable parameters to customize behavior for your use case. All parameters have sensible defaults but can be adjusted within safe bounds.

Execution Parameters

Liquidity Parameters

Risk Parameters

Security Model

Threeium is designed with security as a foundational principle. This section outlines the threat model, assumptions, and security measures implemented throughout the system.

Threat Model

Threeium considers and mitigates the following threat vectors:

• Smart contract vulnerabilities: Reentrancy, integer overflow, logic errors, and access control issues
• Oracle manipulation: Price feed attacks, staleness exploits, and source compromise
• MEV and front-running: Transaction ordering manipulation and sandwich attacks
• Governance attacks: Admin key compromise, parameter manipulation, and upgrade exploits
• Integration risks: Malicious or compromised external protocols and venues

Security Measures

Security Assumptions

The system operates under these security assumptions:

• Solana network operates correctly and maintains liveness with reasonable finality guarantees
• Price oracles (Pyth, Switchboard, Chainlink) provide accurate data within acceptable staleness bounds
• Integrated DEXs and protocols function as documented without malicious behavior
• Users and integrators configure appropriate risk parameters for their use cases
• Governance participants act in good faith and follow established procedures

Frequently Asked Questions

Changelog

Track updates, improvements, and milestones in the Threeium project: