ArchitectureComponentsToken Features
Transaction Fee Accounting
Tracks per-transaction fees for off-chain reconciliation without collecting them on-chain. Emits events for invoicing and reporting workflows. No holder economic impact.
Purpose: Transaction Fee Accounting records fee obligations per transaction without on-chain collection. Platforms use the emitted events for invoicing, reporting, or periodic settlement workflows.
- Doc type: Reference
- What you'll find here: Business impact, risks, controls, failure modes, auditability, dependencies, and ordering notes
- Related:
Interface (capabilities)
This feature exposes the following capabilities. Unlike Transaction Fee, it tracks fee obligations without on-chain collection — platforms use emitted events for off-chain reconciliation.
| Capability | Who can call | Inputs | On-chain effect | Emits | Notes |
|---|---|---|---|---|---|
| Record fee on operation | Automatic (hook) | Triggered on mint, burn, transfer | Increments accrued counter; no token movement | FeeAccrued | Does not rewrite amounts |
| Reconcile accrued fees | GOVERNANCE_ROLE | None | Resets accrued counter; closes accounting period | FeesReconciled | Off-chain settlement trigger |
| Set fee rates | GOVERNANCE_ROLE | Rates per operation type (bps) | Updates fee rate configuration | FeeRatesUpdated | Blocked after freeze |
| Set fee recipient | GOVERNANCE_ROLE | Recipient address | Redirects future reconciliation target | FeeRecipientUpdated | Effective immediately |
| Set fee exemption | GOVERNANCE_ROLE | Account address + exempt flag | Marks address as exempt from tracking | FeeExemptionSet | For system addresses |
| Freeze fee rates | GOVERNANCE_ROLE | None | Permanently locks all rates | FeeRatesFrozen | Irreversible |
Business impact
- Holders: No on-chain economic impact — fees are tracked, not collected. Token amounts are not rewritten.
- Issuer / platform: Fee obligations accumulate off-chain; platform must run a reconciliation workflow to actually collect.
- Economics: Decouples fee obligation recording from settlement. Enables periodic bulk invoicing rather than per-transaction collection.
Risks & abuse cases
- Reconciliation drift: If
reconcileFees()is not called on schedule, accrued fee obligations grow without bound in accounting records. Platforms must maintain a disciplined reconciliation cadence. - Exemption scope creep:
setFeeExemption()can exempt specific addresses from fee tracking. If over-used, fee accounting becomes incomplete. - No on-chain enforcement: Fee obligations are advisory. Off-chain systems must act on emitted events to collect. There is no automatic enforcement mechanism.
Controls & guardrails
| Role | Actions | Recommended guardrail |
|---|---|---|
GOVERNANCE_ROLE | setFeeRates() — set fee rates per operation type | Document rates and lock via process; no on-chain freeze available |
GOVERNANCE_ROLE | reconcileFees() — mark fees as reconciled for an address/period | Automate via scheduled off-chain job |
GOVERNANCE_ROLE | setFeeExemption(address, exempt) — exempt specific addresses | Audit exemption list; restrict exemptions to system addresses only |
Failure modes & edge cases
- Accounting without collection: Recorded obligations that are never settled create audit discrepancies. Establish a settlement SLA.
- Rate changes mid-period: If fee rates change during a billing period, events reflect the rate at the time of the transaction. Off-chain systems must handle rate changes in reconciliation logic.
- High event volume: High-frequency tokens produce large event logs. Ensure off-chain indexing infrastructure handles the volume.
Auditability & operational signals
FeeAccrued(from, to, amount, fee, operationType)— emitted per tracked transaction. Primary signal for off-chain reconciliation.FeesReconciled(address, period, amount)— emitted whenreconcileFees()is called. Confirms settlement.FeeExemptionSet(address, exempt)— emitted when exemption status changes.
Dependencies
- No external ERC-20 required.
- No other features required.
- Off-chain reconciliation infrastructure required (indexer, invoicing system, or subgraph).
Compatibility & ordering notes
supportsRewriting = false— does not modify transfer amounts. Safe to run at any position.- Compatible with Transaction Fee (different collection mechanisms; can run both to track and collect simultaneously).
- Compatible with all other features — no ordering constraints.
Change impact
- Enable after launch: Historical transactions before activation are not retroactively tracked.
- Disable: In-progress uncollected obligations remain in off-chain records. Reconcile before disabling.
- Rate change: Effective immediately. Off-chain systems must handle rate history for correct reconciliation.
See also
- Token Features Catalog — return to the full feature catalog
- Transaction Fee — on-chain fee collection alternative
- Treasury Distribution — distribution and settlement flows
Transaction Fee
Per-transaction fee deducted from transfer amounts on every mint, burn, or transfer. Uses supportsRewriting to reduce the amount in-flight before compliance checks and recipient receipt.
External Transaction Fee
Fixed fee in a separate ERC-20 token (e.g., USDC) charged on every mint, burn, or transfer. Fee is collected from the payer's allowance separately from the transferred amount.