Docs
chromia.com

Register FT4 accounts

On this page

In the FT4 library, accounts function as digital identities, enabling users to transfer assets, interact with dapps, and sign transactions. Account registration allows the system to securely identify and authenticate users, supporting access control mechanisms that let users or administrators define permissions for actions an account can perform. This approach is crucial for maintaining security, preventing unauthorized access, and ensuring that resources such as assets or data remain accessible only to the rightful owner.

FT4 account registration flowClient (your app)Your chain (Rell + FT4)Key or walletFT key · EVM wallet1Pay (transfer strategies)transfer to address2RegisterregisterAccount()3Log indisposable keylogin()5Pending depositheld until claimedregister_accountstrategy checks rules4Accountmain descriptor ["A","T"]session
Registering an FT4 account. With the open strategy, skip step 2. With a transfer strategy (open, fee or subscription), the user first sends tokens to their future account address, and register_account claims them.

Account registration framework

For most dapps, the account registration framework provided by the FT4 library is the recommended approach. This framework offers a flexible, secure, and scalable system for creating new accounts, supporting various strategies tailored to different business models and security requirements. The framework simplifies the developer experience, offering pre-built solutions for common registration scenarios.

Registration strategies

The account registration framework supports several strategies:

  • Open: Anyone can call the register_account() operation to create an account without restrictions.
  • Transfer strategy: Users must perform a transfer to the account address before creating an account. The transfer strategy includes three sub-strategies:
    • Transfer open: Users can claim the entire deposit to their newly created account.
    • Transfer fee: Part of the transferred assets is collected as a fee to the chain's fee account, allowing users to claim only the remaining assets.
    • Transfer subscription: Similar to the transfer fee strategy, but users need to periodically renew their subscription by paying the subscription fee to maintain account access.

To enable a specific strategy, import the corresponding module into the Rell file and configure it in the chromia.yml file. The modules are named as follows:

  • lib.ft4.core.accounts.strategies.open (open strategy - not a transfer strategy)
  • lib.ft4.core.accounts.strategies.transfer.open (transfer open strategy)
  • lib.ft4.core.accounts.strategies.transfer.fee (transfer fee strategy)
  • lib.ft4.core.accounts.strategies.transfer.subscription (transfer subscription strategy)

Strategy comparison

AspectOpenTransfer openTransfer feeTransfer subscription
Fee requiredNoNo (but tokens must be transferred)Yes (one-time)Yes (recurring)
Production useNot recommended (dev/test only)Safe with proper safeguardsRecommendedRecommended
Revenue modelNoneNo direct revenueOne-time paymentsRecurring payments
User experienceDirect account creation (no transfer)Requires token transferSimple one-time paymentRegular payments required
ComplexityVery lowLowMediumHigh

Transfer strategy

To use any of the transfer strategies, certain moduleArgs must first be configured in the chromia.yml file under the key:

YAML
blockchains:
  my_dapp_chain:
    module: my_dapp_module
    moduleArgs:
      lib.ft4.core.accounts.strategies.transfer:

Under this key, settings must be specified, including which chains are permitted to make transfers to the chain and which assets are accepted. Configuring these parameters helps prevent potential DOS attacks and spam from untrusted chains. Here is an example configuration:

YAML
blockchains:
  my_dapp_chain:
    module: my_dapp_module
    moduleArgs:
      lib.ft4.core.accounts.strategies.transfer:
        rules:
          - sender_blockchain: # List of blockchain rids from which we will accept transfers
              - x"08B02E0E14B634031FDF2ED3FD78E7410A5849CD28"
            sender: * # Anyone on the specified blockchain can send us assets
            recipient: * # They can send assets to anyone on this chain
            asset: # List of assets that can be sent from this chain
              - name: CHR # Name of the asset (id can also be used instead)
                min_amount: 5L # If transfer is of less than this value, then the transfer will be rejected
            timeout_days: 30 # After this many days, the sender is allowed to recall the transfer if it hasn't been claimed
            strategy: # List of transfer strategies to enable
              - "fee"
              - "open"

