Perp DEX Copy Trading

Copy trading infrastructure on top of leading perpetual DEXs (GMX, dYdX, Kwenta, Gains, Level, Vela, and more). This repository contains the smart contracts, scripts, tests, and a reference React frontend for deploying and operating copy-trading vaults.

Presentation: https://docs.google.com/presentation/d/1nvyCgkO7xOycq6s9iDtnpJw7GfwbzX_gYYkFvo4vNpw/edit?usp=sharing

---

Repository Structure

• contracts/: Solidity contracts (vault factory, proxy, implementations, interfaces)
• scripts/: Operational scripts for deployment and admin actions
• test/: Hardhat tests and mock contracts
• src/: Node-side helpers (config, contract addresses)
• perp-react/: Reference React client

---

Prerequisites

• Node.js 18+ and npm
• Git
• An RPC URL for Arbitrum (ARBITRUM_RPC_URL)
• Optional: Foundry (for anvil) if you prefer forking with Foundry

---

Quick Start

1. Install dependencies (root and frontend):

npm install
cd perp-react && npm install && cd ..

2. Create your environment file:

cp .env.example .env

Populate at minimum:

ARBITRUM_RPC_URL=YOUR_ARBITRUM_RPC_URL
PRIVATE_KEY=YOUR_LOCAL_DEPLOYER_PRIVATE_KEY

3. Start a local Arbitrum fork (choose one):

Hardhat

npx hardhat node --fork https://rpc.ankr.com/arbitrum

Foundry (anvil)

anvil --fork-url https://rpc.ankr.com/arbitrum

For additional details and known fork accounts, see forkArbitrum.md.

4. Compile contracts:

npx hardhat compile

5. Run tests:

npx hardhat test

---

Deployments and Scripts

With a local node running (see step 3), you can deploy and manage vaults via scripts:

• Deploy VaultFactory:

npx hardhat run scripts/Gov/deployVaultFactory.js --network localhost

• Set factory parameters:

npx hardhat run scripts/Gov/setVaultFactoryParams.js --network localhost

• Withdraw factory funds (governance):

npx hardhat run scripts/Gov/withdrawFactory.js --network localhost

• Create a user vault:

npx hardhat run scripts/User/createVault.js --network localhost

• Delete a user vault:

npx hardhat run scripts/User/deleteVault.js --network localhost

• Owner actions on a vault:

npx hardhat run scripts/User/ownerActions.js --network localhost

Networks: replace --network localhost with your configured network in hardhat.config.js (e.g. arbitrum), ensuring the relevant RPC URL and keys are set in .env.

---

Contracts Overview

• contracts/VaultFactory.sol: Factory and registry for deploying and managing vault proxies
• contracts/VaultProxy.sol: Upgradeable proxy used by each vault instance
• contracts/VaultImplementationV1.sol: First implementation of the vault logic
• contracts/Interfaces/IVaultFactory.sol: Public interface for the factory

The system uses OpenZeppelin libraries and an upgradeable pattern to enable safe upgrades of vault logic while preserving state.

---

Frontend (Reference)

The perp-react/ app is a reference client for interacting with deployed vaults.

cd perp-react
npm start

By default it targets local development; adjust environment variables and contract addresses in perp-react as needed.

---

Configuration

• Root runtime configuration: src/config.js, src/contracts.js
• Built assets for distribution: dist/config.js

Update addresses and constants there after deployments.

---

Conventions

• Lint and test before committing
• Prefer small, focused scripts under scripts/ for operational flows
• Use environment variables for secrets; never commit private keys

---

Security Notice

This codebase is under active development. Smart contracts are high-risk software; use at your own risk. Thoroughly test and audit before deploying to mainnet. Keys used for local testing must never hold real funds.

---

Links

• Presentation: https://docs.google.com/presentation/d/1nvyCgkO7xOycq6s9iDtnpJw7GfwbzX_gYYkFvo4vNpw/edit?usp=sharing
• Architecture overview: PCT_Architecture.html

---

Contact

Platform	Link
📱 Telegram	t.me/novustch
📲 WhatsApp	wa.me/14105015750
💬 Discord	discordapp.com/users/985432160498491473

Feel free to reach out for implementation assistance or integration support.