feat(kad-dht): add RoutingTableDiagnostics for routing health inspection

.github/workflows/tox.yml

@@ -131,5 +131,7 @@ jobs:
           if [[ "${{ matrix.toxenv }}" == "wheel" ]]; then
             python -m tox run -e windows-wheel
           else
-            python -m tox run -e $(echo "py${{ matrix.python-version }}-${{ matrix.toxenv }}" | tr -d '.')
+            tox_python="py${{ matrix.python-version }}"
+            tox_python="${tox_python//./}"
+            python -m tox run -e "${tox_python}-${{ matrix.toxenv }}"
           fi

.gitignore

@@ -189,6 +189,7 @@ tests/interop/js_libp2p/js_node/node_modules/
 tests/interop/js_libp2p/js_node/package-lock.json
 tests/interop/js_libp2p/js_node/src/node_modules/
 tests/interop/js_libp2p/js_node/src/package-lock.json
+examples/request_response/synapse_sidecar/node_modules/
 
 # Sphinx documentation build
 _build/

artifacts/filecoin/libp2p_dependency_tree.v1.json

@@ -313,7 +313,7 @@
       "kind": "config",
       "file": "libp2p/filecoin/__init__.py",
       "line_start": 37,
-      "line_end": 63,
+      "line_end": 89,
       "version": "feat/filecoin-dx-and-tooling"
     },
     {
@@ -545,6 +545,146 @@
       "line_start": 1,
       "line_end": 150,
       "version": "feat/filecoin-dx-and-tooling"
+    },
+    {
+      "id": "py_FilecoinAddress",
+      "project": "py-libp2p",
+      "symbol": "FilecoinAddress",
+      "kind": "type",
+      "file": "libp2p/filecoin/address.py",
+      "line_start": 58,
+      "line_end": 97,
+      "version": "feat/agentic-request-response-example"
+    },
+    {
+      "id": "py_parse_address",
+      "project": "py-libp2p",
+      "symbol": "parse_address",
+      "kind": "fn",
+      "file": "libp2p/filecoin/address.py",
+      "line_start": 81,
+      "line_end": 134,
+      "version": "feat/agentic-request-response-example"
+    },
+    {
+      "id": "py_is_valid_address",
+      "project": "py-libp2p",
+      "symbol": "is_valid_address",
+      "kind": "fn",
+      "file": "libp2p/filecoin/address.py",
+      "line_start": 148,
+      "line_end": 155,
+      "version": "feat/agentic-request-response-example"
+    },
+    {
+      "id": "py_make_delegated_address",
+      "project": "py-libp2p",
+      "symbol": "make_delegated_address",
+      "kind": "fn",
+      "file": "libp2p/filecoin/address.py",
+      "line_start": 158,
+      "line_end": 175,
+      "version": "feat/agentic-request-response-example"
+    },
+    {
+      "id": "py_make_id_address",
+      "project": "py-libp2p",
+      "symbol": "make_id_address",
+      "kind": "fn",
+      "file": "libp2p/filecoin/address.py",
+      "line_start": 178,
+      "line_end": 183,
+      "version": "feat/agentic-request-response-example"
+    },
+    {
+      "id": "py_address_protocol",
+      "project": "py-libp2p",
+      "symbol": "address_protocol",
+      "kind": "fn",
+      "file": "libp2p/filecoin/address.py",
+      "line_start": 186,
+      "line_end": 188,
+      "version": "feat/agentic-request-response-example"
+    },
+    {
+      "id": "py_ID",
+      "project": "py-libp2p",
+      "symbol": "ID",
+      "kind": "const",
+      "file": "libp2p/filecoin/address.py",
+      "line_start": 30,
+      "line_end": 30,
+      "version": "feat/agentic-request-response-example"
+    },
+    {
+      "id": "py_SECP256K1",
+      "project": "py-libp2p",
+      "symbol": "SECP256K1",
+      "kind": "const",
+      "file": "libp2p/filecoin/address.py",
+      "line_start": 31,
+      "line_end": 31,
+      "version": "feat/agentic-request-response-example"
+    },
+    {
+      "id": "py_DELEGATED",
+      "project": "py-libp2p",
+      "symbol": "DELEGATED",
+      "kind": "const",
+      "file": "libp2p/filecoin/address.py",
+      "line_start": 33,
+      "line_end": 33,
+      "version": "feat/agentic-request-response-example"
+    },
+    {
+      "id": "py_BLS",
+      "project": "py-libp2p",
+      "symbol": "BLS",
+      "kind": "const",
+      "file": "libp2p/filecoin/address.py",
+      "line_start": 32,
+      "line_end": 32,
+      "version": "feat/agentic-request-response-example"
+    },
+    {
+      "id": "py_EAM_NAMESPACE",
+      "project": "py-libp2p",
+      "symbol": "EAM_NAMESPACE",
+      "kind": "const",
+      "file": "libp2p/filecoin/address.py",
+      "line_start": 36,
+      "line_end": 36,
+      "version": "feat/agentic-request-response-example"
+    },
+    {
+      "id": "py_DEMO_F410_PAYER",
+      "project": "py-libp2p",
+      "symbol": "DEMO_F410_PAYER",
+      "kind": "const",
+      "file": "libp2p/filecoin/address.py",
+      "line_start": 275,
+      "line_end": 275,
+      "version": "feat/agentic-request-response-example"
+    },
+    {
+      "id": "py_DEMO_F0_PAYER",
+      "project": "py-libp2p",
+      "symbol": "DEMO_F0_PAYER",
+      "kind": "const",
+      "file": "libp2p/filecoin/address.py",
+      "line_start": 278,
+      "line_end": 278,
+      "version": "feat/agentic-request-response-example"
+    },
+    {
+      "id": "py_DEMO_F410_PAYER_TESTNET",
+      "project": "py-libp2p",
+      "symbol": "DEMO_F410_PAYER_TESTNET",
+      "kind": "const",
+      "file": "libp2p/filecoin/address.py",
+      "line_start": 280,
+      "line_end": 280,
+      "version": "feat/agentic-request-response-example"
     }
   ],
   "edges": [
@@ -927,6 +1067,76 @@
       "from": "forest_mainnet_network_name",
       "to": "py_filecoin_architecture_positioning",
       "relation": "derived_from"
+    },
+    {
+      "from": "py_FilecoinAddress",
+      "relation": "defines",
+      "to": "py_public_exports"
+    },
+    {
+      "from": "py_parse_address",
+      "relation": "defines",
+      "to": "py_public_exports"
+    },
+    {
+      "from": "py_is_valid_address",
+      "relation": "defines",
+      "to": "py_public_exports"
+    },
+    {
+      "from": "py_make_delegated_address",
+      "relation": "defines",
+      "to": "py_public_exports"
+    },
+    {
+      "from": "py_make_id_address",
+      "relation": "defines",
+      "to": "py_public_exports"
+    },
+    {
+      "from": "py_address_protocol",
+      "relation": "defines",
+      "to": "py_public_exports"
+    },
+    {
+      "from": "py_ID",
+      "relation": "defines",
+      "to": "py_public_exports"
+    },
+    {
+      "from": "py_SECP256K1",
+      "relation": "defines",
+      "to": "py_public_exports"
+    },
+    {
+      "from": "py_DELEGATED",
+      "relation": "defines",
+      "to": "py_public_exports"
+    },
+    {
+      "from": "py_BLS",
+      "relation": "defines",
+      "to": "py_public_exports"
+    },
+    {
+      "from": "py_EAM_NAMESPACE",
+      "relation": "defines",
+      "to": "py_public_exports"
+    },
+    {
+      "from": "py_DEMO_F410_PAYER",
+      "relation": "defines",
+      "to": "py_public_exports"
+    },
+    {
+      "from": "py_DEMO_F0_PAYER",
+      "relation": "defines",
+      "to": "py_public_exports"
+    },
+    {
+      "from": "py_DEMO_F410_PAYER_TESTNET",
+      "relation": "defines",
+      "to": "py_public_exports"
     }
   ]
 }

