THORName Guide

Summary

THORNames are THORChain's vanity address system that allows affiliates to collect fees and track their user's transactions. THORNames exist on the THORChain L1, so you will need a THORChain address and $RUNE to create and manage a THORName.;

THORNames have the following properties:

• Name: The THORName's string. Between 1-30 hexadecimal characters and -_+ special characters.;
• Owner: This is the THORChain address that owns the THORName
• Aliases: THORNames can have an alias address for any external chain supported by THORChain, and can have an alias for the THORChain L1 that is different than the owner.
• Expiry: THORChain Block-height at which the THORName expires.
• Preferred Asset: The asset to pay out affiliate fees in. This can be any asset supported by THORChain.;

Create a THORName

THORNames are created by posting a MsgDeposit to the THORChain network with the appropriate memo and enough $RUNE to cover the registration fee and to pay for the amount of blocks the THORName should be registered for.;

• Registration fee: tns_register_fee_rune on the Network endpoint. This value is in 1e8, so 100000000 = 1 $RUNE
• Per block fee: tns_fee_per_block_rune on the same endpoint, also in 1e8.;

For example, for a new THORName to be registered for 10 years the amount paid would be:

amt = tns_register_fee_rune + tns_fee_per_block_rune * 10 * 5256000

5256000 = avg # of blocks per year

The expiration of the THORName will automatically be set to the number of blocks in the future that was paid for minus the registration fee.

Memo Format:

Memo template is: ~:name:chain:address:?owner:?preferredAsset:?expiry

• name: Your THORName. Must be unique, between 1-30 characters, hexadecimal and -_+ special characters.;
• chain: The chain of the alias to set.;
• address: The alias address. Must be an address of chain.
• owner: THORChain address of owner (optional).
• preferredAsset: Asset to receive fees in. Must be supported be an active pool on THORChain. Value should be asset property from the Pools endpoint.;

This will register a new THORName called ODIN with a Bitcoin alias of bc1Address owner of thorAddress and preferred asset of BTC.BTC.

Renewing your THORName

All THORName's have a expiration represented by a THORChain block-height. Once the expiration block-height has passed, another THORChain address can claim the THORName and any associated balance in the Affiliate Fee Collector Module (Read #preferred-asset-for-affiliate-fees), so it's important to monitor this and renew your THORName as needed.;

To keep your THORName registered you can extend the registration period (move back the expiration block height), by posting a MsgDeposit with the correct THORName memo and $RUNE amount.;

Memo:

~:ODIN:THOR:<thor-alias-address>

(Chain and alias address are required, so just use current values to keep alias unchanged).

$RUNE Amount:

rune_amt = num_blocks_to_extend * tns_fee_per_block

(Remember this value will be in 1e8, so adjust accordingly for your transaction).

Preferred Asset for Affiliate Fees

Starting in THORNode V116, affiliates can collect their fees in the asset of their choice (choosing from the assets that have a pool on THORChain). In order to collect fees in a preferred asset, affiliates must use a THORName in their swap memos.;

How it Works

If an affiliate's THORName has the proper preferred asset configuration set, the network will begin collecting their affiliate fees in $RUNE in the AffiliateCollector module. Once the accrued RUNE in the module is greater than PreferredAssetOutboundFeeMultiplier* outbound_fee of the preferred asset's chain, the network initiates a swap from $RUNE -> Preferred Asset on behalf of the affiliate. At the time of writing, PreferredAssetOutboundFeeMultiplier is set to 100, so the preferred asset swap happens when the outbound fee is 1% of the accrued $RUNE.;

Configuring a Preferred Asset for a THORName:

1. Register your THORName following instructions above.
2. Set your preferred asset's chain alias (the address you'll be paid out to), and your preferred asset. Note: your preferred asset must be currently supported by THORChain.

For example, if you wanted to be paid out in USDC you would:

1. Grab the full USDC name from the Pools endpoint: ETH.USDC-0XA0B86991C6218B36C1D19D4A2E9EB0CE3606EB48

2. Post a MsgDeposit to the THORChain network with the appropriate memo to register your THORName, set your preferred asset as USDC, and set your Ethereum network address alias. Assuming the following info:

   1. THORChain address: thor1dl7un46w7l7f3ewrnrm6nq58nerjtp0dradjtd
   2. THORName: ac-test
   3. ETH payout address: 0x6621d872f17109d6601c49edba526ebcfd332d5d;

   The full memo would look like:

   ~:ac-test:ETH:0x6621d872f17109d6601c49edba526ebcfd332d5d:thor1dl7un46w7l7f3ewrnrm6nq58nerjtp0dradjtd:ETH.USDC-0XA0B86991C6218B36C1D19D4A2E9EB0CE3606EB48

Once you successfully post your MsgDeposit you can verify that your THORName is configured properly. View your THORName info from THORNode at the following endpoint:
https://thornode.ninerealms.com/thorchain/thorname/ac-test

The response should look like:

{
  "affiliate_collector_rune": "0",
  "aliases": [
    {
      "address": "0x6621d872f17109d6601c49edba526ebcfd332d5d",
      "chain": "ETH"
    },
    {
      "address": "thor1dl7un46w7l7f3ewrnrm6nq58nerjtp0dradjtd",
      "chain": "THOR"
    }
  ],
  "expire_block_height": 22061405,
  "name": "ac-test",
  "owner": "thor1dl7un46w7l7f3ewrnrm6nq58nerjtp0dradjtd",
  "preferred_asset": "ETH.USDC-0XA0B86991C6218B36C1D19D4A2E9EB0CE3606EB48"
}

Your THORName is now properly configured and any affiliate fees will begin accruing in the AffiliateCollector module. You can verify that fees are being collected by checking the affiliate_collector_rune value of the above endpoint.