agirails 2.2.0__tar.gz → 2.3.1__tar.gz

{agirails-2.2.0 → agirails-2.3.1}/.gitignore

@@ -92,4 +92,5 @@ secrets.json
 .ralph/
 .serena/
 CLAUDE.md
+SCRATCHPAD.md
 uv.lock

agirails-2.3.1/PKG-INFO

@@ -0,0 +1,226 @@
+Metadata-Version: 2.4
+Name: agirails
+Version: 2.3.1
+Summary: AGIRAILS Python SDK - Agent Commerce Transaction Protocol
+Project-URL: Homepage, https://agirails.io
+Project-URL: Documentation, https://docs.agirails.io
+Project-URL: Repository, https://github.com/agirails/sdk-python
+Project-URL: Issues, https://github.com/agirails/sdk-python/issues
+Author-email: AGIRAILS Team <developers@agirails.io>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: actp,ai-agents,base,blockchain,escrow,ethereum,payments,web3
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: aiofiles<25.0.0,>=24.0.0
+Requires-Dist: eth-abi<6.0.0,>=5.0.0
+Requires-Dist: eth-account<0.14.0,>=0.13.0
+Requires-Dist: eth-utils<6.0.0,>=5.0.0
+Requires-Dist: httpx<1.0.0,>=0.27.0
+Requires-Dist: pydantic<3.0.0,>=2.6.0
+Requires-Dist: python-dateutil<3.0.0,>=2.8.0
+Requires-Dist: rich<14.0.0,>=13.0.0
+Requires-Dist: typer<1.0.0,>=0.12.0
+Requires-Dist: typing-extensions<5.0.0,>=4.0.0; python_version < '3.10'
+Requires-Dist: web3<8.0.0,>=7.0.0
+Provides-Extra: dev
+Requires-Dist: black>=24.0.0; extra == 'dev'
+Requires-Dist: hypothesis>=6.100.0; extra == 'dev'
+Requires-Dist: mypy>=1.11.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest-benchmark>=4.0.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest-timeout>=2.3.0; extra == 'dev'
+Requires-Dist: pytest-xdist>=3.5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.6.0; extra == 'dev'
+Requires-Dist: types-aiofiles>=24.0.0; extra == 'dev'
+Requires-Dist: types-python-dateutil>=2.8.0; extra == 'dev'
+Provides-Extra: mutation
+Requires-Dist: mutmut>=2.4.0; extra == 'mutation'
+Provides-Extra: security
+Requires-Dist: bandit>=1.7.0; extra == 'security'
+Requires-Dist: pip-audit>=2.7.0; extra == 'security'
+Requires-Dist: safety>=3.0.0; extra == 'security'
+Description-Content-Type: text/markdown
+
+# AGIRAILS Python SDK
+
+[![PyPI](https://img.shields.io/pypi/v/agirails.svg)](https://pypi.org/project/agirails/)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Tests](https://img.shields.io/badge/tests-1738%20passed-brightgreen.svg)]()
+
+The official Python SDK for the **Agent Commerce Transaction Protocol (ACTP)** — enabling AI agents to transact with each other through blockchain-based escrow on Base L2.
+
+**Full 1:1 parity with TypeScript SDK v2.5.0.**
+
+## Install
+
+```bash
+pip install agirails==2.3.0
+```
+
+## Features
+
+- **Adapter Routing** — priority-based adapter selection (Standard, Basic, X402)
+- **x402 Payments** — HTTP-based instant payments with relay fee splitting
+- **ERC-8004 Identity** — on-chain agent identity resolution and reputation
+- **Keystore Security (AIP-13)** — fail-closed private key policy, `ACTP_KEYSTORE_BASE64` for CI/CD
+- **AGIRAILS.md Source of Truth** — parse, hash, publish, pull, diff agent configs
+- **Smart Wallet (ERC-4337)** — batched transactions with paymaster gas sponsorship
+- **Lazy Publish** — mainnet activation deferred to first real transaction
+- **Three-tier API** — Basic, Standard, and Advanced levels
+- **Mock Runtime** — full local testing without blockchain
+- **CLI** — `actp pay`, `publish`, `pull`, `diff`, `deploy:env`, `deploy:check`
+- **Async-first** — built on asyncio
+- **1,738 tests passing**
+
+## Quick Start
+
+```python
+import asyncio
+from agirails import ACTPClient
+
+async def main():
+    client = await ACTPClient.create(mode="mock", requester_address="0x1234...")
+
+    # Adapter router auto-selects the best path
+    # EVM address → ACTP (StandardAdapter)
+    result = await client.pay({"to": "0xProvider...", "amount": "10.00"})
+
+    # HTTP URL → x402 instant payment
+    result = await client.pay({"to": "https://api.example.com/pay", "amount": "5.00"})
+
+    # Agent ID → ERC-8004 resolve → ACTP
+    result = await client.pay({"to": "12345", "amount": "10.00"})
+
+    print(f"Transaction: {result.tx_id}, State: {result.state}")
+
+asyncio.run(main())
+```
+
+## Adapter Routing
+
+Priority-based adapter selection matching TypeScript `AdapterRouter`:
+
+| Adapter | Priority | Target | Use Case |
+|---------|----------|--------|----------|
+| **X402Adapter** | 70 | `https://...` URLs | Instant HTTP payments with relay fee splitting |
+| **StandardAdapter** | 60 | `0x...` addresses | Full ACTP lifecycle with escrow |
+| **BasicAdapter** | 50 | `0x...` addresses | Simple pay-and-forget (Smart Wallet batched) |
+
+## Keystore & Deployment Security (AIP-13)
+
+Fail-closed private key policy with network-aware enforcement:
+
+| Network | `ACTP_PRIVATE_KEY` | Behavior |
+|---------|-------------------|----------|
+| mock | Allowed | Silent |
+| testnet (base-sepolia) | Allowed | Warn once |
+| mainnet (base-mainnet) | Blocked | Hard fail |
+
+**Resolution order:** `ACTP_PRIVATE_KEY` → `ACTP_KEYSTORE_BASE64` + `ACTP_KEY_PASSWORD` → `.actp/keystore.json` → `None`
+
+```bash
+# Generate base64 keystore for CI/CD
+actp deploy:env
+
+# Scan repo for exposed secrets
+actp deploy:check
+```
+
+## AGIRAILS.md Config Management
+
+```bash
+actp publish --network base-sepolia    # Hash + upload to IPFS + register on-chain
+actp pull --network base-sepolia       # Fetch config from chain
+actp diff --network base-sepolia       # Compare local vs on-chain
+```
+
+## Transaction Lifecycle
+
+```
+INITIATED → QUOTED → COMMITTED → IN_PROGRESS → DELIVERED → SETTLED
+                ↘                      ↘              ↘
+              CANCELLED              CANCELLED      DISPUTED → SETTLED
+```
+
+## CLI
+
+```bash
+# Payments
+actp pay <to> <amount> [--deadline TIME]
+actp balance [ADDRESS]
+
+# Transaction management
+actp tx list [--state STATE]
+actp tx status <tx_id>
+actp tx deliver <tx_id>
+actp tx settle <tx_id>
+
+# Config sync
+actp publish [path]
+actp pull [path] [--network NETWORK]
+actp diff [path] [--network NETWORK]
+
+# Deployment security
+actp deploy:env
+actp deploy:check [path] [--fix]
+
+# Mock mode
+actp mint <address> <amount>
+actp time advance <duration>
+```
+
+## SDK Parity
+
+Full 1:1 parity with TypeScript SDK v2.5.0:
+
+| Feature | Python | TypeScript |
+|---------|--------|------------|
+| Adapter Routing | AdapterRouter + 3 adapters | AdapterRouter + 3 adapters |
+| x402 Payments | X402Adapter with relay | X402Adapter with relay |
+| ERC-8004 Identity | ERC8004Bridge + ReputationReporter | ERC8004Bridge + ReputationReporter |
+| Keystore AIP-13 | Full (30-min TTL cache) | Full (30-min TTL cache) |
+| AGIRAILS.md SOT | parse, hash, publish, pull, diff | parse, hash, publish, pull, diff |
+| Smart Wallet | ERC-4337 scaffolding | ERC-4337 full |
+| Lazy Publish | pending-publish lifecycle | pending-publish lifecycle |
+| CLI Commands | pay, publish, pull, diff, deploy:* | pay, publish, pull, diff, deploy:* |
+| State Machine | 8 states, all transitions | 8 states, all transitions |
+| Cross-SDK Tests | Shared test vectors | Shared test vectors |
+
+## Testing
+
+```bash
+pytest                           # Run all 1,738 tests
+pytest -v                        # Verbose output
+pytest tests/test_adapters/      # Adapter tests only
+pytest -k "test_pay"             # Pattern match
+```
+
+## Requirements
+
+- Python 3.9+
+- Dependencies: web3, eth-account, pydantic, aiofiles, httpx, typer, rich
+
+## Links
+
+- [PyPI](https://pypi.org/project/agirails/)
+- [Documentation](https://docs.agirails.io)
+- [GitHub](https://github.com/agirails/sdk-python)
+- [Discord](https://discord.gg/nuhCt75qe4)
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE) for details.

agirails-2.3.1/README.md

@@ -0,0 +1,170 @@
+# AGIRAILS Python SDK
+
+[![PyPI](https://img.shields.io/pypi/v/agirails.svg)](https://pypi.org/project/agirails/)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Tests](https://img.shields.io/badge/tests-1738%20passed-brightgreen.svg)]()
+
+The official Python SDK for the **Agent Commerce Transaction Protocol (ACTP)** — enabling AI agents to transact with each other through blockchain-based escrow on Base L2.
+
+**Full 1:1 parity with TypeScript SDK v2.5.0.**
+
+## Install
+
+```bash
+pip install agirails==2.3.0
+```
+
+## Features
+
+- **Adapter Routing** — priority-based adapter selection (Standard, Basic, X402)
+- **x402 Payments** — HTTP-based instant payments with relay fee splitting
+- **ERC-8004 Identity** — on-chain agent identity resolution and reputation
+- **Keystore Security (AIP-13)** — fail-closed private key policy, `ACTP_KEYSTORE_BASE64` for CI/CD
+- **AGIRAILS.md Source of Truth** — parse, hash, publish, pull, diff agent configs
+- **Smart Wallet (ERC-4337)** — batched transactions with paymaster gas sponsorship
+- **Lazy Publish** — mainnet activation deferred to first real transaction
+- **Three-tier API** — Basic, Standard, and Advanced levels
+- **Mock Runtime** — full local testing without blockchain
+- **CLI** — `actp pay`, `publish`, `pull`, `diff`, `deploy:env`, `deploy:check`
+- **Async-first** — built on asyncio
+- **1,738 tests passing**
+
+## Quick Start
+
+```python
+import asyncio
+from agirails import ACTPClient
+
+async def main():
+    client = await ACTPClient.create(mode="mock", requester_address="0x1234...")
+
+    # Adapter router auto-selects the best path
+    # EVM address → ACTP (StandardAdapter)
+    result = await client.pay({"to": "0xProvider...", "amount": "10.00"})
+
+    # HTTP URL → x402 instant payment
+    result = await client.pay({"to": "https://api.example.com/pay", "amount": "5.00"})
+
+    # Agent ID → ERC-8004 resolve → ACTP
+    result = await client.pay({"to": "12345", "amount": "10.00"})
+
+    print(f"Transaction: {result.tx_id}, State: {result.state}")
+
+asyncio.run(main())
+```
+
+## Adapter Routing
+
+Priority-based adapter selection matching TypeScript `AdapterRouter`:
+
+| Adapter | Priority | Target | Use Case |
+|---------|----------|--------|----------|
+| **X402Adapter** | 70 | `https://...` URLs | Instant HTTP payments with relay fee splitting |
+| **StandardAdapter** | 60 | `0x...` addresses | Full ACTP lifecycle with escrow |
+| **BasicAdapter** | 50 | `0x...` addresses | Simple pay-and-forget (Smart Wallet batched) |
+
+## Keystore & Deployment Security (AIP-13)
+
+Fail-closed private key policy with network-aware enforcement:
+
+| Network | `ACTP_PRIVATE_KEY` | Behavior |
+|---------|-------------------|----------|
+| mock | Allowed | Silent |
+| testnet (base-sepolia) | Allowed | Warn once |
+| mainnet (base-mainnet) | Blocked | Hard fail |
+
+**Resolution order:** `ACTP_PRIVATE_KEY` → `ACTP_KEYSTORE_BASE64` + `ACTP_KEY_PASSWORD` → `.actp/keystore.json` → `None`
+
+```bash
+# Generate base64 keystore for CI/CD
+actp deploy:env
+
+# Scan repo for exposed secrets
+actp deploy:check
+```
+
+## AGIRAILS.md Config Management
+
+```bash
+actp publish --network base-sepolia    # Hash + upload to IPFS + register on-chain
+actp pull --network base-sepolia       # Fetch config from chain
+actp diff --network base-sepolia       # Compare local vs on-chain
+```
+
+## Transaction Lifecycle
+
+```
+INITIATED → QUOTED → COMMITTED → IN_PROGRESS → DELIVERED → SETTLED
+                ↘                      ↘              ↘
+              CANCELLED              CANCELLED      DISPUTED → SETTLED
+```
+
+## CLI
+
+```bash
+# Payments
+actp pay <to> <amount> [--deadline TIME]
+actp balance [ADDRESS]
+
+# Transaction management
+actp tx list [--state STATE]
+actp tx status <tx_id>
+actp tx deliver <tx_id>
+actp tx settle <tx_id>
+
+# Config sync
+actp publish [path]
+actp pull [path] [--network NETWORK]
+actp diff [path] [--network NETWORK]
+
+# Deployment security
+actp deploy:env
+actp deploy:check [path] [--fix]
+
+# Mock mode
+actp mint <address> <amount>
+actp time advance <duration>
+```
+
+## SDK Parity
+
+Full 1:1 parity with TypeScript SDK v2.5.0:
+
+| Feature | Python | TypeScript |
+|---------|--------|------------|
+| Adapter Routing | AdapterRouter + 3 adapters | AdapterRouter + 3 adapters |
+| x402 Payments | X402Adapter with relay | X402Adapter with relay |
+| ERC-8004 Identity | ERC8004Bridge + ReputationReporter | ERC8004Bridge + ReputationReporter |
+| Keystore AIP-13 | Full (30-min TTL cache) | Full (30-min TTL cache) |
+| AGIRAILS.md SOT | parse, hash, publish, pull, diff | parse, hash, publish, pull, diff |
+| Smart Wallet | ERC-4337 scaffolding | ERC-4337 full |
+| Lazy Publish | pending-publish lifecycle | pending-publish lifecycle |
+| CLI Commands | pay, publish, pull, diff, deploy:* | pay, publish, pull, diff, deploy:* |
+| State Machine | 8 states, all transitions | 8 states, all transitions |
+| Cross-SDK Tests | Shared test vectors | Shared test vectors |
+
+## Testing
+
+```bash
+pytest                           # Run all 1,738 tests
+pytest -v                        # Verbose output
+pytest tests/test_adapters/      # Adapter tests only
+pytest -k "test_pay"             # Pattern match
+```
+
+## Requirements
+
+- Python 3.9+
+- Dependencies: web3, eth-account, pydantic, aiofiles, httpx, typer, rich
+
+## Links
+
+- [PyPI](https://pypi.org/project/agirails/)
+- [Documentation](https://docs.agirails.io)
+- [GitHub](https://github.com/agirails/sdk-python)
+- [Discord](https://discord.gg/nuhCt75qe4)
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE) for details.

{agirails-2.2.0 → agirails-2.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agirails"
-version = "2.2.0"
+version = "2.3.1"
 description = "AGIRAILS Python SDK - Agent Commerce Transaction Protocol"
 readme = "README.md"
 license = "Apache-2.0"

{agirails-2.2.0 → agirails-2.3.1}/src/agirails/adapters/__init__.py

@@ -5,7 +5,11 @@ Provides different API levels for ACTP transactions:
 
 - BasicAdapter: Simple pay() method for quick transactions
 - StandardAdapter: Full lifecycle control with separate methods
+- X402Adapter: HTTP 402 Payment Required atomic payments
 - BaseAdapter: Shared utilities (not for direct use)
+- AdapterRegistry: Central registry for managing adapters
+- AdapterRouter: Intelligent adapter selection with guard-rails
+- IAdapter: Common protocol interface for all adapters
 
 Usage:
     >>> from agirails import ACTPClient
@@ -17,6 +21,11 @@ Usage:
     >>> # Standard API (more control)
     >>> tx_id = await client.standard.create_transaction(...)
     >>> escrow_id = await client.standard.link_escrow(tx_id)
+    >>>
+    >>> # X402 API (atomic HTTP payments)
+    >>> from agirails.adapters import X402Adapter, X402AdapterConfig
+    >>> adapter = X402Adapter("0x...", X402AdapterConfig(...))
+    >>> result = await adapter.pay(UnifiedPayParams(to="https://...", amount="10"))
 """
 
 from agirails.adapters.base import (
@@ -38,6 +47,22 @@ from agirails.adapters.standard import (
     StandardTransactionParams,
     TransactionDetails,
 )
+from agirails.adapters.x402_adapter import (
+    X402Adapter,
+    X402AdapterConfig,
+    X402PayParams,
+    X402PayResult,
+)
+from agirails.adapters.types import (
+    AdapterMetadata,
+    AdapterSelectionResult,
+    PaymentIdentity,
+    PaymentMetadata,
+    UnifiedPayParams,
+)
+from agirails.adapters.i_adapter import IAdapter
+from agirails.adapters.adapter_registry import AdapterRegistry
+from agirails.adapters.adapter_router import AdapterRouter
 
 __all__ = [
     # Base
@@ -56,4 +81,20 @@ __all__ = [
     "StandardAdapter",
     "StandardTransactionParams",
     "TransactionDetails",
+    # X402
+    "X402Adapter",
+    "X402AdapterConfig",
+    "X402PayParams",
+    "X402PayResult",
+    # Types
+    "AdapterMetadata",
+    "AdapterSelectionResult",
+    "PaymentIdentity",
+    "PaymentMetadata",
+    "UnifiedPayParams",
+    # Interface
+    "IAdapter",
+    # Registry & Router
+    "AdapterRegistry",
+    "AdapterRouter",
 ]

agirails-2.3.1/src/agirails/adapters/adapter_registry.py

@@ -0,0 +1,150 @@
+"""
+AdapterRegistry - Central registry for payment adapters.
+
+Manages the collection of available adapters and provides
+methods for registration, lookup, and priority-based retrieval.
+
+1:1 port of TypeScript SDK AdapterRegistry.ts.
+
+@module adapters/AdapterRegistry
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List, Optional
+
+from agirails.adapters.i_adapter import IAdapter
+
+
+class AdapterRegistry:
+    """
+    AdapterRegistry - Central registry for managing available adapters.
+
+    The registry maintains a collection of adapters indexed by their ID.
+    It provides methods for:
+    - Registration and unregistration
+    - Lookup by ID
+    - Priority-sorted retrieval
+
+    Example::
+
+        registry = AdapterRegistry()
+
+        # Register adapters
+        registry.register(basic_adapter)
+        registry.register(standard_adapter)
+
+        # Lookup by ID
+        adapter = registry.get('basic')
+
+        # Get all adapters sorted by priority
+        adapters = registry.get_by_priority()
+    """
+
+    def __init__(self) -> None:
+        """Initialize an empty adapter registry."""
+        self._adapters: Dict[str, IAdapter] = {}
+
+    def register(self, adapter: IAdapter) -> None:
+        """
+        Register an adapter.
+
+        If an adapter with the same ID already exists, it will be replaced.
+
+        Args:
+            adapter: Adapter to register.
+
+        Raises:
+            ValueError: If adapter has no metadata.id.
+        """
+        if not hasattr(adapter, "metadata") or not adapter.metadata or not adapter.metadata.id:
+            raise ValueError("Cannot register adapter without metadata.id")
+        self._adapters[adapter.metadata.id] = adapter
+
+    def unregister(self, adapter_id: str) -> bool:
+        """
+        Unregister an adapter by ID.
+
+        Args:
+            adapter_id: Adapter ID to remove.
+
+        Returns:
+            True if adapter was found and removed, False otherwise.
+        """
+        if adapter_id in self._adapters:
+            del self._adapters[adapter_id]
+            return True
+        return False
+
+    def get(self, adapter_id: str) -> Optional[IAdapter]:
+        """
+        Get an adapter by ID.
+
+        Args:
+            adapter_id: Adapter ID to look up.
+
+        Returns:
+            The adapter or None if not found.
+        """
+        return self._adapters.get(adapter_id)
+
+    def get_all(self) -> List[IAdapter]:
+        """
+        Get all registered adapters.
+
+        Returns adapters in insertion order.
+
+        Returns:
+            List of all registered adapters.
+        """
+        return list(self._adapters.values())
+
+    def has(self, adapter_id: str) -> bool:
+        """
+        Check if an adapter is registered.
+
+        Args:
+            adapter_id: Adapter ID to check.
+
+        Returns:
+            True if adapter is registered.
+        """
+        return adapter_id in self._adapters
+
+    def get_by_priority(self) -> List[IAdapter]:
+        """
+        Get adapters sorted by priority (highest first).
+
+        Higher priority adapters are tried first during selection.
+
+        Returns:
+            List of adapters sorted by priority descending.
+        """
+        return sorted(self.get_all(), key=lambda a: a.metadata.priority, reverse=True)
+
+    @property
+    def size(self) -> int:
+        """
+        Get the number of registered adapters.
+
+        Returns:
+            Number of adapters.
+        """
+        return len(self._adapters)
+
+    def get_ids(self) -> List[str]:
+        """
+        Get all adapter IDs.
+
+        Returns:
+            List of adapter IDs.
+        """
+        return list(self._adapters.keys())
+
+    def clear(self) -> None:
+        """
+        Clear all registered adapters.
+
+        Primarily useful for testing.
+        """
+        self._adapters.clear()