Conversion
How DALP models convertible instruments with a loan-side Conversion feature and target-side Conversion Minter feature.
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
| 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 |
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.
| Check | What DALP verifies | Failure result |
|---|---|---|
| Trigger exists | The trigger was published and has not been disabled | 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 | A partial amount is allowed only when the configuration permits it | Conversion reverts |
| Minimum amount | The principal meets the configured minimum conversion amount | Conversion reverts |
| Interest provider | If interest is included, a provider exists and uses the same denomination | Conversion reverts |
| 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 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.
Execution flow
- Governance publishes a trigger with a trigger ID, denomination asset, round price per share in WAD, optional expiry, and metadata hash.
- The holder calls
convert, or a Custodian role holder callsforceConvertfor a mandatory conversion. - DALP validates the trigger, conversion window, amount, partial-conversion policy, interest-provider configuration, and target output.
- DALP creates a conversion record with status
Initiatedand a unique conversion ID. - DALP reduces loan exposure according to the configured debt method.
- DALP asks the target-side Conversion Minter to mint the target token amount.
- Conversion Minter rejects unauthorised converter calls and duplicate conversion IDs, records the issuance, and mints the target tokens.
- 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
| Method | What happens to the loan exposure | Operational meaning |
|---|---|---|
| Burn | The loan tokens are burned during conversion | Use when converted principal should leave supply |
| Lock | The loan tokens are transferred to the configured escrow address | Use when the instrument keeps converted principal in escrow evidence |
| MarkConverted | The holder's converted amount is recorded without moving the tokens | Use when the token balance remains visible but converted portions must not be transferred or converted again |
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.
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:
| Evidence | Where it comes from | What it proves |
|---|---|---|
ConversionInitiated | Loan-side feature | A conversion was accepted 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 |
| 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
| 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
| 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 |
| 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
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 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
Fixed Treasury Yield
Fixed-rate yield paid to token holders at periodic intervals from a treasury. Holders claim completed-period yield, and Historical Balances supplies the snapshot data used for entitlement calculation.
Overview
Capabilities are optional system addons for asset operations. They add focused workflows for token distribution, treasury control, settlement, primary sales, and issuer-signed market data without putting every workflow into an asset contract.