Merge pull request #1 from bnb-chain/feat/sdk-docs-and-tests

feat: improve SDK docs, add wallet tests, and fix registrations flow

Author: devinxl

README.md

@@ -2,6 +2,9 @@
 Network configuration constants.
 """
 
+# 8004scan API base URL
+SCAN_API_URL = "https://www.8004scan.io/api/v1"
+
 # BSC Testnet configuration
 TESTNET_CONFIG = {
     "name": "bsc-testnet",

bnbagent/README.md

@@ -15,7 +15,7 @@
 from .wallets import WalletProvider
 from .contract import ContractInterface
 from .models import AgentEndpoint
-from .constants import TESTNET_CONFIG
+from .constants import TESTNET_CONFIG, SCAN_API_URL
 from .paymaster import Paymaster
 
 
@@ -336,8 +336,52 @@ def register_agent(
                 agent_uri=agent_uri, metadata=metadata
             )
 
-            # Add agentURI to result
-            result["agentURI"] = agent_uri
+            # Get the assigned agentId
+            agent_id = result.get("agentId")
+
+            # Regenerate agent URI with agentId and agentRegistry in registrations field
+            final_agent_uri = agent_uri
+            if agent_id is not None:
+                try:
+                    # Rebuild endpoints from parsed data
+                    endpoints = []
+                    for svc in agent_data.get("services", []):
+                        endpoints.append(
+                            AgentEndpoint(
+                                name=svc.get("name", ""),
+                                endpoint=svc.get("endpoint", ""),
+                                version=svc.get("version"),
+                            )
+                        )
+
+                    if endpoints:
+                        # Regenerate URI with agentId included
+                        final_agent_uri = self.generate_agent_uri(
+                            name=agent_data.get("name", ""),
+                            description=agent_data.get("description", ""),
+                            image=agent_data.get("image"),
+                            endpoints=endpoints,
+                            agent_id=agent_id,
+                            supported_trust=agent_data.get("supportedTrust")
+                            or agent_data.get("supportedTrusts"),
+                        )
+
+                        # Update on-chain URI with registrations field populated
+                        self._logger.debug(
+                            f"Updating agent URI with registrations for agentId={agent_id}"
+                        )
+                        self.contract.set_agent_uri(agent_id, final_agent_uri)
+                        self._logger.info(
+                            f"Updated agent URI with registrations (agentId={agent_id})"
+                        )
+                except Exception as e:
+                    self._logger.warning(
+                        f"Failed to update agent URI with registrations: {str(e)}. "
+                        "The agent is registered but registrations field may be empty."
+                    )
+
+            # Add final agentURI to result
+            result["agentURI"] = final_agent_uri
 
             # Save registered agent to state file (add to list)
             try:
@@ -352,7 +396,7 @@ def register_agent(
                         # Update existing agent info
                         registered_agents[i] = {
                             "name": agent_name,
-                            "agent_uri": agent_uri,
+                            "agent_uri": final_agent_uri,
                             "agent_id": result.get("agentId"),
                             "transaction_hash": result.get("transactionHash"),
                         }
@@ -364,7 +408,7 @@ def register_agent(
                     registered_agents.append(
                         {
                             "name": agent_name,
-                            "agent_uri": agent_uri,
+                            "agent_uri": final_agent_uri,
                             "agent_id": result.get("agentId"),
                             "transaction_hash": result.get("transactionHash"),
                         }
@@ -423,6 +467,80 @@ def get_agent_info(self, agent_id: int) -> Dict[str, Any]:
             self._logger.error(f"Failed to get agent info: {str(e)}")
             raise
 
+    def get_all_agents(
+        self,
+        limit: int = 10,
+        offset: int = 0,
+    ) -> Dict[str, Any]:
+        """
+        List all registered agents.
+
+        This method queries the indexer API to discover registered agents.
+        It does not require on-chain calls.
+
+        Args:
+            limit: Maximum number of agents to return (default: 10, max: 100)
+            offset: Number of agents to skip for pagination (default: 0)
+
+        Returns:
+            dict: Response containing:
+                - items: List of agent objects with fields like:
+                    - token_id: Agent ID
+                    - name: Agent name
+                    - description: Agent description
+                    - owner_address: Owner wallet address
+                    - services: Dict of service endpoints
+                    - total_score: Reputation score
+                - total: Total number of agents matching query
+                - limit: Limit used in query
+                - offset: Offset used in query
+
+        Raises:
+            ConnectionError: If API request fails
+
+        Example:
+            >>> # List first 10 agents
+            >>> agents = sdk.get_all_agents(limit=10)
+            >>> for agent in agents['items']:
+            ...     print(f"Agent #{agent['token_id']}: {agent['name']}")
+
+            >>> # Paginate through results
+            >>> page1 = sdk.get_all_agents(limit=10, offset=0)
+            >>> page2 = sdk.get_all_agents(limit=10, offset=10)
+        """
+        chain_id = self._network_config.get("chain_id")
+
+        self._logger.debug(
+            f"Fetching agents: chain_id={chain_id}, limit={limit}, offset={offset}"
+        )
+
+        # Build query parameters
+        params = {
+            "chain_id": chain_id,
+            "limit": min(limit, 100),  # Cap at 100
+            "offset": offset,
+        }
+
+        try:
+            response = requests.get(
+                f"{SCAN_API_URL}/agents",
+                params=params,
+                timeout=30,
+            )
+            response.raise_for_status()
+
+            data = response.json()
+            self._logger.debug(
+                f"Retrieved {len(data.get('items', []))} agents "
+                f"(total: {data.get('total', 0)})"
+            )
+
+            return data
+
+        except requests.exceptions.RequestException as e:
+            self._logger.error(f"Failed to fetch agents from 8004scan: {str(e)}")
+            raise ConnectionError(f"8004scan API request failed: {str(e)}") from e
+
     def get_metadata(self, agent_id: int, key: str) -> str:
         """
         Get metadata value for an agent.

