ipor-fusion 4.0.0.dev274__tar.gz → 4.0.0.dev282__tar.gz

{ipor_fusion-4.0.0.dev274 → ipor_fusion-4.0.0.dev282}/AGENTS.md

@@ -198,7 +198,7 @@ the lifecycle matrix follows that.
   subpackages do not list them). Their exceptions stay in `errors` and the top
   level. `ipor_fusion.guide` keeps its own namespace. The
   public modules (`about`, `cache`, `chains`, `dependency_graph`, `errors`, `explorer`,
-  `field_docs`, `market_ids`, `market_info`, `morpho_api`, `substrates`, `types`,
+  `field_docs`, `market_ids`, `market_info`, `morpho_api`, `registry`, `substrates`, `types`,
   `validation`, `vault_data`, `vault_info`) stay importable for the names they
   define and the moved names README lists; `cli`, `mcp`, every other module and
   every submodule of a public subpackage (`core.contract`, `fuses.base`, ...) are
@@ -221,7 +221,7 @@ the lifecycle matrix follows that.
 | `IporFusionMarkets`, `Roles` | `market_ids.py`, `config/roles.py` mirror `IporFusionMarkets.sol`, `Roles.sol` in `ipor-fusion/contracts/libraries/`; drift-gated by `tests/test_solidity_mirrors.py` — bump its pinned ref in the same change that syncs the mirrors An id sourced from a contracts feature branch ahead of the pinned ref goes in the test's `_AHEAD_OF_UPSTREAM` allowlist and is removed when the ref catches up |
 | substrate decoders | `substrates.py` registry mirrors each market's `contracts/fuses/<protocol>/*SubstrateLib.sol` or `*FuseLib.sol` |
 | `vault_info` / `fusion market` JSON shapes | the builders and their TypedDicts (`VaultInfoJson`, `MorphoBlueMarketJson`, `MetaMorphoV1Json` / `MetaMorphoV2Json`) in `vault_info.py` / `market_info.py`, models in `mcp/models.py` (`extra="forbid"`, the published schema), the `VaultInfoJson`-typed `_full_vault_info_dict` fixture in `test_mcp_models.py` |
-| CLI command set | every CLI command has a matching tool in `mcp/server.py` with the same arguments (`changelog` maps to `server_info`; `--json` and display filters are CLI-only); `tests/test_cli_mcp_parity.py` enforces it, and both resolve chain and provider through `cli/config_store.resolve_chain_id` |
+| CLI command set | every CLI command has a matching tool in `mcp/server.py` with the same arguments (`changelog` maps to `server_info`; `--json` and display filters are CLI-only); `tests/test_cli_mcp_parity.py` enforces it, and the RPC-backed commands resolve chain and provider through `cli/config_store.resolve_chain_id` (`fusion address` reads no RPC: an omitted chain means every registry chain) |
 
 ## Layout (`src/ipor_fusion/`)
 
@@ -258,6 +258,9 @@ the lifecycle matrix follows that.
   `ctx.cache` (`Web3Context(cache=...)`, default `default_contract_cache()` under
   `$XDG_CACHE_HOME/ipor-fusion/`) or `get_contract_name(cache=...)`. Never cache an
   absence (no code, no answer): it can change at a later block.
+  `registry.py` the ipor-abi address registry (`fetch_address_registry` →
+  `AddressRegistry`, one raw-GitHub file per chain in `REGISTRY_CHAIN_IDS`, cached ten
+  minutes in the process, for good at a commit ref) and the `fusion address` documents;
   `morpho_api.py` the Morpho public GraphQL API client (`fetch_market`, `fetch_vault`,
   `PUBLIC_ALLOCATOR_ADDRESSES`; it narrows the GraphQL body from `object`);
   `market_info.py` — `build_morpho_blue_market_json`, `build_meta_morpho_json`, the
@@ -481,6 +484,7 @@ byte, e.g. Ebisu ZAPPER/REGISTRY).
 
 ## CLI and MCP
 
