On-Chain Perpetuals Infrastructure

Ethereum Sepolia · Non-Custodial · Zero Gas

A fully on-chain perpetuals exchange with zero off-chain dependencies.
Chainlink price oracles · ERC-4337 gasless smart accounts · CCIP cross-chain margin · 50× leverage.

💻 Source Code  ·  📜 Docs  ·  🔗 PositionManager  ·  🚰 Get Testnet USDC

Most DeFi perp protocols rely on off-chain matching engines, centralized price feeds, or custodial bridges. Nexus Perps eliminates every one of these dependencies — every price fetch, every liquidation, every settlement runs entirely on-chain with no external coordination layer.

1. 🏛️ Architecture
2. ✅ Deployed Contracts
3. 🧩 Contract Reference
4. 💻 Frontend Stack
5. 🧪 Test Suite & Coverage
6. 🛠️ Local Setup
7. 🔐 Security Model

Five isolated protocol layers. A failure in cross-chain routing cannot affect vault solvency. The oracle layer is fully stateless with zero write access to core contracts.

┌──────────────────────────────────────────────────────────────────┐
│                        USER / DAPP                               │
│         RainbowKit · Wagmi v2 · Viem · Next.js 14 App Router     │
└───────────────────────────┬──────────────────────────────────────┘
                            │
┌───────────────────────────▼──────────────────────────────────────┐
│                 ACCOUNT ABSTRACTION  (ERC-4337)                  │
│   SmartAccount.sol ── AccountFactory.sol ── NexusPaymaster.sol   │
│   Gasless UserOps · EIP-712 signing · CREATE2 deterministic AA   │
└───────────────────────────┬──────────────────────────────────────┘
                            │
┌───────────────────────────▼──────────────────────────────────────┐
│                      TRADING ENGINE                              │
│   PositionManager.sol  ·  PnLCalculator.sol  ·  LiquidationEngine│
│   Market & limit orders · Isolated/Cross margin · Batch keepers  │
└────────────┬─────────────────────────────────┬───────────────────┘
             │                                 │
┌────────────▼────────────┐       ┌────────────▼────────────────── ┐
│      VAULT LAYER        │       │        ORACLE LAYER             │
│   PerpsVault.sol        │       │   PriceOracle.sol               │
│   18-dec precision      │       │   Chainlink BTC/USD + ETH/USD   │
│   LP share system       │       │   Heartbeat staleness guard     │
│   settleTrade / PnL     │       │   Normalized to 1e18            │
└─────────────────────────┘       └─────────────────────────────────┘
             │
┌────────────▼────────────────────────────────────────────────────┐
│                  CROSS-CHAIN LAYER  (CCIP)                       │
│   CrossChainRouter.sol ── encodes & sends trade requests         │
│   MessageReceiver.sol  ── decodes, deduplicates nonce, executes  │
│   Source chain + sender whitelist · try/catch pipeline safety    │
└─────────────────────────────────────────────────────────────────┘

1. No off-chain trust — Price discovery, execution, liquidation, settlement — all fully on-chain.

2. 18-decimal precision throughout — DECIMALS_SCALAR = 10^(18 - tokenDecimals) normalizes USDC (6 dec) to 1e18 internally, eliminating dust-sweep and rounding bugs.

3. Vault solvency is an invariant — 128 runs × 50 calls = 6,400 randomized state mutations, zero reverts against totalLiquidity + totalLockedCollateral + totalTraderFreeCollateral == ASSET.balanceOf(vault).

4. Isolated margin by default — Cross-margin mode uses _calculateGlobalPnL iterating all active positions for holistic equity checks before liquidation.

All contracts deployed on Ethereum Sepolia and verified on Etherscan.

