# Conversion features

Source: https://docs.settlemint.com/docs/concepts/modeling-assets/token-features/conversion
Reference for the conversion and conversion minter token features that turn a loan or convertible token into newly minted target tokens.

Two token features work as a pair to convert one instrument into another. The conversion feature sits on a loan or convertible token and prices each conversion. The conversion minter sits on the target token and mints the result for the conversion features it lists. Set a pair up in this order: issue the target token with the conversion minter, issue the loan token with the conversion feature pointing at that target, then add the conversion feature's address to the minter's converters. A conversion fails when the target token has no conversion minter or the minter does not list the conversion feature.

A [token feature](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features) is a module attached to one token. An account with the token's governance role attaches, detaches and configures it after issuance where the feature allows it, and each entry names any other role an action needs. The DALP Library is the catalogue of [instrument templates](https://docs.settlemint.com/docs/concepts/modeling-assets/instrument-templates) that ship with the platform, and each entry says which of them include the feature.

## Conversion [#conversion]

Turns a holder's balance of a loan or convertible token into newly minted target tokens at a price that a trigger sets. Governance publishes a trigger, the priced offer a holder converts against, such as a financing round. A trigger holds the round price per target token. The custodian can also force a conversion for a holder, without the holder's signature. The effective price is the round price less the discount, rounded down, and limited to the price cap when one is set. The converted principal, plus accrued interest when interest converts, divides by that price to give the target amount, rounded down to the target token's decimals. The loan side then reduces its exposure with the debt method, and the target token's conversion minter mints the result. The call is atomic: a failed mint reverts the principal reduction. Choose it for convertible notes, SAFEs, and warrants. The platform values the loan token one for one in the denomination asset, so a loan token worth less or more than one unit still converts at one. The DALP Library includes it on four templates: Carbon Credit, Convertible Note, SAFE, and Warrant.

[Figure] A conversion links a loan token to a target token. Governance publishes a trigger that holds a round price per target token. A holder converts loan tokens against that trigger. The conversion feature sits on the loan token. It prices the conversion, then retires the converted principal by the configured debt method: burn, lock in escrow, or mark as converted. It then calls the conversion minter on the target token, which accepts calls only from converters on its allow list. The minter mints the target tokens to the holder, once for each conversion identifier. Labels: Trigger; Published by governance:; a round price.; Holder; Converts loan tokens; against a trigger.; Conversion feature; On the loan token.; Prices and reduces debt.; Conversion minter; On the target token.; Converters on its allow list.; mints; Principal retired; Burned, locked, or; marked as converted.; Target tokens minted; To the holder, once for; each conversion id.

The conversion feature on the loan token and the conversion minter on the target token point at each other, and the minter mints only for listed converters.

All fourteen settings are fixed at issuance, except the window, which governance can change later. The Issue asset form shows the first six rows of the table, with the target token first, and an "Include accrued interest" switch for `includeInterestInConversion`. The other settings take their defaults, and you set them in the template's feature settings or through the Platform API.

