Transaction Memos
Understanding Transaction Memo In Detail
Overview
Transactions to MAYAChain pass user intent with the MEMO
field on their respective chains. MAYAChain inspects the transaction object and the MEMO
in order to process the transaction, so care must be taken to ensure the MEMO
and the transaction are both valid. If not, MAYAChain will automatically refund the assets. All memos are listed here.
MAYAChain uses specific Asset Notation for all assets. Assets and functions can be abbreviated and Affiliate Addresses and asset amounts can be shortened to reduce memo length.
Guides have been created for Swap and Savers to enable quoting and the automatic construction of memos for simplicity.
Memo Size Limits
MAYAChain has a memo size limit of 250 bytes, any inbound tx sent with a larger memo will be ignored. Additionally, memos on UTXO chains are further constrained by the OP_RETURN
size limit, which is 80 bytes.
Format
All memos follow the format: FUNCTION:PARAM1:PARAM2:PARAM3:PARAM4
The function is invoked by a string, which in turn calls a particular handler in the state machine. The state machine parses the memo looking for the parameters which it simply decodes from human-readable strings.
In addition, some parameters are optional. Simply leave them blank, but retain the :
separator:
FUNCTION:PARAM1:::PARAM4
Permitted Functions
The following functions can be put into a memo:
Swap
Perform a swap.
SWAP:ASSET:DESTADDR/REFUNDADDR:LIM/INTERVAL/QUANTITY:AFFILIATE[/AFF2...]:FEE[/FEE2...]:DEXAggregatorAddr:FinalTokenAddr:MnAmountOut
Syntactic Examples:
SWAP:ASSET:DESTADDR
simple swapSWAP:ASSET:DESTADDR:LIM
swap with trade limitSWAP:ASSET:DESTADDR:LIM/
swap with limit, do not stream swap1/1SWAP:ASSET:DESTADDR:LIM/
swap with limit, optimise swap amount, every 3 blocks3/0SWAP:ASSET:DESTADDR:LIM/1/0:AFFILIATE:FEE
swap with limit, optimised,using affiliate address and feeSWAP:ASSET:DESTADDR:LIM/1/0:AFFILIATE_NAME
swap with limit, optimised,using affiliate MAYAName and default fee (set in MAYAName)SWAP:ASSET:DESTADDR:
:AFFILIATE_NAME:FEE
swap with affiliate MAYAName and overridden default feeSWAP:ASSET:DESTADDR::AFF1/AFF2/AFF3
swap with three affiliate MAYANames using default basis points valuesSWAP:ASSET:DESTADDR::AFF1/AFF2/AFF3:/20/
swap with three affiliate MAYANames using default basis points values for AFF1 and AFF3 and with overridden default fee for AFF2
Actual Examples:
SWAP:ETH.ETH:0xe6a30f4f3bad978910e2cbb4d97581f5b5a0ade0
- swap to Ether, send output to the specified address.SWAP:ETH.ETH:0xe6a30f4f3bad978910e2cbb4d97581f5b5a0ade0:10000000,
same as above except the Ether output should be more than 0.1 Ether else refund.SWAP:ETH.ETH:0xe6a30f4f3bad978910e2cbb4d97581f5b5a0ade0:10000000
/1/1,
same as above except explicitly stated,do not stream the swap.SWAP:ETH.ETH:0xe6a30f4f3bad978910e2cbb4d97581f5b5a0ade0:10000000
/3/0,
same as above except told to allow streaming swap, mini swap every 3 blocks and MAYAChain to work out the number of swaps required to achieve optimal price efficiency.SWAP:ETH.ETH:0xe6a30f4f3bad978910e2cbb4d97581f5b5a0ade0:10000000
/3/0:t:10
- same as above except will send 10 basis points from the input and send it tot
(THORSwap's MAYAName).
The above memo can be further reduced to:
=:ETH.ETH:0xe6a30f4f3bad978910e2cbb4d97581f5b5a0ade0:1e6/3/0:t:10
If the MAYAName t
has Affiliate Basis Points set, the memo can be reduced even further to:
=:ETH.ETH:0xe6a30f4f3bad978910e2cbb4d97581f5b5a0ade0:1e6/3/0:t
If the affiliate MAYAName has subaffiliates set, the affiliate fee is split proportionally according to the affiliate share basis points assigned to each subaffiliate. See the MAYAName Guide.
Other examples:
=:r:thor1el4ufmhll3yw7zxzszvfakrk66j7fx0tvcslym:19779138111
- swap to at least 197.79 RUNE=:BNB/BUSD-BD1:thor15s4apx9ap7lazpsct42nmvf0t6am4r3w0r64f2:628197586176 -
Swap to at least 6281.9 Synthetic BUSD.=:BNB.BNB:bnb108n64knfm38f0mm23nkreqqmpc7rpcw89sqqw5:544e6/2/6
- swap to at least 5.4 BNB, using streaming swaps, six swaps, every two blocks.
Custom Refund Address
By default, in the case of a refund the protocol will return the inbound swap to the original sender. However, in the case of protocol <> protocol interactions, many times the original sender is a smart contract, and not the user's EOA. In these cases, a custom refund address can be defined in the memo, which will ensure the user will receive the refund and not the smart contract.
Multiple Affiliates
Interfaces can define up to 5 valid affiliate (allowing both MAYANames and MAYA addresses) and affiliate basis points pairs in a swap memo and the network will attempt to skim an affiliate fee for each. Affiliates and affiliate basis points are separated by "/", eg. :t1/t2/t3:10/20/15
. Alternatively, up to 5 valid affiliates with exactly one specified basis point value can be defined, in which case the network will apply the same basis points fee to each affiliate MAYA address. For affiliate MAYANames, the default basis points set in the MAYAName configuration will be used. For example, in the following affiliate section of the memo:
:tmaya13wrmhnh2qe98rjse30pl7u6jxszjjwl4fd6gwn/tmaya1uuds8pd92qnnq0udw0rpg0szpgcslc9p8gps0z/t3:10
the 10 basis points will apply to both addresses, while the affiliate MAYAName will use the default affiliate basis points specified in its configuration. Subaffiliates
All MAYANames used in the memo as affiliates can have nested subaffiliate MAYANames defined (each child MAYAName can have its own nested child MAYANames; the depth of nesting is unlimited). The affiliate fee assigned to the root affiliate MAYAName is further split among these nested subaffiliates MAYANames. Details on how to define the hierarchy of nested subaffiliates MAYANames can be found in the MAYAName Guide
Calculating Affiliate Fee Shares
Details on how affiliate fee shares are calculated in case of hierarchy of nested subaffiliates MAYANames can be found in the MAYAName Guide (Calculating Affiliate Fee Shares section)
Multiple affiliate examples:
=:r:thor1el4ufmhll3yw7zxzszvfakrk66j7fx0tvcslym::t1/t2/t3
- swap RUNE using three affiliates, with affiliate fees calculated based on the default affiliate basis points specified in each affiliate MAYAName configuration=:r:thor1el4ufmhll3yw7zxzszvfakrk66j7fx0tvcslym::t1/t2/t3:10/20/30
- swap using three affiliates, with affiliate fee basis points overridden by the points specified in memo=:r:thor1el4ufmhll3yw7zxzszvfakrk66j7fx0tvcslym::t1/t2/t3:/20/
- swap using three affiliates, with affiliate fees calculated based on the default affiliate basis points specified in thet1
andt3
affiliate MAYAName configurations, and with the affiliate fee basis points fort2
overridden by the points specified in the memo (20 bps)=:r:thor1el4ufmhll3yw7zxzszvfakrk66j7fx0tvcslym::t1/t2/t3:20
- swap using three affiliates, with affiliate fees calculated based on the default affiliate basis points specified in thet2
andt3
affiliate MAYAName configurations, and with the affiliate fee basis points fort1
overridden by the points specified in the memo (20 bps)=:r:thor1el4ufmhll3yw7zxzszvfakrk66j7fx0tvcslym::t1/tmaya13wrmhnh2qe98rjse30pl7u6jxszjjwl4fd6gwn/t2:20
- swap using three affiliates, with affiliate fees calculated based on the default affiliate basis points specified in thet1
andt2
affiliate MAYAName configurations, and with the affiliate fee basis points specified in the memo (20 bps) fortmaya13wrmhnh2qe98rjse30pl7u6jxszjjwl4fd6gwn
address=:r:thor1el4ufmhll3yw7zxzszvfakrk66j7fx0tvcslym::t1/tmaya13wrmhnh2qe98rjse30pl7u6jxszjjwl4fd6gwn/t2:20/20/
- swap using three affiliates, with the affiliate fee basis points fort1
overridden by the points specified in the memo (20 bps), with the affiliate fee basis points specified in the memo (20 bps) fortmaya13wrmhnh2qe98rjse30pl7u6jxszjjwl4fd6gwn
address, and with affiliate fees calculated based on the default affiliate basis points specified in thet2
affiliate MAYAName configurations
Invalid affiliate memo examples:
=:r:thor1el4ufmhll3yw7zxzszvfakrk66j7fx0tvcslym::t1/tmaya13wrmhnh2qe98rjse30pl7u6jxszjjwl4fd6gwn
- affiliate basis points for explicit affiliate address must be provided=:r:thor1el4ufmhll3yw7zxzszvfakrk66j7fx0tvcslym::t1/t2/t3:10/20
- the number of affiliate names and affiliate basis points must be equal (except when only one value of affiliate basis points is provided)
Deposit Savers
ADD:POOL::AFFILIATE:FEE
Depositing savers can work without a memo; however, memos are recommended to be explicit about the transaction intent.
Examples
+:BTC/BTC
add to the BTC Savings Vaulta:ETH/ETH
add to the ETH Savings Vault+:BTC/BTC::t:10
Deposit with a 10 basis points affiliate
Withdraw Savers
WITHDRAW:POOL
Examples
-:BTC/BTC:10000
Withdraw 100% from BTC Saversw:ETH/ETH:5000
Withdraw 50% from ETH Savers
Add Liquidity
There are rules for adding liquidity, see the rules here.
ADD:POOL:PAIREDADDR:AFFILIATE:FEE
Examples:
ADD:POOL
single-sided add liquidity. If this is a position's first add, liquidity can only be withdrawn to the same address.+:POOL:PAIREDADDR
add on both sides.+:POOL:PAIREDADDR:AFFILIATE:FEE
add with affiliate+:BTC.BTC:
Withdraw Liquidity
Withdraw liquidity from a pool. A withdrawal can be either dual-sided (withdrawn based on pool's price) or entirely single-sided (converted to one side and sent out).
WD:POOL:BASISPOINTS:ASSET
Examples:
WITHDRAW:POOL:10000
dual-sided 100% withdraw liquidity. If a single-address position, this withdraws single-sidedly instead.-:POOL:1000
dual-sided 10% withdraw liquidity.wd:POOL:5000:ASSET
withdraw 50% liquidity as the asset specified while the rest stays in the pool, eg:wd:BTC.BTC:5000:BTC.BTC
DONATE & RESERVE
Donate to a pool or the RESERVE.
DONATE:POOL
Example: DONATE:ETH.ETH
- Donate to the ETH pool.
RESERVE
BOND, UNBOND & LEAVE
Perform node maintenance features. Also see Pooled Nodes.
BOND:ASSET:UNITS:NODEADDR:PROVIDER:FEE
UNBOND:NODEADDR:AMOUNT
LEAVE:NODEADDR
Examples:
BOND:thor19m4kqulyqvya339jfja84h6qp8tkjgxuxa4n4aUNBOND:thor1x2whgc2nt665y0kc44uywhynazvp0l8tp0vtu6:750000000000LEAVE:thor1hlhdm0ngr2j4lt8tt8wuvqxz6aus58j57nxnps
MIRGRATE
Internal memo type used to mark migration transactions between a retiring vault and a new Asgard vault during churn. Special MAYAChain triggered outbound tx without a related inbound tx.
:MIGRATE
Example (LINK): MIGRATE:3494355
NOOP
Dev-centric functions to fix MAYAChain state. Caution: may cause loss of funds if not done exactly right at the right time.
NOOP
Refunds
The following are the conditions for refunds:
Refunds cost fees to prevent Denial of Service attacks. The user will pay the correct outbound fee for that chain.
Other Internal Memos
donate
- add funds to a pool (example:DONATE:ETH.ETH
)consolidate
- consolidate UTXO transactionsragnarok
- only used to delist pools.
Last updated