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

{ipor_fusion-4.0.0.dev122 → ipor_fusion-4.0.0.dev129}/AGENTS.md

@@ -161,11 +161,16 @@ the lifecycle matrix follows that.
   public modules (`about`, `cache`, `chains`, `dependency_graph`, `errors`, `explorer`,
   `field_docs`, `market_ids`, `market_info`, `morpho_api`, `substrates`, `types`,
   `validation`, `vault_data`, `vault_info`) stay importable for the names they
-  define; `cli`, `mcp` and every other module are internal. Examples, the guide
-  and the skill import from `ipor_fusion` or a public module, never an internal
+  define and the moved names README lists; `cli`, `mcp`, every other module and
+  every submodule of a public subpackage (`core.contract`, `fuses.base`, ...) are
+  internal. Examples, the guide, the skill and `scripts/` import from
+  `ipor_fusion`, a public subpackage or a public module, never an internal
   path. Adding or removing a
-  name updates the snapshot in `tests/test_public_api.py`; a removal or rename
-  is a breaking change. The package is `py.typed`, so public APIs stay fully
+  name updates the snapshots in `tests/test_public_api.py` (every `__all__`, and
+  the names each public module keeps by path); moving a name out of a public
+  module leaves a re-export there. A removal or rename is a breaking change.
+  A project type used in a public signature or field is exported too
+  (`tests/test_public_type_reachability.py`). The package is `py.typed`, so public APIs stay fully
   annotated.
 
 ## Invariants that must change together
@@ -395,8 +400,9 @@ role-accounts, oracle-mapping). `vault info` runs independent fetch pipelines
 (vault/asset, fees, WithdrawManager, markets, roles) concurrently on a
 `ThreadPoolExecutor`, each a short chain of `Multicall3` batches; keep new
 reads inside a batch rather than adding per-call round trips. A `from_url` context
-bounds requests in flight (`max_concurrent_requests`, default 8) whatever the pool
-nesting, so a new fan-out does not need its own limit. Contract names,
+bounds requests in flight (`max_concurrent_requests`, default 8; an
+`InFlightLimit` shares one bound across contexts) whatever the pool nesting, so a
+new fan-out does not need its own limit. Contract names,
 token symbols and decimals and deployment blocks are cached per chain in
 `$XDG_CACHE_HOME/ipor-fusion/contract_cache.json` (`<chain>:<address>:<field>`
 keys); tests redirect it with `monkeypatch.setenv("XDG_CACHE_HOME", ...)` or

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

@@ -56,7 +56,11 @@ a `bytes32` return (recall) request is `ReturnRequestId`.
 names earlier reachable only by module path (`FusionFactory`, `FusionInstance`,
 `fetch_market`, `resolve_token_symbol`, the crosschain codecs, ...). Import from
 `ipor_fusion`: a module path outside the README's list (*Public API and stability*)
-still works but is internal.
+still works but is internal. Every project type a public signature or field uses is
+exported too, among them `AaveV3PositionBreakdown`, `AaveV3ReserveTokens`,
+`AccountRequest`, `StateOverrideProvider`, `TransferDirection` and the validation
+vocabulary `Severity`, `Verdict` and `Check`. Also new: `InFlightLimit` (below) and
+`log_bytes`, the hex-or-bytes log field helper the crosschain decoders use.
 
 **Vault reads and validation.** The vault read is one pinned snapshot, and the
 chain is always the context's:
@@ -110,8 +114,13 @@ now shown in share decimals labelled `shares` (``fusion vault info``) and its JS
 `Web3Context.from_url(..., max_concurrent_requests=8)` bounds the RPC requests in
 flight across every thread using the context (``None`` lifts the bound); the vault
 reads fan out on nested thread pools, and the bound is what a rate-limited provider
-sees. A context built from your own `Web3` object is not bounded unless you add the
-same middleware.
+sees. An `int` bounds one context. To bound several contexts on one provider (a
+service that builds a context per request or per scan), create one
+`InFlightLimit(n)` per provider and pass it as `max_concurrent_requests=`: every
+context built with it shares the same `n` slots. A context built from your own
+`Web3` object is not bounded unless you add the limit to it:
+`limit.install(web3)` (innermost, as `from_url` does) or
+`web3.middleware_onion.inject(limit.middleware, layer=0)`.
 
 `ensure_supported_chain` takes `ChainId`. `fetch_unpriceable_priced_tokens` takes the oracle and
 underlying as `ChecksumAddress`. `resolve_token_symbol`, `resolve_token_decimals`,
