> For the complete documentation index, see [llms.txt](https://ringprotocol.gitbook.io/ring/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ringprotocol.gitbook.io/ring/docs/hook-contracts-guide.md).

# Hook Contracts Developer Guide

## Hook Contracts

Few Protocol provides specialized Uniswap V4 Hook contracts that enable seamless integration between Few Wrapped Tokens and Uniswap V4 pools. These hooks automatically handle token wrapping/unwrapping during trading operations.

### Overview

Hook contracts act as middleware between Uniswap V4 pools and Few Protocol's wrapped tokens, providing:

* **Automatic Token Wrapping**: Converts underlying tokens to Few Wrapped Tokens during liquidity provision
* **Seamless Trading**: Users can trade with underlying tokens while the pool operates with wrapped tokens
* **Gas Optimization**: Reduces transaction costs by batching operations
* **Enhanced Liquidity**: Enables deeper liquidity pools with wrapped token benefits

### Available Hook Contracts

#### FewTokenHook

**Purpose**: Universal hook for ERC20 tokens (USDC, DAI, CBBTC, etc.)

**Features**:

* Supports all standard ERC20 tokens except USDT
* 1:1 wrapping/unwrapping ratio
* Automatic approval management
* Compatible with most modern tokens

**Use Cases**:

* USDC ↔ fwUSDC pools
* DAI ↔ fwDAI pools
* CBBTC ↔ fwCBBTC pools
* Any standard ERC20 ↔ Few Wrapped Token pools

#### FewETHHook

**Purpose**: Specialized hook for ETH/WETH integration

**Features**:

* Native ETH support
* WETH compatibility
* Optimized for Ethereum's native currency
* Gas-efficient ETH handling

**Use Cases**:

* ETH ↔ fwWETH pools
* WETH ↔ fwWETH pools
* Native Ethereum trading pairs

#### FewUSDTHook

**Purpose**: Specialized hook for USDT integration

**Features**:

* SafeERC20 compatibility for USDT's non-standard approve function
* Handles USDT's unique implementation quirks
* Secure approval management

**Use Cases**:

* USDT ↔ fwUSDT pools
* Legacy token compatibility

### How Hook Contracts Work

#### 1. Pool Initialization

When a Uniswap V4 pool is created with a Hook contract:

```
Pool: Token A / Few Wrapped Token B (with Hook)
```

#### 2. Liquidity Provision

Users provide liquidity with underlying tokens:

```
User provides: Token A + Token B
Hook converts: Token A → Few Wrapped Token A, Token B → Few Wrapped Token B
Pool receives: Few Wrapped Token A + Few Wrapped Token B
```

#### 3. Trading Operations

Users trade with underlying tokens seamlessly:

```
User swaps: Token A → Token B
Hook converts: Token A → Few Wrapped Token A (input conversion)
Pool executes: Few Wrapped Token A → Few Wrapped Token B
Hook converts: Few Wrapped Token B → Token B (output conversion)
User receives: Token B
```

#### 4. Liquidity Removal

Users withdraw underlying tokens:

```
Pool returns: Few Wrapped Token A + Few Wrapped Token B
Hook converts: Few Wrapped Token A → Token A, Few Wrapped Token B → Token B
User receives: Token A + Token B
```

### Integration Benefits

#### For Traders

* **Familiar Interface**: Trade with standard tokens (USDC, ETH, etc.)
* **Enhanced Features**: Access Few Protocol benefits transparently
* **Lower Costs**: Optimized gas usage through hook automation
* **Better Rates**: Deeper liquidity from wrapped token pools

#### For Liquidity Providers

* **Dual Benefits**: Earn trading fees + Few Protocol rewards
* **Risk Management**: Maintain exposure to underlying assets
* **Simplified Operations**: Automatic wrapping/unwrapping
* **Capital Efficiency**: Single-sided liquidity provision support

#### For Developers

* **Easy Integration**: Standard Uniswap V4 interface
* **Flexible Architecture**: Support for various token types
* **Extensible Design**: Custom hooks for specific needs
* **Battle-tested Code**: Audited and production-ready

### Contract Addresses

#### [Mainnet Deployments](/ring/docs/hook-contracts.md)

### Technical Specifications

#### Hook Flags

All Few Protocol hooks implement the following Uniswap V4 flags:

* `BEFORE_SWAP_FLAG`: Pre-swap token conversion
* `BEFORE_ADD_LIQUIDITY_FLAG`: Pre-liquidity token wrapping
* `BEFORE_SWAP_RETURNS_DELTA_FLAG`: Delta handling for conversions
* `BEFORE_INITIALIZE_FLAG`: Pool initialization setup

#### Security Features

* **Address Validation**: Ensures correct token pairing
* **Overflow Protection**: SafeMath operations throughout
* **Reentrancy Guards**: Protection against reentrancy attacks
* **Access Controls**: Proper permission management

#### Gas Optimization

* **Batch Operations**: Multiple actions in single transaction
* **Efficient Storage**: Optimized state variable usage
* **Minimal External Calls**: Reduced cross-contract interactions
* **Assembly Optimizations**: Critical path optimizations

### Integration Guide

#### For Pool Creators

1. **Choose the Right Hook**: Select based on your token type
2. **Deploy Pool**: Use Uniswap V4 PoolManager with hook address
3. **Initialize**: Set initial price and liquidity
4. **Test**: Verify wrapping/unwrapping functionality

#### For Frontend Developers

1. **Standard Interface**: Use normal Uniswap V4 SDK calls
2. **Token Display**: Show underlying tokens to users
3. **Transaction Handling**: Let hooks manage conversions automatically
4. **Error Handling**: Implement proper error catching

#### Example Integration

```solidity
// Create pool with FewTokenHook
IPoolManager.PoolKey memory key = IPoolManager.PoolKey({
    currency0: Currency.wrap(USDC_ADDRESS),
    currency1: Currency.wrap(FW_USDC_ADDRESS), 
    fee: 3000,
    tickSpacing: 60,
    hooks: IHooks(FEW_TOKEN_HOOK_ADDRESS)
});

poolManager.initialize(key, SQRT_RATIO_1_1, ZERO_BYTES);
```

***

{% hint style="info" %}
**Note**: Hook contracts are immutable once deployed. Always verify contract addresses and test thoroughly on testnets before mainnet integration.
{% endhint %}

{% hint style="warning" %}
**Security**: Never send tokens directly to hook contract addresses. Always interact through Uniswap V4 PoolManager.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://ringprotocol.gitbook.io/ring/docs/hook-contracts-guide.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.