feat(smoke): v4 stable-pool seeding script + guide for Arc

[david-uniswap]

What

Tooling for partners (Arc / LI.FI) to create and fund a Uniswap v4 stable pair (e.g. USDC/EURC) on a new chain without a UI. Motivated by Arc needing a single non-trivial pool to test same-chain swaps against.

Files

• script/smoke/SeedStablePoolV4.s.sol — the seeding script. USD-native interface: the operator only provides token addresses, USD prices, and a USD budget per side. The script derives the sqrtPrice, full-range ticks, token amounts, and liquidity (no ticks or Q64.96 values exposed). Supports staged funding: the first run initializes the pool at the USD-derived price; later runs detect the pool is initialized and top up at the pool's live price without re-pricing it. v4 encoding (MINT_POSITION + SETTLE_PAIR, modifyLiquidities) mirrors the Arc-proven V4SmokeNativeIsERC20.s.sol byte-for-byte. Uses type(uint128).max mint caps and an equal-decimals guard.
• script/smoke/SEED_POOL_GUIDE.md — operator guide: verify tokens, dry-run, broadcast small, quote-test, top up. Includes Arc (5042) addresses and gas notes.
• script/smoke/LocalV4Deploy.s.sol — local test harness that stands up the full v4 stack + two fake stablecoins from precompiled bytecode, so the seed script can be exercised end-to-end on anvil.

Why a USD-native + staged design

A v4 pool's price floats with swaps, but the starting price is set once at initialization and can't be reset. Initializing at a wrong price gets the pool arbitraged, and the loss scales with posted liquidity. So the script is built to seed a small amount first (cheap to get wrong), confirm routing, then top up at the established price.

Validation

Ran locally on anvil with fake ABC ($1.00) / BBC ($0.95) stablecoins:

• Create + small seed ($2/side): pool initialized at the correct USD-derived price (tick -513 = log(0.95)/log(1.0001)), liquidity 0 → ~2M.
• Top up ($1000/side): detected already-initialized, added at the unchanged live price, liquidity ~2M → ~1.028B.
• Quote: 1 BBC → 0.9486 ABC, matching 0.95 minus the 0.05% fee. Pool is routable.

Notes for reviewers

forge script does a full-project build, which hits the repo's cross-package solc-version conflict (permit2 0.8.17 vs v4 0.8.26). Run these scripts with --skip 'src/pkgs/**' --skip 'test/**'; both compile standalone, and LocalV4Deploy deploys protocol contracts from precompiled out/ bytecode via vm.getCode to avoid pulling that source into its compile unit. The guide could alternatively live in Notion if we'd rather not keep partner-onboarding docs in the contracts repo.

🤖 Generated with Claude Code