In this example, every user on a specified Chromia blockchain is allowed to send a minimum of 0.000005 CHR to any user on the receiving blockchain. If the transfer recipient does not have an existing account, they can create one using either the open or fee strategy. This configuration enables granular control over which blockchains can send assets and create accounts.

Transfer strategy configuration values

The transfer strategy uses special values to define flexible rules:

  • $ (Current Chain): Represents the current blockchain's BRID. Can be used in sender_blockchain, issuing_blockchain_rid for assets.
  • * (Any Value): Represents any allowed value. Can be used in sender_blockchain, sender, recipient, and asset fields.
  • X (Same Value): Requires the sender and recipient to be the same account. Can only be used in sender and recipient fields together.

Example configurations

Allow transfers from any chain:

YAML
sender_blockchain:
  - "*"

Allow transfers only from current chain:

YAML
sender_blockchain:
  - "$"

Allow transfers from specific chains:

YAML
sender_blockchain:
  - x"08B02E0E14B634031FDF2ED3FD78E7410A5849CD28"
  - x"6403ccac0c67f7cb6af78e5e15b3aaebb2b42370f0d12e099ed01fa5a068f9fb"

Allow self-transfers only:

YAML
sender: "X"
recipient: "X"

If only the open strategy is enabled, additional configurations are not required. However, the open strategy may not provide optimal spam protection, as it could allow the creation of numerous accounts with minimal assets. For enhanced protection, using an alternative strategy, such as the fee strategy, is recommended.

To configure the fee strategy, additional steps are required beyond the initial setup. First, import the strategy in the main module.rell file

Rell
import lib.ft4.accounts.strategies.transfer.fee;

Then, configure the strategy by specifying the valid asset(s) for payments, the fee amount, and the destination for the fee payment. This is done by adding a configuration under the moduleArgs key in the chromia.yml file:

YAML
blockchains:
  my_dapp_chain:
    module: my_dapp_module
    moduleArgs:
      lib.ft4.core.accounts.strategies.transfer.fee:
        asset:
          - id: x"b31ba66a11a28930d948c8f959cc306184096d1ee858542e765a139b3c79b1aa" # We can specify an asset by id
            amount: 2L # How much of this asset to pay
          - name: test1 # we can specify an asset by name, this will refer to an asset issued by this chain
            amount: 1L
          - issuing_blockchain_rid: x"6403ccac0c67f7cb6af78e5e15b3aaebb2b42370f0d12e099ed01fa5a068f9fb" # We can also specify assets issued by a different chain, even if the names are the same
            name: test1
            amount: 3L
        fee_account: x"023c72addb4fdf09af94f0c94d7fe92a386a7e70cf8a1d85916386bb2535c7b1b1" # All fees will be collected into this account

In the configuration above, users can pay the fee using one of three assets, with varying amounts depending on the asset. This flexibility can accommodate value differences between assets or encourage payment with a preferred asset. It is worth mentioning that the asset id cannot be accompanied by the name or issuing chain rid. Additionally, the account for fee collection is specified, which should typically be controlled by the dapp owner.

Configuring foreign assets (cross-chain assets)

For most mainnet dapps, you'll want to use foreign assets like CHR for account registration. Here are the different ways to specify assets:

Local asset (issued by current chain)

YAML
asset:
  - name: "MyLocalAsset" # Asset issued by this chain
    amount: 1L

Foreign asset by ID

YAML
asset:
  - id: x"C633343E4AA3213EA92158648F11BA8DFF606C6CAC80614CFA5F45E57367F823" # Asset ID
    amount: 1L # 10 CHR (6 decimals)
YAML
asset:
  - name: "CHR" # Asset name
    issuing_blockchain_rid: x"15C0CA99BEE60A3B23829968771C50E491BD00D2E3AE448580CD48A8D71E7BBA" # Economy chain RID
    amount: 1L # 10 CHR (6 decimals)

For account registration using a transfer strategy, a transfer must first be made to the account. If the user already holds an account with enough assets, they may initiate the transfer themselves, or a friend might perform it on their behalf, functioning as an invitation system.

Rate limiting

