Pathfinder

​

What is Pathfinder?

​

The Problem Pathfinder Solves

1. Bridge manually using third-party bridges (Across, Stargate, etc.)
2. Understand chain-specific protocols (Aave on Ethereum vs Arbitrum vs Base)
3. Manage multiple wallets and positions across different chains
4. Swap into yield assets using chain-specific DEXs
5. Monitor and rebalance positions as yields change
6. Handle non-EVM assets by using wrapped versions or CEX on/off-ramps

​

How Pathfinder Works

​

Architecture Overview

​

Hub Chain

• PathfinderVault: Core ERC-4626 vault with accounting logic (totalAssets(), convertToShares(), convertToAssets())
• PathfinderComposer: Handles cross-chain messages via lzCompose()
• ShareOFTAdapter: Bridges share minting/burning between vault and OFT
• Manages asset allocation, rebalancing, and yield generation

​

Spoke Chain

• CommonTokenOFT: ERC-20 + OFT wrapper for common tokens (USDC, USDT, USDe)
• PathfinderShareOFT: ERC-20 + OFT wrapper for vault shares (pf-SHARE)
• Users interact with these contracts on their home chain
• Share tokens are minted/burned via cross-chain messages, maintaining unified accounting

​

Hub Chain Responsibilities

• Maintain canonical accounting (totalAssets(), convertToShares(), convertToAssets()) and enforce buffer constraints on redemptions.
• Own the share supply via ShareOFTAdapter, minting and burning pf-SHARE in response to cross-chain messages.
• Execute deposits, redemptions, and curator-triggered rebalances under role-based access control.
• Produce the single source of truth for share price across every spoke chain.

​

Spoke Chain Responsibilities

• Expose a native ERC-20 interface for deposits (CommonTokenOFT) and withdrawals (PathfinderShareOFT) in the user’s home environment.
• Forward deposits and redemption intents to the hub via LayerZero, without holding inventory or running vault logic locally.
• Deliver pf-SHARE tokens back to users after deposits and return bridged common tokens after redemptions succeed on the hub chain.
• Provide immediate UX feedback — transfers, allowance management, and events all happen on the spoke chain the user already uses.

​

LayerZero Orchestration

​

Deposit Flow

​

Withdrawal Flow (Sufficient Buffer)

​

Withdrawal Flow (Insufficient Buffer)

​

Dual-Asset Accounting

1. Common Token (address public immutable commonToken): ERC-20 token (USDC, USDT, USDe) used for deposits/withdrawals. This provides the liquid buffer for user redemptions.
2. Secondary Asset (address public immutable secondaryAsset): Yield-generating asset (wstETH, Pendle PT, SOL derivatives) held for yield generation. This is where the majority of vault assets are deployed to generate returns.

• uint256 public commonBalance - Current balance of common token
• uint256 public secondaryBalance - Current balance of secondary asset
• uint256 public targetCommonRatio - Target allocation ratio (e.g., 20e16 = 20% common token)

• commonBalance: Common token (USDC, USDT, USDe) - target 20% allocation
• secondaryBalance: Yield-generating asset (wstETH, SOL, PT) - target 80% allocation

• Valuation Oracle (TWAP): Used in totalAssets() for share price calculations - manipulation-resistant, time-weighted average
• Swap Oracle (Spot): Used during rebalance() for execution validation - real-time price from DEX aggregator

• deposit(assets) → mints shares based on current share price
• redeem(shares) → burns shares and returns assets based on current share price
• Share price updates as vault balances and oracle prices change

​

Valuation System

• Used in totalAssets() for share price calculations: commonBalance + (secondaryBalance * getPriceTWAP())
• Provides time-weighted average price over configurable window (e.g., 1 hour)
• Includes staleness check: require(block.timestamp - lastUpdate <= maxStaleness)
• Manipulation-resistant but may lag spot prices during volatile periods

• Used during rebalance() for execution validation
• Provides real-time spot price from DEX aggregator
• Validates minAmountOut against spot price before swap execution
• Acts as secondary check to prevent TWAP manipulation from affecting swap execution

function totalAssets() public view override returns (uint256) {
    uint256 common = commonBalance;
    uint256 secondary = secondaryBalance;
    uint256 secondaryValue = (secondary * valuationOracle.getPriceTWAP()) / 1e18;
    return common + secondaryValue;
}

​

Rebalancing Mechanism

• Calculates current ratio: currentRatio = (commonBalance * 1e18) / totalAssets()
• Compares to targetCommonRatio (e.g., 20e16 = 20%)
• Triggers swap when drift exceeds threshold (e.g., ±5% from target)
• Rebalancing is never triggered by user actions - only by the off-chain agent

1. Monitor: Off-chain agent calls getCurrentAllocation() to check if commonRatio drifts from targetCommonRatio (threshold: ±5%)
2. Quote: If drift detected, agent queries DEX aggregator for swap quote (getQuote(amountIn, tokenIn, tokenOut))
3. Calculate: Agent calculates minAmountOut = quote × 0.95 (5% slippage tolerance)
4. Submit: Agent submits rebalance(amountIn, minAmountOut, swapToSecondary) via private RPC (MEV protection)
5. Validate: Vault validates swapOracle.getPriceSpot() >= minAmountOut before execution
6. Execute: Vault calls swap router, receives amountOut, and updates commonBalance and secondaryBalance atomically

