VolumeBasedFeeHook Hook

The VolumeBasedFeeHook hook implements dynamic fees based on swap volume. The hook adjusts fees in a tiered structure based on swap amounts:

• Below minAmount: Uses defaultFee
• Between minAmount and maxAmount: Uses linear interpolation between feeAtMinAmount and feeAtMaxAmount
• Above maxAmount: Uses feeAtMaxAmount

Fee relationships must maintain:

• feeAtMinAmount < defaultFee
• feeAtMaxAmount < feeAtMinAmount
• minAmount < maxAmount

Getting Started

Prerequisites

• Foundry (Forge)
• Anvil (for local development)

Installation

Clone the repository and install dependencies:

forge install

VolumeBasedFeeHook Hook Details

• Source: src/VolumeBasedFeeHook.sol
• Interface: src/interfaces/IVolumeBasedFeeHook.sol

The VolumeBasedFeeHook hook is designed to be deployed with a set of parameters encapsulated in the IVolumeBasedFeeHook.VolumeBasedFeeHookParams struct.

Example Parameters

IVolumeBasedFeeHook.VolumeBasedFeeHookParams memory params = IVolumeBasedFeeHook.VolumeBasedFeeHookParams({
    defaultFee: 3000,      // 0.3%
    feeAtMinAmount0: 2700, // 0.27%
    feeAtMaxAmount0: 2400, // 0.24%
    feeAtMinAmount1: 2100, // 0.21%
    feeAtMaxAmount1: 2000, // 0.20%
    minAmount0: 1e18,      // 1 token0
    maxAmount0: 10e18,     // 10 token0
    minAmount1: 1e18,      // 1 token1
    maxAmount1: 10e18      // 10 token1
});

Interacting with the VolumeBasedFeeHook Hook

Several scripts are provided in the script/ folder to deploy and interact with the VolumeBasedFeeHook hook. These include:

• Deployment via CREATE2: VolumeBasedFeeHook.s.sol
• Local lifecycle testing (pool initialization, liquidity provision, swaps): Anvil.s.sol

Deploying using Forge Scripts

Deploying the VolumeBasedFeeHook Hook

Use the following command to deploy the VolumeBasedFeeHook hook (via CREATE2) on your local network:

forge script script/VolumeBasedFeeHook.s.sol:VolumeBasedFeeHookScript --rpc-url http://localhost:8545 --private-key <YOUR_PRIVATE_KEY> --broadcast

This script:

• Mines the correct salt (using HookMiner) for the given parameters and flags
• Deploys the VolumeBasedFeeHook hook with the provided parameters
• Logs the deployed hook address

Full Lifecycle Testing on Anvil

You can also run a full deployment and test lifecycle (pool creation, liquidity addition, and swapping) using:

forge script script/Anvil.s.sol:VolumeBasedFeeHookScript --rpc-url http://localhost:8545 --private-key <YOUR_PRIVATE_KEY> --broadcast

The Anvil.s.sol script:

• Deploys a pool manager and the VolumeBasedFeeHook hook
• Sets up additional helper contracts (like the Position Manager and Routers)
• Initializes a pool using the VolumeBasedFeeHook hook
• Adds liquidity and performs a test swap for full-end-to-end verification

Constants & Config Files

Two important files help configure and bootstrap the system:

Constants File

script/base/Constants.sol
The Constants file contains shared, immutable parameters used across scripts. These include:

• Deployer Addresses:
  The address from which CREATE2 deployments are performed (e.g., CREATE2_DEPLOYER).

• Pool Manager & Other Contract Addresses:
  Pre-set addresses for key contracts such as the Pool Manager, Position Manager, and the Permit2 contract, which help in setting up the system on a local Anvil network.

This file centralizes addresses to keep scripts consistent and to easily change deployment configuration if needed.

Config File

script/base/Config.sol
The Config file (if present) is used to configure and fine-tune deployment parameters for different environments. It may include:

• Network-specific configurations
• Pool fee settings and tick spacing
• Default token amounts for liquidity, price parameters, and more

Using these files helps in keeping the deployment scripts clean—by abstracting environment-specific configuration details away from the logic in the scripts themselves.

Debugging & Troubleshooting

Common Issues

1. Hook Deployment Failures:

   • Verify that the deployment flags passed to HookMiner.find match the ones returned by getHookCalls() in your hook.
   • Ensure that the salt mining logic uses the same deployer address (in scripts, this should be the CREATE2 deployer at 0x4e59b44847b379578588920cA78FbF26c0B4956C).

2. Permission Denied / SSH Key Issues:

   • If you encounter Github SSH errors, ensure your SSH keys are correctly added to your agent. Refer to GitHub’s SSH setup guide.

3. Incorrect Fee or Parameter Issues:

   • Ensure that the fee parameters follow the valid relationships:
     • feeAtMinAmount < defaultFee
     • feeAtMaxAmount < feeAtMinAmount
     • minAmount < maxAmount
   • You can add extra debugging logs within your hook to monitor fee calculations if needed.

Additional Debugging Tips

• Use console.log statements in your script to output key variable values.
• Run your tests on Anvil locally and inspect the transaction logs via Foundry’s output.
• Check the v4-core and v4-periphery repositories for more detailed implementation examples.