How syv-labs/surge-periphery works
Project type and purpose
• This is a periphery-layer smart-contract repository for the “Surge” automated-market-maker (AMM) protocol.
• It provides user-facing contracts (routers, position manager, quoter, NFT descriptor, etc.) and utility libraries for interacting with the core Surge pools.
File structure
• Top level:
• contracts/ – on-chain Solidity code subdivided into:
– base, examples, interfaces, libraries, lens
• hardhat.config.ts, package.json, tsconfig.json – Hardhat + TypeScript config
• test/ – TypeScript tests and shared fixtures
• contracts/libraries/ – reusable path-encoding, tick math, price math, safe transfer
• contracts/lens/ – off-chain “view” contracts for swap/tick data (not to be deployed on-chain)
• contracts/interfaces/ – interfaces for core protocol and external tokens
• contracts/examples/ – demo flash-swap, etc.
• tests/ – comprehensive spec files and JSON snapshots
README for additional insights
• Key on-chain components: SwapRouter, NonfungiblePositionManager, Quoter/V2, NFT descriptor, TickLens, PairFlash
• Off-chain tools: lens contracts, Hardhat+Waffle tests
• Design: stateless routers, ERC721-based position manager, off-chain quoter views, OZ upgradeable patterns
a. Main components
• User/Frontend (web UI or scripts)
• On-chain Periphery Contracts
– SwapRouter
– NonfungiblePositionManager (ERC721 positions)
– Quoter & QuoterV2 (view only)
– TickLens (view only)
– NonfungibleTokenPositionDescriptor (SVG/metadata)
– PairFlash example
• Core Surge Protocol Contracts (external to this repo)
– Factory, Pool, Factory hooks
• Utility Libraries (deployed as libraries or linked via Solidity)
• Off-chain Test & Simulation Layer
– Hardhat test harness, shared TS fixtures
b. Relationships and interactions
• Frontend → SwapRouter (on-chain swap calls) → Core Pools
• Frontend → PositionManager → Core Pools + ERC20 approvals + WETH9 wrapper
• Frontend/SDK → Quoter/TickLens (static calls via JSON-RPC) → Core Pools
• PositionManager → NonfungibleTokenPositionDescriptor (on-chain metadata generation)
• All periphery contracts → Library code (linked at compile time)
• Test harness → Deploy Periphery + Core mocks → run tests/specs
c. Architectural patterns & design principles
• Modular “periphery” separation from core protocol
• Stateless router pattern (no storage)
• ERC721 for NFT liquidity positions
• Off-chain “lens” contracts for gas-free data fetching
• Use of SafeMath/tick-math libraries & OZ upgradeable proxies
d. Relevant technologies & frameworks
• Solidity 0.7.6, Hardhat, Waffle, TypeScript tests
• Yarn, Prettier, snapshot testing
• OpenZeppelin upgradeable libraries
• Ethers.js (via Hardhat) for tests