ipor-fusion 4.0.0.dev231__tar.gz → 4.0.0.dev240__tar.gz

{ipor_fusion-4.0.0.dev231 → ipor_fusion-4.0.0.dev240}/AGENTS.md

@@ -218,7 +218,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` (`changelog` maps to `server_info`) |
+| 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` |
 
 ## Layout (`src/ipor_fusion/`)
 
@@ -479,7 +479,9 @@ 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`,
 `vault_remove`, `config_set_provider`, `config_set_etherscan_key`. Every new
-CLI command gets a matching MCP tool. Put every fact in its structured home:
+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`
+sentinel. Put every fact in its structured home:
 the return shape is the Pydantic return type (it becomes `outputSchema`),
 per-argument semantics go in `Annotated[..., Field(description=...)]`, closed
 value sets are `Literal` enums. The docstring keeps only what has no
@@ -487,9 +489,13 @@ structured home: a one-line summary, behavioral notes, cost warnings. Do not
 repeat schema content as prose; it drifts.
 
 `mcp/models.py` forbids extra keys and stays the source of the published JSON
-schema. Adding a field to `build_vault_info_json` (or a `fusion market` document)
-means adding it to its TypedDict, to the matching model (with a default for
-back-compat) and to the `_full_vault_info_dict` fixture;
+schema. A command whose CLI `--json` and MCP tool return the same data publish one
+document: an SDK builder returns its TypedDict (`build_vault_info_json`,
+`build_vault_validation_json`, the `fusion market` builders) and the tool
+validates it into the mirroring model, never a second hand-built shape. Adding a
+field to a document means adding it to its TypedDict, to the matching model (with
+a default for back-compat) and to the `_full_vault_info_dict` fixture for vault
+info;
 `TestTypedDocumentsMirrorModels` in `test_mcp_models.py` holds every TypedDict to
 its model block by block, a union block (`deployment`, `position_breakdown`,
 `source_detail`) shape by shape. Every block is a model; a block whose optional keys

{ipor_fusion-4.0.0.dev231 → ipor_fusion-4.0.0.dev240}/MIGRATION_4.md

@@ -990,6 +990,48 @@ and `log_index` was passed through as given (a hex string from a raw log); the e
 These apply to every caller, type-checked or not. Changes described in full above
 are listed with a link.
 
+- **The CLI and the MCP tools take the same arguments.**
+  - **MCP inputs:** `chain_id` and `block_number` are optional and omitted means
+    auto-detected / latest. The `0` sentinel is gone, and `0` is now rejected with
+    an error naming the argument to omit (it is never read as chain or block 0);
+    a client that passed `0` must omit the argument instead. The CLI refuses
+    `--block-number 0` and `--chain-id 0` the same way. `server_info(changelog_since=)` is `server_info(since=)` as in
+    `fusion changelog --since`, and `vault_oracle_mapping` takes `max_depth` like
+    `--max-depth`.
+  - **Chain auto-detection:** both surfaces use the saved vault's chain, else the
+    chain of the only configured provider. The CLI used only the saved vault.
+  - **CLI options:** every `--block-number` rejects a negative block, and
+    `fusion market morpho-blue --block` is `--block-number` (`--block` still
+    works).
+  - **One role-accounts document:** `fusion vault role-accounts --json` and
+    `vault_role_accounts` publish `RoleAccountsJson`, built by
+    `build_role_accounts_json` (exported).
+  - **Parity test:** `tests/test_cli_mcp_parity.py` holds every command to a
+    tool with the same arguments.
+
+- **`vault validate` publishes one document.** In 3.x the CLI's `--json` output
+  and the MCP `vault_validate` tool returned two different shapes; both now
+  return `VaultValidationJson`, built by `build_vault_validation_json(validation,
+  chain)` (exported from `ipor_fusion` and `ipor_fusion.vault_info`):
+  - `findings` lists every check in order with its `check`, `severity` and
+    `message`. It replaces the CLI's `criticals` / `warnings` / `ok` string lists
+    and the MCP tool's `criticals` / `warnings` / `passed` lists; filter by
+    `severity`.
+  - `erc20` (`tokens`, `value_in_asset`, `market_cached_value`, `unpriced_tokens`)
+    replaces the CLI's `erc20_balances`; `erc20.tokens` has the same entries.
+  - `reconciliation`, `lending_health` and `asset` share their shapes with the
+    `vault info` document. For the MCP tool this means `delta.percent` instead of
+    `delta_percent`, amounts formatted with thousands separators and at most six
+    decimals (`"14,912.465797"`; `raw` keeps the exact value) and the delta's
+    `formatted` as its absolute value, as in `vault info`.
+  - The MCP tool's output gains `block_timestamp`.
+  - An ERC20 entry whose balance read failed keeps its `decimals` when they were
+    read (in `vault info` too).
+  - The MCP output is the builder's document key for key: an amount without a
+    USD value and an ERC20 entry without a balance no longer gain `null` keys
+    (`usd`, `price_usd`, ...) in either tool, `vault_info` included, and a zero
+    USD delta without a price is `0.0`, not `0`.
+
 - **A failed lending read is a warning, never a silent `ok`.** 3.x caught every
   exception in the lending-health readers and dropped the position, so a provider
   outage could leave no lending finding and an `ok` verdict. Now:

