Interface Documentation

This repository contains the Move interface definitions for the The Ferra DAMM (Dynamic Automated Market Maker )protocol. These interfaces provide type definitions and function signatures without imp

Info

Contract Address: 0x66fb6a132c415278c32ab52ecdc2bd73b08b649e396841f48f6f9cccd01b6bbb

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