bnbagent/constants.py

@@ -254,11 +254,11 @@ def sign_message(self, message: str) -> Dict[str, Any]:
         signable_message = encode_defunct(text=message)
         signed_message = self._account.sign_message(signable_message)
 
-        self._logger.debug(f"Message signed: hash={signed_message.messageHash.hex()}")
+        self._logger.debug(f"Message signed: hash={signed_message.message_hash.hex()}")
 
         # Return dict format for consistent interface across wallet providers
         return {
-            "messageHash": signed_message.messageHash,
+            "messageHash": signed_message.message_hash,
             "r": signed_message.r,
             "s": signed_message.s,
             "v": signed_message.v,

bnbagent/erc8004_agent.py

@@ -48,7 +48,7 @@ def main():
     print(f"Contract: {sdk.contract_address}\n")
 
     # Define agent configuration
-    agent_name = "My Testnet Agent 03"
+    agent_name = "My Testnet Agent 06"
     agent_uri = sdk.generate_agent_uri(
         name=agent_name,
         description="A test agent running on BSC Testnet",

bnbagent/wallets/evm_wallet_provider.py

@@ -3,8 +3,9 @@
 """
 
 import pytest
-from unittest.mock import Mock, patch
+from unittest.mock import Mock, patch, MagicMock
 from bnbagent import ERC8004Agent, AgentEndpoint
+import requests
 
 
 class TestERC8004Agent:
@@ -300,3 +301,184 @@ def test_generate_agent_uri_requires_endpoints(self, sdk):
 
         with pytest.raises(ValueError, match="endpoints is required"):
             sdk.generate_agent_uri(name="Test", description="Test", endpoints=[])
+
+    def test_get_all_agents(self, sdk):
+        """Test get_all_agents API call"""
+        with patch("bnbagent.erc8004_agent.requests.get") as mock_get:
+            mock_response = Mock()
+            mock_response.json.return_value = {
+                "items": [
+                    {"token_id": 1, "name": "Agent 1"},
+                    {"token_id": 2, "name": "Agent 2"},
+                ],
+                "total": 2,
+                "limit": 10,
+                "offset": 0,
+            }
+            mock_response.raise_for_status = Mock()
+            mock_get.return_value = mock_response
+
+            result = sdk.get_all_agents(limit=10, offset=0)
+
+            assert "items" in result
+            assert len(result["items"]) == 2
+            assert result["total"] == 2
+
+    def test_get_all_agents_with_pagination(self, sdk):
+        """Test get_all_agents with pagination parameters"""
+        with patch("bnbagent.erc8004_agent.requests.get") as mock_get:
+            mock_response = Mock()
+            mock_response.json.return_value = {
+                "items": [{"token_id": 11, "name": "Agent 11"}],
+                "total": 15,
+                "limit": 5,
+                "offset": 10,
+            }
+            mock_response.raise_for_status = Mock()
+            mock_get.return_value = mock_response
+
+            result = sdk.get_all_agents(limit=5, offset=10)
+
+            assert result["offset"] == 10
+            assert result["limit"] == 5
+            mock_get.assert_called_once()
+            call_args = mock_get.call_args
+            assert call_args[1]["params"]["limit"] == 5
+            assert call_args[1]["params"]["offset"] == 10
+
+    def test_get_all_agents_connection_error(self, sdk):
+        """Test get_all_agents handles connection errors"""
+        with patch("bnbagent.erc8004_agent.requests.get") as mock_get:
+            mock_get.side_effect = requests.exceptions.ConnectionError("Network error")
+
+            with pytest.raises(ConnectionError, match="8004scan API request failed"):
+                sdk.get_all_agents()
+
+    def test_get_all_agents_uses_network_chain_id(self, sdk):
+        """Test get_all_agents uses chain_id from network config"""
+        with patch("bnbagent.erc8004_agent.requests.get") as mock_get:
+            mock_response = Mock()
+            mock_response.json.return_value = {"items": [], "total": 0}
+            mock_response.raise_for_status = Mock()
+            mock_get.return_value = mock_response
+
+            sdk.get_all_agents()
+
+            call_args = mock_get.call_args
+            # Should use chain_id from network config (97 for bsc-testnet)
+            assert call_args[1]["params"]["chain_id"] == 97
+
+    def test_get_local_agent_info_not_found(self, sdk):
+        """Test get_local_agent_info returns None for non-existent agent"""
+        with patch.object(sdk.state_manager, "get", return_value=[]):
+            result = sdk.get_local_agent_info("NonExistent Agent")
+            assert result is None
+
+    def test_get_local_agent_info_found(self, sdk):
+        """Test get_local_agent_info returns agent info when found"""
+        registered_agents = [
+            {
+                "name": "Test Agent",
+                "agent_uri": "data:application/json;base64,xxx",
+                "agent_id": 1,
+                "transaction_hash": "0x123",
+            }
+        ]
+        with patch.object(sdk.state_manager, "get", return_value=registered_agents):
+            result = sdk.get_local_agent_info("Test Agent")
+            assert result is not None
+            assert result["name"] == "Test Agent"
+            assert result["agent_id"] == 1
+
+    def test_get_local_agent_info_empty_name(self, sdk):
+        """Test get_local_agent_info with empty name"""
+        result = sdk.get_local_agent_info("")
+        assert result is None
+
+        result = sdk.get_local_agent_info(None)
+        assert result is None
+
+    def test_wallet_address_property(self, sdk, mock_wallet_provider):
+        """Test wallet_address property"""
+        assert sdk.wallet_address == mock_wallet_provider.address
+
+    def test_contract_address_property(self, sdk):
+        """Test contract_address property"""
+        assert sdk.contract_address == self.DEFAULT_CONTRACT_ADDRESS
+
+    def test_network_property(self, sdk):
+        """Test network property returns config"""
+        network = sdk.network
+        assert "name" in network
+        assert "chain_id" in network
+        assert network["name"] == "bsc-testnet"
+
+    def test_generate_agent_uri_with_supported_trust(self, sdk):
+        """Test generate_agent_uri with supportedTrust field"""
+        agent_uri = sdk.generate_agent_uri(
+            name="Trust Agent",
+            description="Agent with trust mechanisms",
+            endpoints=[
+                AgentEndpoint(
+                    name="A2A",
+                    endpoint="https://agent.example/.well-known/agent-card.json",
+                )
+            ],
+            supported_trust=["reputation", "crypto-economic"],
+        )
+
+        assert isinstance(agent_uri, str)
+        agent_data = sdk.parse_agent_uri(agent_uri)
+        assert "supportedTrust" in agent_data
+        assert "reputation" in agent_data["supportedTrust"]
+
+    def test_generate_agent_uri_with_image(self, sdk):
+        """Test generate_agent_uri with image field"""
+        agent_uri = sdk.generate_agent_uri(
+            name="Image Agent",
+            description="Agent with image",
+            endpoints=[
+                AgentEndpoint(
+                    name="A2A",
+                    endpoint="https://agent.example/.well-known/agent-card.json",
+                )
+            ],
+            image="https://example.com/agent-image.png",
+        )
+
+        agent_data = sdk.parse_agent_uri(agent_uri)
+        assert agent_data["image"] == "https://example.com/agent-image.png"
+
+
+class TestERC8004AgentInitialization:
+    """Test cases for SDK initialization edge cases"""
+
+    def test_invalid_network_raises_error(self):
+        """Test that invalid network raises ValueError"""
+        mock_wallet = Mock()
+        mock_wallet.address = "0x" + "0" * 40
+
+        with pytest.raises(ValueError, match="Unknown network"):
+            with patch("bnbagent.erc8004_agent.Web3") as mock_web3_class:
+                mock_web3 = Mock()
+                mock_web3.is_connected.return_value = True
+                mock_web3_class.return_value = mock_web3
+                ERC8004Agent(wallet_provider=mock_wallet, network="invalid-network")
+
+    def test_missing_wallet_provider_raises_error(self):
+        """Test that missing wallet_provider raises ValueError"""
+        with pytest.raises(ValueError, match="wallet_provider is required"):
+            ERC8004Agent(wallet_provider=None, network="bsc-testnet")
+
+    def test_rpc_connection_failure(self):
+        """Test that RPC connection failure raises ConnectionError"""
+        mock_wallet = Mock()
+        mock_wallet.address = "0x" + "0" * 40
+
+        with patch("bnbagent.erc8004_agent.Web3") as mock_web3_class:
+            mock_web3 = Mock()
+            mock_web3.is_connected.return_value = False
+            mock_web3_class.return_value = mock_web3
+
+            with pytest.raises(ConnectionError, match="Failed to connect to RPC"):
+                ERC8004Agent(wallet_provider=mock_wallet, network="bsc-testnet")