Greeting

Welcome, stranger!

This is the Dango Book, all you need to know about the one app for everything DeFi.

• Follow us on Twitter
• Join our Discord server
• Check out source code on GitHub

Security Audit Guide

This guide documents the architecture of Dango – both the blockchain state machine and the smart contract system built on top of it, targeting security auditors with blockchain and DeFi experience. It covers:

1. Architecture – Database, Jellyfish Merkle Tree, storage layer, the App/ABCI interface, virtual machines, and gas metering.
2. Smart Contract Semantics – Entry points, context types, message passing, storage abstractions, authentication model, and the testing framework.
3. Dango Contract System – Each smart contract (bank, accounts, oracle, perps, gateway, etc.), their state layout, access control, and inter-contract interactions.
4. Indexer & Node – The indexer pipeline, SQL schema, GraphQL API, and the CLI that wires everything together.

Repository layout

Trust model at a glance

┌──────────────────────────────────────────────────────────────┐
│  TRUSTED: Node Binary                                        │
│   dango/core/app (ABCI + state transitions)                  │
│   dango/core/db  (RocksDB persistence)                       │
│   dango/core/vm/rust (native contract execution, no sandbox) │
│   dango/core/jellyfish-merkle (state commitment)             │
│   dango/* system contracts (bank, accounts, etc.)            │
│   dango/indexer/* (read-only; cannot affect consensus)       │
└────────────────────── ▼ ─────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────┐
│  UNTRUSTED: Third-Party WASM Contracts                       │
│   Executed inside dango/core/vm/wasm (Wasmer sandbox)        │
│   All storage access namespaced via StorageProvider          │
│   All operations metered via gas tracker                     │
│   Host function calls go through Gatekeeper middleware       │
└──────────────────────────────────────────────────────────────┘

Note: In the current Dango deployment, all contracts are first-party and executed natively via RustVm. The WasmVm path exists for future third-party contract support. Both paths share the same Vm trait interface.

Architecture

Dango is a custom blockchain state machine that runs on top of CometBFT consensus. It is inspired by CosmWasm but differs in several key ways: native Rust contract execution, account abstraction at the protocol level, a dual-storage model (ADR-065 style), and simplified gas metering.

1. Database Layer

Dango separates storage into two independent stores following the Cosmos SDK ADR-065 pattern:

• State Storage (SS): Flat key-value store for raw, prehashed data. This is what contracts read and write.
• State Commitment (SC): Merkle-tree-backed store for cryptographic state proofs. Keys and values are hashed before insertion.

Both stores are backed by a single RocksDB instance using separate column families (dango/core/db/disk/src/db.rs):

state_storage and wasm_storage together form the logical “state storage” layer. They share the same Batch of pending writes; the DB routes each key to the correct CF based on its prefix:

#![allow(unused)]
fn main() {
// dango/core/db/disk/src/db.rs
fn is_wasm_key(key: &[u8]) -> bool {
    key.starts_with(CONTRACT_NAMESPACE) && key.len() >= WASM_PREFIX_LEN
}
}

A contract key has the format b"wasm" | address (20 bytes) | sub_key, giving a fixed 24-byte prefix (WASM_PREFIX_LEN). Everything else goes to state_storage.

The two CFs exist so that each can have specialized RocksDB options:

Both CFs share a common base configuration: 256 MiB LRU block cache, bloom filters (10 bits/key), L0 filter/index pinning, and level-style compaction.

During iteration, the DB detects whether the scan range falls entirely within the wasm range, entirely outside it, or spans both. In the spanning case, it creates a merged iterator over both CFs, preserving key ordering. When min/max share the same 24-byte contract prefix, RocksDB’s prefix_same_as_start mode is enabled for faster prefix-scoped iteration.

DiskDb

#![allow(unused)]
fn main() {
// dango/core/db/disk/src/db.rs
pub struct DiskDb<T> {
    data: Arc<RwLock<Data>>,          // RocksDB handle + priority data
    pending: Arc<RwLock<Option<PendingData>>>,  // Staged but uncommitted writes
    _commitment: PhantomData<T>,      // MerkleTree or SimpleCommitment
}
}

Key properties:

• Two-phase commit. flush_but_not_commit() stages a write batch in memory as PendingData and returns the new version + root hash. commit() atomically persists the staged batch to RocksDB. If the node crashes between these two calls, all changes are discarded on restart.
• Versioning. Each committed batch increments a monotonic version counter. The version must match the expected block height – the IncorrectVersion error prevents out-of-order mutations.
• Pruning. Old versions can be pruned via prune(up_to_version) to reclaim disk space. Pruned versions can no longer produce Merkle proofs.

MemDb (testing)

#![allow(unused)]
fn main() {
// dango/core/db/memory/src/db.rs
pub struct MemDb<T = SimpleCommitment> {
    inner: Shared<MemDbInner>,
    _commitment: PhantomData<T>,
}
}

An in-memory implementation using BTreeMaps. Only maintains the latest version. Supports snapshot/recovery via dump() and recover() for mainnet forking in tests.

Db trait

#![allow(unused)]
fn main() {
// dango/core/app/src/traits/db.rs
pub trait Db {
    type StateStorage: Storage + Clone + 'static;
    type StateCommitment: Storage + Clone + 'static;
    type Proof: BorshSerialize + BorshDeserialize;

    fn state_commitment(&self) -> Self::StateCommitment;
    fn state_storage_with_comment(&self, version: Option<u64>, comment: &'static str)
        -> Result<Self::StateStorage, Self::Error>;

    fn latest_version(&self) -> Option<u64>;
    fn root_hash(&self, version: Option<u64>) -> Result<Option<Hash256>, Self::Error>;
    fn prove(&self, key: &[u8], version: Option<u64>) -> Result<Self::Proof, Self::Error>;

    fn flush_but_not_commit(&self, batch: Batch) -> Result<(u64, Option<Hash256>), Self::Error>;
    fn commit(&self) -> Result<u64, Self::Error>;
    fn prune(&self, up_to_version: u64) -> Result<(), Self::Error>;
}
}

2. Jellyfish Merkle Tree (JMT)

State commitment uses a binary Jellyfish Merkle Tree adapted from Diem (dango/core/jellyfish-merkle/). The tree provides:

• Cryptographic state root (SHA-256) included in the ABCI app_hash signed by validators.
• Membership proofs (a key exists with a given value) and non-membership proofs (a key does not exist).
• Versioned nodes enabling proofs at historical heights.

Node types

#![allow(unused)]
fn main() {
// Internal node: branches left and right
pub struct InternalNode {
    left_hash: Option<Hash256>,
    right_hash: Option<Hash256>,
}

// Leaf node: actual key-value entry
pub struct LeafNode {
    key_hash: Hash256,
    value_hash: Hash256,
}
}

Apply algorithm

1. Receive a Batch of prehash key-value operations.
2. Hash all keys and values with SHA-256.
3. Sort by key hash.
4. Recursively update tree nodes (only changed paths are rewritten).
5. Record orphaned nodes for future pruning.
6. Return new root hash.

Proof verification

#![allow(unused)]
fn main() {
// dango/core/jellyfish-merkle/src/proof.rs
pub fn verify_membership_proof(
    root_hash: Hash256,
    key_hash: Hash256,
    value_hash: Hash256,
    proof: &MembershipProof,  // Vec of sibling hashes along the path
) -> Result<(), ProofError>;

pub fn verify_non_membership_proof(
    root_hash: Hash256,
    key_hash: Hash256,
    proof: &NonMembershipProof,
) -> Result<(), ProofError>;
}

Commitment trait

#![allow(unused)]
fn main() {
// dango/core/app/src/traits/commitment.rs
pub trait Commitment {
    type Proof;
    fn root_hash(storage: &dyn Storage, version: u64) -> StdResult<Option<Hash256>>;
    fn apply(storage: &mut dyn Storage, old_version: u64, new_version: u64, batch: &Batch)
        -> StdResult<Option<Hash256>>;
    fn prove(storage: &dyn Storage, key_hash: Hash256, version: u64) -> StdResult<Self::Proof>;
    fn prune(storage: &mut dyn Storage, up_to_version: u64) -> StdResult<()>;
}
}

Two implementations: MerkleTree (production, full JMT) and SimpleCommitment (testing fallback, SHA-256 of batch).

3. Storage Layer

dango/core/storage/ provides type-safe, namespace-aware abstractions over raw key-value storage.

Abstractions

Usage example:

#![allow(unused)]
fn main() {
const CONFIG: Item<Config> = Item::new("config");
const BALANCES: Map<Addr, Uint128> = Map::new("balances");
const ADMINS: Set<Addr> = Set::new("admins");
}

Key encoding

Keys implement the PrimaryKey trait which serializes composite keys with length delimiters for unambiguous parsing. Tuple keys like (Addr, u64) are encoded as [len(Addr) | Addr bytes | u64 bytes]. Values are serialized with Borsh by default.

Contract storage isolation

Each contract’s storage is wrapped in a StorageProvider (dango/core/app/src/providers/storage.rs):

#![allow(unused)]
fn main() {
pub struct StorageProvider {
    storage: Box<dyn Storage>,
    namespace: Vec<u8>,  // "wasm" + contract_address
}
}

Every read, write, scan, and remove operation is automatically prefixed with the contract’s namespace. Scans are bounded to [namespace, namespace_increment).

Security guarantee: A contract cannot access another contract’s storage through any combination of key manipulation. The StorageProvider is opaque to contract code.

4. The App (ABCI Interface)

The App struct (dango/core/app/src/app.rs) is the state machine’s entry point. It connects the database, VM, indexer, and proposal preparer:

#![allow(unused)]
fn main() {
pub struct App<DB, VM, PP = NaiveProposalPreparer, ID = NullIndexer> {
    pub db: DB,
    vm: VM,
    pp: PP,
    pub indexer: ID,
    query_gas_limit: u64,
    upgrade_handler: Option<UpgradeHandler<VM>>,
    cargo_version: String,
}
}

ABCI lifecycle

CometBFT drives the state machine through these ABCI methods:

InitChain → [PrepareProposal → CheckTx* → FinalizeBlock → Commit]*

InitChain

Initializes genesis state: stores the chain config, deploys system contracts, executes genesis messages. The first version is 0.

CheckTx

Lightweight mempool validation. Only runs:

1. Fee withholding – Can the sender afford the gas fee?
2. sender.authenticate() – Is the credential (signature, nonce) valid?

State changes from CheckTx are discarded. A failing CheckTx causes the transaction to be rejected from the mempool.

FinalizeBlock

Full transaction processing:

1. Upgrade check. If the current height matches a scheduled upgrade and the binary version matches, run the upgrade handler. If the version mismatches, halt the chain intentionally.
2. Process transactions (see Transaction lifecycle):
   • Withhold the gas fee (gas_limit * gas_fee_rate of gas_token, credited to the owner) – must succeed. Senders in gas_exemptions pay nothing.
   • sender.authenticate() – If fails, the withheld fee is still charged.
   • Execute messages one-by-one, atomically.
   • Commit the withheld fee. There is no refund of unused gas.
3. Run cronjobs. Each scheduled cronjob runs in an isolated buffer; failures are silently discarded.
4. Clean up orphaned codes. Codes not referenced by any contract and older than max_orphan_age are removed.
5. Flush. db.flush_but_not_commit(batch) – stages all changes, computes root hash, but does not persist to disk yet.
6. Index. The indexer receives the block and outcomes.

Commit

db.commit() atomically persists the staged changes to RocksDB. If this fails, the chain panics (conservative: prevents state corruption).

Buffer pattern (rollback)

State changes are accumulated in nested Buffer<S> layers:

#![allow(unused)]
fn main() {
// dango/core/types/src/buffer.rs
pub struct Buffer<S> {
    base: S,
    pending: Batch,  // BTreeMap<Vec<u8>, Op<Vec<u8>>>
}
}

• Block-level buffer: Wraps the DB’s state storage.
• Transaction-level buffer: Wraps the block buffer. On tx success, merged up; on failure, discarded.
• Submessage buffer: Each submessage gets its own buffer for granular rollback.

Reads check pending first (most recent write wins), then fall through to base.

Gas metering

#![allow(unused)]
fn main() {
// dango/core/app/src/gas/tracker.rs
pub struct GasTracker {
    inner: Shared<GasTrackerInner>,  // Shared<T> = Arc<RwLock<T>>
}

struct GasTrackerInner {
    limit: Option<u64>,  // None = unlimited (genesis, cronjobs)
    used: u64,
}
}

Gas is consumed on every operation. Exceeding the limit returns StdError::OutOfGas and aborts execution (state changes discarded, fee still collected).

Gas costs (dango/core/app/src/gas/costs.rs):

See Gas for benchmark methodology.

5. Virtual Machine Layer

Two VM implementations share the same trait:

#![allow(unused)]
fn main() {
// dango/core/app/src/traits/vm.rs
pub trait Vm: Sized {
    type Instance: Instance;
    fn build_instance(
        &mut self,
        code: &[u8],
        code_hash: Hash256,
        storage: StorageProvider,
        state_mutable: bool,
        querier: Box<dyn QuerierProvider>,
        query_depth: usize,
        gas_tracker: GasTracker,
    ) -> Result<Self::Instance, Self::Error>;
}

pub trait Instance {
    fn call_in_0_out_1(self, name: &'static str, ctx: &Context) -> Result<Vec<u8>>;
    fn call_in_1_out_1<P>(self, name: &'static str, ctx: &Context, param: &P) -> Result<Vec<u8>>;
    fn call_in_2_out_1<P1, P2>(self, name: &'static str, ctx: &Context, p1: &P1, p2: &P2) -> Result<Vec<u8>>;
}
}

Note: The Instance is consumed (self, not &self) on each call, preventing state leakage between invocations.

RustVm (native execution)

#![allow(unused)]
fn main() {
// dango/core/vm/rust/src/vm.rs
pub struct RustVm;
}

Executes contracts compiled directly into the node binary. No sandboxing, no gas metering overhead. Used for all first-party system contracts (bank, accounts, perps, oracle, etc.).

Security implication: Code running in RustVm has the same trust level as the node binary itself. A bug in a system contract is indistinguishable from a bug in the state machine.

WasmVm (sandboxed execution)

#![allow(unused)]
fn main() {
// dango/core/vm/wasm/src/vm.rs
pub struct WasmVm {
    cache: Option<Cache>,  // LRU cache of compiled Wasmer modules
}
}

Executes third-party WASM bytecode via the Wasmer runtime. Key protections:

Gatekeeper middleware (dango/core/vm/wasm/src/gatekeeper.rs): Validates WASM modules at compilation time. Allowed/denied features:

Metering middleware: Injects gas tracking into every WASM operation (1 gas per Wasmer op).

Memory limits: 32 MiB per instance (512 WASM pages).

Query depth limit: Maximum 3 levels of nested cross-contract queries.

Host functions (dango/core/vm/wasm/src/imports.rs): The WASM guest can call these host-provided functions:

• Storage: db_read, db_write, db_remove, db_scan, db_next
• Crypto: secp256k1_verify, secp256r1_verify, secp256k1_pubkey_recover
• Hashes: sha2_256, sha2_512, sha3_256, sha3_512, keccak256
• Cross-contract queries: query_chain
• Debug logging: debug

Each host function call:

1. Reads data from WASM linear memory.
2. Charges gas (based on operation + data size).
3. Enforces state_mutable – writes rejected during query execution.
4. Invalidates all iterators on write (preventing use-after-mutation bugs).

6. Chain Upgrades

There are three dimensions in which a change can be breaking:

• Consensus-breaking: Given the same state and block, old and new software produce different results, causing a consensus failure.
• State-breaking: The format of data stored in the DB changes.
• API-breaking: The transaction or query API changes.

Any breaking change requires a coordinated upgrade: all validators halt at the same block height, upgrade, and resume together.

Upgrade procedure

1. The chain owner sends a Message::Upgrade:

   {
     "upgrade": {
       "height": 12345,
       "cargo_version": "1.2.3",
       "git_tag": "v1.2.3",
       "url": "https://github.com/left-curve/left-curve/releases/v1.2.3"
     }
   }
   

   This signals the upgrade height and target version. Node operators should not upgrade yet.

2. The chain finalizes block 12344 normally. At block 12345, during FinalizeBlock, the App reads NEXT_UPGRADE from state and checks the binary’s cargo version.

3. Version mismatch → intentional halt. The App returns an error in FinalizeBlockResponse. Block 12345 is not finalized; no state changes are committed. This is safer than risking a fork.

4. The node operator replaces the binary with version 1.2.3 and restarts.

5. CometBFT retries FinalizeBlock for block 12345. The App sees the version now matches, runs the upgrade handler (App::upgrade_handler) if one is registered, clears NEXT_UPGRADE, records the upgrade in PAST_UPGRADES, and resumes normal block processing.

Upgrade handler

#![allow(unused)]
fn main() {
type UpgradeHandler<VM> = fn(Box<dyn Storage>, VM, BlockInfo) -> AppResult<()>;
}

The handler receives mutable storage access and can perform arbitrary state migrations: adding fields to stored structs, rewriting storage layouts, deploying new contracts, or updating configuration. It runs exactly once at the upgrade height.

Security considerations

• The upgrade height and version are stored on-chain (NEXT_UPGRADE item in app state). Only the chain owner can schedule an upgrade.
• A mismatch between the running binary and the scheduled version causes an intentional halt rather than a silent fork – this is the conservative choice.
• There is no automated upgrade tool (like Cosmos SDK’s cosmovisor) yet; operators must manually replace the binary.

Smart Contract Semantics

This chapter documents the programming model for Dango smart contracts: entry points, context types, message passing, storage, authentication, and the testing framework.

1. Entry Points

Contracts export functions that the host calls at specific points in the transaction lifecycle. Each entry point receives a typed context and returns a typed response.

Basic entry points

System entry points

Entry points are defined using the #[dango_ffi::export] attribute macro, which generates the WASM FFI boilerplate (extern C functions, memory marshaling via Region structs). This macro is only necessary when building contracts for the WasmVm. Contracts targeting the RustVm (all first-party Dango contracts) do not need it – they register their entry points directly as Rust function pointers.

2. Context Types

Each entry point receives a context that controls what the contract can do.

#![allow(unused)]
fn main() {
// dango/core/types/src/context.rs

// Read-only access (queries)
pub struct ImmutableCtx<'a> {
    pub storage:  &'a dyn Storage,
    pub api:      &'a dyn Api,
    pub querier:  QuerierWrapper<'a>,
    pub chain_id: String,
    pub block:    BlockInfo,
    pub contract: Addr,
}

// Read-write access with sender and funds info (execute, instantiate)
pub struct MutableCtx<'a> {
    pub storage:  &'a mut dyn Storage,
    pub api:      &'a dyn Api,
    pub querier:  QuerierWrapper<'a>,
    pub chain_id: String,
    pub block:    BlockInfo,
    pub contract: Addr,
    pub sender:   Addr,
    pub funds:    Coins,
}

// Read-write, chain-initiated (migrate, reply, cron_execute, bank)
pub struct SudoCtx<'a> {
    pub storage:  &'a mut dyn Storage,
    pub api:      &'a dyn Api,
    pub querier:  QuerierWrapper<'a>,
    pub chain_id: String,
    pub block:    BlockInfo,
    pub contract: Addr,
}

// Authentication context (authenticate)
pub struct AuthCtx<'a> {
    pub storage:  &'a mut dyn Storage,
    pub api:      &'a dyn Api,
    pub querier:  QuerierWrapper<'a>,
    pub chain_id: String,
    pub block:    BlockInfo,
    pub contract: Addr,
    pub mode:     AuthMode,
}

pub enum AuthMode {
    Simulate,   // Gas estimation -- tx is unsigned (sig verify skipped)
    Check,      // CheckTx phase
    Finalize,   // FinalizeBlock phase
}
}

Security note: MutableCtx is the only context with sender and funds. A SudoCtx entry point is called by the chain (no user sender). An AuthCtx entry point knows which ABCI phase it’s in, allowing it to skip signature verification during simulation (the tx is not yet signed at that point – the user needs the gas estimate before they can sign).

3. Messages and Responses

Transaction messages

A transaction contains a vector of Message variants:

#![allow(unused)]
fn main() {
pub enum Message {
    Configure(MsgConfigure),
    Upgrade(MsgUpgrade),
    Transfer(MsgTransfer),
    Upload(MsgUpload),
    Instantiate(MsgInstantiate),
    Execute(MsgExecute),
    Migrate(MsgMigrate),
}

pub struct MsgExecute {
    pub contract: Addr,
    pub msg: Json,
    pub funds: Coins,
}
}

Contract responses

#![allow(unused)]
fn main() {
pub struct Response {
    pub submsgs: Vec<SubMessage>,
    pub subevents: Vec<ContractEvent>,
}
}

Submessages and replies

Contracts can emit submessages – nested calls that execute after the current entry point returns:

#![allow(unused)]
fn main() {
pub struct SubMessage {
    pub msg: Message,
    pub reply_on: ReplyOn,
}

pub enum ReplyOn {
    Success(Json),   // Reply only on success (payload passed to reply())
    Error(Json),     // Reply only on failure
    Always(Json),    // Reply regardless
    Never,           // No reply callback
}

pub type SubMsgResult = Result<Event, String>;
}

Execution semantics:

Each submessage executes in its own Buffer. On success, the buffer is committed to the parent. On failure, the submessage’s state changes are always reverted (its buffer is discarded). If reply_on is Error or Always, the parent continues and reply() is called; otherwise, the entire transaction is aborted.

Security implication: A failed submessage can never leave behind partial state changes. If no reply handler catches the failure, the entire transaction is aborted, preventing contracts from silently ignoring errors.

4. Core Types

Addresses

#![allow(unused)]
fn main() {
pub type Addr = EncodedBytes<[u8; 20], AddrEncoder>;  // 20-byte, 0x-prefixed hex

// Deterministic address derivation
// address = ripemd160(sha256(deployer_addr || code_hash || salt))
}

All Addr fields are validated during deserialization. Invalid hex or wrong length is rejected before contract code runs.

Coins

#![allow(unused)]
fn main() {
pub type Coins = BTreeMap<Denom, Uint128>;

// Ordered, deduplicated, non-zero amounts enforced
}

Math types

dango/core/math/ provides overflow-safe fixed-point arithmetic:

All arithmetic is checked. Overflow/underflow returns StdError instead of panicking.

Dimensional Number type

Dango extends the base math types with Number<Q, U, D> (dango/exchange/types/src/typed_number.rs), a dimensionally-typed signed fixed-point decimal (Dec128_6 – 6 decimal places). The three type parameters encode physical dimensions using typenum integers:

• Q – quantity (asset units)
• U – USD value
• D – time duration (days)

Multiplication and division propagate dimensions at the type level, so the compiler rejects nonsensical operations (e.g., adding a price to a quantity):

#![allow(unused)]
fn main() {
// price × quantity = USD value  (Q: -1+1=0, U: 1+0=1, D: 0+0=0)
fn checked_mul<Q1, U1, D1>(self, rhs: Number<Q1, U1, D1>)
    -> MathResult<Number<Q + Q1, U + U1, D + D1>>;

// USD value / price = quantity  (Q: 0-(-1)=1, U: 1-1=0, D: 0-0=0)
fn checked_div<Q1, U1, D1>(self, rhs: Number<Q1, U1, D1>)
    -> MathResult<Number<Q - Q1, U - U1, D - D1>>;
}

Key type aliases used throughout the perps contracts:

This type system is a key defense against unit-confusion bugs in margin, PnL, and funding calculations. A mismatched dimension is a compile-time error, not a runtime surprise.

Bounded types

Dango encourages declarative validation via Bounded<T, B> and LengthBounded<T>:

#![allow(unused)]
fn main() {
struct FeeRateBounds;
impl Bounds<Udec256> for FeeRateBounds {
    const MIN: Bound<Udec256> = Bound::Inclusive(Udec256::ZERO);
    const MAX: Bound<Udec256> = Bound::Exclusive(Udec256::ONE);
}
type FeeRate = Bounded<Udec256, FeeRateBounds>;

// Length bounds
pub type Label = LengthBounded<String, 1, 128>;
pub type Salt = LengthBounded<Binary, 1, 82>;
}

Bounds are enforced during deserialization – contracts never see out-of-bounds data.

5. Storage Abstractions

Item (single value)

#![allow(unused)]
fn main() {
const CONFIG: Item<Config> = Item::new("config");

CONFIG.save(storage, &value)?;
let v = CONFIG.load(storage)?;
let v = CONFIG.may_load(storage)?;  // Option<T>
}

Map (key-value)

#![allow(unused)]
fn main() {
const BALANCES: Map<Addr, Uint128> = Map::new("balances");

BALANCES.save(storage, addr, &amount)?;
let amt = BALANCES.load(storage, addr)?;
BALANCES.has(storage, addr);
BALANCES.remove(storage, addr);

// Iteration
for (key, value) in BALANCES.range(storage, None, None, Order::Ascending)? {
    // ...
}
}

Set (membership)

#![allow(unused)]
fn main() {
const WHITELIST: Set<Addr> = Set::new("whitelist");

WHITELIST.insert(storage, addr)?;
WHITELIST.has(storage, addr);
WHITELIST.remove(storage, addr);
}

Counter

#![allow(unused)]
fn main() {
const NONCE: Counter<u32> = Counter::new("nonce", 0, 1);  // base=0, step=1

let (old, new) = NONCE.increment(storage)?;
}

IndexedMap

For queryable maps with secondary indexes:

#![allow(unused)]
fn main() {
const USERS: IndexedMap<UserIndex, User, UserIndexes> = IndexedMap::new("user", indexes);

// Primary key access
USERS.save(storage, user_idx, &user)?;
let user = USERS.load(storage, user_idx)?;

// Secondary index queries
USERS.idx.by_account.prefix(addr).range(...)?;
USERS.idx.by_name.prefix(name).range(...)?;
}

Index types:

• MultiIndex<PK, IK, T> – one primary key can map to many index keys (one-to-many).
• UniqueIndex<PK, IK, T> – one primary key maps to exactly one unique index key.

6. Cross-Contract Communication

Queries

Contracts can query other contracts or chain state via the QuerierWrapper:

#![allow(unused)]
fn main() {
// Query another contract's custom endpoint (invokes the target's query() entry point)
let result: R::Response = ctx.querier.query_wasm_smart(contract_addr, query_msg)?;

// Query raw storage of another contract (direct KV lookup, no entry point call)
let raw: Option<Binary> = ctx.querier.query_wasm_raw(contract_addr, key)?;

// Query bank balances
let balance: Coin = ctx.querier.query_balance(addr, denom)?;
let all: Coins = ctx.querier.query_balances(addr)?;
}

There is also StorageQuerier::query_wasm_path (dango/core/storage/src/querier.rs), which combines the low gas cost of query_wasm_raw with the ergonomics of query_wasm_smart. It takes a typed storage Path (produced by Item::path() or Map::path(key)), performs a raw KV lookup, and automatically deserializes the result using the storage item’s codec:

#![allow(unused)]
fn main() {
// Read another contract's CONFIG item -- raw lookup, typed result, no entry point call
let cfg: Config = ctx.querier.query_wasm_path(other_contract, CONFIG.path())?;

// Read a specific key from another contract's Map
let user: User = ctx.querier.query_wasm_path(factory, &USERS.path(user_index))?;

// Optional variant (returns None instead of error if key is missing)
let maybe: Option<User> = ctx.querier.may_query_wasm_path(factory, &USERS.path(idx))?;
}

This is the preferred query method in Dango’s inter-contract calls (e.g., the auth module reading user data from the account factory, or the oracle querier reading Pyth prices) because it avoids the overhead of invoking the target contract’s query() entry point entirely.

Queries are read-only and gas-metered. They cannot mutate state. Recursive queries are limited to depth 3 to prevent stack overflow.

Submessages (state-mutating calls)

To call another contract with state mutation, return submessages in the Response:

#![allow(unused)]
fn main() {
let msg = Message::execute(target_addr, &call_msg, coins)?;
let response = Response::new()
    .add_message(msg)                          // reply_on: Never
    .add_submessage(SubMessage::reply_on_success(msg, &data)?);  // reply_on: Success
}

7. Authentication and Account Model

Dango uses account abstraction – every user has a dedicated smart contract instance that handles authentication.

Account lifecycle

1. Registration. User calls the account factory with a signed RegisterUser message.
2. Account creation. The factory deploys an account contract instance, registers the user’s public key, and optionally activates the account.
3. Transaction signing. User constructs a SignDoc (sender, messages, nonce, expiry), signs it, and submits a Tx.
4. Authentication. The host calls the account contract’s authenticate() entry point. The contract verifies the signature, nonce, and account status.

Nonce management

A naively incrementing nonce forces strict transaction ordering: if a user sends nonces 11 and 12 concurrently and 12 arrives first, 12 is rejected (the account expects 11). This is poor UX for high-frequency use cases like canceling multiple limit orders.

Instead, Dango tracks the most recent 20 nonces seen (SEEN_NONCES). A new tx is accepted if:

• Its nonce is not already in SEEN_NONCES.
• Its nonce is greater than the smallest nonce in SEEN_NONCES.
• Its nonce does not jump more than 100 from the current maximum (prevents a DoS where an attacker fills the set with very large values).

When a new nonce is inserted and the set exceeds 20 entries, the smallest is evicted. This means nonces older than the 20th-most-recent are permanently rejected, which also serves as an implicit transaction expiry (supplemented by an explicit expiry timestamp in the tx metadata).

This design allows concurrent, unordered transaction submission while still preventing replay attacks.

Account status

#![allow(unused)]
fn main() {
pub enum AccountStatus {
    Inactive,  // Not yet funded or activated
    Active,    // Can send transactions
    Frozen,    // Blocked (e.g., by governance)
}
}

Inactive accounts are activated on sufficient deposit (≥ min_deposit from app config).

Signature types

8. FFI Layer

dango/core/ffi/ bridges WASM guests and the host:

• Exports (ffi/src/exports.rs): do_instantiate, do_execute, do_query, etc. These deserialize context and message from WASM memory, call the contract function, and serialize the result back.
• Imports (ffi/src/imports.rs): db_read, db_write, secp256k1_verify, etc. These are extern C functions the guest calls to invoke host capabilities.
• Memory (ffi/src/memory.rs): Uses Region structs (offset + capacity) to describe buffers in WASM linear memory. allocate and deallocate are auto-provided entry points.

9. Testing Framework

TestSuite

dango/core/testing/ provides a high-level integration test harness:

#![allow(unused)]
fn main() {
let suite = TestBuilder::new()
    .with_chain_id("test-chain")
    .with_block_time(Duration::from_secs(5))
    .with_genesis_state(genesis)?
    .build()?;

// Upload and deploy a contract
suite.upload(wasm_code)?;
let addr = suite.instantiate(code_hash, &msg, None)?;

// Execute and query
let outcome = suite.execute(addr, &execute_msg, &funds)?;
let result: QueryResponse = suite.query(addr, &query_msg)?;

// Advance blocks
suite.make_block()?;
}

Test helpers

• outcome.should_succeed() / outcome.should_fail() – Assert tx result.
• outcome.should_fail_with_error("msg") – Assert specific error.
• Event inspection via outcome.events.

Testing with MemDb + RustVm

Tests use MemDb (in-memory, no disk I/O) and RustVm (native execution, no WASM compilation). This makes tests fast and deterministic while exercising the same storage and execution paths as production.

Dango-specific test suite

dango/testing/ extends the base suite with helpers for deploying the full Dango contract system (bank, accounts, oracle, perps) in a single genesis block. This enables end-to-end tests that exercise inter-contract interactions.

10. Procedural Macros

dango/core/macros/ provides:

• #[dango_ffi::export] – Generates WASM FFI wrappers for entry points. Only needed for WasmVm contracts; RustVm contracts register entry points directly.
• #[dango_primitives::derive(Serde, Borsh)] – Derives standard traits (Serialize, Deserialize, BorshSerialize, BorshDeserialize, Clone, Debug, PartialEq, Eq).
• #[dango_primitives::event("name")] – Registers an event type with a canonical name.
• #[dango_storage::index_list(PK, T)] – Implements IndexList trait for IndexedMap secondary indexes.

Dango Contract System

Dango is a suite of smart contracts that together form a perpetual futures exchange, oracle, token ledger, bridge aggregator, and account system. All contracts are first-party and execute natively via RustVm.

1. Shared Types (dango/exchange/types/)

All contracts reference a central AppConfig that stores addresses of every system contract:

#![allow(unused)]
fn main() {
pub struct AppAddresses {
    pub account_factory: Addr,
    pub dex: Addr,
    pub gateway: Addr,
    pub hyperlane: Hyperlane<Addr>,
    pub oracle: Addr,
    pub perps: Addr,
    pub warp: Addr,
}
}

Other shared types include authentication types (Key, Signature, Credential, SignDoc, Metadata) and price types (PrecisionlessPrice, PrecisionedPrice).

2. Bank (dango/exchange/bank/)

The bank contract manages all token balances, transfers, mints, and burns.

State layout

Operations

• Transfer. Moves coins between accounts. This is implemented at the host level via BankMsg::Transfer, not as a contract execute message.
• Mint. Mint { to, coins } – caller must be the namespace owner for each denom. If the recipient contract doesn’t exist, coins go to ORPHANED_TRANSFERS.
• Burn. Burn { from, coins } – caller must be the namespace owner.
• Force transfer. ForceTransfer { from, to, coins } – namespace owner can move funds arbitrarily. Used by the perps contract to settle PnL.
• Set transfers enabled. SetTransfersEnabled(bool) – chain owner only.

Disabling transfers

Every balance movement caused by a transfer passes through bank_execute: the Transfer message, the funds attached to an Execute or Instantiate message, and the gas fee withheld by the state machine. That makes it the one place where transfers can be switched off, which the wind-down does.

While disabled, a transfer goes through only if it satisfies both conditions:

1. The sender or the recipient is the gateway contract, or the recipient is the chain owner. The first two cover bridge deposits, withdrawals, and refunds; the third covers the gas fee.
2. The recipient exists. No new orphaned transfer may be created, even on an allowed leg, or a bridge deposit to an account that was never created would strand tokens in the bank again.

mint carries the same recipient check, since it has its own orphan branch. burn and RecoverTransfer are not gated: neither can strand funds once the map is empty and no new entry can be created.

An absent TRANSFERS_ENABLED means enabled, so a chain created before the wind-down needs no genesis change and no migration of this item.

Access control

Namespace ownership is assigned once by the chain owner and cannot be overwritten. For example, the perps contract owns the perp/ namespace.

Security considerations

• Orphaned transfers: If a contract is instantiated but not yet registered, mints to it become dead letters. Recovery requires an explicit RecoverTransfer call. There is no automatic expiry or governance recovery.
• Trust in namespace owners: The bank unconditionally trusts namespace owners for mint/burn/force-transfer. A bug in the perps contract could allow unlimited minting of perp/* tokens.

3. Account Factory (dango/exchange/account-factory/)

Creates and manages user accounts.

State layout

User structure

#![allow(unused)]
fn main() {
pub struct User {
    pub name: Option<Username>,                  // Immutable once set
    pub accounts: BTreeMap<AccountIndex, Addr>,  // Max 5 accounts
    pub keys: BTreeMap<Hash256, Key>,            // All signing keys
}
}

Registration flow

1. User sends tokens to the account factory (deposit ≥ min_deposit).
2. User sends a RegisterUser message with a signed RegisterUserData containing the chain ID.
3. Factory verifies signature, creates a new User record, deploys an account contract, and optionally registers a referrer with the perps contract.

Constraints:

• Exactly one message per registration tx (prevents batching attacks).
• Username is immutable after being set.
• Maximum 5 accounts per user.
• Nonce jump limited to 100 (prevents DoS on the nonce set).

4. Account (dango/exchange/account/)

Single-signature account contract, one instance per user account.

State

Authentication flow

When the host receives a transaction, it calls the sender account’s authenticate():

1. Deserialize the credential from tx.credential.
2. Verify the account is Active (or in Simulate mode).
3. Verify the nonce is valid (not seen, not too far ahead).
4. Verify the signature against the signing key registered in the factory.
5. Return Response.

Operations

• Force withdrawal. ForceWithdrawal { denom, remote, recipient } – chain owner only. Sends the account’s entire balance of denom to recipient on the remote chain, by calling the gateway’s TransferRemote with the balance attached.

  This exists for the wind-down: balances left behind by users who don’t withdraw before the shutdown are returned to the address they deposited from, which the owner supplies as recipient. It carries no privilege inside the gateway – routes, reserves, fees, personal quotas, and rate limits all apply as they would to a withdrawal the user makes themselves, and the resulting withdrawal request still needs the guardian’s or the owner’s approval.

  It works on an Inactive account. The account is not the transaction sender, so authenticate is never involved, and funds attached to an Execute message skip the recipient’s receive hook.

5. Gas fees

Gas fees are handled directly by the state machine; there is no fee contract. The parameters live in the chain Config:

Before a transaction is authenticated, the state machine withholds ceil(gas_limit * gas_fee_rate) of gas_token from the sender and credits it to the chain owner. The fee is charged even if authentication or message execution fails. There is no refund of unused gas.

6. Oracle (dango/exchange/oracle/)

Price feed aggregation for derivatives trading.

State

Price structure

#![allow(unused)]
fn main() {
pub struct Price {
    pub humanized_price: UsdPrice, // e.g., 50000.0 for $50k BTC
    pub timestamp: Timestamp,      // Feed age
}
}

Trust model

• The oracle trusts Pyth network signers whose public keys are registered in PYTH_TRUSTED_SIGNERS with expiry timestamps.
• The chain owner (governance) controls which signers are trusted.
• There is no automated slashing or removal of malicious signers – governance intervention is required.
• Consuming contracts (perps) enforce staleness checks before using prices.

7. Perpetual Futures Exchange (dango/exchange/perps/)

The primary audit target. A leveraged perpetual futures exchange with a vault-based counterparty (market maker).

Note: Detailed mechanism design is documented separately in the Perps section of this book. This chapter focuses on the smart contract implementation details relevant to security auditing.

Source files

dango/exchange/perps/src/
├── lib.rs                  # Entry points (instantiate, execute, query, cron_execute)
├── state.rs                # All storage definitions
├── query.rs                # Query implementations
├── cron.rs                 # Scheduled tasks (funding, conditional orders)
├── core/                   # Pure business logic
│   ├── margin.rs           # Equity, maintenance margin, available margin
│   ├── funding.rs          # Funding rate computation, impact prices
│   ├── fees.rs             # Trading fee calculations (volume-tiered)
│   ├── closure.rs          # Liquidation eligibility, closeout calculations
│   ├── vault.rs            # Vault quoting (bid/ask sizes and prices)
│   ├── fill.rs             # Order fill execution
│   ├── oi.rs               # Open interest constraints
│   ├── liq_price.rs        # Liquidation price computation
│   ├── target_price.rs     # Price constraints for orders
│   ├── min_size.rs         # Minimum order size validation
│   └── decompose.rs        # Decomposing fills into open/close portions
├── trade/                  # State mutations for trading
│   ├── submit_order.rs
│   ├── submit_conditional_order.rs
│   ├── cancel_order.rs
│   ├── cancel_conditional_order.rs
│   ├── deposit.rs
│   └── withdraw.rs
├── vault/                  # Vault (LP) operations
│   ├── add_liquidity.rs
│   ├── remove_liquidity.rs
│   └── refresh.rs          # Vault market-making order placement
├── maintain/               # Maintenance operations
│   ├── configure.rs        # Parameter updates (owner-only)
│   └── liquidate.rs        # Forced position closeout
├── referral/               # Referral system
├── volume.rs               # Trading volume accumulation
├── position_index.rs       # Position tracking by entry price
└── liquidity_depth.rs      # Order book depth aggregation

State layout

Global state:

#![allow(unused)]
fn main() {
STATE: Item<State> {
    last_funding_time: Timestamp,
    vault_share_supply: Uint128,
    insurance_fund: UsdValue,      // Covers bad debt from liquidations
    treasury: UsdValue,            // Accumulated protocol fees
}

PARAM: Item<Param> {
    max_unlocks: u32,
    max_open_orders: u32,
    maker_fee_rates: RateSchedule,      // Volume-tiered schedule
    taker_fee_rates: RateSchedule,
    protocol_fee_rate: Udec128,         // Fraction of fees → treasury
    liquidation_fee_rate: Udec128,
    liquidation_buffer_ratio: Udec128,
    funding_period: Duration,
    vault_total_weight: Udec128,
    vault_cooldown_period: Duration,
    referral_active: bool,
    min_referrer_volume: UsdValue,
    referrer_commission_rates: RateSchedule,
    vault_deposit_cap: Option<UsdValue>,
}
}

Per-pair state:

#![allow(unused)]
fn main() {
PAIR_PARAMS: Map<&PairId, PairParam> {
    tick_size, min_order_size, max_abs_oi,
    max_abs_funding_rate,
    initial_margin_ratio,               // 1/leverage (e.g., 0.1 = 10x)
    maintenance_margin_ratio,           // Liquidation trigger
    impact_size,                        // Notional for impact price sampling
    vault_liquidity_weight,             // Fraction of vault margin allocated
    vault_half_spread,                  // Base bid-ask spread around oracle
    vault_max_quote_size,               // Max single-side vault order size
    vault_size_skew_factor,             // Inventory skew → size tilt
    vault_spread_skew_factor,           // Inventory skew → spread tilt
    vault_max_skew_size,                // Skew saturation point
    bucket_sizes: BTreeSet<UsdPrice>,   // Liquidity depth granularities
}

PAIR_STATES: Map<&PairId, PairState> {
    long_oi,                            // Total long open interest
    short_oi,                           // Total short open interest (abs)
    funding_per_unit,                   // Cumulative funding accumulator
    funding_rate,                       // Current per-day rate (clamped)
}
}

Per-user state:

#![allow(unused)]
fn main() {
USER_STATES: IndexedMap<Addr, UserState> {
    margin: UsdValue,                   // Deposited collateral (USDC)
    vault_shares: Uint128,              // LP shares owned
    positions: BTreeMap<PairId, Position>,
    unlocks: VecDeque<Unlock>,          // Pending vault withdrawals
    reserved_margin: UsdValue,          // Collateral reserved for resting orders
    open_order_count: u32,              // Resting limit order count
}

Position {
    size: Int128,                       // Positive=long, negative=short
    entry_price: UsdPrice,
    entry_funding_per_unit: Dec128,
    conditional_order_above: Option<ConditionalOrder>,
    conditional_order_below: Option<ConditionalOrder>,
}
}

Order book:

#![allow(unused)]
fn main() {
BIDS: IndexedMap<OrderKey, LimitOrder>   // OrderKey = (PairId, Price, OrderId)
ASKS: IndexedMap<OrderKey, LimitOrder>

// ADL position tracking (sorted by entry price for selection)
LONGS: Set<(PairId, UsdPrice, Addr)>
SHORTS: Set<(PairId, UsdPrice, Addr)>
}

Other state:

#![allow(unused)]
fn main() {
VOLUMES: Map<(Addr, Timestamp), UsdValue>  // Per-user per-day volume
REFEREE_TO_REFERRER: Map<UserIndex, UserIndex>
FEE_SHARE_RATIO: Map<UserIndex, FeeShareRatio>
COMMISSION_RATE_OVERRIDES: Map<UserIndex, CommissionRate>
}

Critical flows

Order submission (trade/submit_order.rs)

1. Load user state and pair state/params.
2. Validate: minimum size (or reduce-only exempt), tick alignment, slippage vs oracle (market orders), max open orders.
3. Decompose order into closing portion (vs existing position) and opening portion (new risk).
4. For opening portion: check OI constraints (long_oi + size ≤ max_abs_oi) and initial margin (available_margin ≥ required).
5. Match against resting orders in the order book (which may include orders placed by the vault or by other traders).
6. For fills: compute trading fee (volume-tiered), apply funding (entry_funding_per_unit = current), settle PnL.
7. Resting (unfilled) portion: reserve margin, place on book with TP/SL children.
8. Post-trade validation: available_margin ≥ 0 (reverts entire order otherwise).

Funding (cron.rs → core/funding.rs)

1. Sample order book impact prices (best bid/ask for impact_size notional).
2. Compute midpoint premium vs oracle price.
3. Clamp to max_abs_funding_rate per day, scale by elapsed time.
4. Update pair_state.funding_per_unit += delta.
5. Funding settles lazily on position close: accrued = size × (current_cumulative - entry_cumulative).

Liquidation (maintain/liquidate.rs)

1. Compute equity = margin + Σ(unrealized_pnl) - Σ(accrued_funding).
2. Compute maintenance margin = Σ(|size| × price × mm_ratio).
3. If equity < maintenance_margin: a. Cancel all resting orders (refund reserved margin). b. Close enough of the user’s positions to restore equity ≥ maintenance_margin (with a buffer controlled by liquidation_buffer_ratio). Not all positions are necessarily closed. c. Positions are closed against resting orders in the book at the target price. Only if there is insufficient book liquidity within the target price does the engine resort to auto-deleveraging (ADL) against profitable counter-parties. d. Collect liquidation fee → insurance fund. e. Cover any remaining bad debt from insurance fund.

Vault (LP) system (vault/)

The vault acts as a passive market maker, placing orders around the oracle price:

• Share price: vault_equity / vault_shares + VIRTUAL_ASSETS / VIRTUAL_SHARES (ERC-4626-style virtual shares prevent share inflation attacks).
• Add liquidity: Mint shares at current share price. Slippage-protected via min_shares_to_mint.
• Remove liquidity: Burn shares, queue withdrawal for vault_cooldown_period.
• Quoting: Inventory-based skew tilts bid/ask sizes and spreads to manage directional exposure.

bid_price = oracle × (1 - half_spread × (1 - skew × spread_skew_factor))
ask_price = oracle × (1 + half_spread × (1 + skew × spread_skew_factor))

skew = vault_inventory / vault_max_skew_size  [clamped to [-1, 1]]

Access control

8. Gateway (dango/exchange/gateway/)

Bridge aggregator for cross-chain token transfers.

State

Cross-chain flow

Inbound: Remote bridge delivers tokens → gateway mints wrapped tokens → transfers to recipient (or orphaned transfer if contract not deployed).

Outbound: User sends tokens to gateway → rate limit check → withdrawal fee deducted → local tokens burned → cross-chain message sent.

Rate limiting

#![allow(unused)]
fn main() {
RateLimit = Bounded<Udec128, ZeroInclusiveOneExclusive>
// e.g., 0.1 = max 10% of supply per period
}

Trust model

Trusts Hyperlane validators/ISM. Governance controls bridge configuration, fees, and rate limits.

9. Vesting (dango/exchange/vesting/)

Token vesting with linear schedules and optional cliffs.

State

10. Upgrade (dango/exchange/upgrade/)

Handles state migrations during chain upgrades. Example: migrating PairParam to add new vault skew fields with zero defaults.

11. Inter-Contract Interaction Map

┌──────────────┐  RegisterUser ┌──────────┐  mint   ┌──────┐
│ Account      │◄──────────────│ Account  │────────►│ Bank │
│ (per user)   │               │ Factory  │         │      │
└──────────────┘               └────┬─────┘         └──┬───┘
                                    │ referral         │
                                    ▼                  │
                              ┌──────────┐             │
                              │  Perps   │◄────────────┘ force_transfer
                              │          │  (PnL settlement)
                              └────┬─────┘
                                   │ query prices
                                   ▼
                              ┌──────────┐
                              │  Oracle  │
                              └──────────┘

Key interaction patterns:

• Perps ↔ Bank: Force-transfers for margin deposits/withdrawals and PnL settlement.
• Perps → Oracle: Price queries with staleness checks.
• Account Factory → Perps: Referral registration on user creation.
• Account → Factory: Key and nonce lookups during authentication.

12. Security-Relevant Properties

Invariants to verify

1. Bank solvency: Σ(BALANCES[addr][denom]) = SUPPLIES[denom] for all denoms.
2. Perps margin: For any non-liquidatable user, equity ≥ maintenance_margin.
3. OI balance: pair_state.long_oi - pair_state.short_oi = Σ(positions.size) across all users for each pair.
4. Vault shares: STATE.vault_share_supply = Σ(user_state.vault_shares).
5. Reserved margin consistency: user_state.reserved_margin = Σ(resting_order.margin_required) for that user.
6. Order count: user_state.open_order_count = count of resting orders for that user.

Trust boundaries within Dango

Indexer and Node Architecture

This chapter covers the indexer pipeline, SQL schema, GraphQL API, and the Dango CLI that wires everything together.

1. Indexer Design

The indexer is a read-only, non-consensus component that observes state transitions and writes structured data to external databases. It cannot affect consensus – its operations run after transaction execution and are never on the critical path for state commitment.

Indexer trait

#![allow(unused)]
fn main() {
// dango/core/app/src/traits/indexer.rs
#[async_trait]
pub trait Indexer: Send + Sync {
    async fn start(&mut self, storage: &dyn Storage) -> IndexerResult<()>;
    async fn shutdown(&mut self) -> IndexerResult<()>;
    async fn pre_indexing(&self, block_height: u64) -> IndexerResult<()>;
    async fn index_block(&self, block: &Block, outcome: &BlockOutcome) -> IndexerResult<()>;
    async fn post_indexing(&self, block_height: u64, cfg: Config, app_cfg: Json) -> IndexerResult<()>;
    async fn wait_for_finish(&self) -> IndexerResult<()>;
    async fn last_indexed_block_height(&self) -> IndexerResult<Option<u64>>;
}
}

Call sequence in FinalizeBlock

1. pre_indexing()     ← BEFORE transaction execution
2. Execute all txs
3. Execute cronjobs
4. Remove orphaned codes
5. db.flush_but_not_commit()  ← State root computed
6. index_block()      ← AFTER execution, BEFORE commit
7. [Commit happens separately in do_commit()]
8. post_indexing()    ← AFTER commit, spawned as async task

Security properties:

• Pre-indexing runs before any state mutation – indexer cannot influence tx execution.
• State root is computed before index_block() – indexer cannot affect app_hash.
• Post-indexing is async and non-blocking – indexer errors don’t halt the chain.
• Pre-indexing and index_block errors are fatal (halt block processing).

HookedIndexer (composition)

dango/indexer/hooked/ is the single Indexer impl that the chain wires into App. It owns the three production indexer components by value and orchestrates their per-block work:

#![allow(unused)]
fn main() {
pub struct HookedIndexer {
    pub file:       dango_indexer_cache::Cache,
    pub sql:        dango_indexer_sql::Indexer,
    pub clickhouse: dango_indexer_clickhouse::Indexer,
    // …plus an `is_running` flag and a per-block `post_indexing` task map.
}
}

The data flow is expressed through typed method arguments: Cache::post_indexing returns a BlockAndBlockOutcomeWithHttpDetails payload, which HookedIndexer then hands to SqlIndexer::post_indexing and ClickhouseIndexer::post_indexing in sequence. Each block’s post_indexing runs on its own tokio task so SQL and Clickhouse writes do not block consensus; wait_for_finish drains the task map before shutdown.

The “Hooked” name is historical — earlier revisions held a dynamic Arc<RwLock<Vec<Box<dyn Indexer>>>> and passed data between entries through an opaque http::Extensions-based context. The current shape is the three concrete fields above, but the crate and struct name are kept so deploy scripts and imports do not need to churn.

2. SQL Indexer (dango/indexer/sql/)

Schema

Indexes exist on block_height, hash, sender, contract_addr, and events.data (JSON).

HTTP request tracking

Each transaction records the HTTP peer that submitted it:

#![allow(unused)]
fn main() {
pub struct HttpRequestDetails {
    pub remote_ip: Option<String>,
    pub peer_ip: Option<String>,
    pub created_at: u64,
}
}

Persistence properties

• Idempotent: save_block() checks if the block already exists before inserting (safe for crash recovery).
• Atomic: All table writes within a single database transaction.
• Batch-safe: Inserts batched to 2,048 rows to respect PostgreSQL argument limits.

Event cache

An in-memory ring buffer of recent block events (dango/indexer/sql/src/event_cache.rs). Configurable window size. Used for fast GraphQL lookups without DB round-trips.

3. Cache Indexer (dango/indexer/cache/)

Persists complete block + outcome data to disk for recovery:

~/.dango/indexer/blocks/{height}.json  -- Serialized block data
~/.dango/indexer/last_block.json       -- Latest block height

4. Dango-Specific Writes (dango/indexer/sql/src/write/)

The SQL indexer crate also performs Dango-specific data extraction in the same post_indexing pass, after the generic block/tx/message/event rows have been written:

#![allow(unused)]
fn main() {
// Runs in SqlIndexer::post_indexing (async, non-blocking)
let (transfers, accounts, perps) = tokio::join!(
    crate::write::transfers::save_transfers(&self.context, block_height),
    crate::write::accounts::save_accounts(&self.context, block, app_cfg.clone()),
    crate::write::perps_events::save_perps_events(&self.context, block, app_cfg),
);
}

Two sea-orm migration tables are kept side by side in the same database (grug_seaql_migrations and dango_seaql_migrations) so existing prod data does not need to be migrated.

Extracts:

• Account events: UserRegistered, AccountRegistered, KeyOwned, KeyDisowned → accounts, users, public_keys tables.
• Transfer events: Bank transfer events → transfers table.
• Perps events: Trade execution, funding, liquidation → perps_events table.

Only processes committed events from successful transactions.

5. GraphQL / HTTP Server (dango/indexer/httpd/)

Actix-web HTTP server with async-graphql:

Query types

• block(height) / blocks(first, after) – Block headers with nested transactions and events.
• transaction(hash) / transactions(first, after) – Tx metadata with nested messages and events.
• events(filter) – Event queries with JSON data filtering.

Subscriptions

Real-time subscriptions via PostgreSQL LISTEN/NOTIFY:

• blockMinted – New blocks.
• transactionProcessed – New transactions.
• eventEmitted – New events.

Data loaders

N+1 query prevention via dataloaders:

• BlockTransactionsDataLoader, BlockEventsDataLoader
• TransactionEventsDataLoader, TransactionMessagesDataLoader
• EventTransactionDataLoader, FileTransactionDataLoader

6. Node Startup (dango/cli/)

The dango start command initializes and runs the full node:

1.  Parse CLI args and config
2.  Initialize telemetry (Sentry + OpenTelemetry)
3.  Initialize metrics (Prometheus)
4.  Open DiskDb (RocksDB)
5.  Create RustVm
6.  Create base App
7.  Setup indexer stack (HookedIndexer with three components):
    ├── Cache (disk persistence)
    ├── SqlIndexer (PostgreSQL — generic + Dango-specific tables)
    └── ClickhouseIndexer (analytics)
8.  Run DB migrations + catch-up reindexing
9.  Spawn:
    ├── Dango HTTP server (GraphQL)
    ├── Metrics HTTP server (Prometheus)
    └── ABCI server (CometBFT connection)
10. Signal handlers (SIGINT, SIGTERM)

ABCI server split

The app is split into four ABCI service components:

• Consensus: FinalizeBlock, Commit
• Mempool: CheckTx
• Snapshot: State sync
• Info: Query, simulation

Graceful shutdown

1. Set HTTP shutdown flags (return 503 for new requests).
2. Wait 100ms for propagation.
3. Shutdown indexer (wait for async tasks to complete).
4. Flush telemetry (Sentry, OpenTelemetry).

7. Security Analysis

Trust boundaries

┌────────────────────────────────────────────────────────┐
│ Consensus-Critical (ABCI)                              │
│  App + DB + VM                                         │
│  Indexer trait called but read-only                    │
│  State root determined before indexer writes           │
└────────────────── ▼ ───────────────────────────────────┘
                    │ Block + Outcome
┌───────────────────┴────────────────────────────────────┐
│ Non-Consensus (Indexer Stack)                          │
│  Cache → disk                                          │
│  SqlIndexer → PostgreSQL (generic + Dango tables)      │
│  ClickhouseIndexer → analytics DB                      │
└────────────────── ▼ ───────────────────────────────────┘
                    │
┌───────────────────┴────────────────────────────────────┐
│ Public API (GraphQL/HTTP)                              │
│  Read-only queries over indexed data                   │
│  No state mutation capability                          │
└────────────────────────────────────────────────────────┘

Network exposure

Known gaps

• No GraphQL query complexity limits. Deeply nested or expensive queries could DoS the HTTP server.
• No HTTP rate limiting. Any client can issue unlimited queries.
• Event JSON size unbounded. Malicious contracts could emit large events, inflating the database.
• IP logging without TTL. Transaction origin IPs stored indefinitely.

Previous Audits

A list of audits we have completed so far:

Margin

1. Overview

All trader margin is held internally in the perps contract as a USD value on each user’s userState.

Internal logics of the perps contract use USD amounts exclusively. Token conversion only happens at two boundaries:

• Deposit — the user sends settlement currency (USDC) to the perps contract; the oracle price converts the token amount to USD and credits userState.margin.
• Withdraw — the user requests a USD amount; the oracle price converts it to settlement currency tokens (floor-rounded) and transfers them out.

2. Trader Deposit

The user sends settlement currency as attached funds. The perps contract:

1. Values the settlement currency at a fixed $1 per unit (no oracle lookup).
2. Converts the token amount to USD: $\mathtt{depositValue}=\mathtt{amount}\times 1$.
3. Increment userState.margin by $\mathtt{depositValue}$.

The tokens remain in the perps contract’s bank balance.

3. Trader Withdraw

The user specifies how much USD margin to withdraw. The perps contract:

1. Computes $\mathtt{availableMargin}$ (see §8), clamped to zero.
2. Ensures the requested amount does not exceed $\mathtt{availableMargin}$.
3. Deducts the amount from userState.margin.
4. Converts USD to settlement currency tokens at the fixed $1 rate (floor-rounded to base units).
5. Transfers the tokens to the user.

4. Equity

A user’s equity (net account value) is:

$$\mathtt{equity}=\mathtt{collateralValue}+\sum \mathtt{unrealisedPnl}-\sum \mathtt{accruedFunding}$$

where $\mathtt{collateralValue}$ is the USD value of the user’s deposited margin (userState.margin).

Per-position unrealised PnL is:

$$\mathtt{unrealisedPnl}=\mathtt{size}\times (\mathtt{oraclePrice}-\mathtt{entryPrice})$$

and accrued funding is:

$$\mathtt{accruedFunding}=\mathtt{size}\times (\mathtt{fundingPerUnit}-\mathtt{entryFundingPerUnit})$$

Positive accrued funding is a cost to the trader (subtracted from equity). Refer to Funding for details on the funding rate.

5. Initial margin (IM)

$$\mathtt{IM}=\sum |\mathtt{size}|\times \mathtt{oraclePrice}\times \mathtt{imr}$$

where $\mathtt{imr}$ is the per-pair initial margin ratio. IM is the minimum equity required to open or hold positions. It is used in two places:

• Pre-match margin check — verifies the taker can afford the worst-case 100 % fill (see Order matching §5).
• Available margin calculation — determines how much can be withdrawn or committed to new limit orders (see §8 below).

When checking a new order the IM is computed with a projected size: the user’s current position in that pair is replaced by the hypothetical post-fill position ($\mathtt{currentSize}+\mathtt{orderSize}$). Positions in other pairs use their actual sizes.

6. Maintenance margin (MM)

$$\mathtt{MM}=\sum |\mathtt{size}|\times \mathtt{oraclePrice}\times \mathtt{mmr}$$

where $\mathtt{mmr}$ is the per-pair maintenance margin ratio (always $\le \mathtt{imr}$). A user becomes eligible for liquidation when:

$$\mathtt{equity}<\mathtt{MM}$$

See Liquidation for details.

7. Reserved margin

When a GTC limit order is placed, margin is reserved for the worst-case scenario (the entire order is opening):

$$\mathtt{reservedPerOrder}=|\mathtt{openingSize}|\times \mathtt{limitPrice}\times \mathtt{imr}$$

The user’s total $\mathtt{reservedMargin}$ is the sum across all resting orders. Reserved margin is released proportionally as orders fill and fully released on cancellation. Reduce-only orders reserve zero margin (they can only close).

See Order matching §10 for when reservation occurs.

8. Available margin

$$\mathtt{available}=\max (0,\mathtt{equity}-\mathtt{usedMargin}-\mathtt{reservedMargin})$$

where $\mathtt{usedMargin}$ is the IM of current positions (§5 formula applied to actual sizes, without any projection). This determines how much can be withdrawn (§3) or committed to new limit orders.

Order Matching

This chapter describes how orders are submitted, matched, filled, and settled in the on-chain perpetual futures order book.

1. Order types

An order can be order:

• Market — immediate-or-cancel (IOC). Specifies a max_slippage relative to the oracle price. Any unfilled remainder after matching is discarded (unless nothing filled at all, which is an error).
• Limit — specifies a limit_price and a time_in_force:
  • GTC (default): any unfilled remainder is stored as a resting order on the book.
  • IOC: fills as much as possible, then discards the unfilled remainder. Errors if nothing fills.
  • Post-only: the order is to be inserted into the book without entering the matching engine. Reject if it would cross the best price on the opposite side.

Resting orders on the book are stored as:

The pair ID, order ID, and limit price are part of the storage key.

2. Order decomposition

Before matching, every fill is decomposed into a closing and an opening portion based on the user’s current position:

Both closing and opening carry the same sign as the original order size (or are zero). For reduce-only orders, the opening portion is forced to zero — if the resulting fillable size is zero, the transaction is rejected.

3. Target price

The target price defines the worst acceptable execution price for the taker:

Market orders (bid/buy):

$$\mathtt{targetPrice}=\mathtt{oraclePrice}\times (1+\mathtt{maxSlippage})$$

Market orders (ask/sell):

$$\mathtt{targetPrice}=\mathtt{oraclePrice}\times (1-\mathtt{maxSlippage})$$

Limit orders: $\mathtt{targetPrice}=\mathtt{limitPrice}$ (oracle price is ignored).

The user-supplied $\mathtt{maxSlippage}$ on a market order is bounded by the per-pair cap max_market_slippage — see §3b.

A price constraint is violated when:

• Bid: $\mathtt{execPrice}>\mathtt{targetPrice}$
• Ask: $\mathtt{execPrice}<\mathtt{targetPrice}$

3a. Price banding for limit orders

Every limit order (GTC, IOC, or post-only) must have a limit_price within a per-pair symmetric deviation of the oracle price at submission. Concretely:

$$|\mathtt{limitPrice}-\mathtt{oraclePrice}|\le \mathtt{oraclePrice}\times \mathtt{maxLimitPriceDeviation}$$

where $\mathtt{maxLimitPriceDeviation}$ is a per-pair parameter in $(0,1)$. Equivalently, the limit price must fall inside

$$[\mathtt{oraclePrice}\times (1-\mathtt{maxLimitPriceDeviation}),\mathtt{oraclePrice}\times (1+\mathtt{maxLimitPriceDeviation})]$$

An order whose price falls outside this band is rejected at submission, before matching begins. The check is applied identically to GTC, IOC, and post-only limit orders.

3b. Market-order slippage cap

Each market order must have a max_slippage within a per-pair max_market_slippage constraint at submission:

$$\mathtt{maxSlippage}\le \mathtt{maxMarketSlippage}$$

The same cap applies to max_slippage on TP/SL child orders (attached to a parent submit order or placed as standalone conditional orders), which become market orders when triggered.

Conditional-order staleness. It is possible that when a conditional order is submitted, its max_slippage falls within the max_market_slippage constraint, but when triggered, governance has tightened the constaint such that it is no longer compliant. In this case, the conditional order is canceled with reason = SlippageCapTightened.

4. Matching engine

The matching engine iterates the opposite side of the book in price-time priority:

• A bid (buy) walks the asks in ascending price order (cheapest first).
• An ask (sell) walks the bids in descending price order (most expensive first). Bids are stored with bitwise-NOT inverted prices so that ascending iteration over storage keys yields descending real prices.

At each resting order the engine checks two termination conditions:

1. $\mathtt{remainingSize}=0$ — the taker is fully filled.
2. The resting order’s price violates the taker’s price constraint.

If neither condition is met, the fill size is:

$$\mathtt{takerFillSize}=\{\begin{array}{ll}\min (\mathtt{remainingSize},\mathtt{makerSize})& \text{if bid (both positive)}\\ \max (\mathtt{remainingSize},\mathtt{makerSize})& \text{if ask (both negative)}\end{array}$$

$$\mathtt{makerFillSize}=-\mathtt{takerFillSize}$$

After each fill the maker order is updated: reserved margin is released proportionally, and if fully filled the order is removed from the book and open_order_count is decremented.

5. Pre-match margin check

Before matching begins, the taker’s margin is verified (skipped for reduce-only orders). The check ensures the user can afford the worst case — a 100 % fill:

$$\mathtt{equity}\ge \mathtt{projectedIM}+\mathtt{projectedFee}+\mathtt{reservedMargin}$$

where $\mathtt{projectedIM}$ is the initial margin assuming the full order fills (see Margin §5) and $\mathtt{projectedFee}$ is

$$|\mathtt{size}|\times \mathtt{oraclePrice}\times \mathtt{takerFeeRate}$$

This prevents a taker from submitting orders they cannot collateralise.

Maker order re-checks

When a maker order with an eligible price is encountered, the matching engine performs two check before executing filling:

6a. Self-trade prevention

The exchange uses EXPIRE_MAKER mode. When the taker encounters their own resting order on the opposite side:

1. The maker (resting) order is cancelled (removed from the book).
2. The taker’s open_order_count and reserved_margin are decremented.
3. The taker continues matching deeper in the book — no fill occurs for the self-matched order.

6b. Price-banding

The submission-time band (§3a) only inspects the price at the moment of placement. Between placement and matching, the oracle may move far enough that a previously in-band resting order is now outside the band relative to the current oracle.

To address this, the matching engine applies a band re-check on every resting maker it walks. For each maker encountered during the walk, the engine evaluates the §3a band against the current oracle price. If the maker’s resting price is outside the band, it is canceled with reason = PriceBandViolation.

7. Fill execution

Each fill between taker and maker is executed as follows:

7a. Funding settlement

Accrued funding is settled on the user’s existing position before the fill:

$$\mathtt{accruedFunding}=\mathtt{size}\times (\mathtt{fundingPerUnit}-\mathtt{entryFundingPerUnit})$$

The negated accrued funding is added to the user’s PnL (positive accrued funding is a cost to longs).

7b. Closing PnL

For the closing portion of the fill:

Long closing (selling to close):

$$\mathtt{pnl}=|\mathtt{closingSize}|\times (\mathtt{fillPrice}-\mathtt{entryPrice})$$

Short closing (buying to close):

$$\mathtt{pnl}=|\mathtt{closingSize}|\times (\mathtt{entryPrice}-\mathtt{fillPrice})$$

The position size is reduced by the closing amount. If the position is fully closed, it is removed from state.

7c. Opening position

For the opening portion of the fill:

• New position: entry price is set to the fill price.
• Existing position (same direction): entry price is blended as a weighted average:

$$\mathtt{entryPrice}\leftarrow \frac{|\mathtt{oldSize}|\times \mathtt{oldEntry}+|\mathtt{openingSize}|\times \mathtt{fillPrice}}{|\mathtt{newSize}|}$$

7d. OI update

Open interest is updated per side:

• Closing a long: $\mathtt{longOI}-=|\mathtt{closingSize}|$
• Closing a short: $\mathtt{shortOI}-=|\mathtt{closingSize}|$
• Opening a long: $\mathtt{longOI}+=|\mathtt{openingSize}|$
• Opening a short: $\mathtt{shortOI}+=|\mathtt{openingSize}|$

8. Trading fees

Fees are charged on every fill:

$$\mathtt{fee}=|\mathtt{fillSize}|\times \mathtt{fillPrice}\times \mathtt{feeRate}$$

The fee rate differs by role:

Fees are always positive (absolute value of fill size is used). They are routed to the vault via the settlement loop described below.

9. PnL settlement

After all fills in an order are complete, PnLs and fees are settled atomically as in-place USD margin adjustments. No token conversions occur during settlement — all values are pure UsdValue arithmetic.

9a. Fee loop

For each non-vault user with a non-zero fee:

$$userState.margin-=\mathtt{fee}$$

$$state.vaultMargin+=\mathtt{fee}$$

Fees from the vault to itself are skipped (no-op). Processing fees first ensures collected fees augment $\mathtt{vaultMargin}$ before any vault losses are absorbed.

9b. PnL loop

Non-vault users:

$$userState.margin+=\mathtt{pnl}$$

A user’s margin can go negative temporarily — the outer function handles bad debt (see Liquidation).

Vault:

$$\mathtt{vaultMargin}+=\mathtt{pnl}$$

A negative $\mathtt{vaultMargin}$ represents a deficit (bad debt not yet recovered via ADL).

10. Unfilled remainder

After matching completes:

• Market orders and IOC limit orders: the unfilled remainder is silently discarded. If nothing was filled at all, the transaction reverts with “no liquidity at acceptable price”.
• GTC limit orders: the unfilled remainder is stored as a resting order. Storage requires:
  • open_order_count < max_open_orders
  • Price is aligned to the pair’s tick size ($\mathtt{limitPrice}\mathrm{mod}\mathtt{tickSize}=0$)
  • Sufficient available margin (skipped for reduce-only orders) — see below

Margin reservation (non-reduce-only):

The unfilled portion’s margin requirement is computed and checked against available margin (see Margin §7–§8):

$$\mathtt{marginToReserve}=|\mathtt{openingSize}|\times \mathtt{limitPrice}\times \mathtt{imr}$$

$$\mathtt{availableMargin}\ge \mathtt{marginToReserve}$$

If the check passes, reserved_margin is increased by $\mathtt{marginToReserve}$ and open_order_count is incremented. This is the 0 %-fill scenario check — it ensures the user can afford the order even if nothing fills immediately.

Post-only limit orders take a fast path that bypasses the matching engine entirely. They are rejected if they would cross the best price on the opposite side:

• Buy: $\mathtt{limitPrice}\ge \mathtt{bestAsk}$
• Sell: $\mathtt{limitPrice}\le \mathtt{bestBid}$

If the opposite book is empty, the order always succeeds.

11. Open interest constraint

Each pair has a $\mathtt{maxAbsOI}$ parameter enforcing a per-side cap:

• Long opening: $\mathtt{longOI}+\mathtt{openingSize}\le \mathtt{maxAbsOI}$
• Short opening: $\mathtt{shortOI}+|\mathtt{openingSize}|\le \mathtt{maxAbsOI}$

The constraint is checked before matching and does not apply to reduce-only orders (which have zero opening size). Long and short OI limits are independent but share the same $\mathtt{maxAbsOI}$ parameter.

12. Order cancellation

Single cancel

A user can cancel any individual resting order by its order ID.

On cancellation:

1. The order is removed from the book.
2. reserved_margin is released (subtracted from the user’s total).
3. open_order_count is decremented.
4. If the user state is now empty (no positions, no open orders, no pending unlocks), it is deleted from storage.

Bulk cancel

A user can cancel all of their resting orders across both sides of the book in a single transaction. The contract iterates the user’s resting orders, removing each one and releasing margin. The same cleanup logic applies — if the user state becomes empty after all orders are removed, it is deleted.

Funding

Fundings are periodic payments between longs and shorts that anchor the perpetual contract price to the oracle. When the market trades above the oracle, longs pay shorts; when below, shorts pay longs. This mechanism discourages persistent deviations from the spot price without requiring contract expiry.

1. Premium

Each funding cycle begins with measuring how far the on-chain book has drifted from the oracle. The contract computes two impact prices by walking the book, takes their midpoint, and compares it to the oracle:

• Impact bid — the volume-weighted average price (VWAP) obtained by selling $\mathtt{impactSize}$ worth of base asset into the bid side.
• Impact ask — the VWAP obtained by buying $\mathtt{impactSize}$ worth from the ask side.

The premium is then:

$$\mathtt{midImpactPrice}=\frac{\mathtt{impactBid}+\mathtt{impactAsk}}{2}$$

$$\mathtt{premium}=\frac{\mathtt{midImpactPrice}-\mathtt{oracle}}{\mathtt{oracle}}$$

If a side of the book has less than $\mathtt{impactSize}$ of depth, the walk returns the VWAP of whatever depth is available. If a side has no depth at all, the sample is skipped for that cycle rather than a one-sided mid being computed. In steady state both sides are always populated by the vault.

2. Sampling

A cron job runs frequently (e.g. every minute). Each invocation samples the premium for every active pair and accumulates it into the pair’s state:

$$\mathtt{premiumSum}+=\mathtt{premium}$$

$$\mathtt{premiumSamples}+=1$$

Sampling at a cadence close to the block rate gives each observation roughly equal weight. A resting order that momentarily drags the mid can only influence the average in proportion to how long it sits on the book relative to the full funding period.

3. Collection

When $\mathtt{fundingPeriod}$ has elapsed since the last collection, the same cron invocation finalises the funding rate:

1. Average premium:

   $$\mathtt{avgPremium}=\mathtt{premiumSum}/\mathtt{premiumSamples}$$

2. Clamp to the configured bounds:

   $$\mathtt{rate}=\mathrm{clamp}(\mathtt{avgPremium},[-\mathtt{maxAbsFundingRate},+\mathtt{maxAbsFundingRate}])$$

3. Funding delta — scale by the actual elapsed interval and oracle price:

   $$\mathtt{fundingDelta}=\mathtt{rate}\times \mathtt{interval}\times \mathtt{oraclePrice}$$

4. Accumulate into the pair-level running total:

   $$\mathtt{fundingPerUnit}+=\mathtt{fundingDelta}$$

5. Reset accumulators: $\mathtt{premiumSum}\leftarrow 0$, $\mathtt{premiumSamples}\leftarrow 0$, $\mathtt{lastFundingTime}\leftarrow \mathtt{now}$.

4. Position-level settlement

Accrued funding is settled on a position whenever it is touched — during a fill, liquidation, or ADL event:

$$\mathtt{accruedFunding}=\mathtt{size}\times (\mathtt{fundingPerUnit}-\mathtt{entryFundingPerUnit})$$

After settlement the entry point is reset:

$$\mathtt{entryFundingPerUnit}\leftarrow \mathtt{fundingPerUnit}$$

Sign convention: positive accrued funding is a cost to the holder (longs pay when the rate is positive, shorts pay when it is negative). The negated accrued funding is added to the user’s realised PnL. See Order matching §7a and Vault §4 for how this integrates with fill execution and vault accounting.

5. Parameters

6. Discussions

Vault being the sole maker

As of today, the protocol-owned vault is the dominant maker in Dango’s markets. The vault’s inventory-skew-aware quoting policy causes the book mid to drift from the oracle whenever the vault holds inventory:

$$\mathtt{vaultBid}=\mathtt{oracle}\cdot (1-\mathtt{halfSpread}\cdot (1+\mathtt{skew}\cdot \mathtt{spreadSkewFactor}))$$

$$\mathtt{vaultAsk}=\mathtt{oracle}\cdot (1+\mathtt{halfSpread}\cdot (1-\mathtt{skew}\cdot \mathtt{spreadSkewFactor}))$$

Suppose the vault is literally the only maker in the entire market, we can substitute the vault’s bid and ask into the $\mathtt{midImpactPrice}$ formula:

$$\mathtt{midImpactPrice}=\mathtt{oracle}\cdot (1-\mathtt{halfSpread}\cdot \mathtt{skew}\cdot \mathtt{spreadSkewFactor})$$

and therefore

$$\mathtt{premium}=-\mathtt{halfSpread}\cdot \mathtt{skew}\cdot \mathtt{spreadSkewFactor}\cdot \mathtt{fundingRateMultiplier}$$

Positive skew (vault long, because sell flow has dominated) produces a negative premium, so longs receive funding from shorts — which credits the vault-as-long for absorbed inventory. Symmetric when short. The sign is economically correct by construction.

The closed-form also tethers funding to the vault’s quoting parameters: tightening spreads to compete for flow would otherwise shrink funding by the same factor. $\mathtt{fundingRateMultiplier}$ is a per-pair governance knob that decouples these two — admins can dial funding up or down (e.g. in response to persistent one-sided skew) without touching $\mathtt{halfSpread}$ or $\mathtt{spreadSkewFactor}$ and therefore without changing the vault’s quoted prices. $\mathtt{fundingRateMultiplier}=1$ is the identity and matches the pre-multiplier formulation; $0$ disables funding entirely.

Comparison with other exchanges

The “book mid minus oracle” premium is the dominant on-chain perpetual-funding pattern — see Drift (bid/ask TWAP mid vs oracle TWAP), Vertex (mark vs spot index), Paradex (Fair Basis from mark), and MCDEX v2 (AMM mid vs index). Dango’s formulation differs in reading impact prices (depth-walked VWAPs) rather than top-of-book, which bakes depth distribution into the primitive and forces any book-level manipulation to commit notional proportional to $\mathtt{impactSize}$.

Liquidation & Auto-Deleveraging (ADL)

This document describes how the perpetual futures exchange protects itself from under-collateralised accounts and socialises losses via auto-deleveraging and the insurance fund.

1. Liquidation trigger

Every account has an equity and a maintenance margin (MM):

$$\mathtt{equity}=\mathtt{collateralValue}+\sum \mathtt{unrealisedPnl}-\sum \mathtt{accruedFunding}$$

$$\mathtt{MM}=\sum |\mathtt{positionSize}|\times \mathtt{oraclePrice}\times \mathtt{mmr}$$

where $\mathtt{mmr}$ is the per-pair maintenance-margin ratio. An account becomes liquidatable when

$$\mathtt{equity}<\mathtt{MM}$$

Strict inequality: an account whose equity exactly equals its MM is still safe. An account with no open positions is never liquidatable regardless of its equity.

2. Close schedule

When an account is liquidatable, the system computes the minimum set of position closures needed to restore it above maintenance margin.

1. For every open position, compute its MM contribution:

   $$\mathtt{mmContribution}=|\mathtt{size}|\times \mathtt{oraclePrice}\times \mathtt{mmr}$$

2. Sort positions by MM contribution descending (largest first).

3. Walk the sorted list and close just enough to cover the deficit:

   • $\mathtt{deficit}=\mathtt{MM}-\mathtt{equity}/(1+b)$

     where $b$ is the global liquidation_buffer_ratio (default 0). When $b>0$, positions are closed slightly beyond the maintenance boundary so the user’s post-liquidation equity exceeds their remaining MM by a factor of $(1+b)$, preventing repeated small liquidations from minor adverse price movements.

   • For each position:

     • If $\mathtt{deficit}\le 0$: stop
     • $\mathtt{closeSize}=\min \left(\lceil \frac{\mathtt{deficit}}{\mathtt{oraclePrice}\times \mathtt{mmr}}\rceil ,|\mathtt{size}|\right)$
     • $\mathtt{deficit}-=\mathtt{closeSize}\times \mathtt{oraclePrice}\times \mathtt{mmr}$

This produces a vector of $(\mathtt{pairId},\mathtt{closeSize})$ entries. Each $\mathtt{closeSize}$ has the opposite sign of the existing position (a long is closed with a sell, a short with a buy). Only positions that contribute to the deficit are touched and they may be partially closed when the deficit is small relative to the position.

3. Position closure

Each entry in the close schedule is executed in two phases:

3a. Order book matching

The close is submitted as an immediate-or-cancel (IOC) limit order against the on-chain order book. The order’s limit price is the bankruptcy price (defined in §3b) when the account is solvent ($\mathtt{equity}>0$), or the oracle price when insolvent. It matches resting limit orders at price-time priority. Any filled amount is settled normally (mark-to-market PnL between the entry price and the fill price).

3b. Auto-deleveraging (ADL)

If any quantity remains unfilled after the order book is exhausted, the system automatically deleverages against counter-parties. The unfilled remainder is closed against the most profitable counter-positions at the liquidated user’s bankruptcy price.

Counter-party selection: Positions are indexed by the tuple $(\mathtt{pairId},\mathtt{entryPrice},\mathtt{user})$. For a long being liquidated (selling), the system finds shorts with the highest entry price (most profitable) first. For a short being liquidated (buying), it finds longs with the lowest entry price first.¹

Bankruptcy price: A position’s bankruptcy price (BP) is the fill price at which, if the entire position were closed at it, the user’s total account equity would be exactly zero:

$$\mathtt{bp}=\mathtt{oraclePrice}-\frac{\mathtt{equity}}{|\mathtt{positionSize}|}(\text{for longs})$$

$$\mathtt{bp}=\mathtt{oraclePrice}+\frac{\mathtt{equity}}{|\mathtt{positionSize}|}(\text{for shorts})$$

The divisor is always the position’s full current size, even when the close schedule closes only part of the position. An ADL fill at this price therefore moves exactly $\mathtt{equity}/|\mathtt{positionSize}|$ per unit closed from the user to the counter-party:

• If the user is solvent ($\mathtt{equity}>0$), the BP sits slightly on the favourable side of the oracle for the counter-party (below oracle when closing a long, above when closing a short). The counter-party receives the user’s per-unit equity share as compensation for the forced close; the user keeps the equity attributable to the unclosed remainder, and never goes negative.
• If the user is insolvent ($\mathtt{equity}\le 0$), the BP overshoots the oracle in the user’s favour (above oracle when closing a long, below when closing a short). The counter-party is force-closed at a worse-than-oracle price — it absorbs what would otherwise be bad debt. The close schedule fully closes every position of an insolvent account, so a pure-ADL liquidation leaves the account at exactly zero equity.

ADL does not fill the counter-party’s resting limit orders; their position is force-reduced directly. The shrunken position can, however, cause their resting reduce-only orders to be resized or cancelled, maintaining the invariant that the total size of a user’s reduce-only orders never exceeds their position size.

Liquidation fills (both order-book and ADL) carry zero trading fees for both taker and maker.

Order-book fills during liquidation emit order_filled events with a fill_id just like regular matches (see the events reference); ADL fills do not — they use the separate deleveraged and liquidated events, which carry no fill_id, because ADL is a position transfer at the bankruptcy price rather than an order-book match.

4. Liquidation fee

After all positions in the schedule are closed, a one-time liquidation fee is charged:

$$\mathtt{rawFee}=\mathtt{closedNotional}\times \mathtt{liquidationFeeRate}$$

$$\mathtt{remainingEquity}=\max (0,\mathtt{equityAfterCloses})$$

$$\mathtt{fee}=\min (\mathtt{rawFee},\mathtt{remainingEquity})$$

where $\mathtt{equityAfterCloses}$ is the account’s equity once the scheduled closes are settled — i.e. the post-close margin plus the unrealised PnL of any positions left open.

The fee is deducted from the user’s margin and routed to the insurance fund (not the vault). It is capped at the remaining equity — not margin alone — so the fee itself never drives equity below zero and therefore never creates bad debt. The cap matters precisely when margin and equity diverge: an account can reach liquidation with negative margin but positive equity (its open positions hold unrealised profit), and capping at margin would skip a fee the account can clearly afford; conversely, capping at margin when remaining positions are underwater could charge a fee that pushes equity negative.

5. PnL settlement

All PnL from the liquidation fills (user, book makers, ADL counter-parties) is settled atomically as in-place USD margin adjustments — no token transfers occur. Both user and maker PnL are applied via the same settlement logic described in Order matching §8.

6. Bad debt

After PnL and fee settlement, if the user’s equity is negative the absolute value is bad debt. The account is topped up to exactly zero equity — the bad debt is credited to the user’s margin — and the same amount is subtracted from the insurance fund:

$$\mathtt{badDebt}=|\min (0,\mathtt{equity}\mathtt{after}\mathtt{settlement})|$$

$$user.margin+=\mathtt{badDebt}(\text{so }\mathtt{equity}\leftarrow 0)$$

$$\mathtt{insuranceFund}-=\mathtt{badDebt}$$

Bad debt is a negative-equity condition, not merely a negative margin balance. A cross-margined account can carry negative margin while still solvent when its remaining positions hold unrealised profit (see margin §3); recognising bad debt off the margin sign in that case would transfer insurance-fund value to a solvent user. When the account is fully closed — the normal insolvent path — no positions remain, so equity equals margin and crediting $\mathtt{badDebt}$ is identical to flooring margin to zero.

The insurance fund may go negative. A negative insurance fund represents unresolved bad debt — future liquidation fees will replenish it.

Note: when an insolvent account’s positions are fully ADL’d at their bankruptcy prices — each computed from the account’s equity at the moment that position is processed — the user’s equity is zeroed by construction. Bad debt from ADL fills is therefore zero. Bad debt arises only from book fills at prices worse than the bankruptcy price (e.g., thin order books with deep bids/asks far from oracle); see Example 4.

7. Insurance fund

The insurance fund is a separate pool from the vault that absorbs bad debt and is funded by liquidation fees.

Funding: Every liquidation fee (§4) is credited to the insurance fund.

Usage: Every bad debt event (§6) is debited from the insurance fund.

Negative balance: The insurance fund may go negative when accumulated bad debt exceeds accumulated fees. This is the simplest approach — no special trigger or intervention is needed. Future liquidation fees will naturally replenish the fund.

Other users’ bad debt and liquidation fees never touch the vault’s margin — this isolates liquidity providers from external liquidation losses. However, the vault itself is subject to liquidation like any other account. If the vault’s equity falls below its maintenance margin, its positions are closed following the same procedure described above. The vault’s own liquidation fee goes to the insurance fund, and any bad debt is absorbed by it.

Examples

All examples use:

Cast:

• Alice is the account being liquidated.
• Bob holds the exact opposite position(s), opened against Alice at her entry price — being the most profitable counter-position, he is the ADL counter-party.
• Carol is a third-party maker who supplies order-book liquidity where stated.

Examples 1–6 cover a single position, ordered from the most ideal situation to the least: Alice solvent (1–3) then insolvent (4–6), with the order book absorbing all (1, 4), part (2, 5), or none (3, 6) of the close. Examples 7–8 cover an account with two positions. A final example covers the cross-margin edge case where the account reaches liquidation with negative margin but positive equity — the case the equity caps in §4 and §6 exist for.

All eight numbered examples — plus mirrored variants with the sides flipped — are implemented as end-to-end tests in dango/testing/tests/perps/liquidation_spec.rs, asserting every figure below exactly. The negative-margin edge case is likewise covered by an end-to-end test there.

Example 1 — Solvent; close fully absorbed by the book

Setup

ETH drops to $1,800

Alice’s account

$$\mathtt{equity}=\$2,180+10\times (\$1,800-\$2,000)=\$180$$

$$\mathtt{MM}=10\times \$1,800\times 5\%=\$900$$

$$\$180<\$900\Rightarrow \text{liquidatable (solvent)}$$

Close schedule

$$\mathtt{deficit}=\$900-\$180=\$720$$

$$\mathtt{closeSize}=\lceil \frac{\$720}{\$1,800\times 5\%}\rceil =8\text{ ETH}(\text{partial close; 2 ETH remain})$$

Bankruptcy price

$$\mathtt{bp}=\$1,800-\frac{\$180}{10}=\$1,782$$

Alice is solvent, so the close order’s limit price is the BP.

Execution

Carol’s bid at $1,800 is above the $1,782 limit, so the entire 8 ETH close fills at $1,800. No ADL.

$$\mathtt{AlicePnL}=8\times (\$1,800-\$2,000)=-\$1,600$$

Liquidation fee

$$\mathtt{closedNotional}=8\times \$1,800=\$14,400(\text{valued at the oracle price})$$

$$\mathtt{rawFee}=\$14,400\times 0.1\%=\$14.40$$

$$\mathtt{remainingMargin}=\max (0,\$2,180-\$1,600)=\$580$$

$$\mathtt{fee}=\min (\$14.40,\$580)=\$14.40$$

Final state

No ADL, no bad debt. Alice keeps 2 ETH and equity of $565.60 − 2 × $200 = $165.60.

Example 2 — Solvent; close partially absorbed by the book, remainder ADL’d

Same as Example 1, except Carol’s bid is only 5 ETH @ $1,800.

Execution

• Book: 5 ETH fill Carol’s bid at $1,800.
• ADL: the remaining 3 ETH close against Bob — the most profitable short — at the bankruptcy price, $1,782.

$$\mathtt{AlicePnL}=5\times (\$1,800-\$2,000)+3\times (\$1,782-\$2,000)=-\$1,000-\$654=-\$1,654$$

$$\mathtt{BobPnL}=-3\times (\$1,782-\$2,000)=+\$654$$

Closing 3 ETH at the oracle would have realized $3\times (\$2,000-\$1,800)=\$600$ for Bob; the extra $54 is Alice’s per-unit equity concession, $3\times \$180/10=\$54$.

Liquidation fee

Same closed notional as Example 1 (8 ETH valued at the $1,800 oracle) → fee $14.40.

Final state

No bad debt.

Example 3 — Solvent; book empty, whole close ADL’d

Same as Example 1, but the order book is empty.

Execution

The entire 8 ETH close is ADL’d against Bob at the bankruptcy price, $1,782.

$$\mathtt{AlicePnL}=8\times (\$1,782-\$2,000)=-\$1,744$$

$$\mathtt{BobPnL}=-8\times (\$1,782-\$2,000)=+\$1,744$$

Liquidation fee

$14.40 as before.

Final state

No bad debt: Alice concedes $8\times \$18=\$144$ of her $180 equity to Bob and keeps the rest.

Example 4 — Insolvent; close fully absorbed by the book

Setup

ETH drops to $1,700

Alice’s account

$$\mathtt{equity}=\$2,800+10\times (\$1,700-\$2,000)=-\$200$$

$$\mathtt{MM}=10\times \$1,700\times 5\%=\$850$$

Equity is negative — Alice is liquidatable and insolvent.

Close schedule

$$\mathtt{deficit}=\$850-(-\$200)=\$1,050\ge \mathtt{MM}\Rightarrow \text{full close of all 10 ETH}$$

Bankruptcy price

$$\mathtt{bp}=\$1,700-\frac{-\$200}{10}=\$1,720$$

Alice is insolvent, so the close order’s limit price is the oracle price ($1,700), not the BP.

Execution

Carol’s bid at $1,700 fills the entire 10 ETH — at a price lower than the BP. No ADL.

$$\mathtt{AlicePnL}=10\times (\$1,700-\$2,000)=-\$3,000$$

Liquidation fee

$$\mathtt{remainingMargin}=\max (0,\$2,800-\$3,000)=\$0\Rightarrow \mathtt{fee}=\$0$$

Bad debt

$$\mathtt{badDebt}=|\min (0,\$2,800-\$3,000)|=\$200$$

Equivalently: each of the 10 ETH filled $20 below the $1,720 BP. Alice’s margin is floored to zero and the insurance fund covers the $200.

Final state

Example 5 — Insolvent; close partially absorbed by the book, remainder ADL’d

Same as Example 4, except Carol’s bid is only 4 ETH @ $1,700.

Execution

• Book: 4 ETH fill at $1,700 (below the $1,720 BP).
• ADL: the remaining 6 ETH close against Bob at the BP, $1,720.

$$\mathtt{AlicePnL}=4\times (\$1,700-\$2,000)+6\times (\$1,720-\$2,000)=-\$1,200-\$1,680=-\$2,880$$

$$\mathtt{BobPnL}=-6\times (\$1,720-\$2,000)=+\$1,680$$

Bob is force-closed $20 above oracle on 6 ETH — he absorbs $120 of Alice’s insolvency that would otherwise become bad debt.

Bad debt

$$\mathtt{margin}=\$2,800-\$2,880=-\$80\Rightarrow \mathtt{badDebt}=\$80$$

The $80 equals the book-filled portion’s shortfall from the BP: $4\times (\$1,720-\$1,700)$. The fee is $0 (no remaining margin).

Final state

Example 6 — Insolvent; book empty, whole close ADL’d

Same as Example 4, but the order book is empty.

Execution

All 10 ETH are ADL’d against Bob at the BP, $1,720.

$$\mathtt{AlicePnL}=10\times (\$1,720-\$2,000)=-\$2,800$$

$$\mathtt{margin}=\$2,800-\$2,800=\$0$$

Alice’s equity is zeroed by construction — no bad debt, despite her insolvency. Bob absorbs the whole $200 shortfall by buying back 10 ETH at $20 above oracle:

$$\mathtt{BobPnL}=-10\times (\$1,720-\$2,000)=+\$2,800$$

($200 less than the $3,000 he would realize closing at the oracle.) The fee is $0.

Final state

Example 7 — Two positions, solvent

Alice now holds two longs; Bob holds the exact opposite shorts. The order book is empty in this example and the next, so all closes go to ADL.

Setup

ETH drops to $1,900; BTC drops to $47,000

Alice’s account

$$\mathtt{equity}=\$7,065+10\times (-\$100)+1\times (-\$3,000)=\$3,065$$

$$\mathtt{MM}=10\times \$1,900\times 5\%+1\times \$47,000\times 5\%=\$950+\$2,350=\$3,300$$

$$\$3,065<\$3,300\Rightarrow \text{liquidatable (solvent)}$$

Close schedule

$$\mathtt{deficit}=\$3,300-\$3,065=\$235$$

Positions are processed in descending order of MM contribution: BTC ($2,350) before ETH ($950).

$$\mathtt{closeSiz}{\mathtt{e}}_{\mathtt{BTC}}=\lceil \frac{\$235}{\$47,000\times 5\%}\rceil =0.1\text{ BTC}$$

Closing 0.1 BTC removes $0.1\times \$2,350=\$235$ of MM — the deficit is fully covered, so the ETH position is not scheduled at all.

Bankruptcy price (BTC)

$$\mathtt{bp}=\$47,000-\frac{\$3,065}{1}=\$43,935$$

The numerator is the whole-account equity — including the ETH position’s unrealized PnL — divided by the BTC position’s full size (1 BTC).

Execution

0.1 BTC is ADL’d against Bob at $43,935.

$$\mathtt{AlicePnL}=0.1\times (\$43,935-\$50,000)=-\$606.50$$

$$\mathtt{BobPnL}=+\$606.50$$

Liquidation fee

$$\mathtt{fee}=0.1\times \$47,000\times 0.1\%=\$4.70$$

Final state

No bad debt. Alice’s equity is $6,453.80 − $1,000 − 0.9 × $3,000 = $2,753.80.

Example 8 — Two positions, insolvent

Same positions and margins as Example 7; prices fall further.

ETH drops to $1,800; BTC drops to $44,000

Alice’s account

$$\mathtt{equity}=\$7,065+10\times (-\$200)+1\times (-\$6,000)=-\$935$$

$$\mathtt{MM}=10\times \$1,800\times 5\%+1\times \$44,000\times 5\%=\$900+\$2,200=\$3,100$$

Close schedule

$$\mathtt{deficit}=\$3,100-(-\$935)=\$4,035\ge \mathtt{MM}\Rightarrow \text{both positions fully closed, BTC first}$$

Entry 1: BTC

$$\mathtt{b}{\mathtt{p}}_{\mathtt{BTC}}=\$44,000-\frac{-\$935}{1}=\$44,935$$

The full 1 BTC is ADL’d against Bob at $44,935:

$$\mathtt{margin}:\$7,065+1\times (\$44,935-\$50,000)=\$2,000$$

Alice’s equity is now $\$2,000+10\times (\$1,800-\$2,000)=\$0$ — the first position’s ADL absorbed the entire account shortfall.

Entry 2: ETH

The BP is recomputed from the account’s current equity, which is now zero:

$$\mathtt{b}{\mathtt{p}}_{\mathtt{ETH}}=\$1,800-\frac{\$0}{10}=\$1,800=\text{oracle price}$$

All 10 ETH are ADL’d against Bob at $1,800:

$$\mathtt{margin}:\$2,000+10\times (\$1,800-\$2,000)=\$0$$

Liquidation fee and bad debt

Remaining margin is $0, so the fee is $0; the margin is exactly zero, so there is no bad debt.

Final state

Bob’s two ADL fills realize $1\times (\$50,000-\$44,935)=\$5,065$ on BTC and $10\times (\$2,000-\$1,800)=\$2,000$ on ETH. Alice’s $935 shortfall is absorbed entirely by the BTC fill’s above-oracle premium.

Edge case — negative margin, positive equity

Every example above reaches the fee and bad-debt steps with margin equal to equity: a solvent account is only partially closed but its margin stays positive, and an insolvent account is fully closed, leaving no positions so that margin equals equity. Neither the §4 fee cap nor the §6 bad-debt check can tell margin and equity apart in those cases.

A cross-margined account can, however, reach liquidation with negative margin but positive equity. The cash margin balance goes negative — while the account stays solvent — when the trader extracts an open position’s unrealised profit before it is realised: by withdrawing against it (margin §3), or by realising a loss on a different position against it. The account is still solvent because that position’s unrealised profit is part of equity. This is the case the equity caps exist for.

Setup

Carol rests a 5-ETH bid at the $2,200 oracle.

ETH at $2,200

$$\mathtt{equity}=-\$1,450+10\times (\$2,200-\$2,000)=\$550$$

$$\mathtt{MM}=10\times \$2,200\times 5\%=\$1,100$$

$$\$0<\$550<\$1,100\Rightarrow \text{liquidatable, but solvent}$$

Close schedule

$$\mathtt{deficit}=\$1,100-\$550=\$550\mathtt{closeSize}=\lceil \frac{\$550}{\$2,200\times 5\%}\rceil =5\text{ ETH}(\text{5 ETH remain})$$

Execution

Alice is solvent, so the close order’s limit price is the bankruptcy price $\mathtt{bp}=\$2,200-\$550/10=\$2,145$. Carol’s bid at $2,200 is above that limit, so the 5-ETH close fills on the book at $2,200 (no ADL):

$$\mathtt{AlicePnL}=5\times (\$2,200-\$2,000)=+\$1,000\Rightarrow \mathtt{margin}=-\$1,450+\$1,000=-\$450$$

Closing at the oracle realises no concession, so equity is unchanged at $550.

Liquidation fee

$$\mathtt{rawFee}=5\times \$2,200\times 0.1\%=\$11.00$$

$$\mathtt{equityAfterCloses}=-\$450+5\times (\$2,200-\$2,000)=\$550\Rightarrow \mathtt{fee}=\min (\$11.00,\$550)=\$11.00$$

The margin-based cap would instead have used $\max (0,-\$450)=\$0$ and skipped the fee entirely.

Bad debt

$$\mathtt{equity}\mathtt{after}\mathtt{settlement}=(-\$450-\$11)+5\times \$200=\$539>0\Rightarrow \text{no bad debt}$$

The margin-based check would instead have seen $\mathtt{margin}=-\$461<0$, paid $461 from the insurance fund, and floored Alice’s margin to zero — handing $461 of insurance-fund value to a solvent account and inflating her equity by the same amount.

Final state

Alice keeps 5 ETH and equity of −$461 + 5 × $200 = $539, still solvent. Her margin stays negative — a valid cross-margin state, backed by the open position’s unrealised profit, that resolves itself when she eventually closes the position and realises that profit into margin.

1. This does not perfectly rank by total PnL since it ignores accumulated funding fees, but is a reasonable and efficient approximation. ↩

Vault

1. Overview

The vault is the passive market maker for the perpetual futures exchange. It continuously quotes bid/ask orders around the oracle price on every pair, earning the spread.

Liquidity providers (LPs) deposit settlement currency into the vault and receive vault shares credited to their account.

2. Liquidity provision

Adding liquidity follows an ERC-4626 virtual shares pattern to prevent the first depositor inflation attack.

Constants

Share minting

The LP specifies a USD margin amount $\mathtt{depositMargin}$ to transfer from their trading margin to the vault.

$$\mathtt{effectiveSupply}=\mathtt{vaultShareSupply}+\mathtt{virtualShares}$$

$$\mathtt{effectiveEquity}=\mathtt{vaultEquity}+\mathtt{virtualAssets}$$

$$\mathtt{sharesToMint}=\lfloor \mathtt{effectiveSupply}\times \frac{\mathtt{depositMargin}}{\mathtt{effectiveEquity}}\rfloor$$

Floor rounding protects the vault from rounding exploitation. A minimum-shares parameter lets depositors revert if slippage is too high.

First depositor protection

The virtual terms dominate when real supply and equity are small. An attacker cannot inflate the share price to steal from subsequent depositors because the initial share price is effectively $\$1/1,000,000=\$0.000001$ per share.

3. Liquidity withdrawal

The LP specifies how many vault shares to burn. The USD value to release is computed:

$$\mathtt{releaseValue}=\mathtt{effectiveEquity}\times \frac{\mathtt{sharesToBurn}}{\mathtt{effectiveSupply}}$$

The fund is not released immediately. A cooldown is initiated, with the ending time computed as:

$$\mathtt{endTime}=\mathtt{currentTime}+\mathtt{vaultCooldownPeriod}$$

Once $\mathtt{endTime}$ is reached, the contract credits the released USD value back to the LP’s trading margin.

4. Vault equity

The vault has its own user state (positions acquired from market-making fills). Its equity follows the same formula as any user:

$$\mathtt{vaultEquity}=\mathtt{vaultMarginValue}+\sum \mathtt{unrealisedPnl}-\sum \mathtt{accruedFunding}$$

where $\mathtt{vaultMargin}$ is the vault’s internal USD margin (updated in-place during settlement), and the sums run over all of the vault’s open positions.

If $\mathtt{effectiveEquity}$ is non-positive the vault is in catastrophic loss and both deposits and withdrawals are disabled.

5. Market making policy

The vault uses its margin to market make in the order book. Each block, after the oracle update, the vault cancels all existing quotes and recomputes bid/ask orders for every pair.

The strategy uses inventory skew to reduce the vault’s exposure to directional price movements. When the vault accumulates a position in one direction, it tilts both order sizes and spreads to encourage trades that unwind that position.

Margin allocation

Total vault available margin is split across pairs by weight:

$$\mathtt{pairMargin}=\mathtt{vaultAvailableMargin}\times \frac{\mathtt{vaultLiquidityWeight}}{\mathtt{vaultTotalWeight}}$$

where $\mathtt{vaultAvailableMargin}=\max (0,\mathtt{equity}-\mathtt{usedMargin})$ and $\mathtt{usedMargin}$ is the sum of initial margin across all vault positions (see Margin §8).

Skew ratio

For each pair, compute a skew ratio from the vault’s current position:

$$\mathtt{skew}=\mathrm{clamp}\left(\frac{\mathtt{positionSize}}{\mathtt{maxSkewSize}},-1,1\right)$$

where $\mathtt{positionSize}$ is the vault’s signed position (positive = long, negative = short) and $\mathtt{maxSkewSize}$ is the position size at which skew saturates.

At zero position, $\mathtt{skew}=0$ and quoting is symmetric. At maximum long, $\mathtt{skew}=1$. At maximum short, $\mathtt{skew}=-1$.

Quote size

Each side receives half the allocated margin, capped by a per-pair maximum, then tilted by the skew:

$$\mathtt{halfMargin}=\frac{\mathtt{pairMargin}}{2}$$

$$\mathtt{baseSize}=\min \left(\frac{\mathtt{halfMargin}}{\mathtt{oraclePrice}\times \mathtt{imr}},\mathtt{maxQuoteSize}\right)$$

$$\mathtt{bidSize}=\mathtt{baseSize}\times (1-\mathtt{skew}\times \mathtt{sizeSkewFactor})$$

$$\mathtt{askSize}=\mathtt{baseSize}\times (1+\mathtt{skew}\times \mathtt{sizeSkewFactor})$$

where $\mathtt{imr}$ is the initial margin ratio and $\mathtt{sizeSkewFactor}\in [0,1]$ controls skew intensity.

When the vault is long ($\mathtt{skew}>0$), bid size decreases and ask size increases — the vault offers more on the sell side to unwind. Total quoted size ($\mathtt{bidSize}+\mathtt{askSize}=2\times \mathtt{baseSize}$) is preserved.

Bid price

$$\mathtt{rawBid}=\mathtt{oraclePrice}\times (1-\mathtt{halfSpread}\times (1+\mathtt{skew}\times \mathtt{spreadSkewFactor}))$$

Snap down to the nearest tick:

$$\mathtt{bidPrice}=\mathtt{rawBid}-(\mathtt{rawBid}\mathrm{mod}\mathtt{tickSize})$$

Book-crossing prevention: if $\mathtt{bidPrice}\ge \mathtt{bestAsk}$, clamp to $\mathtt{bestAsk}-\mathtt{tickSize}$.

Skip if $\mathtt{bidPrice}\le 0$ or notional is below the minimum order size.

When the vault is long, the bid spread widens (less likely to accumulate more).

Ask price

$$\mathtt{rawAsk}=\mathtt{oraclePrice}\times (1+\mathtt{halfSpread}\times (1-\mathtt{skew}\times \mathtt{spreadSkewFactor}))$$

Snap up to the nearest tick (ceiling):

$$\mathtt{askPrice}=\{\begin{array}{ll}\mathtt{rawAsk}& \text{if }\mathtt{rawAsk}\mathrm{mod}\mathtt{tickSize}=0\\ \mathtt{rawAsk}-(\mathtt{rawAsk}\mathrm{mod}\mathtt{tickSize})+\mathtt{tickSize}& \text{otherwise}\end{array}$$

Book-crossing prevention: if $\mathtt{askPrice}\le \mathtt{bestBid}$, clamp to $\mathtt{bestBid}+\mathtt{tickSize}$.

Skip if notional is below the minimum order size.

When the vault is long, the ask spread tightens (more attractive to takers who buy from the vault).

Combined effect

When the vault is long, all four levers push toward unwinding:

1. Bid size decreases (less buying)
2. Ask size increases (more selling)
3. Bid spread widens (buys less likely to fill)
4. Ask spread tightens (sells more likely to fill)

The mirror applies when short.

Per-pair parameters

If any of vault_half_spread, vault_max_quote_size, vault_liquidity_weight, tick_size, or the allocated margin is zero, the vault skips quoting for that pair.

Choosing parameters

vault_max_skew_size — the position size at which skew reaches its maximum. A natural starting point is vault_max_quote_size (the existing per-side cap). This means: once the vault has accumulated one full order’s worth of directional exposure, skew is fully engaged. For gentler unwinding, use 2x vault_max_quote_size.

vault_size_skew_factor — how aggressively to tilt order sizes. Start with 0.5: at maximum skew, the heavier side quotes 1.5x and the lighter side 0.5x. A value of 1.0 fully shuts off quoting on one side at max position, which may be too aggressive for a vault that should always provide some liquidity. Range 0.5 to 0.8 is recommended.

vault_spread_skew_factor — how aggressively to tilt spreads. Start with 0.3: at maximum skew, the tightened side has 70% of normal spread and the widened side has 130%. Keep this below vault_size_skew_factor — size adjustment is the primary lever, spread adjustment is the fine-tuning. Range 0.3 to 0.5 is recommended. Values above 1.0 are permitted and cause the tightened side to cross the oracle price at maximum skew (an aggressive-unwind posture, useful for quickly deleveraging a large directional position); the invariant bid < ask still holds since ask - bid = 2 × oracle × vault_half_spread. The effective upper bound is governed by the cross-field invariant vault_half_spread × (1 + vault_spread_skew_factor) < 1, which ensures the bid stays positive at max skew.

General tuning principle: start conservative (size 0.5, spread 0.3), observe PnL and position behavior, increase if the vault still accumulates too much directional exposure.

Referral

The referral system lets existing traders recruit new users and earn a share of the trading fees generated by their referrals. When a referred user trades, a portion of the fee — after the protocol treasury has taken its cut — is distributed to the direct referrer and up to four additional upstream referrers in the referral chain.

1. Overview

Three roles participate in a referral commission:

• Referee — the user who was referred and is paying trading fees.
• Direct referrer (level 1) — the user who referred the referee. Earns a commission on the referee’s fees and may share a portion of it back with the referee.
• Upstream referrers (levels 2–5) — referrers further up the chain. Each receives only the marginal increase in commission rate beyond what lower levels already captured.

Commissions are taken from the trading fee after the protocol treasury has claimed its share. The system can be disabled globally by setting $\mathtt{active}=\text{false}$ in the referral parameters, which causes the commission pass to be skipped entirely.

Referral commissions are applied whenever an order is filled and trading fees are collected. Exception: liquidation fills (both for the taker and the maker) use zero trading fees, so no referral commissions occur during liquidation.

2. Key concepts

Two rates govern how referral fees are distributed:

• Commission rate ($\mathtt{cr}$) — the fraction of the post-protocol-cut fee that the referral system distributes at a given level. This rate is tiered: it increases as the referrer’s direct referees accumulate more 30-day rolling trading volume (see §6b). The chain owner can also set a per-user override (see §6a).

• Fee share ratio ($\mathtt{sr}$) — the fraction of the level-1 commission that the direct referrer gives back to the referee as a rebate. For example, if the commission rate is 20 % and the share ratio is 50 %, the referee receives 10 % and the referrer keeps 10 %. The share ratio is capped at 50 % and can only increase once set.

3. Registration

3a. Becoming a referrer

A user opts in as a referrer by calling SetFeeShareRatio with a $\mathtt{shareRatio}$ value. The share ratio determines what fraction of the level-1 commission the referrer gives back to the referee (see §5a).

Eligibility: the user must have accumulated enough lifetime trading volume:

$$\mathtt{lifetimeVolume}\ge \mathtt{volumeToBeReferrer}$$

Users who have a commission rate override (see §6a) bypass this volume requirement.

Constraints:

• $\mathtt{shareRatio}\le 50\%$ — the maximum share ratio a referrer can set.
• The share ratio can only increase once set. A subsequent call must supply a value $\ge$ the current ratio.

3b. Registering a referee

A referee is linked to a referrer through one of two paths:

1. During account creation — the RegisterUser message on the account factory accepts an optional referrer field. If provided, the factory forwards a SetReferral message to the perps contract.
2. After account creation — the referee (or an account they own) calls SetReferral directly on the perps contract.

Constraints:

• A user cannot refer themselves ($\mathtt{referrer}\ne \mathtt{referee}$).
• The referrer must already have a fee share ratio set (i.e. has opted in as a referrer).
• The referral relationship is immutable once stored — a referee can never change or remove their referrer.

When a referral is registered, a per-referee statistics record is initialised for the (referrer, referee) pair, and the referrer’s $\mathtt{refereeCount}$ is incremented in today’s cumulative data bucket.

4. Fee split recap

For every fill, a trading fee is computed per Order matching §8:

$$\mathtt{fee}=|\mathtt{fillSize}|\times \mathtt{fillPrice}\times \mathtt{feeRate}$$

The fee is then split between the protocol treasury and the vault:

$$\mathtt{protocolFee}=\mathtt{fee}\times \mathtt{protocolFeeRate}$$

$$\mathtt{vaultFee}=\mathtt{fee}-\mathtt{protocolFee}$$

The protocol fee is routed to the treasury and is not affected by referrals. Referral commissions are computed against $\mathtt{vaultFee}$ — i.e. the remainder of the fee after the protocol has taken its cut.

5. Commission distribution

After PnL settlement and fee collection, the contract distributes referral commissions for every fee-paying user who has a referrer. Commissions are drawn from the post-protocol-cut fee and credited to the recipients’ margins.

5a. Level 1 — direct referrer

Let ${\mathtt{cr}}_1$ be the commission rate of the direct referrer (see §6) and $\mathtt{sr}$ be that referrer’s fee share ratio.

The referee (fee payer) receives:

$$\mathtt{refereeShare}=\mathtt{vaultFee}\times {\mathtt{cr}}_1\times \mathtt{sr}$$

The direct referrer receives:

$$\mathtt{referrerCommission}=\mathtt{vaultFee}\times {\mathtt{cr}}_1\times (1-\mathtt{sr})$$

Equivalently, the total level-1 commission is $\mathtt{vaultFee}\times {\mathtt{cr}}_1$, split between referee and referrer by the share ratio.

5b. Levels 2–5 — upstream referrers

The algorithm walks up the referral chain from the direct referrer. At each level $n$ ($2\le n\le 5$), let ${\mathtt{cr}}_n$ be the commission rate of the $n$-th referrer and $\mathtt{maxCr}$ be the maximum commission rate seen at any prior level (initialised to ${\mathtt{cr}}_1$).

$${\mathtt{marginal}}_n=\max (0,{\mathtt{cr}}_n-\mathtt{maxCr})$$

$${\mathtt{commission}}_n=\mathtt{vaultFee}\times {\mathtt{marginal}}_n$$

After computing ${\mathtt{commission}}_n$, update:

$$\mathtt{maxCr}\leftarrow \max (\mathtt{maxCr},{\mathtt{cr}}_n)$$

If ${\mathtt{cr}}_n\le \mathtt{maxCr}$, the referrer at level $n$ receives nothing. The chain walk stops early if a referrer at level $n$ has no referrer of their own, or after level 5.

Upstream referrers do not use a share ratio — the entire marginal commission goes to the upstream referrer.

5c. Vault deduction

After processing all fee-paying users, the total of all commissions is deducted from the fee that would otherwise have accrued to the vault:

$$\mathtt{vaultMargin}-=\sum \mathtt{commissions}$$

5d. Worked example

Setup. Five users form a referral chain, each with a commission rate override. User C has a fee share ratio of 40 %:

Trade. User D trades $10 m taker volume, pays $1,000 in fees. Assume $\mathtt{protocolFeeRate}=0$ so $\mathtt{vaultFee}=\$1,000$.

Total referral commissions = $300, equal to the highest commission rate in the chain (A’s 30 %) applied to the fee after the protocol cut.

Counter-example. Now User F signs up under User E (40 % commission rate) and trades. Since E’s 40 % exceeds every upstream referrer, no upstream commissions are paid — only E and F split the level-1 commission of $\mathtt{vaultFee}\times 40\%$.

6. Commission rate

The commission rate $\mathtt{cr}$ for a referrer determines the fraction of the post-protocol-cut fee that the referral system distributes at that level.

6a. Override

The chain owner can set (or remove) a per-user override via SetCommissionRateOverride. When present, this value is used directly, bypassing the volume-tiered lookup. Users with an override also bypass the $\mathtt{volumeToBeReferrer}$ requirement when calling SetFeeShareRatio.

6b. Volume-tiered lookup

When no override exists, $\mathtt{cr}$ is derived from the referrer’s direct referees’ 30-day rolling trading volume:

1. Load the referrer’s latest cumulative referral data; let $V_{\mathrm{now}}$ be its $\mathtt{refereesVolume}$ field.

2. Load the cumulative data at $t_{\mathrm{now}}-30\text{days}$; let $V_{\mathrm{start}}$ be its $\mathtt{refereesVolume}$ field.

3. Compute the windowed volume:

   $$\mathtt{windowRefereesVolume}=V_{\mathrm{now}}-V_{\mathrm{start}}$$

4. Walk the $\mathtt{commissionRatesByVolume}$ map and select the entry with the highest volume threshold $\le \mathtt{windowRefereesVolume}$.

5. If no tier qualifies, use $\mathtt{commissionRateDefault}$.

Cumulative data is bucketed by day (see §7a), so the lookup loads the nearest bucket at or before the start of the window.

7. Data tracking

7a. Cumulative daily buckets

Each user has a UserReferralData record keyed by (user, day). The day is the block timestamp rounded down to midnight. Fields are cumulative (monotonically increasing), so a rolling window is computed by differencing two buckets.

When a referred user trades:

• The referee’s bucket: $\mathtt{volume}$ and $\mathtt{commissionSharedByReferrer}$ increment.
• The direct referrer’s bucket: $\mathtt{refereesVolume}$ and $\mathtt{commissionEarnedFromReferees}$ increment.
• Upstream referrers: only $\mathtt{commissionEarnedFromReferees}$ increments (and only if they received a non-zero commission).

7b. Per-referee statistics

For every (referrer, referee) pair, a RefereeStats record tracks:

These records are multi-indexed for sorted queries by registered_at, volume, or commission_earned.

7c. Daily active direct referees

On the first trade of each day by a given direct referee, the referrer’s $\mathtt{cumulativeActiveReferees}$ field in today’s cumulative bucket is incremented. Subsequent trades by the same referee on the same day do not increment it again. This is tracked via the $\mathtt{lastDayActive}$ field on RefereeStats: if $\mathtt{lastDayActive}\ne \mathtt{today}$, it is a new active day.

8. Parameters

These fields are part of the top-level Param struct (not a separate nested struct):

Constants:

Risk Parameters

This chapter describes how to choose the risk parameters that govern the perpetual futures exchange — the global Param fields and per-pair PairParam fields defined in the perps contract. The goal is a systematic, reproducible calibration workflow that balances capital efficiency against tail-risk protection.

1. Margin ratios

The initial margin ratio (IMR) sets maximum leverage ($1/\mathtt{imr}$). The maintenance margin ratio (MMR) sets the liquidation threshold. Both are per-pair.

The IMR also bounds closed-session index drift: while a market is closed, the index price can move at most $\pm \mathtt{imr}$ from the last regular-session oracle price, so a thin off-hours book cannot walk the mark far from the true price.

1.1 Volatility-based derivation

Start from the asset’s historical daily return distribution:

1. Collect at least 1 year of daily log-returns.

2. Compute the 99.5th-percentile absolute daily return $r_{99.5}$.

3. Apply a liquidation-delay factor $k$ (typically 2–3) to account for the time between the price move and the liquidation execution:

   $$\mathtt{mmr}=r_{99.5}\times k$$

4. Set IMR as a multiple of MMR:

   $$\mathtt{imr}=\mathtt{mmr}\times m,m\in [1.5,4]$$

A higher $m$ gives more buffer between position entry and liquidation, reducing bad-debt risk at the cost of lower leverage.

1.2 Peer benchmarks

1.3 Invariants

The following must hold for every pair:

$$0<\mathtt{mmr}<\mathtt{imr}\le 1$$

$$\mathtt{liquidationFeeRate}\le \mathtt{mmr}-\mathrm{takerFeeRate}$$

The second constraint ensures a liquidated position can always cover the taker fee and liquidation fee from the maintenance margin cushion.

2. Fee rates

Three fee rates apply globally (not per-pair):

2.1 Sizing principles

• Taker fee should exceed the typical half-spread of the most liquid pair so the vault earns positive expected value on every fill against a taker.
• Maker fee can be zero, slightly positive, or negative (rebate). A zero maker fee attracts resting liquidity; a negative maker fee pays the maker on every fill. The absolute value of the maker fee rate must not exceed the taker fee rate, otherwise the exchange loses money on each trade.
• Liquidation fee must satisfy the invariant in §1.3. It should be large enough to fund the insurance pool but small enough that a liquidated user retains some margin when possible.

2.2 Industry benchmarks

3. Funding parameters

Funding anchors the perp price to the oracle. Two per-pair parameters and one global parameter control its behaviour (see Funding for mechanics):

3.1 Max funding rate

The max daily funding rate limits how much a position can be charged per day. A useful rule of thumb:

$$\mathtt{maxAbsFundingRat}{\mathtt{e}}_{\mathrm{daily}}\le \frac{\mathtt{imr}}{T_{\mathrm{liq}}}$$

where $T_{\mathrm{liq}}$ is the number of days it should take sustained max-rate funding to liquidate a fully leveraged position. For $T_{\mathrm{liq}}=3$ days and $\mathtt{imr}=5\%$:

$$\mathtt{maxRate}=\frac{0.05}{3}\approx 1.67\%\text{ per day}$$

3.2 Impact size

The impact_size determines how deep the order book is walked to compute the premium. Set it to a representative trade size — large enough that the premium reflects real depth, small enough that thin books don’t produce zero premiums too often. A good starting point is 1–5% of the target max OI.

4. Capacity parameters

4.1 Max open interest

The maximum OI per side caps the exchange’s aggregate exposure:

$$\mathtt{maxAbsOI}\le \frac{\mathtt{vaultEquity}\times w_{\mathrm{pair}}}{\mathtt{mmr}\times \mathtt{tailLossFactor}}$$

where $w_{\mathrm{pair}}$ is the pair’s weight fraction and $\mathtt{tailLossFactor}$ (2–5) is a safety multiplier reflecting how many times maintenance margin the vault could lose in a tail event.

Start conservatively — it is easy to raise OI caps but dangerous to lower them (existing positions above the cap cannot be force-closed).

4.2 Min order size

Prevents dust orders. Set to a notional value that covers at least 2× the gas cost of processing the order. Typical values: $10–$100.

4.3 Tick size

The minimum price increment. Too small increases book fragmentation; too large creates implicit spread. Rule of thumb:

$$\mathtt{tickSize}\approx \mathtt{oraclePrice}\times 10^{-4}\text{ to }10^{-3}$$

For BTC at $60,000: tick sizes of $1–$10 are reasonable.

5. Vault parameters

The vault’s market-making policy is controlled by three per-pair parameters and two global parameters (see Vault for mechanics):

5.1 Half-spread

The half-spread should be calibrated to short-term intraday volatility so the vault earns a positive edge:

$$\mathtt{halfSpread}\ge {\sigma }_{\mathtt{intraday}}+\mathtt{makerFeeRate}$$

where ${\sigma }_{intraday}$ is the standard deviation of intra-block price changes. A larger spread protects against adverse selection but reduces fill probability.

5.2 Max quote size

Caps the vault’s resting order size per side per pair. Should be consistent with max_abs_oi — the vault should not be able to accumulate more exposure than the system can handle:

$$\mathtt{maxQuoteSize}\le \mathtt{maxAbsOI}\times f,f\in [0.3,0.8]$$

5.3 Liquidity weight

Determines what fraction of total vault margin is allocated to each pair. Higher-volume, lower-risk pairs should receive higher weights. The sum of all weights equals vault_total_weight.

5.4 Cooldown period

Prevents LPs from front-running known losses. Should exceed the funding period and be long enough that vault positions cannot be manipulated by short-term deposit/withdraw cycles. Typical values: 7–14 days.

6. Operational limits

7. Calibration workflow

The following checklist produces a complete parameter set from scratch:

1. Collect data — Gather ≥ 1 year of daily and hourly OHLCV data for each asset.

2. Compute volatility — For each asset, compute $r_{99.5}$ (daily 99.5th percentile absolute return) and ${\sigma }_{intraday}$ (hourly return standard deviation).

3. Set margin ratios — Derive MMR from $r_{99.5}$ (§1.1), then IMR as a multiple of MMR. Cross-check against peer benchmarks (§1.2).

4. Set fees — Choose maker/taker/liquidation fee rates satisfying §2.1 and the invariant in §1.3.

5. Set funding — Pick funding_period, derive max_abs_funding_rate (§3.1), and calibrate impact_size (§3.2).

6. Size exposure — Set max_abs_oi from vault equity and tail-risk tolerance (§4.1).

7. Set order constraints — Choose min_order_size and tick_size (§4.2, §4.3).

8. Configure vault — Set vault_half_spread, vault_max_quote_size, and vault_liquidity_weight per pair (§5), and vault_cooldown_period globally.

9. Backtest — Replay historical price data through the parameter set. Verify:

   • Liquidations occur before bad debt in > 99% of cases.
   • Vault PnL is positive over the test period.
   • Funding rates do not hit the clamp for more than 5% of periods.

10. Deploy conservatively — Launch with the conservative profile (lower leverage, higher fees, lower OI caps). Tighten parameters toward the aggressive profile as the system proves stable and liquidity deepens.

API Reference

Every Dango deployment exposes its data and trading surface over two HTTP servers:

• the Live API — the consensus node, which talks to CometBFT, performs state transitions, and serves the latest chain state, transaction broadcasting, and real-time streaming; and
• the Archive API — the archive node, which ingests finalized blocks, analyzes them, and serves structured historical data backed by SQL databases.

The Live API speaks REST and WebSocket; the Archive API speaks REST. This chapter is a guide to both. The exhaustive, always-current endpoint reference lives in each server’s interactive documentation (see §1.2); this chapter covers the concepts that reference cannot express — the two-server model, the transaction lifecycle and signing, the WebSocket protocol, and the perps-specific semantics — and points to the interactive docs for the mechanical detail.

Deprecation notice. Dango nodes historically exposed a single GraphQL endpoint, which backed the frontend and most trading bots. GraphQL is being phased out in favor of the REST + WebSocket surface documented here, and the monolithic server is being split into the two servers above. New integrations should target REST + WebSocket. The GraphQL endpoint remains available during the transition but is unmaintained and will be removed; it is not documented here.

1. Overview

1.1 The two APIs

The division reflects where the data lives. The Live API answers from the node’s in-memory and latest-committed state — it is always current but keeps only a shallow window of history. The Archive API answers from SQL databases populated by analyzing every block — it reaches back to genesis but trails the chain tip slightly (see §6.1).

A quick mental model for readers coming from other venues: POST /query is the universal read (Dango’s analogue of Hyperliquid’s /info), and the GET /perps/* and GET /account/* routes are typed shortcuts over it; POST /broadcast is the universal write (the analogue of Hyperliquid’s /exchange).

1.2 Interactive reference

Both servers auto-generate an OpenAPI specification and a Swagger UI from the handlers themselves, served at /docs/ (with the raw spec at /openapi.json). This is the source of truth for paths, HTTP methods, query and path parameters, and status codes — it can never drift from the code, because it is generated from it. Hitting the base path of either server (GET /) redirects to its docs.

See Constants for the concrete hostnames.

One caveat shapes how this chapter divides labor with Swagger: the Live API’s read handlers return their contract responses as opaque JSON, so Swagger documents their parameters but not their response shapes. Those response shapes are documented here, in the Types reference. The Archive API’s feeds return typed objects, so Swagger documents their responses in full; this chapter describes them only in outline. And OpenAPI cannot model WebSocket traffic at all, so the entire WebSocket section lives here.

1.3 Base URLs

See Constants for the mainnet and testnet hostnames of both servers, the WebSocket URL, and the testnet faucet.

2. Conventions

These conventions apply across both servers. Reading them first keeps the rest of the chapter terse.

2.1 Data types and encoding

All requests and responses are JSON. Contract-specific message keys are snake_case.

The perps exchange’s numeric types are signed fixed-point decimals with 6 decimal places, built on dango_types::Number. They are serialized as strings to avoid floating-point loss:

Additional scalar types:

2.2 Identifiers

Addr and Hash256 use different text dialects — an address is lowercase and 0x-prefixed, a hash is bare uppercase. EVM tooling typically displays hashes (e.g. Hyperlane message IDs) as 0x-prefixed lowercase; strip the prefix and uppercase the rest before passing one to Dango, or the request fails to deserialize.

2.3 Pagination

The two servers paginate differently, reflecting their backing stores.

Live API — contract-native paging. The enumerating GET /perps/* and GET /account/* reads forward the contract’s own start_after / limit scheme: iteration begins after the start_after key (a PairId, Addr, or Denom, exclusive) and returns at most limit entries. Omit both to start from the beginning with the contract’s default page size. To page, pass the last key of one response as the next start_after.

Archive API — keyset paging. Every Archive feed is newest-first and keyset-paginated on first (page size, max 50, default 50) and after (an opaque cursor). The response is an envelope:

{
  "items": [ /* … */ ],
  "pageInfo": {
    "hasNextPage": true,
    "endCursor": "6f7b…"
  }
}

