Architecture Overview

Warp Router implements a modular, delegatecall-based architecture that separates routing logic from protocol-specific settlement implementations. This design enables seamless integration of new protocols while maintaining consistent security guarantees and gas optimizations across all settlement types.

System Architecture

The architecture consists of three primary layers:

Router Layer

Handles operation routing, batching of settlement layers, and enforcement of atomicity

Adapter Layer

Protocol-specific settlement logic executed via delegatecall

Arbiter Layer

Validates and unlocks user resources for settlement

Layer 1: Router

The Router system serves as the central coordination hub for all settlement operations. It combines execution logic (RouterLogic) with adapter lifecycle management (RouterManager) to provide a complete routing solution.

Core Components

RouterLogic - Execution Engine

The RouterLogic contract orchestrates all settlement operations:

src/router/core/RouterLogic.sol

contract RouterLogic is IRouter, RouterManager, DirectRoutes, ReentrancyGuardTransient {
    /**
     * @notice Initializes the RouterLogic contract with essential security
     *         and management addresses.
     * @param atomicFillSigner The address authorized to sign atomic fill
     *        batch operations.
     * @param adder The address granted ADAPTER_ADDER_ROLE for registering
     *        new protocol adapters.
     * @param remover The address granted ADAPTER_REMOVER_ROLE for disabling
     *        problematic adapters.
     */
    constructor(
        address atomicFillSigner,
        address adder,
        address remover
    ) RouterManager(adder, remover) {
        $atomicFillSigner = atomicFillSigner;
    }
}

Key Responsibilities:

Atomic intent processing across multiple operations
Gas optimization through adapter caching
Signature validation for all fill operations
Reentrancy protection via transient storage

RouterManager - Lifecycle Management

The RouterManager handles adapter registration, versioning, and lifecycle:Features:

Semantic Versioning: Enforces version compatibility for safe upgrades
Hotfix Support: Allows patch-only upgrades for critical fixes
Role-Based Access: Separate roles for adding (ADD_ROLE) and removing (RM_ROLE) adapters
Emergency Pause: Can pause all fill operations by setting signer to address(0)

Adding New Adapters:

// Install a new adapter (requires ADD_ROLE)
routerManager.installFillAdapter(
    version,    // Semantic version (2 bytes)
    selector,   // Function selector
    adapter,    // Adapter contract address
    tag        // Optional metadata (12 bytes)
);

DirectRoutes - Special Operations

Built-in operations that bypass adapter lookup for common tasks:

singleCall: Direct contract interaction
multiCall: Batched contract interactions
Fee collection operations

Gas Savings: Special selectors save 2,600+ gas by avoiding both storage reads and delegatecalls.

Operation Types

Fill Operations
Claim Operations

Fill operations are settlement operations that fulfill user orders by transferring assets and executing target operations.Standard Fill Route:

function routeFill(
    bytes calldata relayerContext,
    bytes calldata adapterCalldata
) external payable nonReentrant;

Optimized Batch Fill:

src/router/core/RouterLogic.sol

/**
 * @notice Gas-optimized version of routeFill with enhanced batching
 *         and caching mechanisms.
 * @dev Implements several optimizations:
 *      1. Encoded calldata format reduces decoding costs
 *      2. Adapter caching saves ~2100 gas per cache hit
 *      3. Special selector optimization bypasses adapter lookup
 *      4. Inline assembly decoding operates directly on calldata
 *      5. Solver context management for efficient consumption tracking
 */
function optimized_routeFill921336808(
    bytes[] calldata relayerContexts,
    bytes calldata encodedAdapterCalldatas,
    bytes calldata atomicFillSignature
) public payable virtual nonReentrant {
    // Compute hash and verify atomic signature
    bytes32 hash = encodedAdapterCalldatas.hashCalldata();
    require(_isAtomic(hash, atomicFillSignature), InvalidAtomicity());
    
    // Execute batch with caching and optimizations
    // ...
}

Fill operations require atomic signatures from the designated atomic signer.

Claim operations unlock user resources from protocols like TheCompact or Permit2.Single Claim:

function routeClaim(
    bytes calldata relayerContext,
    bytes calldata adapterCalldata
) external payable nonReentrant;

Batch Claims:

function routeClaim(
    bytes[] calldata relayerContexts,
    bytes[] calldata adapterCalldatas
) external payable nonReentrant;

Claim operations don’t require atomic signatures as they rely on protocol-level authorization.

Gas Optimization Features

The Router implements advanced optimization techniques:

Adapter Caching

Consecutive operations with the same selector reuse cached adapter addresses:

// Cache the adapter address on first use
address adapter = selector.resolveAdapter(version);
cachedAdapter = adapter;
cachedSelector = selector;

// Reuse on subsequent calls with same selector
if (selector == cachedSelector) {
    adapter = cachedAdapter;  // Saves ~2100 gas
}

Savings: Approximately 2,100 gas per cache hit (avoids cold SLOAD)

Special Selector Bypass

Built-in operations skip adapter lookup entirely:

// Special selectors handled directly
if (selector == SINGLE_CALL_SELECTOR) {
    _handleSingleCall(calldata);
    return;  // No adapter lookup or delegatecall
}

Savings: 2,600+ gas (avoids SLOAD + DELEGATECALL overhead)

Optimized Encoding

The optimized route accepts pre-encoded calldata arrays:

// Standard: decodes array from memory
bytes[] calldata calldatas;  // ABI decoding overhead

// Optimized: operates on raw encoded bytes
bytes calldata encoded;  // Direct calldata access

Savings: 200-500 gas per element in the array

Context Indexing

Efficient tracking of which operations consume solver contexts:

// Only increment context index for non-special operations
if (!isSpecialSelector(selector)) {
    relayerContext = relayerContexts[contextIndex++];
}

Savings: Reduces unnecessary array access and bounds checking

Security Model

Atomic Signatures

All fill operations require cryptographic signatures from the atomic signer, preventing unauthorized execution.

Reentrancy Protection

ReentrancyGuardTransient protects all external functions using efficient transient storage (EIP-1153).

Role-Based Access

Separate roles for adapter management prevent unauthorized protocol modifications.

Batch Integrity

All operations in a batch must succeed or the entire batch reverts, ensuring atomicity.

Layer 2: Adapters

Adapters are protocol-specific contracts that handle the actual settlement logic for different protocols and chains. They are always executed via delegatecall from the Router, inheriting its storage context and permissions.

Adapter Architecture

src/base/adapter/AdapterBase.sol

/**
 * @title AdapterBase
 * @notice Abstract base contract for settlement layer specific adapters
 * @dev CRITICAL SECURITY NOTICE:
 *      - Adapters are ALWAYS executed via delegatecall from the Router contract
 *      - The Router's storage and balance are accessible during adapter execution
 *      - DO NOT implement direct calls to untrusted contracts
 *      - All external calls to untrusted contracts could be detrimental to Router security
 */
abstract contract AdapterBase is IAdapter, SemVer, IIndexedEvents {
    /// @notice The Router contract address that this adapter is designed to work with
    address public immutable _ROUTER;
    
    /// @notice The Arbiter contract address responsible for validating settlements
    address public immutable ARBITER;
    
    constructor(address router, address arbiter) {
        _ROUTER = router;
        ARBITER = arbiter == address(0) ? address(this) : arbiter;
    }
    
    /**
     * @notice Ensures function is only called via delegatecall from the Router
     * @dev When delegatecalled from Router, address(this) equals _ROUTER
     */
    modifier onlyViaRouter() {
        require(address(this) == _ROUTER, OnlyDelegateCall());
        _;
    }
}

Implementation Requirements

All adapter functions implementing fill or claim logic must follow strict requirements:

Return Function Selector

All external functions must return their own function selector:

function myFillOperation(...) external returns (bytes4) {
    // Settlement logic here
    return this.myFillOperation.selector;
}

This enables the Router to validate successful execution.

Implement ERC165

All fill/claim functions must be registered in supportsInterface:

function supportsInterface(bytes4 interfaceId) public pure override returns (bool) {
    return interfaceId == this.myFillOperation.selector ||
           interfaceId == this.myClaimOperation.selector ||
           super.supportsInterface(interfaceId);
}

Use onlyViaRouter Modifier

All external functions must use the security modifier:

function myOperation(...) external onlyViaRouter returns (bytes4) {
    // Only callable via Router delegatecall
}

Solver Context Handling

Adapters extract solver-specific data using the _loadRelayerContext() helper:

src/base/adapter/AdapterBase.sol

/**
 * @notice Extracts relayer-provided context data from the end of the calldata
 * @dev The Router appends relayer context using:
 *      abi.encodePacked(adapterCalldata, relayerContext, uint256(relayerContext.length))
 * 
 *      Resulting format: [original_function_calldata][relayer_context_bytes][context_length_32_bytes]
 */
function _loadRelayerContext() internal pure returns (
    uint256 contextLength,
    bytes calldata relayerContext
) {
    assembly ("memory-safe") {
        let totalSize := calldatasize()
        contextLength := calldataload(sub(totalSize, 0x20))
        relayerContext.offset := sub(totalSize, add(contextLength, 0x20))
        relayerContext.length := contextLength
    }
}

Example Usage:

src/arbiters/samechain/SameChainAdapter.sol

function _tokenInRecipient() internal pure returns (address tokenInRecipient) {
    (uint256 relayerContextLength, bytes calldata relayerContext) = _loadRelayerContext();
    require(relayerContextLength == 20, InvalidRelayerContext());
    // Decode the recipient address from the first 20 bytes
    return address(bytes20(relayerContext[:20]));
}

Example Adapter: IntentExecutorAdapter

The IntentExecutorAdapter demonstrates a simple forwarding pattern:

src/adapters/IntentExecutorAdapter.sol

/**
 * @title IntentExecutorAdapter
 * @notice Gas-optimized adapter for forwarding intent execution calls
 * @dev Uses memory-safe assembly for calldata forwarding to minimize gas overhead,
 *      typically saving 200-500 gas per call compared to high-level Solidity.
 */
contract IntentExecutorAdapter is AdapterBase {
    address internal immutable EXECUTOR;
    
    constructor(address router, address executor) 
        AdapterBase(router, address(0)) 
        SemVer(0, 0) 
    {
        EXECUTOR = executor;
    }
    
    /**
     * @notice Handles compact intent execution by forwarding to the executor
     * @dev Forwards the call using optimized assembly forwarding
     */
    function handleFill_intentExecutor_handleCompactTargetOps(
        bytes calldata executorCalldata
    ) external payable onlyViaRouter returns (bytes4) {
        EXECUTOR.passthrough(COMPACT_INTENT_SELECTOR, executorCalldata);
        return this.handleFill_intentExecutor_handleCompactTargetOps.selector;
    }
    
    function supportsInterface(bytes4 selector) public pure override returns (bool) {
        return selector == this.handleFill_intentExecutor_handleCompactTargetOps.selector ||
               super.supportsInterface(selector);
    }
}

Layer 3: Arbiters

Arbiters are responsible for validating settlements and unlocking funds from user accounts or resource locks. They provide dual protocol support for both TheCompact and Permit2 standards.

Arbiter Architecture

src/base/arbiter/ArbiterBase.sol

/**
 * @title ArbiterBase
 * @notice Base arbiter contract that enables unlocking funds from user accounts
 * @dev Serves as a critical component acting as an arbiter that can unlock and
 *      manage funds on behalf of users. Provides dual protocol support for both
 *      TheCompact and Permit2 standards.
 */
contract ArbiterBase is CompactArbiter, Permit2Arbiter, PreClaimExecution, IArbiter {
    /// @dev The Router address that has exclusive access to settlement functions
    address internal immutable ROUTER;
    
    constructor(
        address router,
        address compact,
        address addressBook
    )
        CompactArbiter(compact)
        Permit2Arbiter(address(Constants.PERMIT2))
        PreClaimExecution(addressBook)
    {
        ROUTER = router;
    }
    
    /**
     * @notice Restricts function access to only the authorized Router contract
     * @dev Critical security boundary preventing unauthorized access to user funds
     */
    modifier onlyRouter() {
        require(msg.sender == ROUTER, OnlyRouter());
        _;
    }
}