nexus-perps/
├── src/
│   ├── core/
│   │   ├── PositionManager.sol       # Trading engine: market/limit/liquidate/cross-chain
│   │   ├── PerpsVault.sol            # Collateral & LP vault (18-dec precision)
│   │   └── LiquidationEngine.sol     # Keeper-compatible batch liquidator
│   ├── math/
│   │   └── PnLCalculator.sol         # Pure library: PnL, liquidation health, overflow guards
│   ├── oracles/
│   │   └── PriceOracle.sol           # Chainlink aggregator + heartbeat staleness
│   ├── account-abstraction/
│   │   ├── SmartAccount.sol          # ERC-4337: EIP-712 signing, nonce, batch execution
│   │   ├── AccountFactory.sol        # CREATE2 deterministic EIP-1167 clone factory
│   │   └── NexusPaymaster.sol        # Verifying paymaster, chain-ID bound, packed storage
│   ├── cross-chain/
│   │   ├── CrossChainRouter.sol      # CCIP message sender + fee estimation
│   │   └── MessageReceiver.sol       # CCIP receiver + nonce dedup + try/catch execution
│   ├── interfaces/
│   │   ├── IPerpsCore.sol            # Position struct, MarginMode enum, events
│   │   ├── IPriceOracle.sol
│   │   ├── ICrossChain.sol
│   │   └── IEntryPoint.sol
│   └── errors/
│       └── PerpsErrors.sol           # Centralized custom error library (29 errors)
└── web3-app/
    └── src/
        ├── app/                      # Next.js 14 App Router
        │   ├── page.tsx              # Landing page (Server Component)
        │   ├── trade/page.tsx        # Trading interface
        │   ├── vaults/page.tsx       # LP vault interface
        │   ├── portfolio/page.tsx    # Position dashboard
        │   ├── docs/page.tsx         # Protocol docs
        │   └── api/sign/route.ts     # AA session signing endpoint
        ├── components/
        │   ├── AccountVerification.tsx  # Smart account login flow ('use client')
        │   ├── TradingViewWidget.tsx
        │   ├── layout/Navbar.tsx
        │   └── providers/Web3Provider.tsx
        ├── hooks/
        │   ├── useNexusAccount.ts    # AA session state machine
        │   ├── useVaultOperations.ts # deposit/withdraw/addLiquidity/removeLiquidity
        │   ├── useLPOperations.ts    # LP share tracking
        │   ├── useVaultStats.ts      # totalLiquidity, totalLocked, APY
        │   └── usePortfolioData.ts   # Per-trader positions + collateral
        └── constants/
            ├── contracts.ts          # All deployed addresses
            └── abis/                 # 100+ auto-generated ABI JSON files

Full position lifecycle: open → update → close → liquidate.

• Market Orders — openPosition() validates oracle price, locks collateral in vault, stores position at current Chainlink price
• Limit Orders — placeLimitOrder() locks collateral optimistically. Keeper calls executeLimitOrder() when price condition met, earns keeperRewardBps deducted from collateral
• Cross-Chain Trades — executeCrossChainTrade() gated by onlyCrossChainReceiver. Positions flagged isCrossChain = true bypass local vault settlement on close
• Liquidations — Isolated mode uses PnLCalculator.isLiquidatable(). Cross-margin computes totalEquity = vaultCollateral + globalPnL across all active positions via _calculateGlobalPnL
• Asset Tracking — Swap-and-pop O(1) removal. Capped at maxActiveAssets per trader

Single contract holding all trader collateral and LP liquidity with strict dual accounting.

• Dual accounting — traderCollateral (free) and lockedCollateral (in positions) tracked separately. totalTraderFreeCollateral global invariant maintained on every state change
• LP Shares — First deposit burns MINIMUM_LIQUIDITY = 1000 permanently preventing inflation attacks. Subsequent deposits: sharesToMint = scaledAmount * totalLpShares / totalLiquidity
• settleTrade() — Atomically unlocks collateral → adjusts totalLiquidity for PnL → credits payout to trader. Physical token balance checked as safety floor before payout
• Dust prevention — withdraw() enforces scaledAmount % DECIMALS_SCALAR == 0

Pure Solidity library, zero state, no imports except interfaces.

positionSize   = (collateral × leverage) / 1e18
PnL            = (priceDelta × positionSize) / entryPrice
isLiquidatable = equity ≤ maintenanceMargin
               = (collateral + PnL) ≤ (collateral × liquidationThresholdBps / 10000)

Overflow guard inside unchecked {}: checks priceDelta * size <= type(uint256).max before multiplication. Reverts with PerpsErrors.InvalidAmount() on overflow.

EIP-1167 clone-compatible, EIP-712 structured signing.

• validateUserOp() — verifies nonce, recovers signer from USER_OP_TYPEHASH struct hash via ECDSA.tryRecover. Pays missingAccountFunds to EntryPoint. Returns 0 (success) or 1 (failure)
• execute() / executeBatch() — callable only by EntryPoint. Batch validates array length parity. Uses inline assembly { revert(add(result, 32), mload(result)) } to bubble downstream errors
• _disableInitializers() in constructor prevents the implementation contract itself from being initialized as an attack vector

Packed storage: verifyingSigner (20 bytes) + maxCostLimit (12 bytes) fits in 1 storage slot.

• paymasterAndData must be exactly 85 bytes (20 addr + 65 sig) — any other length rejected
• Signs keccak256(userOpHash, block.chainid, address(this)) — chain + contract binding prevents cross-chain replay

• Encodes (trader, nonce, token, isLong, margin, leverage) as ABI payload, sent via CCIP_ROUTER.ccipSend
• Refunds surplus ETH via call{value: refundAmount, gas: 3000} — intentionally ignores return (no reentrancy vector, documented in code)
• rescueFunds() differentiates ETH rescue (address(this).balance - operationalBalance) from ERC20 rescue to prevent double-counting

• Source chain whitelist + sender address whitelist — double-gated access control
• Per-trader nonce deduplication: processedNonces[trader][nonce] prevents replay before execution
• try/catch wraps positionManager.executeCrossChainTrade() — failed trades emit TradeFailed but never block the CCIP pipeline

Next.js 14 App Router with zero backend dependency for read operations. All contract reads use Wagmi v2 + Viem directly from the browser.

AccountVerification.tsx ('use client') drives a 5-step state machine via useNexusAccount:

idle
 └─▶ fetching_nonce       GET /api/sign/route.ts → server generates EIP-712 nonce
       └─▶ awaiting_signature   wallet.signTypedData()
             └─▶ verifying      POST /api/sign → server verifies signature + issues JWT
                   └─▶ deploying_account  AccountFactory.createAccount() if new wallet
                         └─▶ done    24h session active · gas sponsored by NexusPaymaster

Each step renders its own UI: spinner, progress bar, error retry. page.tsx (Server Component) simply imports <AccountVerification /> — no 'use client' needed on the page, no server/client boundary error.

Unit Tests — Every function in isolation. Success paths, revert conditions, access control, edge cases (zero amounts, stale prices, unauthorized callers, zero addresses).

Integration Tests:

• AAFlowIntegrationTest — Smart account deploy → UserOp validation → batch trade execution → unauthorized block
• CrossChainIntegrationFlowTest — Full CCIP encode → router send → receiver decode → PositionManager execute → invalid asset revert → direct call block
• LiquidationFlowIntegrationTest — Stale price oracle protection, precise math solvency, mixed-state batch resilience

Fuzz Tests (256 runs each):

• testFuzz_OpenRandomPositions — random collateral + leverage, validates no panic or unexpected revert
• testFuzz_LiquidationMathSolvency — validates vault never insolvent under any liquidation scenario

Invariant Tests (128 runs × 50 calls = 6,400 state mutations, 0 reverts):

╭─────────────────────┬────────────────────┬───────┬─────────┬──────────╮
│ Contract            │ Selector           │ Calls │ Reverts │ Discards │
╞═════════════════════╪════════════════════╪═══════╪═════════╪══════════╡
│ PositionHandler     │ changeOraclePrice  │ 1,541 │       0 │        0 │
│ PositionHandler     │ createTrader       │ 1,603 │       0 │        1 │
│ PositionHandler     │ openRandomPosition │ 1,659 │       0 │        0 │
│ PositionHandler     │ tryLiquidation     │ 1,598 │       0 │        0 │
╰─────────────────────┴────────────────────┴───────┴─────────┴──────────╯

• invariant_VaultIsSolvent — totalLiquidity ≥ 0 holds across all state mutations
• invariant_InternalAccountingConsistent — sum of all internal balances matches physical ASSET.balanceOf(vault)
• invariant_MaxActiveAssetsRespected — no trader ever exceeds maxActiveAssets

• Foundry (forge, cast, anvil)
• Node.js ≥ 18
• Alchemy API key for Sepolia RPC

git clone https://github.com/NexTechArchitect/Nexus-Protocol.git
cd Nexus-Protocol

# Install Foundry dependencies
forge install

# Run full test suite (95 tests, ~3s)
forge test -vv

# Generate coverage report
forge coverage

# Deploy to Sepolia
cp .env.example .env
# Fill: PRIVATE_KEY, RPC_URL, ETHERSCAN_API_KEY
forge script script/deploy/05_FullDeploy.s.sol --rpc-url sepolia --broadcast --verify

cd web3-app
npm install

cp .env.local.example .env.local
# NEXT_PUBLIC_ALCHEMY_RPC_URL=https://eth-sepolia.g.alchemy.com/v2/YOUR_KEY

npm run dev
# → http://localhost:3000

1. Go to faucet.circle.com
2. Select Ethereum Sepolia (not mainnet)
3. Enter wallet address → receive USDC
4. Deposit via Vaults page → start trading

⚠️ No formal external security audit has been conducted. Deployed on Sepolia testnet with testnet assets only. Do not use with real funds.

Nexus Perps runs exclusively on Ethereum Sepolia. All USDC is Circle testnet USDC with zero real-world value. Faucet at faucet.circle.com — select Ethereum Sepolia only. This is not financial advice.