Skip to content

Latest commit

 

History

History
196 lines (151 loc) · 4.79 KB

README.md

File metadata and controls

196 lines (151 loc) · 4.79 KB

Yield Guard 🛡️

A non-custodial auto stop-loss vault powered by Pyth oracle on Solana.

Overview

Yield Guard protects DeFi investors from market crashes by automatically executing stop-loss orders when prices hit your configured threshold. The vault automatically swaps tokens to USDC via Jupiter DEX.

Features

  • Non-custodial: Assets are held by program-derived addresses (PDAs), the admin cannot withdraw funds
  • Automatic Execution: Anyone can trigger stop-loss when price conditions are met
  • Pyth Oracle Integration: Real-time price feeds with confidence validation
  • Jupiter DEX: Best rate token swap aggregation
  • Comprehensive Security: PDA protection, stale price checks, overflow protection

Architecture

User
  │
  ├─► InitializeVault (create vault for a token)
  │
  ├─► Deposit (add tokens to vault)
  │
  ├─► UpdateStopLoss (change threshold)
  │
  ├─► [Price drops below threshold]
  │       │
  │       └─► ExecuteStopLoss (auto-swap to USDC)
  │
  └─► ClaimRewards (withdraw USDC)

Instructions

Instruction Description
initialize_vault Create a new stop-loss vault for a token
deposit Deposit tokens into the vault
withdraw Withdraw tokens (disabled after stop-loss triggered)
update_stop_loss_price Update the stop-loss threshold
execute_stop_loss Trigger stop-loss (anyone can call)
claim_rewards Claim USDC after stop-loss

Account Structure

Vault

Stores vault configuration and state:

  • authority: Vault owner
  • token_mint: Token to be protected
  • price_feed: Pyth price feed account
  • stop_loss_price: Trigger price threshold
  • is_stop_loss_triggered: Stop-loss executed flag
  • total_value_locked: TVL in the vault

UserPosition

Per-user position tracking:

  • owner: Position owner
  • deposited_amount: Token amount deposited
  • entry_price: Price at time of deposit
  • is_liquidated: Position liquidated flag

Security Features

  1. PDA Protection: All accounts use program-derived addresses with canonical bumps
  2. Oracle Validation:
    • Stale price detection (max 60 seconds)
    • Confidence ratio check (max 50%)
  3. Arithmetic Safety: All math uses checked operations
  4. CPI Whitelisting: Only Jupiter and Token programs can. Idemp be called 5otent Execution: Stop-loss can only trigger once

Program ID

GuaRG7Ydz2gEeY5z7z9hH8f9vQxJpJcVmGpYqK3W3YxW

Building

# Install dependencies
npm install

# Build the program
npm run build
# or
cargo build-sbf --manifest-path=programs/yield-guard/Cargo.toml

# Run tests
npm run test

Testing

The project uses a three-tier testing approach:

  1. Unit Tests (tests/unit/): Fast Rust tests with Mollusk
  2. Integration Tests (tests/integration/): LiteSVM tests
  3. End-to-End Tests (tests/yield-guard.ts): TypeScript tests
# Run all tests
npm run test

# Run Rust unit tests only
npm run test:unit

Deployment

Localnet

solana-test-validator
anchor deploy

Devnet

anchor deploy --provider.cluster devnet

Mainnet

anchor deploy --provider.cluster mainnet

Usage Example

// 1. Initialize vault
await program.methods
  .initializeVault({ stopLossPrice, slippageTolerance, cooldownSeconds })
  .accounts({ /* accounts */ })
  .rpc();

// 2. Deposit tokens
await program.methods
  .deposit(new BN(amount))
  .accounts({ /* accounts */ })
  .rpc();

// 3. When price drops below threshold, anyone can trigger
await program.methods
  .executeStopLoss(quoteBytes)  // quote from Jupiter API
  .accounts({ /* accounts */ })
  .rpc();

// 4. Claim USDC
await program.methods
  .claimRewards()
  .accounts({ /* accounts */ })
  .rpc();

Project Structure

├── programs/yield-guard/
│   ├── src/
│   │   ├── lib.rs        # Main program (instructions + accounts)
│   │   ├── state.rs      # Account structs + events
│   │   └── errors.rs     # Error definitions
│   └── Cargo.toml
├── tests/
│   ├── yield-guard.ts    # TypeScript integration tests
│   ├── unit/mod.rs       # Mollusk unit tests
│   └── integration/mod.rs # LiteSVM integration tests
├── Anchor.toml           # Anchor configuration
├── package.json          # npm scripts
└── tsconfig.json         # TypeScript config

Dependencies

  • Anchor 0.30.1
  • Solana 1.18.0
  • TypeScript 5.0

Security Audit

This is experimental software. Before mainnet deployment:

  1. Get a professional security audit
  2. Increase test coverage
  3. Add upgrade authority with timelock
  4. Consider formal verification

License

MIT

Contributing

Open source for hackathon participation. Contributions welcome!