Routes Engine

The Routes Engine is the programmable heart of Reveel PayID. It determines how incoming payments should be processed, routed, and settled, based on user-defined rules. This engine is what allows Reveel to go beyond simple address redirection and support intelligent, omnichain payment behavior.

---

What is a Route?

A route is a logical set of conditions and outcomes configured by the user (or application) that defines:

• What payment types are accepted (by network, token, sender wallet)

• Where those payments should end up (target chain, token, wallet)

• Whether a swap or bridge is needed (optional, configurable)

Each user can define multiple routes, allowing fine-grained control over how different types of incoming payments are handled.

---

Why It Matters

Without routing, a PayID would just be a static alias for a wallet. With the Routes Engine, Reveel unlocks:

• Network abstraction: sender doesn’t need to know recipient’s chain

• Token normalization: receive USDC even if sender sends USDT

• Smart fallback logic: default wallets for unknown senders or tokens

• Enterprise-style flexibility: tailor rules by partner, product, use case

It brings Web2-style conditional logic into the programmable payment space.

---

Routing Rules: How They Work

Each route contains match conditions and output instructions.

Match Conditions (Inputs)

These define when a route should activate:

• incomingToken: Which tokens should trigger this route

• incomingNetwork: Which chains the payment may come from

• incomingWallets: (Optional) Which sender wallets this route applies to

Output Instructions

These define what to do with the matched funds:

• swapToken: Which token the user prefers to receive (optional)

• swapNetwork: Which chain to settle the funds on (optional)

• outgoingWallet: Final destination wallet

---

Deterministic vs. Flexible Logic

Reveel allows routes to be either:

• Strictly deterministic: routes trigger only when all match conditions are met

• Fallback-friendly: if no exact match, default route can apply

This makes the system powerful enough for:

• Basic personal use (receive USDC on Base always)

• Complex app flows (route payments from App A to Chain A, App B to Chain B)

---

Multi-Route Architecture

Users can have multiple active routes, and the engine evaluates them in order of specificity and priority. This allows:

• Granular override: route payments from a specific sender differently

• General rules: apply a catch-all fallback route for everything else

Each route is stateless, meaning the logic is evaluated per transaction, not stored across sessions.

---

Design Considerations

The Routes Engine is designed to be:

Feature	Benefit
Stateless evaluation	Easier caching, fewer bugs, no cross-transaction memory
Conflict-checked	Users can’t create overlapping or ambiguous routes
Composable	Works with future liquidity and swap modules
Chain-agnostic	Built to support new EVM chains and token standards
User-scoped	Routes are isolated per user to prevent collisions

---

Future Plans:

• Time-based logic (route payments differently on weekdays vs weekends)

• Geofenced rules (based on sender location metadata)

• Token splitting (e.g. split $100: $80 to wallet A, $20 to wallet B)