From a2c53417f4420381237d8c10e3dc9b1f68aab90c Mon Sep 17 00:00:00 2001 From: Supun Setunga Date: Fri, 15 Aug 2025 15:32:33 -0700 Subject: [PATCH 1/5] FLIP for adding 128-bit fixed-point types in Cadence --- cadence/20250815-128-bit-fixed-point-types.md | 78 +++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 cadence/20250815-128-bit-fixed-point-types.md diff --git a/cadence/20250815-128-bit-fixed-point-types.md b/cadence/20250815-128-bit-fixed-point-types.md new file mode 100644 index 000000000..903cd40f8 --- /dev/null +++ b/cadence/20250815-128-bit-fixed-point-types.md @@ -0,0 +1,78 @@ +--- +status: proposed +flip: 341 +authors: Supun Setunga (supun.setunga@flowfoundation.org) +sponsor: Dieter Shirley (dete@flowfoundation.com) +updated: 2025-08-15 +--- + +# FLIP 341: Add 128-bit Fixed-point Types to Cadence + +## Objective + +The objective is to add a set of 128-bit wide fixed-point types, `Fix128` and `UFix128` to Cadence. + +## Motivation + +Cadence currently only supports 64-bit wide decimal fixed-point types, `Fix64` and `UFix64`, +having the ranges `-92233720368.54775808` through `92233720368.54775807` and `0.0` through `184467440737.09551615` +respectively. + +However, there could be requirements to have a much higher precision than what `Fix64` and `UFix64` provide. +For example, applications that handle financial data would require higher precision for arithmetic operations. +Though this can be achieved with a custom fixed-point implementation using integers (128-bit length, 256-bit length, +or even unbounded integers), it is not only a lot of work for developers to implement such a type, +but also would be very inefficient. + +## User Benefit + +Developers can use fixed-point values in Cadence for high-precision arithmetics, efficiently and conveniently. + +## Design Proposal + +Add `Fix128` and `UFix128` to Cadence. + +The proposal is to use a scale of 24, and hence a scaling factor of 1e-24. +Thus, the new fixed-point type can accommodate values in the following ranges: +- `Fix128`: `-170141183460469.231731687303715884105728` through `170141183460469.231731687303715884105727` +- `UFix128`: `0.0` through `340282366920938.463463374607431768211455` + +### Drawbacks + +None. + +### Performance Implications + +None. + +### Dependencies + +None. + +### Engineering Impact + +Implementing a new and efficient fixed-point representation is non-trivial. + +### Compatibility + +Given this is a new feature addition, there's no impact on backward compatibility. + +### User Impact + +Given this is a new feature addition, there's no impact for existing users. + +## Related Issues + +None. + +## Implementation +- `Fix128` - https://github.com/onflow/cadence/pull/4131 +- `UFix128` - https://github.com/onflow/cadence/pull/4147 + +## Prior Art + +Most programing languages do not have built-in types for 128-bit fixed-point values, but are provided either +as a standard library or are available as third-party libraries. e.g: +- Python: https://docs.python.org/3/library/decimal.html +- Rust: https://docs.rs/fixed/latest/fixed/index.html + From 94f284577ac085ecb316b83c8ba00fbb0a80f4d5 Mon Sep 17 00:00:00 2001 From: Supun Setunga Date: Tue, 19 Aug 2025 09:11:02 -0700 Subject: [PATCH 2/5] Add reason behind selecting 24 as the scaling factor --- cadence/20250815-128-bit-fixed-point-types.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/cadence/20250815-128-bit-fixed-point-types.md b/cadence/20250815-128-bit-fixed-point-types.md index 903cd40f8..9bbf21c5f 100644 --- a/cadence/20250815-128-bit-fixed-point-types.md +++ b/cadence/20250815-128-bit-fixed-point-types.md @@ -32,8 +32,13 @@ Developers can use fixed-point values in Cadence for high-precision arithmetics, Add `Fix128` and `UFix128` to Cadence. -The proposal is to use a scale of 24, and hence a scaling factor of 1e-24. -Thus, the new fixed-point type can accommodate values in the following ranges: +The proposal is to use a scale of 24, and therefore a scaling factor of 1e-24. +This scaling factor was chosen because the main objective of adding 128-bit length types is to achieve higher precision, +rather than being able to represent extremely large numbers. +Thus, we think having a scaling factor of 24 provides a high-enough precision for fractional values, +while also leaving large enough upper and lower bounds sufficient for most real-world use cases. + +The new fixed-point type can accommodate values in the following ranges: - `Fix128`: `-170141183460469.231731687303715884105728` through `170141183460469.231731687303715884105727` - `UFix128`: `0.0` through `340282366920938.463463374607431768211455` From e4c58e11ca100042c55113c9129093471d49828e Mon Sep 17 00:00:00 2001 From: Supun Setunga Date: Thu, 21 Aug 2025 14:27:51 -0700 Subject: [PATCH 3/5] Add detailed explanation on choosing a 24 scale Co-authored-by: Dieter Shirley --- cadence/20250815-128-bit-fixed-point-types.md | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/cadence/20250815-128-bit-fixed-point-types.md b/cadence/20250815-128-bit-fixed-point-types.md index 9bbf21c5f..86d24eddd 100644 --- a/cadence/20250815-128-bit-fixed-point-types.md +++ b/cadence/20250815-128-bit-fixed-point-types.md @@ -33,10 +33,20 @@ Developers can use fixed-point values in Cadence for high-precision arithmetics, Add `Fix128` and `UFix128` to Cadence. The proposal is to use a scale of 24, and therefore a scaling factor of 1e-24. -This scaling factor was chosen because the main objective of adding 128-bit length types is to achieve higher precision, -rather than being able to represent extremely large numbers. -Thus, we think having a scaling factor of 24 provides a high-enough precision for fractional values, -while also leaving large enough upper and lower bounds sufficient for most real-world use cases. + +Other blockchain ecosystems (most notably Ethereum) frequently use scale factors (usually called "decimals", per ERC-20) +of 18 (used by ETH itself), 24 (used for internal calculations in MakerDAO), and 27 (used internally by Compound and Aave +for interest calculations). +Although 27 is the most commonly used value, the value of 24 has a precedent in Maker, and leads to a range that is +close to, but slightly larger than the range of `Fix64` and `UFix64`. +This allows all `UFix64` and `Fix64` values to be converted to the equivalent 128-bit types without any loss of precision +or range. +On the other hand, 27 decimals wouldn't have allowed the full range of `Fix64` and `UFix64` to fit in the new types, +and using 18 decimals has been deemed to be insufficient by a number of defi protocols. + +A scaling factor of 24 provides a very high precision for fractional values, while also leaving large enough upper and +lower bounds sufficient for most real-world use cases (which typically will involve internal calculations that convert +back to the 64-bit types). The new fixed-point type can accommodate values in the following ranges: - `Fix128`: `-170141183460469.231731687303715884105728` through `170141183460469.231731687303715884105727` From 70e8efff8366b382189ede0e407949dd629bfaf7 Mon Sep 17 00:00:00 2001 From: Supun Setunga Date: Fri, 22 Aug 2025 08:41:26 -0700 Subject: [PATCH 4/5] Update the explanation Co-authored-by: Dieter Shirley --- cadence/20250815-128-bit-fixed-point-types.md | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/cadence/20250815-128-bit-fixed-point-types.md b/cadence/20250815-128-bit-fixed-point-types.md index 86d24eddd..ead7cc3b2 100644 --- a/cadence/20250815-128-bit-fixed-point-types.md +++ b/cadence/20250815-128-bit-fixed-point-types.md @@ -37,12 +37,9 @@ The proposal is to use a scale of 24, and therefore a scaling factor of 1e-24. Other blockchain ecosystems (most notably Ethereum) frequently use scale factors (usually called "decimals", per ERC-20) of 18 (used by ETH itself), 24 (used for internal calculations in MakerDAO), and 27 (used internally by Compound and Aave for interest calculations). -Although 27 is the most commonly used value, the value of 24 has a precedent in Maker, and leads to a range that is -close to, but slightly larger than the range of `Fix64` and `UFix64`. -This allows all `UFix64` and `Fix64` values to be converted to the equivalent 128-bit types without any loss of precision -or range. -On the other hand, 27 decimals wouldn't have allowed the full range of `Fix64` and `UFix64` to fit in the new types, -and using 18 decimals has been deemed to be insufficient by a number of defi protocols. +Although 27 is the most commonly used value internally by defi protocols, the value of 24 has a precedent in Maker, and +introduces a type that can hold values in the trillions (extreme, but plausible values for very large financial calculations). +Note that all `UFix64` and `Fix64` values can be converted to the equivalent 128-bit types without any loss of precision or range. A scaling factor of 24 provides a very high precision for fractional values, while also leaving large enough upper and lower bounds sufficient for most real-world use cases (which typically will involve internal calculations that convert From 351ee633ab4cd6af50eda6dcbd24990a6805352f Mon Sep 17 00:00:00 2001 From: Supun Setunga Date: Fri, 29 Aug 2025 13:41:59 -0700 Subject: [PATCH 5/5] Accept the FLIP --- cadence/20250815-128-bit-fixed-point-types.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/cadence/20250815-128-bit-fixed-point-types.md b/cadence/20250815-128-bit-fixed-point-types.md index ead7cc3b2..c1a60c706 100644 --- a/cadence/20250815-128-bit-fixed-point-types.md +++ b/cadence/20250815-128-bit-fixed-point-types.md @@ -1,9 +1,9 @@ --- -status: proposed +status: accepted flip: 341 authors: Supun Setunga (supun.setunga@flowfoundation.org) sponsor: Dieter Shirley (dete@flowfoundation.com) -updated: 2025-08-15 +updated: 2025-08-29 --- # FLIP 341: Add 128-bit Fixed-point Types to Cadence