Aggregator Integrations

A DEX aggregator can treat Raphael as one or more liquidity sources on Robinhood Chain. A production integration must discover every supported Raphael pool class, quote against current onchain state and execute through the matching verified router.

Raphael does not provide a single static price feed. A quote is a simulation of an executable route at a particular block.

Integration surface

Load addresses and ABIs from Raphael's versioned deployment registry. Do not reuse addresses, route constants or factory identifiers from upstream ve(3,3) deployments.

Surface	Purpose
Factories and registries	Discover supported pools and validate that a pool belongs to Raphael
Basic-pool quoter or router views	Quote stable and volatile pool segments
Concentrated-liquidity quoter	Quote tick-based pool segments, where deployed
Routers	Execute basic, concentrated or mixed routes
Wrapped native token	Represent native ETH consistently inside routes
Event index	Track pool creation, liquidity changes and swaps

A route edge should retain more than the two token addresses. At minimum, store the pool address, factory, pool class, fee or tick spacing, token direction and compatible quoter/router version.

Pool discovery

1. Start from the verified Raphael factory and registry addresses.
2. Index pool-creation events from each supported factory's deployment block.
3. Validate discovered pools against the originating factory before exposing them.
4. Read token addresses, decimals, fee configuration and pool state from verified contracts.
5. Support parallel pools for the same pair. A pair may have stable, volatile and several concentrated-liquidity markets.
6. Reconcile the index periodically with direct factory reads and handle chain reorganisations.

Token symbols, names and logos are presentation metadata, not identifiers. Key every asset by chain ID and token address.

Quoting

For an exact-input request:

1. enumerate direct and bounded multi-hop candidates;
2. call the compatible quoter for the complete candidate route;
3. reject reverted, zero-output or stale results;
4. estimate execution gas;
5. compare net output after swap fees, aggregator fees and estimated gas cost;
6. return the best supported route with its block number and expiry.

The executable minimum output for slippage tolerance s in basis points is:

$a_{min}=\left\lfloor a_{quote}\frac{10{,}000-s}{10{,}000}\right\rfloor$

For an exact-output request, cap the permitted input:

$a_{max}=\left\lceil a_{quote}\frac{10{,}000+s}{10{,}000}\right\rceil$

Apply these limits to integer base units after the route is quoted. Never use token display values for contract arithmetic.

A quote is not a reservation

Refresh a quote when its block age or time-to-live exceeds your policy, and simulate the exact calldata immediately before submission.

Route construction

Keep logical trade direction separate from a pool's internal token0 and token1 order. For mixed routes, every segment must specify enough information to choose the correct Raphael router path and decode the result.

Do not assume that:

• stable and volatile pools share the same encoding as concentrated pools;
• route-type flags match an upstream deployment;
• every token supports permit signatures;
• a fee-on-transfer or rebasing token is safe to route through;
• a direct pool call is equivalent to router execution.

Prefer the verified Raphael router unless your integration has explicitly implemented and tested the pool's lower-level swap callback and payment rules.

Execution

Before returning executable calldata:

• verify the requested Robinhood Chain ID;
• verify every pool and router against the current allowlist;
• use exact token addresses and integer amounts;
• set amountOutMin or amountInMax from the user's slippage setting;
• set a short, explicit deadline;
• minimise approvals and make the final spender visible;
• simulate from the user's address with the same value and calldata;
• account for an aggregator fee without silently weakening the user's limit.

After submission, parse the confirmed receipt rather than reporting the quote as the result. Record the actual input, output, route, gas used and transaction status.

Native ETH

Model native ETH and wrapped ETH as distinct assets in the route graph. Wrap or unwrap only at an explicitly supported boundary, and ensure the calldata value equals the native amount required by the router. Never infer native-token behaviour from the zero address without checking the deployed interface.

Data freshness and failure handling

A resilient integration should:

• tag quotes with their source block;
• reject indexer data that is materially behind the RPC head;
• retry read failures with bounded backoff, but not blindly resubmit transactions;
• handle replaced, dropped and reverted transactions;
• invalidate pools or routers removed from Raphael's supported deployment registry;
• surface partial outages rather than returning fabricated or cached executable quotes.

Integration acceptance tests

Test at least:

• stable, volatile and concentrated pools supported by the deployment;
• token direction in both orders;
• direct and multi-hop swaps;
• exact-input and exact-output modes, if exposed;
• native wrapping and unwrapping;
• low-liquidity and zero-liquidity paths;
• stale quotes and adverse price movement;
• insufficient balance, allowance and gas;
• non-standard tokens your policy permits;
• RPC failure, reorganisation and indexer lag;
• receipt parsing against actual router events and balance changes.

Before enabling mainnet routing, pin the deployment manifest, ABIs and test vectors used by the integration. Re-run the suite whenever Raphael adds a factory, router or pool implementation.