# Conversion Source: https://docs.settlemint.com/docs/architects/components/token-features/conversion How DALP models convertible instruments with a loan-side Conversion feature and target-side Conversion Minter feature, including how accrued interest settles on a full conversion. The Conversion feature models a convertible instrument as two cooperating token features. The loan token holds the convertible principal, publishes conversion triggers, calculates the target amount, and reduces the holder's loan exposure. The target token uses Conversion Minter to mint the equity or share token only when an authorised loan-side converter calls it with a unique conversion ID. Read this page when you review a convertible note, mandatory conversion, or loan-to-equity setup. It describes the on-chain feature model and operating controls, not the product workflow for creating the asset or the legal terms that govern when conversion is permitted. The two-feature pair described here is the unit of audit: start with the loan-side Conversion feature and the target-side Conversion Minter. ## One-view model [#one-view-model] The loan-side feature owns trigger validation and the target-amount calculation. The target-side Conversion Minter owns the authorised-converter allowlist, the duplicate conversion-ID check, and the issuance record. Begin an audit from these two features. ## Feature pair [#feature-pair] | Feature | Attached to | Main responsibility | Key control | | ----------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | Conversion | Convertible loan token | Publish triggers, validate conversion windows, calculate target output, reduce loan exposure, and call the target-side minter | `GOVERNANCE_ROLE` manages triggers and windows; `CUSTODIAN_ROLE` can force mandatory conversions | | Conversion Minter | Target equity or share token | Mint target tokens from authorised conversion calls and record issuance provenance | `GOVERNANCE_ROLE` manages the authorised converter list | Governance configures the pair at deployment. The loan-side feature references the target token and can use an explicit Conversion Minter address or discover the target-side minter feature from the target token. The target-side feature accepts mint calls only from authorised converter feature contracts. ## What a conversion checks [#what-a-conversion-checks] A holder-initiated conversion calls `convert`. A mandatory conversion calls `forceConvert`, which requires the Custodian role. Both paths share the same validation and execution model. | Check | What DALP verifies | Failure result | | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | Trigger exists | Governance published the trigger and has not disabled it | Conversion reverts | | Trigger timing | The trigger has not expired, and the conversion window is open when configured | Conversion reverts | | Denomination | The trigger denomination matches the conversion configuration | Conversion reverts | | Principal | The holder has enough loan-token balance or unconverted balance for the selected debt method | Conversion reverts | | Partial conversion policy | The configuration permits a partial amount | Conversion reverts | | Minimum amount | The principal meets the configured minimum conversion amount | Conversion reverts | | Interest provider | When the configuration includes interest, a provider exists and uses the same denomination | Conversion reverts | | Interest provider clarity | For a full Mark converted with interest closing on and no explicit provider, discovery resolves to exactly one provider | Conversion reverts | | Convertible interest settled | For a full holder conversion that closes interest accrual, no accrued convertible interest remains beyond the settled window | Conversion reverts with `UnsettledConvertibleInterest` | | Target output | The effective price produces a non-zero target amount | Conversion reverts | | Conversion minter | The target-side minter exists and authorises the loan-side converter | Conversion reverts | The conversion price uses WAD precision. The platform normalizes the loan principal from the loan token's decimals to WAD, adds optional interest in WAD, applies the discount and cap to the trigger price, and converts the result back to the target token's decimals. ## How interest settles on a full conversion [#how-interest-settles-on-a-full-conversion] For a convertible with an interest stream configured to close accrual on conversion, a full holder-initiated conversion converts the holder's accrued interest into target tokens ahead of closing accrual. A full holder conversion never leaves accrued yield behind as claim-only cash. Interest settles in bounded windows. Each window covers a capped number of accrual periods, so a holder with a long backlog settles it across more than one step. The settlement advances a per-holder cursor. Each step picks up where the previous one left off, repeats no work, and skips empty leading periods for a holder who entered late. To close accrual, a full holder conversion first checks that no convertible interest remains beyond the settled window. If interest is still outstanding, the conversion reverts with `UnsettledConvertibleInterest`. The holder settles the outstanding interest first, then completes the conversion. When you build a conversion UI, surface this revert reason so the holder knows to settle interest first. Custodian-run mandatory conversions skip this check, because interest settlement is holder-driven. A forced full conversion settles the first interest window to target tokens, then closes accrual. Any interest beyond that window stays recoverable by the holder as cash. Partial conversions work differently: they settle only the prorated interest for the converted portion and do not drain the wider backlog. ## Execution flow [#execution-flow] 1. Governance publishes a trigger with a trigger ID, denomination asset, round price per share in WAD, optional expiry, and metadata hash. 2. The holder calls `convert`, or a Custodian role holder calls `forceConvert` for a mandatory conversion. 3. DALP validates the trigger, conversion window, amount, partial-conversion policy, interest-provider configuration, and target output. For a full holder conversion that closes interest accrual, DALP also confirms no convertible interest remains unsettled beyond the settled window. 4. DALP creates a conversion record with status `Initiated` and a unique conversion ID. 5. DALP reduces loan exposure according to the configured debt method, and on a full holder conversion converts the holder's accrued interest to target tokens before accrual closes. 6. DALP asks the target-side Conversion Minter to mint the target token amount. 7. Conversion Minter rejects unauthorised converter calls and duplicate conversion IDs, records the issuance, and mints the target tokens. 8. The loan-side record moves to `Minted`, and the conversion emits lifecycle events. The target-side mint is part of the conversion transaction. If the target-side mint fails, the conversion reverts. You will never see a completed loan-side record without corresponding target tokens. ## Debt reduction methods [#debt-reduction-methods] | Method | What happens to the loan exposure | Operational meaning | | ------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | Burn | DALP burns the loan tokens during conversion | Use when converted principal should leave supply | | Lock | DALP transfers the loan tokens to the configured escrow address | Use when the instrument keeps converted principal in escrow evidence | | MarkConverted | DALP records the holder's converted amount without moving the tokens | Use when the token balance remains visible but converted portions must not move or convert again | For `MarkConverted`, the feature tracks total converted principal per holder and blocks transfers of already converted tokens through `canUpdate`. This prevents a later recipient from converting the same visible loan balance. Because `MarkConverted` leaves the converted tokens with the holder, any interest stream computed from that balance keeps running until governance closes it. DALP refuses two `MarkConverted` configurations that would leave that stream open instead of closing it cleanly: * A full conversion configured to close interest on conversion, with no explicit interest provider set, where automatic discovery finds two or more interest providers. The provider to close is ambiguous, so DALP rejects the conversion before any state change. Configure an explicit interest provider so the conversion knows which accrual to close. * A partial conversion with a forward-coupon yield provider attached. Closing accrual cannot express a proportional reduction for a partial amount, so DALP rejects the conversion. This applies whenever such a provider is attached, regardless of the interest-closing setting. Convert the full available principal, or use a debt method that moves the tokens. If you are unsure which method fits, consult your instrument terms. Both checks run prior to debt exposure changes, so a rejected conversion records nothing and mints no target tokens. ## Replay protection and provenance [#replay-protection-and-provenance] The loan-side feature generates a conversion ID from the source token, target token, holder, trigger ID, and an internal nonce. It marks the ID as used ahead of external calls and stores the conversion record prior to reducing debt or minting target tokens. Store this ID in your system to link the on-chain event to your business instruction. The target-side Conversion Minter keeps its own used-conversion-ID map. It rejects a second mint with the same conversion ID, even when the caller holds a valid authorisation. It also stores an issuance record with the conversion ID, recipient, amount minted, source loan token, source converter feature, trigger ID, and timestamp. Use these records together: | Evidence | Where it comes from | What it proves | | ---------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `ConversionInitiated` | Loan-side feature | DALP accepted a conversion for a holder, trigger, principal amount, interest amount, target amount, and effective price | | `TargetIssuedFromConversion` | Target-side minter | The target token minted a specific amount for a specific conversion ID | | `ConversionFinalized` | Loan-side feature | The target mint completed and the conversion record reached `Minted` | | `InterestConverted` | Interest provider | The platform converted a bounded window of accrued interest to target tokens, with the per-period amounts and the window the settlement cursor advanced over | | Issuance record | Target-side minter view | The target-side provenance for a conversion ID | | Conversion record | Loan-side feature view | The loan-side status, amounts, effective price, and target token | ## Operating responsibilities [#operating-responsibilities] | Owner | Responsibility | | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | Issuer or governance operator | Publish accurate trigger terms, disable incorrect triggers, configure conversion windows, and manage the target-side authorised converter list | | Custodian operator | Use `forceConvert` only when the instrument terms allow mandatory conversion | | Asset operations | Verify the loan token, target token, denomination asset, conversion minter address, and authorised converter list before allowing conversions | | Compliance reviewer | Confirm that holder eligibility, transfer restrictions, and target-token compliance rules match the instrument design | | Integration or reconciliation owner | Store conversion IDs, transaction hashes, events, and loan-side and target-side records with the business instruction | ## Failure modes [#failure-modes] | Situation | What happens | How to recover | | --------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | Trigger is missing, inactive, expired, or uses the wrong denomination | Conversion reverts before debt exposure changes | Publish a valid trigger or use the correct trigger ID | | Conversion window is not open | Conversion reverts | Wait for the configured window or update the window with Governance role | | Holder lacks available principal | Conversion reverts | Reconcile the holder's loan-token balance or already converted amount | | Partial conversion is disabled | Conversion reverts for amounts below the full available principal | Convert the full available principal or use an instrument configuration that allows partial conversion | | Interest provider is missing or uses the wrong denomination | Conversion reverts when interest is configured for inclusion | Configure the correct provider before conversion | | Mark converted full conversion finds two or more interest providers | Conversion reverts before debt exposure changes | Configure an explicit interest provider so the conversion can close the right accrual | | Mark converted partial conversion has a forward-coupon yield provider | Conversion reverts before debt exposure changes | Convert the full available principal, or use a debt method that moves the tokens | | Full holder conversion still has unsettled convertible interest | Conversion reverts with `UnsettledConvertibleInterest` before accrual closes | Settle the outstanding interest to target tokens first, then complete the full conversion | | Conversion Minter is missing or does not authorise the converter | Conversion reverts | Attach or configure the target-side minter and authorise the loan-side converter | | Conversion ID was already used on the target side | Target mint reverts | Reconcile the existing conversion instead of replaying the mint | ## What this feature does not decide [#what-this-feature-does-not-decide] Conversion enforces the configured on-chain terms. It does not decide whether the issuer had legal authority to convert. It does not verify that an off-chain financing round closed, that a board approval was valid, or that the target equity economics are fair. Keep those decisions in your instrument terms, your governance approval process, and your off-chain evidence file. ## See also [#see-also] * [Token conversion records API](/docs/api-reference/tokens/token-conversion-records) for reading conversion IDs, status, and issuance evidence * [Token conversion triggers API](/docs/api-reference/tokens/token-conversion-triggers) for listing triggers with effective pricing and auditing their published, disabled, and republished lifecycle * [Conversion API reference](/docs/api-reference/token-features/conversion) for the conversion request and how the endpoint settles accrued interest across requests * [Token features catalog](/docs/architects/components/token-features) for the broader feature model * [Asset policy](/docs/architecture/concepts/asset-policy) for how compliance and transfer rules combine with feature behavior * [Asset contracts](/docs/architects/components/asset-contracts) for role and deployment architecture * [Compliance modules](/docs/compliance-security/compliance) for eligibility checks on target-token holders