Conversion feature for convertible-instrument exchange

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.

When you enter the conversion target token in the details step, the wizard checks that address against the tokens deployed on the platform before it lets you continue. If the address is not an existing platform token, the field shows an error naming the conversion target, and the Next button stays disabled until you correct it. This catches a well-formed but undeployed address at the wizard step instead of letting it fail later at deployment. The check also runs when you resume a saved draft, so a restored target that no longer resolves to a deployed token blocks the step too.

The Review and deploy step shows the conversion target, denomination asset, and discount back to you on the summary, so you can confirm them one last time before submitting the transaction.

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. See Submitting a conversion for the trigger and principal inputs the Convert action validates.
Optional mandatory conversion at the window end. If the operating model includes force-convert at maturity, an authorised operator triggers the mandatory-conversion action.

Submitting a conversion

The Convert action collects two inputs before it lets a holder confirm:

Field	What to enter
Trigger ID	The 32-byte (`bytes32`) identifier of the published conversion trigger to convert against.
Principal Amount	The amount of principal to convert.

The action validates both inputs before it advances:

Continue stays disabled until the Trigger ID is a well-formed 32-byte hex value and the Principal Amount is non-empty. A malformed trigger ID (anything that is not 0x followed by 64 hex characters) cannot pass this step.
Confirm Conversion stays disabled until the entered Trigger ID matches an active, unexpired trigger on the token. If no matching active trigger is found, the action shows "No active trigger found for this ID." so the disabled state is explained. A trigger that has been disabled, or whose expiry has passed, does not satisfy this check even when its ID is well-formed.

Once an active trigger matches, the confirmation step previews the effective price and the estimated output for the entered principal, so the holder can review the result before submitting. The on-chain conversion remains the authoritative guard: these checks stop a known-bad request before it is submitted rather than letting it fail later on-chain.

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 target rejected as not an existing token	Confirm the conversion target token is deployed on the platform and you entered its address. The wizard blocks the step until the target resolves to a live platform token.
Conversion rejected as outside window	Confirm the conversion window is open and the holder's request reaches the platform during the window.
Convert action will not let you confirm	Confirm the Trigger ID is a 32-byte hex value and matches a published trigger that is still active and unexpired. The action shows "No active trigger found for this ID." when no active trigger matches.
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.

Conversion