Key Responsibilities

Execute Pre-Claim Operations

Arbiters execute optional operations before settlement:

src/base/arbiter/ArbiterBase.sol

function _compactPreClaimOps(
    Types.Order calldata order,
    Types.Signatures calldata sigs,
    bytes32[] calldata otherElements,
    uint256 elementOffset,
    uint256 notarizedChainId
) internal returns (bytes32 mandateHash) {
    // Compute EIP-712 hashes for order components
    bytes32 targetAttributesHash = order.hashTargetAttributes();
    bytes32 destOpsHash = order.targetOps.hashOps();
    
    // Determine if pre-claim operations need execution
    (SmartExecutionLib.Type opsType, bytes32 preClaimOpsHash) = 
        order.preClaimOps.decodeAll();
    
    // Execute pre-claim operations if they exist
    if (preClaimOpsHash != Constants.NO_OPS) {
        if (opsType == SmartExecutionLib.Type.ERC7579) {
            _handlePreClaimOpsCompactERC7579({...});
        } else if (opsType == SmartExecutionLib.Type.MultiCall) {
            _handlePreClaimOpsMulticall({...});
        } else if (opsType == SmartExecutionLib.Type.Calldata) {
            _handlePreClaimOpsCallData({...});
        }
    }
    
    // Return mandate hash for protocol validation
    return EIP712TypeHashLib.hashMandateRaw({...});
}

Compute Mandate Hashes

Arbiters compute mandate hashes for TheCompact and Permit2 validation:

// Construct the mandate hash for protocol validation
mandateHash = EIP712TypeHashLib.hashMandateRaw({
    targetAttributes: targetAttributesHash,
    minGas: minGas,
    preClaimOpsHash: preClaimOpsHash,
    destOpsHash: destOpsHash,
    qHash: qHash
});

The mandate hash uniquely identifies the order and its operations for protocol-level validation.

Router-Only Access Control

Arbiters enforce strict access control:

modifier onlyRouter() {
    require(msg.sender == ROUTER, OnlyRouter());
    _;
}

This prevents unauthorized entities from executing settlement operations or accessing user funds.

Orchestrate Settlement Flow

Arbiters coordinate the complete settlement flow for both protocols:

Validate user signatures
Execute pre-claim operations with proper gas stipends
Unlock funds from TheCompact or Permit2
Transfer assets to designated recipients
Execute target operations on behalf of users

Settlement Flows

Let’s examine the complete settlement flows for different operation types.

Fill Flow

Signature Verification

Router verifies the atomic fill signature to ensure authorization

Adapter Lookup

Router loads the adapter address from storage (or cache if available)

Delegatecall Execution

Router delegatecalls into the adapter with the relayer context appended

Settlement Layer Interaction

Adapter interacts with the settlement layer (TheCompact, Permit2, etc.)

Intent Execution

Intent executor validates user signature and executes target operations

Completion

Adapter returns its function selector to confirm successful execution

Claim Flow

Router Invocation

Relayer calls routeClaim with adapter calldata (no atomic signature required)

Adapter Execution

Router delegatecalls into the claim adapter

Arbiter Coordination

Adapter calls the arbiter to orchestrate the claim process

Pre-Claim Operations

Arbiter executes optional pre-claim operations with dedicated gas stipend

Protocol Selection

Arbiter claims funds from either Permit2 or TheCompact based on order type

Fund Transfer

Protocol validates signatures and transfers funds to arbiter

Settlement

Arbiter deposits funds to the settlement layer destination

Security Architecture

Delegatecall Context

Adapters execute in Router’s context, inheriting its storage and permissions. This requires strict security controls on adapter code.

Signature Validation

Multiple signature validation layers:

Atomic signatures for fill operations
User signatures for intent execution
Protocol signatures for resource unlocking