Roll the page’s endCursor back in as the next request’s after to fetch the following page; stop when hasNextPage is false. The cursor is opaque — treat it as a token, do not parse it.

2.4 Errors

Live API REST. Errors map to HTTP status codes: 400 (malformed body or failed query), 404 (single-item lookup found nothing), 503 (a contract address could not be resolved yet — the chain has not committed its genesis state; retry), 500 (transport failure to the consensus node). The body carries the error message.

Archive API REST. Errors are a JSON envelope with the matching status: 400 (malformed argument or cursor), 404 (absent resource), 500 (internal). For example, a bad cursor:

{ "error": "invalid cursor: …" }

WebSocket. Errors ride the socket as error-keyed frames; see §5.5 for the frame shape and the code catalog.

2.5 Casing

URL path segments are kebab-case (/perps/liquidity-depth, /perps/order/by-user). Query parameters keep the snake_case spelling and the wire encoding of the contract fields they forward to — so a numeric grug type stays string-encoded in the query string (bucket_size=10 parses as a UsdPrice), while a plain integer is unquoted (limit=20).

3. Live API — reading state

All reads in this section answer from the latest finalized state and require no authentication.

3.1 The universal query

POST /query runs any read-only query against the latest state. The body is a raw grug Query object; the response is the raw QueryResponse. This is the lowest-level, most general read — every typed shortcut in §3.2 desugars to one of these.

