Accounts and permissions

FIO Accounts

FIO Chain inherits EOSIO Accounts and Permission scheme. However, a number of modifications were made with the goal of making the interaction with the FIO Chain more seamless to the users.

Specifically, it was deemed that an explicit step to create and pay for an account before one can interact with the FIO Chain was intrusive and that a better approach would be to allow a user to simply generate a public key and have the account created automatically on first interaction.

To achieve this objective on FIO Chain:

  • Account is created automatically when certain actions are triggered with a supplied public key for which an account has not yet been created. This allows the user to generate a FIO Public Key off-chain and provide that as a valid public address akin to UTXO chains.
  • When an account is created:
    • Its name is set to the hash of the supplied public key using custom hash function.
    • Its owner and active permissions are set to the supplied public key.
    • The supplied public key is permanently stored in fio.address->accountmap table and can be queried to lookup the original FIO Public Key, even if permissions were modified.
  • The account cannot be explicitly created with a custom name to avoid collisions with a hashed public key. newaccount is not a supported action.

The following actions automatically create an account:

Contract Action Endpoint Description
fio.token trnsfiopubky /transfer_tokens_pub_key When transferring tokens to a public key, for which an account has not yet been created.
fio.token trnsloctoks /transfer_locked_tokens When transferring locked tokens to a public key, for which an account has not yet been created.
fio.address regaddress /register_fio_address When registering a FIO Address for a public key, for which an account has not yet been created.
fio.address regdomain /register_fio_domain When registering a FIO Domain for a public key, for which an account has not yet been created.
fio.address xferaddress /transfer_fio_address When transferring a FIO Address to a public key, for which an account has not yet been created.
fio.address xferdomain /transfer_fio_domain When transferring a FIO Domain to a public key, for which an account has not yet been created.

The fees for the above actions reflect the potential of increased resource usage associated with account creation.

More information about FIO Public Keys

Permissions

When a FIO Account is created, the corresponding FIO Public Key is assigned as the owner and active permission. The implicit default permission linked to all actions is active, which sits one level below the owner permission within the hierarchy structure. The active permission can do anything the owner permission can, except changing the keys associated with the owner.

As FIO Chain inherits EOSIO Permission scheme, permissions in FIO Chain can be modified. However, please consider the following.

Limitations

  • Only one public key can be specified for a single permission, e.g. active cannot have 2 public keys. It can however, have multiple accounts, which may be helpful for setting up a multisig.
  • “waits” are not supported.

Implications

  • Custom permissions are not currently supported by the SDKs. This means that if an account’s default permissions are changed and the user imports their private key to a wallet which supports FIO using the SDK, that account may not work correctly on that wallet as it would not be able to properly sign transactions. This does not mean you should not allow for custom permissions in your application, it means you should consider disclosing portability of the account to your users.
  • Many actions (e.g. trnsfiopubky, regaddress) and getters (e.g. /get_fio_balance, /get_fio_addresses) accept FIO Public Key as an input parameter. It is important to understand that the supplied FIO Public Key will always be converted to the default hashed account and the action or getter will be executed against that account even if the permissions on it have been modified.
  • When a FIO Address is created, the FIO Public Key which hashes to the account which will own the FIO Address is automatically mapped to it. This occurs irrespective of the permissions which are set on the account. This ensures that funds sent to the FIO Address will always go to the owner account. The mapped FIO Public Key is also used to encrypt and decrypt FIO Request and FIO Data.

Custom permission example

Refer to the linkauth code example which shows how to create a custom permission that can be used to register a FIO Address on a private FIO Domain.

Compromised private key use case

If a user’s private key is compromised, the cleanest way to handle it would be to transfer all tokens, FIO Addresses and FIO Domains to a new account, i.e. FIO Public Key. However, this may not always be possible (e.g. account has locked tokens) or desirable. An alternative could be to replace the owner/active permissions. This is possible in FIO Chain, provided the implications above. However, the following should also be considered.

If the account owns any FIO Addresses, those, by default, are mapped to the FIO Public Key which maps to the hashed account. This is not an issue for sending tokens, as they will arrive in the account now protected by new permissions. However, that FIO Public Key and corresponding private key are also used to encrypt and decrypt FIO Request and FIO Data. Therefore, anyone with the private key can decrypt the content. The mapped FIO Public Key can be swapped separately from permissions, but this will:

  • Result in funds sent to the FIO Address being sent to the account which hashes from the new key.
  • The wallet would have to keep the compromised private key around to decrypt old content.

A modification to the FIO Chain has been proposed to have separate FIO keys for receiving tokens and encrypting/decrypting content.