PostIntentHookRegistry

​

Overview

​

Purpose

• Hook Whitelisting: Maintain a list of trusted post-intent hook contracts
• Security Control: Prevent unauthorized or malicious hooks from being executed
• Extensibility: Enable protocol extensions through approved custom logic
• Governance: Allow protocol owners to control which hooks are available

​

State Variables

mapping(address => bool) public whitelistedHooks;
address[] public hooks;

• whitelistedHooks: Maps hook addresses to their whitelist status
• hooks: Array of all whitelisted hook addresses

​

Core Functions

​

Adding Hooks

function addPostIntentHook(address _hook) external onlyOwner

• _hook: Address of the hook contract to whitelist

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

​

Removing Hooks

function removePostIntentHook(address _hook) external onlyOwner

• _hook: Address of the hook contract to remove

• Hook must be currently whitelisted
• Only callable by owner

​

View Functions

​

Check Hook Status

function isWhitelistedHook(address _hook) external view returns (bool)

• _hook: Address of the hook contract to check

​

Get All Hooks

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

​

Integration with Core Contracts

​

Orchestrator

// In Orchestrator constructor
postIntentHookRegistry = IPostIntentHookRegistry(_postIntentHookRegistry);

// Validation when executing hooks
require(
    postIntentHookRegistry.isWhitelistedHook(hookAddress),
    "Hook not whitelisted"
);

​

Hook Execution Flow

1. User signals intent with an optional post-intent hook address
2. Orchestrator validates hook is whitelisted via registry
3. After intent fulfillment, orchestrator calls the whitelisted hook
4. Hook executes custom logic (e.g., bridge tokens, swap, etc.)

​

Configuration Updates

function setPostIntentHookRegistry(address _postIntentHookRegistry) external onlyOwner {
    postIntentHookRegistry = IPostIntentHookRegistry(_postIntentHookRegistry);
    emit PostIntentHookRegistryUpdated(_postIntentHookRegistry);
}

​

Example Post-Intent Hooks

​

AcrossBridgeHookV2

• Whitelisted in the registry
• Called after successful intent fulfillment
• Bridges funds using Across Protocol

​

Custom Hook Pattern

interface IPostIntentHook {
    function execute(
        address recipient,
        uint256 amount,
        address token,
        bytes calldata data
    ) external;
}

​

Access Control

​

Owner-Only Functions

• addPostIntentHook(): Add hook to whitelist
• removePostIntentHook(): Remove hook from whitelist

​

View Functions

• isWhitelistedHook()
• getWhitelistedHooks()
• whitelistedHooks[address] (public mapping)

​

Events

event PostIntentHookAdded(address indexed hook);
event PostIntentHookRemoved(address indexed hook);

• Monitoring hook whitelist changes
• Off-chain indexing of available hooks
• Audit trails for governance decisions

​

Usage Patterns

​

Adding a New Hook

// 1. Deploy hook contract
AcrossBridgeHookV2 bridgeHook = new AcrossBridgeHookV2(...);

// 2. Whitelist in registry
postIntentHookRegistry.addPostIntentHook(address(bridgeHook));

// 3. Users can now specify this hook when signaling intents

​

Using Hooks in Intents

// User signals intent with post-intent hook
SignalIntentParams memory params = SignalIntentParams({
    // ... other parameters
    postIntentHook: whitelistedHookAddress,
    hookData: abi.encode(bridgeDestination, minAmount)
});

orchestrator.signalIntent(params);

​

Removing Deprecated Hooks

// Remove hook from whitelist
postIntentHookRegistry.removePostIntentHook(deprecatedHookAddress);

// Note: Existing intents using this hook can still be fulfilled,
// but new intents cannot use it

​

Security Considerations

​

Hook Validation

1. Whitelist Only: Only explicitly approved hooks can be used
2. Owner Control: Centralized governance over hook approval
3. No Automatic Approval: Hooks must be manually reviewed and added

​

Hook Security Requirements

1. Code Audit: Hook contract should be audited for security
2. Correct Interface: Implements expected function signatures
3. Re-entrancy Protection: Doesn’t create re-entrancy vulnerabilities
4. Gas Limits: Doesn’t consume excessive gas
5. Fund Safety: Cannot steal or lock user funds

​

Integration Security

1. Validation First: Always check isWhitelistedHook() before execution
2. Error Handling: Handle hook failures gracefully
3. Event Logging: Track hook executions for monitoring

​

User Protection

• Users should understand what hooks do before using them
• Hook execution failures should not prevent intent fulfillment
• Hooks cannot access more funds than specified in the intent

​

Hook Development Guidelines

1. Stateless Execution: Hooks should be stateless when possible
2. Clear Purpose: Each hook should have a specific, well-defined purpose
3. Gas Efficiency: Optimize for gas to keep user costs low
4. Error Recovery: Handle errors gracefully without reverting the entire transaction
5. Documentation: Clearly document hook behavior and parameters

​

Deployment Strategy

1. Initial Deployment: Deploy registry with no hooks
2. Add Trusted Hooks: Whitelist audited hook contracts
3. Configure Orchestrator: Set registry address in Orchestrator
4. Monitor Usage: Track hook usage via events
5. Iterate: Add new hooks as protocol evolves

​

Related Contracts

• Orchestrator - Executes whitelisted hooks after intent fulfillment
• AcrossBridgeHookV2 - Example post-intent hook for cross-chain bridging
• OrchestratorRegistry - Related registry for orchestrator authorization