> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cow.bleu.builders/llms.txt
> Use this file to discover all available pages before exploring further.

# HooksTrampoline Contract

> Complete API reference for the HooksTrampoline contract

The `HooksTrampoline` contract provides a secure execution environment for user-specified hooks during CoW Protocol settlements. It ensures hooks are executed in an unprivileged context and prevents hook failures from blocking settlements.

## Contract Overview

```solidity theme={null}
contract HooksTrampoline {
    address public immutable settlement;

    constructor(address settlement_);
    function execute(Hook[] calldata hooks) external onlySettlement;
}
```

## Constructor

Initializes the trampoline with the CoW Protocol settlement contract address.

```solidity theme={null}
constructor(address settlement_)
```

### Parameters

| Name | Type | Description |
| - | - | - |
| `settlement_` | `address` | The address of the CoW Protocol settlement contract. This address will be the only caller authorized to execute hooks through this trampoline. |

### Example

```solidity theme={null}
// Deploy trampoline for a specific settlement contract
address settlementAddress = 0x9008D19f58AAbD9eD0D60971565AA8510560ab41;
HooksTrampoline trampoline = new HooksTrampoline(settlementAddress);
```

## State Variables

### settlement

```solidity theme={null}
address public immutable settlement
```

The address of the CoW Protocol settlement contract. This is set during construction and cannot be changed.

| Property | Value |
| - | - |
| Type | `address` |
| Visibility | `public` |
| Mutability | `immutable` |

Returns the address of the authorized settlement contract. Only this address can call the `execute()` function.

## Functions

### execute

Executes an array of user-specified hooks during a CoW Protocol settlement.

```solidity theme={null}
function execute(Hook[] calldata hooks) external onlySettlement
```

#### Parameters

| Name | Type | Description |
| - | - | - |
| `hooks` | `Hook[]` | An array of `Hook` structs to execute sequentially. Each hook specifies a target address, call data, and gas limit. See [Hook Struct](https://docs.cow.bleu.builders/hooks-trampoline/api/hook-struct.md) for details. |

#### Behavior

* **Access Control**: Can only be called by the settlement contract (enforced by `onlySettlement` modifier)
* **Gas Management**: Each hook is called with its specified gas limit using the formula `forwardedGas = gasleft() * 63 / 64`
* **Revert Handling**: Hook failures do NOT cause the entire transaction to revert, protecting the settlement
* **Sequential Execution**: Hooks execute in array order
* **Gas Limit Verification**: If insufficient gas remains for a hook's gas limit, the function reverts by wasting all remaining gas

#### Gas Limit Notes

> [!NOTE]
>
> The trampoline attempts to forward exactly the specified gas limit to each hook, but may forward slightly less due to gas overhead between measurement and execution.

> [!WARNING]
>
> If a hook's gas limit exceeds available gas (accounting for the 63/64 forwarding rule), the transaction will revert by consuming all remaining gas. This is necessary for proper gas estimation with some node implementations.

#### Example

```solidity theme={null}
// Called by settlement contract during order execution
Hook[] memory hooks = new Hook[](2);

hooks[0] = Hook({
    target: 0x1234...,
    callData: abi.encodeWithSignature("beforeSettle()"),
    gasLimit: 50000
});

hooks[1] = Hook({
    target: 0x5678...,
    callData: abi.encodeWithSignature("afterSettle(uint256)", amount),
    gasLimit: 100000
});

trampoline.execute(hooks);
```

## Modifiers

### onlySettlement

```solidity theme={null}
modifier onlySettlement()
```

Ensures that `msg.sender` is the CoW Protocol settlement contract. Methods with this modifier are guaranteed to only be called as part of a CoW Protocol settlement.

#### Behavior

* Checks if `msg.sender == settlement`
* Reverts with `NotASettlement()` if the check fails
* Allows function execution to proceed if the check passes

#### Example

```solidity theme={null}
// This call succeeds only if made from settlement contract
trampoline.execute(hooks); // From settlement: OK
trampoline.execute(hooks); // From other address: reverts with NotASettlement()
```

## Security Features

### Unprivileged Execution

Hooks execute in the trampoline's context, not the settlement contract's context. This prevents hooks from accessing privileged settlement contract state or functionality.

### Revert Isolation

Hook reverts are caught and ignored, preventing a single malicious or badly configured hook from blocking an entire settlement batch.

### Gas Limit Enforcement

Each hook has a specified gas limit, preventing runaway execution from consuming excessive gas or causing out-of-gas errors for subsequent operations.

## Related

* [Hook Struct](https://docs.cow.bleu.builders/hooks-trampoline/api/hook-struct.md) — Structure specification for hooks
* [Errors](https://docs.cow.bleu.builders/hooks-trampoline/api/errors.md) — Error types and handling
* [Usage Guide](https://docs.cow.bleu.builders/hooks-trampoline/usage.md) — Guide to implementing hooks


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.