FT4 provides built-in rate limiting to prevent spam and abuse. Rate limiting can be configured globally or per-account to control how frequently users can perform operations.

Global rate limiting configuration

Configure rate limiting in your chromia.yml:

YAML
blockchains:
  <my_blockchain_name>:
    module: my_dapp_module
    moduleArgs:
      lib.ft4.core.accounts:
        rate_limit:
          active: true
          max_points: 20
          recovery_time: 5000 # milliseconds
          points_at_account_creation: 1

Rate limiting parameters

  • active: Enables or disables rate limiting globally
  • max_points: Maximum points allowed before rate limiting is triggered
  • recovery_time: Time in milliseconds for points to recover
  • points_at_account_creation: Points consumed when creating an account

Per-account rate limiting

You can implement custom rate limiting logic by extending the get_rate_limit_config_for_account function:

Rell
@extend(get_rate_limit_config_for_account) function get_rate_limit_config_for_account(account: account): rate_limit_config? {
    // Return custom config for specific accounts
    // Return null to use global default
}

For more details on rate limiting implementation, see the Rell Security documentation.

Register with FT4 admin operation

For scenarios requiring greater control or direct intervention, Chromia offers the FT4 admin operation. This admin-level operation allows authorized administrators to create accounts directly, bypassing the user-driven registration process.

Why use the admin operation?

Admin operations are intended for cases requiring stricter control over account creation, such as when developers or dapp owners need to create accounts for system users, team members, or to initiate specific business processes. Unlike user-led registrations, admin operations can bypass certain checks and constraints, enabling direct management of the blockchain environment.

However, admin operations are not recommended for production environments, as they may introduce security risks if not carefully managed. If an admin operation is necessary, consider building a custom admin module tailored to the specific requirements of the dapp.

Admin vs. non-admin operations

  • Admin operations: These provide broader permissions and access, allowing administrators to perform tasks like account registration, asset management, or system updates. They are powerful but carry higher risks, as improper use can affect the security and stability of the entire system.
  • Non-admin operations: These are designed for end-users or automated processes with more restricted access. They follow strict rules, ensuring that users can only perform actions they are explicitly authorized to carry out (e.g., transferring assets or modifying their own account settings).

Registering an account with FT4 admin

The FT4 admin operation, ft4.admin.register_account, requires an auth descriptor as a parameter. An auth descriptor specifies who can access an account, what actions they can perform, and the lifetime of the auth descriptor. The access to an account is determined by a public key when FT authentication (native Chromia signatures) is used or an EVM account address when an EVM wallet is used for authentication.

The actions allowed by the auth descriptor are specified with authorization keys, and expiration rules determine the activation and validity duration of the auth descriptor. For more details, see the auth descriptor topic.

To create an account using the FT4 admin operation, follow these steps:

  1. Generate a new key pair for the account and retrieve the public key:

    Terminal
    chr keygen --file .chromia/user.keypair | grep pubkey
  2. Register the account using the FT4 admin operation:

    Terminal
    chr tx ft4.admin.register_account \
        '[0, [["A","T"], x"0351D4F299E3D33EC745C9F3C2F74934960F58411BE8BAE52A1E6EC8D0BA26AEDB"], null]' \
        --await --secret .chromia/ft4-admin.keypair

    In this command:

    • 0 represents a single signature auth descriptor.

    • A (account) and T (transfer) are auth flags defined in the FT library.

    • Replace 0351D4F299E3D33EC745C9F3C2F74934960F58411BE8BAE52A1E6EC8D0BA26AEDB with the generated public key for the user.

  3. A query can be added that returns all accounts to verify if the account exists. Add the following query to your code:

    Rell
    query get_all_accounts() = accounts.account @* {} (.id);
  4. Update and wait for the blockchain to reflect the changes:

    Terminal
    chr node update
  5. You can now execute the query to retrieve all accounts:

    Terminal
    chr query get_all_accounts

    The output will display the account ID(s), such as:

    Output
    [x"5E2488889F72939DD4D0A034FB91893ACBF14C7EDBCEF2A9F5C621A07169EAD2"]

Register with a custom operation