Example — query a contract:

curl -X POST https://<live-host>/query \
  -H 'Content-Type: application/json' \
  -d '{"wasm_smart": {"contract": "PERPS_CONTRACT", "msg": {"state": {}}}}'

The response is keyed by the request variant:

{ "wasm_smart": { /* the contract's State object */ } }

The body accepts any Query variant — for example {"app_config": {}}, {"balance": {"address": "0x…", "denom": "bridge/usdc"}}, or a smart-contract query as above. Some perps reads have no typed shortcut and are reached only this way — for instance a user’s cumulative trading volume:

{ "wasm_smart": { "contract": "PERPS_CONTRACT", "msg": { "volume": { "user": "0x…", "since": null } } } }

Multi-query. To fetch several pieces of state as one atomic snapshot at a single block height, wrap them in multi. This is the correct way to read, say, oracle prices and a user’s positions together — issuing two separate requests may straddle a block boundary and return an inconsistent pair.

{
  "multi": [
    { "wasm_smart": { "contract": "ORACLE_CONTRACT", "msg": { "prices": {} } } },
    { "wasm_smart": { "contract": "PERPS_CONTRACT", "msg": { "user_state": { "user": "0x…" } } } }
  ]
}

The response is an array of results positionally matching the requests; each is {"Ok": …} or {"Err": "…"}, and one failure does not abort the others.

