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.

Use this explanation when you review a convertible note, mandatory conversion, or loan-to-equity setup. It describes the on-chain feature model and operating controls. It does not replace the product workflow for creating the asset or the legal terms that define when a conversion is allowed.

One-view model

The loan-side feature owns trigger validation and conversion calculation. The target-side feature owns the authorised-converter allowlist, duplicate conversion-ID check, and issuance record.

Feature pair

The pair is configured 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

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.

The conversion price uses WAD precision. The loan principal is normalized from the loan token's decimals to WAD, optional interest is added in WAD, the discount and cap are applied to the trigger price, and the result is converted back to the target token's decimals.

How interest is settled on a full conversion

When a convertible carries an interest stream and the configuration converts interest and closes accrual on conversion, a full holder-initiated conversion converts the holder's accrued interest into target tokens before accrual closes. A full holder conversion never leaves accrued yield behind as claim-only cash.

Interest is settled in bounded windows. Each window covers a capped number of accrual periods, so a holder with a long backlog of accrued interest settles it across more than one step rather than in a single unbounded transaction. The settlement advances a per-holder cursor, so each step picks up where the previous one left off, repeats no work, and steps over empty leading periods for a holder who entered late.

A full holder conversion that would close accrual checks that no convertible interest remains beyond the settled window. If interest is still outstanding, the conversion reverts with UnsettledConvertibleInterest instead of closing accrual and silently rerouting the remaining yield. The holder settles the outstanding interest first, then completes the conversion.

A mandatory conversion run by a Custodian is not gated this way. The interest conversion is holder-driven, so a custodian cannot drain a holder's backlog on their behalf, and a mandatory conversion must never be blocked by one. 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 rather than converting to target tokens.

Partial conversions are unaffected: they settle only the prorated interest for the converted portion and do not drain the wider backlog.

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 rather than leaving a completed loan-side record without target tokens.

Debt reduction methods

For MarkConverted, the feature tracks total converted principal per holder and blocks transfers of already converted tokens through canUpdate. This prevents the same visible loan balance from being converted by a later recipient.

Because MarkConverted leaves the converted tokens with the holder, any interest stream computed from that balance keeps running unless it is closed. DALP refuses two MarkConverted configurations that would leave that stream open instead of closing it silently:

• 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 the conversion is rejected 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 the conversion is rejected. 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.

Both checks run before debt exposure changes, so a rejected conversion records nothing and mints no target tokens.

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 before external calls and stores the conversion record before reducing debt or minting target tokens.

The target-side Conversion Minter keeps its own used-conversion-ID map. It rejects a second mint with the same conversion ID, even if the caller is authorised. 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:

Operating responsibilities

Failure modes

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, whether an off-chain financing round closed, whether a board approval was valid, or whether the target equity economics are fair. Keep those decisions in the instrument terms, governance approval process, and off-chain evidence file.

See also

• Token conversion records API for reading conversion IDs, status, and issuance evidence
• Token conversion triggers API for listing triggers with effective pricing and auditing their published, disabled, and republished lifecycle
• Conversion API reference for the conversion request and how the endpoint settles accrued interest across requests
• Token features catalog for the broader feature model
• Asset policy for how compliance and transfer rules combine with feature behavior
• Asset contracts for role and deployment architecture
• Compliance modules for eligibility checks on target-token holders