If the provided account registration framework or admin operation does not meet specific requirements, a custom operation can be created to handle account registration. Writing a custom operation provides full control over the registration process, enabling customization according to unique requirements and security needs.

When registering an account with a custom operation, protecting the operation against potential spam attacks on the blockchain is essential. In this example, users are required to provide a voucher during registration. This approach involves creating a register and an admin operation to allow vouchers to be added.

  1. Define the voucher entity and the add_voucher operation in your code:

    Rell
    entity voucher {
        hash: byte_array;
        mutable is_used: boolean = false;
    }
    
    operation add_voucher(hash: byte_array) {
        admin.require_admin();
        create voucher(hash);
    }
  2. Define the register_account operation, which includes voucher validation and account creation:

    Rell
    operation register_account(accounts.auth_descriptor, voucher_code: text) {
        // extract pubkey from auth descriptor
        val pubkey = byte_array.from_gtv(auth_descriptor.args[1]);
    
        // check if provided key is signer
        require(op_context.is_signer(pubkey), "Transaction needs to be signed by %s".format(pubkey));
    
        val hash = voucher_code.hash();
        val voucher = require(
            voucher @? { hash },
            "Provided voucher with code <%s> does not exist".format(voucher_code)
        );
        require(
            not voucher.is_used,
            "Provided voucher with code <%s> is already used".format(voucher_code)
        );
        voucher.is_used = true;
        accounts.create_account_with_auth(auth_descriptor);
    }
  3. After adding the code snippets to the appropriate sections in your main.rell file, update the blockchain to apply the changes.

  4. Generate a voucher hash using the chr repl command as follows:

    Terminal
    chr repl -c '"voucher_1".hash()'

    The output will be a hash like:

    Output
    x"E1E72D0C6C975815BD3259D81E67253D98CF90D888B4C7CB393C8CFB9043BAF3"
  5. Add the voucher hash to the blockchain using the admin operation:

    Terminal
    chr tx add_voucher \
      'x"E1E72D0C6C975815BD3259D81E67253D98CF90D888B4C7CB393C8CFB9043BAF3"' \
      --await --secret .chromia/ft4-admin.keypair
  6. Generate a new keypair for the user who'll register the account, and retrieve the public key:

    Terminal
    chr keygen --file .chromia/user-2.keypair | grep pubkey
  7. Register the account using the custom operation register_account:

    Terminal
    chr tx register_account \
      '[0, [["A", "T"], x"03772E03AE22835384164AA90E28C84F78C97D29A2635861DC3F7E32F0CC8FDF51"], null]' \
      voucher_1 \
      --await --secret .chromia/user-2.keypair

    Replace 03772E03AE22835384164AA90E28C84F78C97D29A2635861DC3F7E32F0CC8FDF51 with the generated public key for the user.

  8. To verify the successful account registration, execute the get_all_accounts query again. You should now see two account IDs or one if you didn't follow the first half of the guide:

    Terminal
    chr query get_all_accounts

    The output would include the account IDs:

    Output
    [x"5E2488889F72939DD4D0A034FB91893ACBF14C7EDBCEF2A9F5C621A07169EAD2", x"79C71AF3C9C951BED380F8ADAB2E407C15CC4A9EB942AA222D870136C45801CE"]

Dapp-controlled accounts

Chromia provides support for accounts that are entirely managed by dapp logic. These accounts do not have any associated auth descriptors, meaning they cannot be accessed or modified by external parties.

Dapp-controlled accounts are beneficial for:

  • Creating liquidity pools or treasuries
  • Holding locked funds or protocol fees
  • Implementing automated reward systems

You can find a code example demonstrating how to create a dapp-controlled account in this demo repository.

Transfer open strategy example

This FT4 example demonstrates account registration with the transfer open strategy, which allows registration only when sender and recipient IDs match during cross-chain transfers. The Test asset is registered dynamically on the first chain and via the init operation on the second.

The sender account uses a custom custom_register_account operation to register and mint 100 Test assets. The recipient is registered using the standard register_account operation with the same strategy.

Refer to the Github repository for more details and code examples.