agirails 2.3.0__tar.gz → 2.3.1__tar.gz

{agirails-2.3.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.3.0 → agirails-2.3.1}/pyproject.toml

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

{agirails-2.3.0 → agirails-2.3.1}/src/agirails/client.py

@@ -317,7 +317,7 @@ class ACTPClient:
             )
 
         # Map mode to network name
-        network_name = "base-sepolia" if config.mode == "testnet" else "base"
+        network_name = "base-sepolia" if config.mode == "testnet" else "base-mainnet"
 
         # Create EAS helper if config provided or attestation required
         eas_helper = None

{agirails-2.3.0 → agirails-2.3.1}/src/agirails/config/networks.py

@@ -152,10 +152,7 @@ BASE_MAINNET = NetworkConfig(
         max_fee_per_gas=500_000_000,  # 0.5 gwei
         max_priority_fee_per_gas=100_000_000,  # 0.1 gwei
     ),
-    # SECURITY: $1,000 max transaction limit until contracts are audited.
-    # This limits exposure in case of undiscovered vulnerabilities.
-    # Will be removed/increased after formal security audit.
-    max_transaction_amount=1000,
+    # Security audit passed February 2026 — no findings. No transaction limit.
 )
 
 

{agirails-2.3.0 → agirails-2.3.1}/src/agirails/errors/__init__.py

@@ -37,6 +37,7 @@ from agirails.errors.validation import (
 )
 from agirails.errors.network import (
     NetworkError,
+    TransientRPCError,
     TransactionRevertedError,
     SignatureVerificationError,
 )
