> ## 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.

# PostIntentHookRegistry

> Registry for whitelisting post-intent hook contracts

## Overview

The `PostIntentHookRegistry` is a registry contract that manages a whitelist of authorized post-intent hook contracts. These hooks are executed after an intent is successfully fulfilled, enabling custom logic such as automated bridging, token swaps, or other post-payment actions.

**Contract Location:** `contracts/registries/PostIntentHookRegistry.sol`

## Purpose

The PostIntentHookRegistry serves several important functions:

* **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

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

```solidity theme={null}
function addPostIntentHook(address _hook) external onlyOwner
```

Adds a post-intent hook contract to the whitelist.

**Parameters:**

* `_hook`: Address of the hook contract to whitelist

**Requirements:**

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

**Emits:** `PostIntentHookAdded(address indexed hook)`

**Reference:** `contracts/registries/PostIntentHookRegistry.sol:32`

### Removing Hooks

```solidity theme={null}
function removePostIntentHook(address _hook) external onlyOwner
```

Removes a post-intent hook contract from the whitelist.

**Parameters:**

* `_hook`: Address of the hook contract to remove

**Requirements:**

* Hook must be currently whitelisted
* Only callable by owner

**Emits:** `PostIntentHookRemoved(address indexed hook)`

**Reference:** `contracts/registries/PostIntentHookRegistry.sol:47`

## View Functions

### Check Hook Status

```solidity theme={null}
function isWhitelistedHook(address _hook) external view returns (bool)
```

Checks if a hook contract is whitelisted.

**Parameters:**

* `_hook`: Address of the hook contract to check

**Returns:** `true` if the hook is whitelisted, `false` otherwise

**Reference:** `contracts/registries/PostIntentHookRegistry.sol:58`

### Get All Hooks

```solidity theme={null}
function getWhitelistedHooks() external view returns (address[] memory)
```

Returns array of all whitelisted hook addresses.

**Reference:** `contracts/registries/PostIntentHookRegistry.sol:62`

## Integration with Core Contracts

### Orchestrator

The Orchestrator contract uses the PostIntentHookRegistry to validate and execute post-intent hooks:

```solidity theme={null}
// In Orchestrator constructor
postIntentHookRegistry = IPostIntentHookRegistry(_postIntentHookRegistry);

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

**Reference:** `contracts/Orchestrator.sol:84`

### 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

Orchestrator can update its registry reference:

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

**Reference:** `contracts/Orchestrator.sol:327`

## Example Post-Intent Hooks

### AcrossBridgeHookV2

Automatically bridges tokens to another chain after payment is received:

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

**Reference:** `contracts/hooks/AcrossBridgeHookV2.sol`

### Custom Hook Pattern

Post-intent hooks must implement the expected interface:

```solidity theme={null}
interface IPostIntentHook {
    function execute(
        address recipient,
        uint256 amount,
        address token,
        bytes calldata data
    ) external;
}
```

## Access Control

### Owner-Only Functions

All state-modifying functions require owner privileges:

* `addPostIntentHook()`: Add hook to whitelist
* `removePostIntentHook()`: Remove hook from whitelist

**Access Control Pattern:** OpenZeppelin's `Ownable` with `onlyOwner` modifier

### View Functions

All query functions are publicly accessible:

* `isWhitelistedHook()`
* `getWhitelistedHooks()`
* `whitelistedHooks[address]` (public mapping)

## Events

```solidity theme={null}
event PostIntentHookAdded(address indexed hook);
event PostIntentHookRemoved(address indexed hook);
```

These events enable:

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

## Usage Patterns

### Adding a New Hook

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

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

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

Before whitelisting a hook, verify:

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

When developing post-intent hooks:

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](/contracts/orchestrator) - Executes whitelisted hooks after intent fulfillment
* [AcrossBridgeHookV2](/contracts/across-bridge-hook) - Example post-intent hook for cross-chain bridging
* [OrchestratorRegistry](/contracts/orchestrator-registry) - Related registry for orchestrator authorization