Tethra DEX - Smart Contracts

Perpetual futures trading protocol with up to 100x leverage, deployed on Flow EVM Testnet and Base Sepolia with Account Abstraction (USDC gas payments) and Privy smart wallets integration.

🌟 Key Features

⚡ Instant Market Orders - Execute trades immediately at current oracle price
📊 High Leverage - Up to 100x on BTC/ETH, 20x on altcoins
🎯 Advanced Orders - Limit orders, stop-loss, take-profit, grid trading
💵 USDC Gas Payments - Pay transaction fees in USDC via Account Abstraction
🎲 One Tap Profit - Short-term price prediction betting (30s-5min)
🔐 Privy Smart Wallets - Embedded wallets with email/social login
💎 Dual Token Economy - USDC for trading, TETH for governance & rewards

🚀 Quick Start

Prerequisites

Foundry installed
Testnet ETH for deployment:
- Flow: Flow Testnet Faucet
- Base: Base Sepolia Faucet
Private key with ETH for deployment

Installation

# Clone repository
git clone <your-repo-url>
cd tethra-dex/tethra-sc

# Install dependencies
forge install

# Compile contracts
forge build

Testing

# Run all tests
forge test

# Run with gas report
forge test --gas-report

# Run with verbose output
forge test -vvv

📁 Project Structure

tethra-sc/
├── src/
│   ├── token/
│   │   ├── TethraToken.sol          # TETH governance token (10M supply)
│   │   └── MockUSDC.sol             # Test USDC with faucet
│   ├── risk/
│   │   └── RiskManager.sol          # Trade validation & risk checks
│   ├── trading/
│   │   ├── PositionManager.sol      # Position tracking & PnL calculation
│   │   ├── MarketExecutor.sol       # Market order execution
│   │   ├── LimitExecutorV2.sol      # Limit/stop-loss orders
│   │   ├── TapToTradeExecutor.sol   # Fast tap-to-trade orders
│   │   └── OneTapProfit.sol         # Price prediction betting
│   ├── treasury/
│   │   └── TreasuryManager.sol      # Central treasury & fee management
│   ├── paymaster/
│   │   └── USDCPaymaster.sol        # Account Abstraction paymaster
│   └── staking/
│       ├── TethraStaking.sol        # Stake TETH → Earn USDC
│       └── LiquidityMining.sol      # Provide USDC → Earn TETH
├── script/
│   └── FullDeploy.s.sol             # Complete deployment script
├── test/                             # Foundry tests
└── foundry.toml                      # Foundry configuration

📦 Smart Contracts Overview

Core Trading Contracts (5)

Contract	Description	Key Features
RiskManager	Trade validation & risk management	Leverage limits (100x BTC/ETH, 20x alts), Liquidation checks
PositionManager	Position tracking & PnL	Real-time PnL calculation, Position history
MarketExecutor	Market order execution	Instant fills, Signed price verification
LimitExecutorV2	Advanced orders	Limit orders, Stop-loss, Take-profit, Grid trading
TreasuryManager	Treasury management	Fee collection, Profit distribution, Liquidity pool

Infrastructure Contracts (3)

Contract	Description	Purpose
TethraToken	TETH governance token	10M supply, Staking rewards, Governance
MockUSDC	Test USDC	Faucet (1,000 USDC/claim) for testing
USDCPaymaster	Account Abstraction	Pay gas fees with USDC

Incentive Contracts (2)

Contract	Description	Rewards
TethraStaking	Stake TETH tokens	Earn 30% of trading fees in USDC
LiquidityMining	Provide USDC liquidity	Earn TETH tokens (1 per block)

Specialty Trading (2)

Contract	Description	Features
TapToTradeExecutor	Fast order execution	Backend-managed instant trades
OneTapProfit	Price prediction betting	30s-5min duration, 2x multiplier

🔧 Deployment

Quick Deploy (All Contracts)

Deploy to Flow EVM Testnet:

forge script script/FullDeploy.s.sol \
  --rpc-url https://testnet.evm.nodes.onflow.org \
  --private-key YOUR_PRIVATE_KEY \
  --broadcast

Deploy to Base Sepolia:

forge script script/FullDeploy.s.sol \
  --rpc-url https://sepolia.base.org \
  --private-key YOUR_PRIVATE_KEY \
  --broadcast

This will:

✅ Deploy all 12 contracts (tokens, trading, staking, paymaster)
✅ Grant all necessary roles (EXECUTOR_ROLE, KEEPER_ROLE, etc.)
✅ Initialize TethraToken distribution
✅ Connect contracts (Treasury → Staking, etc.)
✅ Save deployment addresses to JSON file

Post-Deployment

After deployment, copy contract addresses to your backend .env file with the appropriate prefix (FLOW_* or BASE_*).

📦 Deployed Contracts

Flow EVM Testnet (Chain ID: 545)

Token Contracts:

USDC: 0x2c6887Fa522B551992974b68ffB1660f6d2F8340
Tethra Token (TETH): 0xff9EEdD3Ca844794fb9934D4Fa56dE5Ca89c6fbA

Core Trading Contracts:

Risk Manager: 0xc04B2294D30D6e077B1736d84A11DFe6f68e9745
Position Manager: 0x29Bc61d98d9BD0298C010D59A5C2e5a2CB5D8958
Treasury Manager: 0xADbb3D9eE68d701e61bA49DDe3fa85e4864c00e9
Market Executor: 0x5f6fe2dee3A77F255057A4210958784B60A9C66D

