rango-types/lib/api/main/routing.d.ts

Rango Exchange Types

import { RoutingResultType } from '../shared/index.js';
import type { Amount, Asset, SwapResult } from './common.js';
import type { TransactionType } from './transactions.js';
export { RoutingResultType };
/**
 * All user wallets for a specific blockchain
 *
 * @property {string} blockchain - The blockchain that wallets belong to
 * @property {string[]} addresses - List of user wallet addresses for the specified blockchain
 *
 */
export type UserWalletBlockchain = {
    blockchain: string;
    addresses: string[];
};
/**
 * Full information of a path of multiple swaps that should be executed by user to swap X to Y
 *
 * @property {string} outputAmount - The estimation of Rango from output amount of Y
 * @property {RoutingResultType} resultType - Indicates that result is OK or have some problems such as Price Impact issue.
 * If there is a price impact issue Rango won't allow dApps to createTransaction and it will fail because of the risk of huge loss for user.
 * @property {SwapResult[]} swaps - List of required swaps to swap X to Y with the expected outputAmount
 *
 */
export type SimulationResult = {
    outputAmount: string;
    resultType: RoutingResultType;
    swaps: SwapResult[];
};
/**
 * Describing a required Asset for swapping X to Y and check if the wallet has enough balance or not
 *
 * @property {Asset} asset - asset required for fee or balance
 * @property {Asset} requiredAmount
 * @property {Amount} currentAmount
 * @property {boolean} ok - If true, means this requirement is fulfilled, false means swap may fail due to insufficient balance
 * @property {string} reason - 'FEE' | 'FEE_AND_INPUT_ASSET' | 'INPUT_ASSET'
 *
 */
export type WalletRequiredAssets = {
    asset: Asset;
    requiredAmount: Amount;
    currentAmount: Amount;
    ok: boolean;
    reason: 'FEE' | 'FEE_AND_INPUT_ASSET' | 'INPUT_ASSET';
};
/**
 * The validation status of a wallet
 *
 * @property {string} address - The address of wallet
 * @property {boolean} addressIsValid - If false, the wallet address is invalid for the given blockchain
 * @property {WalletRequiredAssets[]} requiredAssets - The list of required assets for swapping X to Y in this wallet
 * and the status to indicate whether these assets are missing or not
 * @property {boolean} validResult - If false, Rango was unable to fetch the balance of this address to check the
 * requiredAssets availability
 *
 */
export type WalletValidationStatus = {
    address: string;
    addressIsValid: boolean;
    requiredAssets: WalletRequiredAssets[];
    validResult: boolean;
};
/**
 * The blockchain that this validation data belongs to
 *
 * @property {string} blockchain - The blockchain of validation
 * @property {WalletValidationStatus[]} wallets - The status of validation for all the wallets of the specific blockchain
 *
 */
export type BlockchainValidationStatus = {
    blockchain: string;
    wallets: WalletValidationStatus[];
};
/**
 * The data required for relaying message from the source chain to the target chain in a cross-chain swap
 *
 * @property {string} sourceContract - Address of your contract on source chain (will be called in case of refund in the source chain)
 * @property {string} destinationContract - Address of your contract on destination chain (will be called in case of success/refund in the destination chain)
 * @property {string} imMessage - The message that you want to pass to your contract on the destination chain
 *
 */