function rebalance(uint256 amountIn, uint256 minAmountOut, bool swapToSecondary) external onlyRebalancer {
    require(!paused, "Paused");
    
    uint256 spotPrice = swapOracle.getPriceSpot();
    require(spotPrice >= minAmountOut, "Slippage too high");
    
    // Execute swap via router
    // Update balances atomically
}

• Only callable by rebalancer role (off-chain agent)
• Never triggered by user actions (deposit()/redeem())
• Validates spot price against minAmountOut before execution
• MEV protection via private RPC submission

​

Security: Buffer-and-Revert Model

​

How It Works

function redeem(uint256 shares) public override returns (uint256 assets) {
    assets = convertToAssets(shares);
    
    // Buffer check: require commonBalance >= assets
    require(commonBalance >= assets, "InsufficientBuffer");
    
    commonBalance -= assets;
    _burn(msg.sender, shares);
    
    IERC20(commonToken).safeTransfer(msg.sender, assets);
    return assets;
}

• Maintains commonBalance (target: 20% of totalAssets())
• Maintains secondaryBalance (target: 80% of totalAssets())
• totalAssets() = commonBalance + (secondaryBalance × TWAP price)

1. User calls redeem(shares)
2. Vault calculates assets = convertToAssets(shares)
3. Vault checks: require(commonBalance >= assets)
4. If sufficient: Transfer assets, burn shares, succeed
5. If insufficient: Revert with InsufficientBuffer error

• When withdrawal reverts, off-chain agent detects buffer depletion
• Agent monitors commonBalance / totalAssets() ratio
• When below threshold, agent calls rebalance() to swap secondary → common
• User can retry withdrawal after buffer is replenished

• Buffer Target: targetCommonRatio (e.g., 20e16 = 20%) maintained via rebalancing to ensure sufficient liquidity
• Revert Condition: require(commonBalance >= assets) in redeem() - no automatic swap on insufficient buffer
• Asynchronous Rebalancing: Off-chain agent monitors commonBalance / totalAssets() and calls rebalance() when below threshold, allowing optimal swap execution
• No User-Triggered Swaps: deposit() and redeem() never call swap functions directly, preventing predictable MEV targets

​

Why This Matters

​

Macroeconomic Rationale: Bank Runs and Solvency

​

The Bank Run Problem

• Illiquid assets: Secondary yield assets (wstETH, SOL, PT) that generate returns but require time to swap at optimal prices
• Liquid liabilities: User deposits redeemable on-demand for USDC

1. Swap large amounts of secondary assets at unfavorable prices (fire sales)
2. Trigger a death spiral as poor execution reduces share value
3. Cause remaining depositors to panic and withdraw, accelerating the collapse

​

How Buffering Prevents Runs

• Small withdrawals (2-5% of buffer) execute immediately
• Buffer decreases, agent detects drift from target ratio
• Agent calls rebalance() to swap secondary → common
• Buffer replenished to target 20% allocation

• Large withdrawal (e.g., 15% of total assets) requested
• Vault checks: commonBalance >= assets?
• If sufficient: Withdrawal succeeds, buffer decreases
• If insufficient: Transaction reverts with InsufficientBuffer
• Agent detects revert, calls rebalance() to swap secondary → common
• User retries withdrawal after buffer replenished

• No user-triggered swaps: Only rebalancer can execute swaps
• Price validation: Spot oracle validates minAmountOut before swap
• MEV protection: Swaps submitted via private RPC (Flashbots)
• Atomic updates: Balance updates happen atomically, no intermediate states

1. Prevents Fire Sales: redeem() reverts with InsufficientBuffer error when commonBalance < assets. No swap is executed automatically. The rebalancing agent can wait for optimal market conditions before calling rebalance(), ensuring swaps happen at favorable prices.
2. Solvency Guarantee: The invariant commonBalance >= sum(pending withdrawals) is maintained up to targetCommonRatio * totalAssets(). Withdrawals up to this threshold execute without touching secondaryBalance, preserving yield generation.
3. Coordination Failure: When commonBalance < assets, the transaction reverts. Users cannot coordinate simultaneous withdrawals exceeding buffer capacity. The rebalancing delay breaks run dynamics by forcing sequential withdrawals.
4. Price Discovery: Asynchronous rebalance() enables:
   • Multi-aggregator quote comparison (getQuote() from 1inch, Paraswap)
   • Optimal timing (wait for favorable market conditions)
   • MEV protection (private RPC submission via Flashbots)
   • Slippage validation (require(spotPrice >= minAmountOut))

​

Solvency Guarantees

​

Real-World Parallels

• Bank Reserve Requirements: Banks must hold reserves to cover withdrawals, preventing runs
• Money Market Fund Gates: During stress, funds can suspend redemptions to prevent fire sales
• Central Bank Lender of Last Resort: Central banks provide liquidity during crises to prevent systemic collapse

​

Additional Security Features

​

Summary

• LayerZero OFT standard for seamless token streaming across chains without user interaction
• Hub-and-spoke architecture separating vault logic (hub) from user interfaces (spokes)
• Dual-asset accounting balancing liquidity buffers with yield generation
• Dual-oracle pricing using TWAP for share valuation and spot prices for swap validation
• Asynchronous rebalancing that aggregates user deposits for efficient execution
• Buffer-based withdrawals preventing MEV exploitation and forced liquidations
• Unified accounting where users hold vault shares, not chain-specific wrapped tokens

• Curators design sophisticated multi-chain strategies
• Pathfinder executes them transparently
• Users see “deposit → yield → withdraw” in their preferred stablecoin
• Security is built into the design through buffer management and MEV protection