Convert
What “convert” means on EDMA
Convert transforms already-minted, PoV-backed assets into a new, functionally equivalent form—without creating new value or moving cash. You use it to aggregate, split, or wrap assets (for example, hourly attributes → 1 MWh; 1 MWh → 10×0.1 MWh; Energy token → program-specific wrapper; Energy-side evidence → Carbon unit when allowed). Convert never triggers a protocol fee or an EDM burn; those happen at Settle/Release. Lineage stays append-only, and One-Claim prevents double use across routes. Short rule: Convert changes the shape, not the substance.
A. What you can convert
Aggregate: Combine many small, PoV-minted units into a larger standard unit. Example: 12 × 0.0833 MWh hourly attributes → 1 MWh Energy token.
Split: Break one unit into multiple smaller, fungible units (where the standard allows). Example: 1 MWh → 10 × 0.1 MWh (ERC-1155 quantity).
Wrap / Mirror: Produce a program-specific representation, linked to an external registry serial or method. Example: Energy token → compliance wrapper (mirror record with registry serial).
Methodology conversion (policy-gated): Transform Energy-side evidence into Carbon units if the methodology explicitly permits it. Example: Energy token → 1 tCO₂e Carbon token (consumes energy lineage).
Governance defines which categories are convertible per lane and method. If a route forbids a pathway, the Gate refuses the conversion.
B. Inputs & checks
Conversions are tightly controlled and always follow the same structure:
Parent token(s): IDs and quantities you intend to convert.
Target form: Category (Energy/Carbon/Attribute), unit size, or wrapper schema (program id / registry serial / methodology).
Optional: External registry proof (for wrappers), rounding policy (where allowed).
Ownership & status: Parent tokens must belong to caller, be PoV-valid, and not be frozen or already consumed.
Conservation: The sum of children equals the sum of parents, within permitted rounding rules (if any).
Route policy: Conversion is permitted for the source/target categories and method/region.
Uniqueness: Children receive derived claim ids bound to the parents’ claim_id/pov_hash; parents are consumed/locked so they cannot be reused.
External mirror (if any): Registry attestation present; mirror link recorded.
No protocol fee or burn: No protocol fee is computed, and no burn is attempted.
C. Flow
All steps occur in one transaction; partial state cannot leak. The flow is always:
Validate inputs and route policy; compute the set of child specs.
Reserve child claim ids derived from the parents (One-Claim for conversion lineage).
Mint child(ren) with pov_hash, claim_id, metadata (method/region/vintage or program wrapper), and lineage pointer(s) to parent(s).
Mark parents as CONVERTED/CONSUMED (non-transferable, non-listable).
Emit TokenConverted with parent ids, child ids, conservation summary.
D. What convert does not do
No cash movement: Does not flip Locked EDSD → Unlocked EDSD (no money moves).
No protocol fee or burn: Does not charge a protocol fee or burn EDM.
No tradability guarantee: Does not make assets tradable if the target is a mirror (wrapper may be non-transferable if the external program requires it).
No weakening of One-Claim: Parents are consumed, children carry lineage.
E. Events, API, and webhooks
Event: TokenConverted { parent_ids[], child_ids[], conservation_check, lineage[] }
API: POST /v1/tokens/convert Body: { parents: [{id, qty}], target: {category, unit_size|schema, program_ref?}, options: {rounding?, metadata?} } Returns: { children: [{id, qty}], lineage, receipt_uri }
Webhooks: tokens.converted — includes parents, children, conservation summary, lineage links.
Explorer lineage: The Explorer shows parent → child lineage on both token pages.
F. Invariants
Conservation: Σ(parent_qty) = Σ(child_qty) (exact or within governed rounding rules; remainder explicitly discarded or carried).
Uniqueness: Parents become CONVERTED/CONSUMED; children derive new claim ids tied to the same dossier lineage; One-Claim blocks re-use anywhere on EDMA.
Idempotency: Same request (same parent set + target spec) replays to no-op after the first success.
Append-only: Replacements (after revocation) mint new children with replaces: old_claim_id; history is never erased.
G. Edge cases & policy notes
Rounding: If a standard forbids fractional units, governance must define how to handle remainder; the receipt shows the treatment.
Program wrapper revoked: A mirror can be invalidated by the external registry; the token is frozen; a corrective conversion or replacement links to the new serial.
Cross-route locks: If policy forbids Energy→Carbon after Energy sale, the conversion fails (E_CONVERSION_POLICY_FORBIDDEN).
Multi-parent merge: Allowed when children aggregate; lineage stores all consumed parents.
H. Operator checklist
Parent selection: Pick the smallest set of parents that equals the target size; avoid avoidable rounding.
Route/method check: Ensure route/method permits the conversion; check the policy hint in the UI/API before submitting.
Registry proof: If you’re wrapping to a program, attach the registry proof; the mirror serial appears on the child.
Post-conversion listing: After conversion, list children, not parents; parents show Converted and won’t trade.
Plain recap
Last updated