TurboSwap — Automated Market Maker (Anchor / SVM)

Overview

This repository contains a Solana-style AMM written with Anchor (Rust) plus a TypeScript client. It targets the Eclipse Network (Solana Virtual Machine L2 on Ethereum) and implements a concentrated liquidity / swap program (programs/cp-swap) with a matching client under client/.

This README is written for senior engineers: it documents architecture, core accounts/instructions, build/test/deploy steps, integration notes for SVM, security considerations, and recommended next steps.

---

High-level architecture

• On-chain program (Rust / Anchor)

  • Located in programs/cp-swap.
  • Anchor program exposing instructions for pool creation, liquidity management (add/remove), and swaps.

• Client (TypeScript)

  • client/ contains scripts to bootstrap pools and interact with the program from off-chain.

• Testing

  • tests/ contains Rust/Anchor integration tests that exercise program logic.

(Repository structure inspected from the project root.)

---

Design & primitives

Key primitives

• Pool — on-chain account holding reserves, fee parameters, and metadata.
• Liquidity position / Tick / Concentrated liquidity model — the program appears to support more advanced liquidity abstractions (see cp-swap source for details).
• Swap instruction — atomic swap using the pool's pricing curve and fee logic.

Design goals (inferred)

• Compatibility with SVM (Eclipse) so developers can reuse Solana tooling (Anchor, solana-cli) while targeting an Ethereum L2.
• Familiar Anchor account model and CPI-friendly entrypoints for composability.

---

Core accounts & instructions (developer summary)

Inspect programs/cp-swap/src/lib.rs and module files for definitive types and account constraints. The descriptions below are intentionally high-level and typical for an Anchor based AMM.

• Accounts

  • PoolState — stores reserves, LP token mint(s), fee config, owner/authority.
  • Position — per-liquidity-provider position when concentrated liquidity is implemented.
  • User / Vault accounts — token vaults holding liquidity (token A/B reserves).

• Primary instructions

  • initialize_pool — create and initialize pool-state and vaults.
  • mint_liquidity / burn_liquidity — supply or remove liquidity; mints/burns LP tokens.
  • swap — perform token exchange using pool pricing; collects fees.
  • set_fee / set_admin — governance/admin controls.

---

Build & test (developer commands)

Prereqs: Rust toolchain, cargo, Anchor (v0.25+ recommended), Node.js & Yarn, solana-cli (or SVM-compatible CLI if using Eclipse local devnet).

1. Install Rust + Anchor

# Rust
curl https://sh.rustup.rs -sSf | sh
rustup update stable

# Anchor
cargo install --git https://github.com/coral-xyz/anchor --tag v0.25.0 anchor-cli --locked || cargo install --locked --force anchor-cli

2. Build the program

cd programs/cp-swap
anchor build

3. Run the test-suite

# from repository root
anchor test

Notes:

• If you target Eclipse SVM, you may need to run a local SVM node or use the network's devnet RPC and a compatible CLI. Anchor tests assume a Solana-style local validator; to run unchanged tests on SVM, adapt RPC and keypair targets.

---

Client usage (TypeScript)

1. Install dependencies

cd client
yarn install

2. Configure client_config.ini (RPC URL, wallet keypair path, program ID overrides)

3. Example: create a pool & add liquidity

yarn ts-node scripts/create_pool.ts --tokenA <mintA> --tokenB <mintB> --fee 30
yarn ts-node scripts/add_liquidity.ts --pool <poolPubkey> --amountA 1000 --amountB 500

Replace ts-node commands with your preferred runtime (build + node) if necessary.

---

Deployment notes (Eclipse / SVM specifics)

• Eclipse SVM aims to be compatible with Solana runtime semantics while running as an L2 — that reduces porting friction but requires attention to:

  • RPC endpoint differences (URL, chain id equivalents).
  • Fee model differences — gas accounting on SVM differs from Solana; test gas usage on target network.
  • Program IDs and accounts — ensure program IDs used when deploying match those referenced by the client (update Anchor.toml / deployed IDL).

• Recommended workflow

  1. Run Anchor build to generate IDL (target target/idl/*.json).
  2. Deploy program to local SVM or devnet via the network's deployment tooling. If SVM provides an anchor adapter, use it; otherwise deploy with the SVM-compatible loader and update Anchor.toml.
  3. Update client to reference deployed program ID and RPC.

---

Security & audits (important for senior devs)

• Arithmetic safety: use checked math for all fee and reserve calculations; avoid unchecked casts between integer sizes.
• Reentrancy: Although Solana's account model reduces reentrancy risk, ensure instruction ordering cannot be abused via CPI into other programs.
• Invariant checks: After swaps and liquidity ops assert pool invariants (e.g., non-negative reserves, LP accounting matches minted/burned tokens).
• Access control: admin-only instructions should validate authority and consider timelocks for governance changes.
• Fuzzing & property testing: add extensive fuzzing on swap invariants (Conzilla / proptest / arbitrary-based fuzzing) and cross-check outcomes against a reference Rust simulation.

Recommended immediate actions before production

1. Add unit/property tests to exercise corner cases (max slippage, tiny liquidity, fee rounding).
2. Run a formal audit or at least 3rd-party security review for financial primitives.
3. Integrate CI with cargo-audit and clippy enforcement, plus TypeScript eslint/tsc checks.

---

Gas/Cost optimization ideas

• Pack frequently-updated fields tightly in account structs to reduce rent and account size.
• Minimize CPI where possible — inline small helper logic rather than delegating to another program if it increases call-counts.
• Use explicit instruction batching in client to amortize overhead for multi-step operations.

---

Developer notes & TODOs

• Add comprehensive README examples showing raw transactions and decoded instruction data.
• Publish IDL to client/ and include a code example that hydrates Anchor Program object from IDL.
• Continuous integration: anchor build, anchor test, yarn lint, yarn test on PRs.
• Document expected Anchor / Solana / SVM versions and pin them in rust-toolchain.toml and package.json engines.

---

Contributing

1. Fork the repo
2. Create feature branch
3. Run linters and tests locally
4. Open PR with description, test plan, and security considerations

---

License

This project is Apache-2.0 licensed.

---

Contract Architecture Diagram

graph TD
    A[Client / Frontend] -->|Sends TX| B[Anchor Program: cp-swap]

    subgraph On-chain Program
        B --> C[PoolState Account]
        B --> D[Vault A Token Account]
        B --> E[Vault B Token Account]
        B --> F[Position Accounts]
    end

    C -->|Holds metadata, fees, reserves| D
    C --> E
    F -->|Represents LP concentrated liquidity| C

Loading

---

References

• Repository root and file tree inspected in this session.