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 can also be created using newfioacc action, which takes FIO Public Key and creates an account for it. It is equivalent to newaccount is not a supported action.

The following actions automatically create an account:

ContractActionEndpointDescription
fio.tokentrnsfiopubky/transfer_tokens_pub_keyWhen transferring tokens to a public key, for which an account has not yet been created.
fio.tokentrnsloctoks/transfer_locked_tokensWhen transferring locked tokens to a public key, for which an account has not yet been created.
fio.addressregaddress/register_fio_addressWhen registering a FIO Crypto Handle for a public key, for which an account has not yet been created.
fio.addressregdomain/register_fio_domainWhen registering a FIO Domain for a public key, for which an account has not yet been created.
fio.addressxferaddress/transfer_fio_addressWhen transferring a FIO Crypto Handle to a public key, for which an account has not yet been created.
fio.addressxferdomain/transfer_fio_domainWhen 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.

Additional Information

Permissions

General 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

  • “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) 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 Handle is created, the FIO Public Key which hashes to the account which will own the FIO Handle 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 Handle will always go to the owner account. The mapped FIO Public Key is also initially set as the default public key used to encrypt and decrypt FIO Request and FIO Data.

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 Crypto Handles 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 and the FIO Request and FIO Data encrypt key. It is important to understand that anyone with the compromised private key will still be able to decrypt content of past FIO Request and FIO Data transaction.

Custom permission example

FIO-specific Permissions

FIP-40 has introduced FIO-specific Permissions, which allow one account to execute specific FIO actions, based on permission granted by another account. Unlike General Permissions, with FIO-specific Permissions the account which executes the action acts as their own account and therefore pays all on-chain fees associated with the transaction.

Example

An example, and the only FIO-specific permission currently supported, is registering FIO Handle on private FIO Domain. Historically, this action was only allowed by the account which owned the domain. If General Permissions are used to grant another account the ability to register handles on that domain, the owner account still pays the on-chain fee for that transaction, since when executed the transaction is executed on behalf of the owner account.

Supported Permissions

Permission NameObjectDescription
register_address_on_domaindomain nameThis permission, when granted by the domain owner (grantor), will allow the account receiving the permission (grantee) to register FIO Handles on specific FIO Domain (object), which may be private.

Terminology

  • grantor - account which grants the permission. In the above example, it is the domain owner.
  • grantee - account which is granted the permission. In the above example, it is the account which will be registering the domain.
  • object_name - in case of the FIO Handle Registration permission, this is the domain name.

Adding FIO-specific Permission

To add FIO-specific Permission, use addperm action.

Remove FIO-specific Permission

To remove, or revoke, FIO-specific Permission, use remperm action.

Fetch permissions

Additional Information