Skip to content
RandyPenPublic

Latest commit

 

History

79 Commits

Folders and files

Repository files navigation

CDPM - Cetus DLMM Position Manager

Sui Mainnet

Package Address Use
CDPM v3 0xfd1832dffed42597f3237df3c43a1c88208ce6a65d8af7fc85c6df69229dcaae Move call targets
Original CDPM package 0x612dfd45a2e350995d492a59b595e64ec07a2253912f9eb22c2fd5947c6135d6 Object and event type filters

CDPM v3 was deployed on November 19, 2026 under the dependency-only upgrade policy (192). Mainnet upgrade transaction · Publication metadata

Find the shared object IDs, capability IDs, and dependency package addresses in the mainnet constants reference.

Overview

CDPM (Cetus DLMM Position Manager) is a Sui Move smart contract that enables proxy liquidity management on Cetus DLMM (Discrete Liquidity Market Maker). The contract allows users to manage their liquidity positions directly or delegate management to the protocol or custom AI agents, with the protocol collecting fees on managed operations.

Key Features

1. User Self-Management

  • Deposit & Create Positions: Deposit liquidity and create new positions
  • Add/Remove Liquidity: Manage existing positions
  • Collect Fees/Rewards: Collect accumulated fees and rewards
  • Balance Management: Deposit to and withdraw from position balance
  • Agent Management: Authorize/deauthorize agent addresses

2. Protocol-Managed Operations

  • Automated Liquidity Management: Protocol can add/remove liquidity on behalf of users
  • Fee Collection with Protocol Cut: Protocol collects fees, taking a percentage (default: 20%)
  • Balance Transfers: Move fees from fee bag to balance for withdrawal
  • Access Control: Admin-managed allow list for protocol addresses

3. AI Agent Delegation

  • Custom Agent Authorization: Users can authorize custom AI agents
  • Agent Operations: Agents can perform liquidity management operations
  • Permission Control: Agents have limited permissions (cannot withdraw funds)

Building an LP agent? RandyPen/lp-agent is an open-source reference implementation of an autonomous liquidity-provider agent built against this contract's agent-delegation surface (TypeScript/Bun agent + Python forecasting pipeline). Third-party developers can fork it as a starting point — bring your own strategies, pool profiles, and prediction models, then deploy independently.

Architecture

Core Data Structures

PositionManager

Central structure representing a user's liquidity position:

public struct PositionManager has key {
    id: UID,
    owner: address,             // Position owner
    agents: VecSet<address>,    // Authorized agents
    pool_id: ID,                // Cetus DLMM pool bound to this manager
    position: Option<Position>, // Cetus DLMM position, when open
    balance: Bag,               // Token balances (String -> Balance<T>)
    fee: Bag,                   // Accumulated fees (String -> Balance<T>)
    lending: Bag,               // Scallop and Kai SAV vault entries
}

public struct ScallopVault<phantom T> has store {
    scoin: Balance<MarketCoin<T>>,   // Scallop sCoin (type-pinned to MarketCoin<T>)
    principal: u64,                  // Underlying principal supplied (net of redemptions)
}

public struct KaiVault<phantom T, phantom YT> has store {
    yt_balance: Balance<YT>,
    principal: u64,
}

FeeHouse

Protocol fee management:

public struct FeeHouse has key {
    id: UID,
    fee_rate: u64,  // Protocol fee rate (0-5000 of 10000, capped at MAX_FEE_RATE = 50%)
    fee: Bag,       // Accumulated protocol fees
}

AccessList

Protocol address allow list:

public struct AccessList has key {
    id: UID,
    allow: VecSet<address>,  // Allowed protocol addresses
}

AdminCap

Administrator capability token:

public struct AdminCap has key {
    id: UID,  // Single admin capability
}

Permission System

Four-tier permission model:

  1. Owner: Creator of the PositionManager
  2. Agent: Addresses authorized by owner (limited operations)
  3. Protocol: Addresses in AccessList (managed by admin)
  4. Admin: Holder of AdminCap (global management)

