Types

Enums are written the way NEAR contracts usually write them in JSON: a variant without fields is a string ("OutputOfLastIn"), a variant with fields is an object with one key ({ "ExactIn": "1000" }). Optional fields can be null or left out, except referral_fees in a DepositMessage, which can only be left out.

Basic types

Type	Format	Example
U128	Integer string, in the asset’s smallest unit	"1000000000000000000000000"
AccountId	NEAR account ID	"alice.near"
Base64	Base64 string of bytes	"AQIDBA=="

AssetId

A string:

Format	Asset
near	Native NEAR
nep141:<contract>	NEP-141 fungible token, for example nep141:usdt.tether-token.near
nep171:<contract>:<token id>	NEP-171 NFT. Its balance is "0" or "1"
nep245:<contract>:<token id>	NEP-245 multi token

These are the same IDs the DEX Aggregator uses after intear-dex:.

DexId

A string, <deployer>/<name>, for example "slimedragon.near/xyk".

AccountOrDexId

An owner of inner balances:

{ "Account": "alice.near" }

{ "Dex": "slimedragon.near/xyk" }

SwapRequestAmount

Value	Meaning
{ "ExactIn": "<U128>" }	Pay exactly this much asset_in
{ "ExactOut": "<U128>" }	Receive exactly this much asset_out

SwapOperationAmount

The amount of a SwapSimple or SwapAdvanced operation:

Value	Meaning
{ "Amount": SwapRequestAmount }	A fixed amount, for example { "Amount": { "ExactIn": "1000" } }
"OutputOfLastIn"	Exact input of the output of the last swap in the list, SwapSimple or SwapAdvanced. Its asset_out must match this asset_in
"EntireBalanceIn"	Exact input of everything available of asset_in

DirectWithdrawAmount

The amount of the withdraw method:

Value	Meaning
{ "Exact": "<U128>" }	A fixed amount
{ "Full": { "at_least": "<U128>" | null } }	The whole balance. Fails if it’s less than at_least

WithdrawAmount

The amount of a Withdraw operation: the same as DirectWithdrawAmount, plus:

Value	Meaning
"PreviousSwapOutput"	The output of the last swap in the list, SwapSimple or SwapAdvanced. Its asset_out must match this asset_id

Operation

One step of execute_operations or of a deposit message.

{
  "SwapSimple": {
    "dex_id": "slimedragon.near/xyk",
    "message": "<base64>",
    "asset_in": "near",
    "asset_out": "nep141:usdt.tether-token.near",
    "amount": "EntireBalanceIn",
    "constraint": "4800000"
  }
}

Operation	Fields	What it does
SwapSimple	dex_id: DexId, message: Base64, asset_in: AssetId, asset_out: AssetId, amount: SwapOperationAmount, constraint?: U128	A swap. constraint is the minimum output for an exact input, or the maximum input for an exact output
SwapAdvanced	asset_in: AssetId, asset_out: AssetId, amount: SwapOperationAmount, constraint?: U128, options: SwapOption[], mode: "FindBest" | "FallbackQueue"	A swap on one of several DEXs or routes: the best of them, or the first that works. See Best of several DEXs
Withdraw	asset_id: AssetId, amount: WithdrawAmount, to?: AccountId, rescue_address?: AccountId	Sends the asset to to (default: you). rescue_address is only used in deposit messages, see Withdrawing from a deposit
TransferAsset	to: AccountOrDexId, asset_id: AssetId, amount: U128	Moves the asset to another inner balance
DexCall	dex_id: DexId, method: string, args: Base64, attached_assets: { [AssetId]: U128 }	Calls a DEX method
StorageDeposit	amount: U128, for: AccountOrDexId	Turns NEAR into a storage balance of for. At least 0.005 NEAR. for is required
RegisterAssets	asset_ids: AssetId[], for?: AccountOrDexId	Registers assets. Only in execute_operations
DeployDexCode	last_part_of_id: string, code_base64: Base64	Deploys DEX code. Only in execute_operations

SwapOption

A DEX that a SwapAdvanced operation can swap on, and the message to pass to it, like the dex_id and message of a SwapSimple:

{ "dex_id": "slimedragon.near/xyk", "message": "<base64>" }

DepositMessage

The msg of a token transfer to the engine, as a JSON string, or operations of deposit_near. Either a list of operations:

[{ "SwapSimple": { ... } }, { "Withdraw": { ... } }]

or an object with a referrer, referral fees, or both:

{ "operations": [{ "SwapSimple": { ... } }], "referrer": "myapp.near", "referral_fees": [["myapp.near", 5000]] }

referrer can be null, but leave referral_fees out instead of setting it to null: null makes the whole message invalid, so deposit_near fails and a token deposit is refunded.

ReferralFees

An array of [AccountId, u32] pairs: the accounts a swap pays referral fees to, out of its input, and the fee of each, where 1000000 is 100%. At most 5 of them, adding up to at most 50000 (5%).

[["myapp.near", 5000], ["partner.near", 1000]]

StorageBalance

{ "total": "10000000000000000000000", "available": "9000000000000000000000" }

total is everything deposited, available is the part not used for storage yet. Both in yoctoNEAR.

Borsh

The engine sends DEXs swap and call requests and reads their responses in Borsh, and dex_events_borsh is Borsh too. Inside them, the swap message, the args of a call and the response of a DEX method are bytes in whatever format the DEX defines (Plach uses Borsh). In Borsh:

• AssetId is an enum: Near (0), Nep141(AccountId) (1), Nep245(AccountId, String) (2), Nep171(AccountId, String) (3).
• DexId is a struct of deployer: AccountId and id: String.
• AccountId is a string.
• Caller, what a DEX gets from the engine’s caller host function, is an enum: Direct(AccountId) (0), the account that called the engine, or OnTransfer { alleged_sender: AccountId, transfer_of: AssetId } (1), for operations in a deposit. See What a DEX sees.

In Rust, these types and the request and response types of DEXs are in the intear-dex-types crate. It isn’t on crates.io, so add it from GitHub:

intear-dex-types = { git = "https://github.com/INTEARnear/dex" }

Outside a contract, also enable the non-contract-usage feature of near-sdk. DEX code enables the crate’s dex feature for the engine’s host functions, like env::caller() and env::dex_event().