ipor-fusion 4.0.0.dev255__tar.gz → 4.0.0.dev260__tar.gz

{ipor_fusion-4.0.0.dev255 → ipor_fusion-4.0.0.dev260}/AGENTS.md

@@ -419,7 +419,9 @@ or examples.
   round re-resolves it. Labels only name calls in `result.calls` and failures.
   Integration tests and examples use it instead of a local node.
 - Amounts are raw on-chain integers; `types.py` `NewType`s (`Amount`, `Shares`,
-  `MarketId`, ...) name the unit, and nothing scales by decimals.
+  `MarketId`, ...) name the unit, and nothing scales by decimals except the exact
+  boundary converters `parse_amount` / `format_amount` (and the `*_shares` pair):
+  decimal text in, raw integer out, no float ever.
 - Three address roles are nominal: `PlasmaVaultAddress`, `FuseAddress` and
   `AccessManagerAddress` (NewTypes of `ChecksumAddress`). Their wrappers, getters and
   records return them, so a vault, a fuse and an access manager cannot be passed for

{ipor_fusion-4.0.0.dev255 → ipor_fusion-4.0.0.dev260}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ipor-fusion
-Version: 4.0.0.dev255
+Version: 4.0.0.dev260
 Summary: The IPOR Fusion SDK for Python
 Project-URL: homepage, https://ipor.io
 Project-URL: repository, https://github.com/IPOR-Labs/ipor-fusion.py