Quick Start

Prerequisites

  • Sui CLI installed
  • Move development environment
  • Access to Sui network (testnet/mainnet)

Use the deployed package

Build transactions targeting the v3 package above. The CDPM User SDK guide covers position management, agent authorization, and lending.

Publish a separate deployment

  1. Build the contract:

    sui move build --build-env mainnet
  2. Publish the package:

    sui client publish --gas-budget 100000000
  3. Initialize the contract:

    • The init function automatically creates:
      • AdminCap transferred to deployer
      • FeeHouse with default 20% fee rate
      • AccessList (empty)
      • GlobalRecord for position tracking

Basic Usage

1. User Creates Position

Two entrypoints exist depending on whether the caller already owns a Cetus Position object.

// (a) Deposit raw coins and open a fresh Cetus position inside a new PM.
public fun user_deposit_liquidity<CoinTypeA, CoinTypeB>(
    record: &mut Record,
    pool: &mut Pool<CoinTypeA, CoinTypeB>,
    coin_a: &mut Coin<CoinTypeA>,
    coin_b: &mut Coin<CoinTypeB>,
    bins: vector<u32>,
    amounts_a: vector<u64>,
    amounts_b: vector<u64>,
    config: &GlobalConfig,
    versioned: &Versioned,
    clk: &Clock,
    ctx: &mut TxContext,
);

// (b) Wrap an existing Cetus `Position` the caller already holds into a fresh PM.
public fun user_deposit_position(
    record: &mut Record,
    position: Position,
    ctx: &mut TxContext,
);

2. Add Authorized Agent

// Authorize an AI agent (no Clock parameter)
public fun user_insert_agent(
    pm: &mut PositionManager,
    agent: address,
    ctx: &TxContext,
);

3. Collect Fees

// Collect accumulated fees
let (coin_a, coin_b) = user_collect_fee<CoinTypeA, CoinTypeB>(
    pm: &mut PositionManager,
    pool: &mut Pool<CoinTypeA, CoinTypeB>,
    config: &GlobalConfig,
    versioned: &Versioned,
    clk: &Clock,
    ctx: &mut TxContext,
);

Fee Mechanism

Protocol Fee Calculation

Protocol DLMM collections and positive lending interest use the configured fee rate, initially 20%.

fee_amount = amount * fee_rate / FEE_DENOMINATOR

Where FEE_DENOMINATOR = 10000 (100%).

The fee rate is capped at 50% (MAX_FEE_RATE = 5000) via admin_set_fee. This bound limits admin authority and cannot be bypassed without redeploying.

Fee Distribution

  • Owners receive the full DLMM collection, and agents credit the full collection to pm.fee.
  • Protocol operators deduct the configured rate from DLMM fee and reward collections.
  • Scallop and Kai redeems charge the configured rate on positive interest for every authorized caller.

Design Notes

The following behaviors are intentional design choices, not defects. They are documented here so that integrators and auditors do not mistake them for bugs.

D-01: Protocol Fee on Managed DLMM Collections

protocol_collect_fee and protocol_collect_reward call take_fee. Owner DLMM collection functions return the full coins to the caller, and agent collection functions credit the full amount to pm.fee. Lending redemptions use the interest fee described in D-08 and D-10.

D-02: Empty agents Set Means "Protocol May Operate"

Each PositionManager has an agents: VecSet<address> field that acts as a mutually exclusive switch between protocol-managed and agent-managed modes:

agents state Who may call protocol_* Who may call agent_*
empty (default) whitelisted protocol addresses nobody
non-empty nobody only addresses in agents

When the owner authorizes at least one agent, the protocol is automatically excluded from managing the position — the user has opted into a custom agent and the protocol must step aside. Conversely, when no agent is configured, the position is considered opted into protocol management.

D-03: fee_rate Changes Take Effect Immediately