3.2 Typed read shortcuts

Typed GET routes wrap the most common perps and account reads: the parameters are validated and documented, the target contract address is resolved server-side (clients never pass it), and the response is the contract’s response object verbatim. Use the interactive docs for the exhaustive parameter detail; the response shapes are documented in the Types reference.

Perps reads — all resolve to a query against the perps contract:

Each of the four one-item lookups (pair-param, pair-state, order/{id}, order/by-client-order-id) responds 404 when the item does not exist, rather than 200 with a null body.

Account reads:

The seen-nonces routes back nonce selection when building a transaction — see §4.2. URL-encode the session_key, as its base64 form may contain +, /, and =.

Worked example — order book depth

This one read is worked in full as the template for the rest. It also has a WebSocket twin (§5.3): same parameters, same response.

Server Live · Auth none · State latest finalized

REST — GET /perps/liquidity-depth

curl 'https://<live-host>/perps/liquidity-depth?pair_id=perp/ethusd&bucket_size=10&limit=20'

WebSocket twin — channel perpsLiquidityDepth, same parameters plus interval (blocks between refreshes; ≥ 1, default 10; use 1 for per-block updates):

{"method":"subscribe","id":1,"subscription":{"type":"perpsLiquidityDepth","pair_id":"perp/ethusd","bucket_size":"10","limit":20,"interval":1}}