@@ -170,7 +170,10 @@ Fuse, factory and manager addresses per chain are published in
 [ipor-abi](https://github.com/IPOR-Labs/ipor-abi) (`mainnet/mainnet-<chain>-fusion/addresses.json`).
 A fuse must also be registered on the vault; `vault.get_fuses().call(ctx)` lists the registered ones.
 
-Amounts are raw on-chain integers (`Amount`, `Shares` in `ipor_fusion.types`); the SDK never scales by decimals.
+Amounts are raw on-chain integers (`Amount`, `Shares` in `ipor_fusion.types`); the SDK scales by decimals
+only in explicit boundary converters.
+`parse_amount("1.5", Decimals(6))` and `format_amount(Amount(1_500_000), Decimals(6))` convert exactly at the
+boundary (no floats, no rounding; `parse_shares` / `format_shares` for shares at the share token's decimals).
 
 ### Read, send, or simulate
 

{ipor_fusion-4.0.0.dev255 → ipor_fusion-4.0.0.dev260}/README.md

@@ -122,7 +122,10 @@ Fuse, factory and manager addresses per chain are published in
 [ipor-abi](https://github.com/IPOR-Labs/ipor-abi) (`mainnet/mainnet-<chain>-fusion/addresses.json`).
 A fuse must also be registered on the vault; `vault.get_fuses().call(ctx)` lists the registered ones.
 
-Amounts are raw on-chain integers (`Amount`, `Shares` in `ipor_fusion.types`); the SDK never scales by decimals.
+Amounts are raw on-chain integers (`Amount`, `Shares` in `ipor_fusion.types`); the SDK scales by decimals
+only in explicit boundary converters.
+`parse_amount("1.5", Decimals(6))` and `format_amount(Amount(1_500_000), Decimals(6))` convert exactly at the
+boundary (no floats, no rounding; `parse_shares` / `format_shares` for shares at the share token's decimals).
 
 ### Read, send, or simulate
 

{ipor_fusion-4.0.0.dev255 → ipor_fusion-4.0.0.dev260}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ipor-fusion"
-version = "4.0.0.dev255"
+version = "4.0.0.dev260"
 description = "The IPOR Fusion SDK for Python"
 authors = [
     { name = "Adam Mydlarz", email = "amydlarz@gmail.com" },

{ipor_fusion-4.0.0.dev255 → ipor_fusion-4.0.0.dev260}/src/ipor_fusion/__init__.py

@@ -333,11 +333,15 @@ from ipor_fusion.types import (
     TokenId,
     TxHash,
     Verdict,
+    format_amount,
+    format_shares,
     parse_access_manager_address,
+    parse_amount,
     parse_fuse_address,
     parse_hex_address,
     parse_morpho_market_id,
     parse_plasma_vault_address,
+    parse_shares,
     parse_tx_hash,
 )
 from ipor_fusion.validation import (
@@ -617,6 +621,10 @@ __all__ = [
     "parse_plasma_vault_address",
     "parse_morpho_market_id",
     "parse_tx_hash",
+    "parse_amount",
+    "parse_shares",
+    "format_amount",
+    "format_shares",
     "Price",
     "Period",
     "MAX_UINT256",

{ipor_fusion-4.0.0.dev255 → ipor_fusion-4.0.0.dev260}/src/ipor_fusion/types.py

@@ -1,3 +1,4 @@
+import re
 from dataclasses import dataclass
 from typing import ClassVar, Literal, NewType, TypeAlias
 
@@ -196,3 +197,81 @@ def parse_fuse_address(value: str | bytes) -> FuseAddress:
 def parse_access_manager_address(value: str | bytes) -> AccessManagerAddress:
     """An access manager's address, checksummed; see `parse_plasma_vault_address`."""
     return AccessManagerAddress(_checksum(value))
+
+
+# ASCII digits only: ``\d`` would also take other scripts' digits, which int() reads.
+_DECIMAL_TEXT = re.compile(r"([0-9]*)(?:\.([0-9]*))?")
+
+
+_UINT256_DIGITS = len(str(MAX_UINT256))
+
+
+def _check_decimals(decimals: Decimals) -> None:
+    if not 0 <= decimals <= 255:
+        raise ValueError(f"decimals must be 0..255 (ERC-20 uint8), got {decimals}")
+
+
+def _parse_units(text: str, decimals: Decimals, what: str) -> int:
+    if not isinstance(text, str):
+        raise TypeError(
+            f"{what} must be text, not {type(text).__name__}: floats lose precision"
+        )
+    _check_decimals(decimals)
+    match = _DECIMAL_TEXT.fullmatch(text.strip())
+    if match is None or not (match.group(1) or match.group(2)):
+        raise ValueError(f"not a decimal {what}: {text!r}")
+    whole, fraction = match.group(1).lstrip("0"), match.group(2) or ""
+    if len(fraction) > decimals:
+        raise ValueError(
+            f"{what} {text!r} has {len(fraction)} fractional digits,"
+            f" more than the {decimals} the token carries"
+        )
+    # Bounded before int(): a longer whole part overflows uint256 at any scale.
+    if len(whole) > _UINT256_DIGITS:
+        raise ValueError(f"{what} {text!r} exceeds uint256")
+    value = int(whole + fraction.ljust(decimals, "0") or "0")
+    if value > MAX_UINT256:
+        raise ValueError(f"{what} {text!r} exceeds uint256")
+    return value
+
+
+def _format_units(value: int, decimals: Decimals, what: str) -> str:
+    if not 0 <= value <= MAX_UINT256:
+        raise ValueError(f"{what} must be within uint256, got {value}")
+    _check_decimals(decimals)
+    whole, fraction = divmod(value, 10**decimals)
+    if fraction == 0:
+        return str(whole)
+    return f"{whole}.{str(fraction).zfill(decimals).rstrip('0')}"
+
+
+def parse_amount(text: str, decimals: Decimals) -> Amount:
+    """The raw `Amount` of ``text`` token units at ``decimals``, exactly:
+    ``parse_amount("1.5", Decimals(6))`` is ``Amount(1_500_000)``.
+
+    ``text`` is digits with at most one ``.`` (surrounding whitespace ignored);
+    no sign, exponent or separators. ``decimals`` is 0..255, an ERC-20 uint8.
+    Raises ``ValueError`` for anything else, for more fractional digits than
+    ``decimals`` (nothing is rounded) and for a value above uint256; ``TypeError`` for a non-string, so a float is never
+    accepted. Inverse of `format_amount`.
+    """
+    return Amount(_parse_units(text, decimals, "amount"))
+
+
+def parse_shares(text: str, decimals: Decimals) -> Shares:
+    """`parse_amount` for vault shares at the share token's ``decimals``
+    (`PlasmaVault.decimals`, not the asset's)."""
+    return Shares(_parse_units(text, decimals, "shares"))
+
+
+def format_amount(amount: Amount, decimals: Decimals) -> str:
+    """``amount`` in token units as exact decimal text, no trailing zeros:
+    ``format_amount(Amount(1_500_000), Decimals(6))`` is ``"1.5"``; a whole
+    number has no ``.``. Raises ``ValueError`` on an amount outside uint256 or
+    ``decimals`` outside 0..255. Inverse of `parse_amount`."""
+    return _format_units(amount, decimals, "amount")
+
+
+def format_shares(shares: Shares, decimals: Decimals) -> str:
+    """`format_amount` for vault shares."""
+    return _format_units(shares, decimals, "shares")

{ipor_fusion-4.0.0.dev255 → ipor_fusion-4.0.0.dev260}/tests/test_public_api.py

@@ -367,7 +367,9 @@ _ALL_SNAPSHOT: dict[str, frozenset[str]] = {
             "find_creation_block",
             "find_markets_missing_erc20_dependency",
             "find_orphan_fuse_markets",
+            "format_amount",
             "format_market_label",
+            "format_shares",
             "get_contract_name",
             "get_deployment_tx",
             "get_logs_adaptive",
@@ -377,10 +379,12 @@ _ALL_SNAPSHOT: dict[str, frozenset[str]] = {
             "morpho_blue_address",
             "package_version",
             "parse_access_manager_address",
+            "parse_amount",
             "parse_fuse_address",
             "parse_hex_address",
             "parse_morpho_market_id",
             "parse_plasma_vault_address",
+            "parse_shares",
             "parse_tx_hash",
             "price_oracle_middleware",
             "read_changelog",
@@ -1107,11 +1111,15 @@ _MODULE_PATH_SNAPSHOT: dict[str, frozenset[str]] = {
             "TxHash",
             "Verdict",
             "ZERO_ADDRESS",
+            "format_amount",
+            "format_shares",
             "parse_access_manager_address",
+            "parse_amount",
             "parse_fuse_address",
             "parse_hex_address",
             "parse_morpho_market_id",
             "parse_plasma_vault_address",
+            "parse_shares",
             "parse_tx_hash",
         }
     ),

{ipor_fusion-4.0.0.dev255 → ipor_fusion-4.0.0.dev260}/tests/test_types_and_events.py

@@ -6,7 +6,7 @@ from hexbytes import HexBytes
 from web3 import Web3
 
 from ipor_fusion.fuses.events import extract_events
-from ipor_fusion.types import Amount, Decimals, Price
+from ipor_fusion.types import MAX_UINT256, Amount, Decimals, Price, Shares
 
 ADDR = Web3.to_checksum_address("0x1111111111111111111111111111111111111111")
 
@@ -155,3 +155,119 @@ class TestRoleParsers:
         assert parser(bytes.fromhex(self.LOWER[2:])) == checksum
         with pytest.raises(ValueError):
             parser("0x1234")
+
+
+class TestAmountText:
+    @pytest.mark.parametrize(
+        ("text", "decimals", "raw"),
+        [
+            ("1.5", 6, 1_500_000),
+            ("0.000001", 6, 1),
+            ("1", 18, 10**18),
+            ("1.", 6, 1_000_000),
+            (".5", 6, 500_000),
+            (" 42 ", 0, 42),
+            ("0", 6, 0),
+            ("1.000000", 6, 1_000_000),
+            (str(MAX_UINT256), 0, MAX_UINT256),
+            (
+                "115792089237316195423570985008687907853269984665640564039457.584007913129639935",
+                18,
+                MAX_UINT256,
+            ),
+        ],
+    )
+    def test_parse_amount_is_exact(self, text, decimals, raw):
+        from ipor_fusion import parse_amount
+
+        assert parse_amount(text, Decimals(decimals)) == raw
+
+    @pytest.mark.parametrize(
+        "text",
+        [
+            "",
+            ".",
+            "-1",
+            "+1",
+            "1e6",
+            "1,000",
+            "1_000",
+            "1.5.0",
+            "0x10",
+            "1 0",
+            "nan",
+            "\u0663",
+            "\uff11.5",
+        ],
+    )
+    def test_parse_amount_rejects_anything_but_plain_decimal_text(self, text):
+        from ipor_fusion import parse_amount
+
+        with pytest.raises(ValueError, match="not a decimal amount"):
+            parse_amount(text, Decimals(6))
+
+    def test_parse_amount_never_rounds(self):
+        from ipor_fusion import parse_amount
+
+        with pytest.raises(ValueError, match="7 fractional digits"):
+            parse_amount("1.0000001", Decimals(6))
+
+    def test_parse_amount_rejects_uint256_overflow_and_floats(self):
+        from ipor_fusion import parse_amount
+
+        with pytest.raises(ValueError, match="exceeds uint256"):
+            parse_amount(str(MAX_UINT256 + 1), Decimals(0))
+        with pytest.raises(TypeError, match="floats lose precision"):
+            parse_amount(1.5, Decimals(6))
+        with pytest.raises(ValueError, match="decimals"):
+            parse_amount("1", Decimals(-1))
+        with pytest.raises(ValueError, match="0..255"):
+            parse_amount("1", Decimals(256))
+
+    def test_parse_amount_bounds_digits_before_converting(self):
+        from ipor_fusion import parse_amount
+
+        # Leading zeros are not significant, past Python's int() digit limit too.
+        assert parse_amount("0" * 5000 + "1", Decimals(0)) == 1
+        with pytest.raises(ValueError, match="exceeds uint256"):
+            parse_amount("1" * 5000, Decimals(0))
+        assert parse_amount("0." + "0" * 254 + "1", Decimals(255)) == 1
+
+    @pytest.mark.parametrize(
+        ("raw", "decimals", "text"),
+        [
+            (1_500_000, 6, "1.5"),
+            (1, 6, "0.000001"),
+            (10**18, 18, "1"),
+            (0, 6, "0"),
+            (42, 0, "42"),
+            (123_456_789, 4, "12345.6789"),
+            (
+                MAX_UINT256,
+                18,
+                "115792089237316195423570985008687907853269984665640564039457.584007913129639935",
+            ),
+        ],
+    )
+    def test_format_amount_round_trips(self, raw, decimals, text):
+        from ipor_fusion import format_amount, parse_amount
+
+        assert format_amount(Amount(raw), Decimals(decimals)) == text
+        assert parse_amount(text, Decimals(decimals)) == raw
+
+    @pytest.mark.parametrize("raw", [-1, MAX_UINT256 + 1])
+    def test_format_amount_rejects_values_outside_uint256(self, raw):
+        from ipor_fusion import format_amount, format_shares
+
+        with pytest.raises(ValueError, match="within uint256"):
+            format_amount(Amount(raw), Decimals(6))
+        with pytest.raises(ValueError, match="within uint256"):
+            format_shares(Shares(raw), Decimals(6))
+        with pytest.raises(ValueError, match="0..255"):
+            format_amount(Amount(1), Decimals(256))
+
+    def test_shares_pair_mirrors_amounts(self):
+        from ipor_fusion import format_shares, parse_shares
+
+        assert parse_shares("2.5", Decimals(8)) == Shares(250_000_000)
+        assert format_shares(Shares(250_000_000), Decimals(8)) == "2.5"