Uniswap v4 Hook Integration - AI Technical Reference

Critical Configuration Requirements

Hook Address Permission System

CRITICAL: Hook permissions are determined by deployed contract address bits, NOT by getHookPermissions() function.

Permission Mapping:

• BEFORE_SWAP_FLAG: Address must have bit 0 set (address ends in odd number)
• AFTER_SWAP_FLAG: Address must have bit 1 set
• BEFORE_SWAP_RETURNS_DELTA_FLAG: Address must have bit 2 set
• AFTER_SWAP_RETURNS_DELTA_FLAG: Address must have bit 3 set

Failure Mode: Hook compiles and deploys successfully but functions never execute
Root Cause: Address permission bits don't match required permissions
Detection: beforeSwap never called despite beforeSwap: true in code

Address Mining Requirements

Tool: HookMiner contract from v4-periphery
Time Cost: 30 seconds for simple permissions, 5+ minutes for complex combinations
Implementation:

uint160 flags = uint160(Hooks.BEFORE_SWAP_FLAG | Hooks.AFTER_SWAP_FLAG);
(address hookAddress, bytes32 salt) = HookMiner.find(
    CREATE2_DEPLOYER,
    flags,
    type(MyHook).creationCode,
    abi.encode(poolManager)
);

Delta Settlement System

Flash Accounting Critical Rules

System: All delta modifications must sum to zero by transaction end
Failure: CurrencyNotSettled revert if deltas don't balance
Settlement Required: Every delta your hook creates must be explicitly settled

Delta Direction Convention:

• Taking tokens: Return negative delta (-feeAmount)
• Giving tokens: Return positive delta (+rebateAmount)

Settlement Implementation:

// Hook takes 0.1% fee
int128 fee = int128(swapAmount * 10 / 10000);
hookDelta = BalanceDeltaLibrary.toBalanceDelta(-fee, 0);

// REQUIRED: Settle the delta
IERC20(token0).transfer(address(poolManager), uint256(fee));
poolManager.settle(Currency.wrap(address(token0)));

Common Failure Patterns

Transaction Reverts

Error	Root Cause	Fix
"Hook address not valid"	Address permission bits don't match hook requirements	Use HookMiner to find correct address
"CurrencyNotSettled"	Hook modifies deltas but doesn't settle them	Call settle() for taken tokens, take() for given tokens
"Hook delta exceeds swap amount"	Hook tries to take more than swap amount	Validate delta amounts against swap parameters
"Transaction reverted without reason"	SDK misconfiguration or missing approvals	Check testnet vs mainnet configs, verify token approvals

Function Execution Failures

Symptom: Hook functions not called despite correct permissions
Causes:

1. Function signature mismatch (missing calldata keywords)
2. Wrong return types
3. Missing BaseHook inheritance

Correct Function Signatures:

function beforeSwap(
    address sender,
    PoolKey calldata key,        // Must be calldata
    SwapParams calldata params,  // Must be calldata
    bytes calldata hookData      // Must be calldata
) external returns (bytes4, BeforeSwapDelta, uint24) {
    return (BaseHook.beforeSwap.selector, BeforeSwapDelta.wrap(0), 0);
}

Security Vulnerabilities

Access Control Requirements

CRITICAL: All hook callback functions must have onlyPoolManager modifier
Risk: Without access control, anyone can call hook functions directly and drain funds

// VULNERABLE
function afterSwap(...) external returns (...) {
    feeToken.transfer(msg.sender, collectedFees); // Anyone can call this
}

// SECURE
function afterSwap(...) external onlyPoolManager returns (...) {
    feeToken.transfer(owner, collectedFees); // Only PoolManager can call
}

Async Hook Risks

Risk Level: CRITICAL - Can steal all user funds
Attack: Malicious async hooks can take tokens instead of executing swaps
Mitigation: Only use async hooks from trusted sources, validate pool tokens

Token Compatibility Issues

Problem Tokens:

• USDT: No return value on transfer()
• Fee-on-transfer tokens: Balance changes don't match transfer amounts
• Rebasing tokens: Balances change automatically

Solution: Use OpenZeppelin's SafeERC20 for all token operations

Gas Optimization Critical Points

Loop Optimization

Failure Pattern: Unbounded loops cause "out of gas" on certain swaps

// BAD - Gas scales with array size
for (uint i = 0; i < authorizedUsers.length; i++) {
    require(validateUser(authorizedUsers[i]), "Invalid user");
}

