RelayerRegistry

Registry for whitelisting authorized relayer addresses

Overview

The RelayerRegistry is a registry contract that manages a whitelist of authorized relayer addresses. Relayers are trusted entities that can submit transactions on behalf of users, typically for gasless transaction experiences or automated fulfillment processes.

Contract Location: contracts/registries/RelayerRegistry.sol

Purpose

The RelayerRegistry serves several key functions:

• Relayer Whitelisting: Maintain a list of trusted relayer addresses
• Access Control: Prevent unauthorized relayers from submitting transactions
• Gasless Transactions: Enable trusted relayers to submit meta-transactions for users
• Automated Fulfillment: Allow approved relayers to automatically fulfill intents

State Variables

mapping(address => bool) public isWhitelistedRelayer;
address[] public relayers;

• isWhitelistedRelayer: Maps relayer addresses to their whitelist status
• relayers: Array of all whitelisted relayer addresses

Core Functions

Adding Relayers

function addRelayer(address _relayer) external onlyOwner

Adds a relayer address to the whitelist.

Parameters:

• _relayer: Address of the relayer to whitelist

Requirements:

• Relayer address cannot be zero address
• Relayer must not already be whitelisted
• Only callable by owner

Emits: RelayerAdded(address indexed relayer)

Reference: contracts/registries/RelayerRegistry.sol:32

Removing Relayers

function removeRelayer(address _relayer) external onlyOwner

Removes a relayer address from the whitelist.

Parameters:

• _relayer: Address of the relayer to remove

Requirements:

• Relayer must be currently whitelisted
• Only callable by owner

Emits: RelayerRemoved(address indexed relayer)

Reference: contracts/registries/RelayerRegistry.sol:47

View Functions

Get All Relayers

function getWhitelistedRelayers() external view returns (address[] memory)

Returns array of all whitelisted relayer addresses.

Reference: contracts/registries/RelayerRegistry.sol:60

Check Relayer Status

The isWhitelistedRelayer mapping is public, allowing anyone to check if an address is a whitelisted relayer:

bool isWhitelisted = relayerRegistry.isWhitelistedRelayer(relayerAddress);

Integration with Core Contracts

Orchestrator

The Orchestrator contracts (Orchestrator.sol and OrchestratorV2.sol) use the RelayerRegistry to validate relayer submissions:

// In Orchestrator constructor
relayerRegistry = IRelayerRegistry(_relayerRegistry);

// Validation logic
if (msg.sender != intentSignaler) {
    require(
        relayerRegistry.isWhitelistedRelayer(msg.sender),
        "Caller must be intent signaler or whitelisted relayer"
    );
}

Reference: contracts/Orchestrator.sol:85

Configuration Updates

Orchestrator contracts can update their relayer registry reference:

function setRelayerRegistry(address _relayerRegistry) external onlyOwner {
    relayerRegistry = IRelayerRegistry(_relayerRegistry);
    emit RelayerRegistryUpdated(_relayerRegistry);
}

Reference: contracts/Orchestrator.sol:339

Use Cases

Gasless Transactions

Relayers enable users to interact with the protocol without holding native gas tokens:

1. User signs an intent off-chain
2. Whitelisted relayer submits the transaction on-chain
3. Relayer pays gas fees
4. Relayer potentially earns fees from the intent

Automated Intent Fulfillment

Relayers can automatically fulfill intents when off-chain payment is detected:

1. Relayer monitors off-chain payment systems
2. When payment is confirmed, relayer submits proof on-chain
3. Intent is fulfilled without user needing to submit second transaction

Meta-Transaction Support

Relayers can implement meta-transaction patterns:

1. User signs message with intent to perform action
2. Relayer wraps user’s signature in actual transaction
3. Contract validates user signature and relayer authorization
4. Action executes as if user submitted directly

Access Control

Owner-Only Functions

All state-modifying functions require owner privileges:

• addRelayer(): Add relayer to whitelist
• removeRelayer(): Remove relayer from whitelist

Access Control Pattern: OpenZeppelin’s Ownable with onlyOwner modifier

View Functions

All query functions are publicly accessible:

• getWhitelistedRelayers()
• isWhitelistedRelayer[address] (public mapping)

Events

event RelayerAdded(address indexed relayer);
event RelayerRemoved(address indexed relayer);

These events enable:

• Monitoring relayer whitelist changes
• Off-chain tracking of authorized relayers
• Audit trails for relayer management

Usage Patterns

Adding a Relayer

// Authorize new relayer
relayerRegistry.addRelayer(newRelayerAddress);

// Relayer can now submit transactions

Removing a Relayer

// Revoke relayer authorization
relayerRegistry.removeRelayer(compromisedRelayerAddress);

// Relayer can no longer submit transactions

Validation in Orchestrator

function fulfillIntent(bytes32 intentHash) external {
    Intent memory intent = intents[intentHash];
    
    // Allow intent owner or whitelisted relayer
    require(
        msg.sender == intent.owner || 
        relayerRegistry.isWhitelistedRelayer(msg.sender),
        "Not authorized"
    );
    
    // Process fulfillment
    // ...
}

Relayer Security

Trust Assumptions

Whitelisted relayers are trusted to:

1. Submit Valid Transactions: Only submit legitimate user requests
2. Protect User Data: Handle user signatures and data securely
3. Fair Fees: Charge reasonable fees for relaying services
4. Availability: Maintain uptime for critical operations

Security Considerations

1. Centralized Trust: Relayers are centrally approved by owner
2. Revocability: Malicious relayers can be removed from whitelist
3. User Consent: Users must explicitly sign transactions for relayers
4. Limited Scope: Relayers can only execute user-signed actions

Relayer Compromise Response

If a relayer is compromised:

1. Owner immediately removes relayer from whitelist
2. Relayer can no longer submit new transactions
3. Existing intents are not affected
4. Monitor for any malicious activity from the compromised relayer

Relayer Requirements

Before whitelisting a relayer:

1. Identity Verification: Know who operates the relayer
2. Security Audit: Review relayer infrastructure security
3. Reputation: Check relayer’s history and reputation
4. SLA Commitment: Ensure relayer commits to availability
5. Fee Transparency: Relayer must be transparent about fees

Deployment Strategy

1. Initial Deployment: Deploy registry with no relayers
2. Add Trusted Relayers: Whitelist vetted relayer addresses
3. Configure Orchestrator: Set registry address in Orchestrator
4. Monitor Activity: Track relayer submissions via events
5. Iterate: Add/remove relayers as needed

Related Contracts

• Orchestrator - Uses registry to validate relayer submissions
• OrchestratorV2 - Enhanced orchestrator with relayer support
• PaymentVerifierRegistry - Related registry for payment verifiers