> For the complete documentation index, see [llms.txt](https://docs.turbine.exchange/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.turbine.exchange/reference/contracts/solidity-documentation.md).

# Solidity Documentation

Turbine protocol consists of an offchain backend and a set of smart contracts.

There are two main groups of contracts:

* **Order Settlement** (`settler`): The main contract - `TurbineSettler` - is responsible for settling orders. Turbine backend submits transactions directly to this contract.
* **Liquidity Provision** (`univ4-hook`): Liquidity provision is implemented by a Uniswap V4 Hook - `TurbineHook` - and a Router - `TurbineLiquidityRouter`.

## Overview

### TurbineHook

* Implements a Uniswap V4 Hook interface to intercept and customize pool actions (e.g., swaps, liquidity additions).
* Uses an internal ERC20 token to represent liquidity shares (similar to Uniswap V2 LP tokens).
* Tracks the reserves internally (like Uniswap V2’s `reserves0` and `reserves1`) to issue or burn liquidity tokens accordingly.
* Restricts direct pool operations so that only the designated router can invoke critical functions like minting, burning, or swapping.

### Router

* Orchestrates liquidity addition (`addLiquidity`), removal (`removeLiquidity`), and swaps (`swapExactTokens`) by interacting with both TurbineHook and the Uniswap V4 PoolManager.
* Implements the `IUnlockCallback` interface, which is used by the Uniswap V4 `PoolManager` during certain operations.
* Allows for a simplified user interface, controlling the flow of tokens during swaps and liquidity changes.

### Swap flow

1. `TurbineSettler` calls `LiquidityRouter`.
2. `LiquidityRouter` unlocks `PoolManager` to begin an operation. `PoolManager` invokes `LiquidityRouter.unlockCallback(...)`.
3. `LiquidityRouter` calls `PoolManager.swap(...)` to perform the swap.
4. `PoolManager` delegates the accounting to `TurbineHook` via `beforeSwap(...)` and `afterSwap(...)` functions.
5. `LiquidityRouter` transfers tokens to and from `PoolManager` and `TurbineSettler`.

## Development with Foundry

### Installation

```shell
forge install
git submodule update --init --recursive --remote
```

### Build

```shell
$ forge build
```

or to also include dev contracts used by Rust, use the makefile:

```shell
$ make build
```

### Test

```shell
$ forge test -vvv
```

### Fuzz & Invariant Tests

Fuzz and invariant tests live in `test/fuzz/` and run in CI with default settings (256 fuzz runs, 64 invariant runs). To run locally with more iterations:

```shell
# All fuzz + invariant tests
forge test --match-path "*/fuzz/*" -vv

# With more iterations
forge test --match-path "*/fuzz/*" --fuzz-runs 5000

# Only stateful invariant tests (requires RPC_URL for fork)
forge test --match-path "*/fuzz/invariant/*" -vv
```

### Format

```shell
$ forge fmt
```

### Deploy

See the specific page in the documentation for more information on how to deploy the contracts.


---

# 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:

```
GET https://docs.turbine.exchange/reference/contracts/solidity-documentation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.