ipor-fusion 4.0.0.dev126__tar.gz → 4.0.0.dev129__tar.gz

{ipor_fusion-4.0.0.dev126 → ipor_fusion-4.0.0.dev129}/MIGRATION_4.md

@@ -255,8 +255,11 @@ before passing it on.
 `HyperCorePendingState` and `HyperCoreTransferSnapshot` carry them.
 
 **External state.** `ExternalStateExecutor.proposal_hash` returns and `confirm_balance`
-takes a `ProposalHash`; `BalanceProposal.proposal_hash` and `NavMark.proposal_hash`
-are `ProposalHash`; `ExternalStateEvent.transaction_hash` is a `TxHash`.
+takes a `ProposalHash`; `BalanceProposal.proposal_hash` is a `ProposalHash`;
+`ExternalStateEvent.transaction_hash` is a `TxHash`.
+`ExternalStateExecutor.mark_nav` and `NavMark` are gone: send `propose_balance` and
+`confirm_balance` from separate custodians, then
+`PlasmaVault.update_markets_balances([IporFusionMarkets.EXTERNAL_STATE])`.
 
 **Errors and explorer.** `TransactionError(tx_hash=)` takes a `TxHash`,
 `LogScanError(address=)` a `ChecksumAddress`; `get_revert_reason` takes a `TxHash`;
@@ -349,7 +352,7 @@ placeholder wrapper.
   and `VaultSimulator.observe` stamp the same hash for the same bytes, whatever
   context executes them. Pass `ctx.chain_id` for the chain you read from.
   `pending_proposals` now refuses an executor at the zero address when the Call is
-  built, not when it is decoded. `mark_nav` takes the chain from its contexts.
+  built, not when it is decoded.
 
 | 3.x | 4.0 |
 |---|---|
@@ -560,10 +563,8 @@ is the wrong one.
   `parse_balance_proposed` / `find_balance_proposed` for one of the executor's own
   `BalanceProposed` logs whose data is missing or malformed (including data that is
   not hex at all, which raised `TypeError`) or whose hash is not the hash of its own
-  fields; and `mark_nav` when the propose receipt it fetched has no such log or
-  records another value or proposer. A log that is not the event or not from the
-  executor, and `find_balance_proposed` over logs that hold no match, are still
-  `ValueError`.
+  fields. A log that is not the event or not from the executor, and
+  `find_balance_proposed` over logs that hold no match, are still `ValueError`.
 - `ccip_token_lane` raises the new `UnsupportedContractVersionError` (still a
   `ValueError`) for an OnRamp version whose layout is not verified.
 - `quote_ccip_native_fee` raises `SimulationError` (label `"quote"`, with

{ipor_fusion-4.0.0.dev126 → ipor_fusion-4.0.0.dev129}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ipor-fusion
-Version: 4.0.0.dev126
+Version: 4.0.0.dev129
 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.dev126 → ipor_fusion-4.0.0.dev129}/examples/CONTRIBUTING.md

@@ -63,11 +63,7 @@ role-separation note is about. Label the collapse itself, not the calls: sending
 as two separate calls *is* the production shape, and only "both keys in one process" is
 simulation-only.
 
-Cross-reference the SDK method a production caller would use instead, where one exists -- but only
-where the SDK method is the one to reach for. `ExternalStateExecutor.mark_nav` is the counter-example:
-it composes both custodian calls, its own docstring warns that this "does not preserve the
-dual-custodian separation", and it is expected to be deprecated in favour of the two primitives. Do
-not point readers at it.
+Cross-reference the SDK method a production caller would use instead, where one exists.
 
 ## 3. One self-contained file
 

{ipor_fusion-4.0.0.dev126 → ipor_fusion-4.0.0.dev129}/examples/external_state_margin_leg_base.py

@@ -894,13 +894,6 @@ def run_simulation(web3: Web3) -> SimulationResult:
     # driven from this one process. In a real deployment they live in separate
     # systems -- if one process can send both, a single compromise moves the
     # vault's NAV and the two-party design has bought nothing.
