soroban-fixed-point-math

为SOROBAN智能合约提供固定点数学的库。

安全性

这是一个实验性软件，按照“原样”和“可用”的原则提供。

我们不提供任何保证，并且不会对通过使用此代码库而产生的任何损失承担责任。

使用方法

将此添加到您的 Cargo.toml

[dependencies]
soroban_fixed_point_math = "<desired version>"

FixedPoint Trait

该 FixedPoint 特性针对Rust泛型整数 i64、u64、i128 和 u128 实现。在固定点数学计算过程中发生的任何溢出或除以零都将返回 None，与Rust现有的已检查数学函数保持一致。

幻影溢出是中间计算中溢出导致的结果，但预期结果应在范围内。此特性为每个实现的整数类型管理不同。

• i64 和 u64
  • 在发生幻影溢出的情况下，中间计算会缩放到 i128 / u128 并重试。
• i128 和 u128
  • 在发生幻影溢出的情况下，函数将终止并返回 None。如果您需要处理更大的数字，请使用 SorobanFixedPoint 特性。

SorobanFixedPoint Trait

为 Soroban 主机类型 I256 和 U256 实现了 SorobanFixedPoint 特性。如果发生任何 I256 或 U256 算术错误，特性将导致程序崩溃，因为主机函数默认情况下会崩溃。

还包括了对 i128 和 u128 整数类型的 SorobanFixedPoint 特性的额外实现，以支持更大的中间计算。这消除了大多数 128 位定点数学的幻影溢出事件。

示例

对于任何实现 FixedPoint 的支持类型，你可以执行定点操作，如下所示

use soroban_fixed_point_math::FixedPoint;

let x: u64 = 1_5000000;
let y: u64 = 2_0000000;
assert_eq!(x.fixed_mul_floor(y, 1_0000000).unwrap(), 3_0000000);

对于任何实现 SorobanFixedPoint 的支持类型，你可以执行定点操作，如下所示

use soroban_fixed_point_math::SorobanFixedPoint;
use soroban_sdk::{Env, I256};

let env: Env //... from your contract, or Env::default() in a test
let x: I256 = I256::from_i32(&env, 1_5000000);
let y: I256 = I256::from_i32(&env, 2_0000000);
assert_eq!(x.fixed_mul_ceil(&x, &y, I256::from_i32(&env, 1_0000000)), 3_0000000);

致谢

这个库受到了许多来源的启发或直接修改，主要包括

• Solmate
• OpenZeppelin

WASM

支持 WASM 目标 wasm32-unknown-unknown。

贡献

欢迎贡献。请查阅贡献指南（待办事项）！

许可

此库在 MIT 许可证 下发布。