External Transaction Fee
Fixed mint, burn, and transfer fees collected in a separate ERC-20 token. Covers fee token approvals, governance controls, freeze behavior, and operational failure modes.
External Transaction Fee collects a fixed ERC-20 fee whenever the asset token is minted, burned, or transferred. Use External Transaction Fee when the programme charges in a separate asset, such as a stable fee token, and the transferred asset amount must stay unchanged. The payer needs enough of the configured fee token. The payer must also approve the feature contract before the operation can complete.
Operating model
The fee hook is gross based. It adds a separate ERC-20 transfer on top of the asset operation instead of rewriting the asset amount.
To see the feature work end to end, configure a non-zero fee, fund the payer with the fee token, approve the feature contract, and run a mint, burn, or transfer that triggers the hook. A successful operation keeps the asset amount intact and emits ExternalFeeCollected for the separate fee payment.
Interface
Fees are denominated in the configured fee token and collected from the payer's allowance.
| Capability | Who can call | Inputs | On-chain effect | Emits | Notes |
|---|---|---|---|---|---|
| Collect external fee on operation | Automatic hook | Triggered on mint, burn, transfer | Transfers fee token from payer to recipient | ExternalFeeCollected | Payer must have approved fee token |
| Set fee amounts | GOVERNANCE_ROLE | Fixed mint, burn, and transfer fees in the fee token's smallest unit | Updates fee amounts | FeesUpdated | Blocked after freeze |
| Set fee token | GOVERNANCE_ROLE | ERC-20 token address | Changes fee denomination token | FeeTokenUpdated | All payers must re-approve new token |
| Set fee recipient | GOVERNANCE_ROLE | Recipient address | Redirects future collections | FeeRecipientUpdated | Effective immediately |
| Freeze fees | GOVERNANCE_ROLE | None | Permanently locks configuration | FeesFrozen | Irreversible |
What payers must prepare
A payer needs three things before an operation that triggers the feature:
- The asset token being minted, burned, or transferred, when the operation requires an asset balance.
- Enough balance of the configured external fee token.
- Enough allowance from the fee token to the External Transaction Fee feature contract.
The DALP dapp shows the payer's fee token balance and allowance in the mint, burn, and transfer sheets. The readiness panel compares both values with the fee required for that operation, including repeated charged rows in a batch submission.
Amount units
Configure mint, burn, and transfer fees in the external fee token, not in the asset token. For API calls, submit the raw smallest-unit amount for the configured fee token. In the dapp, the fee-setting form reads the fee token and scales the entered value with that token's decimals before submission.
If governance changes the fee token, review the configured fee amounts before operating the asset again. The same displayed amount can map to a different raw value when the new fee token uses different decimals.
Governance controls
| Control | Effect | Production check |
|---|---|---|
setFees() | Updates mint, burn, and transfer fee amounts | Confirm the values are expressed in the fee token's smallest unit |
setFeeToken() | Changes the ERC-20 token used for fee payments | Communicate the new token and require fresh payer approvals |
setFeeRecipient() | Changes the destination for future fee collections | Keep the recipient under an approved treasury or multisig policy |
freezeFees() | Permanently locks fee amounts, token, and recipient | Freeze only after the launch configuration is final |
All four governance actions are unavailable after the fee configuration is frozen. The dapp disables the actions when the connected wallet lacks the governance role or when the feature is already frozen.
Operational impact
- Holders and payers: Every covered operation has an additional ERC-20 cost. The operation reverts if the payer lacks fee token balance or allowance.
- Issuer or recipient: Fee revenue is collected in the configured ERC-20 token, which can be a stable asset when the programme needs predictable fee denomination.
- Economics: External fees keep the gross asset amount intact. Use this feature when the fee should not be taken out of the transferred asset itself.
Failure modes and edge cases
| Condition | Result | Operator response |
|---|---|---|
| Payer has no fee token allowance | The mint, burn, or transfer reverts | Prompt the payer to approve the fee token for the feature contract |
| Payer has too little fee token balance | The operation reverts | Fund the payer wallet or lower the fee before freeze |
| Fee token contract pauses or fails | Covered token operations can revert | Use a reliable ERC-20 fee token and monitor token contract health |
| Governance changes the fee token | Existing payer approvals stop applying | Tell payers to approve the new fee token before their next operation |
| Governance freezes the configuration | Fee amounts, recipient, and fee token can no longer change | Treat freeze as a launch control, not as a routine update |
Auditability and operational signals
ExternalFeeCollected(from, feeToken, feeAmount, operationType): emitted for each collected external fee.FeesUpdated(sender, mintFee, burnFee, transferFee): emitted when governance changes fee amounts.FeeTokenUpdated(sender, oldToken, newToken): emitted when governance changes the fee token.FeeRecipientUpdated(sender, oldRecipient, newRecipient): emitted when governance changes the recipient.FeesFrozen(sender): emitted when governance freezes the configuration.
Fee totals shown for the active fee token are cumulative for that fee token. If governance changes the fee token and later switches back, the displayed total for the restored token includes fees collected before the earlier change. A fee token that has not collected fees yet starts at zero.
Compatibility notes
- External Transaction Fee does not rewrite the asset transfer amount.
- When the asset also uses Transaction Fee, place Transaction Fee before External Transaction Fee. Transaction Fee rewrites the asset amount. External Transaction Fee collects a separate fee token.
- Compliance checks still evaluate the asset amount. The external fee collection is a separate ERC-20 movement.
- The feature can be attached through the configurable-token feature route when the asset supports feature attachment.
API surfaces
DALP exposes the External Transaction Fee controls through token mutation routes:
| Action | Method and path | Purpose |
|---|---|---|
| Create feature | POST /api/v2/tokens/{tokenAddress}/external-transaction-fee/features | Attach the feature with fee token, recipient, and initial fee amounts |
| Set amounts | PATCH /api/v2/tokens/{tokenAddress}/external-transaction-fee/amounts | Update mint, burn, and transfer fees before freeze |
| Set recipient | PATCH /api/v2/tokens/{tokenAddress}/external-transaction-fee/recipient | Update the recipient for future collections before freeze |
| Set fee token | PATCH /api/v2/tokens/{tokenAddress}/external-transaction-fee/token | Change the ERC-20 token used for fee payments before freeze |
| Freeze | POST /api/v2/tokens/{tokenAddress}/external-transaction-fee/rate-freezes | Permanently freeze the fee configuration |
The route schemas define the exact request and response fields for these controls.
See also
- Token Features Catalog: compare available token features
- Transaction Fee: collect fees from the asset amount itself
- Asset Contracts: understand deployment architecture and roles
- Mint assets: operate asset minting from the dapp
- Burn assets: operate asset burning from the dapp
Transaction Fee Accounting
Explains how DALP records per-operation fee obligations for off-chain invoicing without collecting tokens on-chain. Covers rates, exemptions, reconciliation, and audit events.
Voting Power
Voting Power adds delegated, checkpointed voting weight to DALPAsset tokens for governance contracts that read current or past votes.