-    #
-    # ExternalStateExecutor.mark_nav runs the propose, the confirm and -- when
-    # handed a vault -- the refresh in one call. It cannot be used here for a
-    # mechanical reason: it .send(ctx)s each leg, and nothing is broadcast under
-    # eth_simulateV1. It is also not what a production deployment wants, for the
-    # reason above: one process holding both custodian keys is one key wearing
-    # two hats.
     sim.next_block().with_block_time_shift(PROPOSE_OFFSET)
     sim.add_call(
         call=executor.propose_balance(VENUE_BALANCE_ACCOUNT, MARGIN_AMOUNT),

{ipor_fusion-4.0.0.dev126 → ipor_fusion-4.0.0.dev129}/pyproject.toml

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

{ipor_fusion-4.0.0.dev126 → ipor_fusion-4.0.0.dev129}/src/ipor_fusion/__init__.py

@@ -39,7 +39,6 @@ from ipor_fusion.core.external_state_executor import (
     BalanceProposal,
     ExternalStateExecutor,
     ExternalStateVaultState,
-    NavMark,
     RawLog,
     read_external_state,
 )
@@ -553,7 +552,6 @@ __all__ = [
     "BalanceFuseSnapshot",
     "ExternalStateVaultState",
     "read_external_state",
-    "NavMark",
     "CrosschainExecutor",
     "StargateCrosschainExecutor",
     "StargateCrosschainDispatcher",

{ipor_fusion-4.0.0.dev126 → ipor_fusion-4.0.0.dev129}/src/ipor_fusion/core/external_state_executor.py

@@ -6,20 +6,19 @@ by the external-state market. Its address lives in the VAULT's ERC-7201 storage
 
 NAV for the external-state market is marked by a dual-custodian propose/confirm
 on this executor, then a `update_markets_balances([EXTERNAL_STATE])` refresh on
-the vault. `mark_nav` runs that whole sequence in one process; a separate
-confirm service instead reads `pending_proposals` and confirms the hash it
-returns, never guessing the executor's global nonce. The same proposal reaches
-an offline reader through the `BalanceProposed` event -- `find_balance_proposed`
-picks it out of a receipt's logs, `parse_balance_proposed` decodes one row from
-an index -- and `balances` and `last_updated` report what the custodians last
-confirmed for an account.
+the vault. The confirming custodian's service reads `pending_proposals` and
+confirms the hash it returns, never guessing the executor's global nonce. The
+same proposal reaches an offline reader through the `BalanceProposed` event --
+`find_balance_proposed` picks it out of a receipt's logs,
+`parse_balance_proposed` decodes one row from an index -- and `balances` and
+`last_updated` report what the custodians last confirmed for an account.
 """
 
 from __future__ import annotations
 
 from collections.abc import Iterable, Mapping
 from dataclasses import dataclass, replace
-from typing import TYPE_CHECKING, Any
+from typing import Any
 
 from eth_abi import decode, encode
 from eth_abi.exceptions import DecodingError
@@ -27,25 +26,19 @@ from eth_typing import ChecksumAddress
 from eth_utils import keccak
 from hexbytes import HexBytes
 from web3 import Web3
-from web3.types import BlockIdentifier, TxReceipt
+from web3.types import BlockIdentifier
 
 from ipor_fusion.core.context import Web3Context
 from ipor_fusion.core.contract import Call, ContractWrapper
 from ipor_fusion.errors import ExternalStateError
-from ipor_fusion.market_ids import IporFusionMarkets
 from ipor_fusion.types import (
     ZERO_ADDRESS,
     Amount,
     ChainId,
-    MarketId,
     PlasmaVaultAddress,
     ProposalHash,
 )
 
-if TYPE_CHECKING:
-    from ipor_fusion.core.plasma_vault import PlasmaVault
-
-
 # The log shapes the event readers below accept: a receipt log from web3.py
 # (HexBytes fields, checksummed address), and a raw JSON-RPC or
 # `eth_simulateV1` row (0x-hex strings, lowercase address). Looser than
@@ -108,17 +101,6 @@ def _hash_of(
     )
 
 
-def _no_balance_proposed(
-    executor: ChecksumAddress, balance_account: ChecksumAddress | None
-) -> str:
-    for_account = (
-        f" for account {Web3.to_checksum_address(balance_account)}"
-        if balance_account is not None
-        else ""
-    )
-    return f"no BalanceProposed log from executor {executor}{for_account}"
-
-
 def _require_matching_hash(
     proposal: BalanceProposal, *, executor: ChecksumAddress, chain_id: ChainId
 ) -> None:
@@ -141,22 +123,6 @@ def _require_matching_hash(
         )
 
 
-@dataclass(frozen=True, slots=True)
-class NavMark:
-    """Outcome of a `mark_nav` run: the confirmed proposal plus every receipt.
-
-    `refresh_receipt` is `None` when `mark_nav` was called without a `vault`
-    (propose + confirm only, no cached-NAV refresh).
-    """
-
-    proposed_at: int
-    nonce: int
-    proposal_hash: ProposalHash
-    propose_receipt: TxReceipt
-    confirm_receipt: TxReceipt
-    refresh_receipt: TxReceipt | None
-
-
 @dataclass(frozen=True, slots=True)
 class ExternalStateVaultState:
     """The external-state market's vault-scoped state, read from the vault's
@@ -516,7 +482,8 @@ class ExternalStateExecutor(ContractWrapper):
     ) -> Call[None]:
         """CUSTODIAN-only: propose `value` (underlying units) as the new tracked
         balance of `balance_account`. Confirm it from a *different* custodian
-        with `confirm_balance`; see `mark_nav` for the full sequence."""
+        with `confirm_balance`, then refresh the vault's cached NAV with
+        `PlasmaVault.update_markets_balances([EXTERNAL_STATE])`."""
         return self._write("proposeBalance(address,uint256)", balance_account, value)
 
     def confirm_balance(
@@ -743,18 +710,6 @@ class ExternalStateExecutor(ContractWrapper):
         silently skips, and over a range you filtered yourself a foreign log
         means the filter is wrong, not that the row is uninteresting.
         """
-        found = self._last_balance_proposed(logs, balance_account, chain_id)
-        if found is not None:
-            return found
-        raise ValueError(_no_balance_proposed(self._address, balance_account))
-
-    def _last_balance_proposed(
-        self,
-        logs: Iterable[RawLog],
-        balance_account: ChecksumAddress | None,
-        chain_id: ChainId,
-    ) -> BalanceProposal | None:
-        """`find_balance_proposed` without the raise when nothing matches."""
         self._require_address()
         wanted = (
             Web3.to_checksum_address(balance_account)
@@ -770,111 +725,16 @@ class ExternalStateExecutor(ContractWrapper):
             proposal = self._decode_balance_proposed(log)
             if wanted is None or proposal.balance_account == wanted:
                 found = proposal
-        if found is not None:
-            # Outside the loop: one hash instead of N, and only over the log
-            # actually being returned.
-            _require_matching_hash(
-                found,
-                executor=self._address,
-                chain_id=chain_id,
-            )
-        return found
-
-    def mark_nav(
-        self,
-        *,
-        value: Amount,
-        balance_account: ChecksumAddress,
-        proposer_ctx: Web3Context,
-        confirmer_ctx: Web3Context,
-        vault: PlasmaVault | None = None,
-    ) -> NavMark:
-        """Mark the external-state NAV: propose `value` (custodian A), confirm it
-        (custodian B), and optionally refresh the vault's cached NAV.
-
-        `proposer_ctx` signs the propose; `confirmer_ctx` signs the confirm (and,
-        when `vault` is given, the `update_markets_balances([EXTERNAL_STATE])`
-        refresh). The two signers MUST be different custodians, and MUST be on
-        the same chain; both are checked before the propose is sent, since the
-        hash is chain-bound and a mismatch would otherwise only surface with a
-        proposal already stranded on the proposer's chain. The confirm hash,
-        nonce, and timestamp are taken from the propose tx's `BalanceProposed`
-        event -- exactly what the contract stored, so no read can race the
-        executor's global nonce. Returns a `NavMark` with the proposal and every
-        receipt.
-
-        The marked balance is valued into the vault's `totalAssets` via the
-        external-state market (50), so it moves the share price; the refresh is
-        what propagates the new value into the vault's cached NAV.
-
-        Sends up to three transactions and blocks on each; see `NavMark`. If the
-        propose receipt does not record the value and proposer this call sent,
-        or carries a hash that is not the hash of those fields, it raises rather
-        than confirming -- note the propose transaction has already landed at
-        that point, leaving a pending proposal behind.
-
-        Security: mark_nav composes `propose_balance` + `confirm_balance`, so it
-        needs both custodian keys in one process and does not preserve the
-        dual-custodian separation. When that separation is the point, run the two
-        primitives from separate services instead.
-        """
-        proposer = proposer_ctx.signer
-        confirmer = confirmer_ctx.signer
-        if proposer is None:
-            raise ValueError("proposer_ctx must have a signer")
-        if confirmer is None:
-            raise ValueError("confirmer_ctx must have a signer")
-        proposer_address = Web3.to_checksum_address(proposer)
-        if proposer_address == Web3.to_checksum_address(confirmer):
-            raise ValueError("proposer and confirmer must be different custodians")
-        if proposer_ctx.chain_id != confirmer_ctx.chain_id:
+        if found is None:
+            for_account = f" for account {wanted}" if wanted is not None else ""
             raise ValueError(
-                f"proposer_ctx is on chain {proposer_ctx.chain_id} but "
-                f"confirmer_ctx is on {confirmer_ctx.chain_id}; both custodians "
-                "must sign on the same chain"
+                f"no BalanceProposed log from executor {self._address}{for_account}"
             )
-
-        propose_receipt = self.propose_balance(balance_account, value).send(
-            proposer_ctx
-        )
-        # Verified against the CONFIRMER's chain, which is the one the confirm
-        # will be checked on (validated equal to the proposer's above).
-        proposal = self._last_balance_proposed(
-            propose_receipt["logs"], balance_account, confirmer_ctx.chain_id
-        )
-        if proposal is None:
-            raise ExternalStateError(
-                "the propose receipt records "
-                + _no_balance_proposed(self._address, balance_account)
-            )
-        # The receipt is data from the node, so confirm only what we asked for:
-        # signing off on a proposal that differs from the one just sent would
-        # attest a value this call never chose.
-        if proposal.value != value:
-            raise ExternalStateError(
-                f"proposed {value} but the receipt records {proposal.value}; "
-                "refusing to confirm"
-            )
-        if proposal.proposer != proposer_address:
-            raise ExternalStateError(
-                f"proposal was made by {proposal.proposer}, not {proposer_address}; "
-                "refusing to confirm"
-            )
-        confirm_receipt = self.confirm_balance(
-            balance_account, proposal.proposal_hash
-        ).send(confirmer_ctx)
-
-        refresh_receipt: TxReceipt | None = None
-        if vault is not None:
-            refresh_receipt = vault.update_markets_balances(
-                [MarketId(IporFusionMarkets.EXTERNAL_STATE)]
-            ).send(confirmer_ctx)
-
-        return NavMark(
-            proposed_at=proposal.proposed_at,
-            nonce=proposal.nonce,
-            proposal_hash=proposal.proposal_hash,
-            propose_receipt=propose_receipt,
-            confirm_receipt=confirm_receipt,
-            refresh_receipt=refresh_receipt,
+        # Outside the loop: one hash instead of N, and only over the log
+        # actually being returned.
+        _require_matching_hash(
+            found,
+            executor=self._address,
+            chain_id=chain_id,
         )
+        return found

{ipor_fusion-4.0.0.dev126 → ipor_fusion-4.0.0.dev129}/src/ipor_fusion/errors.py

@@ -212,10 +212,9 @@ class HyperCoreValuationError(IporFusionError, ValueError):
 
 class ExternalStateError(IporFusionError, ValueError):
     """The external-state market's on-chain data is not usable: the vault's
-    storage holds no executor or a malformed word, an executor's
+    storage holds no executor or a malformed word, or an executor's
     ``BalanceProposed`` log is malformed or carries a hash that is not the hash
-    of its own fields, or a propose receipt does not record the proposal that
-    was sent.
+    of its own fields.
 
     Also a ValueError, the type these failures had before 4.0.
     """