ipor-fusion 4.0.0.dev110__tar.gz → 4.0.0.dev114__tar.gz

{ipor_fusion-4.0.0.dev110 → ipor_fusion-4.0.0.dev114}/MIGRATION_4.md

@@ -84,6 +84,20 @@ chain is always the context's:
   the context's default block and `Web3Context.get_block(block=None)` returns it,
   both instead of ``"latest"``.
 
+Snapshot fields carry their units: `VaultData.total_assets`,
+`underlying_balance_on_vault` and `market_balances` values are `Amount`;
+`total_supply` and `supply_cap` are `Shares`; `share_decimals` / `asset_decimals` are `Decimals`;
+`block_timestamp` and `deployment_timestamp` are `Timestamp`. `FeeData` fee fields
+are `Fee`, `management_fee_last_update` a `Timestamp`, `unrealized_management_fee` an
+`Amount`; `WithdrawManagerData.withdraw_window` is a `Period`, its fees `Fee`,
+`shares_to_release` `Shares`, `last_release_funds_timestamp` a `Timestamp` and the
+converted amounts `Amount`. A custom `VaultState` annotates the same.
+`PlasmaVault.total_supply()`, `balance_of()` and `get_total_supply_cap()` return
+`Shares` (vault shares), and `transfer` / `approve` / `transfer_from` /
+`set_total_supply_cap` take `Shares`; `ERC20` keeps `Amount`. The supply cap is
+now shown in share decimals labelled `shares` (``fusion vault info``) and its JSON
+``formatted`` uses `share_decimals`; it was formatted with the asset's decimals.
+
 `ensure_supported_chain` takes `ChainId`. `fetch_unpriceable_priced_tokens` takes the oracle and
 underlying as `ChecksumAddress`. `resolve_token_symbol`, `resolve_token_decimals`,
 `get_contract_name` and `get_deployment_tx` take `HexAddress` (a checksum address

{ipor_fusion-4.0.0.dev110 → ipor_fusion-4.0.0.dev114}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ipor-fusion
-Version: 4.0.0.dev110
+Version: 4.0.0.dev114
 Summary: The IPOR Fusion SDK for Python
 Project-URL: homepage, https://ipor.io
 Project-URL: repository, https://github.com/IPOR-Labs/ipor-fusion.py

{ipor_fusion-4.0.0.dev110 → ipor_fusion-4.0.0.dev114}/pyproject.toml

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

{ipor_fusion-4.0.0.dev110 → ipor_fusion-4.0.0.dev114}/src/ipor_fusion/cli/vault_info_view.py

@@ -185,7 +185,7 @@ def _print_supply(data: VaultData) -> None:
     else:
         click.echo(
             f"Supply Cap:       "
-            f"{_format_amount(data.supply_cap, data.asset_decimals)} {data.asset_symbol}"
+            f"{_format_amount(data.supply_cap, data.share_decimals)} shares"
         )
 
 

{ipor_fusion-4.0.0.dev110 → ipor_fusion-4.0.0.dev114}/src/ipor_fusion/core/plasma_vault.py

@@ -191,7 +191,7 @@ class PlasmaVault(ContractWrapper):
         `addFuses` steps must be reverted before the vault is usable."""
         return self._write("removeFuses(address[])", fuses)
 
-    def set_total_supply_cap(self, cap: Amount) -> Call[None]:
+    def set_total_supply_cap(self, cap: Shares) -> Call[None]:
         return self._write("setTotalSupplyCap(uint256)", cap)
 
     def convert_to_public_vault(self) -> Call[None]:
@@ -362,25 +362,26 @@ class PlasmaVault(ContractWrapper):
             "configureInstantWithdrawalFuses((address,bytes32[])[])", normalized
         )
 
-    def transfer(self, to: ChecksumAddress, value: Amount) -> Call[None]:
+    def transfer(self, to: ChecksumAddress, value: Shares) -> Call[None]:
         return self._write("transfer(address,uint256)", to, value)
 
-    def approve(self, account: ChecksumAddress, amount: Amount) -> Call[None]:
+    def approve(self, account: ChecksumAddress, amount: Shares) -> Call[None]:
         return self._write("approve(address,uint256)", account, amount)
 
     def transfer_from(
-        self, _from: ChecksumAddress, to: ChecksumAddress, amount: Amount
+        self, _from: ChecksumAddress, to: ChecksumAddress, amount: Shares
     ) -> Call[None]:
         return self._write("transferFrom(address,address,uint256)", _from, to, amount)
 
-    def balance_of(self, account: ChecksumAddress) -> Call[Amount]:
+    def balance_of(self, account: ChecksumAddress) -> Call[Shares]:
         return self._view(
-            "balanceOf(address)", account, output_types=["uint256"], decoder=Amount
+            "balanceOf(address)", account, output_types=["uint256"], decoder=Shares
         )
 
-    def get_total_supply_cap(self) -> Call[Amount]:
+    def get_total_supply_cap(self) -> Call[Shares]:
+        """The maximum total supply, in shares (``2**256 - 1``: uncapped)."""
         return self._view(
-            "getTotalSupplyCap()", output_types=["uint256"], decoder=Amount
+            "getTotalSupplyCap()", output_types=["uint256"], decoder=Shares
         )
 
     def max_withdraw(self, account: ChecksumAddress) -> Call[Amount]:
@@ -418,8 +419,8 @@ class PlasmaVault(ContractWrapper):
     def total_assets(self) -> Call[Amount]:
         return self._view("totalAssets()", output_types=["uint256"], decoder=Amount)
 
-    def total_supply(self) -> Call[Amount]:
-        return self._view("totalSupply()", output_types=["uint256"], decoder=Amount)
+    def total_supply(self) -> Call[Shares]:
+        return self._view("totalSupply()", output_types=["uint256"], decoder=Shares)
 
     def name(self) -> Call[str]:
         return self._view("name()", output_types=["string"])

{ipor_fusion-4.0.0.dev110 → ipor_fusion-4.0.0.dev114}/src/ipor_fusion/validation.py

@@ -13,6 +13,7 @@ from dataclasses import dataclass, field
 from typing import Protocol, TypeVar
 
 from eth_typing import ChecksumAddress
+from web3.types import Timestamp
 
 from ipor_fusion.core.context import Web3Context
 from ipor_fusion.core.plasma_vault import BalanceFuse
@@ -24,7 +25,15 @@ from ipor_fusion.dependency_graph import (
 from ipor_fusion.market_ids import IporFusionMarkets
 from ipor_fusion.readers.lending_health import VaultLendingHealth
 from ipor_fusion.substrates import decode_substrate, format_market_label
-from ipor_fusion.types import ChainId, FuseAddress, MarketId, PlasmaVaultAddress
+from ipor_fusion.types import (
+    Amount,
+    ChainId,
+    Decimals,
+    FuseAddress,
+    MarketId,
+    PlasmaVaultAddress,
+    Shares,
+)
 from ipor_fusion.types import Check as Check
 from ipor_fusion.types import Severity as Severity
 from ipor_fusion.types import Verdict as Verdict
@@ -57,9 +66,9 @@ class WithdrawQueue(Protocol):
     """The WithdrawManager state the reconciliation needs."""
 
     @property
-    def shares_to_release(self) -> int: ...
+    def shares_to_release(self) -> Shares: ...
     @property
-    def shares_to_release_assets(self) -> int | None: ...
+    def shares_to_release_assets(self) -> Amount | None: ...
 
 
 class UnpriceableToken(Protocol):
@@ -97,19 +106,19 @@ class VaultState(Protocol):
     @property
     def block_number(self) -> int: ...
     @property
-    def block_timestamp(self) -> int: ...
+    def block_timestamp(self) -> Timestamp: ...
     @property
     def asset(self) -> ChecksumAddress: ...
     @property
     def asset_symbol(self) -> str: ...
     @property
-    def asset_decimals(self) -> int: ...
+    def asset_decimals(self) -> Decimals: ...
     @property
     def asset_price_usd(self) -> float | None: ...
     @property
-    def total_assets(self) -> int: ...
+    def total_assets(self) -> Amount: ...
     @property
-    def underlying_balance_on_vault(self) -> int: ...
+    def underlying_balance_on_vault(self) -> Amount: ...
     @property
     def price_oracle_addr(self) -> ChecksumAddress: ...
     @property
@@ -129,7 +138,7 @@ class VaultState(Protocol):
     @property
     def unimplemented_getters(self) -> Sequence[str]: ...
     @property
-    def market_balances(self) -> Mapping[MarketId, int]: ...
+    def market_balances(self) -> Mapping[MarketId, Amount]: ...
     @property
     def erc20(self) -> Erc20Holdings: ...
 

{ipor_fusion-4.0.0.dev110 → ipor_fusion-4.0.0.dev114}/src/ipor_fusion/vault_data.py

@@ -18,7 +18,7 @@ from typing import Any, TypeVar
 from eth_typing import HexAddress
 from eth_utils import function_signature_to_4byte_selector
 from web3 import Web3
-from web3.types import ChecksumAddress
+from web3.types import ChecksumAddress, Timestamp
 
 from ipor_fusion.cache import CacheKey, cache_get, cache_key, cache_put
 from ipor_fusion.chains import ensure_supported_chain
@@ -57,10 +57,13 @@ from ipor_fusion.readers.unpriceable import (
 from ipor_fusion.substrates import decode_substrate
 from ipor_fusion.types import (
     AccessManagerAddress,
+    Amount,
     ChainId,
+    Decimals,
     FuseAddress,
     MarketId,
     PlasmaVaultAddress,
+    Shares,
     parse_hex_address,
 )
 from ipor_fusion.vault_erc20 import Erc20Holdings, _Asset, _read_erc20_holdings
@@ -115,12 +118,12 @@ class VaultData:
     chain_id: ChainId
     block_number: int
     is_latest: bool
-    block_timestamp: int
-    share_decimals: int
-    asset_decimals: int
-    total_assets: int
-    total_supply: int
-    supply_cap: int
+    block_timestamp: Timestamp
+    share_decimals: Decimals
+    asset_decimals: Decimals
+    total_assets: Amount
+    total_supply: Shares
+    supply_cap: Shares
     asset: ChecksumAddress
     asset_symbol: str
     access_manager: AccessManagerAddress
@@ -135,10 +138,10 @@ class VaultData:
     # totalAssets via ERC4626 base accounting; by design NOT tracked as an
     # ERC20_VAULT_BALANCE substrate, so it is read directly in
     # fetch_vault_data rather than derived from substrates.
-    underlying_balance_on_vault: int = 0
+    underlying_balance_on_vault: Amount = Amount(0)
     vault_name: str = ""
     deployment_block: int | None = None
-    deployment_timestamp: int | None = None
+    deployment_timestamp: Timestamp | None = None
     # Short error code from `fetch_deployment_info` when block/timestamp could
     # not be resolved. Surfaced in CLI output and the JSON `deployment` field
     # so users can distinguish "lookup not attempted/failed" from
@@ -186,7 +189,7 @@ class VaultData:
     unimplemented_getters: list[str] = field(default_factory=list)
     # totalAssetsInMarket of every balance-fuse market, once per market, in
     # balance-fuse order.
-    market_balances: dict[MarketId, int] = field(default_factory=dict)
+    market_balances: dict[MarketId, Amount] = field(default_factory=dict)
     # The ERC20_VAULT_BALANCE tokens read directly (empty without that market).
     erc20: Erc20Holdings = field(default_factory=Erc20Holdings)
     # Symbols (lowercase address keys) of the substrate and breakdown tokens,
@@ -215,7 +218,7 @@ def _fuse_market_id_call(fuse: ChecksumAddress) -> Call[int]:
     )
 
 
-_UNCAPPED = 2**256 - 1
+_UNCAPPED = Shares(2**256 - 1)
 
 
 def _missing_required_getter(
@@ -285,7 +288,7 @@ def resolve_token_decimals(ctx: Web3Context, address: HexAddress) -> int | None:
     return decimals
 
 
-def _block_timestamp(ctx: Web3Context, block: int) -> int:
+def _block_timestamp(ctx: Web3Context, block: int) -> Timestamp:
     return ctx.web3.eth.get_block(block)["timestamp"]
 
 
@@ -435,7 +438,7 @@ class _MarketReads:
     # Only markets with at least one substrate.
     market_substrates: dict[MarketId, list[bytes]]
     aave_pools: dict[MarketId, ChecksumAddress]
-    market_balances: dict[MarketId, int]
+    market_balances: dict[MarketId, Amount]
     # False when the vault predates getMarketSubstrates (substrates unknown).
     substrates_available: bool = True
 
@@ -763,7 +766,7 @@ def fetch_deployment_info(
     vault_address: PlasmaVaultAddress,
     *,
     api_key: str | None = None,
-) -> tuple[int | None, int | None, str | None]:
+) -> tuple[int | None, Timestamp | None, str | None]:
     """Return ``(block, timestamp, error)`` for the vault deployment, cached in
     ``ctx.cache``.
 
@@ -781,7 +784,7 @@ def fetch_deployment_info(
     block = _cached_int(cached, block_key)
     stamp = _cached_int(cached, time_key)
     if block is not None and stamp is not None:
-        return block, stamp, None
+        return block, Timestamp(stamp), None
 
     tx_hash, error = get_deployment_tx(chain_id, vault_address, api_key)
     if not tx_hash:
@@ -790,7 +793,7 @@ def fetch_deployment_info(
     try:
         tx = ctx.web3.eth.get_transaction(tx_hash)
         block_number: int = tx["blockNumber"]
-        timestamp: int = ctx.web3.eth.get_block(block_number)["timestamp"]
+        timestamp: Timestamp = ctx.web3.eth.get_block(block_number)["timestamp"]
     except Exception:
         return None, None, "rpc-fetch-failed"
     cache_put(ctx.cache, {block_key: str(block_number), time_key: str(timestamp)})

{ipor_fusion-4.0.0.dev110 → ipor_fusion-4.0.0.dev114}/src/ipor_fusion/vault_info.py

@@ -645,7 +645,7 @@ def _supply_cap_json(data: VaultData) -> dict[str, Any]:
         "formatted": (
             "unlimited"
             if data.supply_cap == UINT256_MAX
-            else _format_amount(data.supply_cap, data.asset_decimals)
+            else _format_amount(data.supply_cap, data.share_decimals)
         ),
     }
 

{ipor_fusion-4.0.0.dev110 → ipor_fusion-4.0.0.dev114}/src/ipor_fusion/vault_managers.py

@@ -7,7 +7,7 @@ from dataclasses import dataclass, field
 from functools import partial
 
 from eth_abi.exceptions import DecodingError
-from web3.types import ChecksumAddress
+from web3.types import ChecksumAddress, Timestamp
 
 from ipor_fusion.core.context import Web3Context
 from ipor_fusion.core.fee_manager import (
@@ -19,7 +19,7 @@ from ipor_fusion.core.fee_manager import (
 from ipor_fusion.core.plasma_vault import PlasmaVault
 from ipor_fusion.core.withdraw_manager import AccountRequest, WithdrawManager
 from ipor_fusion.errors import EmptyCallResultError
-from ipor_fusion.types import ZERO_ADDRESS, Shares
+from ipor_fusion.types import ZERO_ADDRESS, Amount, Fee, Period, Shares
 from ipor_fusion.vault_reads import _read_batch, _safe_call, _scan_or_none
 
 
@@ -41,15 +41,15 @@ class FeeData:
     configurations have drifted.
     """
 
-    performance_fee_vault_bps: int | None = None
-    management_fee_vault_bps: int | None = None
-    management_fee_last_update: int | None = None
-    unrealized_management_fee: int | None = None
+    performance_fee_vault_bps: Fee | None = None
+    management_fee_vault_bps: Fee | None = None
+    management_fee_last_update: Timestamp | None = None
+    unrealized_management_fee: Amount | None = None
     fee_manager: ChecksumAddress | None = None
     ipor_dao_fee_recipient: ChecksumAddress | None = None
-    deposit_fee_wad: int | None = None
-    performance_fee_manager_bps: int | None = None
-    management_fee_manager_bps: int | None = None
+    deposit_fee_wad: Fee | None = None
+    performance_fee_manager_bps: Fee | None = None
+    management_fee_manager_bps: Fee | None = None
     performance_fee_recipients: list[RecipientFee] | None = None
     management_fee_recipients: list[RecipientFee] | None = None
     high_water_mark: HighWaterMarkPerformanceFee | None = None
@@ -59,21 +59,21 @@ class FeeData:
 class WithdrawManagerData:
     """On-chain state snapshot from the WithdrawManager contract."""
 
-    withdraw_window: int
+    withdraw_window: Period
     # None (not 0) when the getter failed: a zero fee and an unreadable fee
     # are different facts, and the fees section reports both.
-    request_fee: int | None
-    withdraw_fee: int | None
-    shares_to_release: int
-    last_release_funds_timestamp: int
+    request_fee: Fee | None
+    withdraw_fee: Fee | None
+    shares_to_release: Shares
+    last_release_funds_timestamp: Timestamp
     # None when the WithdrawRequestUpdated scan or its reads failed.
     pending_requests: list[AccountRequest] | None
     # convertToAssets of shares_to_release at the snapshot block; None when
     # the read failed (or there is nothing to release: 0).
-    shares_to_release_assets: int | None = None
+    shares_to_release_assets: Amount | None = None
     # convertToAssets of each pending request's shares, by account; a failed
     # read is None.
-    pending_request_assets: dict[ChecksumAddress, int | None] = field(
+    pending_request_assets: dict[ChecksumAddress, Amount | None] = field(
         default_factory=dict
     )
 
@@ -108,11 +108,11 @@ def _fetch_withdraw_manager(
         ],
     )
     return address, WithdrawManagerData(
-        withdraw_window=window or 0,
+        withdraw_window=window or Period(0),
         request_fee=request_fee,
         withdraw_fee=withdraw_fee,
         shares_to_release=to_release,
-        last_release_funds_timestamp=last_ts or 0,
+        last_release_funds_timestamp=last_ts or Timestamp(0),
         pending_requests=pending,
         shares_to_release_assets=release_assets,
         pending_request_assets={

{ipor_fusion-4.0.0.dev110 → ipor_fusion-4.0.0.dev114}/tests/fixtures/vault_info_golden/clean.txt

@@ -11,7 +11,7 @@ Share decimals:   6
 Asset price:      N/A
 Total Assets:     0.0 USDC
 Total Supply:     0.0 shares
-Supply Cap:       1,000,000.0 USDC
+Supply Cap:       1,000,000.0 shares
 Access Manager:   0x00000000000000000000000000000000000000AC
 Price Oracle:     0x000000000000000000000000000000000000000C
 Rewards Manager:  N/A