# Conversion Source: https://docs.settlemint.com/docs/architecture/components/token-features/conversion Convertible instrument pair for DALPAsset - Conversion (loan-side) and Conversion Minter (equity-side). Manages trigger types, executes holder-initiated and forced conversions, and coordinates cross-token burns and mints. The Conversion feature pair implements convertible instruments. Conversion attaches to the convertible loan token and manages triggers and execution. Conversion Minter attaches to the equity token and mints equity when the loan-side conversion is authorized. Asset-level eligibility still comes from [asset policy](/docs/architecture/concepts/asset-policy), not from the conversion feature itself. ## Interface [#interface] This feature exposes capabilities across a cooperative two-contract pair. The Conversion feature manages triggers and executes conversions. Conversion Minter mints target tokens when authorized. **Conversion (Loan-Side):** | Capability | Who can call | Inputs | On-chain effect | Emits | Notes | | -------------------------- | ----------------- | ----------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------- | ------------------------------------ | | Publish conversion trigger | `GOVERNANCE_ROLE` | Trigger ID, price, expiry, metadata | Creates trigger definition | `TriggerPublished` | Denomination must match config | | Disable trigger | `GOVERNANCE_ROLE` | Trigger ID | Deactivates trigger | `TriggerDisabled` | Existing conversions unaffected | | Convert tokens | Token holder | Principal amount + trigger ID | Burns loan tokens; requests equity mint | `ConversionInitiated`, `ConversionFinalized` | Requires valid trigger + open window | | Force convert | `CUSTODIAN_ROLE` | Holder address, amount, trigger ID | Burns holder's loan tokens; requests equity mint | `ForcedConversion`, `ConversionInitiated`, `ConversionFinalized` | Mandatory convertibles | | Set conversion window | `GOVERNANCE_ROLE` | Start + end timestamps | Updates when conversions are allowed | `ConversionWindowUpdated` | - | **Conversion Minter (Equity-Side):** | Capability | Who can call | Inputs | On-chain effect | Emits | Notes | | -------------------- | -------------------- | -------------------------------- | -------------------------------- | ---------------------------- | --------------------------------- | | Authorize converter | `GOVERNANCE_ROLE` | Converter contract address | Adds to minter allowlist | `ConverterAuthorized` | Required during deployment | | Remove converter | `GOVERNANCE_ROLE` | Converter contract address | Removes from minter allowlist | `ConverterDeauthorized` | Audit allowlist post-deployment | | Mint from conversion | Authorized converter | Recipient, amount, conversion ID | Mints equity tokens to recipient | `TargetIssuedFromConversion` | Replay-protected by conversion ID | Trigger details, conversion records, available principal, and authorization status are available as read-only queries on their respective contracts. *** ## Business impact [#business-impact] * **Holders (loan token):** Can convert their loan token balance to equity tokens when a valid trigger condition is met. Token balance is the source of truth for convertible principal - no separate position registration. * **Holders (equity):** Equity supply increases as loan tokens are converted. Existing equity holders are diluted proportionally. * **Issuer:** Sets conversion triggers (price thresholds, discount rates, conversion caps, time windows). Can force conversion for mandatory convertibles via `CUSTODIAN_ROLE`. * **Economics:** Loan tokens are burned on conversion; equity tokens are minted by the Conversion Minter. Two-contract cooperative pair - both must be configured correctly. *** ## Risks & abuse cases [#risks--abuse-cases] * **Deployment sequence error:** Incorrect deployment order (e.g., deploying the loan token before authorizing the Conversion Minter) will leave the conversion feature unable to mint equity. The entire conversion mechanism fails silently or reverts. * **Conversion Minter allowlist not locked:** If `addAuthorizedConverter()` is called but the allowlist is not reviewed post-deployment, unauthorized addresses added later could trigger unauthorized equity mints. * **`forceConvert()` misuse:** CUSTODIAN\_ROLE can force conversion for mandatory convertibles. Without documented governance controls, this action can be executed without holder consent. * **Trigger front-running:** Price-based triggers observable on-chain can be front-run. Conversion window triggers with defined open/close dates are more predictable. *** ## Deployment sequence [#deployment-sequence] Incorrect deployment order will break the authorization chain. Follow this exact sequence: 1. Deploy the equity token with Conversion Minter attached. 2. Deploy the loan token with Conversion attached and configured with the equity token address. 3. Authorize the loan-side Conversion feature contract on the Conversion Minter. This sequence ensures the equity token exists before the loan token references it, and the Conversion Minter's allowlist is populated before any conversion can be triggered. ## Asset Designer configuration [#asset-designer-configuration] When a template exposes any Conversion field, Asset Designer requires the two address inputs that the token-creation schema needs: | Field | Required when | Notes | | ------------------ | ------------------------------- | ---------------------------------------------------------------------------------------------------- | | Target token | Any Conversion field is present | Equity or share token received after conversion. | | Denomination asset | Any Conversion field is present | Unit-of-account token used for conversion pricing. | | Discount | Discount field is present | Integer basis points only. The value can be `0` through `9999`, so `2000` represents a 20% discount. | The form validates these fields before submission. A discount with decimals or a value of `10000` basis points is rejected because the conversion price must remain above zero. *** ## Controls & guardrails [#controls--guardrails] | Contract | Role | Actions | Recommended guardrail | | -------------------------- | ----------------- | --------------------------------------------------------------- | ---------------------------------------------------------------- | | Conversion (Loan) | `GOVERNANCE_ROLE` | `publishTrigger()`, `disableTrigger()`, `setConversionWindow()` | Review all trigger parameters before publishing; test on testnet | | Conversion (Loan) | `CUSTODIAN_ROLE` | `forceConvert()` - mandatory conversion at maturity | Document governance process; require multi-sig approval | | Conversion Minter (Equity) | `GOVERNANCE_ROLE` | `addAuthorizedConverter()`, `removeAuthorizedConverter()` | Audit allowlist post-deployment; remove test addresses | *** ## Failure modes & edge cases [#failure-modes--edge-cases] * **Trigger not met:** Conversion attempts when no trigger condition is active revert. Holders must wait for a valid trigger window. * **Conversion Minter not authorized:** If the loan-side Conversion feature is not on the Conversion Minter's allowlist, all conversion attempts revert. Verify authorization as part of deployment verification. * **Equity supply cap:** If the equity token has a supply cap (via compliance module), conversions that would exceed the cap revert. Ensure the cap accounts for the full potential loan conversion volume. * **Replay protection:** Each conversion event carries a replay protection nonce. The same conversion request cannot be submitted twice. *** ## Auditability & operational signals [#auditability--operational-signals] **Conversion (Loan-Side):** * `ConversionInitiated(conversionId, holder, triggerId, loanAmount)` / `ConversionFinalized(conversionId, holder, equityAmount)` - emitted per successful conversion. * `ForcedConversion(holder, loanAmount, triggeredBy)` - emitted when CUSTODIAN\_ROLE forces conversion. * `TriggerPublished(triggerId, type, parameters)` / `TriggerDisabled(triggerId)` - emitted on trigger lifecycle changes. **Conversion Minter (Equity-Side):** * `ConverterAuthorized(converterAddress)` / `ConverterDeauthorized(converterAddress)` - emitted on allowlist changes. * `TargetIssuedFromConversion(conversionId, recipient, amount, sourceLoanToken, triggerId)` - emitted per conversion mint. Primary provenance signal. * `ConversionWindowUpdated(start, end)` - emitted when the conversion window is changed. Alert on mid-lifecycle window changes. *** ## Dependencies [#dependencies] * **Two DALPAsset tokens** - one for the loan instrument, one for the equity instrument. Both must be deployed before configuration. * **Deployment coordination** - the three-step deployment sequence (above) is a hard dependency. * No external ERC-20 required for the conversion mechanism itself. *** ## Compatibility & ordering notes [#compatibility--ordering-notes] **Conversion (Loan-Side):** * `supportsRewriting = false` - uses `canUpdate()` to restrict transfer of already-converted loan tokens (MarkConverted debt method). The four lifecycle hooks (`onMinted`, `onBurned`, `onTransferred`, `onRedeemed`) are no-ops for this feature. * **Order first** in the loan token's feature array (transfer restriction behavior). **Conversion Minter (Equity-Side):** * No hooks - order in the equity token's feature array is irrelevant. Compatible with compliance modules on both tokens - compliance runs before features; a holder must pass compliance to receive converted equity tokens. *** ## Change impact [#change-impact] * **Enable at deployment:** Both features must be configured at deployment. Adding them post-deployment requires the full three-step authorization sequence. * **Disable Conversion (Loan):** Pending conversions in-flight may be affected. Existing trigger definitions become inactive. Loan tokens are no longer convertible. * **Disable Conversion Minter (Equity):** Equity can no longer be minted for conversions. All in-flight and future conversion attempts on the loan side will revert. * **Remove authorized converter:** Immediately prevents future conversion-triggered mints. Any in-progress conversions that have not yet minted equity will revert. *** ## See also [#see-also] * [Token Features Catalog](/docs/architecture/components/token-features) - return to the full feature catalog * [Asset Contracts](/docs/architecture/components/asset-contracts) - deployment architecture and role model * [Compliance Modules](/docs/architecture/security/compliance) - compliance checks on conversion recipients