admin_set_fee updates FeeHouse.fee_rate without a timelock or per-position checkpoint. The new rate applies to the next protocol_collect_* call, including any Cetus fees/rewards that accrued before the rate change.

Rationale: rebalancing and fee collection happen frequently, so the amount of yield that could possibly accrue between two rate changes is small. The economic impact of retroactive application is therefore bounded and acceptable in exchange for operational simplicity.

D-04: withdraw_from_balance / withdraw_from_fee Truncate on Insufficient Balance

When the requested amount is greater than or equal to the current balance, the internal withdrawal helpers return the entire available balance rather than aborting:

if (amount >= balance_amount) {
    bag::remove<String, Balance<T>>(&mut pm.balance, coin_type).into_coin(ctx)
} else {
    balance::split<T>(bag::borrow_mut(&mut pm.balance, coin_type), amount).into_coin(ctx)
}

This is intentional. It lets callers pass a conservative upper bound (for example u64::MAX for "withdraw everything") and guarantees that dust from rounding never strands a bag entry. Downstream functions that require an exact amount (e.g. pool::add_liquidity) will still abort, so no funds can be lost.

D-05: Upgrade Policy

The current CDPM package uses the irreversible OnlyDep upgrade policy (see the upgrade policy: line near the top of this README). The core cdpm.move bytecode cannot be changed; only dependency-version updates needed to track Cetus DLMM, Scallop, and Kai SAV remain possible. The admin levers are admin_set_fee (capped at 50%), admin_transfer, and the admin_force_return_* / admin_force_close_pm asset-evacuation escape hatch (D-12), which can only ever route assets to pm.owner — never to the admin.

If a dependency ships a breaking type-identity change, a fresh cdpm deploy is still required.

D-06: user_close_pm Drain-Preconditions Surface as cdpm Error Codes

user_close_pm validates four drain-preconditions up front so the abort diagnostic is always a cdpm error code, not an upstream framework abort:

  • EPositionHasRewards (1007) if any reward type in the underlying Cetus PositionInfo.rewards_owned vector is non-zero. cdpm reads the vector through pool::position_manager → position::borrow_position_info → position::info_rewards before calling pool::close_position.
  • ELendingNotEmpty (1004) if pm.lending still holds any Scallop / Kai vault.
  • EBalanceNotEmpty (1008) if pm.balance is non-empty.
  • EFeeNotEmpty (1009) if pm.fee is non-empty.

How to close safely: build a PTB that first

  1. calls user_collect_reward<CoinTypeA, CoinTypeB, R> once for every reward type on the pool (set of Rs is pool-specific and not known statically inside cdpm),
  2. redeems every Scallop / Kai vault via scallop_redeem / kai_redeem,
  3. drains pm.balance via user_remove_liquidity_from_balance,
  4. drains pm.fee via user_withdraw_fee,

then calls user_close_pm in the same transaction. The user-sdk skill documents a helper; see skills/cdpm-user-sdk/reference/workflows.md.

D-08: Scallop Lending — Direct-Integration Single-Shot Idle Yield

Idle balances in pm.balance (assets outside the active bin range) can be loaned to Scallop to earn interest. The PM stores Scallop's sCoin protocol::reserve::MarketCoin<T> in a lending: Bag keyed by underlying type:

public struct ScallopVault<phantom T> has store {
    scoin: Balance<MarketCoin<T>>,
    principal: u64,
}

Type-pinned sCoin. MarketCoin<T> has only the drop ability and no public constructor, so the only way to obtain a non-zero Balance<MarketCoin<T>> is through Scallop's own mint flow. cdpm populates ScallopVault.scoin exclusively via mint::mint<T> called from inside scallop_supply — no PTB-supplied share token ever reaches storage.

Single-shot API (post-refactor):

public fun scallop_supply<T>(
    access: &AccessList,
    pm: &mut PositionManager,
    version: &ScallopVersion,
    market: &mut Market,
    amount: u64,
    clock: &Clock,
    ctx: &mut TxContext,
);