Response — both forms return the same object (the WebSocket frame wraps it as {blockHeight, response}):

{
  "bids": {
    "2999.000000": { "size": "12.500000", "notional": "37487.500000" },
    "2998.000000": { "size": "8.200000",  "notional": "24583.600000" }
  },
  "asks": {
    "3001.000000": { "size": "10.000000", "notional": "30010.000000" }
  }
}

bids and asks are maps from bucket price to that bucket’s aggregated size (absolute contracts) and notional (USD). Bids read best (highest) first in descending key order; asks best (lowest) first in ascending key order.

Errors — 400 unknown pair, or bucket_size not one of the pair’s configured sizes. 503 the chain has not committed genesis yet (retry).

See also — Order matching for how the book forms; PairParam for the valid bucket_sizes.

Note. A handful of GraphQL-only reads — searching users by public key, and enumerating a user’s accounts — have no REST twin yet. They remain on the deprecated GraphQL endpoint and will be replaced; the account address forms above cover the common cases in the meantime.

3.3 Blocks and node status

The Live API serves the recent tail of blocks from the node’s on-disk cache. For deep history, use the Archive API (§6.2).

The /block/full/{height} shape matches the WebSocket fullBlock channel (§5.2). /up proves the chain is answering and the indexer database is reachable: is_running is whether the latest finalized block is younger than 30 seconds, and indexed_block_height is the highest block the indexer has written.