Advanced Trading:

Limit Executor: 0x9782F89bDB822059FeaC76425b10f81A1E2d5d3f
Tap To Trade Executor: 0xD59551d80BDfe94662ACed1d27b5b12792711072
One Tap Profit: 0x42C53C1769779277B74bD89b3e6994E88d33E285

Staking & Incentives:

Tethra Staking: 0x3c30c160406fd840A571B65fD475A91F960B730E
Liquidity Mining: 0xE9de7BF710B98D465BB90a92599F40431b0D3Bf8

Infrastructure:

USDC Paymaster: 0x3aB9B3DD9D96F063902A8FE12Ed1401e26c5D533

Explorer: Flow EVM Testnet

Base Sepolia (Chain ID: 84532)

Token Contracts:

USDC: 0x9d660c5d4BFE4b7fcC76f327b22ABF7773DD48c1
Tethra Token (TETH): 0x6f1330f207Ab5e2a52c550AF308bA28e3c517311

Core Trading Contracts:

Risk Manager: 0x08A23503CC221C3B520D2E9bA2aB93E3546d798F
Position Manager: 0x8eA6059Bd95a9f0A47Ce361130ffB007415519aF
Treasury Manager: 0x157e68fBDD7D8294badeD37d876aEb7765986681
Market Executor: 0xA1badd2cea74931d668B7aB99015ede28735B3EF

Advanced Trading:

Limit Executor: 0x8c297677FEA6F0beDC0D1fa139aa2bc23eE6234a
Tap To Trade Executor: 0x79Cb84cF317235EA5C61Cce662373D982853E8d8
One Tap Profit: 0x5D4c52a7aD4Fb6B43C6B212Db1C1e0A7f9B0f73c

Staking & Incentives:

Tethra Staking: 0x69FFE0989234971eA2bc542c84c9861b0D8F9b17
Liquidity Mining: 0x76dc221f50ca56A1E8445508CA9ecc0aD57d0B11

Infrastructure:

USDC Paymaster: 0x94FbB9C6C854599c7562c282eADa4889115CCd8E

Explorer: Base Sepolia Scan

💰 Token Distribution

TETH Token (10,000,000 total):

50% (5M) → Staking Rewards
20% (2M) → Liquidity Mining Rewards
20% (2M) → Team
10% (1M) → Treasury

Distribution is automatic during deployment via TethraToken.initialize().

💵 Fee Structure

Action	Fee	Recipient
Market Trade	0.05% of position size	Protocol (split 50/30/20)
Limit Order Execution	0.5 USDC	Keeper
Liquidation	0.5% of position	Liquidator
Early Unstake (Staking)	10%	Treasury
Early Withdrawal (LP)	15%	Treasury

Fee Distribution:

50% → Liquidity Pool (backs trader profits)
30% → TETH Stakers (via TethraStaking)
20% → Protocol Treasury

🔐 Access Control & Roles

The deployment script automatically grants these roles:

TreasuryManager

EXECUTOR_ROLE → MarketExecutor, LimitExecutorV2, TapToTradeExecutor, OneTapProfit
KEEPER_ROLE → Backend keeper address (for liquidations)

LimitExecutorV2

KEEPER_ROLE → Backend keeper address (for limit order execution)

MarketExecutor

PRICE_SIGNER_ROLE → Backend price signer address

🛡️ Security Features

✅ OpenZeppelin Contracts - Battle-tested security libraries
✅ ReentrancyGuard - All state-changing functions protected
✅ Access Control - Role-based permissions (RBAC)
✅ SafeERC20 - Safe token transfers
✅ Signed Prices - ECDSA verification (5-minute validity)
✅ Immutable Contracts - No upgradability (trustless)
✅ Oracle Validation - Price freshness checks

📊 Leverage Limits

Asset	Max Leverage	Min Collateral
BTC	100x	10 USDC
ETH	100x	10 USDC
SOL, AVAX, NEAR	50x	10 USDC
BNB, XRP, LINK, MATIC	20x	10 USDC
AAVE, ARB, DOGE	20x	10 USDC

🧪 Testing

# Run all tests
forge test

# Test specific contract
forge test --match-contract PositionManagerTest

# Test with gas report
forge test --gas-report

# Test with coverage
forge coverage

🚀 Next Steps

After deploying contracts:

Update Backend
- Copy contract addresses to tethra-be/.env
- Grant PRICE_SIGNER_ROLE to backend signer
- Fund relay wallet with ETH
Update Frontend
- Update contract addresses in frontend config
- Test market orders
- Test limit orders
Add Liquidity
- Call TreasuryManager.addLiquidity() to fund protocol
- Initial recommendation: 10,000 USDC minimum
Test Trading
- Claim Mock USDC from faucet
- Open test positions
- Verify PnL calculations

🔗 Important Links

📄 License

MIT License - see LICENSE file for details

Built with ❤️ by Tethra DEX Team using Foundry

For questions or support, please open an issue on GitHub.

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
.github/workflows		.github/workflows
broadcast		broadcast
lib		lib
script		script
src		src
test		test
.env.example		.env.example
.gitignore		.gitignore
.gitmodules		.gitmodules
LICENSE		LICENSE
README.md		README.md
foundry.lock		foundry.lock
foundry.toml		foundry.toml

License

TethraFi/smartcontract

Folders and files

Latest commit

History

Repository files navigation