Conversion

Purpose: The Conversion feature pair implements convertible instruments. Conversion (Loan-Side) attaches to the convertible loan token and manages triggers and execution. Conversion Minter (Equity-Side) attaches to the equity token and mints equity when authorized by the loan-side conversion.

• Doc type: Reference
• What you'll find here: Business impact, risks, deployment sequence, controls, failure modes, auditability, dependencies, and ordering notes
• Related:
  • Token Features Catalog
  • Asset Contracts
  • Compliance Modules

---

Interface (capabilities)

This feature exposes capabilities across a cooperative two-contract pair. The Conversion feature (loan-side) manages triggers and executes conversions. The Conversion Minter (equity-side) mints target tokens when authorized.

Conversion (Loan-Side):

Conversion Minter (Equity-Side):

Trigger details, conversion records, available principal, and authorization status are available as read-only queries on their respective contracts.

---

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

• 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 (critical)

Incorrect deployment order will break the authorization chain. Follow this exact sequence:

1. Deploy equity token (target) with Conversion Minter feature attached
2. Deploy loan token (source) with Conversion feature attached, configured with equity token address
3. Call addAuthorizedConverter() on the Conversion Minter, authorizing the loan-side Conversion feature contract address

This sequence ensures the equity token is deployed before the loan token references it, and the Conversion Minter's allowlist is populated before any conversion can be triggered.

---

Controls & guardrails

---

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

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

• 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

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

• 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

• Token Features Catalog — return to the full feature catalog
• Asset Contracts — deployment architecture and role model
• Compliance Modules — compliance checks on conversion recipients