How levana-protocol/levana-perps works
Project type and purpose
• This is a full-stack, multi-chain perpetual-swap protocol (Perps V2)
• On-chain: CosmWasm smart contracts (Rust) implementing financial primitives (market, factory, tokens, vaults, copy-trading, etc.)
• Off-chain: CLI executables (Rust bins under packages/perps-exes), TypeScript SDK, CI/CD pipelines, testing harnesses, static site templates
• Research and schema generation are also included
File structure – group into major domains
1. Smart Contracts
– contracts/… subdirs: each CosmWasm contract module (market, factory, cw20, vault, etc.)
2. Off-chain Tools & CLI
– packages/perps-exes/…: Rust binaries (perps-deploy, perps-bots, perps-companion, perps-market-params, perps-qa, perps-bridge) + Web UI templates + CI scripts
3. SDKs
– ts-schema/…: Yarn project that generates TypeScript types from contract schemas
– Native Rust/WASM SDK lives alongside contracts/, exposed via perpswap/… crate
4. Testing & Fuzzing
– packages/multi_test: integration test harness simulating chains & contracts
– packages/fuzz: cargo-fuzz targets on core logic
– contracts/*/proptest-regressions
5. CI/CD and DevOps
– .ci/: Dockerfiles, shell scripts for building contracts, migrating chains, packaging source tarballs
– .github/workflows: YAML for build, test, bots, market-analyzer, perps-deploy pipelines
– justfile: recipe runner for local commands (build-contracts, local-deploy, fuzz, coverage)
6. Documentation & Research
– README.md, docs/, research/price-manip-modeling
7. Data & Assets
– data/rewards: CSV incentives history
– packages/perps-exes/assets, static/, templates/
README for architecture clues
• Emphasis on multichain support, Dockerized contract builds, local Osmosis testnet, TypeScript & Rust/WASM SDKs
• Deployment flows via the perps-deploy CLI
• Testing flows (off-chain, on-chain, prop tests, fuzz)
Main components (to appear
A. On-chain layer
1. Cosmos chains (Local Osmosis, Testnet, Mainnet)
2. CosmWasm VM – hosts multiple smart contract modules from contracts/
B. Off-chain orchestration & deployment
1. perps-deploy CLI (Rust) – stores code, instantiates/migrates contracts
2. perps-bots CLI – operational bot suite (cranking, liquidity checks, alerts, etc.)
3. perps-companion – companion service with HTTP API and Postgres DB migrations
4. perps-market-params – service fetching market data (Coingecko, S3, Slack) and pushing updates
5. perps-qa – automated QA suite
6. perps-bridge – bridging messages or assets
C. SDK & API layer
1. Rust/WASM SDK (perpswap/…) exposing contract calls
2. TypeScript SDK and schema generator (ts-schema/…) for front-ends and devs
D. Testing & Continuous Integration
1. multi_test harness simulating chain & contract interactions in Rust
2. fuzz targets ensuring core logic correctness
3. GitHub Actions / CI scripts executing build, test, coverage, and deployment
E. Data & UI Assets
1. Static site assets & templates used by perps-companion and market-params front ends
2. Historical rewards data
Relationships & data flows
• Developer → runs Just recipes or CI pipelines → builds WASM contracts (Docker/Cargo) → pushed to chain via perps-deploy
• perps-deploy communicates via Cosmos RPC to the chain → stores code IDs & instantiates contracts
• perps-bots & companion services poll chain state via RPC/SDK → perform cranks, compute PnL, trigger migrations
• TypeScript & Rust/WASM SDKs call smart contracts on chain → used by front-ends or other services
• multi_test harness uses Rust SDK to instantiate in-memory chains, run scenarios, report results
• CI pipelines orchestrate lint, test, build, publish crates, push containers, and deploy CLI tools
Architectural patterns & principles
• Modular CosmWasm contract packages (each contract is a component)
• CLI-based microservices pattern (each Rust binary is a separate microservice)
• Shared SDK crates for code reuse (perpswap, CosmJS wrappers)
• Infrastructure as code: Docker, Just, shell scripts, GitHub workflows
• Multi-chain abstraction via config files and chain-specific assets/*.toml
• Testing isolation: fuzz tests, proptests, multi_test scenarios
Summary checklist
[ ] All on-chain contracts grouped in CosmWasm VM
[ ] SDK layer clearly separated, showing Rust/WASM vs. TS
[ ] Testing harnesses and CI pipelines represented
[ ] External dependencies and data stores drawn