# Transaction Fee Accounting Source: https://docs.settlemint.com/docs/architecture/components/token-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. Transaction Fee Accounting records fee obligations for mint, burn, transfer, and redemption operations without collecting tokens on-chain. Platforms use the emitted accounting events to invoice, report, or settle those obligations outside the token contract. Governance users can set account exemptions from the transaction fee accounting capability card when an address should be excluded from fee tracking. Related pages: * [Token Features Catalog](/docs/architecture/components/token-features) * [Asset Contracts](/docs/architecture/components/asset-contracts) * [Treasury Distribution](/docs/architecture/flows/treasury-distribution) ## Interface [#interface] Unlike [Transaction Fee](/docs/architecture/components/token-features/transaction-fee), Transaction Fee Accounting tracks fee obligations without moving or withholding tokens. | Capability | Who can call | Inputs | On-chain effect | Emits | Notes | | ----------------------- | ----------------- | --------------------------------------------- | ------------------------------------------------ | --------------------- | ------------------------------------------------------- | | Record fee on operation | Automatic (hook) | Triggered on mint, burn, transfer, redemption | 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` | Mint, burn, and transfer rates in bps | Updates fee rate configuration | `FeeRatesUpdated` | Redemptions use the burn fee rate; 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` | Available from the dapp capability card and API | | Freeze fee rates | `GOVERNANCE_ROLE` | None | Permanently locks all rates | `FeeRatesFrozen` | Irreversible | *** ## Business impact [#business-impact] * **Holders:** No on-chain economic impact. Fees are tracked, not collected, and 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 [#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. Exempting the zero address is valid and excludes mint-side or burn-side fee tracking because mint and burn operations use the zero address on one side of the token movement. * **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 [#controls--guardrails] | Role | Actions | Recommended guardrail | | ----------------- | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------- | | `GOVERNANCE_ROLE` | `setFeeRates()` - set mint, burn, and transfer rates | Document changes and freeze rates when they should no longer move | | `GOVERNANCE_ROLE` | `reconcileFees()` - mark accrued fees as reconciled for a period | Automate via scheduled off-chain job | | `GOVERNANCE_ROLE` | `setFeeExemption(address, exempt)` - exempt a holder, system address, or the zero address for mint/burn accounting paths | Audit exemption list; keep exemptions narrow and time-bound | | `GOVERNANCE_ROLE` | `freezeFeeRates()` - permanently lock the configured rates | Treat as irreversible | *** ## Failure modes & edge cases [#failure-modes--edge-cases] * **Accounting without collection:** Recorded obligations that are never settled create audit discrepancies. Establish a settlement SLA. * **Concurrent fee events:** Fee accruals are added to the existing indexed total. Reconciliation resets the accrued total and adds the reconciled amount to the reconciled total, so reporting jobs should treat `FeeAccrued` and `FeesReconciled` as period events rather than overwriting earlier events. * **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 [#auditability--operational-signals] * `FeeAccrued(payer, from, to, feeType, operationAmount, feeBps, feeAmount, timestamp)` - emitted per tracked operation. Use `feeAmount` for the accrued obligation and `feeType` to distinguish mint, burn, transfer, and redemption operations. * `FeesReconciled(caller, recipient, amount, periodEnd)` - emitted when accrued fees are reconciled. After reconciliation, the accrued total returns to zero and the reconciled total increases by the reconciled amount. * `FeeRatesUpdated(sender, oldRates, newRates)` - emitted when fee rates change. * `FeeRecipientUpdated(sender, oldRecipient, newRecipient)` - emitted when the recipient changes. * `FeeRatesFrozen(sender)` - emitted when rate changes are permanently locked. * `FeeExemptionSet(sender, account, exempt)` - emitted when exemption status changes. *** ## Dependencies [#dependencies] * No external ERC-20 required. * No other features required. * Off-chain reconciliation infrastructure required (indexer, invoicing system, or subgraph). *** ## Compatibility & ordering notes [#compatibility--ordering-notes] * `supportsRewriting = false` - does not modify transfer amounts. Safe to run at any position. * Mutually exclusive with Transaction Fee in asset templates and token creation requests. Use Transaction Fee for on-chain collection, or Transaction Fee Accounting for off-chain settlement records. * Compatible with all other features. There are no ordering constraints. *** ## Change impact [#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 [#see-also] * [Token Features Catalog](/docs/architecture/components/token-features) - return to the full feature catalog * [Transaction Fee](/docs/architecture/components/token-features/transaction-fee) - on-chain fee collection alternative * [Treasury Distribution](/docs/architecture/flows/treasury-distribution) - distribution and settlement flows