Repository navigation
Description
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:
DigitalMonetaryAmount/DigitalCurrencyCodemix cryptocurrency concerns into the core money model. These belong in a separate, specialised namespace.Double doubleValueis 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.- 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.
CurrencyCodeenum should be refreshed against the latest ISO 4217 active list (e.g.,VESfor the Venezuelan BolΓvar Soberano).
Possible Solution
A dual-representation v1.0.0 model that:
- Removes
DigitalMonetaryAmountandDigitalCurrencyCode - Keeps
MonetaryAmount(withdoubleValue+currencyCode) backwards-compatible with v0.3.0 - Adds
FixedPointMonetaryAmountfor precision-safe arithmetic - Annotates each
CurrencyCodeenum value with a@DecimalPlacesdecorator carrying its ISO 4217 minor-unit count - Refreshes
CurrencyCodeagainst 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
DigitalMonetaryAmountandDigitalCurrencyCode. Contracts using these would migrate to either:- A new dedicated namespace (e.g.
org.accordproject.crypto@1.0.0), or - Continue using
@0.3.0in parallel (Concerto supports multi-version imports), or - Switch to fiat
MonetaryAmountwhere appropriate.
- A new dedicated namespace (e.g.
Non-breaking additions
FixedPointMonetaryAmountβ new conceptAmountβ new abstract base (existingMonetaryAmountextends it)@DecimalPlacesdecorator on eachCurrencyCodevalue- New
CurrencyCodeenum entries (e.g.VES)
Design alternatives considered
- Generic
FixedPoint<S>type β rejected: Concerto doesn't have generics and adding them for one type is too invasive. - Replace
Double doubleValuewithLong mantissaoutright β rejected: breaks every v0.3.0 contract. - Single concept with optional
mantissa+scalealongsidedoubleValueβ rejected: dual-state in one concept invites consistency bugs; clearer to model as two related concepts sharingAmount. - Separate
CurrencyDecimalPlacesreference concept β rejected in favour of@DecimalPlacesdecorator; metadata co-located with the enum is harder to desynchronise. - 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
- Is the abstract
Amountbase useful, or does it add ceremony without payoff? - Are there code-generation targets in
concerto-codegenthat strip decorators? If so, what's the mitigation for consumers in those languages? - Should we also add
FixedPointCurrencyConversionfor precision-safe FX rates? - Are there contracts in the wild that still rely on
DigitalMonetaryAmount/DigitalCurrencyCode? If so, what's the migration story? - Should we add Concerto validation constraints (e.g.,
scalerange[0, 4]) onFixedPointMonetaryAmount, or leave that to applications?
Happy to iterate on this β feedback welcome before any PR.
Activity
niallroche commentedon Jul 7, 2026
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:
MonetaryAmountcould remain as the legacy-compatible shape, but should be clearly documented as approximate / legacy. New templates should have a precise representation available:or, if the model wants to expose fixed-point structure directly:
This gives existing templates a soft landing: they can keep importing
MonetaryAmountwithdoubleValueandcurrencyCode, while new templates use the precise type.The design I would avoid is adding both
doubleValueand precise fields to the sameMonetaryAmountconcept. 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:
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.PreciseMonetaryAmount.MonetaryAmount.PreciseMonetaryAmount.This keeps backwards compatibility, but does not continue to use
Doubleas the preferred representation for serious monetary values.mttrbrts commentedon Jul 12, 2026
I like that direction @niallroche, here's another iteration which aims to reconcile your comments with my constraints.
money@0.3.0.MonetaryAmount. No renamed properties, no new required properties. An existing{ doubleValue, currencyCode }instance validates unchanged.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.scaleon the unit is self-describing β there is nothing to tag.Revised model β
money@1.0.0Key changes vs. the original proposal in this issue, and why:
CurrencyCodeenum is replaced by aCurrencyCodescalar (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 onUnit, whosecodeis an openStringkeyed byscheme.)@DecimalPlacesdecorator 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. Insteadscaletravels onUnit, so aPreciseAmountis fully self-describing at read time β noModelManagerneeded to interpret it, and it works identically for fiat and tokens.unscaledValueis an exact integer string (BigInteger), not aLong. The original draft used a numeric mantissa to avoid parsing, but aLongis a JSnumberand 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 ambiguousString valuethat was rejected earlier (a string that could be either"10.50"or"1050"): the encoding is a strict integer andscalelives on the unit, so there is still no discriminator. The cost is oneBigInt(unscaledValue)at the boundary.Amountbase is dropped (open question Create time.ctoΒ #1). With legacy carryingcurrencyCodeand precise carryingunit, the base shared no members and only added ceremony.DigitalMonetaryAmount/DigitalCurrencyCodeare removed. Crypto/token amounts are now expressed as aPreciseAmountwhoseunit.schemeiserc20,slip44,caip19, etc. β no separate namespace and no hard-coded coin list.Worked examples
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.jswork equally well. (Dinero v1 storesamountas a JSnumberβ back to the 2^53 limit, so v2 is required.) Distribution + adapters tracked in #187.Upgrade path (unsafe β precise)
A
Doublecan't be reinterpreted as precise in place, so some change is unavoidable when upgrading. This design minimises it:currencyCodecarries straight over intounit.code, and only the value changes representation via a one-time$classswap.doubleValueandunscaledValuelive 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
scaleis now data rather than a hard-coded enum decorator, the canonicalcode β Unitmapping lives as reference data in a separate namespace,org.accordproject.money.reference@1.0.0: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 indexesunitsby code to resolve/validate the canonical scale. The trade-off is explicit: correctness of thecode β scalemapping now lives in the registry + validation, not the type system β which is the price of not hard-coding tickers.Open follow-ups
UnitMapsurfaced a concerto-core bug (Serializer.toJSONcan't serialize a map whose value concept is imported from another namespace) β fix + upstream PR: fix(concerto-core): serialize maps with cross-namespace concept valuesΒ concerto#1279.money@0.3.0code set plusVES.Draft implementation (models + reference registry data) is up as #188.
niallroche commentedon Jul 13, 2026
Great iteration, Matt. A few small suggestions:
MonetaryUnitseems to have lost theidentifierfield from the earlier sketch.I think it is worth keeping as for token schemes,
codealone 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:
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
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?
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:
Suggested:
feat(money): address review β unit identifier, non-negative scale, caβ¦
niallroche commentedon Jul 14, 2026
the new revised approach looks like it has adressed those points Matt
feat(money): propose org.accordproject.money@1.0.0 + reference registβ¦