@@ -197,7 +206,13 @@ keyword arguments only. `ZERO_ADDRESS` is a `ChecksumAddress` (same value).
 `HYPERCORE_PENDING_READERS` are keyed by `ChainId` (`HYPEREVM_CHAIN_ID` is one) and
 `explorer.SUPPORTED_CHAINS` is a `frozenset[ChainId]`, so
 `ensure_supported_chain(CHAIN_NAME_TO_ID["ethereum"])` type-checks;
-`PUBLIC_ALLOCATOR_ADDRESSES` values are `ChecksumAddress`. `IporFusionMarkets.RWA`
+`PUBLIC_ALLOCATOR_ADDRESSES` values are `ChecksumAddress`. Import `CHAIN_NAMES`,
+`CHAIN_NAME_TO_ID`, `SUPPORTED_CHAIN_IDS`, `GET_LOGS_RANGE_HINTS`,
+`PUBLIC_ALLOCATOR_ADDRESSES`, `HYPERCORE_PENDING_READERS`, `HYPEREVM_CHAIN_ID` and
+`HYPERCORE_MARKET` from `ipor_fusion` (the HyperCore ones also from
+`ipor_fusion.readers`). `BLOCK_EXPLORER_URLS`, `MORPHO_BLUE_ADDRESSES`,
+`AAVE_V3_POOL` and `explorer.SUPPORTED_CHAINS` are internal: use
+`morpho_blue_address(chain_id)` for Morpho Blue. `IporFusionMarkets.RWA`
 is gone: market 50 is `IporFusionMarkets.EXTERNAL_STATE`. `MORPHO_BLUE_ADDRESS` is
 gone: use `morpho_blue_address(chain_id)`.
 
