Architecture

Rugdrome is organized into several protocol layers. Each layer has a clear responsibility and interacts with the others through well-defined interfaces.

High-Level Layers

Layer	Contracts	Purpose
Token	RUGD (Rugd.sol)	ERC-20 RUGD token, minted by the Minter.
veNFT	VotingEscrow, VeArtProxy	Locks RUGD and mints veNFTs that represent voting power and fee share.
Rewards	RewardsDistributor, Minter	Distributes emissions and protocol fees.
Governance	RugdGovernor (RugdGovernor.sol), RugdTimelockController (RugdTimelockController.sol)	On-chain proposal and execution pipeline.
Factories	PairFactory, GaugeFactory, BribeFactory, CLFactory, CLGaugeFactory	Deploy and register pools, gauges, and bribes.
Registry	FactoryRegistry	Whitelist of approved factories used by the Voter.
AMM	Pair, Router, CLPool, CLPositionManager, CLGauge	Swap, provide liquidity, and collect fees.
Meta-tx	ProtocolForwarder	ERC-2771 trusted forwarder for gasless transactions.

User Flows

Swapping

1. The user approves the token to the Router.
2. The Router routes the swap through one or more Pair or CLPool contracts.
3. Trading fees accrue to the pool and are later distributed to LPs or voters.

Providing Liquidity

1. The user approves tokens and calls Router.addLiquidity() or ZapHelper.zapIn().
2. The Pair or CLPool mints LP or position NFTs.
3. LPs can stake their position in a Gauge to earn RUGD emissions.

Voting and Emissions

1. Users lock RUGD in VotingEscrow to receive a veNFT.
2. veNFT holders vote for gauges through Voter.
3. Voter records vote weights and the Minter mints weekly emissions proportional to gauge weights.
4. Gauges distribute emissions to LPs; voters earn bribes and fees.

Governance

1. Token holders or delegates create proposals via RugdGovernor (RugdGovernor.sol).
2. After the voting delay and period, successful proposals are queued in RugdTimelockController (RugdTimelockController.sol).
3. After the timelock delay, the proposal can be executed.

Frontend Architecture

The frontend is a Next.js 13 application using the App Router:

• app/ — Page routes and layouts with SEO metadata.
• components/ — Shared React components and UI primitives.
• hooks/ — Custom React hooks for blockchain interactions.
• lib/ — Utilities, configuration, and contract ABIs.
• store/ — Zustand global state stores.
• types/ — TypeScript type definitions.

Repository Layout

.
├── contracts/       # Solidity smart contracts
├── frontend/        # Next.js frontend
├── scripts/         # Hardhat/Foundry deployment and operations scripts
├── test/            # Hardhat and Foundry tests
├── audits/          # Security audit reports
├── docs/            # This documentation site
└── lib/             # Git submodule dependencies (forge-std)

Known Simplifications

• The CL implementation uses a single-position-swap model with no cross-tick swaps. It is suitable for single-position pools and small swaps but is not a full Uniswap V3 port.
• CLGauge.claimFees is a stub; CL fee collection is handled through the position manager.
• The anti-dilution rebase is implemented as a pro-rata locked-amount rebase rather than a global checkpoint multiplier.