AlphaDEX Documentation

Scrypto Component Methods

This document serves as a reference for anyone who wants to integrate their Scrypto component(s) with AlphaDEX. It lists the methods that are available for users of the AlphaDEX exchange.
AlphaDEX consists of one main exchange (AlphadexExchange) component and several pair (AlphadexPair) components. All the components are global components that can be accessed independently on the ledger. Pair components can only be created by the exchange component and the exchange component provides a function (get_all_pairs) to get a list of all the pairs (and their component addresses) on the exchange.

AlphaDEX Scrypto Package Address

RCNet v3.1: package_tdx_e_1phu0w2rdxrs4et6gapvm6yvteygmnhppshqfy38k34j8l5gp0qt075

AlphaDEX Exchange Component Address

RCNet v3.1: component_tdx_e_1crp9wwvc8t0reg2hdu9m2lg64nsky4k7nsn2tnk9vcme683l4wthu0

Exchange Component Methods

Method: new_pair:

Call signature:

pub fn new_pair(
    &mut self,
    token1_address: ResourceAddress,
    token2_address: ResourceAddress,
    estimated_price: Decimal,
    mut fee_bucket: FungibleBucket,
    platform_badge_id: u32,
) -> (Global<AlphadexPair>, FungibleBucket)

Description:

Creates a new trading pair on the exchange. A fee of 500 XRD is payable to create a new pair to avoid spamming of dead pairs on the exchange. If the pair includes XRD, then the convention is to make XRD the 2nd token in the pair (token2).

Parameters:

token1_address	The resource address of the first token in the pair.
token2_address	The resource address of the second token in the pair.
estimated price	The estimated price of the pair expressed as how many of token2 is required to buy 1 token1. This value is required to calculate the minimum price increase (also sometimes called the price tick).
fee_bucket	Bucket with at least 500 XRD to pay the fee for creating a new pair on the exchange
platform_badge_id	The id of the platform through which the transaction is being submitted. This platform will get a share of the fee.

Returns:

Global<AlphadexPair>	A global reference to the newly created pair component.
FungibleBucket	Any remaining tokens in fee_bucket.

Events:

AlphadexPairEvent(CREATE).

Method: new_platform_badge

Call signature:

pub fn new_platform_badge(&mut self, platform_name: String, fee: Decimal) -> Bucket

Description:

Creates a new platform badge which will charge the specified fee. A platform badge is used to identify any platform through which users can place orders/trades on AlphaDEX. The badge allows the platform to earn a portion of the fee on every trade that involves its users. The platform fee specified must be between 0% and 0.1%. Platforms can have more than one badge with different fees if they want to charge their users differentiated fees. The platform badge is also used to claim accumulated platform fees from the exchange

Parameters:

platform_name	The name of the platform/app this badge is for.
fee	The fee that this platform wants to charge on every trade from its users. The fee should be expressed in decimals. (i.e. 0.1% = 0.001).

Returns:

Bucket

The new platform badge NFT.

Events:

AlphadexPlatformEvent(CREATE)

Method: new_platform_badge_with _max_fee

Call signature:

pub fn new_platform_badge_with_max_fee(&mut self, platform_name: String) -> Bucket

Description:

Creates a new platform badge which will charge the maximum allowed platform fee (0.1%). A platform badge is used to identify any platform through which users can place orders/trades on AlphaDEX. The badge allows the platform to earn a portion of the fee on every trade that involves its users. Platforms can have more than one badge with different fees if they want to charge their users differentiated fees. The platform badge is also used to claim accumulated platform fees from the exchange.

Parameters:

platform_name

The name of the platform/app this badge is for.

Returns:

Bucket

The new platform badge NFT.

Events:

AlphadexPlatformEvent(CREATE)

Method: change_platform_fee

Call signature:

pub fn change_platform_fee(&mut self, new_fee: Decimal, platform_proof: Proof)

Description:

Changes the fee on a platform badge. The fee specified must be between 0% and 0.1%.

Parameters:

new_fee:	The new fee that the platform wants to charge on every trade from its users. The fee should be expressed in decimals. (i.e. 0.1% = 0.001) The platform fee cannot be set higher than 0.1% (0.001).
platform_proof:	Proof of the platform badge for which to change the fee.

Returns:

Nothing

Events:

AlphadexPlatformEvent(FEE_CHANGE)

Method: change_platform_name

Call signature:

pub fn change_platform_name(&mut self, new_platform_name: String, platform_proof: Proof)

Description:

Changes the name for a platform badge.

Parameters:

new_platform_name:	The new name for the platform.
platform_proof:	Proof of the platform badge for which to change the fee.

Returns:

Nothing

Events:

AlphadexPlatformEvent(NAME_CHANGE)

Method: claim_platform_exchange_fee

Call signature:

    pub fn claim_platform_exchange_fees(
    &mut self,
    platform_proof: Proof,
) -> (FungibleBucket, FungibleBucket)

Description:

Claims unclaimed fees on the exchange component due to the platform. The exchange component only earns fees in XRD, but to keep the structure the same with the same function in trading pairs, this function also returns 2 buckets (one XRD bucket and one empty bucket).

Parameters:

platform_proof:

Proof of the platform badge for which to claim fees.

Returns:

FungibleBucket	Unclaimed fees in XRD.
FungibleBucket	Empty bucket (exchange component fees are always XRD, so this empty bucket is returned to keep the format the same as the similar function in a pair.

Events:

AlphadexPlatformEvent(CLAIM_FEES)

Method: swap:

Call signature:

pub fn swap(
    &mut self,
    from_tokens: FungibleBucket,
    to_token_address: ResourceAddress,
    max_slippage: Decimal,
    platform_badge_id: u32,
) -> (FungibleBucket, Decimal)

Description:

Swaps between any two tokens on the exchange. If a direct pair does not exist between the tokens the function will execute 2 swaps: from_token -> XRD -> to_token

Parameters:

from_tokens:	A bucket with the tokens to swap from.
to_token_address:	The resource address of the token to swap to.
max_slippage:	The maximum percentage of price slippage to tolerate in the swap. The slippage percentage is specified in decimals (i.e. 0.1% = 0.001).
platform_badge_id:	The id of the platform that is facilitating the swap

Returns:

FungibleBucket	The tokens received from the swap.
Decimal	The actual slippage percentage experienced in the swap, expressed in decimals (i.e. 0.1% = 0.001).

Events:

AlphadexSwapEvent(CREATE)

Method: std_swap:

Call signature:

pub fn std_swap(
    &mut self,
    from_tokens: FungibleBucket,
    to_token_address: ResourceAddress,
) -> (FungibleBucket, Decimal)

Description:

Standard format swap function. Swaps between any two tokens on the exchange. If a direct pair does not exist between the tokens the function will execute 2 swaps: from_token -> XRD -> to_token. This function is exactly the same as the swap function, but it has no slippage limit and uses a zero fee platform.

Parameters:

from_tokens:	A bucket with the tokens to swap from.
to_token_address:	The resource address of the token to swap to.

Returns:

FungibleBucket	The tokens received from the swap.
FungibleBucket	An empty bucket to conform to the standard format swap output. This bucket would normally containing any remaining from_tokens that were not used in the swap.

Events:

AlphadexSwapEvent(CREATE)

Method: get_all_pairs:

Call signature:
fn get_all_pairs(&self, only_active: bool) -> Vec<PairInfo>

Description:

Returns a list of all the pairs that are on the exchange.

Parameters:

only_active:

Indicates whether to only return active pairs (true) or all pairs (false).

Returns:

Vec<PairInfo>:	a list with basic information about each pair.
PairInfo:
name:	The name of the pair.
address:	The global component address of the pair.
token1:	The resource address of the 1st token in the pair.
token2:	The resource address of the 2nd token in the pair.
status:	The activation status of the pair. Either ACTIVE or INACTIVE.

Events:

None

Method: get_all_tokens:

Call signature:
pub fn get_all_tokens(&self) -> Vec<ResourceAddress>

Description:

Returns a list of all the tokens on the exchange.

Parameters:

None

Returns:

Vec <ResourceAddress>:

A list of the resource addresses of all the tokens on the exchange.

Events:

None

Method: get_token_pairs :

Call signature:

pub fn get_token_pairs(
    &self,
    token_address: ResourceAddress,
    only_active: bool,
) -> Vec<PairInfo>

Description:

Returns a list of all the pairs on the exchange that contains the specified token.

Parameters:

token_address:	The resource address of the token you want to find pairs for..
only_active:	Indicates whether to only return active pairs (true) or all pairs (false).

Returns:

Vec<PairInfo>:	a list with basic information about each pair.
PairInfo:
name:	The name of the pair.
address:	The global component address of the pair.
token1:	The resource address of the 1st token in the pair.
token2:	The resource address of the 2nd token in the pair.
status:	The activation status of the pair. Either ACTIVE or INACTIVE.

Events:

None

Method: get_platform_unclaimed_fees

Call signature:

pub fn get_platform_unclaimed_fees(
    &self,
    platform_proof: Proof,
) -> HashMap<ComponentAddress, (Decimal, Decimal)>

Description:

Returns all the unclaimed fees per pair for a platform badge.

Parameters:

platform_proof:

Proof of the platform badge for which to lookup unclaimed fees.

Returns:

HashMap <ComponentAddress, (Decimal, Decimal):	A map of the pair component addresses and the associated unclaimed platform fees for each pair.
ComponentAddress:	The ComponentAddress of the pair
Decimal:	Amount of unclaimed fees in token1 of the pair
Decimal:	Amount of unclaimed fees in token2 of the pair

Events:

None

Pair Component Methods

Method: swap

Call signature:

pub fn swap(
    &mut self,
    from_tokens: FungibleBucket,
    max_slippage: Decimal,
    platform_badge_id: u32,
) -> (FungibleBucket, Decimal)

Description:

Swaps between the two tokens in the pair.

Parameters:

from_tokens:	A bucket with the tokens to swap from
max_slippage:	The maximum percentage of price slippage to tolerate in the swap. The slippage percentage is specified in decimals (i.e. 0.1% = 0.001.
platform_badge_id:	The id of the platform that is facilitating the swap.

Returns:

FungibleBucket:	The tokens received from the swap
Decimal:	The actual slippage percentage experienced in the swap, expressed in decimals (i.e. 0.1% = 0.001).

Events:

AlphadexSwapEvent(CREATE)

Method: std_swap

Call signature:

pub fn std_swap(
    &mut self,
    from_tokens: FungibleBucket,
    to_token_address: ResourceAddress,
) -> (FungibleBucket, FungibleBucket)

Description:

Standard format swap function. Swaps between the two tokens in the pair. This function is exactly the same as the swap function, but it has no slippage limit and uses a zero fee platform

Parameters:

from_tokens:	A bucket with the tokens to swap from
to_token_address:	The resource address of the token to swap to

Returns:

FungibleBucket:	The tokens received from the swap
FungibleBucket:	an empty bucket to conform to the standard format swap output. This bucket would normally containing any remaining from_tokens that were not used in the swap.

Events:

AlphadexSwapEvent(CREATE)

Method: new_market_order

Call signature:

        pub fn new_market_order(
            &mut self,
            order_type: String,
            order_side: String,
            token: ResourceAddress,
            amount: Decimal,
            max_slippage: Decimal,
            order_bucket: FungibleBucket,
            platform_badge_id: u32,
        ) -> (NonFungibleBucket, FungibleBucket, FungibleBucket, Decimal)

Description:

Executes a market order in the pair. Market orders do not get added to the orderbook if they cannot be matched completely.

Parameters:

order_type:	The type of the market order to place. Can either be 'MARKET' or 'MARKETPARTIAL'. MARKET: the order is either fulfilled completely or rejected. MARKETPARTIAL: the order is fulfilled as much as possible and the rest of the tokens (if any) are returned.
order_side:	The side of the order. Can either be BUY or SELL.
token:	The resource address of the specified token that you want to BUY/SELL
amount:	The amount of the specified token that you want to BUY/SELL.
max_slippage:	The maximum percentage of price slippage to allow for the order. Expressed in decimals. I.e. 0.1% = 0.001
order_bucket:	A bucket with the tokens needed for the order.
platform_badge _id:	The id of the platform through which the swap is submitted.

Returns:

NonFungibleBucket:	The receipt NFT for this order.
FungibleBucket:	The tokens received from the order.
FungibleBucket:	Any remaining tokens received for the order.
Decimal:	The actual percentage slippage experienced during the order. Expressed in decimals. I.e. 0.1% = 0.001.

Events:

AlphadexOrderEvent(CREATE)

Method: new_limit_order

Call signature:

    pub fn new_limit_order(
        &mut self,
        order_type: String,
        order_side: String,
        token: ResourceAddress,
        amount: Decimal,
        price: Decimal,
        order_bucket: FungibleBucket,
        platform_badge_id: u32,
settlement_account_address: ComponentAddress,
    ) -> (NonFungibleBucket, FungibleBucket, FungibleBucket)

Description:

Executes a limit order in the pair. The portion of the order that can be matched immediately will be returned to the caller. The unmatched portion of the order will be added to the orderbook and when matched the proceeds will be sent to the specified settlement account.

Parameters:

order_type:	The type of the limit order to place. Can either be 'LIMIT' or 'POSTONLY'. LIMIT: A LIMIT order allows for some/all of the order to be matched immediately if possible with the remainder being added to the orderbook. POSTONLY: A POSTONLY order will fail if it can be matched partially/fully immediately. Use POSTONLY when you want to ensure that your limit order is only added to the orderbook.
order_side:	The side of the order. Can either be BUY or SELL.
token:	The resource address of the specified token that you want to BUY/SELL
amount:	The amount of the specified token that you want to BUY/SELL.
price:	The price at which you want your order to be matched or added to the orderbook. For a LIMIT order, if a better price is available to match the order, that price will be used for matching.
order_bucket:	A bucket with the tokens needed for the order.
platform_badge_id:	The id of the platform through which the swap is submitted.
settlement_account _address:	The global address of the account component to receive the proceeds of the order once placed on the orderbook.

Returns:

NonFungibleBucket:	The receipt NFT for this order.
FungibleBucket:	The tokens received from the order.
FungibleBucket:	Any remaining tokens received for the order.

Events:

AlphadexOrderEvent(CREATE)

Method: new_limit_order_to_claim

Call signature:

pub fn new_limit_order_to_claim(
    &mut self,
    order_type: String,
    order_side: String,
    token: ResourceAddress,
    amount: Decimal,
    price: Decimal,
    order_bucket: FungibleBucket,
    platform_badge_id: u32,
) -> (NonFungibleBucket, FungibleBucket, FungibleBucket)

Description:

Parameters:

order_type:	The type of the limit order to place. Can either be 'LIMIT' or 'POSTONLY'. LIMIT: A LIMIT order allows for some/all of the order to be matched immediately if possible with the remainder being added to the orderbook. POSTONLY: A POSTONLY order will fail if it can be matched partially/fully immediately. Use POSTONLY when you want to ensure that your limit order is only added to the orderbook.
order_side:	The side of the order. Can either be BUY or SELL.
token:	The resource address of the specified token that you want to BUY/SELL
amount:	The amount of the specified token that you want to BUY/SELL.
price:	The price at which you want your order to be matched or added to the orderbook. For a LIMIT order, if a better price is available to match the order, that price will be used for matching.
order_bucket:	A bucket with the tokens needed for the order.
platform_badge_id:	The id of the platform through which the swap is submitted.

Returns:

NonFungibleBucket:	The receipt NFT for this order.
FungibleBucket:	The tokens received from the order.
FungibleBucket:	Any remaining tokens received for the order.

Events:

AlphadexOrderEvent(CREATE)

Method: claim_order_tokens

Call signature:

        pub fn claim_order_tokens(
            &mut self,
            orders_proof: Proof,
        ) -> (FungibleBucket, FungibleBucket)

Description:

Claims all retained tokens kept in a pair for the specified orders.

Parameters:

orders_proof:

A proof of a Vec of order receipts for this pair.

Returns:

NonFungibleBucket:	The receipt NFT for this order.
FungibleBucket:	The unclaimed token1 for the specified orders.
FungibleBucket:	The unclaimed token2 for the specified orders.

Events:

AlphadexOrderEvent(CLAIM_TOKENS)

Method: cancel_order

Call signature:

pub fn claim_order_tokens(
    &mut self,
    order_proof: Proof,
) -> (FungibleBucket, FungibleBucket)

Description:

Cancels and order that is still PENDING on the orderbook.

Parameters:

orders_proof:

A proof of the order receipt for the order to be cancelled.

Returns:

FungibleBucket:	The unclaimed / unmatched token1 for the cancelled order.
FungibleBucket:	The unclaimed / unmatched token2 for the cancelled order.

Events:

AlphadexOrderEvent(CANCEL)

Method: claim_platform_fees

Call signature:

pub fn claim_platform_fees(
    &mut self,
    platform_badge: Proof,
) -> (FungibleBucket, FungibleBucket)

Description:

Claims the accumulated platform fees in the pair for the specified platform.

Parameters:

platform_badge:

Proof of the platform badge for which to claim fees.

Returns:

FungibleBucket:	Unclaimed token1 platform fees.
FungibleBucket:	Unclaimed token2 platform fees.

Events:

AlphadexPlatformEvent(CLAIM_FEES)

Method: get_last_price:

Call signature:

        pub fn get_last_price(&self) -> Option<Decimal>

Description:

Returns an option of the last price that the pair traded at.

Parameters:

None

Returns:

Option<Decimal>:

An Option containing either the last price the pair traded at or None if the pair has not had a trade yet.

Events:

None

Method: get_prices

Call signature:

pub fn get_prices(&self) -> (Option<Decimal>, Option<Decimal>, Option<Decimal>)

Description:

Returns an option of each of:

the last price that the pair traded at

the best buy price available

the best sell price available

Parameters:

None

Returns:

Option<Decimal>:	An Option containing either the last price the pair traded at or None if the pair has not had a trade yet..
Option<Decimal>:	An Option containing either the best (highest) buy price in the pair or None if the pair has no buy orders.
Option<Decimal>:	An Option containing either the best (lowest) sell price in the pair or None if the pair has no sell orders.

Events:

None

Method: get_orderbook

Call signature:

pub fn get_orderbook(
    &self,
    price_high: Decimal,
    price_low: Decimal,
) -> (Vec<OrderbookLine>, Vec<OrderbookLine>)

Description:

Returns the orderbook information for the pair.

Parameters:

price_high:	The highest price to include in the returned orderbook data
price_low:	The lowest price to include in the returned orderbook data.

Returns:


        Vec <OrderbookLine>:  A list of orderbookLine information for buy orders.
        Vec <OrderbookLine>:  A list of orderbookLine information for sell orders.
        OrderbookLine: price: the price of the orderbook line
quantity_remaining: the amount of token1 available at this price
value_remaining: the amount of token2 available at this price
orders: a list of the order ids available at this price.

Events:

None

Method: get_price_max_decimals:

Call signature:

        pub fn get_price_max_decimals(&self) -> u32

Description:

Returns the maximum number of decimals in the price of the pair. This can be used to calculate the minimum price increase (price tick) as 10^(-maximum decimals).

Parameters:

None:

Returns:

u32:	The maximum number of decimals in the price of the pair.

Events:

None

Vec <OrderbookLine>:	A list of orderbookLine information for buy orders.
Vec <OrderbookLine>:	A list of orderbookLine information for sell orders.
OrderbookLine:	price: the price of the orderbook line quantity_remaining: the amount of token1 available at this price value_remaining: the amount of token2 available at this price orders: a list of the order ids available at this price.