@@ -240,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`;
@@ -253,8 +271,10 @@ except below): `chain_id` fields are `ChainId`, `role_id` `RoleId`, `market_id`
 `MarketId`. Calling an MCP tool function directly from Python takes `ChainId`.
 
 **Fuse base.** `Fuse`, `StakeFuse` and the shared validators and substrate packers
-live in `ipor_fusion.core.fuse`; `ipor_fusion.fuses.base`, `ipor_fusion.fuses` and
-`ipor_fusion` re-export them, so existing imports keep working. Fuse equality and
+moved to `ipor_fusion.core.fuse`. Import `Fuse` and `StakeFuse` from `ipor_fusion`
+or `ipor_fusion.fuses`. `ipor_fusion.fuses.base` still re-exports them in 4.0, but
+it is a submodule of a public subpackage and therefore internal (see the README,
+*Public API and stability*); so are the underscore validators and packers. Fuse equality and
 hash now cover every attribute a fuse stores, not only its class and address (see
 [Behavior changes](#behavior-changes)).
 
@@ -267,9 +287,7 @@ unchanged.
 | 3.x import | 4.0 import |
 |---|---|
 | `ipor_fusion.fuses.crosschain` | `ipor_fusion.crosschain.fuses` (or `ipor_fusion.crosschain`) |
-| `ipor_fusion.fuses.crosschain.base` | `ipor_fusion.crosschain.fuses.base` |
-| `ipor_fusion.fuses.crosschain.ccip` | `ipor_fusion.crosschain.fuses.ccip` |
-| `ipor_fusion.fuses.crosschain.stargate` | `ipor_fusion.crosschain.fuses.stargate` |
+| `ipor_fusion.fuses.crosschain.base`, `.ccip`, `.stargate` | `ipor_fusion.crosschain.fuses` (its submodules `base`, `ccip` and `stargate` exist but are internal) |
 | `from ipor_fusion.fuses import CcipCrosschainSupplyFuse` (and the other crosschain encoders, `SendParams`, `CrosschainSubstrate*`, `crosschain_market_id`) | `from ipor_fusion.crosschain import ...` or `from ipor_fusion import ...` |
 
 `ipor_fusion.crosschain` now exports the whole crosschain surface: besides the
@@ -280,8 +298,9 @@ the transports and chains, `discover_deployment`, `open_lane(s)`, `LANES` and
 and wrappers.
 
 **Moved, still importable.** `FuseAction` lives in `ipor_fusion.core.fuse_action` and
-`ZERO_ADDRESS` in `ipor_fusion.types`; both are re-exported from
-`ipor_fusion.fuses.base` and `FuseAction` from `ipor_fusion`. The CLI's internal
+`ZERO_ADDRESS` in `ipor_fusion.types`; import both from `ipor_fusion` (`FuseAction`
+also from `ipor_fusion.fuses`, `ZERO_ADDRESS` from the public module
+`ipor_fusion.types`). The internal `ipor_fusion.fuses.base` still re-exports them. The CLI's internal
 `ipor_fusion.cli.vault_cmd` was split into `options`, `vault_info_view`,
 `vault_markets_view` and `oracle_mapping_view` (private names, not API).
 
@@ -333,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 |
 |---|---|
@@ -544,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.dev122 → ipor_fusion-4.0.0.dev129}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ipor-fusion
-Version: 4.0.0.dev122
+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
@@ -383,16 +383,23 @@ release; adding one does not.
 - **Public modules** stay importable for the top-level names they define:
   `about`, `cache`, `chains`, `dependency_graph`, `errors`, `explorer`, `field_docs`,
   `market_ids`, `market_info`, `morpho_api`, `substrates`, `types`, `validation`,
-  `vault_data` and `vault_info` (all under `ipor_fusion.`).
+  `vault_data` and `vault_info` (all under `ipor_fusion.`). A name that moved out of
+  one of them keeps its old path there (`vault_data.FeeData`,
+  `vault_data.WithdrawManagerData`, `validation.Erc20Holding`,
+  `validation.Erc20Holdings`, `morpho_api.MorphoApiError`).
 - **Internal:** `ipor_fusion.cli`, `ipor_fusion.mcp`, every other module (e.g.
-  `vault_reads`, the submodules of the public subpackages), underscore
-  names, and names in no `__all__`. They change without notice; the CLI and the
-  MCP server are stable as commands and tools, not as Python modules.
+  `vault_reads`) and every submodule of a public subpackage (e.g.
+  `ipor_fusion.core.contract`, `ipor_fusion.fuses.base`; import their names from
+  the subpackage or `ipor_fusion`), underscore names, and names in no `__all__`.
+  They change without notice; the CLI and the MCP server are stable as commands
+  and tools, not as Python modules.
 - **Preview features** (`PREVIEW_FEATURES` in `ipor_fusion.about`: crosschain,
   HyperCore) are exported like the rest but may change in a minor release.
 
-`tests/test_public_api.py` snapshots every `__all__`, so a change to the surface
-is a deliberate, reviewed edit.
+`tests/test_public_api.py` snapshots every `__all__` and the names each public
+module keeps by path, so a change to the surface is a deliberate, reviewed edit.
+`tests/test_public_type_reachability.py` fails when a public signature or field
+uses a project type that no `__all__` exports.
 
 ## Architecture
 

{ipor_fusion-4.0.0.dev122 → ipor_fusion-4.0.0.dev129}/README.md

@@ -335,16 +335,23 @@ release; adding one does not.
 - **Public modules** stay importable for the top-level names they define:
   `about`, `cache`, `chains`, `dependency_graph`, `errors`, `explorer`, `field_docs`,
   `market_ids`, `market_info`, `morpho_api`, `substrates`, `types`, `validation`,
-  `vault_data` and `vault_info` (all under `ipor_fusion.`).
+  `vault_data` and `vault_info` (all under `ipor_fusion.`). A name that moved out of
+  one of them keeps its old path there (`vault_data.FeeData`,
+  `vault_data.WithdrawManagerData`, `validation.Erc20Holding`,
+  `validation.Erc20Holdings`, `morpho_api.MorphoApiError`).
 - **Internal:** `ipor_fusion.cli`, `ipor_fusion.mcp`, every other module (e.g.
-  `vault_reads`, the submodules of the public subpackages), underscore
-  names, and names in no `__all__`. They change without notice; the CLI and the
-  MCP server are stable as commands and tools, not as Python modules.
+  `vault_reads`) and every submodule of a public subpackage (e.g.
+  `ipor_fusion.core.contract`, `ipor_fusion.fuses.base`; import their names from
+  the subpackage or `ipor_fusion`), underscore names, and names in no `__all__`.
+  They change without notice; the CLI and the MCP server are stable as commands
+  and tools, not as Python modules.
 - **Preview features** (`PREVIEW_FEATURES` in `ipor_fusion.about`: crosschain,
   HyperCore) are exported like the rest but may change in a minor release.
 
-`tests/test_public_api.py` snapshots every `__all__`, so a change to the surface
-is a deliberate, reviewed edit.
+`tests/test_public_api.py` snapshots every `__all__` and the names each public
+module keeps by path, so a change to the surface is a deliberate, reviewed edit.
+`tests/test_public_type_reachability.py` fails when a public signature or field
+uses a project type that no `__all__` exports.
 
 ## Architecture
 

{ipor_fusion-4.0.0.dev122 → 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.dev122 → 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.dev122 → ipor_fusion-4.0.0.dev129}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ipor-fusion"
-version = "4.0.0.dev122"
+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.dev122 → ipor_fusion-4.0.0.dev129}/scripts/crosschain_readiness.py

@@ -41,8 +41,7 @@ from eth_utils import function_signature_to_4byte_selector, keccak
 from web3 import Web3
 from web3.types import RPCEndpoint
 
-from ipor_fusion import ERC20, Web3Context, ccip_token_lane
-from ipor_fusion.core.contract import Call
+from ipor_fusion import ERC20, Call, Web3Context, ccip_token_lane
 from ipor_fusion.crosschain import CcipCrosschainFactory, CcipOffRamp, CcipRouter
 from ipor_fusion.types import ChainId
 

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

@@ -31,7 +31,7 @@ from ipor_fusion.core.access import (
     resolve_access_manager,
     role_account_sort_key,
 )
-from ipor_fusion.core.context import Web3Context
+from ipor_fusion.core.context import InFlightLimit, Web3Context
 from ipor_fusion.core.contract import Call
 from ipor_fusion.core.erc20 import ERC20
 from ipor_fusion.core.external_state_executor import (
@@ -39,7 +39,6 @@ from ipor_fusion.core.external_state_executor import (
     BalanceProposal,
     ExternalStateExecutor,
     ExternalStateVaultState,
-    NavMark,
     RawLog,
     read_external_state,
 )
@@ -69,11 +68,13 @@ from ipor_fusion.core.rewards_manager import RewardsManager, VestingData
 from ipor_fusion.core.simulation import (
     SimulatedCallResult,
     SimulationResult,
+    StateOverrideProvider,
     VaultSimulator,
     erc20_balance_slot,
     is_simulate_v1_supported,
 )
 from ipor_fusion.core.withdraw_manager import (
+    AccountRequest,
     PendingRequestsInfo,
     WithdrawManager,
     WithdrawRequestInfo,
@@ -183,6 +184,7 @@ from ipor_fusion.crosschain import (
     encode_oft_compose_msg,
     fetch_verifier_result,
     find_ccip_events,
+    log_bytes,
     lz_compose_calldata,
     lz_receive_calldata,
     manual_execution,
@@ -332,9 +334,14 @@ from ipor_fusion.morpho_api import (
     fetch_vault,
 )
 from ipor_fusion.readers import (
+    HYPERCORE_MARKET,
+    HYPERCORE_PENDING_READERS,
+    HYPEREVM_CHAIN_ID,
     AaveV3FuseReader,
     AaveV3PoolAddressesProvider,
+    AaveV3PositionBreakdown,
     AaveV3Reader,
+    AaveV3ReserveTokens,
     AaveV3UserAccountData,
     AaveV4OracleReader,
     AaveV4SpokeReader,
@@ -375,6 +382,7 @@ from ipor_fusion.readers import (
     PositionData,
     RamsesV2Position,
     RamsesV2Reader,
+    TransferDirection,
     UniswapV3Position,
     UniswapV3Reader,
     VaultLendingHealth,
@@ -404,6 +412,7 @@ from ipor_fusion.types import (
     AssetId,
     AssetSource,
     ChainId,
+    Check,
     CommandId,
     Decimals,
     DeploymentRequestId,
@@ -432,12 +441,14 @@ from ipor_fusion.types import (
     ProposalId,
     ReturnRequestId,
     RoleId,
+    Severity,
     Shares,
     StargateAssetId,
     Tick,
     TokenId,
     TransferId,
     TxHash,
+    Verdict,
     parse_access_manager_address,
     parse_fuse_address,
     parse_hex_address,
@@ -497,6 +508,7 @@ __all__ = [
     "read_changelog",
     "repository_url",
     "Web3Context",
+    "InFlightLimit",
     "Call",
     "get_logs_adaptive",
     "find_creation_block",
@@ -504,6 +516,7 @@ __all__ = [
     "Multicall3",
     "MULTICALL3_ADDRESS",
     "VaultSimulator",
+    "StateOverrideProvider",
     "SimulationResult",
     "SimulatedCallResult",
     "is_simulate_v1_supported",
@@ -517,6 +530,7 @@ __all__ = [
     "VestingData",
     "ERC20",
     "WithdrawManager",
+    "AccountRequest",
     "FeeAccount",
     "FeeManager",
     "RecipientFee",
@@ -538,7 +552,6 @@ __all__ = [
     "BalanceFuseSnapshot",
     "ExternalStateVaultState",
     "read_external_state",
-    "NavMark",
     "CrosschainExecutor",
     "StargateCrosschainExecutor",
     "StargateCrosschainDispatcher",
@@ -563,6 +576,7 @@ __all__ = [
     "CcipChain",
     "CrosschainSimulator",
     "CrosschainLane",
+    "log_bytes",
     "StargateLane",
     "CcipLane",
     "LaneFuses",
@@ -820,12 +834,17 @@ __all__ = [
     "morpho_blue_address",
     "AaveV3FuseReader",
     "AaveV3PoolAddressesProvider",
+    "AaveV3PositionBreakdown",
     "AaveV3Reader",
+    "AaveV3ReserveTokens",
     "AaveV3UserAccountData",
     "AaveV4OracleReader",
     "AaveV4SpokeReader",
     "AaveV4UserAccountData",
     "CompoundV3Reader",
+    "HYPERCORE_MARKET",
+    "HYPERCORE_PENDING_READERS",
+    "HYPEREVM_CHAIN_ID",
     "HyperCoreAccountMarginSummary",
     "HyperCoreActionClass",
     "HyperCoreEvmExitCeiling",
@@ -843,6 +862,7 @@ __all__ = [
     "HyperCoreTransferOutcome",
     "HyperCoreTransferSnapshot",
     "HyperCoreTransferStatus",
+    "TransferDirection",
     "compare_hypercore_transfer",
     "read_hypercore_evm_exit_ceiling",
     "read_hypercore_transfer_outcome",
@@ -871,6 +891,9 @@ __all__ = [
     "Erc20Holding",
     "Erc20Holdings",
     "Finding",
+    "Severity",
+    "Verdict",
+    "Check",
     "Reconciliation",
     "UnpriceableToken",
     "VaultState",

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

@@ -1,5 +1,5 @@
 from ipor_fusion.core.access import AccessManager, RoleAccount, RoleStatus
-from ipor_fusion.core.context import Web3Context
+from ipor_fusion.core.context import InFlightLimit, Web3Context
 from ipor_fusion.core.erc20 import ERC20
 from ipor_fusion.core.fee_manager import (
     FeeAccount,
@@ -23,6 +23,7 @@ from ipor_fusion.core.plasma_vault import (
 )
 from ipor_fusion.core.rewards_manager import RewardsManager, VestingData
 from ipor_fusion.core.withdraw_manager import (
+    AccountRequest,
     PendingRequestsInfo,
     WithdrawManager,
     WithdrawRequestInfo,
@@ -30,6 +31,7 @@ from ipor_fusion.core.withdraw_manager import (
 
 __all__ = [
     "Web3Context",
+    "InFlightLimit",
     "Multicall3",
     "MULTICALL3_ADDRESS",
     "PlasmaVault",
@@ -40,6 +42,7 @@ __all__ = [
     "VestingData",
     "ERC20",
     "WithdrawManager",
+    "AccountRequest",
     "WithdrawRequestInfo",
     "PendingRequestsInfo",
     "BalanceFuse",

{ipor_fusion-4.0.0.dev122 → ipor_fusion-4.0.0.dev129}/src/ipor_fusion/core/context.py

@@ -170,11 +170,15 @@ class Web3Context:
         log_scan_max_requests: int | None = DEFAULT_LOG_SCAN_MAX_REQUESTS,
         log_source: LogSource | None = None,
         cache: ContractCache | None = None,
-        max_concurrent_requests: int | None = DEFAULT_MAX_CONCURRENT_REQUESTS,
+        max_concurrent_requests: int
+        | InFlightLimit
+        | None = DEFAULT_MAX_CONCURRENT_REQUESTS,
     ) -> Web3Context:
         """A context on an HTTP provider at ``url``. ``max_concurrent_requests``
-        bounds the RPC requests in flight across every thread using it
-        (``None``: unbounded)."""
+        bounds the RPC requests in flight: an ``int`` across every thread using
+        this context, an `InFlightLimit` across every context and `Web3` it is
+        installed on (share one per provider in a service that builds a context
+        per request); ``None`` leaves them unbounded."""
         web3 = Web3(
             Web3.HTTPProvider(
                 url,
@@ -192,15 +196,11 @@ class Web3Context:
         # with a ValueError. The middleware moves it to proofOfAuthorityData
         # and leaves every other block untouched.
         web3.middleware_onion.inject(ExtraDataToPOAMiddleware, layer=0)
+        if isinstance(max_concurrent_requests, int):
+            max_concurrent_requests = InFlightLimit(max_concurrent_requests)
         if max_concurrent_requests is not None:
-            # Innermost (layer 0, injected last): a slot covers only the provider
-            # call, so a middleware that issues its own request (the gas price
-            # strategy reads a block) never waits on the slot it already holds.
-            web3.middleware_onion.inject(
-                _in_flight_limit(max_concurrent_requests),
-                name="in_flight_limit",
-                layer=0,
-            )
+            # Injected last, so innermost (see `InFlightLimit.install`).
+            max_concurrent_requests.install(web3)
         chain_id = ChainId(web3.eth.chain_id)
 
         return cls(
@@ -417,15 +417,43 @@ class Web3Context:
         return value * percentage // 100
 
 
-def _in_flight_limit(limit: int) -> type[Web3Middleware]:
-    """A middleware class (web3 instantiates it per Web3) holding a semaphore
-    slot for the duration of each provider call; a JSON-RPC batch is one HTTP
-    request, so it takes one slot whatever its item count."""
-    if limit < 1:
-        raise ValueError(f"max_concurrent_requests must be at least 1, got {limit}")
-    slots = threading.BoundedSemaphore(limit)
+class InFlightLimit:
+    """A bound on the RPC requests in flight, shareable across `Web3` objects.
+
+    Every `Web3` it is installed on (``install``, or
+    ``Web3Context.from_url(max_concurrent_requests=limit)``) takes a slot from
+    the same semaphore for each provider call, so several contexts on one
+    provider, or a service that builds a context per request, stay within
+    ``limit`` in total. A JSON-RPC batch is one HTTP request and takes one slot
+    whatever its item count; a failed request releases its slot.
+    """
+
+    def __init__(self, limit: int):
+        if limit < 1:
+            raise ValueError(f"an in-flight limit must be at least 1, got {limit}")
+        self._limit = limit
+        self._middleware = _slot_middleware(threading.BoundedSemaphore(limit))
+
+    @property
+    def limit(self) -> int:
+        return self._limit
+
+    @property
+    def middleware(self) -> type[Web3Middleware]:
+        """The middleware class to add to a `Web3` by hand; every instance
+        web3 builds from it shares this limit's slots."""
+        return self._middleware
+
+    def install(self, web3: Web3) -> None:
+        """Add the limit to ``web3`` as its innermost middleware
+        (``in_flight_limit``). A slot then covers only the provider call, so a
+        middleware that issues its own request (the gas price strategy reads a
+        block) never waits on the slot it already holds."""
+        web3.middleware_onion.inject(self._middleware, name="in_flight_limit", layer=0)
+
 
-    class InFlightLimit(Web3Middleware):
+def _slot_middleware(slots: threading.BoundedSemaphore) -> type[Web3Middleware]:
+    class InFlightLimitMiddleware(Web3Middleware):
         def wrap_make_request(self, make_request: MakeRequestFn) -> MakeRequestFn:
             def limited(method: RPCEndpoint, params: Any) -> RPCResponse:
                 with slots:
@@ -444,4 +472,4 @@ def _in_flight_limit(limit: int) -> type[Web3Middleware]:
 
             return limited
 
-    return InFlightLimit
+    return InFlightLimitMiddleware