export type InterChainMessage = {
    sourceContract: string;
    destinationContract: string;
    imMessage: string;
};
/**
 * Body of routing request
 *
 * @property {Asset} from - The source asset
 * @property {Asset} to - The destination asset
 * @property {string} amount - The human-readable amount of asset X that is going to be swapped, example: 0.28
 * @property {{ [key: string]: string }} selectedWallets - Map of blockchain to selected address
 * @property {UserWalletBlockchain[] | null} [connectedWallets] - List of all user connected wallet addresses per each blockchain
 * @property {boolean} [checkPrerequisites] - It should be false when client just likes to preview the route to user,
 * and true when user accepted to swap. If true, server will be slower to respond, but will check some pre-requisites including balance
 * of token X and required fees in user's wallets. The default value is false.
 * @property {string} [slippage] - User slippage, used to filter routes which are incompatible with this slippage
 * @property {string} [destination] - Custom destination for the route
 * @property {boolean} [forceExecution] - Use this flag if you want to ignore checkPrerequisites before executing the route
 * @property {string | null} [affiliateRef] - To enable dApps to charge affiliate fees and generate income from users' transactions,
 * the affiliate referral code should be provided. You can create this code by visiting the following link: https://app.rango.exchange/affiliate.
 * @property {number | null} [affiliatePercent] - If you want to change the default affiliate fee percentage, you can provide a new value here.
 * @property {{ [key: string]: string }} [affiliateWallets] - If you want to change the default affiliate wallet addresses, you can provide new values here.
 * (Map of route blockchains to affiliate address)
 * @property {boolean} [disableMultiStepTx] - It should be false when client wants to support multi-transactions per route step. default is true.
 * @property {string[]} [blockchains] - List of all accepted blockchains, an empty list means no filter is required
 * @property {string[]} [swappers] - List of all accepted swappers, an empty list means no filter is required
 * @property {boolean} [swappersExclude] - Indicates include/exclude mode for the swappers param
 * @property {string[]} [swapperGroups] - List of all accepted swapper groups, an empty list means no filter is required
 * @property {boolean} [swappersGroupsExclude] - Indicates include/exclude mode for the swappers group param
 * @property {TransactionType[]} [transactionTypes] - List of all accepted transaction types including [EVM, TRANSFER, COSMOS, ...]
 * @property {string[]} [messagingProtocols] - List of all messaging protocols, an empty list means no filter is required
 * @property {number} [maxLength] - Maximum number of steps in a route
 * @property {boolean} [experimental] - For enabling experimental features in routing
 * @property {boolean} [contractCall] - Mark it true if you are going to call this route via your own contract, so we
 * will filter routes that are not possible to be called from a contract
 * @property {InterChainMessage} [interChainMessage] - The data required for relaying message in a cross-chain swap
 * @property {boolean} [enableCentralizedSwappers] - You could set this parameter to true if you want to enable routing from the centralized protocols like Exodus.
 * By default, this parameter is false.
 * @property {boolean} [avoidNativeFee] - When it is true, Swappers that have native tokens as fee must be excluded. example: when you call it from AA account.
 *
 */
export type BestRouteRequest = {
    from: Asset;
    to: Asset;
    amount: string;
    selectedWallets: {
        [key: string]: string;
    };
    connectedWallets?: UserWalletBlockchain[] | null;
    checkPrerequisites?: boolean;
    slippage?: string;
    destination?: string;
    forceExecution?: boolean;
    affiliateRef?: string | null;
    affiliatePercent?: number | null;
    affiliateWallets?: {
        [key: string]: string;
    };
    disableMultiStepTx?: boolean;
    blockchains?: string[];
    swappers?: string[];
    swappersExclude?: boolean;
    swapperGroups?: string[];
    swappersGroupsExclude?: boolean;
    transactionTypes?: TransactionType[];
    messagingProtocols?: string[];
    maxLength?: number;
    experimental?: boolean;
    contractCall?: boolean;
    interChainMessage?: InterChainMessage | null;
    enableCentralizedSwappers?: boolean;
    avoidNativeFee?: boolean;
};
/**
 * The response of best route, if the result fields is null, it means that no route is found
 *
 * @property {string} requestId - The unique requestId which is generated for this request by the server. It should be
 * passed down to all other endpoints if this swap continues on. e.g. d10657ce-b13a-405c-825b-b47f8a5016ad
 * @property {string} requestAmount - The human readable input amount from the request
 * @property {Asset} from - The source asset
 * @property {Asset} to - The destination asset
 * @property {SimulationResult | null} result
 * @property {BlockchainValidationStatus[]} validationStatus - Pre-requisites check result. It will be null if
 * the request checkPrerequisites was false
 * @property {string[]} diagnosisMessages - list of string messages that might be cause of not finding the route.
 * It's just for display purposes
 * @property {string[]} missingBlockchains - List of all blockchains which are necessary to be present for the best
 * route and user has not provided any connected wallets for it. A null or empty list indicates that there is no problem.
 * @property {boolean} walletNotSupportingFromBlockchain - A warning indicates that none of your wallets have the same
 * blockchain as X asset
 * @property {boolean} boolean - A The state of confirm swap
 * @property {string | null} error - Error message
 * @property {number | null} errorCode - Error code
 * @property {number | null} traceId - Trace Id, for debug purpose
 *
 */
export type BestRouteResponse = {
    requestId: string;
    requestAmount: string;
    from: Asset;
    to: Asset;
    result: SimulationResult | null;
    validationStatus: BlockchainValidationStatus[];
    diagnosisMessages: string[];
    missingBlockchains: string[];
    walletNotSupportingFromBlockchain: boolean;
    error: string | null;
    errorCode: number | null;
    traceId: number | null;
};
export type Tag = 'RECOMMENDED' | 'FASTEST' | 'LOWEST_FEE' | 'HIGH_IMPACT' | 'CENTRALIZED';
/**
 * A tag that can be assigned to a route.
 */