4. Live API — transactions

Every write — trading, margin, vault, and account operations — is a signed transaction (Tx) broadcast to the Live API. This section covers the lifecycle, the signing scheme, and the catalog of messages. The mechanics behind each operation live in the dedicated chapters (Order matching, Vault, …); here we document the wire format.

4.1 Transaction lifecycle

graph LR
    A[Compose<br/>messages] --> B[Fetch metadata<br/>chain_id, user_index, nonce]
    B --> C[Simulate<br/>POST /simulate]
    C --> D[Set gas limit]
    D --> E[Build SignDoc]
    E --> F[Sign]
    F --> G[Broadcast<br/>POST /broadcast]

1. Compose messages — build the contract execute message(s) (§4.7–§4.9).
2. Fetch metadata — the chain ID, the sender’s user_index, and the next nonce (see §4.2).
3. Simulate — dry-run to estimate gas (§4.5).
4. Set gas limit — the simulation’s gas_used, plus ~770,000 for signature-verification overhead.
5. Build the SignDoc — assemble {sender, gas_limit, messages, data} (§4.3).
6. Sign — with the chosen key.
7. Broadcast — submit the signed Tx (§4.6).

4.2 Transaction structure and nonces

A transaction wraps one or more messages with authentication metadata and a credential:

{
  "sender": "0x1234…abcd",
  "gas_limit": 1500000,
  "msgs": [
    { "execute": { "contract": "PERPS_CONTRACT", "msg": { /* … */ }, "funds": {} } }
  ],
  "data": { "user_index": 0, "chain_id": "dango-1", "nonce": 42, "expiry": null },
  "credential": { /* … */ }
}