+`fusion address` (lookup, names, list; the ipor-abi registry through `registry.py`),
 `fusion config` (set-provider, set-etherscan-key, show), `fusion market`
 (morpho-blue, meta-morpho), `fusion vault` (add, remove, list, info, validate,
 role-accounts, oracle-mapping). `vault info` runs independent fetch pipelines
@@ -498,7 +502,8 @@ inject a cache.
 Every CLI command has an MCP tool (`fusion changelog` maps to `server_info`;
 the rest share names). Read-only: `vault_info`, `vault_validate`,
 `vault_list`, `vault_role_accounts`, `vault_oracle_mapping`, `market_morpho_blue`,
-`market_meta_morpho`, `config_show`, `server_info`. Mutating: `vault_add`,
+`market_meta_morpho`, `address_lookup`, `address_names`, `address_list`,
+`config_show`, `server_info`. Mutating: `vault_add`,
 `vault_remove`, `config_set_provider`, `config_set_etherscan_key`. Every new
 CLI command gets a matching MCP tool with the same argument names; an optional
 chain or block is `None` when omitted (`ChainArg`, `BlockArg`), never a `0`

{ipor_fusion-4.0.0.dev274 → ipor_fusion-4.0.0.dev282}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ipor-fusion
-Version: 4.0.0.dev274
+Version: 4.0.0.dev282
 Summary: The IPOR Fusion SDK for Python
 Project-URL: homepage, https://ipor.io
 Project-URL: repository, https://github.com/IPOR-Labs/ipor-fusion.py
@@ -168,7 +168,8 @@ receipt = vault.execute([action]).send(ctx)
 ```
 
 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`).