export type TagValue = Tag | Omit<string, Tag>;
/**
 * The multi-routing result tag.
 *
 * @property {string} label - The human-readable label.
 * @property {TagValue} value - The value of Tag.
 */
export type RouteTag = {
    label: string;
    value: TagValue;
};
/**
 * The type of preferences for sorting routes.
 */
export type PreferenceType = 'FEE' | 'SPEED' | 'PRICE' | 'NET_OUTPUT' | 'SMART';
/**
 * Score calculated for each preference for sorting in UI
 *
 * @property {PreferenceType} preferenceType - Type of evaluated aspect.
 * @property {number} score - Value of score (typically between 0 to 100).
 */
export type SimulationScore = {
    preferenceType: PreferenceType;
    score: number;
};
/**
 * Full information of a path of multiple swaps that should be executed by user to swap X to Y
 *
 * @property {string} requestId - The unique requestId which is generated for this request by the server. It should be
 * passed down to all other endpoints if this swap continues on. e.g. d10657ce-b13a-405c-825b-b47f8a5016ad
 * @property {string} outputAmount - The estimation of Rango from output amount of Y
 * @property {RoutingResultType} resultType - Indicates that result is OK or have some problems such as Price Impact issue.
 * If there is a price impact issue Rango won't allow dApps to createTransaction and it will fail because of the risk of huge loss for user.
 * @property {SwapResult[]} swaps - List of required swaps to swap X to Y with the expected outputAmount
 * @property {SimulationScore[]} scores - List of scores calculated for each preference aspect
 * @property {RouteTag[]} tags - List of tags attributed to each route considering every aspect
 * @property {string[]} missingBlockchains - List of all blockchains which are necessary to be present for the best
 * route and user has not provided any connected wallets for it. A null or empty list indicates that there is no problem.
 * @property {boolean} walletNotSupportingFromBlockchain - A warning indicates that none of your wallets have the same
 * blockchain as X asset
 */
export type MultiRouteSimulationResult = {
    requestId: string;
    outputAmount: string;
    resultType: RoutingResultType;
    swaps: SwapResult[];
    scores: {
        preferenceType: PreferenceType;
        score: number;
    }[];
    tags: RouteTag[];
    missingBlockchains: string[];
    walletNotSupportingFromBlockchain: boolean;
};
/**
 * The best route request body for multi-routing
 */
export type MultiRouteRequest = Omit<BestRouteRequest, 'selectedWallets' | 'destination' | 'checkPrerequisites' | 'forceExecution' | 'maxLength'>;
/**
 * The best route response for multi-routing, if the results field is empty, it means that no route is found
 *
 * @property {Asset} from - The source asset
 * @property {Asset} to - The destination asset
 * @property {string} requestAmount - The human readable input amount from the request
 * @property {string} routeId - The unique roteId generated for this request by server
 * @property {MultiRouteSimulationResult} results - List of best routes data
 * @property {string[]} diagnosisMessages - list of string messages that might be cause of not finding the route.
 * It's just for display purposes
 * @property {string | null} error - Error message
 * @property {number | null} errorCode - Error code
 * @property {number | null} traceId - Trace Id, for debug purpose
 */
export type MultiRouteResponse = {
    from: Asset;
    to: Asset;
    requestAmount: string;
    routeId: string;
    results: MultiRouteSimulationResult[];
    diagnosisMessages: string[];
    error: string | null;
    errorCode: number | null;
    traceId: number | null;
};
/**
 * The body of confirmation request for selected route.
 *
 * @property {string} requestId - The unique requestId which is generated for this request by the server. It should be
 * passed down to all other endpoints if this swap continues on. e.g. d10657ce-b13a-405c-825b-b47f8a5016ad
 * @property {{ [key: string]: string }} selectedWallets - Map of blockchain to selected address
 * @property {string} [destination] - Custom destination for the route
 */
export type ConfirmRouteRequest = {
    requestId: string;
    selectedWallets: {
        [key: string]: string;
    };
    destination?: string;
};
/**
 * The response of confirmation request for selected route
 *
 * @property {boolean} ok - If true, the result has a value and error message is null.
 * @property {BestRouteResponse | null} result - Result of confirm swap
 * @property {string | null} error - Error message about the incident if ok == false.
 * @property {string | null} errorCode - Error code about the incident if ok == false.
 * @property {number | null} traceId - Trace Id, for debug purpose
 */
export type ConfirmRouteResponse = {
    ok: boolean;
    result: Omit<BestRouteResponse, 'error' | 'errorCode' | 'traceId'> | null;
    error: string | null;
    errorCode: string | null;
    traceId: number | null;
};
//# sourceMappingURL=routing.d.ts.map