# Composable Token

Source: https://docs.settlemint.com/docs/concepts/modeling-assets/composable-token
A composable token lets an issuer bring a new regulated instrument to market by configuring facts, features, and rules instead of writing new contract code.



[Figure] One contract model composed for many instrument shapes. An Instrument Template supplies three inputs: the instrument facts to record, the Token Features whose behaviour runs in execution order, and the compliance rules that decide who may hold the asset and what may proceed. These inputs configure one focal Composable Token contract carrying identity, roles, and per-token compliance. The same contract model then represents a bond, fund, sukuk, loan, structured note, commodity, or another shape the issuer defines. Labels: Instrument template; Instrument facts; terms to record; Token Features; behaviour, in execution order; Compliance rules; who may hold it; Composable Token; One contract model; identity, roles,; per-token compliance; Instruments; Bond; Fund; Sukuk; Loan; Structured note; Commodity; or another shape; the issuer defines.

A template selects the facts, ordered features, and rules for one contract model, which gives product coverage through composition.

A composable token is the one ERC-20-compatible asset contract the platform deploys for every instrument, with identity, role and compliance controls built in and an ordered list of token features that carry its behaviour. An issuer brings a new instrument to market by configuring it, with no new contract code, as long as the platform's features, fact fields and compliance modules cover the design.

Feature order is policy: it decides which feature sees which amount.

A feature attaches at creation or on a live asset. The generic feature lifecycle API replaces its configuration by rotating the instance.

## Why a new instrument does not need new contract code [#why-a-new-instrument-does-not-need-new-contract-code]

Building a separate smart contract for every asset type delays every new product launch. A Composable Token replaces per-type contracts with one shared regulated ERC-20 model configured with instrument facts, [Token Features](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features) and compliance rules.

An Instrument Template captures that configuration off chain so each new bond, fund, sukuk, loan, structured note or commodity reuses an approved shape on EVM networks. Configuration covers digital mechanics and policy hooks, while legal terms, regulatory classification and suitability remain issuer responsibilities.

## How composition works [#how-composition-works]

Each Composable Token deploys with the regulated token core, identity and role controls, metadata, pause and custody behaviour, and a per-token compliance contract. During deployment, the asset factory instantiates every configured feature and writes their addresses as one atomic ordered list so partial deployments cannot occur.

Every token operation executes across that ordered list in three atomic phases:

1. **Pre-check:** Every feature evaluates the requested operation unchanged, and any refusal reverts the entire operation from any position.
2. **Rewrite pipeline:** Rewriting features run in list order, each transforming the balance legs produced by the previous rewriter (each resulting leg then runs the full compliance check).
3. **Notification:** Every feature receives the original operation and the final executed legs once.

[Figure] Three phases, and only the middle one is a pipeline. One transfer enters the token's ordered feature list, which holds up to 32 entries. In the first phase every feature is asked whether the operation may proceed, about the operation exactly as requested, so a refusal reverts the whole operation from any position. In the second phase the features that rewrite run in list order as a pipeline: each rewriter receives the legs the previous one produced, plus the original operation, and each resulting leg executes through the token's full pipeline. In the last phase every feature is notified once with the original operation and the legs that executed. The run is atomic: the executed legs and their notifications land together, or nothing changes. Labels: Position decides in one phase only; Transfer requested; one operation enters an ordered list of up to 32 features; each one is asked about the operation exactly as requested; 1. Every feature is asked; a refusal reverts the whole operation, from any position in the list; 2. Rewriters run in list order; First rewriter; Next rewriter; The legs that execute; each receives the legs the one before produced, plus the original operation; told the original operation and the legs that executed; 3. Every feature notified once; Atomic: legs settled, or nothing changed.

Only the rewriting phase hands a result on, while the question before it and the notification after it reach every feature with the same inputs.

