bluefin

name	bluefin
description	This skill should be used when the user asks about Bluefin, Bluefin perpetuals, Bluefin perps, Bluefin DEX, or wants to integrate with Bluefin on Sui. Covers perpetual futures trading, margin accounts, funding rates, liquidation, ADL, asset deposits/withdrawals, and vaults.

Bluefin Protocol on Sui

Bluefin is a perpetual futures DEX on Sui. It uses off-chain order matching (sequencer/TEE) with on-chain settlement. Users deposit collateral to an AssetBank, and trades are executed via signed payloads verified on-chain. Supports both cross-margin and isolated-margin positions.

Package IDs

Package	Original ID	Description
Perps v2	0xe74481697f432ddee8dd6f9bd13b9d0297a5b63d55f3db25c4d3b5d34dad85b7	Perpetuals engine: accounts, positions, margining, exchange
Vault	0xfadc2a695e4d92612a203f5bfc48e9f0a5be4d6bad9d08b1e8f06ce9be7a3f5a	Vault system for managed perpetual positions

Source Files

Decompiled Move source:

• Perps v2 (latest): packages/mainnet_most_used/0xe2/0ade8adca3df877664e6af96e39143ca32be4a3f74234aa628932fc0b31b82/decompiled_modules/
• Vault: packages/mainnet_most_used/0xf6/83f21823e6dbbeca59759c2c5f703e3f7f40cfd488191de424e56b0bdb7fd1/decompiled_modules/

Architecture

• ExternalDataStore: Shared object for user-facing deposits. Contains AssetBank and perpetual configs pending sync.
• InternalDataStore: Owned by operator (TEE). Stores accounts, positions, perpetual state, filled orders, sequence hashes.
• Account: Per-user account with cross positions, isolated positions, deposited assets, and fee tiers.
• Position: Perpetual position with size, average_entry_price, is_long, leverage, margin, funding state.
• Perpetual: Market config (symbol, IMR/MMR, fees, tick/step size, price bounds, funding rate, oracle price).
• AssetBank: Multi-asset collateral bank. Deposits go here before being synced to InternalDataStore.
• Vault: Managed vault where users deposit funds, receive shares, and an operator trades on their behalf.

Key Design: Sequencer/TEE Pattern

Most operations (trades, liquidations, funding, withdrawals) are NOT direct user calls. Instead:

1. User signs an order off-chain
2. Sequencer matches orders and creates signed payloads
3. TEE or operator submits BCS-encoded + signed transactions on-chain
4. On-chain contracts verify signatures and execute settlement

The only direct user entry point is deposit_to_asset_bank.

Constants

• Base unit: 1e9 (protocol_decimals = 9)
• Primary collateral: USDC
• IMR range: 2%-50% (20_000_000 - 500_000_000)
• MMR minimum: 1% (10_000_000)
• Max fee: 3% (30_000_000)
• Lifespan (tx validity): 90 days (7_776_000_000 ms)

Key Modules

Module	Purpose
exchange	Entry points: deposit, trade settlement, liquidation, funding, ADL
data_store	ExternalDataStore + InternalDataStore, perpetual/account CRUD
account	Account struct, positions, assets, PnL computation, health checks
perpetual	Perpetual market config, funding rates, oracle prices
bank	AssetBank, multi-asset deposits/withdrawals, asset support
margining_engine	Trade math, PnL settlement, fee calculation, health verification
signed_number	Signed integer math (value + sign bool) for PnL calculations
constants	Action types, base units, payload types, operator roles
bluefin_vault	Vault deposit/withdraw/claim with share-based accounting

Common Integration Patterns

Deposit to Asset Bank (only direct user entry point)

// Deposit collateral (e.g., USDC) to Bluefin for trading
exchange::deposit_to_asset_bank<USDC>(
    external_data_store,  // &mut ExternalDataStore
    string::utf8(b"USDC"), // asset symbol
    account_address,       // destination account
    amount,                // amount in asset decimals
    &mut coin,             // coin to deposit from
    ctx
);

Query Account Position

let position = account::get_account_position(account, symbol, is_isolated);
let (perpetual, size, avg_price, is_long, leverage, margin, is_isolated, pending_funding) =
    account::get_position_values(&position);

Compute Position PnL

let pnl = account::compute_position_pnl(perpetual_table, &position);
// Returns signed_number::Number (value + sign)

Check Account Health

let (account_value, health) = account::get_account_value_and_health(
    account, symbol, is_isolated, perpetual_table, asset_table, threshold
);
let is_liq = account::is_liquidateable(account, symbol, is_isolated, perpetual_table, asset_table);

Query Perpetual Config

let symbol = perpetual::get_symbol(perp);
let oracle_price = perpetual::get_oracle_price(perp);
let (maker_fee, taker_fee) = perpetual::get_fees(perp);
let imr = perpetual::get_imr(perp);
let mmr = perpetual::get_mmr(perp);

Vault: Deposit

bluefin_vault::deposit_to_vault<USDC>(
    perpetual_v2, bank_v2, sequencer,
    vault, &mut coin, amount, beneficiary, ctx
);

Vault: Withdraw (request shares burn)

bluefin_vault::withdraw_from_vault<USDC>(
    perpetual_v2, bank_v2, vault, shares_amount, ctx
);

Vault: Claim Withdrawn Funds

bluefin_vault::claim_withdrawn_funds<USDC>(vault, recipient, amount, ctx);

Related Skills

• sui-framework -- Core Sui types (Coin, Balance, Clock)
• pyth -- Oracle price feeds used by Bluefin