LiquidityPilot

Problem, context, and constraints

Liquidity management is substantially more complex than making a router call: users need defensible minimum outputs and deadlines, while ERC-20 and LP-token allowances must be intentionally scoped.

Liquidity removal only works when the integration contract actually owns the LP tokens it asks the router to spend; an approval alone does not move user-held LP tokens into contract custody.

One-sided entry and single-token exit introduce intermediate assets, multiple router boundaries, and remainder accounting that must be reconciled without sweeping unrelated balances.

Frontend previews must separate illustrative demo values from live balances, pair composition, reserves, allowances, LP ownership, and quotes.

My role and contribution

Smart Contract & Frontend Engineer

• Designed an immutable router-and-factory-based Solidity coordination contract with no owner, fee collector, proxy, or privileged withdrawal surface.
• Added configurable exact-input swaps, including multi-hop paths.
• Added one-sided direct-pair entry with a single input transfer.
• Minted LP tokens directly to the selected recipient.
• Tracked and refunded unused operation-specific token deltas.
• Implemented correct LP-token custody before liquidity removal.
• Added standard two-token removal and single-token exit.
• Used SafeERC20, exact forceApprove values, post-operation allowance clearing, custom errors, and reentrancy protection.
• Added deterministic unit tests and fuzz properties for accounting and minimum-output boundaries.
• Added optional Arbitrum fork tests covering deployed router and factory bytecode, pair composition, quotes, swaps, liquidity entry, and removal.
• Built a Next.js frontend with React, wagmi, and viem.
• Added wallet and network guards, factory pair discovery, pair-composition validation, live balances, allowances, reserves, LP ownership, and debounced quotes.
• Implemented simulation-first execution, mined-receipt handling, query refreshes, and explicit transaction stages.
• Added separate contract and frontend GitHub Actions workflows.
• Documented architecture, security, learning, deployment, and reproducibility workflows.

Architecture and system details

A wallet connects to a typed Next.js console that validates the configured network, discovers the pair through the factory, and reads live balances, allowances, reserves, LP ownership, and quotes. LiquidityPilot coordinates exact-input swaps, one-sided entry, standard removal, and single-token exit across immutable V2 router and factory boundaries. Operation-delta accounting settles only assets created by the current call, while deterministic mocks, optional Arbitrum fork validation, local Anvil workflows, CI, and an explicit Vercel Demo mode cover delivery and review.

Key technical decisions

Security, scaling, and reliability

• SafeERC20 and USDT-compatible forceApprove handle token transfers and exact router-facing allowances.
• Every state-changing public flow uses reentrancy protection and validates addresses, amounts, paths, pairs, recipients, and deadlines before custody.
• Router and factory addresses are immutable, and the contract has no owner, upgradeability, protocol fee, or privileged withdrawal path.
• Factory pair discovery and token-composition checks make the LP boundary explicit.
• LP tokens are pulled into LiquidityPilot before the router receives an exact removal allowance.
• Operation-delta accounting avoids sweeping unrelated balances during refunds.
• The public frontend rejects incomplete or cross-network configuration and cannot submit transactions in Demo mode.
• LiquidityPilot is unaudited educational software, not a security guarantee or production-ready deployment.

Testing strategy

• Deterministic Foundry unit tests exercise the contract flows with original token, pair, factory, and router mocks.
• Fuzz properties cover input and refund accounting plus exact minimum-output boundaries.
• Frontend tests cover configuration, live state, allowance planning, pair validation, simulation failures, receipt handling, and bigint arithmetic.
• Optional Arbitrum fork integration validates deployed router and factory code, pair composition, quotations, swaps, liquidity entry, and removal when an archive-capable RPC is provided.
• Separate contract and frontend CI workflows define formatting, compilation, linting, type checks, tests, coverage reporting, and production builds as appropriate.

Result and proof

• The public GitHub repository contains the contracts, frontend, deterministic mocks, optional fork suite, deployment scripts, and delivery workflows.
• Architecture, security, learning, deployment, and reproducibility documentation make the trust boundaries and local or fork workflows reviewable.
• The public Vercel site provides an honest Demo mode with labelled illustrative values and no transaction submission without valid deployment configuration.
• Reproducible commands cover contract and frontend checks without claiming an audit, production usage, or an Arbitrum mainnet LiquidityPilot deployment.

Challenges, tradeoffs, and next steps

Hardest part: Correctly modelling the complete LP-token lifecycle and intermediate-asset accounting across swaps, liquidity addition, removal, refunds, approvals, and frontend previews.

Key learning: A router call is only one part of the integration. Token ownership, allowance scope, pair discovery, LP custody, price protection, intermediate balances, refunds, simulation, receipt handling, network validation, and honest public configuration must all be designed explicitly.

• Implement reserve-aware optimal zap sizing.
• Add Permit2 support.
• Support a wider token and pool registry.
• Broaden route support.
• Obtain an independent security review before any real-funds recommendation.
• Use audited deployment configuration only if the full environment can be verified.