List position matters only among rewriting features, where an earlier rewriter shapes the legs seen by the next. Place [hold](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/balances-and-holds) first, followed by restrictions such as [maturity](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/income#maturity-redemption) and [conversion](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/conversion#conversion), fee collection, external fee hooks and analytics last. Restrictions cannot be outranked because any refusal reverts the entire operation, and analytics features always receive the final executed legs.

Instrument templates define composition off chain, and the Platform API validates feature dependencies and conflicts before publishing or issuing (the on-chain asset factory resolves keys from the system add-on registry without rechecking dependencies). System add-ons provide shared deployment infrastructure such as feature factories, while each deployed token feature belongs to one token.

## Issuing from the template catalogue [#issuing-from-the-template-catalogue]

Issuance starts from a published instrument template in the catalogue. System templates serve as shared baselines that cannot be edited or deleted ([DALP-14365](https://docs.settlemint.com/docs/api-reference/errors)): unpublish or hide them per organisation, or copy them into an editable organisation template.

Publishing rejects missing dependencies or conflicting feature pairs with [DALP-14094](https://docs.settlemint.com/docs/api-reference/errors) (listing offending features in `data.reason`), and creation rechecks conflicting pairs with [DALP-0605](https://docs.settlemint.com/docs/api-reference/errors). Editing a template never modifies already-issued tokens on chain, though existing assets keep their template link for catalogue naming and asset-class grouping.

## Servicing a live asset [#servicing-a-live-asset]

Live behaviour lives in attached feature contracts managed via the [token feature endpoints](https://docs.settlemint.com/docs/api-reference/v2) by an account holding governance plus either Supply management and Custodian or the admin role. Attach adds a feature, detach removes it, and rotation swaps in a newly configured instance while leaving the prior contract readable on chain.

Both attach and rotate append to the end of the feature list, so rotating a rewriter changes its execution order as well as its settings. Only an on-chain `setFeatures` call can reorder existing entries in place.

Prefer rotation over detach for configuration changes: rotation swaps instances in one write with zero hook gap, whereas detaching opens an unbackfilled window where derived state freezes and restrictions lift immediately. After reattaching, totals recomputed from live balances recover immediately while per-holder derived values catch up only when each holder next moves.

Neither the Console nor the Platform API detaches or rotates conversion or the distribution waterfall, and the API blocks detaching or rotating dividend yield while declared dividends remain unclaimed. On chain, `setFeatures` can still modify the full list.

[Figure] Two ways to change a feature, and only one opens a window. Two independent paths from Attached. A rotate deploys a new instance carrying the new configuration. It joins the end of the ordered list, the old instance stays readable on chain, and no window opens because hooks keep flowing throughout. A detach opens a window in which no hooks arrive and derived state freezes, and that gap is never backfilled. On reattach, totals recomputed from live balances are correct at once, while per-holder derived values catch up only when that holder's balance next moves. Servicing history is read against the instance that was attached at the time. Labels: One feature on one token, over time; Rotate: no window opens; Attached; hooks arrive,; derived state; stays current; rotate; Rotated; A new instance, carrying the new configuration,; joins the end of the list.; The old instance stays readable on chain.; No window opens: hooks keep flowing.; Detach: opens a window; Attached; hooks arrive,; derived state; stays current; detach; Detached window; no hooks, derived; state freezes, never; backfilled; reattach; Reattached; totals recompute at; once, holder values; catch up on next move; history reads against the instance attached at the time.

Rotating a feature keeps hooks flowing, while detaching opens a window in which no hooks arrive and derived state freezes.

Four configuration facts decide what a composable token does, and they differ in what it takes to change them.

| What you configure | What it decides | What changing it takes |
| --- | --- | --- |
| The instrument template. | Which facts the asset records, which features it must hold, and which compliance template it links. | Supplied at creation. A creation request without one is declined. |
| The order of the feature list. | The legs a transfer settles into, because the rewriting features hand their result to the next rewriter in the list. | Set as one complete ordered set at creation. Through the Platform API, attach and rotation append an instance and detach removes one. On chain, the roles that set the feature list can replace the whole list in one call. |
| How many features the token holds. | Up to 32 entries on one token. | A hard ceiling. A list longer than 32 is rejected, not truncated. |
| One feature's own configuration, such as a coupon schedule or a fee rate. | That feature's behaviour, and its position, because the replacement joins the end of the list. | Rotation, which deploys a replacement instance and retires the current one. |

## When an off-chain register decides every movement [#when-an-off-chain-register-decides-every-movement]

A feature can block every ordinary token movement. **Booked movements** (listed as "Register lines" on the **Features** tab) supports share classes whose legal register lives off chain with a transfer agent or fund administrator.

While attached, every mint, burn, transfer, forced transfer and wallet recovery outside a booked register entry is refused, while non-moving features such as dividend yield continue working. Supply management books approved movements against their register references in one transaction. Detaching the feature restores ordinary token operations.

The Share-Class Mirror template deploys one mirror token per share class with Historical balances, Hold (to reserve open requests) and Booked movements attached, requiring verified recipient identities without extra compliance policies. Unit-moving features such as Management fee, Conversion, Conversion minter, Supply delegate and Maturity redemption cannot coexist with it. See [Booked movements](https://docs.settlemint.com/docs/console/asset-management/manage/booked-movements).

## The integration contract [#the-integration-contract]

Integrate through the generic asset and feature surfaces rather than branching on fixed contract types. Creation specifies asset metadata, instrument type name, initial facts and an ordered list of feature keys and configurations. Treat the instrument type name as deployment identity and metadata, and branch client logic on the attached features discovered at runtime.

API feature listings sort alphabetically, so read execution order on chain via `getFeatures()`. Because detach and reattach create multiple historical feature instances, use the latest active instance for live operations and keep detached records for audit history.

Feature lifecycle writes are asynchronous: wait for settlement and read the deployed address from the token's feature list rather than deriving it. Attaching an existing feature fails with `already-attached` (rotate instead). See the [token feature endpoints](https://docs.settlemint.com/docs/api-reference/v2).

Design for three creation rejections: missing instrument template ([DALP-0316](https://docs.settlemint.com/docs/api-reference/errors)), unregistered token factory type ([DALP-0314](https://docs.settlemint.com/docs/api-reference/errors)), and a denomination asset lacking readable ERC-20 `symbol()` and `decimals()` ([DALP-9073](https://docs.settlemint.com/docs/api-reference/errors)).

## Controls and evidence [#controls-and-evidence]

Each composable token deploys its own compliance contract evaluating token-level and system-wide rules before balances change. Custodian forced transfers and wallet recoveries skip compliance rules while still checking recipient identity verification and passing a forced flag to attached features (so features like Booked movements can still block them). Governance configures the token's rules and compliance contract.

Templates reject draft compliance templates, unsupported module-set versions and incompatible module sets before deployment. Access managers gate supply, governance, custody and emergency roles. Because attached features execute with token-level mint, burn and transfer authority (subject to compliance), modifying the feature list requires governance plus Supply management and Custodian (or admin). A system manager can upgrade the shared asset-factory implementation across all composable tokens (`TokenImplementationUpdated`).

An auditor reads three evidence sources:

| Evidence source | What it holds | Where it lives |
| --- | --- | --- |
| The chain. | Every transaction and event from the token and its attached features. | On the network. The platform indexes it for queries. |
| The instrument template. | The approved starting configuration: instrument facts, required features, and compliance choice. | On the platform. |
| The issuer's own records. | Legal approval and classification. | Off the platform, unless an implementation explicitly stores them. |

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

### Can a standard ERC-20 wallet hold a Composable Token?

Yes. The asset contract implements the ERC-20 interface, so wallets, explorers, and existing token tooling read balances and submit transfers without any DALP-specific software. The difference is what happens after submission: every transfer runs the identity, compliance, and feature checks this page describes, so a transfer a plain ERC-20 contract would settle can revert here. The wallet must satisfy the asset's recipient identity requirements to receive tokens.

### Does the 32-entry ceiling count detached features?

No. The ceiling measures the list installed on the token at one moment, because the contract stores the ordered set in a fixed array of 32 slots. A detach frees the entry it held, and a rotation swaps one entry for its replacement, so historical instances cost no capacity. What grows over an asset's life is the population of on-chain instances, one more with every rotation, while at most one instance of each type is attached.

### Do transfer fees apply to a forced transfer or a recovery?

No. Custodian forced transfers and wallet recoveries pass a forced flag across all three pipeline phases, and fee features leave forced legs unchanged. Supply-management burns remain ordinary burns, so burn fees still apply to them.

### Does rotating or detaching a feature put balances at risk?

No units move during a lifecycle write because balances live in the token contract itself. However, detaching restrictions such as maturity redemption, Booked movements or hold lifts those rules immediately, attaching grants token-level movement authority, and detaching opens a permanent gap in derived state.

## Related concepts [#related-concepts]

- [Instrument Templates](https://docs.settlemint.com/docs/concepts/modeling-assets/instrument-templates): Reusable product shapes that bind instrument facts, required features, and a compliance choice.
- [Asset Lifecycle](https://docs.settlemint.com/docs/concepts/issuing-and-markets/asset-lifecycle): The working life a Composable Token enters once issued, from servicing through an optional retirement, on the same indexed record its creation started.
- [Asset Class](https://docs.settlemint.com/docs/concepts/modeling-assets/asset-class): The economic category, such as a bond or a fund, that groups the reusable product definitions a composable token can be configured from.
- [Denomination Asset](https://docs.settlemint.com/docs/concepts/modeling-assets/denomination-asset): The asset a payout-bearing Token Feature pays out in, resolved independently by each feature installed on a Composable Token.
- [Stablecoin](https://docs.settlemint.com/docs/concepts/modeling-assets/stablecoin): A cash-class instrument issued the same way, through an Instrument Template that configures a Composable Token.
- [EVM Contract Set](https://docs.settlemint.com/docs/platform/evm-contract-set): The identity, compliance, custody, and settlement contracts DALP deploys on EVM chains around one composable security token.