docs/advertising_addresses.rst

@@ -0,0 +1,23 @@
+Advertising dialable addresses
+==============================
+
+Other peers need a multiaddr they can actually dial. py-libp2p combines **listen**
+addresses with two ways to surface a **publicly reachable** address:
+
+**1. Inferred from Identify (NAT / cloud)** — Remote peers report what they see
+when they connect, via :mod:`libp2p.identity.identify`. The host’s
+:class:`~libp2p.host.observed_addr_manager.ObservedAddrManager` collects those
+reports; after enough distinct observer groups agree on the same external
+address, it is included in :meth:`libp2p.host.basic_host.BasicHost.get_addrs`.
+Background and API details: :doc:`libp2p.host` (section
+``libp2p.host.observed_addr_manager``).
+
+**2. Explicit ``announce_addrs``** — If you already know the dialable address
+(fixed public IP, ngrok, load balancer, etc.), pass ``announce_addrs`` when
+constructing :class:`~libp2p.host.basic_host.BasicHost`. That list is advertised
+instead of augmenting with observed addresses (observations may still be recorded
+for :meth:`~libp2p.host.basic_host.BasicHost.get_nat_type` and related logic).
+
+For step-by-step usage, comparison of the two approaches, and a full example
+script, see :doc:`examples.announce_addrs` (source:
+``examples/announce_addrs/announce_addrs.py`` in the repository).

