Fee-based Tokens

Overview

Fee-based tokens introduce an alternative token model where no upfront deposit is required during minting. Instead, transaction fees are charged on each transfer of the token.

This model differs from the traditional deposit-based approach and is designed to:

• Reduce initial barriers to token creation
• Enable scalable, high-frequency use cases
• Provide flexible monetization strategies

Token Models Comparison

When creating tokens, you can choose between two models:

Deposit-Based Tokens (Default)

Deposit-based tokens follow the traditional model where minting requires locking a percentage of the token's value in HTR (e.g., 1%). This deposit acts as a reserve and can be fully withdrawn when the tokens are later melted.

Because of this backing mechanism, deposit-based tokens are well-suited for use cases where backing and scarcity are important. They are commonly used for assets that represent a stored value or require specific economic guarantees.

Fee-Based Tokens

Fee-based tokens remove the need for any upfront deposit during minting. Instead, costs are distributed over time through transaction fees, which are charged on each transfer and permanently burned.

This model is effective for high-activity environments. It enables scalable token economies where frequent, and even small transactions are expected, such as in games, loyalty programs, or other utility-driven systems. By eliminating the initial capital requirement, it also lowers the barrier for token creation and experimentation.

How Fee-Based Tokens Work

Core Concept

Fee-based tokens shift the cost from minting time to usage time.

Instead of locking value when the token is created, the cost is applied whenever the token is used in a transaction. In practice, this means:

• Tokens can be minted without any upfront deposit
• Each transaction involving the token incurs a small fee
• The transaction must explicitly define how the fee is paid using a fee header

This approach makes token creation more accessible while ensuring the network still collects fees during usage.

Fee Calculation

Fees are calculated based on how many outputs include fee-based tokens in a transaction.

Fee = number_of_outputs × 0.01 HTR

Key Rules

When working with fee-based tokens, a few rules must always be respected.

• Only outputs that contain fee-based tokens are considered when calculating the fee.
• If a transaction does not generate any outputs (for example, during a melt operation), it is treated as having one output for fee purposes.

Additionally, fee validation is strict, which means that the total fee must match the expected value exactly. Any underpayment or overpayment will cause the transaction to be rejected.

Fee Payment Options

Fees can be paid using different tokens, depending on availability and preference.

HTR (Native Token)

The most straightforward option is to pay fees directly in HTR. This requires no conversion and is generally the simplest approach to implement and understand.

Deposit-Based Tokens

Fees can also be paid using deposit-based tokens. In this case, the amount is converted using a fixed ratio derived from the deposit percentage (for example, 100:1 when the deposit is 1%).

Because of this conversion, amounts must be provided in exact multiples of the conversion factor to avoid precision loss.

For example, if the required fee is:

0.01 HTR

It can be paid as either:

• 0.01 HTR (native token)
• 1.00 deposit-token (converted equivalent)

Fee Header

To validate a transaction, it is not enough to know that a fee exists — the transaction must explicitly declare how the fee is being paid. This is done through the fee header.

The fee header specifies:

• Which token is used to pay the fee
• How much of that token is being used

Example

inputs:  [100 DBT, 1000 FBT]
outputs: [1000 FBT]
tokens:  [DBT, FBT]

fee_header:
  fees: [(100, 1)]  ← Pay 100 DBT as fee

In this example, the tuple (100, 1) represents the fee payment:

• 1 refers to the index of the token in the tokens array (DBT)
• 100 is the amount of that token used to pay the fee

This way, the fee header removes ambiguity by making fee payment explicit and proving the network with information to:

• Identify which tokens are being used for fees.
• Convert values if necessary (e.g., deposit tokens → HTR equivalent)
• Verify that the total fee matches the required amount exactly.

Using Fee-Based Tokens

Nano Contracts Behavior

Fee-based tokens do not follow a gas-based model like Ethereum. Instead of charging for computational complexity, fees are applied in a more predictable way based on operations performed.

Each relevant operation executed within a nano contract incurs a fixed cost of 0.01 HTR. These costs are applied per action or syscall, making fees easier to estimate and reason about.

In practice, fees are charged for operations such as:

• Token creation (create_fee_token)
• Minting tokens (mint_tokens)
• Melting tokens (melt_tokens)
• Contract interactions like deposits and withdrawals

This model keeps execution costs simple and deterministic, avoiding the variability typically associated with gas-based systems.

Contract Deposits and Withdrawals

When interacting with nano contracts, fee-based tokens are commonly moved into and out of contracts through deposit and withdrawal actions. However, for the number of actions, the fee calculation only takes into account actions that are relevant to fee-based tokens, such as deposits, and withdrawals.

Fee = 0.01 × number_of_outputs + number_of_actions

These actions are fundamental to enabling contract-based logic such as escrow, staking, or conditional transfers.

Deposit

A deposit transfers tokens from a user into a nano contract.

This action:

• Locks the tokens inside the contract
• Makes them available for contract logic
• Counts as a fee-charging action

Example behavior:

User → Contract: deposit 100 FBT

This increases the contract's internal balance and allows the contract to manage or redistribute those tokens based on its logic.

Withdrawal

A withdrawal transfers tokens from the contract back to a user.

This action:

• Releases tokens from the contract state.
• Sends them to a specified output
• Also counts as a fee-charging action

Example behavior:

Contract → User: withdraw 100 FBT
Fee Impact

Given that both deposit and withdrawal operations are considered actions in fee calculation, and each action adds a fixed cost of 0.01 HTR; a transaction that includes 1 deposit + 1 withdrawal + 2 outputs would result in a total fee of:

Fee = (2 × 0.01) + (2 × 0.01) = 0.04 HTR

This ensures that contract interactions remain predictable while still accounting for state-changing operations.

Creating a Token

Fee-based tokens can be created directly within nano contracts using a dedicated syscall:

fbt = self.syscall.create_fee_token(5000, 'FBT')

This operation mints the token without requiring any upfront HTR deposit. Instead, the only cost incurred is the syscall fee associated with executing the operation.

As a result, token creation becomes lightweight and accessible, making it easier to experiment with new token models or launch high-volume use cases without needing initial capital.

Transferring Tokens

When transferring fee-based tokens, the cost of the transaction depends on how many outputs include those tokens.

Each output that contains a fee-based token contributes to the total fee. As a result, transactions with more outputs will incur in higher fees.

For example:

5 outputs → 5 × 0.01 HTR = 0.05 HTR fee

This means that splitting a transfer into multiple outputs (e.g., sending tokens to multiple recipients) increases the total cost proportionally.

Melting Tokens

Melting fee-based tokens follows the same authorization rules as other token models, but still requires paying the corresponding transaction fee.

To perform a melting operation, the transaction must include melting authority for the token. Even though no outputs may be created, the operation is still considered in the fee calculation and will incur a minimum fee.

As with all fee-based transactions, the fee must be exactly correct.

Invalid example:

Required: 100 DBT
Provided: 150 DBT → ❌ rejected

In this case, the transaction is rejected because the fee exceeds the required amount. Both underpayment and overpayment are not allowed.