SwapGuard

Problem, context, and constraints

A basic router call does not demonstrate the full DEX integration boundary: users still need protection from stale execution and unacceptable output, while ERC-20 allowances require deliberate limits.

External router and token behavior needs realistic integration evidence in addition to isolated mocks.

A public portfolio experience also needs to explain the transaction flow without requiring real funds or pretending to submit a live swap.

My role and contribution

Smart Contract & Frontend Engineer

• Designed and implemented the SwapGuard integration contract around an immutable Uniswap V2-compatible router.
• Added strict router, path, amount, recipient, deadline, slippage, and router-response validation with custom errors.
• Implemented quotations, minimum-output calculation, exact-input swaps, SafeERC20 transfers, and exact temporary router allowances.
• Sent swap output directly from the router to the recipient and checked that the contract retained no input balance after success.
• Built behavioral token and router mocks, 25 unit tests including two 256-case fuzz tests, and a pinned Arbitrum fork suite against deployed contracts.
• Built local Anvil deployment, funding, and swap workflows for reproducible real-protocol execution.
• Built the React, wagmi, and viem interface with bigint-safe arithmetic and explicit wallet, allowance, quote, receipt, and balance states.
• Added CI, architecture and security documentation, and a portfolio-safe Vercel mode that performs no RPC calls, wallet signatures, approvals, or transactions.

Architecture and system details

The execution path is Wallet / React client → SwapGuard → Uniswap V2-compatible router → liquidity pools → recipient. The client handles bigint-safe input and transaction states; SwapGuard validates parameters, pulls the exact input, grants the router an exact temporary allowance, and sends output directly to the recipient. Unit tests use behavioral mocks, the pinned Arbitrum suite exercises deployed bytecode and historical state, local Anvil mode performs the real fork-based flow, and public portfolio mode demonstrates the UX without fake transactions.

Key technical decisions

Security, scaling, and reliability

• The constructor rejects a zero router or an address without deployed code, then stores the router immutably; there is no owner, upgradeability, or protocol fee.
• Paths require at least two nonzero token addresses, no consecutive duplicates, and different input and output endpoints.
• Swaps reject expired deadlines, zero input, zero minimum output, and a zero recipient.
• Minimum output uses basis-point arithmetic with application slippage capped at 1,000 bps (10%).
• SafeERC20 and forceApprove support exact temporary router allowances, which are cleared after successful execution.
• Reentrancy protection, router-response validation, balance invariants, and atomic rollback cover common failure paths.
• Output is delivered directly to the recipient so the integration contract does not intentionally custody it.
• A router quote is not an oracle; router trust, MEV, front-running, sandwich exposure, and standard-token limitations remain explicit boundaries.
• SwapGuard is an unaudited educational portfolio project and is not presented as production-ready or fully secure.

Testing strategy

• The current Foundry unit suite contains 25 passing tests, including two fuzz tests run with 256 cases each, covering validation, quotes, direct and multi-hop behavior, allowance cleanup, events, rollback, and balance invariants.
• The current Vitest frontend suite contains 21 passing tests for configuration modes, bigint parsing and formatting, slippage, deadlines, routes, deterministic previews, explorer links, and quote invalidation.
• Contract formatting and compilation, frontend lint, tests, and production build are enforced by GitHub Actions.
• Five pinned Arbitrum fork tests are implemented against block 250000000; they require an archive-capable RPC and are reported as implemented unless executed in the current environment.

Result and proof

• The public repository provides the full contract, mocks, unit and fuzz suite, pinned fork suite, local Anvil workflow, CI, and architecture and security documentation.
• The public Vercel site provides an interactive portfolio preview that requires no wallet or real funds and never pretends to submit a transaction.
• The project demonstrates the full DEX integration boundary: allowances, quotations, execution guarantees, failure handling, wallet states, and reproducible testing against a real protocol.

Challenges, tradeoffs, and next steps

Hardest part: Aligning safe contract integration with external router behavior, real token decimals and allowances, reproducible fork testing, and an honest public demonstration that never fakes on-chain execution.

Key learning: Router quotes and execution are separate concerns: slippage, deadlines, allowance scope, router trust, fork evidence, wallet states, and configuration validation all need explicit treatment at their respective boundaries.

• Add EIP-2612 or Permit2 approvals.
• Support Uniswap V3 or DEX aggregation.
• Add oracle validation and price-impact calculation.
• Add native ETH and explicit fee-on-transfer support.
• Explore private transaction submission for stronger MEV protection.
• Add a verified public testnet flow only when the router, tokens, liquidity, faucet, RPC, deployment, and end-to-end transaction can all be proven.