> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/zkp2p/zkp2p-contracts/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```solidity theme={null}
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

```solidity theme={null}
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

```solidity theme={null}
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

```solidity theme={null}
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:

```solidity theme={null}
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:

```solidity theme={null}
// 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:

```solidity theme={null}
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

```solidity theme={null}
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

```solidity theme={null}
// Authorize new relayer
relayerRegistry.addRelayer(newRelayerAddress);

// Relayer can now submit transactions
```

### Removing a Relayer

```solidity theme={null}
// Revoke relayer authorization
relayerRegistry.removeRelayer(compromisedRelayerAddress);

// Relayer can no longer submit transactions
```

### Validation in Orchestrator

```solidity theme={null}
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](/contracts/orchestrator) - Uses registry to validate relayer submissions
* [OrchestratorV2](/contracts/orchestrator) - Enhanced orchestrator with relayer support
* [PaymentVerifierRegistry](/contracts/payment-verifier-registry) - Related registry for payment verifiers