Struct StablecoinDEX 

pub struct StablecoinDEX {
    pub books: <Mapping<B256, Orderbook> as StorableType>::Handler,
    pub orders: <Mapping<u128, Order> as StorableType>::Handler,
    pub balances: <Mapping<Address, Mapping<Address, u128>> as StorableType>::Handler,
    pub next_order_id: <u128 as StorableType>::Handler,
    pub book_keys: <Vec<B256> as StorableType>::Handler,
    address: Address,
    storage: StorageCtx,
}

Fields

books: <Mapping<B256, Orderbook> as StorableType>::Handler

orders: <Mapping<u128, Order> as StorableType>::Handler

balances: <Mapping<Address, Mapping<Address, u128>> as StorableType>::Handler

next_order_id: <u128 as StorableType>::Handler

book_keys: <Vec<B256> as StorableType>::Handler

address: Address

storage: StorageCtx

Implementations

impl StablecoinDEX

pub fn new() -> Self

Creates an instance of the precompile.

Caution: This does not initialize the account, see Self::initialize.

fn __new(address: Address) -> Self

fn __initialize(&mut self) -> Result<()>

fn emit_event(&mut self, event: impl IntoLogData) -> Result<()>

pub fn emitted_events(&self) -> &Vec<LogData>

Available on crate features test-utils only.

pub fn clear_emitted_events(&mut self)

Available on crate features test-utils only.

pub fn assert_emitted_events(&self, expected: Vec<impl IntoLogData>)

Available on crate features test-utils only.

impl StablecoinDEX

pub fn address(&self) -> Address

Returns the StablecoinDEX address.

pub fn initialize(&mut self) -> Result<()>

Initializes the stablecoin DEX precompile.

fn next_order_id(&self) -> Result<u128>

Read next order ID (always at least 1)

fn increment_next_order_id(&mut self) -> Result<()>

Increment next order ID

pub fn balance_of(&self, user: Address, token: Address) -> Result<u128>

Returns the user’s DEX balance for token.

pub fn min_price(&self) -> u32

Returns the minimum representable scaled price (MIN_PRICE).

pub fn max_price(&self) -> u32

Returns the maximum representable scaled price (MAX_PRICE).

fn validate_or_create_pair( &mut self, book: &Orderbook, token: Address, ) -> Result<()>

Validates that a trading pair exists or creates the pair

pub fn get_order(&self, order_id: u128) -> Result<Order>

Fetches an active Order from storage by ID.

Errors

• OrderDoesNotExist — order has a zero maker (already filled/deleted) or has not yet been assigned (ID ≥ next order ID)

fn set_balance( &mut self, user: Address, token: Address, amount: u128, ) -> Result<()>

Set user’s balance for a specific token

fn increment_balance( &mut self, user: Address, token: Address, amount: u128, ) -> Result<()>

Add to user’s balance

fn sub_balance( &mut self, user: Address, token: Address, amount: u128, ) -> Result<()>

Subtract from user’s balance.

fn emit_order_filled( &mut self, order_id: u128, maker: Address, taker: Address, amount_filled: u128, partial_fill: bool, ) -> Result<()>

Emit the appropriate OrderFilled event

fn transfer(&mut self, token: Address, to: Address, amount: u128) -> Result<()>

Transfer tokens, accounting for pathUSD

fn transfer_from( &mut self, token: Address, from: Address, amount: u128, ) -> Result<()>

Transfer tokens from user, accounting for pathUSD

fn decrement_balance_or_transfer_from( &mut self, user: Address, token: Address, amount: u128, ) -> Result<()>

Decrement user’s internal balance or transfer from external wallet

pub fn quote_swap_exact_amount_out( &self, token_in: Address, token_out: Address, amount_out: u128, ) -> Result<u128>

Quotes the input amount required to receive exactly amount_out tokens, routing through one or more orderbooks without executing trades.

Errors

• IdenticalTokens — token_in and token_out are the same address
• InvalidToken — a token address does not have a valid TIP-20 prefix
• PairDoesNotExist — no orderbook exists for one of the hops in the route
• InsufficientLiquidity — not enough resting orders to fill amount_out

pub fn quote_swap_exact_amount_in( &self, token_in: Address, token_out: Address, amount_in: u128, ) -> Result<u128>

Quotes the output amount received for exactly amount_in input tokens, routing through one or more orderbooks without executing trades.

Errors