public fun scallop_redeem<T>(
    access: &AccessList,
    pm: &mut PositionManager,
    fee_house: &mut FeeHouse,
    version: &ScallopVersion,
    market: &mut Market,
    scoin_amount: u64,
    clock: &Clock,
    ctx: &mut TxContext,
);

Each operation is a single MoveCall. cdpm itself invokes mint::mint / redeem::redeem; the returned share token / underlying flows directly into PM storage. Both upstream functions call accrue_interest_for_market as their first step, so the exchange rate used is always fresh by construction — no EStaleScallopState freshness guard is needed.

All three managed-tier callers (owner / agent / protocol & no-agents) are accepted via assert_caller_authorized. Yield interest is treated as protocol income — every scallop_redeem deducts fee_rate (capped at MAX_FEE_RATE = 50%) from the interest portion (max(0, redeemed_amount - principal_portion)); principal returns to pm.balance intact. Departure from D-01 is intentional: lending is a recurring protocol-managed yield, not self-management.

PTB templates:

Supply:
  cdpm::scallop_supply<T>(access, pm, version, market, amount, clock)

Redeem:
  cdpm::scallop_redeem<T>(access, pm, fee_house, version, market, scoin_amount, clock)

Operational risks:

  1. Liquidity risk — Scallop is over-collateralized lending. At ≈100% utilization, redeem::redeem aborts. Off-chain scheduler must reserve a non-Scallop buffer for emergency rebalancing.
  2. Version risk — Scallop bumping Version aborts cdpm's mint/redeem call. Resolution path: a cdpm DEP_ONLY upgrade to the new Scallop protocol dep (cdpm source unchanged).
  3. Whitelist risk — Scallop checks tx_context::sender(ctx); cdpm is the immediate sender from Scallop's perspective. If Scallop disables allow_all, supply/redeem fails until cdpm's address is whitelisted.
  4. Asset deactivation — Scallop's mint aborts on disabled coin types.
  5. Supply cap — Scallop enforces a per-asset supply_limit; large mints may abort.
  6. Gas vs yield — every redeem call accrues interest first; tiny positions can be net-negative.
  7. Scallop package re-deploy — if Scallop ever publishes a NEW package with a new MarketCoin<T> type identity, cdpm's bytecode references the OLD MarketCoin<T> and cannot accept the new sCoin type. Resolution: a fresh cdpm deploy is required to track the new MarketCoin<T>.

Trust boundary. The security ceiling of cdpm's Scallop integration is the integrity of the Scallop team and their custody of the ScallopProtocol package upgrade-cap + AdminCap. A backdoored protocol::reserve upgrade can drain underlying Balance<T> out of every existing Reserve shared object. cdpm inherits exactly the same Scallop-trust assumption every other Scallop consumer takes — no more, no less.

Admin escape hatch (D-12). The owner-only exit for lending remains the normal scallop_redeem → pm.balance → user_remove_liquidity_from_balance flow, which preserves the principal-counter accounting that protocol-fee math depends on. In the "upgrade incompatible" emergency, the admin can redeem the position to the underlying via admin_force_return_scallop<T> (calling Scallop's redeem::redeem and charging the same interest-only protocol fee as scallop_redeem, Coin<T> straight to pm.owner). See D-12. User mitigations are purely off-chain (don't supply if you don't trust Scallop; bound per-PM exposure via the scheduler).

user_close_pm asserts lending is empty (ELendingNotEmpty = 1004). Callers must redeem every vault before closing the PM.

D-09: Kai SAV Lending — Direct-Integration Single-Shot Yield

A second yield destination alongside Scallop. Targets Kai's Single-Asset Vault (SAV) layer — kai_sav::vault — with the production-only kai_leverage_supply_pool strategy module. cdpm calls the full chain (vault::deposit for supply; vault::withdraw → klsp::withdraw → vault::redeem_withdraw_ticket for redeem) inline.

public struct KaiVault<phantom T, phantom YT> has store {
    yt_balance: Balance<YT>,
    principal: u64,
}

Stored in the same lending: Bag as ScallopVault. Bag key is YT's type_name (not T's), so a single underlying T can simultaneously have a Scallop vault (key = T) and a Kai vault (key = YT) without collision.

Type-pin defense: lp_treasury: TreasuryCap<YT> lives inside Kai's Vault<T, YT> and only kai_sav::vault itself can mint YT balances. Combined with kai_sav::vault::new being public(package) (vault.move:235), no external code can publish a fake Vault<USDC, EvilYT> and forge Coin<EvilYT> of attacker-chosen value — cdpm does not need an admin-curated vault registry.

Public surface:

public fun kai_supply<T, YT>(
    access: &AccessList,
    pm: &mut PositionManager,
    vault: &mut kai_sav::vault::Vault<T, YT>,
    amount: u64,
    clock: &Clock,
    ctx: &mut TxContext,
);

public fun kai_redeem<T, ST, YT>(
    access: &AccessList,
    pm: &mut PositionManager,
    fee_house: &mut FeeHouse,
    vault: &mut kai_sav::vault::Vault<T, YT>,
    strategy: &mut klsp::Strategy<T, ST>,
    supply_pool: &mut SupplyPool<T, ST>,
    yt_amount: u64,
    clock: &Clock,
    ctx: &mut TxContext,
);

PTB templates:

Supply:
  cdpm::kai_supply<T, YT>(access, pm, vault, amount, clock)

Redeem:
  cdpm::kai_redeem<T, ST, YT>(
      access, pm, fee_house, vault, strategy, supply_pool, yt_amount, clock)

The full Kai withdrawal chain runs inside kai_redeem atomically. vault.withdraw_ticket_issued flips to true at the first step and back to false at the third, all within one Move function; no intermediate state ever escapes the call.

Yield fee semantics match Scallop (MAX_FEE_RATE = 50%, charged on max(0, redeemed - principal_portion)).

Operational caveats:

  • Bootstrap (yt_supply == 0): Kai's vault::deposit returns YT at the bootstrap 1:1 rate. cdpm records the actual returned yt_balance as principal accumulation; no EZeroExpected guard exists.
  • Strategy losses (StrategyLossEvent in vault::redeem_withdraw_ticket): when the strategy returns less than requested, cdpm consumes the smaller amount. The fee formula yields interest = 0 for any redeem where the loss eats into principal — the user is not double-taxed. The user receives redeemed - 0 = redeemed into pm.balance.
  • Admin pause / TVL cap / rate limiter: caller PTB aborts at the live vault::* / klsp::* call. cdpm unaffected; pm.lending intact, awaiting unpause.
  • New Kai strategy module: if Kai future-deploys a vault using a different strategy module, kai_redeem on that vault aborts at PTB construction or strategy::withdraw execution. Resolution: a new cdpm release that adds a parallel kai_redeem_via_<newmodule> entry.

Trust boundary. Identical shape to Scallop's: integrity of Kunalabs and their custody of the kai_sav / kai_leverage upgrade-caps. No admin-curated YT whitelist; the type-system suffices.

For Kai lending the owner-only exit is kai_redeem → pm.balance → user_remove_liquidity_from_balance; the admin emergency path is admin_force_return_kai<T, ST, YT> (redeem to underlying Coin<T> with the same interest-only fee as kai_redeem, to pm.owner — see D-12).

D-12: Admin Emergency Return — Asset Evacuation Escape Hatch