Access Control

Layered access control:

Router validates atomic signatures
Adapters enforce onlyViaRouter
Arbiters enforce onlyRouter

Atomicity Guarantees

All operations in a batch succeed or revert together, preventing partial execution vulnerabilities.

Security Considerations

Critical security boundaries must be maintained at all layers

For Adapter Developers

Delegatecall Context: Adapters execute in Router’s storage context - never write to storage slots
External Calls: Only interact with trusted, well-audited protocols
Return Values: Always return function selector for validation
Interface Support: Implement ERC165 for all settlement functions
No Untrusted Calls: Never make calls to user-provided addresses

For Arbiter Developers

Router-Only Access: Enforce onlyRouter modifier on all settlement functions
Signature Validation: Validate all user signatures before unlocking funds
Gas Stipends: Properly account for EIP-150’s 63/64 gas forwarding rule
Mandate Hashes: Compute hashes correctly to prevent signature replay
Pre-Claim Safety: Execute pre-claim operations with proper error handling

For Solvers/Relayers

Atomic Signatures: Fill operations require valid signatures from atomic signer
Context Validation: Ensure solver context matches adapter expectations
Batch Integrity: Design batches carefully to avoid partial execution
Gas Estimation: Account for pre-claim operation gas stipends
Protocol Authorization: Ensure proper protocol-level authorizations for claims

Performance Characteristics

Gas Cost Breakdown

Operation Type	Base Cost	With Caching	Special Selector
Single Fill	~150k gas	N/A	N/A
Batch Fill (5 ops, same adapter)	~600k gas	~540k gas (10% savings)	N/A
Batch Fill (5 ops, mixed adapters)	~650k gas	~590k gas (9% savings)	N/A
Special Call	~50k gas	N/A	~47k gas (6% savings)

Actual gas costs vary based on the specific protocol adapter and settlement layer used.

Optimization Impact

Adapter Caching Benefits:

First operation: Full SLOAD cost (~2,100 gas)
Cached operations: Memory read (~3 gas)
Break-even point: 2 operations with same adapter
Maximum benefit: Long batches with few adapters

Special Selector Benefits:

Avoids SLOAD: ~2,100 gas saved
Avoids DELEGATECALL: ~700 gas saved
Avoids context append: ~200 gas saved
Total savings: ~2,600+ gas per operation

Next Steps

Integration Guide

Learn how to integrate Warp Router into your solver or relayer

Build an Adapter

Step-by-step guide to building custom protocol adapters

API Reference

Complete API documentation for all contracts

Security Best Practices

Learn security best practices for each layer

Get Started

Core Concepts

Integration Guide

Advanced

Documentation Index

​Architecture Overview

​System Architecture

Router Layer

Adapter Layer

Arbiter Layer

​Layer 1: Router

​Core Components

​Operation Types

​Gas Optimization Features

​Security Model

Atomic Signatures

Reentrancy Protection

Role-Based Access

Batch Integrity

​Layer 2: Adapters

​Adapter Architecture

​Implementation Requirements

​Solver Context Handling

​Example Adapter: IntentExecutorAdapter

​Layer 3: Arbiters

​Arbiter Architecture

​Key Responsibilities

​Settlement Flows

​Fill Flow

​Claim Flow

​Security Architecture

Delegatecall Context

Signature Validation

Access Control

Atomicity Guarantees

​Security Considerations

​Performance Characteristics

​Gas Cost Breakdown

​Optimization Impact

​Next Steps

Integration Guide

Build an Adapter

API Reference

Security Best Practices

Architecture Overview

System Architecture

Layer 1: Router

Core Components

Operation Types

Gas Optimization Features

Security Model

Layer 2: Adapters

Adapter Architecture

Implementation Requirements

Solver Context Handling

Example Adapter: IntentExecutorAdapter

Layer 3: Arbiters

Arbiter Architecture

Key Responsibilities

Settlement Flows

Fill Flow

Claim Flow

Security Architecture

Security Considerations

Performance Characteristics

Gas Cost Breakdown

Optimization Impact

Next Steps