Skip to content

Proposal: org.accordproject.money@1.0.0 β€” remove DigitalCurrencyCode, support non-decimal denominations, fixed-point representationΒ #186

Closed

Description

@mttrbrts

Feature Request πŸ›οΈ

Propose a stable 1.0.0 release of org.accordproject.money, addressing three long-standing concerns: removal of digital currency types, correct handling of non-decimal currency denominations, and an optional precision-safe fixed-point representation.

Opening this for community discussion before any code changes land.

Use Case

The current model (org.accordproject.money@0.3.0) has a few limitations that surface in real contracts:

  1. DigitalMonetaryAmount / DigitalCurrencyCode mix cryptocurrency concerns into the core money model. These belong in a separate, specialised namespace.
  2. Double doubleValue is ambiguous across currencies with different minor-unit conventions β€” JPY (0 decimals), USD (2 decimals), KWD (3 decimals) all share the same field type but require different interpretation.
  3. No precision-safe option exists for contracts that need exact arithmetic (banking, settlement, regulated financial reporting). Floating-point rounding errors are unsuitable for these domains.
  4. CurrencyCode enum should be refreshed against the latest ISO 4217 active list (e.g., VES for the Venezuelan BolΓ­var Soberano).

Possible Solution

A dual-representation v1.0.0 model that:

  • Removes DigitalMonetaryAmount and DigitalCurrencyCode
  • Keeps MonetaryAmount (with doubleValue + currencyCode) backwards-compatible with v0.3.0
  • Adds FixedPointMonetaryAmount for precision-safe arithmetic
  • Annotates each CurrencyCode enum value with a @DecimalPlaces decorator carrying its ISO 4217 minor-unit count
  • Refreshes CurrencyCode against ISO 4217 as of 2026

Draft money@1.0.0.cto

concerto version "^3.0.0"

namespace org.accordproject.money@1.0.0

/**
 * Declares the @DecimalPlaces decorator.
 * Carries the ISO 4217 minor-unit count for each currency.
 */
declaration DecimalPlaces {
  o Integer value range=[0,4]
}

/**
 * ISO 4217 currency codes (active codes as of 2026), each annotated
 * with its standard minor-unit count via @DecimalPlaces.
 *
 *   0 decimals: BIF, CLP, DJF, GNF, ISK, JPY, KMF, KRW, PYG, RWF,
 *               UGX, VND, VUV, XAF, XOF, XPF
 *   2 decimals: most currencies (USD, EUR, GBP, AUD, CAD, …)
 *   3 decimals: BHD, BOV, COU, IQD, JOD, KWD, LYD, OMR, TND, UYI,
 *               XAU, XAG, XPT, XPD, XBA, XBB, XBC, XBD
 */
enum CurrencyCode {
  @DecimalPlaces(2) o AED
  @DecimalPlaces(2) o AFN
  // ... full ISO 4217 list ...
  @DecimalPlaces(3) o BHD
  @DecimalPlaces(0) o BIF
  // ...
  @DecimalPlaces(0) o JPY
  // ...
  @DecimalPlaces(3) o KWD
  // ...
  @DecimalPlaces(2) o USD
  // ...
  @DecimalPlaces(2) o VES   // NEW: Venezuelan BolΓ­var Soberano
  @DecimalPlaces(2) o ZWL
}

/**
 * Abstract base for monetary amounts. All representations share a currency code.
 */
abstract concept Amount {
  o CurrencyCode currencyCode
}

/**
 * Decimal-based monetary amount (v0.3.0 compatible).
 *
 * Use when: legacy contracts, display values, estimates where
 * floating-point precision loss is acceptable.
 *
 * Example: { doubleValue: 10.50, currencyCode: "USD" }
 */
concept MonetaryAmount extends Amount {
  o Double doubleValue
}

/**
 * Fixed-point monetary amount (v1.0 precision-safe).
 *
 * Represents: value = mantissa Γ— 10^(-scale)
 *
 * Use when: financial calculations requiring exact arithmetic,
 * currencies with non-decimal denominations, audit trails,
 * regulated reporting.
 *
 * The scale should match the currency's @DecimalPlaces decorator value.
 *
 * Examples:
 *   { mantissa: 1050,   scale: 2, currencyCode: "USD" } = $10.50
 *   { mantissa: 10050,  scale: 0, currencyCode: "JPY" } = Β₯10,050
 *   { mantissa: 100500, scale: 3, currencyCode: "KWD" } = 100.500 KWD
 */
