Enforce ACE policies on CCIP token transfers using Hardhat

1. Install Node.js and npm:

   • Make sure you have Node.js v22.10.0 or above installed. If not, install Node.js v22.10.0 using their documentation.
   • npm is bundled with Node.js. If npm is unavailable, reinstall or update Node.js.

2. Install/Update Chainlink ccip-cli:

3. Clone the repository and navigate to the project directory:

CCIP 2.0 template

Clone the CCIP 2.0 Hardhat template for a smoother setup.

→

4. Create a .env file by copying the .env.example file, and fill in the required values:

This tutorial uses a single wallet for every deployment, configuration update, and test transfer: the wallet stored in KEYSTORE_NAME.

5. To make sure your terminal has access to these variables, run the following command:

6. Build the project:

7. Create an encrypted Hardhat keystore, if you haven't already:

This tutorial assumes you have already deployed tokens and token pools and configured a working lane between Ethereum Sepolia and Arbitrum Sepolia. If not, complete one of the registration tutorials first:

• Burn & Mint (Hardhat)
• Lock & Mint (Hardhat)

Export the addresses for both chains:

Use two different recipient addresses. The destination policy will deny only DENIED_RECEIVER; you will use UNRESTRICTED_RECEIVER to confirm that transfers to other recipients still succeed.

You also need a Policy Engine on each chain. Create a policy engine, include Ethereum Sepolia and Arbitrum Sepolia, wait until the engine is Active, and copy its onchain address for each chain.

Deploy an AdvancedPoolHooks contract on each chain, then attach it to that chain's token pool. The allowlist stays empty in this tutorial: policy enforcement comes from ACE, not the allowlist. Pass the engine address at deploy time so the hooks connect to it in the same transaction: the constructor calls attach() on the engine, which starts ACE target detection.

deployAdvancedPoolHooks.ts

View the hooks deployment task on GitHub.

→

1. Deploy hooks on Ethereum Sepolia (source chain):

Export the source hooks address:

2. Deploy hooks on Arbitrum Sepolia (destination chain):

Export the destination hooks address:

3. Attach the source hooks to the source pool:

4. Attach the destination hooks to the destination pool:

If you passed --policyengine when deploying the hooks, they are already connected to the engine and ACE target detection has started. Skip the commands below and verify the connections with the read task. To connect hooks deployed without an engine, or to point them at a different engine, use the setPolicyEngine task.

setPolicyEngine.ts

View the policy engine task on GitHub.

→

1. Set the engine on the source hooks (Ethereum Sepolia):

Your output should look something like this:

2. Set the engine on the destination hooks (Arbitrum Sepolia):

3. Verify both connections with the read task:

Expected output for each chain:

The hook is now attached to the engine onchain. Complete the Platform-side configuration once per engine by following Protect CCIP Token Pools with ACE. This tutorial does not repeat those steps; it links the exact section for each task:

1. Verify the detected targets: each hooks address appears as a detected target under its engine. Assign the built-in CCIP-AdvancedPoolHooks contract type to each target. See Verify the detected target.
2. Create a policy instance on each chain: use the reject policy type. On the source engine, configure the instance's denylist with the address you will send from. On the destination engine, configure the instance's denylist with $DENIED_RECEIVER. See Create a policy instance.
3. Protect the hook functions: on the source target, protect preflightCheck and map the policy parameter Account (address) to the extractor output from. On the destination target, protect postflightCheck and map Account (address) to to. Read Restrict source senders first: the payload sender is the token pool, not the user, so the from output is what evaluates the transfer sender. See Protect a hook function.

Send a transfer from the address on the source denylist. The source preflightCheck runs before the token pool locks or burns tokens, so the source transaction reverts and the transfer never starts.

Expected result: the send transaction reverts. The Policy Engine returns PolicyRunRejected; its reject reason identifies the underlying policy rejection, and the hook call propagates that revert.

If this step does not fail as expected, check:

• The source hooks point at the engine (getPolicyEngine shows the engine address).
• The source target uses the CCIP-AdvancedPoolHooks contract type.
• The protection maps Account (address) to the from output on preflightCheck.
• The denylisted address is the one sending the transfer.

Remove the sending address from the source policy's denylist (see Update policy configuration). Wait for the configuration transaction to confirm on Ethereum Sepolia, then send the same transfer again. With no policy rejecting it, the transfer executes end to end.

Expected output (example):

This confirms the lane and both hooks work when no policy rejects the transfer.

Send a transfer whose recipient is on the destination denylist. The source preflightCheck passes (the sender is not denied), the message travels to Arbitrum Sepolia, and the destination postflightCheck rejects before the token pool releases or mints tokens. The tokens remain unreleased, and the message stays unexecuted.

The send transaction succeeds on Sepolia. On Arbitrum Sepolia, execution fails: the CCIP Explorer shows the message in a failure state with the rejecting policy in the error data.

Resolve the rejection condition, then complete the message through manual execution.

1. Remove $DENIED_RECEIVER from the destination policy's denylist (see Update policy configuration). Wait for the configuration transaction to confirm on Arbitrum Sepolia before continuing. The next evaluation of postflightCheck passes.

2. Confirm the message is ready for manual execution:

Use the bare 0x... message ID (or the source transaction hash) as the argument, not the full CCIP Explorer URL. The status shows the failure state and readyForManualExecution.

3. Manually execute the message on Arbitrum Sepolia:

Manual execution is a destination-chain transaction: the wallet needs Arbitrum Sepolia ETH for gas. After the transaction confirms, the recipient receives the tokens and the message status becomes Success.

For the full recovery flow, including gas overrides and diagnosing other failure causes, read CCIP Manual Execution.