The primary message is execute, targeting a contract with a snake_case msg and optional funds (a map of denom → amount string, {} for none):

{ "execute": { "contract": "PERPS_CONTRACT", "msg": { "trade": { "deposit": {} } }, "funds": { "bridge/usdc": "1000000000" } } }

USDC uses 6 decimals (1 USDC = 1000000 base units); all bridged tokens use the bridge/ prefix.

Nonces. Dango uses unordered nonces with a sliding window, similar to Hyperliquid’s scheme. Nonces are tracked per signer, in two namespaces: a standard credential (master key) draws from one account-wide window; a session credential draws from its own window, keyed by the session public key — so several clients (e.g. one bot per session key) can drive one account concurrently without colliding. Within a window, the account keeps the 20 most recently seen nonces; a transaction is accepted if its nonce is unused, newer than the oldest in the window, and no greater than the newest seen plus 100.

Pick the next nonce client-side by querying the relevant window against the sender’s own account contract (§3.2):

• A standard signer reads GET /account/{address}/seen-nonces and uses max + 1 (or 0 if empty).
• A session signer reads GET /account/{address}/session-seen-nonces?session_key=<base64> and uses max + 1 of that array; if that window is empty, it falls back to the standard window’s max + 1, or 0 if the account has never transacted.

4.3 Signing

