Features

FT4 supports the following features:

• Account management
• Asset management and transaction history

Account management

The central entity of the FT4 module is the account. An account is uniquely identified by an id:

entity account {
  key id: byte_array;
  index type: text;
}

Multiple users can control an account with different levels of access rights. The authentication descriptors, or auth descriptors, define who can control an account and what they can do with it:

entity account_auth_descriptor {
   id: byte_array;
   key account, id;
   index id;
   auth_type;
   args: byte_array;
   rules: byte_array;
   mutable ctr: integer;
   created: timestamp;
}

Auth descriptors and access control

In FT4, accounts can be accessed using multiple key pairs, enabling various possibilities. Auth descriptors determine who can access an account and specify their access level.

As auth descriptors are stored on the chain and hold a certain amount of data, users could store infinite data on the chain, impacting performance. For this reason, a limit must be set to the number of auth descriptors an account can hold.

By default, this limit is set to 10. You can configure the value like this:

blockchains:
  my_rell_dapp:
    module: main
    moduleArgs:
      lib.ft4.core.accounts:
        auth_descriptor:
          max_number_per_account: 4

The upper bound for this value is 200. Setting it to a higher number will default back to 200.

There are two types of auth descriptors: single-signature and multi-signature.

• Single-signature auth descriptor: This auth descriptor specifies only one signer, typically identified by a public key when using native postchain signatures or an EVM account address when using EVM signatures.

• Multi-signature auth descriptor: This descriptor involves two or more signers, with the number of required signatures specified. Similarly, signers are identified by public keys or EVM account addresses. Currently, multi-sig signatures are only supported for native postchain signatures.

Auth flags and operation authorization

Auth flags define what actions an auth descriptor is authorized to perform on an account. When authenticating users for operations, the necessary auth flags must be specified; otherwise, the transaction are rejected.

FT4 defines the following built-in auth flags:

• T (Transfer) flag: This flag is required for transfer operations. If an auth descriptor lacks this flag, transfer operations are rejected.

• A (Account) flag: This flag is required for FT4 account operations, such as adding or deleting auth descriptors.

In addition to the built-in auth flags, Dapps can define custom auth flags to support their specific authorization requirements. This can be done by specifying any string as an argument when creating the auth descriptor. Flags need not only be a single letter, but keeping them short is recommended for performance reasons.

Expiration rules for auth descriptors

Auth descriptors can have expiration rules defined, determining their validity over time. The following expiration rules are supported:

• Block height: An auth descriptor can be set to expire after a certain block height.

• Block time: An auth descriptor can be set to expire after a specific block time.

• Number of authorizations: An auth descriptor can be set to expire after being used a certain number of times to authorize a user.

It's important to note that auth descriptors added during account creation cannot have expiration rules set. This prevents users from accidentally losing access to their accounts.

You can configure the maximum allowed number of rules for an auth descriptor like this (default value is 8):

blockchains:
  my_rell_dapp:
    module: main
    moduleArgs:
      lib.ft4.core.accounts:
        max_auth_descriptor_rules: 4

One may want to limit the number of rules for performance reasons. All rules need to be checked when using the auth descriptor, increasing the work needed to evaluate them each time the user performs an authorization.

Asset management

FT4 provides support for multiple assets. The asset table contains a list of registered assets:

entity asset {
   key id: byte_array;
   name;
   key symbol: text;
   decimals: integer;
   issuing_blockchain_rid: byte_array;
   icon_url: text;
   type: text = ASSET_TYPE_FT4;
   mutable total_supply: big_integer;
}

The balance table keeps track of an account's assets:

entity balance {
  key accounts.account, asset;
  mutable amount: big_integer;
}