Overview

One of the key utilities of the FIO Protocol is the ability to send crypto using a FIO Handle, instead of complicated Native Blockchain Public Address (NBPA) such as 0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B on Ethereum.

A wallet can very easily look-up the NBPA using the /get_pub_address method. However, before this can happen the wallet hosting the FIO Handle must first map the NBPA to the FIO Handle.

Native Integration

For wallets desiring full control over the registration user experience, the best strategy is to execute mapping actions directly to the FIO Chain.

Mapping Options

Applications that enable users to manage their private keys (such as crypto wallets) which integrate the FIO Protocol have two options on enabling mapping of associated public addresses to the human readable FIO Handle.

Map Automatically

The application may automatically map all supported NBPAs to the FIO Handle.

Let User Decide

The application may enable users to select which NBPA to map to the FIO Handle through a radio button or similar interface.

Mapping Action

To map NBPA to a FIO Handle use the addaddress action.

You may pass up to 5 NBPAs in a single call. The action can be executed using gas-free bundled transactions, so in most cases there will not be a fee to the user.

Each NBPA is identified with:

• chain_code identifies the blockchain, such as Bitcoin (BTC), or Ethereum (ETH).
• token_code identifies the token on that blockchain or * for all tokens on that blockchain. For example USDC represents ERC20 token on Ethereum.

FIO maintains a list of chain and token codes that are being used by other FIO Protocol integrators. It is recommended that you follow this standard any time you submit a transaction on the FIO Protocol. If you are using different codes please map them to those published.

If you are using codes which are not yet part of the standard, please submit a pull request to the list to ensure other FIO Protocol integrators are using the same codes.

📘

Mapping chains vs tokens!

While FIO Protocol allows for the FIO Handle to be mapped to specific tokens, most users expect their handle to be mapped at the chain level, in other words they will use the same address for all tokens on that chain.

For that reason, in most applications, you should set token_code to *

Chain-level Public Addresses

By specifying * for the token_code you can map all tokens for that chain to the same address. For example, you may want to map all of your ETH tokens to the same public address:

{
 "fio_address": "purse@alice",
 "public_addresses": [
   {
     "chain_code": "BTC",
     "token_code": "BTC",
     "public_address": "1PMycacnJaSqwwJqjawXBErnLsZ7RkXUAs"
   },
   {
     "chain_code": "ETH",
     "token_code": "*",
     "public_address": "0xab5801a7d398351b8be11c439e05c5b3259aec9b"
   }
 ],
 "max_fee": 0,
 "tpid": "rewards@wallet",
 "actor": "aftyershcu22"
}

In this case, a user doing a /get_pub_address lookup for the ETH USDC (or any ETH token) address for purse@alice would get the 0xab5801a7d398351b8be11c439e05c5b3259aec9b public address returned.

It is also possible to map both a * and a specific token_code to a single chain_code. For example:

{
"fio_address": "purse@alice",
"public_addresses": [
  {
    "chain_code": "ETH",
    "token_code": "USDC",
    "public_address": "0xa635801a7d398351b8bb945439e05c5b3259b4d2"
  },
  {
    "chain_code": "ETH",
    "token_code": "*",
    "public_address": "0xab5801a7d398351b8be11c439e05c5b3259aec9b"
  }
],
"max_fee": 0,
"tpid": "rewards@wallet",
"actor": "aftyershcu22"
}

In this case, a user doing a /get_pub_address lookup for ETH USDC would get the first public_address returned. For any other ETH token, the second address would be returned.

See FIP-18 for a more detailed description of chain-level public address functionality.

Multi-level Addressing

Certain blockchains, or accounts on those blockchains, require the use of Multi-level Addressing, when, in addition to public address, additional piece of information is required to properly route a transaction.

The following are examples:

• Destination Tags on Ripple
• Memos on Stellar
• Payment ID on Monero

There is not a clear standard on how to properly communicate these additional properties. The FIO Protocol supports both integrated addresses as well as URI Scheme as follows:

• Integrated Address - an integrated address may be passed in just like standard public address. The FIO Protocol does not perform validation on the passed string.
• URI Scheme - the FIO Protocol supports the formatting of public addresses using URI Schemes, where certain attributes are appended to the public address following a ‘?’ and delimited with ‘&’. The additional parameters are returned via URI parameters like this:

  public_address?parameter1=value1&parameter2=value2
  

