Conversion
How operators configure the conversion token feature for convertible instruments that exchange holdings into a target equity or settlement token.
The conversion token feature handles instruments that exchange their holdings into a target token at a configured rate, discount, or window. Use it for convertible notes that convert into equity, carbon credits that retire into a retirement token, or any composable instrument where the lifecycle ends in conversion rather than redemption.
Conversion always pairs with conversion-minter. The minter feature handles the target-side minting that mirrors the source-side burn during conversion.
For the architecture reference, see Conversion.
When it attaches
Convertible-note (system-convertible-note) and carbon-credit (system-carbon-credit) templates attach conversion + conversion-minter.
What you configure
In the Asset Designer details step, the wizard surfaces:
| Parameter | Description |
|---|---|
targetToken | The token holders convert into. Must be an equity-class token for convertible notes, or a retirement token for carbon credits. |
conversionMinter | Address of the conversion-minter on the target token. The Designer wires this automatically if both features attach during the same flow. |
denominationAsset | ERC-20 used for any interest or partial-payment leg. |
discountBps | Conversion discount in basis points (e.g. 2000 for 20% discount). |
capPricePerShareWad | Optional cap on the conversion price. |
conversionWindowStart | When conversion becomes available. |
conversionWindowEnd | When conversion stops being available. After this, mandatory conversion may force-convert remaining holdings. |
minConversionAmount | Minimum amount per conversion request. |
partialAllowed | Whether partial conversion is allowed. |
includeInterestInConversion | Whether accrued interest converts with the principal. |
closeInterestOnConversion | Whether interest accrual closes after conversion. |
The target-token prerequisite is checked during template selection: if no compatible equity-class (or retirement) target exists, the template card is disabled.
What you operate
After deployment:
- Communicate the conversion window to holders. Conversion is window-bound; outside the window, holders cannot voluntarily convert.
- Holders submit conversion through the platform's conversion flow during the window. The feature burns the source holding and the conversion-minter mints the target.
- Optional mandatory conversion at the window end. If the operating model includes force-convert at maturity, an authorised operator triggers the mandatory-conversion action.
Operating considerations
- Conversion always pairs with conversion-minter. The Asset Designer enforces this composition rule.
- Target-token authority must include the conversion-minter as a permitted minter on the target. The Designer wires this when both assets are managed by the same operating team; cross-organisation conversions require manual minter approval on the target.
- Conversion-window dates are restricted-mutable. Plan changes around the window boundaries.
- Discount and cap interact: a 20% discount with no cap can produce a different conversion ratio than 20% discount with a cap, depending on the target token's price at conversion time.
Troubleshooting
| What you see | What to check |
|---|---|
| Conversion rejected as outside window | Confirm the conversion window is open and the holder's request reaches the platform during the window. |
| Conversion fails with minter error | Confirm the conversion-minter on the target token authorises this conversion contract. |
| Holder receives unexpected target amount | Confirm the discount, cap, and target-token price feed are configured correctly. Conversion math runs against the prices recorded at the conversion block. |
Read next
- Conversion architecture
- Conversion minter — required companion feature.
- System templates catalog
External transaction fee
How operators configure the external-transaction-fee token feature to charge fixed fees in a separate ERC-20 asset for mint, burn, and transfer operations.
Conversion minter
How the conversion-minter token feature mints target-side tokens during a conversion exchange, paired with the conversion feature on the source asset.