@@ -89,6 +90,7 @@ __all__ = [
     "InvalidAmountError",
     # Network
     "NetworkError",
+    "TransientRPCError",
     "TransactionRevertedError",
     "SignatureVerificationError",
     # Storage

{agirails-2.3.0 → agirails-2.3.1}/src/agirails/errors/network.py

@@ -95,6 +95,39 @@ class TransactionRevertedError(ACTPError):
         self.block_number = block_number
 
 
+class TransientRPCError(NetworkError):
+    """
+    Raised for transient RPC/network failures that are safe to retry.
+
+    Distinguishes retry-able failures (connection drops, rate limits,
+    timeouts) from permanent failures (contract reverts, invalid state).
+
+    BlockchainRuntime._rate_limited_call() retries on this class only.
+
+    Example:
+        >>> raise TransientRPCError("Rate limit exceeded", cause=original_error)
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        endpoint: Optional[str] = None,
+        cause: Optional[Exception] = None,
+        details: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        details = details or {}
+        if cause is not None:
+            details["cause"] = type(cause).__name__
+        super().__init__(
+            message,
+            endpoint=endpoint,
+            details=details,
+        )
+        self.code = "TRANSIENT_RPC_ERROR"
+        self.cause = cause
+
+
 class SignatureVerificationError(ACTPError):
     """
     Raised when a cryptographic signature verification fails.

agirails-2.3.1/src/agirails/protocol/base.py

@@ -0,0 +1,171 @@
+"""
+ContractBase: shared infrastructure for ACTPKernel and EscrowVault.
+
+Eliminates the verbatim duplication of _sign_and_send, _build_tx_params,
+_to_bytes32, and _to_receipt that existed in both contract wrappers.
+
+NonceManager integration is optional:
+- When nonce_manager is provided: get_nonce() / confirm_nonce() / release_nonce()
+  are called automatically inside _build_tx_params() and _sign_and_send().
+- When None: falls back to w3.eth.get_transaction_count("pending") — same
+  behavior as pre-refactor, backward compat preserved.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Dict, Optional
+
+from eth_account.signers.local import LocalAccount
+from web3 import AsyncWeb3
+from web3.contract import AsyncContract
+from web3.types import TxReceipt
+
+from agirails.errors.transaction import TransactionError
+from agirails.protocol.nonce import NonceManager
+from agirails.types.transaction import TransactionReceipt
+
+# Security Note (M-3): Default timeout for transaction receipts (5 minutes)
+DEFAULT_TX_WAIT_TIMEOUT = 300.0
+
+
+class ContractBase:
+    """
+    Abstract base for ACTPKernel and EscrowVault contract wrappers.
+
+    Owns the transaction lifecycle: build params -> sign -> send -> wait -> receipt.
+    Integrates NonceManager when provided, falls back to RPC nonce otherwise.
+    """
+
+    def __init__(
+        self,
+        contract: AsyncContract,
+        account: LocalAccount,
+        w3: AsyncWeb3,
+        chain_id: int,
+        *,
+        nonce_manager: Optional[NonceManager] = None,
+    ) -> None:
+        self.contract = contract
+        self.account = account
+        self.w3 = w3
+        self.chain_id = chain_id
+        self._nonce_manager = nonce_manager
+
+    async def _build_tx_params(
+        self,
+        gas_limit: int,
+        max_fee_per_gas: Optional[int] = None,
+        max_priority_fee_per_gas: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """Build EIP-1559 transaction parameters."""
+        # Use NonceManager when available; else ask chain directly
+        if self._nonce_manager is not None:
+            nonce = await self._nonce_manager.get_nonce()
+        else:
+            # Legacy path: fetch nonce from RPC including unconfirmed transactions
+            nonce = await self.w3.eth.get_transaction_count(
+                self.account.address, "pending"
+            )
+
+        # Get gas prices if not provided
+        if max_fee_per_gas is None or max_priority_fee_per_gas is None:
+            block = await self.w3.eth.get_block("latest")
+            base_fee = block.get("baseFeePerGas", 1_000_000_000)  # 1 gwei fallback
+
+            if max_priority_fee_per_gas is None:
+                max_priority_fee_per_gas = 1_000_000_000  # 1 gwei
+
+            if max_fee_per_gas is None:
+                # 2x base fee + priority fee
+                max_fee_per_gas = (base_fee * 2) + max_priority_fee_per_gas
+
+        return {
+            "from": self.account.address,
+            "nonce": nonce,
+            "gas": gas_limit,
+            "maxFeePerGas": max_fee_per_gas,
+            "maxPriorityFeePerGas": max_priority_fee_per_gas,
+            "chainId": self.chain_id,
+        }
+
+    async def _sign_and_send(
+        self,
+        tx: Dict[str, Any],
+        timeout: float = DEFAULT_TX_WAIT_TIMEOUT,
+    ) -> TxReceipt:
+        """
+        Sign and broadcast a transaction, wait for receipt.
+
+        Nonce lifecycle:
+        - Pre-broadcast failure  -> release_nonce (nonce never hit the chain)
+        - Post-broadcast timeout -> confirm_nonce (tx is in mempool, nonce consumed)
+        - Reverted tx (status=0) -> confirm_nonce (revert still consumed nonce)
+        - Success (status=1)     -> confirm_nonce
+
+        Security Note (M-3): Uses timeout to prevent indefinite hangs.
+        """
+        nonce: Optional[int] = tx.get("nonce")
+
+        signed_tx = self.w3.eth.account.sign_transaction(tx, self.account.key)
+        try:
+            tx_hash = await self.w3.eth.send_raw_transaction(
+                signed_tx.raw_transaction
+            )
+        except Exception:
+            # Broadcast failed — release nonce so it can be reused
+            if self._nonce_manager is not None and nonce is not None:
+                self._nonce_manager.release_nonce(nonce)
+            raise
+
+        # Transaction was broadcast — nonce is consumed regardless of outcome
+        try:
+            receipt = await asyncio.wait_for(
+                self.w3.eth.wait_for_transaction_receipt(tx_hash),
+                timeout=timeout,
+            )
+        except asyncio.TimeoutError:
+            # TX is in mempool — nonce is consumed
+            if self._nonce_manager is not None and nonce is not None:
+                self._nonce_manager.confirm_nonce(nonce)
+            raise TransactionError(
+                f"Transaction {tx_hash.hex()} timed out after {timeout}s. "
+                "Check network congestion and gas settings.",
+                tx_id=tx_hash.hex(),
+            )
+
+        # Confirm nonce whether tx succeeded or reverted (nonce was used on-chain)
+        if self._nonce_manager is not None and nonce is not None:
+            self._nonce_manager.confirm_nonce(nonce)
+
+        if receipt["status"] != 1:
+            raise TransactionError(
+                f"Transaction failed: {tx_hash.hex()}",
+                tx_id=tx_hash.hex(),
+            )
+
+        return receipt
+
+    def _to_bytes32(self, value: str) -> bytes:
+        """Convert hex string to bytes32."""
+        if value.startswith("0x"):
+            value = value[2:]
+        # Pad to 32 bytes if needed
+        value = value.zfill(64)
+        return bytes.fromhex(value)
+
+    def _to_receipt(self, receipt: TxReceipt) -> TransactionReceipt:
+        """Convert web3 receipt to TransactionReceipt."""
+        return TransactionReceipt(
+            transaction_hash=receipt["transactionHash"].hex()
+            if isinstance(receipt["transactionHash"], bytes)
+            else receipt["transactionHash"],
+            block_number=receipt["blockNumber"],
+            block_hash=receipt["blockHash"].hex()
+            if isinstance(receipt["blockHash"], bytes)
+            else receipt["blockHash"],
+            gas_used=receipt["gasUsed"],
+            effective_gas_price=receipt.get("effectiveGasPrice", 0),
+            status=receipt["status"],
+            logs=[dict(log) for log in receipt.get("logs", [])],
+        )