+[ipor-abi](https://github.com/IPOR-Labs/ipor-abi) (`mainnet/mainnet-<chain>-fusion/addresses.json`);
+`fetch_address_registry(chain_id).address("SupplyFuseAaveV3")` reads them by name (`ipor_fusion.registry`).
 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 scales by decimals
@@ -225,6 +226,10 @@ fusion vault list
 # Inspect a Morpho Blue market or MetaMorpho vault
 fusion market morpho-blue 0xMARKET_ID --chain ethereum
 fusion market meta-morpho 0xVAULT_ADDRESS --chain ethereum
+
+# Find IPOR Fusion contracts in the ipor-abi registry
+fusion address lookup SupplyFuseAaveV3 --chain base
+fusion address list --chain base
 ```
 
 ## MCP Server
@@ -291,6 +296,9 @@ Available tools:
 | `vault_remove` | Remove a vault from the local config |
 | `market_morpho_blue` | Morpho Blue market parameters and state |
 | `market_meta_morpho` | MetaMorpho V1 or Morpho Vault V2 allocations and caps (Morpho API) |
+| `address_lookup` | IPOR Fusion contracts by name substring or address (ipor-abi registry) |
+| `address_names` | Contract names in the registry, with the chains that have them |
+| `address_list` | One chain's full `{name: address}` registry |
 
 Configure providers and vaults via `fusion config` or the MCP config tools first.
 

{ipor_fusion-4.0.0.dev274 → ipor_fusion-4.0.0.dev282}/README.md

@@ -119,7 +119,8 @@ receipt = vault.execute([action]).send(ctx)
 ```
 
 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`).
+[ipor-abi](https://github.com/IPOR-Labs/ipor-abi) (`mainnet/mainnet-<chain>-fusion/addresses.json`);
+`fetch_address_registry(chain_id).address("SupplyFuseAaveV3")` reads them by name (`ipor_fusion.registry`).
 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 scales by decimals
@@ -176,6 +177,10 @@ fusion vault list
 # Inspect a Morpho Blue market or MetaMorpho vault
 fusion market morpho-blue 0xMARKET_ID --chain ethereum
 fusion market meta-morpho 0xVAULT_ADDRESS --chain ethereum
+
+# Find IPOR Fusion contracts in the ipor-abi registry
+fusion address lookup SupplyFuseAaveV3 --chain base
+fusion address list --chain base
 ```
 
 ## MCP Server
@@ -242,6 +247,9 @@ Available tools:
 | `vault_remove` | Remove a vault from the local config |
 | `market_morpho_blue` | Morpho Blue market parameters and state |
 | `market_meta_morpho` | MetaMorpho V1 or Morpho Vault V2 allocations and caps (Morpho API) |
+| `address_lookup` | IPOR Fusion contracts by name substring or address (ipor-abi registry) |
+| `address_names` | Contract names in the registry, with the chains that have them |
+| `address_list` | One chain's full `{name: address}` registry |
 
 Configure providers and vaults via `fusion config` or the MCP config tools first.
 

{ipor_fusion-4.0.0.dev274 → ipor_fusion-4.0.0.dev282}/pyproject.toml

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

{ipor_fusion-4.0.0.dev274 → ipor_fusion-4.0.0.dev282}/skills/ipor-deploy-vault/SKILL.md

@@ -231,9 +231,11 @@ slot was read on chain and matches the registry's `IporFusionFactoryImpl`;
 The factory implementations are upgraded in place, so the implementation
 column changes with releases while the proxy stays.
 
-Fuse addresses are not in the SDK. Resolve them by registry name and chain
-in `ipor-abi` (`SupplyFuseAaveV3`, `BalanceFuseAaveV3`, ...), or with the
-hosted server's `fusion_address_lookup(name, chain_id=...)`. The SDK class
+Resolve fuse addresses by registry name and chain from `ipor-abi`
+(`SupplyFuseAaveV3`, `BalanceFuseAaveV3`, ...):
+`fetch_address_registry(ChainId(8453)).address("SupplyFuseAaveV3")` in the SDK,
+`fusion address lookup SupplyFuseAaveV3 --chain base`, or the MCP tool
+`address_lookup` (the hosted server's `fusion_address_lookup`). The SDK class
 for a registry name swaps the parts: `SupplyFuseAaveV3` is `AaveV3SupplyFuse`.
 
 ## Pointers

{ipor_fusion-4.0.0.dev274 → ipor_fusion-4.0.0.dev282}/src/ipor_fusion/__init__.py

@@ -107,6 +107,8 @@ from ipor_fusion.dependency_graph import (
 )
 from ipor_fusion.errors import (
     CUSTOM_ERRORS,
+    AddressNotInRegistryError,
+    AddressRegistryError,
     BalanceSlotNotFoundError,
     ContractNotFoundError,
     CrosschainDiscoveryError,
@@ -301,6 +303,22 @@ from ipor_fusion.readers.oracle_mapping_nodes import (
     OraclePriceJson,
     SourceDetailJson,
 )
+from ipor_fusion.registry import (
+    REGISTRY_CHAIN_IDS,
+    REGISTRY_REPOSITORY,
+    AddressListJson,
+    AddressLookupJson,
+    AddressMatchJson,
+    AddressNameJson,
+    AddressNamesJson,
+    AddressRegistry,
+    build_address_list_json,
+    build_address_lookup_json,
+    build_address_names_json,
+    fetch_address_registries,
+    fetch_address_registry,
+    registry_url,
+)
 from ipor_fusion.substrates import (
     SubstrateInfo,
     decode_substrate,
@@ -450,6 +468,22 @@ __all__ = [
     "repository_url",
     "Web3Context",
     "InFlightLimit",
+    "AddressNotInRegistryError",
+    "AddressRegistryError",
+    "REGISTRY_CHAIN_IDS",
+    "REGISTRY_REPOSITORY",
+    "AddressListJson",
+    "AddressLookupJson",
+    "AddressMatchJson",
+    "AddressNameJson",
+    "AddressNamesJson",
+    "AddressRegistry",
+    "build_address_list_json",
+    "build_address_lookup_json",
+    "build_address_names_json",
+    "fetch_address_registries",
+    "fetch_address_registry",
+    "registry_url",
     "ContextManager",
     "Call",
     "get_logs_adaptive",

ipor_fusion-4.0.0.dev282/src/ipor_fusion/cli/address_cmd.py

@@ -0,0 +1,108 @@
+"""`fusion address` — IPOR Fusion deployment addresses from the ipor-abi registry."""
+
+from __future__ import annotations
+
+import json as json_lib
+
+import click
+
+from ipor_fusion.cli.options import CHAIN
+from ipor_fusion.cli.vault_rendering import _print_table
+from ipor_fusion.errors import AddressRegistryError, UnsupportedChainError
+from ipor_fusion.registry import (
+    AddressRegistry,
+    build_address_list_json,
+    build_address_lookup_json,
+    build_address_names_json,
+    fetch_address_registries,
+    fetch_address_registry,
+)
+from ipor_fusion.types import ChainId
+
+_JSON = click.option(
+    "--json",
+    "json_output",
+    is_flag=True,
+    default=False,
+    help="Emit machine-readable JSON instead of a table.",
+)
+
+
+def _registries(chain_id: ChainId | None) -> list[AddressRegistry]:
+    try:
+        return fetch_address_registries(None if chain_id is None else [chain_id])
+    except (AddressRegistryError, UnsupportedChainError) as exc:
+        raise click.UsageError(str(exc)) from exc
+
+
+@click.group()
+def address() -> None:
+    """Look up IPOR Fusion contract addresses (ipor-abi registry)."""
+
+
+@address.command("lookup")
+@click.argument("query")
+@click.option(
+    "--chain",
+    "chain_id",
+    type=CHAIN,
+    default=None,
+    help="Search one chain (ID or name); default: every chain with a registry.",
+)
+@_JSON
+def lookup(query: str, chain_id: ChainId | None, json_output: bool) -> None:
+    """Find contracts by name substring, or the names of an address."""
+    document = build_address_lookup_json(query, _registries(chain_id))
+    if json_output:
+        click.echo(json_lib.dumps(document, indent=2))
+        return
+    _print_table(
+        ("Chain", "Name", "Address"),
+        [(m["chain"], m["name"], m["address"]) for m in document["matches"]],
+    )
+
+
+@address.command("names")
+@click.option(
+    "--chain",
+    "chain_id",
+    type=CHAIN,
+    default=None,
+    help="List one chain (ID or name); default: every chain with a registry.",
+)
+@_JSON
+def names(chain_id: ChainId | None, json_output: bool) -> None:
+    """List the contract names in the registry, with the chains that have them."""
+    document = build_address_names_json(_registries(chain_id))
+    if json_output:
+        click.echo(json_lib.dumps(document, indent=2))
+        return
+    _print_table(
+        ("Name", "Chains"),
+        [
+            (entry["name"], ", ".join(str(c) for c in entry["chain_ids"]))
+            for entry in document["names"]
+        ],
+    )
+
+
+@address.command("list")
+@click.option(
+    "--chain",
+    "chain_id",
+    type=CHAIN,
+    required=True,
+    help="Chain ID or name (ethereum, base, arbitrum, ...).",
+)
+@_JSON
+def list_addresses(chain_id: ChainId, json_output: bool) -> None:
+    """Every registered contract of one chain."""
+    try:
+        registry = fetch_address_registry(chain_id)
+    except (AddressRegistryError, UnsupportedChainError) as exc:
+        raise click.UsageError(str(exc)) from exc
+    document = build_address_list_json(registry)
+    if json_output:
+        click.echo(json_lib.dumps(document, indent=2))
+        return
+    _print_table(("Name", "Address"), list(document["addresses"].items()))

{ipor_fusion-4.0.0.dev274 → ipor_fusion-4.0.0.dev282}/src/ipor_fusion/cli/main.py

@@ -5,6 +5,7 @@ import sys
 
 import click
 
+from ipor_fusion.cli.address_cmd import address
 from ipor_fusion.cli.changelog_cmd import changelog
 from ipor_fusion.cli.config_cmd import config
 from ipor_fusion.cli.market_cmd import market
@@ -29,6 +30,7 @@ def cli(ctx: click.Context, verbose: bool, quiet: bool, no_color: bool) -> None:
         ctx.obj["no_color"] = False
 
 
+cli.add_command(address)
 cli.add_command(changelog)
 cli.add_command(config)
 cli.add_command(market)

{ipor_fusion-4.0.0.dev274 → ipor_fusion-4.0.0.dev282}/src/ipor_fusion/errors.py

@@ -293,6 +293,15 @@ class MorphoApiError(IporFusionError, RuntimeError):
     addresses or market ids). Also a RuntimeError, its base before 4.0."""
 
 
+class AddressRegistryError(IporFusionError, RuntimeError):
+    """The ipor-abi address registry is unreachable or its file does not parse
+    as a ``{name: address}`` map."""
+
+
+class AddressNotInRegistryError(IporFusionError, LookupError):
+    """A chain's address registry has no contract by the requested name."""
+
+
 class CrosschainDiscoveryError(IporFusionError):
     """A crosschain vault's on-chain configuration is not one discovery can
     use: a malformed or unexpected market grant, an executor managed by another

{ipor_fusion-4.0.0.dev274 → ipor_fusion-4.0.0.dev282}/src/ipor_fusion/fuses/universal.py

@@ -14,14 +14,18 @@ from ipor_fusion.types import Amount, FuseAddress
 class UniversalTokenSwapperAbi(Enum):
     """ABI revision of the deployed UniversalTokenSwapperFuse contract.
 
-    Deployed fuses are immutable, so both revisions coexist across chains:
-    older deployments (e.g. Base) accept only the LEGACY signature, newer
-    ones (e.g. HyperEVM, markets 12 and 1202) only the MIN_AMOUNT_OUT one.
-    Pick the member matching the fuse address this instance is bound to.
+    Deployed fuses are immutable, so the revisions coexist across chains:
+    older deployments (e.g. Base) accept only the LEGACY signature, the
+    HyperEVM ones (markets 12 and 1202) only the MIN_AMOUNT_OUT one, and the
+    Arbitrum fuses of the 2026-10-21 contracts release (markets 12 and 1202)
+    only TOKENS_TO_RETURN, which adds the tokens the swap calls may leave in
+    the executor. Pick the member matching the fuse address this instance is
+    bound to.
     """
 
     LEGACY = auto()
     MIN_AMOUNT_OUT = auto()
+    TOKENS_TO_RETURN = auto()
 
 
 class UniversalTokenSwapperSubstrates:
@@ -73,7 +77,11 @@ class UniversalTokenSwapperFuse(Fuse):
         targets: list[ChecksumAddress],
         data: list[bytes],
         min_amount_out: Amount | None = None,
+        tokens_to_return: list[ChecksumAddress] | None = None,
     ) -> FuseAction:
+        """``tokens_to_return`` (TOKENS_TO_RETURN only): intermediate or extra
+        output tokens the swap calls may leave in the executor, each a granted
+        Token substrate; the executor returns them to the vault."""
         self._validate_address(token_in, "token_in")
         self._validate_address(token_out, "token_out")
         self._validate_amount(amount_in, "amount_in")
@@ -81,6 +89,13 @@ class UniversalTokenSwapperFuse(Fuse):
             raise ValueError(
                 f"targets and data must have the same length, got {len(targets)} and {len(data)}"
             )
+        if (
+            tokens_to_return is not None
+            and self._abi is not UniversalTokenSwapperAbi.TOKENS_TO_RETURN
+        ):
+            raise ValueError(
+                "tokens_to_return requires abi=UniversalTokenSwapperAbi.TOKENS_TO_RETURN"
+            )
         if self._abi is UniversalTokenSwapperAbi.LEGACY:
             if min_amount_out is not None:
                 raise ValueError(
@@ -92,11 +107,27 @@ class UniversalTokenSwapperFuse(Fuse):
             )
         if min_amount_out is None:
             raise ValueError(
-                "min_amount_out is required with abi=UniversalTokenSwapperAbi.MIN_AMOUNT_OUT"
+                f"min_amount_out is required with abi=UniversalTokenSwapperAbi.{self._abi.name}"
                 " (pass 0 to rely on the vault-side slippage cap only)"
             )
         self._validate_non_negative(min_amount_out, "min_amount_out")
+        if self._abi is UniversalTokenSwapperAbi.MIN_AMOUNT_OUT:
+            return self._action_raw(
+                "enter((address,address,uint256,uint256,(address[],bytes[])))",
+                [[token_in, token_out, amount_in, min_amount_out, [targets, data]]],
+            )
+        returned = list(tokens_to_return or [])
+        for index, token in enumerate(returned):
+            self._validate_address(token, f"tokens_to_return[{index}]")
         return self._action_raw(
-            "enter((address,address,uint256,uint256,(address[],bytes[])))",
-            [[token_in, token_out, amount_in, min_amount_out, [targets, data]]],
+            "enter((address,address,uint256,uint256,(address[],bytes[],address[])))",
+            [
+                [
+                    token_in,
+                    token_out,
+                    amount_in,
+                    min_amount_out,
+                    [targets, data, returned],
+                ]
+            ],
         )

{ipor_fusion-4.0.0.dev274 → ipor_fusion-4.0.0.dev282}/src/ipor_fusion/guide/quickstart.md

@@ -146,7 +146,9 @@ slot was read on chain and matches the registry's `IporFusionFactoryImpl`;
 The factory implementations are upgraded in place, so the implementation
 column changes with releases while the proxy stays.
 
-Fuse addresses are not in the SDK. Resolve them by registry name and chain
-in `ipor-abi` (`SupplyFuseAaveV3`, `BalanceFuseAaveV3`, ...), or with the
-hosted server's `fusion_address_lookup(name, chain_id=...)`. The SDK class
+Resolve fuse addresses by registry name and chain from `ipor-abi`
+(`SupplyFuseAaveV3`, `BalanceFuseAaveV3`, ...):
+`fetch_address_registry(ChainId(8453)).address("SupplyFuseAaveV3")` in the SDK,
+`fusion address lookup SupplyFuseAaveV3 --chain base`, or the MCP tool
+`address_lookup` (the hosted server's `fusion_address_lookup`). The SDK class
 for a registry name swaps the parts: `SupplyFuseAaveV3` is `AaveV3SupplyFuse`.

{ipor_fusion-4.0.0.dev274 → ipor_fusion-4.0.0.dev282}/src/ipor_fusion/mcp/models.py

@@ -1199,3 +1199,44 @@ class ServerInfoResponse(_Base):
         "crosschain and HyperCore). Everything the package ships outside these "
         "is production.",
     )
+
+
+class AddressMatch(_Base):
+    chain_id: ChainId
+    chain: str
+    name: str = Field(description="Contract name in the ipor-abi registry.")
+    address: str
+
+
+class AddressLookupResponse(_Base):
+    """Registry entries matching a name substring or an address."""
+
+    query: str
+    query_type: Literal["address", "name"] = Field(
+        description="'address' for 0x and 40 hex digits (exact match), else 'name' "
+        "(case-insensitive substring)."
+    )
+    match_count: int
+    matches: list[AddressMatch]
+
+
+class AddressName(_Base):
+    name: str
+    chain_ids: list[ChainId] = Field(description="Chains registering this name.")
+
+
+class AddressNamesResponse(_Base):
+    """Every contract name in the registries read."""
+
+    chain_ids: list[ChainId] = Field(description="Chains whose registry was read.")
+    names: list[AddressName]
+
+
+class AddressListResponse(_Base):
+    """One chain's full ``{name: address}`` registry."""
+
+    chain_id: ChainId
+    chain: str
+    ref: str = Field(description="ipor-abi git ref the map was read at.")
+    count: int
+    addresses: dict[str, str]

{ipor_fusion-4.0.0.dev274 → ipor_fusion-4.0.0.dev282}/src/ipor_fusion/mcp/server.py

@@ -38,6 +38,9 @@ from ipor_fusion.market_info import (
 from ipor_fusion.mcp.guide import register_guide
 from ipor_fusion.mcp.models import (
     ActionResult,
+    AddressListResponse,
+    AddressLookupResponse,
+    AddressNamesResponse,
     ChangelogEntryModel,
     ConfigShowResponse,
     MetaMorphoVaultResponse,
@@ -57,6 +60,13 @@ from ipor_fusion.morpho_api import (
 )
 from ipor_fusion.readers.morpho import MorphoReader, morpho_blue_address
 from ipor_fusion.readers.oracle_mapping import build_oracle_mapping
+from ipor_fusion.registry import (
+    build_address_list_json,
+    build_address_lookup_json,
+    build_address_names_json,
+    fetch_address_registries,
+    fetch_address_registry,
+)
 from ipor_fusion.types import (
     ChainId,
     PlasmaVaultAddress,
@@ -127,7 +137,9 @@ def _build_ctx(
     return ctx, block_number
 
 
-def _no_zero_sentinel(name: str) -> Callable[[object], object]:
+def _no_zero_sentinel(
+    name: str, omitted: str | None = None
+) -> Callable[[object], object]:
     """Refuse 0 with an explicit message: clients built against the 3.x tools
     still send it meaning auto / latest, and reading it as block or chain 0
     would answer with genesis-block data instead of an error."""
@@ -136,7 +148,14 @@ def _no_zero_sentinel(name: str) -> Callable[[object], object]:
         if value == 0 and not isinstance(value, bool):
             raise ValueError(
                 f"{name}=0 is not a sentinel any more: omit {name} for "
-                + ("the latest block" if name == "block_number" else "auto-detection")
+                + (
+                    omitted
+                    or (
+                        "the latest block"
+                        if name == "block_number"
+                        else "auto-detection"
+                    )
+                )
             )
         return value
 
@@ -158,6 +177,11 @@ ChainArg = Annotated[
 
 # The market tools need the chain: no auto-detection, so no omission either.
 RequiredChainArg = Annotated[ChainId, Field(description="Chain ID.", gt=0)]
+RegistryChainArg = Annotated[
+    ChainId | None,
+    Field(description="Chain ID; omitted: every chain with a deployment file.", gt=0),
+    BeforeValidator(_no_zero_sentinel("chain_id", "every chain")),
+]
 BlockArg = Annotated[
     int | None,
     Field(description="Block number (positive); omitted: latest.", ge=1),
@@ -681,6 +705,35 @@ def market_meta_morpho(
     return MetaMorphoVaultResponse.model_validate(payload)
 
 
+@mcp.tool()
+def address_lookup(
+    query: str, chain_id: RegistryChainArg = None
+) -> AddressLookupResponse:
+    """Find IPOR Fusion contracts in the ipor-abi registry by name substring, or
+    the names of an address. Reads one file per chain (cached ten minutes)."""
+    registries = fetch_address_registries(None if chain_id is None else [chain_id])
+    return AddressLookupResponse.model_validate(
+        build_address_lookup_json(query, registries)
+    )
+
+
+@mcp.tool()
+def address_names(chain_id: RegistryChainArg = None) -> AddressNamesResponse:
+    """List the contract names in the ipor-abi registry, with the chains that
+    have each; use them with address_lookup."""
+    registries = fetch_address_registries(None if chain_id is None else [chain_id])
+    return AddressNamesResponse.model_validate(build_address_names_json(registries))
+
+
+@mcp.tool()
+def address_list(chain_id: RequiredChainArg) -> AddressListResponse:
+    """One chain's full {name: address} registry: hundreds of entries;
+    address_lookup is cheaper for one contract."""
+    return AddressListResponse.model_validate(
+        build_address_list_json(fetch_address_registry(chain_id))
+    )
+
+
 def main() -> None:
     mcp.run(transport="stdio")