• IdenticalTokens — token_in and token_out are the same address
• InvalidToken — a token address does not have a valid TIP-20 prefix
• PairDoesNotExist — no orderbook exists for one of the hops in the route
• InsufficientLiquidity — not enough resting orders to fill amount_in

pub fn swap_exact_amount_in( &mut self, sender: Address, token_in: Address, token_out: Address, amount_in: u128, min_amount_out: u128, ) -> Result<u128>

Swaps amount_in of token_in for token_out, routing through one or more orderbooks. Deducts input via TIP20Token transfer or DEX balance, then fills orders at best price per hop.

Errors

• InvalidBaseToken — token address does not have a valid TIP-20 prefix
• PairNotFound — no orderbook exists for the token pair
• InsufficientOutput — final output amount falls below min_amount_out
• InsufficientBalance — sender balance lower than required input

pub fn swap_exact_amount_out( &mut self, sender: Address, token_in: Address, token_out: Address, amount_out: u128, max_amount_in: u128, ) -> Result<u128>

Swaps to receive exactly amount_out of token_out, routing through one or more orderbooks. Works backwards from output to compute input, then deducts via TIP20Token or DEX balance.

Errors

• InvalidBaseToken — token address does not have a valid TIP-20 prefix
• PairNotFound — no orderbook exists for the token pair
• MaxInputExceeded — required input exceeds max_amount_in
• InsufficientBalance — sender balance lower than required input

pub fn get_price_level( &self, base: Address, tick: i16, is_bid: bool, ) -> Result<TickLevel>

Returns the TickLevel for a given base token, tick, and side. Looks up the quote token via TIP20Token and derives the book key.

Errors

• InvalidBaseToken — base address does not resolve to a valid TIP20Token

pub fn books(&self, pair_key: B256) -> Result<Orderbook>

Returns the Orderbook for a given pair key.

pub fn get_book_keys(&self) -> Result<Vec<B256>>

Returns all registered orderbook keys.

pub fn tick_to_price(&self, tick: i16) -> Result<u32>

Converts a relative tick to a scaled price. On T2+ validates TICK_SPACING alignment.

Errors

• InvalidTick — tick is not aligned to TICK_SPACING (T2+ only)

pub fn price_to_tick(&self, price: u32) -> Result<i16>

Converts a scaled price to a relative tick. On T2+ validates TICK_SPACING alignment.

Errors

• TickOutOfBounds — price is outside the [MIN_PRICE, MAX_PRICE] range
• InvalidTick — resulting tick is not aligned to TICK_SPACING (T2+ only)

pub fn create_pair(&mut self, base: Address) -> Result<B256>

Creates a new trading pair between base and its quote token. Both must be USD-denominated tokens validated via TIP20Factory. Reverts if the pair already exists.

Errors

• InvalidBaseToken — token address does not have a valid TIP-20 prefix
• InvalidCurrency — both tokens must be USD-denominated (validated via TIP20Factory).
• PairAlreadyExists — an orderbook for this pair is already initialized

pub fn place( &mut self, sender: Address, token: Address, amount: u128, is_bid: bool, tick: i16, ) -> Result<u128>

Places a limit order on the orderbook for token against its quote token. Escrows the appropriate amount via TIP20Token transfer or DEX balance and enforces compliance via the TIP403Registry. Auto-creates the trading pair if needed.

Errors

• InvalidBaseToken — token address does not have a valid TIP-20 prefix
• TickOutOfBounds — tick is outside the allowed [MIN_TICK, MAX_TICK] range
• InvalidTick — tick is not aligned to TICK_SPACING
• BelowMinimumOrderSize — order amount is below MIN_ORDER_AMOUNT
• InsufficientBalance — sender balance lower than required escrow
• PolicyForbids — TIP-403 policy rejects the token transfer

Returns

The assigned order ID

fn commit_order_to_book(&mut self, order: Order) -> Result<()>

Commits an order to the specified orderbook, updating tick bits, best bid/ask, and total liquidity

pub fn place_flip( &mut self, sender: Address, token: Address, amount: u128, is_bid: bool, tick: i16, flip_tick: i16, internal_balance_only: bool, ) -> Result<u128>

Places a flip order that auto-reverses to the opposite side when fully filled, acting as perpetual liquidity. Escrows tokens via TIP20Token and enforces compliance via TIP403Registry. For bids flip_tick must be > tick; for asks, < tick.

Errors