concept FixedPointMonetaryAmount extends Amount {
  o Long mantissa
  o Integer scale default=2
}

/**
 * Currency exchange rate (decimal).
 */
concept CurrencyConversion {
  o CurrencyCode from
  o CurrencyCode to
  o Double rate
}

Why decorators instead of a CurrencyDecimalPlaces concept

Earlier drafts of this proposal carried a separate CurrencyDecimalPlaces concept as reference data. Decorators are strictly better:

  • Single source of truth β€” metadata lives on the enum value itself; no risk of drift between two collections
  • Idiomatic Concerto β€” decorators are the language's intended mechanism for static metadata
  • Smaller surface β€” eliminates a concept from the model
  • Tooling-friendly β€” code generators, validators, and introspection APIs can access the value via getDecorator('DecimalPlaces')

Tradeoff: decorators are not part of the wire format, so consumers need access to the model (not just the instance) to resolve the scale. This is fine for any caller that already loads the CTO via a ModelManager.

Conversion semantics

The two amount representations are interconvertible by reading the decorator off the enum value:

MonetaryAmount β†’ FixedPointMonetaryAmount
  Input:  { doubleValue: 10.50, currencyCode: "USD" }
  Lookup: CurrencyCode.USD.@DecimalPlaces = 2
  Output: { mantissa: 1050, scale: 2, currencyCode: "USD" }

FixedPointMonetaryAmount β†’ MonetaryAmount
  Input:  { mantissa: 1050, scale: 2, currencyCode: "USD" }
  Output: { doubleValue: 10.50, currencyCode: "USD" }

JavaScript helper sketch:

function getDecimalPlaces(modelManager, currencyCode) {
  const enumDecl = modelManager.getType('org.accordproject.money@1.0.0.CurrencyCode');
  const enumValue = enumDecl.getOwnProperty(currencyCode);
  return enumValue.getDecorator('DecimalPlaces').getArguments()[0];
}

Decimal places reference (ISO 4217)

Decimals Count Currencies
0 16 BIF, CLP, DJF, GNF, ISK, JPY, KMF, KRW, PYG, RWF, UGX, VND, VUV, XAF, XOF, XPF
2 ~137 AED, AUD, CAD, CHF, CNY, EUR, GBP, USD, … (most currencies)
3 18 BHD, BOV, COU, IQD, JOD, KWD, LYD, OMR, TND, UYI, XAU, XAG, XPT, XPD, XBA, XBB, XBC, XBD

Context

This proposal came out of a discussion about modelling monetary amounts in Cicero contracts. The driving questions were:

  • Can a JPY amount be represented unambiguously without out-of-band knowledge?
  • Can a contract that settles money use a representation that doesn't introduce floating-point drift?
  • Is the digital-currency concept still earning its place in the core money model, or should it move out?

The dual-representation approach lets template authors choose: keep MonetaryAmount for human-readable / display / legacy use, opt into FixedPointMonetaryAmount for precision-critical work, and convert between them when integrating systems with different expectations.

Detailed Description

Use case guidance

Scenario Recommended type
Legacy contracts (v0.3.0 migration) MonetaryAmount
Display values, UI bindings MonetaryAmount
Banking, settlement, ledgers FixedPointMonetaryAmount
Tax computations, accruals FixedPointMonetaryAmount
Regulated financial reporting FixedPointMonetaryAmount
Cross-currency arithmetic FixedPointMonetaryAmount
Estimated / approximate values MonetaryAmount

Breaking changes

  • Removal of DigitalMonetaryAmount and DigitalCurrencyCode. Contracts using these would migrate to either:
    • A new dedicated namespace (e.g. org.accordproject.crypto@1.0.0), or
    • Continue using @0.3.0 in parallel (Concerto supports multi-version imports), or
    • Switch to fiat MonetaryAmount where appropriate.

Non-breaking additions

  • FixedPointMonetaryAmount β€” new concept
  • Amount β€” new abstract base (existing MonetaryAmount extends it)
  • @DecimalPlaces decorator on each CurrencyCode value
  • New CurrencyCode enum entries (e.g. VES)

Design alternatives considered

  1. Generic FixedPoint<S> type β€” rejected: Concerto doesn't have generics and adding them for one type is too invasive.
  2. Replace Double doubleValue with Long mantissa outright β€” rejected: breaks every v0.3.0 contract.
  3. Single concept with optional mantissa + scale alongside doubleValue β€” rejected: dual-state in one concept invites consistency bugs; clearer to model as two related concepts sharing Amount.
  4. Separate CurrencyDecimalPlaces reference concept β€” rejected in favour of @DecimalPlaces decorator; metadata co-located with the enum is harder to desynchronise.
  5. String-based decimal representation β€” rejected: loses type information, requires parsing on every operation.

