bnbagent 0.0.1__tar.gz

bnbagent-0.0.1/.github/workflows/release.yaml

@@ -0,0 +1,132 @@
+name: Release bnbagent to PyPI
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version to release (e.g., 0.1.0)'
+        required: true
+        type: string
+      release_to_prod:
+        description: 'Release to production PyPI (unchecked = test PyPI)'
+        required: false
+        default: false
+        type: boolean
+      skip_tests:
+        description: 'Skip tests before release'
+        required: false
+        default: false
+        type: boolean
+
+jobs:
+  release:
+    name: Build and Publish to PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write  # Required for trusted publishing to PyPI
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Fetch all history for tags
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Install dependencies
+        run: |
+          uv sync --extra dev
+
+      - name: Run tests
+        if: ${{ !inputs.skip_tests }}
+        run: |
+          uv run pytest -v
+
+      - name: Update version in pyproject.toml
+        run: |
+          # Update version in pyproject.toml
+          sed -i 's/^version = ".*"/version = "${{ inputs.version }}"/' pyproject.toml
+          echo "Updated version to ${{ inputs.version }}"
+          cat pyproject.toml | grep "^version"
+
+      - name: Build package
+        run: |
+          uv build
+
+      - name: Check package contents
+        run: |
+          ls -lh dist/
+          echo "Package files:"
+          find dist -type f
+
+      - name: Publish to Production PyPI
+        if: ${{ inputs.release_to_prod }}
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: ./dist/
+          print-hash: true
+          password: ${{ secrets.PYPI_API_TOKEN }}
+          # Uses trusted publishing (OIDC) - no token needed
+          # Configure OIDC in PyPI account settings: https://pypi.org/manage/account/publishing/
+
+      - name: Publish to Test PyPI
+        if: ${{ !inputs.release_to_prod }}
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: ./dist/
+          print-hash: true
+          repository-url: https://test.pypi.org/legacy/
+          password: ${{ secrets.TEST_PYPI_API_TOKEN }}
+          # For Test PyPI, you can use trusted publishing or API token
+          # If using API token, set TEST_PYPI_API_TOKEN secret
+
+      - name: Commit version update
+        if: success() && inputs.release_to_prod
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add pyproject.toml
+          git commit -m "chore: bump version to ${{ inputs.version }}" || exit 0
+          git push origin HEAD:${{ github.ref_name }} || echo "No changes to commit or branch protection"
+
+      - name: Create Git tag
+        if: success() && inputs.release_to_prod
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git tag -a "bnbagent-v${{ inputs.version }}" -m "Release bnbagent v${{ inputs.version }}"
+          git push origin "bnbagent-v${{ inputs.version }}"
+
+      - name: Create GitHub Release
+        if: success() && inputs.release_to_prod
+        uses: softprops/action-gh-release@v1
+        with:
+          tag_name: bnbagent-v${{ inputs.version }}
+          name: bnbagent v${{ inputs.version }}
+          body: |
+            ## bnbagent v${{ inputs.version }}
+
+            Python SDK for ERC-8004 on-chain agent registration and management.
+
+            ### Installation
+
+            ```bash
+            pip install bnbagent==${{ inputs.version }}
+            ```
+
+            ✅ Published to **Production PyPI**
+
+            ### Changes
+
+            See [CHANGELOG.md](https://github.com/${{ github.repository }}/blob/main/CHANGELOG.md) for details.
+          draft: false
+          prerelease: false

bnbagent-0.0.1/.gitignore

@@ -0,0 +1,61 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+env/
+ENV/
+.venv/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Key files (NEVER commit private keys!)
+.bnbagent_state
+*.key
+*.pem
+*.keystore
+
+# Environment variables
+.env
+.env.local
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Type checking / Linting
+.mypy_cache/
+.ruff_cache/
+
+# Logs
+*.log
+
+# OS
+.DS_Store
+Thumbs.db

bnbagent-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BNBChain Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bnbagent-0.0.1/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: bnbagent
+Version: 0.0.1
+Summary: Python SDK for ERC-8004 on-chain agent registration and management
+Project-URL: Homepage, https://github.com/bnb-chain/bnbagent-sdk
+Project-URL: Documentation, https://github.com/bnb-chain/bnbagent-sdk#readme
+Project-URL: Repository, https://github.com/bnb-chain/bnbagent-sdk
+Project-URL: Issues, https://github.com/bnb-chain/bnbagent-sdk/issues
+Author-email: Your Name <your.email@example.com>
+License: MIT
+License-File: LICENSE
+Keywords: agent,binance-smart-chain,blockchain,bsc,erc-8004,ethereum,sdk,web3
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: eth-account>=0.10.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: web3>=6.15.0
+Provides-Extra: dev
+Requires-Dist: pytest-mock>=3.11.0; extra == 'dev'
+Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# BNBAgent SDK
+
+Python SDK for ERC-8004 on-chain agent registration and management.
+
+## Features
+
+- **Agent Registration**: Register AI agents on-chain via ERC-8004 Identity Registry
+- **Agent Discovery**: Query and browse registered agents
+- **Zero Gas Fees**: MegaFuel Paymaster sponsorship for contract operations
+- **Keystore Encryption**: Password-protected wallet (Keystore V3, compatible with MetaMask/Geth)
+- **Extensible Wallet**: WalletProvider abstraction for EVM/MPC wallets
+
+## Network
+
+### BSC Testnet (Chain ID: 97)
+
+| Contract | Address |
+|----------|---------|
+| Identity Registry | `0x8004A818BFB912233c491871b3d84c89A494BD9e` |
+| Reputation Registry | `0x8004B663056A597Dffe9eCcC1965A193B7388713` |
+
+### BSC Mainnet (Chain ID: 56)
+
+> **Note:** Mainnet support is not yet available. It will be supported soon. Stay tuned!
+
+## Installation
+
+> **Requirements:** Python 3.10+ and `uv` (recommended) or `pip`
+
+```bash
+pip install git+https://github.com/bnb-chain/bnbagent-sdk.git
+```
+
+For development:
+
+```bash
+git clone https://github.com/bnb-chain/bnbagent-sdk.git
+cd bnbagent-sdk
+uv sync --extra dev  # or: pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```python
+import os
+from bnbagent import ERC8004Agent, EVMWalletProvider, AgentEndpoint
+
+# Create wallet and SDK
+wallet = EVMWalletProvider(password=os.getenv("WALLET_PASSWORD"))
+sdk = ERC8004Agent(wallet_provider=wallet, network="bsc-testnet")
+
+# Generate and register agent
+agent_uri = sdk.generate_agent_uri(
+    name="My Agent",
+    description="A test agent",
+    endpoints=[
+        AgentEndpoint(
+            name="A2A",
+            endpoint="https://agent.example/.well-known/agent-card.json",
+            version="0.3.0"
+        )
+    ]
+)
+
+result = sdk.register_agent(agent_uri=agent_uri)
+print(f"Agent registered with ID: {result['agentId']}")
+```
+
+## Core Operations
+
+### Register Agent
+
+```python
+result = sdk.register_agent(agent_uri=agent_uri)
+# Returns: {agentId, transactionHash, agentURI, ...}
+```
+
+### Discover Agents
+
+```python
+# List agents with pagination
+agents = sdk.get_all_agents(limit=10, offset=0)
+for agent in agents['items']:
+    print(f"#{agent['token_id']}: {agent['name']}")
+
+# Get single agent info (on-chain)
+info = sdk.get_agent_info(agent_id=1)
+```
+
+### Update Agent
+
+```python
+new_uri = sdk.generate_agent_uri(
+    name="Updated Agent",
+    description="New description",
+    endpoints=[...],
+    agent_id=1  # Include for registrations field
+)
+sdk.set_agent_uri(agent_id=1, agent_uri=new_uri)
+```
+
+### Metadata
+
+```python
+# Get/set metadata
+version = sdk.get_metadata(agent_id=1, key="version")
+sdk.set_metadata(agent_id=1, key="version", value="2.0.0")
+```
+
+## Examples
+
+See [`examples/testnet_usage.py`](examples/testnet_usage.py) for a complete working example including:
+- Wallet creation and management
+- Agent registration
+- Agent discovery and querying
+- Metadata operations
+
+## Documentation
+
+- **[API Reference](bnbagent/README.md)** - Complete API documentation with workflow examples
+
+## Security
+
+The SDK stores encrypted wallet state in `.bnbagent_state`:
+
+- **Encryption**: AES-128-CTR with scrypt key derivation (Keystore V3)
+- **File permissions**: `0o600` (owner read/write only)
+- **Format**: Compatible with MetaMask/Geth keystore
+
+### Best Practices
+
+1. **Never commit secrets**: Add `.bnbagent_state` to `.gitignore`
+2. **Use environment variables**: Store `WALLET_PASSWORD` in env, not in code
+3. **Backup your wallet**: Export keystore JSON and store securely
+
+```python
+# Export wallet for backup
+keystore = wallet.export_keystore()
+with open("backup-wallet.json", "w") as f:
+    json.dump(keystore, f)
+```
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `WALLET_PASSWORD` | Password for wallet encryption/decryption |
+
+## Error Handling
+
+```python
+try:
+    result = sdk.register_agent(agent_uri=agent_uri)
+except ConnectionError as e:
+    print(f"RPC connection failed: {e}")
+except ValueError as e:
+    print(f"Invalid input: {e}")
+except RuntimeError as e:
+    print(f"Transaction failed: {e}")
+```
+
+## Development
+
+### Running Tests
+
+```bash
+uv run pytest              # Run tests
+uv run pytest --cov=bnbagent  # With coverage
+```
+
+### Contributing
+
+1. Follow existing code patterns
+2. Include error handling
+3. Add tests for new features
+4. Run tests before submitting
+
+## License
+
+This SDK is part of the ERC-8004 implementation project.

bnbagent-0.0.1/README.md

@@ -0,0 +1,180 @@
+# BNBAgent SDK
+
+Python SDK for ERC-8004 on-chain agent registration and management.
+
+## Features
+
+- **Agent Registration**: Register AI agents on-chain via ERC-8004 Identity Registry
+- **Agent Discovery**: Query and browse registered agents
+- **Zero Gas Fees**: MegaFuel Paymaster sponsorship for contract operations
+- **Keystore Encryption**: Password-protected wallet (Keystore V3, compatible with MetaMask/Geth)
+- **Extensible Wallet**: WalletProvider abstraction for EVM/MPC wallets
+
+## Network
+
+### BSC Testnet (Chain ID: 97)
+
+| Contract | Address |
+|----------|---------|
+| Identity Registry | `0x8004A818BFB912233c491871b3d84c89A494BD9e` |
+| Reputation Registry | `0x8004B663056A597Dffe9eCcC1965A193B7388713` |
+
+### BSC Mainnet (Chain ID: 56)
+
+> **Note:** Mainnet support is not yet available. It will be supported soon. Stay tuned!
+
+## Installation
+
+> **Requirements:** Python 3.10+ and `uv` (recommended) or `pip`
+
+```bash
+pip install git+https://github.com/bnb-chain/bnbagent-sdk.git
+```
+
+For development:
+
+```bash
+git clone https://github.com/bnb-chain/bnbagent-sdk.git
+cd bnbagent-sdk
+uv sync --extra dev  # or: pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```python
+import os
+from bnbagent import ERC8004Agent, EVMWalletProvider, AgentEndpoint
+
+# Create wallet and SDK
+wallet = EVMWalletProvider(password=os.getenv("WALLET_PASSWORD"))
+sdk = ERC8004Agent(wallet_provider=wallet, network="bsc-testnet")
+
+# Generate and register agent
+agent_uri = sdk.generate_agent_uri(
+    name="My Agent",
+    description="A test agent",
+    endpoints=[
+        AgentEndpoint(
+            name="A2A",
+            endpoint="https://agent.example/.well-known/agent-card.json",
+            version="0.3.0"
+        )
+    ]
+)
+
+result = sdk.register_agent(agent_uri=agent_uri)
+print(f"Agent registered with ID: {result['agentId']}")
+```
+
+## Core Operations
+
+### Register Agent
+
+```python
+result = sdk.register_agent(agent_uri=agent_uri)
+# Returns: {agentId, transactionHash, agentURI, ...}
+```
+
+### Discover Agents
+
+```python
+# List agents with pagination
+agents = sdk.get_all_agents(limit=10, offset=0)
+for agent in agents['items']:
+    print(f"#{agent['token_id']}: {agent['name']}")
+
+# Get single agent info (on-chain)
+info = sdk.get_agent_info(agent_id=1)
+```
+
+### Update Agent
+
+```python
+new_uri = sdk.generate_agent_uri(
+    name="Updated Agent",
+    description="New description",
+    endpoints=[...],
+    agent_id=1  # Include for registrations field
+)
+sdk.set_agent_uri(agent_id=1, agent_uri=new_uri)
+```
+
+### Metadata
+
+```python
+# Get/set metadata
+version = sdk.get_metadata(agent_id=1, key="version")
+sdk.set_metadata(agent_id=1, key="version", value="2.0.0")
+```
+
+## Examples
+
+See [`examples/testnet_usage.py`](examples/testnet_usage.py) for a complete working example including:
+- Wallet creation and management
+- Agent registration
+- Agent discovery and querying
+- Metadata operations
+
+## Documentation
+
+- **[API Reference](bnbagent/README.md)** - Complete API documentation with workflow examples
+
+## Security
+
+The SDK stores encrypted wallet state in `.bnbagent_state`:
+
+- **Encryption**: AES-128-CTR with scrypt key derivation (Keystore V3)
+- **File permissions**: `0o600` (owner read/write only)
+- **Format**: Compatible with MetaMask/Geth keystore
+
+### Best Practices
+
+1. **Never commit secrets**: Add `.bnbagent_state` to `.gitignore`
+2. **Use environment variables**: Store `WALLET_PASSWORD` in env, not in code
+3. **Backup your wallet**: Export keystore JSON and store securely
+
+```python
+# Export wallet for backup
+keystore = wallet.export_keystore()
+with open("backup-wallet.json", "w") as f:
+    json.dump(keystore, f)
+```
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `WALLET_PASSWORD` | Password for wallet encryption/decryption |
+
+## Error Handling
+
+```python
+try:
+    result = sdk.register_agent(agent_uri=agent_uri)
+except ConnectionError as e:
+    print(f"RPC connection failed: {e}")
+except ValueError as e:
+    print(f"Invalid input: {e}")
+except RuntimeError as e:
+    print(f"Transaction failed: {e}")
+```
+
+## Development
+
+### Running Tests
+
+```bash
+uv run pytest              # Run tests
+uv run pytest --cov=bnbagent  # With coverage
+```
+
+### Contributing
+
+1. Follow existing code patterns
+2. Include error handling
+3. Add tests for new features
+4. Run tests before submitting
+
+## License
+
+This SDK is part of the ERC-8004 implementation project.