FIO maintains a list of multi-level parameters that are being used by other FIO Protocol integrators. It is recommended that you follow this standard any time you submit a transaction on the FIO Protocol. If you are using different parameters please map them to those published.

If you are using codes which are not yet part of the standard, please submit a pull request to the list to ensure other FIO Protocol integrators are using the same parameters.

FIO Public Key Mapping

The FIO Public key which was used to register FIO Handle is automatically added to that address’ mapping for chain_code: FIO, token_code: FIO.

🚧

Update Encrypt Key

If your application lets the user update a FIO Public Key which is mapped to their FIO Handle using addaddress action, it is recommended that you update the encrypt key to the public key which corresponds to the private key which secures the account. If you fail to properly set the encrypt key, your application may not be able to properly encrypt/decrypt FIO Request and FIO Data.

Example:

• User's default private key is SK1 which maps to PK1
• User registers FIO Handle FH1
• PK1 is automatically mapped to FH1 for FIO Tokens
• Since encrypt key is not set by default the /get_encrypt_key will return PK1 and it will be used for encryption
• User now maps PK2 to FH1 for FIO Tokens
• Since encrypt key is still not set the /get_encrypt_key will now return PK2 and it will be used for encryption. If your application has access to corresponding SK2, that is fine. However, if you do not and you would like to continue to use SK1 for encryption/decryption, you must update the encrypt key to PK1 using updcryptkey action. /get_encrypt_key will now return PK1, while /get_pub_address for FIO Tokens will return PK2.

For additional information see Encryption in FIO Request and FIO Data.

Mapping FIO Handles to bank accounts

FIO Handle can also be mapped to bank account information required to route fiat transactions. For this purpose chain_code: FIAT should be used and token_code should correspond to the banking standard used.

For example to map FIO Crypto Handle to a ACH bank account:

{
	"chain_code": "FIAT",
	"token_code": "ACH",
	"public_address": "{'aba':'102000076','acc':'1234567890'}"
}

To map FIO Crypto Handle to an IBAN bank account:

{
	"chain_code": "FIAT",
	"token_code": "IBAN",
	"public_address": "{'iban':'DE89370400440532013000'}"
}

Mapping FIO Handles to social media accounts

FIO Handle can also be mapped to social media accounts. For this purpose chain_code: SOCIAL should be used and token_code should correspond to the specific social media site, as published in the Chain and token code standard. The public_address should be the user's social media handle on that specific site.

For example to map FIO Crypto Handle to users's Twitter account:

{
	"chain_code": "SOCIALS",
	"token_code": "TWITTER",
	"public_address": "username"
}

Getters

Integrating these actions do not require the integrator to have access to user's FIO Private Key.

Available FIO Handle Mapping Getters

Write Transactions

Integrating these actions require the integrator to have access to user's Private key and properly serialize and sign each transaction. For additional information, see Write Transaction.

Available FIO Handle Mapping Actions

UX/UI Considerations

• When resolving a FIO Handle, expect that the returned public address will contain URI parameters.
• Most common is memo. If you receive a memo, insert it into the memo (or equivalent) parameter for the native transaction on that blockchain.
• If you receive any of the other parameters above, insert it into corresponding parameter for the native transaction on that blockchain.
• If you do not support ability to accept returned parameters, consider warning the user that the FIO Handle they used contains information which will not be used.
• Note: The application should direct users to mapping their tokens after registering a FIO Handle (or unmapping if the platform maps all tokens automatically).

Quality Assurance Checklist

The following lists the items that should be tested to confirm support for FIO Mapping of blockchain addresses:

• User is able to connect their FIO Crypto Handle to their crypto/tokens.
• User is able to disconnect their FIO Crypto Handle.
• Disconnecting the main FIO wallet is disabled.

Link to FIO App

Alternatively to Native Integration, the application may link the user to to the FIO App, a comprehensive website to register and manage FIO Handles and many other functionality related to FIO Protocol.

For additional information, see FIO App.

Privacy

Currently NBPA mappings are stored on the FIO Chain unencrypted. It is therefore possible for an observer to connect multiple NBPAs via their parent FIO Handle.

It is therefore important that integrating wallets clearly communicate this to their users, so that they can make an educated decision on which NBPAs to map. In addition users should understand that due to the nature of blockchain once NBPA has been published on the blockchain it will be accessible indefinitely, even if it is later “removed” from current mappings.