JAMM System Architecture

Architecture Overview

JAMM DEX uses a layered, modular architecture to ensure scalability, security, and maintainability. The system consists of a core contract layer, a library layer, and an interface layer.

Core Contracts

JAMMFactory

Responsibilities: Creates and manages trading pairs.

• Maintains a registry of all trading pairs.

• Deploys pair contracts deterministically using CREATE2.

• Manages protocol fee settings.

• Handles the registration for the referral system.

Key Functions:

// Creates a new trading pair for tokenA and tokenB with a specific fee
function createPair(address tokenA, address tokenB, uint24 fee) external returns (address pair);

// Retrieves the address of an existing pair
function getPair(address tokenA, address tokenB, uint24 fee) external view returns (address pair);

// Sets a referrer for the message sender
function setReferrer(address _referrer) external;

JAMMPair

Responsibilities: Implements the specific liquidity pool.

• Maintains reserves of two tokens.

• Executes token swap logic.

• Manages adding and removing liquidity.

• Calculates and allocates trading fees.

Key Functions:

// Mints LP tokens
function mint(address to) external returns (uint liquidity);

// Burns LP tokens
function burn(address to) external returns (uint amount0, uint amount1);

// Swaps tokens
function swap(uint amount0Out, uint amount1Out, address to, bytes calldata data, address _referrer) external;

// Returns the token reserves and the last block timestamp
function getReserves() external view returns (uint112 reserve0, uint112 reserve1, uint32 blockTimestampLast);

JAMMRouter

Responsibilities: Provides a user-friendly interface for trading.

• Offers high-level functions for trades.

• Handles multi-hop swap paths.

• Manages deadline checks.

• Supports automatic conversion of ETH/WJU.

Key Functions:

// Swaps an exact amount of input tokens for as many output tokens as possible
function swapExactTokensForTokens(uint amountIn, uint amountOutMin, address[] calldata path, uint24[] calldata fees, address to, address referrer, uint deadline) external returns (uint[] memory amounts);

// Adds liquidity to a pair
function addLiquidity(address tokenA, address tokenB, uint24 fee, uint amountADesired, uint amountBDesired, uint amountAMin, uint amountBMin, address to, uint deadline) external returns (uint amountA, uint amountB, uint liquidity);

// Removes liquidity from a pair
function removeLiquidity(address tokenA, address tokenB, uint24 fee, uint liquidity, uint amountAMin, uint amountBMin, address to, uint deadline) external returns (uint amountA, uint amountB);

JAMMERC20

Responsibilities: Standard implementation of LP tokens.

• Implements the ERC-20 standard.

• Supports the EIP-2612 permit function.

• Manages the minting and burning of LP tokens.

Key Functions:

// Approves spending tokens via a signature
function permit(address owner, address spender, uint value, uint deadline, uint8 v, bytes32 r, bytes32 s) external;

WJU

Responsibilities: Implementation of the wrapped JU token.

• Provides wrapping and unwrapping of the JU token.

• Fully compatible with the ERC-20 standard.

• Supports receiving ETH directly.

Key Functions:

// Wraps JU into WJU
function deposit() public payable;

// Unwraps WJU back to JU
function withdraw(uint amount) public;

Libraries

JAMMLibrary

Provides core mathematical calculations and utility functions:

• sortTokens(): Sorts token addresses.

• pairFor(): Calculates the pair address.

• getReserves(): Fetches reserves.

• getAmountOut(), getAmountIn(): Calculates swap amounts.

• getAmountsOut(), getAmountsIn(): Calculates amounts for multi-hop swaps.

Math

Provides safe mathematical operations:

• sqrt(): Square root calculation (using Babylonian method).

• min(): Finds the minimum of two numbers.

• Uses Solidity >=0.8.0 for built-in overflow/underflow protection.

TransferHelper

Provides safe token transfer functions:

• safeTransfer(): Safe token transfer.

• safeTransferFrom(): Safe token transfer from another address.

• safeTransferETH(): Safe ETH transfer.

• safeApprove(): Safe token approval.

UQ112x112

Provides support for fixed-point number arithmetic:

• Used for price accumulation.

• Enables high-precision math.

Data Flow Architecture

Trading Flow

User → JAMMRouter → JAMMPair → Token Contracts
  ↓        ↓         ↓
Check Params → Calc Path → Execute Swap → Update Reserves

Liquidity Management Flow

User → JAMMRouter → JAMMPair → JAMMERC20
  ↓        ↓         ↓         ↓
Add Liquidity → Transfer Tokens → Mint LP → Issue LP Tokens

Security Architecture

Re-entrancy Guard

All critical functions are protected by a re-entrancy lock:

modifier lock() {
    require(unlocked == 1, "JAMM: LOCKED");
    unlocked = 0;
    _;
    unlocked = 1;
}

Mathematical Safety

• Uses Solidity ^0.8.21 for built-in overflow and underflow protection.

• The Math library provides a safe sqrt function.

• The JAMMLibrary includes checks for zero reserves and amounts.

Access Control

• Key functions in JAMMFactory can only be called by feeToSetter.

• The initialize function in JAMMPair can only be called by the factory.

• A referrer can only be set once per user.

Fee Architecture

Fee Tiers

uint24 public constant FEE_0_5_PERCENT = 50;   // 0.5%
uint24 public constant FEE_1_PERCENT = 100;    // 1%
uint24 public constant FEE_2_PERCENT = 200;    // 2%
uint24 public constant FEE_3_PERCENT = 300;    // 3%

Fee Distribution

• Trading Fees: A portion of the swap fee (fee/50000 or fee/100000) is sent to a designated feeTo address. If a referrer is active, the fee is split between the protocol and the referrer.

• Protocol Fees: A portion of the liquidity provider fees can be minted as new LP tokens and sent to a mintTo address, calculated based on the growth of the k value.

Address Generation

CREATE2 Deterministic Deployment

Pair addresses are generated using CREATE2, ensuring predictability:

// salt is calculated from the sorted token addresses and the fee
bytes32 salt = keccak256(abi.encodePacked(token0, token1, fee));
// create2 opcode is used to deploy the pair
pair := create2(0, add(bytecode, 32), mload(bytecode), salt)

Init Code Hash

// The hash of the JAMMPair creation code, used in pairFor calculation
bytes32 public constant INIT_CODE_PAIR_HASH = keccak256(type(JAMMPair).creationCode);

Current Value: 0x2e599419feff8382bdfc47abf847537b06e96b0525db3802b2a9fb0bfe068ed8

Event System

Core Events

• PairCreated(address indexed token0, address indexed token1, uint24 fee, address pair, uint)

• Swap(address indexed sender, uint amount0In, uint amount1In, uint amount0Out, uint amount1Out, address indexed to)

• Mint(address indexed sender, uint amount0, uint amount1)

• Burn(address indexed sender, uint amount0, uint amount1, address indexed to)

• Sync(uint112 reserve0, uint112 reserve1)

• Fee(address indexed sender, address indexed referrer, address token, uint amount)

• Referrer(address indexed sender, address indexed referrer)

These events provide a complete on-chain data trail for front-end applications and analytics tools.