docs/examples.a2a_http_payment_demo.rst

@@ -0,0 +1,90 @@
+A2A HTTP Payment Demo
+=====================
+
+This example exposes the payment demo through the official A2A Python SDK over
+HTTP JSON-RPC with Server-Sent Events (SSE) for streaming updates.
+
+It keeps the same task semantics as the libp2p demo while adding a standards-
+facing surface:
+
+- ``GET /.well-known/agent-card.json`` for discovery
+- ``POST /rpc`` with ``SendMessage`` / ``GetTask`` / ``CancelTask`` / ``ListTasks``
+- ``SendStreamingMessage`` over SSE for real-time task progress and artifact updates
+
+The HTTP facade can run in two backend modes:
+
+- ``simulation``: safe local mode, no external services required
+- ``synapse``: real Synapse/Filecoin execution through a Node sidecar
+
+Python requirements
+-------------------
+
+Install the optional Python packages needed for the HTTP facade:
+
+.. code-block:: console
+
+    $ pip install "a2a-sdk[http-server]" uvicorn
+
+Node sidecar requirements
+-------------------------
+
+Install the sidecar dependencies once:
+
+.. code-block:: console
+
+    $ cd examples/request_response/synapse_sidecar
+    $ npm install
+
+Simulation mode
+---------------
+
+Run the official A2A server locally in simulation mode:
+
+.. code-block:: console
+
+    $ a2a-http-payment-demo --backend simulation --host 127.0.0.1 --port 9999
+
+The Agent Card will advertise ``http://127.0.0.1:9999/rpc`` as the preferred
+JSON-RPC interface.
+
+Synapse-backed mode
+-------------------
+
+To enable real Synapse/Filecoin execution, configure a funded testnet wallet
+and run the server with the Synapse backend:
+
+.. code-block:: console
+
+    $ export A2A_SYNAPSE_PRIVATE_KEY=0x...
+    $ export A2A_SYNAPSE_NETWORK=calibration
+    $ export A2A_SYNAPSE_EXECUTE_TRANSACTIONS=1
+    $ a2a-http-payment-demo --backend synapse --host 127.0.0.1 --port 9999
+
+Important environment variables:
+
+- ``A2A_SYNAPSE_PRIVATE_KEY``: private key used by the Node sidecar
+- ``A2A_SYNAPSE_NETWORK``: ``calibration`` or ``mainnet`` (default: ``calibration``)
+- ``A2A_SYNAPSE_RPC_URL``: optional custom Filecoin RPC endpoint
+- ``A2A_SYNAPSE_PANDORA_ADDRESS``: optional Pandora contract override
+- ``A2A_SYNAPSE_EXECUTE_TRANSACTIONS``: set to ``1`` to allow real funding and approval transactions
+- ``A2A_SYNAPSE_VERIFY_DOWNLOAD``: set to ``0`` to skip retrieval verification
+
+The Synapse bridge is intentionally conservative. If the wallet needs funding or
+service approval and ``A2A_SYNAPSE_EXECUTE_TRANSACTIONS`` is not enabled, the
+task fails with an explicit instruction instead of spending automatically.
+
+What the real backend adds
+--------------------------
+
+When the Synapse backend is enabled, the demo stops being purely simulated:
+
+- the quote path inspects the wallet, payment account, and allowance requirements
+- the store path can perform deposit and service-approval transactions
+- the storage receipt includes real ``CommP`` / piece identifiers, proof set data,
+  provider address, and retrieval verification metadata
+
+The full source code for the HTTP facade is below:
+
+.. literalinclude:: ../examples/request_response/a2a_http_payment_demo.py
+    :language: python
+    :linenos: