PokePerp

PokePerp: Pokémon index perpetuals

PokePerp is a decentralized perpetuals protocol designed around clarity, composability, and risk-first engineering. It combines a compact, auditable set of smart contracts with a lightweight off-chain reporter and a simple web UI to enable margin-based long/short exposure with deterministic on-chain settlement. The system is built with Solidity (Foundry) and a TypeScript reporter, and supports local E2E testing with Anvil as well as real deployments for demo purposes.

Live demo: https://pokeperp-delta.vercel.app/

What It Does

• Enables margin trading on perpetual markets with transparent on-chain settlement.

• Uses a native Oracle to provide reliable index prices for fills and PnL.

• Applies strict pre- and post-trade risk checks before state transitions finalize.

Architecture at a Glance

• Oracle: Accepts reporter-submitted prices and exposes the current index used for settlement.

• Vault: Custodies collateral (TestUSDC in the demo), updates balances, and applies realized PnL.

• RiskEngine: Performs health checks and enforces margin requirements around each trade action.

• PerpEngine: Implements core perpetual logic, position transitions, and PnL calculations.

• OrderBook: Stores order intents and orchestrates order placement and execution entry points.

• SettlementHook: Optional hook for post-trade settlement actions and integrations.

• Reporter (off-chain): A TypeScript service that publishes price updates to the Oracle; pairs with local E2E tooling (Anvil) for deterministic tests.
  
  

This separation keeps the surface area small and the responsibilities clear, making the system easier to audit and reason about.

User Flow

• Connect a wallet to the demo app.

1. Obtain test collateral (TestUSDC) and deposit to the Vault as margin.

2. Place an order via the OrderBook; the PerpEngine evaluates the intent through the RiskEngine.

3. On execution, the Oracle’s price is read, PnL is computed, and balances are updated in the Vault through a deterministic settlement path.

Deployed Contracts (Demo)

Note: These addresses reflect the current demo deployment.

Why This Design

• Modular and explicit: Each component has a single responsibility and a narrow interface.

• Deterministic settlement: Clear ordering from order intent to state transition improves reproducibility and safety.

• Developer-friendly: Built with Solidity 0.8.29 and Foundry; TypeScript reporter; local-first E2E testing via Anvil.

• Chain readiness: Designed for practical deployments (e.g., Arbitrum) while maintaining local test parity.

Status and Next Steps

• Current: Demo deployment, end-to-end flow, and oracle-reporter integration.

• Next: Additional markets, expanded risk parameters, liquidation keepers, further UI polish, and third-party audits.

Security Notice

This is a hackathon-stage project and has not been audited. Use only with test collateral.