| Parameter | Description |
| --- | --- |
| Target token address (`targetToken`) | The DALP asset that holders receive. It must have the conversion minter and cannot be the loan token. No asset class is required. |
| Conversion denomination asset (`denominationAsset`) | The [denomination asset](https://docs.settlemint.com/docs/concepts/modeling-assets/denomination-asset) that prices the conversion. Every trigger and any interest provider must use the same asset. |
| Conversion discount (BPS) (`discountBps`) | Discount on the trigger's round price, 0 to 9,999 basis points. The default is 0. A value of 2000 means 20%. |
| Conversion price cap (per share) (`capPricePerShareWad`) | The highest effective price for one target token, in the denomination asset, which the API takes as an 18-decimal fixed-point value. Leave it blank for no cap. It cannot change after issuance. To use a valuation cap, divide it by the fully diluted share count. |
| Conversion window start (`conversionWindowStart`) | When conversions open, as a date. Blank means open from now. |
| Conversion window end (`conversionWindowEnd`) | When conversions close. Blank means no deadline. It cannot be before the start. |
| Minimum conversion amount (`minConversionAmount`) | The smallest conversion, in loan token base units. The default is 0, which means no minimum. |
| Partial conversion allowed (`partialAllowed`) | Whether a holder can convert part of a balance. The default is false: the holder converts the whole balance. |
| Include interest in conversion (`includeInterestInConversion`) | Whether accrued interest converts with the principal. The default is false. When true, token creation also binds the conversion feature as the only consumer of the interest provider. That bind cannot be undone. |
| Interest provider (`interestProvider`) | The interest yield or fixed treasury yield feature that supplies the interest. 0 finds it automatically when exactly one is attached. |
| Close interest on conversion (`closeInterestOnConversion`) | Whether a full conversion stops the holder's interest accrual. The default is true. |
| Debt method (`debtMethod`) | How the loan side retires the principal: 0 Burn (the default), 1 Lock, or 2 MarkConverted. |
| Escrow address (`escrowAddress`) | The account that receives locked principal. Required when `debtMethod` is 1, and 0 otherwise. |
| Conversion minter (`conversionMinter`) | The conversion minter on the target token. 0, the default, finds it automatically. |

The debt method decides what happens to the loan tokens. Burn destroys the converted principal. Lock moves it to the escrow account, which then holds it. MarkConverted moves nothing: the holder keeps the loan tokens, but converted tokens can no longer be transferred or burned, and "convert all" converts only the unconverted balance. No Library template pins Lock or MarkConverted. MarkConverted also blocks attaching interest yield or fixed treasury yield later, and it rejects a partial conversion while a fixed treasury yield feature is attached.

After issuance, governance publishes and disables triggers and changes the conversion window. The window is a conversion setting, but the Platform API route that updates it is addressed with the feature name `conversion-minter`. Neither the Console nor the Platform API rotates or detaches the conversion feature, so through the platform no other term changes. On chain, the token's governance role can still replace the whole feature list, conversion included. A holder converts the holder's own balance and, when interest converts, the holder's accrued interest. A full conversion that would close accrual while convertible interest remains first needs that interest drained. The Platform API drains it in up to 10 rounds before it converts. A forced conversion skips that check. The custodian role can force a conversion. [Token conversion](https://docs.settlemint.com/docs/console/asset-management/manage/conversion) walks through publishing a round, holder and forced conversions, and what the holder sees.

A holder with 100,000 loan tokens, all with 18 decimals, converts against a trigger with a round price of 2.50. The discount is 20%, the cap is 1.80, accrued interest is 3,000, and interest converts. The discounted price is 2.00, so the cap lowers the effective price to 1.80. The value is 100,000 plus 3,000, which gives 103,000. The holder receives 103,000 divided by 1.80, which is 57,222.22 target tokens. Without the cap the holder would receive 51,500, and without interest 55,555.56.

A conversion that rounds to zero target tokens is rejected, so a decimal mismatch cannot burn principal for nothing. When rounding drops part of a target token, the conversion record keeps that fraction, and Conversion History shows it under the target tokens received. 100 notes with 18 decimals, converted at 0.72 into a target with 0 decimals, give 138 target tokens, and the row shows 0.888888888888888888 lost to rounding. Nothing pays the fraction out. The conversion feature has a second generation, the newer feature implementation that [Token features](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features) describes. It retires the principal as a booked movement, a movement the token executes outside the fee and rewrite features, so a transaction fee or an external fee on the loan token takes no part of the principal. Both generations share one configuration. The figure on this page shows how the loan and target tokens pair, and the corporate action "conversion" in [Corporate actions](https://docs.settlemint.com/docs/console/asset-management/manage/corporate-actions) runs it for a bond.

Each conversion counts once in the totals, by its conversion identifier. For the feature, the platform keeps the number of conversions, the principal converted, the interest converted and the target tokens issued. For each trigger it keeps the number of conversions and the principal converted, and for each holder it keeps the principal converted. A repeated event for a recorded conversion does not change a total.

## Conversion minter [#conversion-minter]

Sits on the target token and mints there only for the conversion features on its allow list. A call from any other address is rejected. Each conversion has a unique identifier, and the minter marks it used before it mints, so a replay fails on the loan side and on the target side. It records the recipient, the amount, the loan token, the converter, and the trigger for each issuance. Choose it on any token that other instruments convert into. The DALP Library includes it on two templates: Carbon Credit and Convertible Target Equity. Neither lists a converter.

| Parameter | Description |
| --- | --- |
| Convertible classes (`authorizedConverters`) | The conversion features that may mint here. Zero to 100 rows, each a distinct conversion feature address. The list starts empty. |

After issuance, an account with the governance role and the Supply management or admin role adds converters, because an authorised converter mints on the target token. Governance alone removes them. The Console action "Add converter" takes the conversion feature's address on the loan token. A wallet or other contract that is not a conversion feature is rejected. The second generation mints as a booked movement, so a fee on the target token takes no part of the issued tokens. Detaching the minter while a conversion is live leaves every conversion on that pair reverting. [Corporate Action](https://docs.settlemint.com/docs/concepts/issuing-and-markets/corporate-action) covers the conversion as a corporate action.