Inclusive Layer

Appearance

EVM AMM Smart Contracts ​

This document outlines the external functions available for users to interact with this modified Uniswap V3 Core implementation for swapping and liquidity management.

Entry Points Overview ​

Users interact with two main contracts:

  • SwapRouter: For executing token swaps
  • NonfungiblePositionManager: For liquidity provision and management

SwapRouter Functions ​

Exact Input Swaps ​

exactInputSingle(ExactInputSingleParams params) ​

Execute a swap with exact input amount for a single pool.

exactInput(ExactInputParams params) ​

Execute a multi-hop swap with exact input amount.

Exact Output Swaps ​

exactOutputSingle(ExactOutputSingleParams params) ​

Execute a swap with exact output amount for a single pool.

exactOutput(ExactOutputParams params) ​

Execute a multi-hop swap with exact output amount.

NonfungiblePositionManager Functions ​

Liquidity Management ​

mint(MintParams params) ​

Create a new liquidity position and mint an NFT representing it.

increaseLiquidity(IncreaseLiquidityParams params) ​

Add liquidity to an existing position.

decreaseLiquidity(DecreaseLiquidityParams params) ​

Remove liquidity from an existing position.

collect(CollectParams params) ​

Collect accumulated fees from a position.

burn(uint256 tokenId) ​

Burn an NFT position (must have zero liquidity and fees).

Pool Creation (Restricted) ​

createAndInitializePoolIfNecessaryWithParams(CreatePoolParams params) ​

Create and initialize a new pool (only accessible by pool manager).

Key Differences from Standard Uniswap V3 ​

1. Exclusive Trading Periods (ETP) ​

Purpose: Provides Caishen Wallet users with exclusive access to newly launched tokens before public trading begins.

Impact: During exclusive trading periods, only Caishen Wallet users and authorized market makers can swap.

SwapRouter Changes:

  • All swap functions check _checkExclusiveTrading() before execution
  • Enforces exclusive trading period restrictions based on pool configuration
  • Only vault address (representing Caishen Wallet users) and whitelisted market makers can trade during exclusive periods
  • Guarantees efficient trading experience for early adopters before public market access

2. Market Maker Whitelist System ​

SwapRouter Owner Functions:

  • addWhitelistedMarketMaker(address pool, address marketMaker)
  • removeWhitelistedMarketMaker(address pool, address marketMaker)
  • transferOwnership(address newOwner)

Access: Only SwapRouter owner can manage market maker whitelist per pool.

3. Project Manager Privileges and Liquidity Locking ​

Liquidity Protection: Project Manager liquidity is automatically locked during Exclusive Trading Period (ETP) and Early Launch Lock (ELL) periods to guarantee efficient trading.

NonfungiblePositionManager Changes:

  • decreaseLiquidity() has special logic for project managers with time-based restrictions
  • Project managers cannot withdraw liquidity during ETP and ELL periods, ensuring stable trading conditions
  • Project managers can call burnByProjectManager() instead of regular burn() on pools (after lock periods)
  • Locked liquidity guarantees sufficient depth for Caishen Wallet users during exclusive access windows
  • Provides additional control over liquidity management during launch phases while protecting trader experience

4. Pool Manager Controlled Pool Creation ​

Restriction: Pool creation via periphery is restricted to designated pool manager.

Standard Uniswap V3: Anyone can create pools via position manager This Implementation: Only poolManager address can call createAndInitializePoolIfNecessaryWithParams()

5. Launch Parameter Requirements ​

Pool Creation Changes:

  • Pools must be created with PoolLaunchParameters
  • Includes launch type configuration (Fair/Curated)
  • Defines exclusive trading periods and access controls
  • Requires oracle setup before operations

Standard Uniswap V3: Simple pool creation with just token pair and fee This Implementation: Complex launch configuration with access controls and timing restrictions

Access Control Summary ​

SwapRouter Owner ​

Powers:

  • Add/remove market makers from whitelist per pool
  • Transfer ownership
  • Manage exclusive trading access