• InvalidBaseToken — token address does not have a valid TIP-20 prefix
• TickOutOfBounds — tick or flip_tick outside [MIN_TICK, MAX_TICK]
• InvalidTick — tick is not aligned to TICK_SPACING
• InvalidFlipTick — flip_tick on wrong side of tick for order direction
• BelowMinimumOrderSize — order amount is below MIN_ORDER_AMOUNT
• InsufficientBalance — sender balance lower than required escrow
• PolicyForbids — TIP-403 policy rejects the token transfer

fn partial_fill_order( &mut self, order: &mut Order, level: &mut TickLevel, fill_amount: u128, taker: Address, ) -> Result<u128>

Partially fill an order with the specified amount. Fill amount is denominated in base token.

fn fill_order( &mut self, book_key: B256, order: &mut Order, level: TickLevel, taker: Address, ) -> Result<(u128, Option<(TickLevel, Order)>)>

Fill an order and delete from storage. Returns the next best order and price level.

fn fill_orders_exact_out( &mut self, book_key: B256, bid: bool, amount_out: u128, taker: Address, ) -> Result<u128>

Fill orders for exact output amount

fn fill_orders_exact_in( &mut self, book_key: B256, bid: bool, amount_in: u128, taker: Address, ) -> Result<u128>

Fill orders with exact amount in

fn get_best_price_level( &mut self, book_key: B256, is_bid: bool, ) -> Result<TickLevel>

Helper function to get best tick from orderbook

pub fn cancel(&mut self, sender: Address, order_id: u128) -> Result<()>

Cancels an active order and refunds escrowed tokens to the maker. Only the order maker can cancel their own orders.

Errors

• OrderDoesNotExist — order ID not found or already fully filled
• Unauthorized — only the order maker can cancel their order

fn cancel_active_order(&mut self, order: Order) -> Result<()>

Cancel an active order (already in the orderbook)

pub fn cancel_stale_order(&mut self, order_id: u128) -> Result<()>

Cancels an order whose maker is blocked by TIP403Registry policy, allowing anyone to clean up stale liquidity.

TIP-1015: T2+ checks sender authorization (maker must be able to send escrowed tokens)

Errors

• OrderDoesNotExist — order ID not found or already fully filled
• OrderNotStale — order maker is still authorized by TIP-403 policy

pub fn withdraw( &mut self, user: Address, token: Address, amount: u128, ) -> Result<()>

Withdraws amount from the caller’s DEX balance, transferring tokens back via TIP20Token.

Errors

• InsufficientBalance — DEX balance lower than withdrawal amount

fn quote_exact_out( &self, book_key: B256, amount_out: u128, is_bid: bool, ) -> Result<u128>

Quote exact output amount without executing trades

fn find_trade_path( &self, token_in: Address, token_out: Address, ) -> Result<Vec<(B256, bool)>>

Find the trade path between two tokens Returns a vector of (book_key, base_for_quote) tuples for each hop Also validates that all pairs exist

fn validate_and_build_route( &self, path: &[Address], ) -> Result<Vec<(B256, bool)>>

Validates that all pairs in the path exist and returns book keys with direction info

fn find_path_to_root(&self, token: Address) -> Result<Vec<Address>>

Find the path from a token to the root (pathUSD) Returns a vector of addresses starting with the token and ending with pathUSD

fn quote_exact_in( &self, book_key: B256, amount_in: u128, is_bid: bool, ) -> Result<u128>

Quote exact input amount without executing trades

impl StablecoinDEX

pub fn create_precompile(cfg: &CfgEnv<TempoHardfork>) -> DynPrecompile

Creates the EVM precompile for this type.

Trait Implementations

impl ContractStorage for StablecoinDEX

fn address(&self) -> Address

Contract address.

fn storage(&self) -> &StorageCtx

Contract storage accessor.

fn storage_mut(&mut self) -> &mut StorageCtx

Contract storage mutable accessor.

fn is_initialized(&self) -> Result<bool>

Returns true if the contract has been initialized (has bytecode deployed).

impl Default for StablecoinDEX

fn default() -> Self

Returns the “default value” for a type.

impl Precompile for StablecoinDEX

fn call(&mut self, calldata: &[u8], msg_sender: Address) -> PrecompileResult

Dispatches an EVM call to this precompile.

Layout

Note: Most layout information is completely unstable and may even differ between compilations. The only exception is types with certain repr(...) attributes. Please see the Rust Reference's “Type Layout” chapter for details on type layout guarantees.

Size: 536 bytes