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 conceptual model, events, and constraints, see the Conversion architecture reference.

When it attaches

Convertible-note (system-convertible-note) and carbon-credit (system-carbon-credit) templates attach both conversion and conversion-minter. The Asset Designer selects the correct pair of features based on the template; you do not configure them separately.

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 form validates.
Optional mandatory conversion applies at the window end. If the operating model includes force-convert at maturity, an authorised operator triggers mandatory conversion.

Verify the deployed configuration

After the token deploys, confirm the conversion terms persisted exactly as you entered them. Open the deployed token's overview page and find the Conversion card.

The card summarises the live configuration read back from the deployed feature:

Field	What it shows
Target token	The token holders convert into.
Denomination asset	The ERC-20 used for the interest or partial-payment leg.
Discount	The conversion discount, shown as a percentage (e.g. `20.00%`).
Partial allowed	Whether holders may convert part of their position.

When the conversion-minter is attached, the card also surfaces minter activity: the number of conversion issuances completed so far and how many converter addresses are authorised on the target.

For more detail, open Configuration details on the card. The detail sheet shows the conversion-minter address, the discount in both basis points and percent (e.g. 2000 bps (20.00%)), and the minter's total issued amount. Addresses are copyable from this view. Other deployment terms such as pricing caps, the conversion window, minimum conversion amount, and interest-handling flags are set during asset creation and are not displayed on this card, so set them deliberately in the Asset Designer details step.

Confirm a deploy landed the values you intended before you announce the conversion window to holders. Two signals point to a configuration that did not persist: an empty or zero address for the target token or denomination asset, or a discount that reads 0.00% when you entered one. Do not open conversion against that token until you have confirmed the terms. A zero conversion-minter address is not itself a fault: when the minter is left to auto-discover on the target token, it is stored as a zero address by design. To inspect triggers, conversion history, and management records, select View conversion details on the card.

Submitting a conversion

The Convert form 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.

Both fields validate as the holder types, and Continue stays disabled until every check below passes:

Check	What the holder sees
Trigger ID format	A trigger ID that is not `0x` followed by 64 hex characters cannot pass this step.
Trigger ID resolves	Once the token's triggers have loaded, a well-formed ID that does not match an active, unexpired trigger shows the field error "No active trigger exists for this ID." While the triggers are still loading, the field shows no error and Continue stays disabled.
Principal Amount	The amount must be a valid number. A blank, negative, or malformed amount (for example a trailing `1.`) shows the field error "Enter a valid amount. Use 0 to convert all available principal."

Entering 0 as the Principal Amount is valid: it converts all of the holder's available principal for the matched trigger. The Your conversion balance card in the sheet shows the available principal and total converted so the holder can confirm what 0 will convert.

A trigger that has been disabled, or whose expiry has passed, does not satisfy the resolve check even when its ID is well-formed.

Once an active trigger matches and the amount is valid, the confirmation step shows the effective price for the matched trigger. For a specific non-zero amount, it also shows the estimated output for the entered principal so the holder can review the result before submitting. A convert-all request (Principal Amount 0) resolves its exact amount on-chain, so no estimated output appears for it. The on-chain conversion remains the authoritative guard: these checks stop a known-bad request before it reaches the signing step rather than letting it fail later with a generic save error.

Partial amounts when partial conversion is off

When the token's partialAllowed flag is off, holders may only convert their full available principal in a single request. The Convert flow enforces this before signing: if the holder enters a partial amount, Continue and Confirm stay disabled and the values step shows the warning "This token does not allow partial conversions. Enter 0 to convert your full available principal."

Entering 0 is always accepted and converts the holder's full available principal, so following the warning produces a request the flow will accept. The check only blocks a positive amount smaller than the full available principal; a full-amount entry passes.

This guard runs only in the platform's Convert flow as an early check. The on-chain conversion stays the authoritative backstop and rejects a partial amount on a token that disallows partial conversion, no matter how the request reaches it. The pre-signing check exists so the holder finds out at the values step instead of after signing.

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.
Partial conversion is a deploy-time choice. With it off, every conversion request must be the holder's full available principal (entered as 0); communicate this so holders do not try to convert a partial amount. See Partial amounts when partial conversion is off.
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 form will not let you continue	Confirm the Trigger ID is a 32-byte hex value matching a published trigger that is still active and unexpired. Confirm the Principal Amount is a valid number (use `0` to convert all available principal). The form shows a field error such as "No active trigger exists for this ID." or "Enter a valid amount. Use 0 to convert all available principal." next to the input that needs fixing.
Partial amount blocked with a partial-conversion warning	The token disallows partial conversion. Enter `0` to convert the holder's full available principal, or enable partial conversion at asset creation if the operating model needs it. The warning reads "This token does not allow partial conversions. Enter 0 to convert your full available principal."
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