# Token features

Source: https://docs.settlemint.com/docs/concepts/modeling-assets/token-features
How the sixteen documented token features reach a token, how to choose one, and why a feature operation is rejected, with one reference page per feature group.

Seventeen token features add behaviour to a token, such as paying a coupon, charging a fee, or converting a loan into equity, and this catalogue documents sixteen of them. A feature reaches a token through an instrument template or, after issuance, through a governance action. This page covers that route, how to choose a feature, and why an operation is rejected. Five reference pages hold one entry per feature, with its parameters, units and the roles that operate it. [Instrument templates](https://docs.settlemint.com/docs/console/asset-design/instrument-templates) covers the template workflow, and composable token explains why a token's behaviour is built from features. The [Platform API](https://docs.settlemint.com/docs/api-reference/v2) manages the same features programmatically.

An instrument template is a set of token features with their defaults, plus metadata fields and a compliance policy. You select a feature on the template's "Features" step, and issuing from that template installs it. After issuance, an account that holds the governance role attaches, detaches, rotates, or updates it. A token holds an ordered list of at most 32 features and runs them in list order: the template's order at issuance, and the end of the list for a feature attached later. The platform never sorts the list.

After issuance, the Console attaches twelve features from the "Attach a feature" list on a token's Features tab. Hold, voting power, permit, and supply delegate take no settings. Register lines, the feature behind [Booked movements](https://docs.settlemint.com/docs/console/asset-management/manage/booked-movements), is the one feature this catalogue does not document. It needs hold attached first and asks which moves an investor may request. Maturity redemption, dividend yield, interest yield, management fee, transaction fee, transaction fee accounting, and external transaction fee ask for their settings, which the sheet shows for review before the wallet step. The list leaves out a feature that is already attached, and interest yield on an asset type other than deposit or fund. Fixed treasury yield attaches from "Set yield schedule" on the token's yield page, and voting power also from the Governance wizard, which offers an inline attach when the token lacks it.

The menu on a feature's section on the same tab detaches every feature except conversion and the distribution waterfall, and replaces a feature that has settings. Conversion and the distribution waterfall reach a token through the platform only from a template at issuance, and neither the Console nor the Platform API attaches, detaches or rotates them. The Platform API attaches every other feature. On chain, the token's governance role can still replace the whole feature list, those two included. Each feature entry names the actions that exist after issuance and the role each one needs.

Every form that configures a feature, in the template's "Features" step, in structures, and at issuance, shows each parameter under its name and a sentence on what to enter, and opens the feature with its own summary line, the same sentence the feature's detail screen shows. The tables give the platform identifier wherever an API call takes it. The four fee features, fixed treasury yield, conversion, and the conversion minter have a second generation, a newer implementation of the feature contract, and their entries say how it differs. Each feature instance runs the implementation its feature factory points to, and the Console shows no generation badge.

[Figure] Where a token's features come from. An instrument template has three parts: the token features with their defaults, the metadata fields an issuer fills in, and the compliance policy a new token starts with. Issue asset turns the template into a token. The token holds an ordered list of at most 32 features, which it runs in list order. The platform never sorts the list. After issuance, an account with the governance role can attach, detach, rotate, or update a feature. A later template edit does not reach a token that was already issued. Labels: One instrument template, three parts; Token features; Chosen on the Features; step, with defaults.; Metadata fields; Product facts the; issuer fills in.; Compliance policy; The rules a new; token starts with.; Issue asset; The token's ordered feature list; At most 32 features. They run in list order, and the platform never sorts the list.; After issuance, the governance role changes the list; Attach, detach, rotate, or update a feature. A template edit never reaches an issued token.

A template fixes the starting feature list, and after issuance only governance actions change the token's own list.

## Feature reference pages [#feature-reference-pages]

Each page covers one group of features and states, for every feature in it, the parameters, the units, and the actions after issuance.

- [Income features](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income): dividend yield, interest yield, fixed treasury yield, maturity redemption, and the distribution waterfall.
- [Fee features](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/fees): management fee, transaction fee, transaction fee accounting, and external transaction fee.
- [Conversion features](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/conversion): conversion and the conversion minter.
- [Permit](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/permit): the permit feature and the Platform API routes that sign and relay a permit.
- [Balance, voting, hold and supply features](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/balances-and-holds): historical balances, voting power, hold, and supply delegate.

## Choose the feature by what it does [#choose-the-feature-by-what-it-does]

Group the sixteen features by the job they do, then pick the one in that row that matches your requirement.

| You need to | Features | The feature decides |
| --- | --- | --- |
| Pay holders income or principal | [Dividend yield](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#dividend-yield), [Interest yield](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#interest-yield), [Fixed treasury yield](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#fixed-treasury-yield), [Maturity redemption](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#maturity-redemption), [Distribution waterfall](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#distribution-waterfall) | How much a holder receives, from which treasury, and when |
| Charge or account for fees | [Management fee](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/fees#management-fee), [Transaction fee](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/fees#transaction-fee), [Transaction fee accounting](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/fees#transaction-fee-accounting), [External transaction fee](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/fees#external-transaction-fee) | Who pays, in which asset, and whether value moves |
| Convert one instrument into another | [Conversion](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/conversion#conversion), [Conversion minter](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/conversion#conversion-minter) | The price, the window, and which token is minted |
| Keep records and enable voting | [Historical balances](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/balances-and-holds#historical-balances), [Voting power](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/balances-and-holds#voting-power) | Which balances can be read at a past time, and who holds vote weight |
| Approve or reserve units | [Permit](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/permit#permit), [Hold](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/balances-and-holds#hold) | Who can approve a spender by signature, and who can reserve units |
| Let a wallet or add-on mint and burn | [Supply delegate](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/balances-and-holds#supply-delegate) | Who may mint, who may burn, and up to what amount |

Within the income row, the choice is how the amount is decided. [Dividend yield](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#dividend-yield) pays an amount per share that the issuer declares each time, fixed from balances on a record date. [Interest yield](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#interest-yield) pays a rate that accrues on balances as time passes. [Fixed treasury yield](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#fixed-treasury-yield) pays a fixed coupon for each period, on the balance held at the end of that period. [Maturity redemption](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#maturity-redemption) pays face value once, after maturity, in exchange for the token. The [distribution waterfall](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#distribution-waterfall) decides no amount. It splits one pool across the share classes of an instrument, and each class's dividend yield then pays from its own part.

Within the fee row, the choice is who pays and what moves. One 100-token transfer shows the four behaviours side by side. The example uses a transaction fee of 2.5%, which is 250 basis points,, a flat external fee of 2.5 units of a second token, and a 1% yearly management fee that is collected separately.

| On one 100-token transfer | Net: [transaction fee](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/fees#transaction-fee) | Gross: [external transaction fee](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/fees#external-transaction-fee) | Inflationary: [Management fee](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/fees#management-fee) | Tracking: [transaction fee accounting](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/fees#transaction-fee-accounting) |
| --- | --- | --- | --- | --- |
| The receiver gets | 97.5 tokens | 100 tokens | 100 tokens | 100 tokens |
| The sender pays | 100 tokens | 100 tokens, plus 2.5 fee tokens | 100 tokens | 100 tokens |
| The fee is paid in | The same token, to the recipient | A second token, to the recipient | New tokens, minted to the recipient | Nothing moves |
| The fee depends on | A percentage of the amount | A fixed amount for each operation | Average supply and elapsed time | A percentage, recorded only |
| It dilutes holders | No | No | Yes | No |
| A holder must act | No | Hold fee tokens and approve the feature | No | No |

The next table shows what each feature needs before it works, what it cannot sit beside, and whether it needs a token before issuance. A feature that needs a token before issuance makes the template row show "Needs a denomination asset" or "Needs a target token" on Issue asset until the tenant has that token. The Features step enforces the dependencies and the conflicts as you toggle: "Select Historical Balances first." and "Conflicts with Transaction Fee Accounting." are the messages it shows.

| Feature | Needs | Cannot sit beside | Needs a token before issuance |
| --- | --- | --- | --- |
| [Conversion](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/conversion#conversion) | A conversion minter on the target token, and an interest provider if interest converts | [Booked movements](https://docs.settlemint.com/docs/console/asset-management/manage/booked-movements) | Yes: a denomination token and a target token |
| [Conversion minter](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/conversion#conversion-minter) | A conversion feature that is on its list of converters | [Booked movements](https://docs.settlemint.com/docs/console/asset-management/manage/booked-movements) | No |
| [Distribution waterfall](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#distribution-waterfall) | Dividend yield and historical balances | Nothing | Yes: a payment token |
| [Dividend yield](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#dividend-yield) | Historical balances | Nothing | Yes: a denomination token |
| [External transaction fee](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/fees#external-transaction-fee) | Nothing | Nothing | Yes: a fee token |
| [Fixed treasury yield](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#fixed-treasury-yield) | Historical balances | Nothing | Yes: a denomination token |
| [Historical balances](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/balances-and-holds#historical-balances) | Nothing | Nothing | No |
| [Hold](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/balances-and-holds#hold) | Nothing | Nothing | No |
| [Interest yield](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#interest-yield) | Historical balances | Nothing | Yes: a denomination token |
| [Management fee](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/fees#management-fee) | Nothing | [Booked movements](https://docs.settlemint.com/docs/console/asset-management/manage/booked-movements) | No |
| [Maturity redemption](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#maturity-redemption) | Nothing | [Booked movements](https://docs.settlemint.com/docs/console/asset-management/manage/booked-movements) | Yes: a denomination token |
| [Permit](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/permit#permit) | Nothing | Nothing | No |
| [Supply delegate](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/balances-and-holds#supply-delegate) | Nothing | [Booked movements](https://docs.settlemint.com/docs/console/asset-management/manage/booked-movements) | No |
| [Transaction fee](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/fees#transaction-fee) | Nothing | Transaction fee accounting | No |
| [Transaction fee accounting](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/fees#transaction-fee-accounting) | Nothing | Transaction fee | No |
| [Voting power](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/balances-and-holds#voting-power) | Nothing (token governance needs it) | Nothing | No |

## When an operation is rejected [#when-an-operation-is-rejected]

A rejection comes from one of three places: the template, the attach and detach API, or the token itself while it runs. A rejection reflects the rule and the state at that moment, so repeating the same call fails again until the condition changes.

The template's "Features" step blocks a feature that misses a dependency or conflicts with another one. Publishing checks both again, and issuing a token with the conflicting pair is rejected with [DALP-0605](https://docs.settlemint.com/docs/api-reference/errors).

An attach, detach, or rotate through the Platform API can be rejected for these reasons.

| Reason | What it means |
| --- | --- |
| `already-attached` | The token already has the feature. A conflicting feature that is already attached gives the same reason, with a message that names it, and the refusal's `conflictingFeatureName` field carries the id of the feature to detach. |
| `conversion-incompatible` | The token's conversion uses MarkConverted, and you tried to attach or rotate interest yield or fixed treasury yield. A balance-based yield would keep paying on converted supply. |
| `conversion-provider-unresolvable` | The change would leave the conversion feature without exactly one interest provider: both yield features are attached and none is chosen, the chosen one is wrong, or the denominations differ. |
| `dividends-outstanding` | A detach or rotate of dividend yield while declared dividends are still unclaimed. Let holders claim, or reclaim the dividends, first. |
| Detach blocked by dependents | Another attached feature depends on the feature. The message lists them. |
| Detach blocked by open proposals | The token's governor has pending, active, or queued proposals, and the feature is voting power. |
| `dependency-not-attached` | An attach of a feature whose dependency is missing. The refusal lists the missing features, for example historical balances for a yield feature, or hold for register lines. |
| `token-not-configurable` | The token was issued without a feature list, as tokens of the original asset families are, so nothing can be attached. |
| `start-date-in-future` | An interest yield start date after the chain's next block. Leave it out or set it at or before that time. |
| `payout-treasury-is-token` | A yield or maturity redemption treasury that is a token contract. |
| `fixed-yield-ends-after-maturity` | A fixed treasury yield that would end after the attached maturity date, or a maturity date before the attached fixed treasury yield ends. Applies to attach only. |
| `create-feature-would-revert` | A simulation of the factory call from the submitting wallet reverted. The refusal names the contract error when it is known. Nothing was queued. |
| `feature-not-found`, `stale-index` | The feature is not attached, or the index lists a feature the token no longer carries on chain. |
| `unchanged-address` | A rotate whose configuration equals the current one, so it would land on the address already in use. A feature without settings, such as permit, always gives this. |
| `not-replaceable` | A rotate of register lines. Change its requestable kinds through the settings route instead. |
| `name-mismatch` | The body names a different feature from the path. |
| `factory-not-found` | The system has no factory registered for the feature. |

At run time, a token or a feature reverts with an error that names the rule. These are the ones you meet most often.

| Feature | Error | When it happens |
| --- | --- | --- |
| Any feature with a governance action | `UnauthorizedCaller` ([DALP-4331](https://docs.settlemint.com/docs/api-reference/errors)) | The caller lacks the governance role. |
| Maturity redemption | `TransferBlockedAfterMaturity` (DALP-1092) | A transfer or a mint after maturity. |
| Maturity redemption | `InsufficientTreasuryBalance` (DALP-1043) | Maturing, or redeeming, when the treasury cannot cover the payout. |
| Hold | `AmountExceedsAvailable` | A transfer, burn, or reservation above the available balance. |
| Conversion | `CannotTransferConvertedTokens` | MarkConverted: a transfer or burn of units already converted. |
| Conversion | `ConversionMinterMissing`, `UnauthorizedConverter` | The target token has no minter, or its minter does not list the conversion feature. |
| Conversion | `ZeroTargetAmount` | The target amount rounds down to zero. |
| Distribution waterfall | `InsufficientAllocation` | A class's payout exceeds its leg. |
| Distribution waterfall | `UnauthorizedClass`, `PayoutAssetMismatch` | The caller is not the class's dividend yield, or the payout is in another asset. |
| Distribution waterfall | `UnboundDividend`, `ReferenceRequired` | The claimed dividend was not bound by a funded distribution, or the call names none. |
| Distribution waterfall | `WaterfallUnderfunded`, `AlreadyReleased` | A release while the waterfall holds less than it owes, or of a leg already released. |
| Distribution waterfall | `SplitChanged` | The split changed between the preview and the confirm. Nothing moved. |
| Distribution waterfall | `ClassNotBound` | A class has no token bound. |
| Distribution waterfall | `DistributionNettingLocked` | A netting change after a distribution was funded under that priority row. |
| Distribution waterfall | `UnknownPriorityRow` | A netting change or read for a determination kind that has no priority row. |
| Transaction fee, transaction fee accounting | `FeeRatesAreFrozen` (DALP-1020) | A rate change after a freeze. Accounting also locks the recipient. The net fee does not. |
| Management fee | `FeeRateIsFrozen` (DALP-1019) | A rate or recipient change after a freeze. |
| External transaction fee | `FeesAreFrozen` (DALP-1024) | An amount, recipient, or token change after a freeze. |
| External transaction fee | `ERC20InsufficientAllowance` (DALP-1102) | The payer has not approved the feature to spend the fee token. |
| Transaction fee accounting | `NoFeesToReconcile` (DALP-1070) | Reconcile with a zero total. |
| Fixed treasury yield | `NoYieldAvailable` (DALP-4243) | A claim when no completed period has anything to pay. |
| Historical balances | `QueryBeforeEnabled` | A strict lookup for a time before the feature started. |

## Troubleshooting [#troubleshooting]

**A feature card says Select X first or Conflicts with X**

The Features step shows "Select Historical Balances first." when a feature needs another one, and "Conflicts with
Transaction Fee Accounting." when two selected features cannot sit on one token. Enable the named feature first.
Turning a feature off also turns off every feature that depends on it, so the confirmation can remove more than the
card you clicked.

**A template shows Needs a denomination asset**

Seven features need a token that already exists in the tenant: external transaction fee, maturity redemption, fixed
treasury yield, dividend yield, interest yield, the distribution waterfall, and conversion. Any token satisfies the
check, and conversion also needs a target token that has the conversion minter. Open the template's detail panel and
issue the token it needs, or register an existing one, for example with "Issue a stablecoin" or "Register an existing
stablecoin", then return to Issue asset.

**A coupon pays more than expected**

The contract pays its stored rate once for each payment period. A schedule created through the Platform API with
`rateBasis` set to `per_period`, or with no basis from either the request or its template, stores the rate as given,
so 500 basis points with a daily interval pays 5% of face value every day. Also check the schedule length: with a
per-period rate, a span that is not a whole number of intervals ends with a shorter period that still pays a full
coupon. Fix the rate and the dates by detaching the feature and attaching a new schedule.

**A transfer fails after maturity**

After maturity every mint and every regular transfer reverts with `TransferBlockedAfterMaturity`. The matured state
cannot be reset, and the block lasts while maturity redemption stays attached. Burns pass, so holders redeem. A
custodian can still run a forced transfer, and an attached feature can still move units. Redeem the position, because
retrying the transfer fails again.

**A transfer fails on held units**

A venue has reserved some of the holder's units, so the transfer is above the available balance and reverts with
`AmountExceedsAvailable`. Units the custodian froze count the same way. Cancel the resting order on the venue to
release the hold, or transfer no more than the available balance.

**A waterfall class receives nothing**

Check four causes. Distinct ordinary ranks are winner-take-all, so a class at a higher rank gets nothing in ordinary
mode. The pool may not reach the class, and the preview then shows "Not reached". A class with a leg but no supply on
the record date, or a per-share rate that rounds to zero, gets no dividend, and its leg stays in the waterfall. Last,
`fund` reverts with `ClassNotBound` until every class has a token.

**An operation reverts on the fee token's allowance**

An external transaction fee pulls the fee from the payer with an ERC-20 transfer, so the payer needs fee-token balance
and an allowance for the feature contract. The payer is the account that receives a mint, or the sender of a transfer
or a burn. The fee recipient is not exempt, so it needs the allowance when it pays.

**A detached feature leaves a gap in its history**

Historical balances records nothing while it is detached. A lookup for that period returns the last checkpoint written
before the detach, so a dividend with a record date in the gap reads stale balances. The platform blocks the detach if
the token has fixed treasury yield, dividend yield, interest yield, or the distribution waterfall. Remove dependent
features before detaching historical balances.

## Frequently asked questions [#frequently-asked-questions]

### Can I add or remove a feature after issuance?

Yes for most features, with the governance role. Holders do not approve these changes: governance can attach a management fee that dilutes every holder, or a transaction fee on every transfer, to a token already in circulation. The Console attaches twelve features from the "Attach a feature" list on the Features tab: hold, voting power, permit, supply delegate, register lines, maturity redemption, dividend yield, interest yield, management fee, transaction fee, transaction fee accounting, and external transaction fee. It attaches fixed treasury yield from "Set yield schedule" on the yield page, which "View yield details" on the Features tab opens. The Platform API attaches those features, historical balances, and the conversion minter. Through the platform, conversion and the distribution waterfall reach a token only at issuance, and neither the Console nor the Platform API detaches them. A detach is blocked while another feature depends on the feature, while declared dividends are unclaimed, and, for voting power, while governance proposals are open. These settings change in place: fee rates and recipients, the fixed treasury yield and maturity redemption treasuries, the interest rate, and the conversion window. Any other setting needs a rotate, which replaces the feature with a new contract at the end of the list. The Console offers it as "Replace" in the section menu of a feature that has settings.

### Does the order of features matter?

Yes, and the platform does not enforce an order. Features run in list order, so a mis-ordered list can change compliance, fee, and rewrite behaviour. The list follows the template at issuance. A feature attached later goes to the end, and a rotated feature moves to the end. The recommended order puts hold first, then restrictions, fees, external fee hooks and analytics, and the DALP Library places hold first on every template except Share-Class Mirror. Read the order from the token's `getFeatures()` list, since the API lists features alphabetically.

### Is the fixed treasury yield rate annual?

In the Console's issuance form and its "Set yield schedule" action for this feature, yes. An asset on the standalone yield schedule takes its rate per period. You enter the rate per year and DALP converts it to the rate each period pays: 500 basis points a year on a semi-annual schedule pays 246.575 basis points every 180 days, and a shorter final period pays that prorated to its length. Through the Platform API, set `rateBasis` to `annual` for the same conversion. A request that leaves it out takes the basis its template states, which is `annual` for the DALP Library's fixed-income templates. With `per_period`, or with no basis stated anywhere, the API treats `rate` as the per-period rate, so 500 basis points on a daily schedule pays 5% of face value every day.

### Do unclaimed dividends expire?

No. The claim deadline does not stop a claim. A holder can claim after the deadline until governance reclaims the dividend. Reclaiming releases the feature's liability, closes the dividend and moves no tokens, and a holder can no longer claim it after that. In a waterfall, the unclaimed amount stays in that class's leg. Once governance has reclaimed the dividend, an account with the governance role can release the leg, which returns the amount to the wallet that funded the distribution.

### Does a template edit change issued tokens?

No. A template edit changes future issuance only. The token's own feature list lives on chain, and only governance actions on the token change it.