ALFQuote

Demo

About

ALFQuote is a hook-aware integration toolkit for discovering, assessing, quoting, and safely simulating swaps through Uniswap v4 DualPool hooks on Ethereum. DualPool hooks can keep assets in external ERC-4626 vaults and return liquidity to Uniswap only when a swap occurs. As a result, the standard PoolManager liquidity value can be zero even when the hook has usable capacity and can provide a quote. Integrators that inspect only vanilla PoolManager liquidity can incorrectly reject these pools. ALFQuote provides a reusable TypeScript library and an alfquote command-line interface with four commands: discover enumerates factory deployments or reconstructs a hook’s pools from onchain Initialize events. assess reports compatibility, provenance, routing requirements, and upgradeability as four independent, evidence-backed fields. It never compresses them into a misleading “safe” verdict. quote checks hook and pool liveness, applies the hook’s advertised gas bound, reads vanilla liquidity, reserves, and effective liquidity separately, and produces a hook-aware indicative quote. swap builds protected Universal Router v2 calldata and performs a read-only simulation. It reports slippage protection, gas, decoded reverts, balances, ERC-20 allowances, Permit2 allowances, and all execution blockers. It never signs or broadcasts a transaction. Every command supports readable terminal output and a stable JSON envelope for coding agents. Results include schema version, chain and block context, input data, warnings, status, and structured output or errors. Zero quotes, unavailable evidence, failed liveness, and identity mismatches fail closed rather than becoming usable prices. The project includes live Ethereum mainnet verification, a successful protected swap on a controlled Tenderly mainnet fork, reproducible evidence, 235 automated tests, package-boundary checks, and no-send safety gates.

How it's made

ALFQuote is an npm workspace written in TypeScript. It contains a reusable alfquote library, a Commander-based CLI, separate read-only verification scripts, and isolated Tenderly fork-evidence tooling. The onchain integration uses viem for Ethereum RPC reads, ABI encoding and decoding, event parsing, storage access, calldata construction, and transaction simulation. The discovery service reads the official DualPool factory registry at an explicit block. For each deployment, it verifies provenance in both directions: the factory must recognize the hook, and the hook must report the expected factory. Pool discovery scans PoolManager Initialize logs, filters by the exact event signature, reconstructs every PoolKey field, and derives the PoolId to check it against the event. Explicit fixtures remain clearly labeled and never inherit a factory claim. Assessment is deliberately conservative. ERC-165 support and required IALFHook views establish compatibility. Provenance, routing policy, and upgradeability remain independent. Proxy detection checks EIP-1967 implementation, beacon, and admin storage slots, plus EIP-1167 minimal-proxy bytecode. Failed or incomplete reads produce unknown or unverified, never a favorable guess. The quote service checks isLive() and livePools(poolId) before quoting. It reads maxGas() and uses that value as the quote call’s gas bound. It then reports three different liquidity signals: Vanilla PoolManager liquidity Total DualPool reserves Effective liquidity currently usable for swaps The mainnet proof showed why this distinction matters: the selected PoolManager position reported zero vanilla liquidity while the DualPool hook had positive effective liquidity and returned a non-zero quote. Protected swaps are encoded for Universal Router v2 using V4_SWAP, SWAP_EXACT_IN_SINGLE, SETTLE_ALL, and TAKE_ALL. The release path always uses empty DualPool hookData. amountOutMinimum is calculated from the quote and an explicit slippage value. Simulation checks the sender’s token balance, ERC-20 approval to Permit2, Permit2 approval to Universal Router, and Permit2 expiration. Reverts are decoded and classified conservatively. The public library contains no wallet client, private key, signer, approval transaction, or broadcast function. Tenderly was used as a controlled mainnet-fork environment because a read-only mainnet address did not have the balances and Permit2 approvals needed to prove successful execution. A fresh evidence run funded an isolated test address, submitted normal approval transactions, and executed a protected 1 USDC swap. The quote, minimum output, actual output, gas, balance changes, and hook events were reconciled. Mainnet remained read-only, and the successful fork simulation remains the primary execution proof. The CLI uses Commander 15 and exposes injectable arguments, environment variables, and output sinks so command behavior can be tested without spawning processes. Human and JSON output come from the same structured result. Big integers are serialized as decimal strings, RPC credentials are redacted, and long calldata is preserved without truncation. Exit codes distinguish success, typed skips, invalid input, unavailable evidence, swap blockers, configuration problems, and internal failures. The repository uses Vitest for unit and integration coverage. CI performs a clean install, type-check, build, 235 tests, package-boundary checks, and no-send scans. An offline end-to-end test drives all four commands through one mocked transport. An opt-in integration script verifies the complete journey against live Ethereum mainnet.