The credential wraps a StandardCredential (a key identifier + signature) or a SessionCredential (§4.4). Three signature schemes are supported:

Passkey (Secp256r1 / WebAuthn):

{ "standard": { "key_hash": "A1B2…", "signature": { "passkey": { "authenticator_data": "<base64>", "client_data": "<base64>", "sig": "<base64>" } } } }

sig is a 64-byte Secp256r1 signature; client_data is the base64-encoded WebAuthn client-data JSON (its challenge is the base64url of the SHA-256 of the SignDoc); authenticator_data is the base64-encoded authenticator data.

Secp256k1:

{ "standard": { "key_hash": "A1B2…", "signature": { "secp256k1": "<base64>" } } }

A 64-byte Secp256k1 signature, base64-encoded.

EIP-712 (Ethereum wallets):

{ "standard": { "key_hash": "A1B2…", "signature": { "eip712": { "typed_data": "<base64>", "sig": "<base64>" } } } }

sig is a 65-byte signature (64-byte Secp256k1 + 1-byte recovery id); typed_data is the base64-encoded EIP-712 typed-data JSON.

The SignDoc. The signed payload mirrors the transaction but replaces credential with the structured data:

{
  "sender": "0x1234…abcd",
  "gas_limit": 1500000,
  "messages": [ /* … */ ],
  "data": { "chain_id": "dango-1", "expiry": null, "nonce": 42, "user_index": 0 }
}

To sign: serialize the SignDoc to canonical JSON (keys sorted alphabetically), hash with SHA-256, and sign the hash. For Passkey, that hash is the WebAuthn challenge; for EIP-712, the SignDoc is mapped to a typed-data structure and signed via eth_signTypedData_v4.

4.4 Session keys

Session keys allow delegated signing without the master key on every transaction. A SessionCredential carries the session key, its expiry, a SignDoc signature by the session key, and an authorization — the SessionInfo signed by the master key:

{
  "session": {
    "session_info": { "session_key": "<base64>", "expire_at": "1700000000" },
    "session_signature": "<base64>",
    "authorization": { "key_hash": "A1B2…", "signature": { /* standard signature */ } }
  }
}

4.5 Simulating and gas

POST /simulate dry-runs an UnsignedTx (the transaction without a credential) and returns its TxOutcome:

curl -X POST https://<live-host>/simulate \
  -H 'Content-Type: application/json' \
  -d '{"sender": "0x1234…abcd", "msgs": [ /* … */ ], "data": {"user_index": 0, "chain_id": "dango-1", "nonce": 42, "expiry": null}}'

{ "gas_limit": 100000000, "gas_used": 750000, "result": { "Ok": null }, "events": { /* … */ } }

Simulation skips signature verification, so add 770,000 gas (the Secp256k1 verification cost) to gas_used when setting the final gas_limit. result is {"Ok": null} on success or {"Err": {"error": "…"}} on failure; the reported gas_limit is the simulation ceiling, not the value to use — use gas_used.

4.6 Broadcasting

POST /broadcast submits a signed Tx to the mempool and returns a BroadcastTxOutcome. This is a mempool receipt, not block inclusion:

curl -X POST https://<live-host>/broadcast \
  -H 'Content-Type: application/json' \
  -d '{"sender": "0x1234…abcd", "gas_limit": 1500000, "msgs": [ /* … */ ], "data": { /* … */ }, "credential": { /* … */ }}'

{ "tx_hash": "…", "check_tx": { "gas_limit": 1500000, "gas_used": 12000, "result": { "Ok": null }, "events": { /* … */ } } }

An accepted transaction returns 200 with check_tx.result = {"Ok": null}; a mempool-rejected transaction also returns 200, but with check_tx.result an {"Err": …} (it never entered a block). Only a transport failure to the consensus node returns 500. To confirm block inclusion, poll the transaction hash, or watch the event stream. A client already holding a WebSocket connection can broadcast over it instead (§5.4).

4.7 Account and key messages

New users, subaccounts, and key changes go through the account factory contract (ACCOUNT_FACTORY_CONTRACT), not the perps contract.

Register a user — a two-step process. First call register_user on the factory, using the factory address itself as sender and null for data and credential:

{
  "sender": "ACCOUNT_FACTORY_CONTRACT",
  "gas_limit": 1500000,
  "msgs": [
    {
      "execute": {
        "contract": "ACCOUNT_FACTORY_CONTRACT",
        "msg": {
          "register_user": {
            "key": { "secp256r1": "<base64>" },
            "key_hash": "A1B2…",
            "seed": 12345,
            "signature": { "passkey": { "authenticator_data": "<base64>", "client_data": "<base64>", "sig": "<base64>" } }
          }
        },
        "funds": {}
      }
    }
  ],
  "data": null,
  "credential": null
}

The master account is created inactive (spam prevention); the new address is returned in the transaction events. Second, send it at least the minimum_deposit (10 USDC = 10000000 bridge/usdc on mainnet), from an existing Dango account or bridged in via Hyperlane, and the account activates on receipt. To confirm a bridged deposit arrived, query the mailbox’s delivered method with the Hyperlane message id via POST /query (Hash256 uppercase, no 0x); a true result is permanent and means the funds are spendable.