> For the complete documentation index, see [llms.txt](https://docs.ferra.ag/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ferra.ag/integration/damm/smart-contract/interface-documentation.md).

# Interface Documentation

### Info

**Contract Address**: [0x6615ce71ab4f4a9119cc612c04a9daf77206e23201ec5efedd6bf873b2a16fd2](https://suivision.xyz/package/0x6615ce71ab4f4a9119cc612c04a9daf77206e23201ec5efedd6bf873b2a16fd2)

**Github**: <https://github.com/Ferra-Labs/damm-interface>

### Overview

The Ferra DAMM (Dynamic Automated Market Maker) interface consists of four main modules:

1. `factory.move` - Factory interface for creating and managing liquidity pools
2. `pool.move` - Pool management interface (core trading, swap operations, and liquidity management)
3. `position.move` - Position management interface (user position tracking, fee collection, and liquidity provision)
4. `fee_helper.move` / `pair_parameter_helper.move` - Fee calculation engine (fee scheduler, dynamic fee, fee validation)

### Key Differences from Standard CLMM

Ferra DAMM introduces several advanced features:

#### 1. Dynamic Fee System

* **Base Fee Scheduler**: Time-based fee reduction from cliff fee to base rate
* **Volatility-Based Dynamic Fee**: Automatic fee adjustment based on market volatility
* **Configurable Fee Collection Mode**: Collect fees on input, output, or quote token

#### 2. Fee Scheduler Modes

* **Linear Mode**: Fee decreases linearly over time periods
* **Exponential Mode**: Fee decreases exponentially with decay factor

#### 3. Pool Launch Features

* **Activation Timestamp**: Pools can be scheduled for future activation
* **Whitelist System**: Pre-launch access for whitelisted addresses
* **Quote Token Configuration**: Specify which token is the quote for fee collection

### Module Overview

| Module          | Description                                   |
| --------------- | --------------------------------------------- |
| Factory Module  | Pool creation and registry management         |
| Pool Module     | Core trading, swaps, and liquidity operations |
| Position Module | Position NFT management and fee collection    |
| Rewarder Module | Liquidity mining rewards distribution         |

### Architecture Diagram

```
┌─────────────────────────────────────────────────────────────┐
│                      GlobalConfig                           │
│  (Fee Tiers, Fee Schedulers, Dynamic Fee Params, ACL)       │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                        Factory                              │
│              (Pool Registry, Pool Creation)                 │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                          Pool                               │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │TickManager  │  │PositionMng  │  │   RewarderManager   │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
│  ┌─────────────────────────────────────────────────────┐    │
│  │              PairParameters                         │    │
│  │  (Fee Scheduler + Dynamic Fee + Price State)        │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    Position NFT                             │
│          (Transferable, Lockable, Fee Earning)              │
└─────────────────────────────────────────────────────────────┘
```

### Fee Calculation

The total fee rate in DAMM is calculated as:

```
total_fee = base_fee + variable_fee

where:
- base_fee = scheduled_fee (from fee scheduler) OR static_fee_rate
- variable_fee = volatility_based_fee (from dynamic fee system)
```

#### Fee Scheduler Formula

**Linear Mode:**

```
current_fee = cliff_fee - (periods_elapsed × reduction_per_period)
```

**Exponential Mode:**

```
current_fee = cliff_fee × (decay_factor ^ periods_elapsed)
```

#### Dynamic Fee Formula

```
variable_fee = (volatility_accumulator × variable_fee_control) / PRECISION
```


---

# 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://docs.ferra.ag/integration/damm/smart-contract/interface-documentation.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.