Pool Manager ​

Powers:

  • Create new pools via NonfungiblePositionManager
  • Set launch parameters and configurations

Project Manager (per pool) ​

Powers:

  • Special liquidity burning privileges via burnByProjectManager()
  • Enhanced control during token launch phases

Whitelisted Market Makers (per pool) ​

Powers:

  • Trade during exclusive trading periods
  • Provide liquidity when regular users cannot

Vault Address (Caishen Wallet) ​

Powers:

  • Represents Caishen Wallet users for exclusive trading access
  • Trade during exclusive trading periods across all pools
  • Receives pool creation notifications
  • Enables seamless early access to new token launches

Error Codes ​

  • UA: Unauthorized access
  • ONS: Oracle Not Set - oracle must be configured before pool operations
  • NP: Not Periphery - restricted operation attempted
  • NPM: Not Pool Manager - pool creation attempted by non-manager
  • SWAP_ROUTER: NOT_AUTHORIZED_FOR_EXCLUSIVE_TRADING: Swap attempted during exclusive period by unauthorized user

Usage Notes ​

  1. Exclusive Trading Checks: All swaps are subject to exclusive trading period validation for Caishen Wallet user protection
  2. Oracle Requirements: Pools must have oracles configured before operations can begin
  3. NFT Positions: All liquidity positions are represented as ERC-721 NFTs
  4. Liquidity Locking: Project Manager liquidity is automatically locked during ETP and ELL periods to ensure trading stability
  5. Caishen Wallet Access: Vault address provides seamless exclusive access for Caishen Wallet users during launch windows
  6. Launch Phase Control: Pools can restrict trading to specific addresses during launch phases to optimize user experience

Struct and Parameter Definitions ​

SwapRouter Parameters ​

ExactInputSingleParams ​

solidity
struct ExactInputSingleParams {
    address tokenIn;
    address tokenOut;
    uint24 fee;
    address recipient;
    uint256 deadline;
    uint256 amountIn;
    uint256 amountOutMinimum;
    uint160 sqrtPriceLimitX96;
}

ExactInputParams ​

solidity
struct ExactInputParams {
    bytes path;
    address recipient;
    uint256 deadline;
    uint256 amountIn;
    uint256 amountOutMinimum;
}

ExactOutputSingleParams ​

solidity
struct ExactOutputSingleParams {
    address tokenIn;
    address tokenOut;
    uint24 fee;
    address recipient;
    uint256 deadline;
    uint256 amountOut;
    uint256 amountInMaximum;
    uint160 sqrtPriceLimitX96;
}

ExactOutputParams ​

solidity
struct ExactOutputParams {
    bytes path;
    address recipient;
    uint256 deadline;
    uint256 amountOut;
    uint256 amountInMaximum;
}

NonfungiblePositionManager Parameters ​

MintParams ​

solidity
struct MintParams {
    address token0;
    address token1;
    uint24 fee;
    int24 tickLower;
    int24 tickUpper;
    uint256 amount0Desired;
    uint256 amount1Desired;
    uint256 amount0Min;
    uint256 amount1Min;
    address recipient;
    uint256 deadline;
}

IncreaseLiquidityParams ​

solidity
struct IncreaseLiquidityParams {
    uint256 tokenId;
    uint256 amount0Desired;
    uint256 amount1Desired;
    uint256 amount0Min;
    uint256 amount1Min;
    uint256 deadline;
}

DecreaseLiquidityParams ​

solidity
struct DecreaseLiquidityParams {
    uint256 tokenId;
    uint128 liquidity;
    uint256 amount0Min;
    uint256 amount1Min;
    uint256 deadline;
}

CollectParams ​

solidity
struct CollectParams {
    uint256 tokenId;
    address recipient;
    uint128 amount0Max;
    uint128 amount1Max;
}

CreatePoolParams ​

solidity
struct CreatePoolParams {
    address token0;
    address token1;
    uint24 fee;
    uint160 sqrtPriceX96;
    PoolLaunchParameters launchParams;
}