For the "upgrade incompatible" scenario (a dependency ships a breaking type-identity change), the admin — and only the holder of the AdminCap multisig — can force raw stored assets out of any PM back to pm.owner:

  • admin_force_return_balance<T> / admin_force_return_fee<T> — drain pm.balance[T] / pm.fee[T] to pm.owner.
  • admin_force_return_position — hand the raw Cetus Position object back to pm.owner (no close, no reward collect).
  • admin_force_return_scallop<T> — redeem the Scallop position to the underlying Coin<T> (via redeem::redeem, protocol fee on the interest portion) and return it to pm.owner.
  • admin_force_return_kai<T, ST, YT> — redeem the Kai vault to the underlying Coin<T> (full withdraw → klsp::withdraw → redeem_withdraw_ticket chain, protocol fee on interest) and return it to pm.owner.
  • admin_force_close_pm — delete a fully drained PM (aborts with EPositionStillActive/EBalanceNotEmpty/EFeeNotEmpty/ELendingNotEmpty if anything remains).
  • user_remove_record_entry — owner clears the stale Record index entry pointing at an admin-closed PM.

Every admin_force_return_* hard-codes the recipient to pm.owner, so the admin can only "un-stick" funds, never steal them. Because Bag is non-iterable, each call drains one coin type; the admin enumerates present types off-chain from the PM's dynamic fields and calls once per type, then closes. This is a forward-looking guarantee for the next deploy: a fresh package cannot rescue assets already stranded in a prior package's PMs.

Security Features

1. Permission Separation

  • Clear boundaries between owner, agent, protocol, and admin roles
  • Agent-limited operations (cannot withdraw funds)
  • Protocol access controlled by admin-managed allow list

2. Input Validation

  • Fee rate bounds checking (0-50%, MAX_FEE_RATE = 5000)
  • Permission validation on all operations
  • Safe mathematical operations (u128 for fee calculations)

3. Event System

Comprehensive event emission for all operations:

  • Position creation/closing
  • Liquidity addition/removal
  • Fee/reward collection
  • Agent management
  • Admin operations

Event System

All key operations emit events for off-chain monitoring. Recent improvements include:

Enhanced Event Data (Completed ✅)

  • FeeCollected: Added coin_type_a and coin_type_b fields
  • ProtocolFeeCollected: Added coin_type_a and coin_type_b fields
  • RewardCollected: Renamed reward_type to coin_type for consistency
  • ProtocolRewardCollected: Renamed reward_type to coin_type for consistency

See API Documentation for complete event details.

Development

Project Structure

cdpm/
├── sources/
│   └── cdpm.move          # Main contract
├── tests/
│   ├── cdpm_admin_tests.move
│   └── cdpm_tests.move
├── specs/                 # Formal verification runner and specifications
├── Move.toml              # Package configuration
├── Move.lock              # Dependency lock
└── Published.toml         # Mainnet publication metadata

Dependencies

  • Cetus DLMM core v10 uses the mainnet-v0.10.1 interface and the pinned IntegerMate and MoveSTL libraries.
  • Scallop Lending v20 uses the vendored Scallop interface and X v2.
  • Kai SAV v17 and Kai Leverage v21 use the same pinned upstream commit.

See the dependency manifest for source pins and the v3 dependency linkage for on-chain package addresses.

Build and verify

sui move build --build-env mainnet
sui move test --build-env mainnet --package-size 64
bash scripts/check_no_spec_symbols.sh
bun --no-env-file specs/verify.ts

The formal verification command requires Bun and sui-prover. It verifies admin_set_fee_spec in a temporary directory. The bytecode check scans the production build for leaked verification and test helpers. Formal verification setup and scope

Documentation

Comprehensive documentation is available:

  1. DESIGN.md - Technical design and architecture
  2. API.md - Complete API reference
  3. RandyPen/lp-agent - Reference implementation of an autonomous LP agent built on this contract, for third-party agent developers to fork

License

This project is licensed under the terms of the original repository.

Contributing

  1. Review the design notes (D-01 through D-11) in DESIGN.md before changing protocol behavior
  2. Ensure comprehensive testing for all changes
  3. Maintain backward compatibility where possible

Support

For issues, questions, or security concerns:

  1. Review documentation
  2. Check existing issues
  3. Contact maintainers through appropriate channels

Last updated November 19, 2026 Documentation Version: 1.0

Releases

Packages

Contributors

Languages