Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/rhinestonewtf/warp-router/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The Router is the central entry point for all settlement operations in the Warp Router ecosystem. It orchestrates cross-chain settlement operations and protocol integrations through a flexible adapter architecture.
The Router contract is deployed at a deterministic storage layout position to ensure predictable deployment and integration patterns across chains.

​
Architecture

The Router system consists of three main components:

Router

Main entry point contract that inherits all functionality

RouterLogic

Core routing logic for fill and claim operations

RouterManager

Adapter lifecycle management with role-based access control

​
Router Contract

The Router contract serves as the primary entry point with a deterministic storage layout:
Router.sol
contract Router layout at 88_967_819_156_726_863_884_428_300_865_593_401_225_272_190_543_010_065_736_923_496_773_938_567_778_360
    is RouterLogic, RouterUtils
{
    constructor(address atomicFillSigner, address adder, address remover) 
        RouterLogic(atomicFillSigner, adder, remover) 
    { }
}
The custom storage layout position ensures that state variables occupy predictable storage slots across deployments, enabling advanced patterns like proxy-based upgrades.

​
RouterLogic

RouterLogic implements the core routing functionality for all settlement operations:
RouterLogic.sol
contract RouterLogic is IRouter, RouterManager, DirectRoutes, ReentrancyGuardTransient {
    constructor(address atomicFillSigner, address adder, address remover) 
        RouterManager(adder, remover) 
    {
        $atomicFillSigner = atomicFillSigner;
    }
}
Key Responsibilities:
  1. Operation Routing - Routes fill and claim operations to appropriate protocol adapters
  2. Atomic Execution - Ensures batched operations execute atomically or revert entirely
  3. Gas Optimization - Implements advanced caching and optimization techniques
  4. Security Enforcement - Validates signatures and prevents unauthorized operations
  5. Context Management - Manages solver-specific contexts for each operation

​
RouterManager

RouterManager handles the adapter lifecycle with semantic versioning:
RouterManager.sol
contract RouterManager is AccessControl, IRouterManager {
    bytes32 internal constant ADD_ROLE = bytes32(uint256(0x1001));
    bytes32 internal constant RM_ROLE = bytes32(uint256(0x1002));
    address public $atomicFillSigner;
}
Management Functions: 
function installFillAdapter(
    bytes2 protocolVersion,
    bytes4 selector,
    address adapter
) external onlyRole(ADD_ROLE)
Install new adapters for fill operations with version validation.

​
Atomic Fill Security

The Router uses an atomic fill signer to authorize batch operations:
RouterLogic.sol
function _isAtomic(bytes32 hash, bytes calldata atomicSig) 
    internal virtual returns (bool atomic) 
{
    address signer = $atomicFillSigner;
    require(signer != address(0), IRouter.AtomicSignerNotSet());
    atomic = (signer == ECDSA.recoverCalldata(hash, atomicSig));
}
The atomicFillSigner is immutable after deployment. Setting it to address(0) effectively pauses all fill operations while preserving claim functionality.
Security Features:
  • Single Authorized Signer - Only the designated signer can authorize fill batches
  • Replay Protection - Signatures are bound to specific calldata via hash
  • ECDSA Recovery - Efficient signature verification without public key input
  • Pausable - Setting signer to zero address pauses fills

​
Operation Flow

1

Submit Operation

User or solver submits fill or claim operation to Router
2

Signature Validation

Router validates atomic fill signature (for fills only)
3

Adapter Resolution

Router resolves function selector to adapter address
4

Delegatecall Execution

Router delegatecalls adapter with relayer context
5

Settlement

Adapter coordinates with arbiter for final settlement

​
Gas Optimizations

The Router implements several gas optimization techniques:

​
Adapter Caching

RouterLogic.sol
// Cache last used adapter to avoid repeated SLOAD operations
bytes4 prevSelector;
address adapter;

if (selector != prevSelector) {
    adapter = selector.withFillAdapter().adapterAddress();
    prevSelector = selector;
}
// Saves ~2100 gas per cache hit

​
Optimized Route Fill

The optimized_routeFill921336808 function provides enhanced performance:
RouterLogic.sol
function optimized_routeFill921336808(
    bytes[] calldata relayerContexts,
    bytes calldata encodedAdapterCalldatas,
    bytes calldata atomicFillSignature
) public payable virtual nonReentrant
Optimizations:
  • Encoded Calldata Format - Reduces calldata costs by ~200-500 gas per element
  • Adapter Caching - Reuses cached addresses for consecutive same-selector calls
  • Special Selector Bypass - Built-in selectors skip adapter lookup entirely
  • Inline Assembly Decoding - Operates directly on calldata without memory copying
  • Adapter Cache Hit: ~2,100 gas (avoids cold SLOAD)
  • Special Selector: ~2,600+ gas (avoids SLOAD + DELEGATECALL overhead)
  • Encoded Calldata: ~200-500 gas per operation
  • Assembly Decoding: Saves memory expansion and copying costs

​
Role-Based Access Control

The Router uses OpenZeppelin’s AccessControl for adapter management:
RoleAddressCapabilities
ADD_ROLEadderInstall new adapters, apply hotfixes, set atomic fill signer, pause router
RM_ROLEremoverRetire problematic or deprecated adapters
RouterManager.sol
constructor(address addAdmin, address rmAdmin) {
    _grantRole(ADD_ROLE, addAdmin);
    _grantRole(RM_ROLE, rmAdmin);
}

​
Configuration

​
Deployment Parameters

​
atomicFillSigner
address
required
Address authorized to sign atomic fill batches. Must be non-zero for fills to function. Consider using hardware wallet or multi-sig.
​
adder
address
required
Address granted ADD_ROLE for registering new protocol adapters. Should be a secure governance address.
​
remover
address
required
Address granted RM_ROLE for disabling compromised adapters. Should be a secure operations address.

​
Example Deployment

address atomicSigner = 0x1234...;
address governance = 0x5678...;
address operations = 0x9abc...;

Router router = new Router(atomicSigner, governance, operations);

​
Security Considerations

Critical Security Points:
  • The atomicFillSigner controls all user asset movements through fills
  • Adapter management roles should be assigned to secure governance/operations addresses
  • All addresses are immutable or role-protected after deployment
  • Reentrancy protection is enforced on all external functions

Adapters

Learn about the adapter architecture and delegatecall pattern

Fill & Claim

Understand fill and claim operation types

Build docs developers (and LLMs) love

Get started for freeTalk to us