{ipor_fusion-4.0.0.dev231 → ipor_fusion-4.0.0.dev240}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ipor-fusion
-Version: 4.0.0.dev231
+Version: 4.0.0.dev240
 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.dev231 → ipor_fusion-4.0.0.dev240}/pyproject.toml

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

{ipor_fusion-4.0.0.dev231 → ipor_fusion-4.0.0.dev240}/src/ipor_fusion/__init__.py

@@ -28,7 +28,9 @@ from ipor_fusion.core.access import (
     AccessManager,
     RoleAccount,
     RoleAccountJson,
+    RoleAccountsJson,
     RoleStatus,
+    build_role_accounts_json,
     resolve_access_manager,
     role_account_sort_key,
 )
@@ -368,7 +370,9 @@ from ipor_fusion.vault_info import (
     DeploymentErrorJson,
     DeploymentJson,
     Erc20BalanceJson,
+    Erc20HoldingsJson,
     FeesJson,
+    FindingJson,
     FuseJson,
     HealthCheckJson,
     HighWaterMarkJson,
@@ -392,8 +396,10 @@ from ipor_fusion.vault_info import (
     VaultAssetJson,
     VaultInfoJson,
     VaultLinksJson,
+    VaultValidationJson,
     WithdrawManagerJson,
     build_vault_info_json,
+    build_vault_validation_json,
 )
 
 __version__ = package_version()
@@ -461,6 +467,8 @@ __all__ = [
     "RoleStatus",
     "resolve_access_manager",
     "role_account_sort_key",
+    "RoleAccountsJson",
+    "build_role_accounts_json",
     "RewardsManager",
     "VestingData",
     "ERC20",
@@ -719,6 +727,10 @@ __all__ = [
     "UsdAmountJson",
     "VaultAssetJson",
     "VaultInfoJson",
+    "VaultValidationJson",
+    "FindingJson",
+    "Erc20HoldingsJson",
+    "build_vault_validation_json",
     "VaultLinksJson",
     "WithdrawManagerJson",
     "MorphoApiError",

{ipor_fusion-4.0.0.dev231 → ipor_fusion-4.0.0.dev240}/src/ipor_fusion/cli/config_cmd.py

@@ -20,7 +20,7 @@ def config() -> None:
 @click.argument("url")
 @click.option(
     "--chain-id",
-    type=int,
+    type=click.IntRange(min=1),
     default=None,
     help="Chain ID (auto-detected from URL if omitted).",
 )

{ipor_fusion-4.0.0.dev231 → ipor_fusion-4.0.0.dev240}/src/ipor_fusion/cli/config_store.py

@@ -88,3 +88,21 @@ def load_config() -> FusionConfig:
 def save_config(config: FusionConfig) -> None:
     CONFIG_DIR.mkdir(parents=True, exist_ok=True)
     CONFIG_FILE.write_text(config.model_dump_json(indent=2), encoding="utf-8")
+
+
+def resolve_chain_id(
+    cfg: FusionConfig, vault_address: str, chain_id: ChainId | None
+) -> ChainId | None:
+    """The chain a command or tool runs on: the one given, else the saved
+    vault's, else the chain of the only configured provider; None when none
+    applies. The CLI and the MCP server share it so both resolve alike."""
+    if chain_id is not None:
+        return chain_id
+    if entry := next(
+        (v for v in cfg.vaults if v.address.lower() == vault_address.lower()),
+        None,
+    ):
+        return entry.chain_id
+    if len(cfg.providers) == 1:
+        return ChainId(int(next(iter(cfg.providers))))
+    return None

{ipor_fusion-4.0.0.dev231 → ipor_fusion-4.0.0.dev240}/src/ipor_fusion/cli/market_cmd.py

@@ -16,7 +16,7 @@ from eth_typing import ChecksumAddress
 
 from ipor_fusion.chains import CHAIN_NAMES
 from ipor_fusion.cli.config_store import load_config
-from ipor_fusion.cli.options import ADDRESS, CHAIN, _resolve_provider
+from ipor_fusion.cli.options import ADDRESS, BLOCK_NUMBER, CHAIN, _resolve_provider
 from ipor_fusion.cli.vault_rendering import _format_amount, _print_table
 from ipor_fusion.core.context import Web3Context
 from ipor_fusion.market_info import (
@@ -81,8 +81,10 @@ def market() -> None:
     help="Chain ID or name (ethereum, base, arbitrum, ...).",
 )
 @click.option(
+    "--block-number",
     "--block",
-    type=int,
+    "block_number",
+    type=BLOCK_NUMBER,
     default=None,
     help="Block number for on-chain reads (default: latest).",
 )
@@ -109,7 +111,7 @@ def market() -> None:
 def morpho_blue(
     market_id: MorphoBlueMarketId,
     chain_id: ChainId,
-    block: int | None,
+    block_number: int | None,
     no_api: bool,
     vault_filter: str | None,
     json_output: bool,
@@ -125,8 +127,8 @@ def morpho_blue(
     cfg = load_config()
     provider_url = _resolve_provider(cfg, chain_id)
     ctx = Web3Context.from_url(provider_url)
-    if block is not None:
-        ctx = ctx.at_block(block)
+    if block_number is not None:
+        ctx = ctx.at_block(block_number)
     reader = MorphoReader(morpho_blue_address(chain_id))
     mid = market_id
     params, state = reader.read_existing_market(ctx, mid)

{ipor_fusion-4.0.0.dev231 → ipor_fusion-4.0.0.dev240}/src/ipor_fusion/cli/options.py

@@ -7,6 +7,7 @@ from web3 import Web3
 from ipor_fusion.chains import CHAIN_NAME_TO_ID, ensure_supported_chain
 from ipor_fusion.cli.config_store import (
     FusionConfig,
+    resolve_chain_id,
 )
 from ipor_fusion.core.context import Web3Context
 from ipor_fusion.errors import (
@@ -74,11 +75,11 @@ class ChainType(click.ParamType):  # pyright: ignore[reportMissingTypeArgument]
         self, value: object, param: click.Parameter | None, ctx: click.Context | None
     ) -> ChainId:
         if isinstance(value, int):
-            return ChainId(value)
+            return self._positive(value, param, ctx)
         if not isinstance(value, str):
             self.fail(f"expected string, got {type(value).__name__}", param, ctx)
         try:
-            return ChainId(int(value))
+            return self._positive(int(value), param, ctx)
         except ValueError:
             pass
         lower = value.lower().strip()
@@ -91,22 +92,54 @@ class ChainType(click.ParamType):  # pyright: ignore[reportMissingTypeArgument]
             ctx,
         )
 
+    def _positive(
+        self, value: int, param: click.Parameter | None, ctx: click.Context | None
+    ) -> ChainId:
+        if value <= 0:
+            self.fail(
+                f"chain ID must be positive, got {value}; omit --chain-id to "
+                "auto-detect it",
+                param,
+                ctx,
+            )
+        return ChainId(value)
+
 
 CHAIN = ChainType()
 
 
+class BlockNumberType(click.IntRange):
+    """A positive block number. 0 is refused rather than read as block 0:
+    some callers still pass it meaning "latest"."""
+
+    name = "block"
+
+    def __init__(self) -> None:
+        super().__init__(min=1)
+
+    def convert(
+        self, value: object, param: click.Parameter | None, ctx: click.Context | None
+    ) -> int:
+        if value in (0, "0"):
+            self.fail(
+                "0 is not a block selector: omit --block-number for the latest block",
+                param,
+                ctx,
+            )
+        return super().convert(value, param, ctx)
+
+
+BLOCK_NUMBER = BlockNumberType()
+
+
 def _resolve_chain_id(
     cfg: FusionConfig, vault_address: PlasmaVaultAddress, chain_id: ChainId | None
 ) -> ChainId:
-    if chain_id is not None:
-        return chain_id
-    if entry := next(
-        (v for v in cfg.vaults if v.address.lower() == vault_address.lower()),
-        None,
-    ):
-        return entry.chain_id
+    if (resolved := resolve_chain_id(cfg, vault_address, chain_id)) is not None:
+        return resolved
     raise click.UsageError(
-        "Unknown vault — use --chain-id (e.g. --chain-id ethereum, --chain-id 8453)"
+        "Cannot tell the chain: the vault is not saved and there is not exactly one "
+        "configured provider — use --chain-id (e.g. --chain-id ethereum, --chain-id 8453)"
     )
 
 

{ipor_fusion-4.0.0.dev231 → ipor_fusion-4.0.0.dev240}/src/ipor_fusion/cli/vault_cmd.py

@@ -2,11 +2,8 @@ from __future__ import annotations
 
 import json
 import sys
-from typing import TypedDict
 
 import click
-from web3 import Web3
-from web3.types import Timestamp
 
 from ipor_fusion.chains import CHAIN_NAMES
 from ipor_fusion.cli.config_store import (
@@ -15,7 +12,13 @@ from ipor_fusion.cli.config_store import (
     load_config,
     save_config,
 )
-from ipor_fusion.cli.options import CHAIN, VAULT_ADDRESS, _build_ctx, _resolve_provider
+from ipor_fusion.cli.options import (
+    BLOCK_NUMBER,
+    CHAIN,
+    VAULT_ADDRESS,
+    _build_ctx,
+    _resolve_provider,
+)
 from ipor_fusion.cli.oracle_mapping_view import _print_oracle_mapping
 from ipor_fusion.cli.vault_health import (
     _print_validation,
@@ -29,8 +32,8 @@ from ipor_fusion.cli.vault_rendering import (
 )
 from ipor_fusion.config.roles import Roles
 from ipor_fusion.core.access import (
+    build_role_accounts_json,
     resolve_access_manager,
-    role_account_sort_key,
 )
 from ipor_fusion.core.context import Web3Context
 from ipor_fusion.core.plasma_vault import PlasmaVault
@@ -42,9 +45,8 @@ from ipor_fusion.errors import (
 from ipor_fusion.readers.oracle_mapping import (
     build_oracle_mapping,
 )
-from ipor_fusion.types import ChainId, Check, PlasmaVaultAddress, Severity, Verdict
+from ipor_fusion.types import ChainId, PlasmaVaultAddress
 from ipor_fusion.validation import (
-    VaultValidation,
     validate_vault,
 )
 from ipor_fusion.vault_data import (
@@ -52,43 +54,11 @@ from ipor_fusion.vault_data import (
     fetch_vault_data,
 )
 from ipor_fusion.vault_info import (
-    Erc20BalanceJson,
-    LendingHealthJson,
-    ReconciliationJson,
-    VaultAssetJson,
-    _erc20_balances_json,
-    _lending_health_json,
-    _reconciliation_json,
     _unix_to_iso,
+    build_vault_validation_json,
 )
 
 
-class _FindingJson(TypedDict):
-    check: Check
-    severity: Severity
-    message: str
-
-
-class _ValidationJson(TypedDict):
-    """The ``fusion vault validate --json`` document."""
-
-    vault: PlasmaVaultAddress
-    chain: str
-    chain_id: ChainId
-    block: int
-    block_timestamp: Timestamp
-    block_timestamp_utc: str
-    asset: VaultAssetJson
-    verdict: Verdict
-    criticals: list[str]
-    warnings: list[str]
-    ok: list[str]
-    findings: list[_FindingJson]
-    reconciliation: ReconciliationJson
-    erc20_balances: list[Erc20BalanceJson]
-    lending_health: LendingHealthJson | None
-
-
 def _auto_save_vault(
     cfg: FusionConfig,
     vault_address: PlasmaVaultAddress,
@@ -216,7 +186,7 @@ vault.add_command(list_vaults, "ls")
 )
 @click.option(
     "--block-number",
-    type=int,
+    type=BLOCK_NUMBER,
     default=None,
     help="Block number (default: latest).",
 )
@@ -261,7 +231,7 @@ def info(
 )
 @click.option(
     "--block-number",
-    type=int,
+    type=BLOCK_NUMBER,
     default=None,
     help="Block number (default: latest).",
 )
@@ -296,7 +266,9 @@ def validate(
 
     chain_label = CHAIN_NAMES.get(chain_id, str(chain_id))
     if json_output:
-        click.echo(json.dumps(_validation_json(validation, chain_label), indent=2))
+        click.echo(
+            json.dumps(build_vault_validation_json(validation, chain_label), indent=2)
+        )
     else:
         click.echo(f"Vault:   {validation.vault}")
         click.echo(f"Chain:   {chain_label} (chain-id={chain_id})")
@@ -307,36 +279,6 @@ def validate(
         sys.exit(1)
 
 
-def _validation_json(validation: VaultValidation, chain_label: str) -> _ValidationJson:
-    return {
-        "vault": validation.vault,
-        "chain": chain_label,
-        "chain_id": validation.chain_id,
-        "block": validation.block_number,
-        "block_timestamp": validation.block_timestamp,
-        "block_timestamp_utc": _unix_to_iso(validation.block_timestamp),
-        "asset": {
-            "address": validation.asset,
-            "symbol": validation.asset_symbol,
-            "decimals": validation.asset_decimals,
-            "price_usd": validation.asset_price_usd,
-        },
-        "verdict": validation.verdict,
-        "criticals": list(validation.criticals),
-        "warnings": list(validation.warnings),
-        "ok": list(validation.ok),
-        "findings": [
-            {"check": f.check, "severity": f.severity, "message": f.message}
-            for f in validation.findings
-        ],
-        "reconciliation": _reconciliation_json(
-            validation.reconciliation, validation.asset_decimals
-        ),
-        "erc20_balances": _erc20_balances_json(validation),
-        "lending_health": _lending_health_json(validation.lending_health),
-    }
-
-
 @vault.command("role-accounts")
 @click.argument("vault_address", type=VAULT_ADDRESS)
 @click.option(
@@ -350,7 +292,7 @@ def _validation_json(validation: VaultValidation, chain_label: str) -> _Validati
 )
 @click.option(
     "--block-number",
-    type=int,
+    type=BLOCK_NUMBER,
     default=None,
     help="Block number (default: latest).",
 )
@@ -389,21 +331,19 @@ def role_accounts(
         raise click.ClickException(
             f"RoleGranted log scan failed ({type(exc).__name__}: {exc})."
         ) from exc
-    rows = [ra.to_dict() for ra in sorted(accounts, key=role_account_sort_key)]
-
+    document = build_role_accounts_json(
+        accounts,
+        vault=vault_address,
+        access_manager=manager.address,
+        chain_id=chain_id,
+        role=role_id,
+    )
     if json_output:
-        payload = {
-            "vault": Web3.to_checksum_address(vault_address),
-            "access_manager": manager.address,
-            "chain_id": chain_id,
-            "role_filter": Roles.get_name(role_id) if role_id is not None else None,
-            "accounts": rows,
-        }
-        click.echo(json.dumps(payload, indent=2))
+        click.echo(json.dumps(document, indent=2))
         return
 
     click.echo(f"Access Manager: {manager.address}")
-    _print_role_accounts_table(rows)
+    _print_role_accounts_table(document["accounts"])
 
 
 @vault.command("oracle-mapping")
@@ -413,7 +353,7 @@ def role_accounts(
 )
 @click.option(
     "--block-number",
-    type=click.IntRange(min=0),
+    type=BLOCK_NUMBER,
     default=None,
     help="Block number (default: latest).",
 )

{ipor_fusion-4.0.0.dev231 → ipor_fusion-4.0.0.dev240}/src/ipor_fusion/core/__init__.py

@@ -2,7 +2,9 @@ from ipor_fusion.core.access import (
     AccessManager,
     RoleAccount,
     RoleAccountJson,
+    RoleAccountsJson,
     RoleStatus,
+    build_role_accounts_json,
     resolve_access_manager,
     role_account_sort_key,
 )
@@ -138,4 +140,6 @@ __all__ = [
     "price_oracle_middleware",
     "resolve_access_manager",
     "role_account_sort_key",
+    "RoleAccountsJson",
+    "build_role_accounts_json",
 ]

{ipor_fusion-4.0.0.dev231 → ipor_fusion-4.0.0.dev240}/src/ipor_fusion/core/access.py

@@ -1,4 +1,4 @@
-from collections.abc import Callable
+from collections.abc import Callable, Sequence
 from dataclasses import dataclass
 from typing import TypedDict
 
@@ -21,7 +21,13 @@ from ipor_fusion.errors import (
     NotPlasmaVaultError,
     OwnerNotFoundError,
 )
-from ipor_fusion.types import AccessManagerAddress, Period, PlasmaVaultAddress, RoleId
+from ipor_fusion.types import (
+    AccessManagerAddress,
+    ChainId,
+    Period,
+    PlasmaVaultAddress,
+    RoleId,
+)
 
 
 class RoleAccountJson(TypedDict):
@@ -71,6 +77,38 @@ def role_account_sort_key(role_account: RoleAccount) -> tuple[str, int]:
     return (role_account.account.lower(), role_account.role_id)
 
 
+class RoleAccountsJson(TypedDict):
+    """The ``fusion vault role-accounts --json`` document and the
+    ``vault_role_accounts`` MCP tool output (`build_role_accounts_json`)."""
+
+    vault: PlasmaVaultAddress
+    access_manager: AccessManagerAddress
+    chain_id: ChainId
+    role_filter: str | None
+    accounts: list[RoleAccountJson]
+
+
+def build_role_accounts_json(
+    accounts: Sequence[RoleAccount],
+    *,
+    vault: PlasmaVaultAddress,
+    access_manager: AccessManagerAddress,
+    chain_id: ChainId,
+    role: RoleId | Roles | None = None,
+) -> RoleAccountsJson:
+    """Role holders as the one document both tools publish, in
+    `role_account_sort_key` order; ``role`` is the filter applied, if any."""
+    return {
+        "vault": vault,
+        "access_manager": access_manager,
+        "chain_id": chain_id,
+        "role_filter": Roles.get_name(role) if role is not None else None,
+        "accounts": [
+            ra.to_dict() for ra in sorted(accounts, key=role_account_sort_key)
+        ],
+    }
+
+
 def _role_status_decoder(values: tuple[bool, int]) -> RoleStatus:
     is_member, execution_delay = values
     return RoleStatus(is_member=is_member, execution_delay=Period(execution_delay))