// GOOD - Constant gas
require(isAuthorized[msg.sender], "Unauthorized");

External Call Management

Risk: Oracle calls can fail or consume excessive gas
Solution: Implement fallback patterns with cached values

uint256 price = cachedPrice;
if (block.timestamp > lastUpdate + 3600) {
    try priceOracle.getPrice(token) returns (uint256 newPrice) {
        price = newPrice;
        cachedPrice = newPrice;
        lastUpdate = block.timestamp;
    } catch {
        // Use stale price if oracle fails
    }
}

Production Deployment Requirements

Testing Prerequisites

1. Mainnet Fork Testing: Test with real token balances and current block state
2. Gas Usage Verification: Test with realistic large swap amounts (1000+ ETH)
3. Oracle Failure Testing: Mock external dependencies failures
4. Edge Case Coverage: Test extreme token amounts for overflow conditions

Monitoring Requirements

Critical Metrics:

• Hook execution success rate
• Gas usage per call type
• Delta settlement success rate
• External call failure rate

Monitoring Implementation:

event HookExecuted(string functionName, bool success, uint256 gasUsed);
event DeltaSettlementFailed(address token, int256 amount);
event ExternalCallFailed(address target, bytes data);

Emergency Response System

Circuit Breaker Pattern (Required for production):

bool public emergencyPause = false;
address public emergencyAdmin;

modifier whenNotPaused() {
    require(!emergencyPause, "Hook paused for emergency");
    _;
}

function emergencyPauseHook() external {
    require(msg.sender == emergencyAdmin, "Only emergency admin");
    emergencyPause = true;
    emit EmergencyPause(block.timestamp);
}

Resource Requirements

Development Time Investment

• Basic hook implementation: 2-3 days
• Security audit and testing: 1-2 weeks
• Production deployment and monitoring setup: 3-5 days
• Address mining for complex permissions: 5+ minutes per deployment

Expertise Requirements

• Essential: Solidity development, Uniswap v4 architecture understanding
• Critical: Gas optimization techniques, MEV protection strategies
• Required: Testing frameworks (Foundry), security audit practices

Infrastructure Dependencies

• Testing: Mainnet fork access (Infura/Alchemy)
• Deployment: CREATE2 deployer contract
• Monitoring: Transaction debugging tools (Tenderly)
• Security: Emergency response procedures

Decision Criteria for Implementation

When to Use Hooks

Suitable for:

• Custom fee structures
• MEV protection mechanisms
• Liquidity incentive programs
• Integration with external protocols

Avoid for:

• Simple token transfers (use standard DEX)
• High-frequency trading (gas costs too high)
• Experimental features without emergency stops

Alternative Considerations

Instead of Hooks:

• Simple swaps: Use Uniswap Universal Router
• Custom logic: Build separate contract that calls Uniswap
• Fee collection: Use pool fee mechanisms instead of hook deltas

Critical Warnings

Production Failures That Will Occur

1. Delta calculation overflow: Use safe math for large token amounts
2. External protocol dependency: All external calls will fail eventually
3. Permission mismatch after upgrades: Re-mine addresses after code changes
4. MEV exploitation: Hook modifications are visible and exploitable

Breaking Points

• Gas limit: Hooks hit 300k+ gas with complex logic
• Token compatibility: Non-standard ERC20 tokens break assumptions
• Oracle manipulation: Price feeds can be manipulated during low liquidity
• Sandwich attacks: Predictable hook behavior enables MEV exploitation

Support Quality Assessment

• Official documentation: Incomplete, missing production edge cases
• Community support: Variable quality, verify all advice
• Security audit availability: Limited auditors familiar with v4 hooks
• Emergency response: No official incident response procedures

Tool Requirements for Implementation

Essential Development Tools

• Foundry: Only testing framework that properly handles v4 state
• HookMiner: Required for address mining with correct permissions
• Cast CLI: Quick permission verification and debugging
• BaseHook contract: Always inherit from v4-periphery BaseHook

Security Analysis Tools

• Tenderly: Best transaction debugging for failed hooks
• OpenZeppelin Defender: Contract monitoring and alerting
• CertiK/Hacken audit guides: Security checklist for hooks

Production Monitoring

• Gas tracking: Monitor hook execution costs
• Delta settlement monitoring: Track settlement success rates
• External dependency monitoring: Alert on oracle/protocol failures
• Circuit breaker implementation: Emergency stop functionality

This technical reference provides the operational intelligence needed for successful Uniswap v4 hook implementation while highlighting critical failure modes and their solutions.