OrchestratorRegistry

​

Overview

​

Purpose

• Access Control: Restricts which contracts can interact with escrow funds
• Orchestrator Allowlist: Maintains a list of authorized orchestrator implementations
• Security Layer: Prevents unauthorized contracts from managing deposits
• Upgrade Management: Controls rollout of new orchestrator versions

​

State Variables

mapping(address => bool) public override isOrchestrator;

• isOrchestrator: Maps orchestrator addresses to their authorization status

​

Core Functions

​

Adding Orchestrators

function addOrchestrator(address _orchestrator) external override onlyOwner

• _orchestrator: Address of the orchestrator contract to authorize

• Orchestrator address cannot be zero
• Orchestrator must not already be added
• Only callable by owner

• ZeroAddress(): If _orchestrator is the zero address
• OrchestratorAlreadyAdded(address orchestrator): If orchestrator is already authorized

​

Removing Orchestrators

function removeOrchestrator(address _orchestrator) external override onlyOwner

• _orchestrator: Address of the orchestrator contract to de-authorize

• Orchestrator address cannot be zero
• Orchestrator must currently be authorized
• Only callable by owner

• ZeroAddress(): If _orchestrator is the zero address
• OrchestratorNotFound(address orchestrator): If orchestrator is not currently authorized

​

View Functions

​

Check Orchestrator Authorization

mapping(address => bool) public isOrchestrator;

bool authorized = orchestratorRegistry.isOrchestrator(orchestratorAddress);

​

Integration with Core Contracts

​

EscrowV2

// In EscrowV2 constructor
orchestratorRegistry = IOrchestratorRegistry(_orchestratorRegistry);

// Validation in EscrowV2 functions
modifier onlyOrchestrator() {
    require(
        orchestratorRegistry.isOrchestrator(msg.sender),
        "Caller is not an authorized orchestrator"
    );
    _;
}

• Deposit creation on behalf of users
• Intent signaling and locking
• Payment releases
• Deposit withdrawals

​

Payment Verifiers

orchestratorRegistry = IOrchestratorRegistry(_orchestratorRegistry);

// Validation before processing proofs
require(
    orchestratorRegistry.isOrchestrator(msg.sender),
    "Caller not authorized orchestrator"
);

​

Hooks

• WhitelistPreIntentHook: Checks orchestrator authorization before allowing whitelisted operations
• SignatureGatingPreIntentHook: Validates orchestrator before processing gated intents
• AcrossBridgeHookV2: Ensures only authorized orchestrators can trigger bridge operations

​

Access Control

​

Custom Errors

error ZeroAddress();
error OrchestratorAlreadyAdded(address orchestrator);
error OrchestratorNotFound(address orchestrator);

​

Owner Functions

• addOrchestrator(): Authorize new orchestrators
• removeOrchestrator(): Revoke orchestrator authorization

​

Public View

​

Events

event OrchestratorAdded(address indexed orchestrator);
event OrchestratorRemoved(address indexed orchestrator);

• Tracking orchestrator authorization changes
• Off-chain monitoring of authorized orchestrators
• Audit trails for governance actions

​

Security Model

​

Authorization Security

1. Centralized Control: Only owner can modify orchestrator list
2. Explicit Authorization: Orchestrators must be explicitly added
3. Revocability: Authorization can be revoked at any time
4. Zero Address Protection: Prevents authorization of invalid addresses

​

Integration Security

1. Pre-Call Validation: Contracts must check isOrchestrator before granting access
2. Modifier Usage: Use onlyOrchestrator modifier for protected functions
3. Event Monitoring: Watch for orchestrator changes to update off-chain systems

​

Upgrade Considerations

• Removing an orchestrator doesn’t affect its existing operations (deposits, intents)
• New orchestrators can be added without disrupting existing ones
• Registry contract itself can be upgraded by updating reference in EscrowV2

​

Usage Pattern

​

Deployment and Setup

// 1. Deploy OrchestratorRegistry
OrchestratorRegistry registry = new OrchestratorRegistry();

// 2. Authorize orchestrators
registry.addOrchestrator(orchestratorV1Address);
registry.addOrchestrator(orchestratorV2Address);

// 3. Configure EscrowV2 with registry
escrowV2.setOrchestratorRegistry(address(registry));

​

Upgrading Orchestrators

// Deploy new orchestrator version
OrchestratorV3 newOrchestrator = new OrchestratorV3(...);

// Authorize new version
orchestratorRegistry.addOrchestrator(address(newOrchestrator));

// Optionally, remove old version
orchestratorRegistry.removeOrchestrator(oldOrchestratorAddress);

​

Validation in Protected Contracts

contract ProtectedContract {
    IOrchestratorRegistry public orchestratorRegistry;
    
    modifier onlyAuthorizedOrchestrator() {
        require(
            orchestratorRegistry.isOrchestrator(msg.sender),
            "Not authorized"
        );
        _;
    }
    
    function protectedFunction() external onlyAuthorizedOrchestrator {
        // Protected logic
    }
}

​

Deployment Considerations

1. Single Registry: Use one OrchestratorRegistry per chain for all orchestrator versions
2. Initial Authorization: Authorize initial orchestrator(s) immediately after deployment
3. Registry Updates: EscrowV2 allows updating registry reference via setOrchestratorRegistry()
4. Multi-Version Support: Multiple orchestrator versions can be authorized simultaneously

​

Related Contracts

• EscrowV2 - Uses registry to validate orchestrator calls
• Orchestrator - V1 orchestrator that can be authorized
• OrchestratorV2 - V2 orchestrator with enhanced features
• UnifiedPaymentVerifier - Validates orchestrator authorization
• Intent Hooks - Various hooks that check orchestrator authorization