The dual-concept approach with a shared Amount base and decorator-annotated enum felt most idiomatic for Concerto.

Open questions for the community

  1. Is the abstract Amount base useful, or does it add ceremony without payoff?
  2. Are there code-generation targets in concerto-codegen that strip decorators? If so, what's the mitigation for consumers in those languages?
  3. Should we also add FixedPointCurrencyConversion for precision-safe FX rates?
  4. Are there contracts in the wild that still rely on DigitalMonetaryAmount / DigitalCurrencyCode? If so, what's the migration story?
  5. Should we add Concerto validation constraints (e.g., scale range [0, 4]) on FixedPointMonetaryAmount, or leave that to applications?

Happy to iterate on this β€” feedback welcome before any PR.

Activity

  1. niallroche commented on Jul 7, 2026

    @niallroche
    Contributor

    We should also address crypto/digital assets as part of this change. The current enum-based approach is limiting: it cannot cleanly represent assets with well-known external identifiers, chain/network context, token contract addresses, or asset-specific precision.

    One way to incorporate backwards compatibility is to make compatibility a migration layer, not the conceptual center of the new model.

    A two-tier design could look like this:

    abstract concept Amount {
      o MonetaryUnit unit
    }
    
    concept MonetaryAmount extends Amount {
      o Double doubleValue
      o CurrencyCode currencyCode
    }
    

    MonetaryAmount could remain as the legacy-compatible shape, but should be clearly documented as approximate / legacy. New templates should have a precise representation available:

    concept PreciseMonetaryAmount extends Amount {
      o String value
      o MonetaryUnit unit
      o MonetaryAmountEncoding encoding default="DECIMAL"
    }
    

    or, if the model wants to expose fixed-point structure directly:

    concept FixedPointMonetaryAmount extends Amount {
      o String mantissa
      o Integer scale
      o MonetaryUnit unit
    }
    

    This gives existing templates a soft landing: they can keep importing MonetaryAmount with doubleValue and currencyCode, while new templates use the precise type.
    The design I would avoid is adding both doubleValue and precise fields to the same MonetaryAmount concept. That creates a consistency trap:

    {
      "doubleValue": 10.5,
      "mantissa": "1049",
      "scale": 2
    }

    At that point consumers have to guess which representation is authoritative.

    One reasonable v1 compromise might be:

    abstract concept Amount {
    }
    
    concept MonetaryAmount extends Amount {
      o Double doubleValue
      o CurrencyCode currencyCode
    }
    
    enum MonetaryAmountEncoding {
      o DECIMAL
      o SCALED_INTEGER
    }
    
    concept MonetaryUnit {
      o String code optional          // e.g. USD, JPY, ETH, USDC
      o String scheme                 // e.g. iso4217, iso24165, erc20, caip19, coin, custom
      o String identifier optional    // e.g. DTI, CAIP-19 asset id, token address
      o Integer scale optional        // decimal precision / token decimals where applicable
    }
    
    concept PreciseMonetaryAmount extends Amount {
      o String value
      o MonetaryUnit unit
      o MonetaryAmountEncoding encoding default="DECIMAL"
    }
    

    Suggested conversion guidance:

    • MonetaryAmount -> PreciseMonetaryAmount: allowed, but may be lossy because the source is a binary float.
    • PreciseMonetaryAmount -> MonetaryAmount: allowed for display and legacy APIs, but not for settlement, audit, or financial calculations.
    • Financial logic SHOULD accept PreciseMonetaryAmount.
    • Legacy templates MAY continue to use MonetaryAmount.
    • New templates SHOULD prefer PreciseMonetaryAmount.
      This keeps backwards compatibility, but does not continue to use Double as the preferred representation for serious monetary values.
  2. mttrbrts commented on Jul 12, 2026

    @mttrbrts
    SponsorMemberAuthor

    I like that direction @niallroche, here's another iteration which aims to reconcile your comments with my constraints.

    Edit: revised PreciseAmount.unscaledValue from a Long to an exact integer string (BigInteger). A Long is a JS number, exact only to 2^53 β€” which is hit at ~0.009 ETH (18 decimals), not just at large amounts, and is also lossy for aggregate/on-chain magnitudes. Encoding the mantissa as a strict integer string makes it exact at any scale and interop-safe; arithmetic is done via a thin adapter over Dinero.js v2 / big.js rather than native numbers. Constraint 2 below is updated accordingly. I've also renamed the two amount concepts to ApproximateAmount (Double; display/estimates) and PreciseAmount (exact) so the choice between them is self-documenting. Per @niallroche's review below: Unit gains an optional scheme-scoped identifier (CAIP-19 / contract address / DTI) to disambiguate tokens, scale is constrained non-negative (range=[0,]), and BigInteger now rejects "-0".

    1. Structural back-compat for money@0.3.0.MonetaryAmount. No renamed properties, no new required properties. An existing { doubleValue, currencyCode } instance validates unchanged.
    2. Precise value is exact at any scale. An exact integer mantissa (not a float), so no floating-point drift and no ambiguity β€” and, unlike a Long, not capped at 2^53 (which 18-decimal tokens and aggregate balances exceed). It is encoded as a string for exactness/interop; clients convert once at the boundary (BigInt / Dinero v2) and do exact integer arithmetic.
    3. No discriminator enum. A scaled integer with scale on the unit is self-describing β€” there is nothing to tag.
    4. Non-fiat units are in scope, but ticker codes are not hard-coded into the model.

    Revised model β€” money@1.0.0

    // ISO 4217 alphabetic format, not enumerated
    scalar CurrencyCode extends String regex=/^[A-Z]{3}$/
    
    concept ApproximateAmount {
      o Double doubleValue
      o CurrencyCode currencyCode
    }
    
    concept Unit {
      o String code                      // USD, JPY, ETH, USDC
      o String scheme default="iso4217"  // iso4217 | iso24165 | erc20 | slip44 | caip19 | ...
      o String identifier optional       // CAIP-19 asset id, contract address, DTI, ...
      o Integer scale range=[0,]         // decimal places / minor units: 2, 0, 6, 18
    }
    
    // exact integer mantissa, canonical form (no "-0"), encoded as a string
    scalar BigInteger extends String regex=/^(0|-?[1-9][0-9]*)$/
    
    concept PreciseAmount {
      o BigInteger unscaledValue              // amount = unscaledValue Γ— 10^(βˆ’unit.scale)
      o Unit unit
    }
    

    Key changes vs. the original proposal in this issue, and why:

    • CurrencyCode enum is replaced by a CurrencyCode scalar (String + regex /^[A-Z]{3}$/). This stays structurally compatible because every enum member is three uppercase letters (e.g. "USD"), which the scalar accepts. It constrains the ISO 4217 format without enumerating the code list, so new/retired codes need no model change β€” while still removing the closed enum that used to bake every code into the model. (Arbitrary non-fiat units live on Unit, whose code is an open String keyed by scheme.)
    • @DecimalPlaces decorator is dropped. A decorator can only annotate hard-coded enum values, so it can't carry scale for arbitrary tokens, and it isn't in the wire format. Instead scale travels on Unit, so a PreciseAmount is fully self-describing at read time β€” no ModelManager needed to interpret it, and it works identically for fiat and tokens.
    • unscaledValue is an exact integer string (BigInteger), not a Long. The original draft used a numeric mantissa to avoid parsing, but a Long is a JS number and loses precision above 2^53 β€” i.e. above ~0.009 ETH at 18 decimals, and for aggregate/on-chain magnitudes generally. A strict integer-string mantissa is exact at any scale and never truncated by a JSON parser or across languages. Crucially this is not the ambiguous String value that was rejected earlier (a string that could be either "10.50" or "1050"): the encoding is a strict integer and scale lives on the unit, so there is still no discriminator. The cost is one BigInt(unscaledValue) at the boundary.
    • The abstract Amount base is dropped (open question Create time.ctoΒ #1). With legacy carrying currencyCode and precise carrying unit, the base shared no members and only added ceremony.
    • DigitalMonetaryAmount / DigitalCurrencyCode are removed. Crypto/token amounts are now expressed as a PreciseAmount whose unit.scheme is erc20, slip44, caip19, etc. β€” no separate namespace and no hard-coded coin list.

    Worked examples

    $10.50      -> { unscaledValue: "1050",                unit: { code: "USD",  scale: 2 } }
    Β₯10,050     -> { unscaledValue: "10050",               unit: { code: "JPY",  scale: 0 } }
    100.500 KWD -> { unscaledValue: "100500",              unit: { code: "KWD",  scale: 3 } }
    1.5 USDC    -> { unscaledValue: "1500000",             unit: { code: "USDC", scheme: "erc20",  scale: 6 } }
    1.5 ETH     -> { unscaledValue: "1500000000000000000", unit: { code: "ETH",  scheme: "slip44", scale: 18 } }
    

    Arithmetic β€” reuse, don't build

    Because the shape is integer mantissa + scale, it maps directly onto existing arbitrary-precision money libraries, so there's no need for a bespoke money engine. The maintainable path is a thin adapter over Dinero.js v2 (bigint calculator): Unit β†’ currency { code, base: 10, exponent: scale }, unscaledValue β†’ BigInt(amount), which gives exact add/subtract/allocate/compare and locale formatting for free. big.js / decimal.js work equally well. (Dinero v1 stores amount as a JS number β†’ back to the 2^53 limit, so v2 is required.) Distribution + adapters tracked in #187.

    Upgrade path (unsafe β†’ precise)

    A Double can't be reinterpreted as precise in place, so some change is unavoidable when upgrading. This design minimises it: currencyCode carries straight over into unit.code, and only the value changes representation via a one-time $class swap. doubleValue and unscaledValue live on different concepts, so a single instance never holds both β€” there's no dual-state consistency trap.

    Canonical scales as reference data (not in the schema)

    Because scale is now data rather than a hard-coded enum decorator, the canonical code β†’ Unit mapping lives as reference data in a separate namespace, org.accordproject.money.reference@1.0.0:

    map UnitMap {
      o String
      o Unit
    }
    concept CurrencyRegistry {
      o String scheme
      o UnitMap units
    }
    

    Published registries (e.g. an ISO 4217 table, an ERC-20 table, a SLIP-0044 native-coin table) are validated instances of CurrencyRegistry. A consumer loads the registry for a scheme and indexes units by code to resolve/validate the canonical scale. The trade-off is explicit: correctness of the code ↔ scale mapping now lives in the registry + validation, not the type system β€” which is the price of not hard-coding tickers.

    Open follow-ups

    Draft implementation (models + reference registry data) is up as #188.

  3. niallroche commented on Jul 13, 2026

    @niallroche
    Contributor

    Great iteration, Matt. A few small suggestions:

    1. The proposed MonetaryUnit seems to have lost the identifier field from the earlier sketch.

    I think it is worth keeping as for token schemes, code alone is ambiguous. For example, "USDC" exists on many chains with different contracts, and two tokens can legitimately share a ticker. The instance should be able to carry the disambiguator rather than depending entirely on registry lookup. Sending the wrong token on the wrong chain can have disastrous consequences.

    Adding an optional scheme-scoped identifier would let the instance carry its own disambiguation:

    concept MonetaryUnit {
      o String code
      o String scheme default="iso4217"
      o String identifier optional        // CAIP-19 asset id, contract address, DTI, etc.
      o Integer scale
    }
    

    An example CAIP-19 Asset ID would be : eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48eip155:1
    This represents the Ethereum Mainnet network.erc20 represents the asset class.Smart Contract Address: 0xa0b8699....
    See (https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-21.md) and
    (https://docs.glider.fi/guides/caip-identifiers)18b36c1d19d4a2e9eb0ce3606eb48

    This is the canonical ERC-20 smart contract deployed on Ethereum, verifiable on Etherscan.

    Or it could be a DTI (Digital Token Identifier) assigned by the Digital Token Identifier Foundation as a unique 9-character alphanumeric code mapping to the token's reference data. DTI codes are asset-specific, meaning the exact alphanumeric string must be retrieved via the official DTIF Registry for each specific token

    1. scale should probably be constrained to be non-negative.
      scale says how many decimal places the unit has. USD has scale: 2, so value: "1050" means 10.50. But scale is currently a plain Integer, and integers can be negative. If someone writes scale: -2, the maths says multiply by 100 instead, so value: "5" would mean 500 USD. That is almost certainly a mistake.
      Could we add a non-negative constraint, e.g. range=[0,] if open-ended ranges are supported, or an equivalent constraint?

    2. IntegerAmount currently accepts "-0".
      Minus-zero and zero are the same amount written two ways, but the comment promises canonical form. Two spellings of zero means identical amounts can hash or compare differently.

    Current:

    scalar IntegerAmount extends String regex=/^-?(0|[1-9][0-9]*)$/
    

    Suggested:

    scalar IntegerAmount extends String regex=/^(0|-?[1-9][0-9]*)$/
    
  4. niallroche commented on Jul 14, 2026

    @niallroche
    Contributor

    the new revised approach looks like it has adressed those points Matt

  5. self-assigned this
    on Jul 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions