openclaw-algorand-plugin 0.5.0

package/skills/algorand-x402-python/references/explain-algorand-x402-python-reference.md

@@ -0,0 +1,315 @@
+# x402-avm Python Package Reference
+
+Detailed reference for the `x402-avm` Python package covering package structure, extras, async/sync variants, signer protocols, registration functions, constants, utilities, and algosdk encoding.
+
+## Package Structure
+
+The package is published on PyPI as `x402-avm` but all imports use the `x402` namespace:
+
+```
+x402/
+  __init__.py                  # x402Client, x402ClientSync, x402Facilitator, etc.
+  server.py                    # x402ResourceServer, x402ResourceServerSync
+  schemas.py                   # AssetAmount, Network, PaymentRequirements, etc.
+  http/
+    __init__.py                # HTTPFacilitatorClient, HTTPFacilitatorClientSync, PaymentOption, etc.
+    types.py                   # RouteConfig, RoutesConfig, FacilitatorConfig
+    clients/
+      __init__.py              # Lazy imports for httpx/requests
+      httpx.py                 # x402HttpxClient, wrapHttpxWithPayment, etc.
+      requests.py              # x402_requests, wrapRequestsWithPayment, etc.
+    middleware/
+      __init__.py              # Lazy imports for fastapi/flask
+      fastapi.py               # PaymentMiddlewareASGI, payment_middleware, etc.
+      flask.py                 # PaymentMiddleware, payment_middleware, etc.
+  mechanisms/
+    avm/
+      __init__.py              # Re-exports constants
+      constants.py             # Network IDs, USDC config, algod URLs
+      signer.py                # ClientAvmSigner, FacilitatorAvmSigner Protocols
+      utils.py                 # Address validation, encoding, network utils
+      exact/
+        __init__.py            # ExactAvmClientScheme, ExactAvmServerScheme, etc.
+        register.py            # register_exact_avm_client, register_exact_avm_server, etc.
+    evm/                       # EVM mechanism (same structure)
+    svm/                       # SVM mechanism (same structure)
+```
+
+## Extras
+
+| Extra | Installs | Use Case |
+|-------|----------|----------|
+| `[avm]` | `py-algorand-sdk>=2.0.0` | Algorand transaction signing |
+| `[evm]` | `web3`, `eth-account` | Ethereum/EVM transaction signing |
+| `[svm]` | `solders`, `solana-py` | Solana/SVM transaction signing |
+| `[fastapi]` | `fastapi[standard]>=0.115.0`, `starlette>=0.27.0` | FastAPI async middleware |
+| `[flask]` | `flask>=3.0.0` | Flask sync middleware |
+| `[httpx]` | `httpx>=0.28.1` | Async HTTP client |
+| `[requests]` | `requests>=2.31.0` | Sync HTTP client |
+| `[mechanisms]` | All mechanism extras | All blockchain mechanisms |
+| `[clients]` | `httpx`, `requests` | All HTTP clients |
+| `[servers]` | `fastapi`, `flask` | All server frameworks |
+| `[extensions]` | Extensions dependencies | Optional extensions |
+| `[all]` | Everything | Full installation |
+
+Installation examples:
+
+```bash
+pip install "x402-avm[avm]"
+pip install "x402-avm[fastapi,avm]"
+pip install "x402-avm[flask,avm]"
+pip install "x402-avm[httpx,avm]"
+pip install "x402-avm[requests,avm]"
+pip install "x402-avm[all]"
+```
+
+## Async vs Sync Component Table
+
+| Component | Async (FastAPI/httpx) | Sync (Flask/requests) |
+|-----------|----------------------|----------------------|
+| x402 Client | `x402Client` | `x402ClientSync` |
+| Resource Server | `x402ResourceServer` | `x402ResourceServerSync` |
+| Facilitator Client | `HTTPFacilitatorClient` | `HTTPFacilitatorClientSync` |
+| HTTP Resource Server | `x402HTTPResourceServer` | `x402HTTPResourceServerSync` |
+| HTTP Client wrapper | `x402HTTPClient` | `x402HTTPClientSync` |
+| Middleware (FastAPI) | `PaymentMiddlewareASGI` | N/A |
+| Middleware (Flask) | N/A | `PaymentMiddleware` |
+| HTTP Client (httpx) | `x402HttpxClient` | N/A |
+| HTTP Client (requests) | N/A | `x402_requests` |
+| Payment info storage | `request.state.payment_payload` | `flask.g.payment_payload` |
+
+## ClientAvmSigner Protocol
+
+Defined in `x402.mechanisms.avm.signer`. Structural typing -- no inheritance required.
+
+```python
+class ClientAvmSigner(Protocol):
+    @property
+    def address(self) -> str:
+        """58-character Algorand address."""
+        ...
+
+    def sign_transactions(
+        self,
+        unsigned_txns: list[bytes],
+        indexes_to_sign: list[int],
+    ) -> list[bytes | None]:
+        """Sign specified transactions in a group.
+
+        Args:
+            unsigned_txns: Raw msgpack-encoded unsigned transactions.
+            indexes_to_sign: Indexes this signer should sign.
+
+        Returns:
+            Parallel list: signed bytes at signed indexes, None elsewhere.
+        """
+        ...
+```
+
+### Implementation Notes
+
+- `unsigned_txns` contains raw msgpack bytes, not base64 strings
+- Convert at boundary: `base64.b64encode(txn_bytes).decode()` before `msgpack_decode`
+- `Transaction.sign(key)` expects base64-encoded private key string
+- Convert back: `base64.b64decode(msgpack_encode(signed))` to return raw bytes
+
+## FacilitatorAvmSigner Protocol
+
+Defined in `x402.mechanisms.avm.signer`. Required for facilitator services.
+
+```python
+class FacilitatorAvmSigner(Protocol):
+    def get_addresses(self) -> list[str]: ...
+    def sign_transaction(self, txn_bytes: bytes, fee_payer: str, network: str) -> bytes: ...
+    def sign_group(self, group_bytes: list[bytes], fee_payer: str, indexes_to_sign: list[int], network: str) -> list[bytes]: ...
+    def simulate_group(self, group_bytes: list[bytes], network: str) -> None: ...
+    def send_group(self, group_bytes: list[bytes], network: str) -> str: ...
+    def confirm_transaction(self, txid: str, network: str, rounds: int = 4) -> None: ...
+```
+
+### Implementation Patterns
+
+| Method | Key Pattern |
+|--------|-------------|
+| `simulate_group` | Wrap unsigned `Transaction` with `SignedTransaction(txn, None)`, use `allow_empty_signatures=True` |
+| `send_group` | Use `send_raw_transaction(base64.b64encode(b"".join(group_bytes)))` |
+| `confirm_transaction` | Use `transaction.wait_for_confirmation(client, txid, rounds)` |
+
+## Registration Functions
+
+### `register_exact_avm_client(client, signer, networks=None, algod_url=None)`
+
+Registers AVM payment scheme on an x402 client.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `client` | `x402Client \| x402ClientSync` | required | The x402 client instance |
+| `signer` | `ClientAvmSigner` | required | Signer implementation |
+| `networks` | `str \| list[str] \| None` | `None` | Specific networks; default registers `"algorand:*"` wildcard + V1 names |
+| `algod_url` | `str \| None` | `None` | Custom algod endpoint |
+
+### `register_exact_avm_server(server)`
+
+Registers AVM scheme on a resource server.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `server` | `x402ResourceServer \| x402ResourceServerSync` | The resource server |
+
+### `register_exact_avm_facilitator(facilitator, signer, networks)`
+
+Registers AVM scheme on a facilitator.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `facilitator` | `x402Facilitator` | The facilitator instance |
+| `signer` | `FacilitatorAvmSigner` | Facilitator signer implementation |
+| `networks` | `list[str]` | CAIP-2 network identifiers to support |
+
+## Constants
+
+Defined in `x402.mechanisms.avm.constants`:
+
+### Network Identifiers
+
+| Constant | Value |
+|----------|-------|
+| `ALGORAND_MAINNET_CAIP2` | `"algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8="` |
+| `ALGORAND_TESTNET_CAIP2` | `"algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI="` |
+| `SUPPORTED_NETWORKS` | `[MAINNET_CAIP2, TESTNET_CAIP2]` |
+| `MAINNET_GENESIS_HASH` | `"wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8="` |
+| `TESTNET_GENESIS_HASH` | `"SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI="` |
+| `V1_NETWORKS` | `["algorand-mainnet", "algorand-testnet"]` |
+
+### USDC Configuration
+
+| Constant | Value |
+|----------|-------|
+| `USDC_MAINNET_ASA_ID` | `31566704` |
+| `USDC_TESTNET_ASA_ID` | `10458941` |
+| `DEFAULT_DECIMALS` | `6` |
+
+### Algod Endpoints
+
+| Constant | Default Value |
+|----------|---------------|
+| `MAINNET_ALGOD_URL` | env `ALGOD_MAINNET_URL` or `"https://mainnet-api.algonode.cloud"` |
+| `TESTNET_ALGOD_URL` | env `ALGOD_TESTNET_URL` or `"https://testnet-api.algonode.cloud"` |
+| `FALLBACK_ALGOD_MAINNET` | `"https://mainnet-api.algonode.cloud"` |
+| `FALLBACK_ALGOD_TESTNET` | `"https://testnet-api.algonode.cloud"` |
+
+### Transaction Limits
+
+| Constant | Value |
+|----------|-------|
+| `MAX_GROUP_SIZE` | `16` |
+| `MIN_TXN_FEE` | `1000` (microAlgos) |
+
+## Utility Functions
+
+Defined in `x402.mechanisms.avm.utils`:
+
+| Function | Signature | Returns |
+|----------|-----------|---------|
+| `is_valid_address(addr)` | `str -> bool` | Whether address is valid 58-char Algorand address |
+| `to_atomic_amount(amount)` | `float -> int` | Decimal to atomic units (e.g., 1.50 -> 1500000) |
+| `from_atomic_amount(amount)` | `int -> float` | Atomic units to decimal (e.g., 1500000 -> 1.5) |
+| `decode_transaction_bytes(raw)` | `bytes -> DecodedTransactionInfo` | Decoded transaction details |
+| `decode_base64_transaction(b64)` | `str -> DecodedTransactionInfo` | Decode from base64 string |
+| `decode_payment_group(group, index)` | `list[str], int -> PaymentGroupInfo` | Full group analysis |
+| `encode_transaction_group(txns)` | `list[bytes] -> list[str]` | Encode raw bytes to base64 strings |
+| `normalize_network(network)` | `str -> str` | Normalize V1 name to CAIP-2 |
+| `is_valid_network(network)` | `str -> bool` | Check if network is recognized |
+| `get_network_config(network)` | `str -> dict` | Full config for network |
+| `get_usdc_asa_id(network)` | `str -> int` | USDC ASA ID for network |
+| `get_genesis_hash(network)` | `str -> str` | Genesis hash for network |
+| `network_from_genesis_hash(hash)` | `str -> str` | CAIP-2 from genesis hash |
+| `validate_no_security_risks(info)` | `DecodedTransactionInfo -> str \| None` | Error code or None |
+| `validate_fee_payer_transaction(info, addr)` | `DecodedTransactionInfo, str -> str \| None` | Error code or None |
+| `is_blocked_transaction_type(type)` | `str -> bool` | Whether type is blocked (e.g., keyreg) |
+
+## algosdk Encoding Notes (v2.11.1)
+
+The Python `algosdk` has different encoding conventions than TypeScript algosdk:
+
+| Operation | Python algosdk | TypeScript algosdk |
+|-----------|---------------|-------------------|
+| `msgpack_decode(s)` | Expects **base64 string** | N/A (uses `decodeUnsignedTransaction(Uint8Array)`) |
+| `msgpack_encode(obj)` | Returns **base64 string** | N/A (uses `txn.toByte()` returning `Uint8Array`) |
+| `Transaction.sign(key)` | Expects **base64 string** key | `signTransaction(txn, Uint8Array)` |
+| SDK protocol | Passes **raw msgpack bytes** | Passes **raw `Uint8Array`** |
+
+Boundary conversions:
+
+```python
+# Raw bytes -> algosdk object
+txn_obj = encoding.msgpack_decode(base64.b64encode(raw_bytes).decode("utf-8"))
+
+# algosdk object -> raw bytes
+raw_bytes = base64.b64decode(encoding.msgpack_encode(txn_obj))
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `AVM_PRIVATE_KEY` | Base64-encoded 64-byte key (32-byte seed + 32-byte pubkey) | Required |
+| `ALGOD_MAINNET_URL` | Custom algod mainnet endpoint | `https://mainnet-api.algonode.cloud` |
+| `ALGOD_TESTNET_URL` | Custom algod testnet endpoint | `https://testnet-api.algonode.cloud` |
+| `INDEXER_MAINNET_URL` | Custom indexer mainnet endpoint | `https://mainnet-idx.algonode.cloud` |
+| `INDEXER_TESTNET_URL` | Custom indexer testnet endpoint | `https://testnet-idx.algonode.cloud` |
+| `ALGOD_SERVER` | Algod URL for facilitator examples | N/A |
+| `ALGOD_TOKEN` | Algod token for facilitator examples | N/A |
+
+### Private Key Format
+
+The `AVM_PRIVATE_KEY` is a Base64-encoded 64-byte key:
+- First 32 bytes: Ed25519 seed (private key)
+- Last 32 bytes: Ed25519 public key
+- Address derivation: `encoding.encode_address(secret_key[32:])`
+
+## Payment Flow
+
+```
+Client -> Resource Server -> Facilitator -> Algorand Network
+  |          |                  |                |
+  | 1. GET   |                  |                |
+  |--------->|                  |                |
+  | 2. 402   |                  |                |
+  |<---------|                  |                |
+  | 3. Build |                  |                |
+  |   payload|                  |                |
+  | 4. GET + |                  |                |
+  | PAYMENT- |                  |                |
+  | SIGNATURE|                  |                |
+  |--------->| 5. verify()      |                |
+  |          |----------------->| 6. simulate    |
+  |          |                  |--------------->|
+  |          |                  |<---------------|
+  |          |<-----------------|                |
+  |          | 7. settle()      |                |
+  |          |----------------->| 8. sign + send |
+  |          |                  |--------------->|
+  |          |                  |<---------------|
+  |          |<-----------------| 9. txId        |
+  | 10. 200  |                  |                |
+  |<---------|                  |                |
+```
+
+## Testing Notes
+
+- Use Algorand TestNet for development with free test ALGO from the [Algorand Faucet](https://bank.testnet.algorand.network/)
+- USDC on TestNet uses ASA ID `10458941` -- ensure receiver has opted in
+- Simulation (`simulate_group`) validates transactions without submitting
+- Algorand has instant finality -- once confirmed, transactions are permanent
+- AlgoNode public endpoints require no authentication token
+
+## External Resources
+
+- [x402-avm on PyPI](https://pypi.org/project/x402-avm/)
+- [x402-avm GitHub Repository](https://github.com/GoPlausible/x402-avm/tree/branch-v2-algorand-publish/)
+- [x402-avm Examples](https://github.com/GoPlausible/x402-avm/tree/branch-v2-algorand-publish/examples/)
+- [x402 Algorand Documentation](https://github.com/GoPlausible/.github/blob/main/profile/algorand-x402-documentation/)
+- [Algorand Developer Portal](https://dev.algorand.co/)
+- [py-algorand-sdk Documentation](https://py-algorand-sdk.readthedocs.io/)
+- [Coinbase x402 Specification](https://github.com/coinbase/x402)

package/skills/algorand-x402-python/references/explain-algorand-x402-python.md

@@ -0,0 +1,167 @@
+# x402-avm Python Package for Algorand
+
+The `x402-avm` Python package provides Algorand (AVM) payment protocol support through a modular extras system, Protocol-based signer interfaces, and async/sync variants for every component.
+
+## Prerequisites
+
+Before using this skill, ensure:
+
+1. **Python 3.10+** is installed
+2. **pip** is available for package installation
+3. **Understanding of x402 protocol** -- client sends request, gets 402, creates payment, retries with payment header
+
+## Core Concept: Extras-Based Installation
+
+The `x402-avm` package uses pip extras to install only what you need. The package name on PyPI is `x402-avm` but all imports use `from x402...` (not `from x402_avm...`).
+
+```bash
+# Minimal AVM support
+pip install "x402-avm[avm]"
+
+# Server frameworks
+pip install "x402-avm[fastapi,avm]"
+pip install "x402-avm[flask,avm]"
+
+# HTTP clients
+pip install "x402-avm[httpx,avm]"
+pip install "x402-avm[requests,avm]"
+
+# Everything
+pip install "x402-avm[all]"
+```
+
+## Core Workflow: Signer Protocol Pattern
+
+The key insight is that x402 defines **Protocol classes** (structural typing) for signers. Your implementation does not need to inherit -- it just needs matching methods.
+
+```
+Private Key (env var)
+        |
+        v
+Signer Implementation (satisfies Protocol)
+        |
+        v
+register_exact_avm_client(x402_client, signer)
+        |
+        v
+HTTP Client (httpx or requests) handles 402 automatically
+```
+
+## How to Proceed
+
+### Step 1: Choose Your Extras
+
+| Use Case | Install Command |
+|----------|----------------|
+| Client with httpx (async) | `pip install "x402-avm[httpx,avm]"` |
+| Client with requests (sync) | `pip install "x402-avm[requests,avm]"` |
+| Server with FastAPI (async) | `pip install "x402-avm[fastapi,avm]"` |
+| Server with Flask (sync) | `pip install "x402-avm[flask,avm]"` |
+| Facilitator service | `pip install "x402-avm[fastapi,avm]"` or `"x402-avm[flask,avm]"` |
+| Full installation | `pip install "x402-avm[all]"` |
+
+### Step 2: Understand Async vs Sync Variants
+
+Every core class has both async and sync variants. Using the wrong variant causes runtime errors.
+
+| Component | Async (FastAPI/httpx) | Sync (Flask/requests) |
+|-----------|----------------------|----------------------|
+| x402 Client | `x402Client` | `x402ClientSync` |
+| Resource Server | `x402ResourceServer` | `x402ResourceServerSync` |
+| Facilitator Client | `HTTPFacilitatorClient` | `HTTPFacilitatorClientSync` |
+| HTTP Resource Server | `x402HTTPResourceServer` | `x402HTTPResourceServerSync` |
+
+### Step 3: Implement a Signer
+
+For clients, implement `ClientAvmSigner`:
+
+```python
+from x402.mechanisms.avm.signer import ClientAvmSigner
+
+# Protocol -- just match this shape:
+class ClientAvmSigner(Protocol):
+    @property
+    def address(self) -> str: ...
+    def sign_transactions(self, unsigned_txns: list[bytes], indexes_to_sign: list[int]) -> list[bytes | None]: ...
+```
+
+For facilitators, implement `FacilitatorAvmSigner`:
+
+```python
+from x402.mechanisms.avm.signer import FacilitatorAvmSigner
+
+# Protocol -- match this shape:
+class FacilitatorAvmSigner(Protocol):
+    def get_addresses(self) -> list[str]: ...
+    def sign_transaction(self, txn_bytes: bytes, fee_payer: str, network: str) -> bytes: ...
+    def sign_group(self, group_bytes: list[bytes], fee_payer: str, indexes_to_sign: list[int], network: str) -> list[bytes]: ...
+    def simulate_group(self, group_bytes: list[bytes], network: str) -> None: ...
+    def send_group(self, group_bytes: list[bytes], network: str) -> str: ...
+    def confirm_transaction(self, txid: str, network: str, rounds: int = 4) -> None: ...
+```
+
+### Step 4: Handle algosdk Encoding Boundaries
+
+This is the most common source of bugs. The x402 SDK passes **raw msgpack bytes** between methods, but Python algosdk (v2.11.1) works with **base64 strings**:
+
+| Operation | Python algosdk Expects/Returns |
+|-----------|-------------------------------|
+| `msgpack_decode(s)` | Expects **base64 string** |
+| `msgpack_encode(obj)` | Returns **base64 string** |
+| `Transaction.sign(key)` | Expects **base64 string** key |
+
+Boundary conversion:
+
+```python
+import base64
+from algosdk import encoding
+
+# Raw bytes -> algosdk object (DECODE)
+b64_string = base64.b64encode(raw_bytes).decode("utf-8")
+txn_obj = encoding.msgpack_decode(b64_string)
+
+# algosdk object -> raw bytes (ENCODE)
+b64_string = encoding.msgpack_encode(txn_obj)
+raw_bytes = base64.b64decode(b64_string)
+```
+
+### Step 5: Register and Use
+
+```python
+from x402 import x402Client
+from x402.mechanisms.avm.exact import register_exact_avm_client
+
+signer = MyClientSigner(os.environ["AVM_PRIVATE_KEY"])
+client = x402Client()
+register_exact_avm_client(client, signer)
+# Now use with httpx or requests client wrappers
+```
+
+## Important Rules / Guidelines
+
+1. **Always use base64 boundaries** -- `msgpack_decode` expects base64 string, not raw bytes
+2. **Match async/sync variants** -- FastAPI uses `x402Client`, Flask uses `x402ClientSync`
+3. **Private key format** -- `AVM_PRIVATE_KEY` is Base64-encoded 64 bytes (32-byte seed + 32-byte pubkey)
+4. **Address derivation** -- `encode_address(secret_key[32:])` extracts address from public key portion
+5. **Import as x402** -- install as `x402-avm` but import as `from x402...`
+6. **Protocol typing** -- no inheritance needed, just match the method signatures
+
+## Common Errors / Troubleshooting
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `TypeError: a bytes-like object is required` | Passed raw bytes to `msgpack_decode` | Convert to base64 string first: `base64.b64encode(raw).decode()` |
+| `TypeError: expected str, got bytes` | `msgpack_encode` returns base64 string, not bytes | Use `base64.b64decode(result)` to get raw bytes |
+| `Invalid key length: expected 64` | Wrong key format | Ensure `AVM_PRIVATE_KEY` is Base64-encoded 64-byte key |
+| `TypeError: x402HTTPAdapter requires sync client` | Used `x402Client` with requests | Use `x402ClientSync` for requests (sync) |
+| `ImportError: AVM mechanism requires...` | Missing `py-algorand-sdk` | `pip install "x402-avm[avm]"` |
+| `ModuleNotFoundError: x402_avm` | Wrong import name | Import as `from x402...` not `from x402_avm...` |
+| `Simulation failed: ...` | Transaction group invalid | Check group ID assignment, fee calculations, asset opt-in |
+
+## References / Further Reading
+
+- [explain-algorand-x402-python-reference.md](./explain-algorand-x402-python-reference.md) - Detailed API reference for all Python components
+- [explain-algorand-x402-python-examples.md](./explain-algorand-x402-python-examples.md) - Complete code examples
+- [x402-avm on PyPI](https://pypi.org/project/x402-avm/)
+- [x402-avm Examples Repository](https://github.com/GoPlausible/x402-avm/tree/branch-v2-algorand-publish/examples/)
+- [x402 Algorand Documentation](https://github.com/GoPlausible/.github/blob/main/profile/algorand-x402-documentation/)