> 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
```