envarpay 0.1.0a6__py3-none-any.whl

envarpay/__init__.py

@@ -0,0 +1,20 @@
+"""Standard-protocol payment adapters and read-only configuration/receipt utilities."""
+
+__version__ = "0.1.0a6"
+
+from .config import Config, load_config
+
+__all__ = ["Config", "PaidServer", "WalletService", "load_config", "__version__"]
+
+
+def __getattr__(name):
+    # Reading configuration or receipts does not load signer/runtime dependencies.
+    if name == "PaidServer":
+        from .seller import PaidServer
+
+        return PaidServer
+    if name == "WalletService":
+        from .wallet import WalletService
+
+        return WalletService
+    raise AttributeError(name)

envarpay/__main__.py

@@ -0,0 +1,3 @@
+from envarpay.cli import main
+
+main()

envarpay/backend.py

@@ -0,0 +1,55 @@
+"""Thin adapters to existing Agent services. No Agent is instantiated here."""
+
+from __future__ import annotations
+
+from mcp.types import CallToolResult, Tool
+
+from .config import Backend
+from .storage import PaymentError
+from .transport import connect
+
+
+class AgentBackend:
+    def __init__(self, config: Backend, timeout: int):
+        self.config, self.timeout = config, timeout
+
+    async def list_tools(self) -> list[Tool]:
+        if self.config.kind == "http":
+            from .runtime_http import RuntimeHTTP
+
+            RuntimeHTTP(self.config, self.timeout).credential()
+            return [
+                Tool(
+                    name="ask_agent",
+                    description="Ask the connected agent to perform a single task",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "question": {"type": "string", "minLength": 1, "maxLength": 32000}
+                        },
+                        "required": ["question"],
+                        "additionalProperties": False,
+                    },
+                )
+            ]
+        async with connect(self.config.upstream, self.timeout) as session:
+            tools, cursor = [], None
+            for _ in range(4):
+                page = await session.list_tools(cursor=cursor)
+                tools.extend(page.tools)
+                if len(tools) > 64:
+                    raise PaymentError("Expose at most 64 selected capabilities")
+                cursor = page.nextCursor
+                if not cursor:
+                    return tools
+            raise PaymentError("Capability discovery exceeded the page limit")
+
+    async def call(self, name: str, arguments: dict) -> CallToolResult:
+        if self.config.kind == "mcp":
+            async with connect(self.config.upstream, self.timeout) as session:
+                return await session.call_tool(name, arguments)
+        from .runtime_http import RuntimeHTTP
+
+        if name != "ask_agent":
+            raise PaymentError("Unknown Agent capability")
+        return await RuntimeHTTP(self.config, self.timeout).call(arguments["question"])

envarpay/chain.py

@@ -0,0 +1,128 @@
+"""Independent USDC receipt checks, including the authorization nonce."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Any
+
+import httpx
+from eth_utils import keccak
+
+from .config import Config, address
+from .storage import PaymentError
+
+
+class Chain:
+    def __init__(self, config: Config):
+        self.config = config
+
+    async def rpc(self, method: str, params: list) -> Any:
+        async with httpx.AsyncClient(timeout=30) as client:
+            response = await client.post(
+                self.config.rpc_url,
+                json={
+                    "jsonrpc": "2.0",
+                    "id": 1,
+                    "method": method,
+                    "params": params,
+                },
+            )
+            response.raise_for_status()
+            data = response.json()
+        if "error" in data or "result" not in data:
+            raise PaymentError("RPC failed; preserve the original payment and inspect status")
+        return data["result"]
+
+    async def check_network(self) -> None:
+        if int(await self.rpc("eth_chainId", []), 16) != self.config.chain_id:
+            raise PaymentError("RPC chain does not match the configured network")
+
+    async def prove(self, tx: str, authorization: dict) -> dict:
+        await self.check_network()
+        if len(tx) != 66 or not tx.startswith("0x"):
+            raise PaymentError("Invalid settlement transaction hash")
+        end = time.monotonic() + self.config.timeout_seconds
+        while True:
+            receipt = await self.rpc("eth_getTransactionReceipt", [tx])
+            if receipt:
+                latest = int(await self.rpc("eth_blockNumber", []), 16)
+                if latest - int(receipt["blockNumber"], 16) + 1 >= self.config.confirmations:
+                    break
+            if time.monotonic() >= end:
+                raise PaymentError("Receipt remains unconfirmed; do not sign again")
+            await asyncio.sleep(1)
+        block = await self.rpc("eth_getBlockByNumber", [receipt["blockNumber"], False])
+        log_index = self.validate_receipt(receipt, tx, authorization)
+        if not block or block["hash"].lower() != receipt["blockHash"].lower():
+            raise PaymentError("Receipt is not on the current canonical chain")
+        return {
+            "network": self.config.network,
+            "transaction": tx,
+            "asset": self.config.asset,
+            "payer": address(authorization["from"]),
+            "recipient": address(authorization["to"]),
+            "amount_atomic": str(authorization["value"]),
+            "nonce": authorization["nonce"],
+            "block_number": int(receipt["blockNumber"], 16),
+            "block_hash": receipt["blockHash"],
+            "log_index": log_index,
+            "confirmations": self.config.confirmations,
+            "verified_at": time.time(),
+        }
+
+    async def find_authorization(self, authorization: dict, from_block: int) -> str | None:
+        await self.check_network()
+        latest = int(await self.rpc("eth_blockNumber", []), 16)
+        if from_block < 0 or latest - from_block > 50000:
+            raise PaymentError("Original payment needs a bounded chain audit")
+        used = "0x" + keccak(text="AuthorizationUsed(address,bytes32)").hex()
+        payer = "0x" + address(authorization["from"])[2:].lower().zfill(64)
+        logs = await self.rpc(
+            "eth_getLogs",
+            [
+                {
+                    "address": self.config.asset,
+                    "fromBlock": hex(from_block),
+                    "toBlock": hex(latest),
+                    "topics": [used, payer, authorization["nonce"]],
+                }
+            ],
+        )
+        transactions = {log["transactionHash"] for log in logs if not log.get("removed")}
+        if len(transactions) > 1:
+            raise PaymentError("Ambiguous authorization history")
+        return next(iter(transactions), None)
+
+    def validate_receipt(self, receipt: dict, tx: str, authorization: dict) -> int:
+        return verify_usdc_receipt(receipt, tx, self.config.asset, authorization)
+
+
+def verify_usdc_receipt(receipt: dict, tx: str, asset: str, authorization: dict) -> int:
+    """Verify transfer identity without constructing a wallet or reading a signing key."""
+    if int(receipt["status"], 16) != 1 or receipt["transactionHash"].lower() != tx.lower():
+        raise PaymentError("Transaction did not succeed")
+    payer = "0x" + address(authorization["from"])[2:].lower().zfill(64)
+    recipient = "0x" + address(authorization["to"])[2:].lower().zfill(64)
+    transfer = "0x" + keccak(text="Transfer(address,address,uint256)").hex()
+    used = "0x" + keccak(text="AuthorizationUsed(address,bytes32)").hex()
+    logs = [
+        log
+        for log in receipt["logs"]
+        if log["address"].lower() == asset.lower() and not log.get("removed")
+    ]
+    transfers = [
+        log
+        for log in logs
+        if [t.lower() for t in log["topics"]] == [transfer, payer, recipient]
+        and len(log["data"]) == 66
+        and int(log["data"], 16) == int(authorization["value"])
+    ]
+    nonces = [
+        log
+        for log in logs
+        if [t.lower() for t in log["topics"]] == [used, payer, authorization["nonce"].lower()]
+    ]
+    if len(transfers) != 1 or len(nonces) != 1:
+        raise PaymentError("Exact USDC Transfer and original AuthorizationUsed nonce required")
+    return int(transfers[0]["logIndex"], 16)

envarpay/cli.py

@@ -0,0 +1,315 @@
+"""Command-line setup, serving and read-only diagnostics."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import sys
+from importlib.metadata import version
+from pathlib import Path
+
+from eth_account import Account
+from loguru import logger
+from pydantic import ValidationError
+
+from . import __version__
+from .chain import Chain
+from .config import load_config
+from .setup import AGENTS, describe_config, initialize, write_new
+from .storage import PaymentError, Store
+
+
+def parser() -> argparse.ArgumentParser:
+    root = argparse.ArgumentParser(prog="envarpay", description="MCP + x402 agent payments")
+    root.add_argument("--version", action="version", version=__version__)
+    sub = root.add_subparsers(dest="command", required=True)
+    from .tasks.cli import add_parser
+
+    add_parser(sub)
+    init = sub.add_parser(
+        "init", help="Choose an agent and role; generate configs, wallet entry and setup guide"
+    )
+    init.add_argument(
+        "--directory", type=Path, default=Path("agent-pay"), help="New empty setup directory"
+    )
+    init.add_argument(
+        "--agent", choices=AGENTS, default="mcp", help="Your existing agent/framework"
+    )
+    init.add_argument(
+        "--role", choices=["buyer", "seller", "both"], help="Paid setup role (default: both)"
+    )
+    init.add_argument(
+        "--mode",
+        choices=["seller", "private"],
+        default="seller",
+        help="Private mode connects an authenticated service without payments",
+    )
+    init.add_argument(
+        "--pay-to",
+        help="Full receiving address: yours for seller/both, the seller's for buyer",
+    )
+    init.add_argument("--peer-pay-to", help="Other seller's full address when using --role both")
+    init.add_argument(
+        "--peer-url", default="http://127.0.0.1:4020/mcp", help="Paid seller MCP endpoint"
+    )
+    init.add_argument(
+        "--upstream", default="http://127.0.0.1:8000/mcp", help="Private MCP capability to sell"
+    )
+    init.add_argument("--tool", default="ask_agent", help="MCP tool to sell/allow")
+    amounts = init.add_argument_group("amounts in USDC (up to six decimals)")
+    amounts.add_argument(
+        "--price", default="0.01", help="Seller price per tool call (default: 0.01)"
+    )
+    amounts.add_argument(
+        "--max-per-call", default="0.01", help="Buyer per-call limit (default: 0.01)"
+    )
+    amounts.add_argument(
+        "--budget", default="0.01", help="Buyer cumulative limit, not daily (default: 0.01)"
+    )
+    init.add_argument(
+        "--allow-http",
+        action="store_true",
+        help="Allow remote plain HTTP for private container networks",
+    )
+    init.add_argument("--json", action="store_true", help="Print the setup summary as JSON")
+    init.add_argument(
+        "--backend",
+        choices=["mcp", "openclaw", "hermes-http"],
+        default="mcp",
+        help="Seller adapter; defaults to private MCP. HTTP presets are experimental.",
+    )
+    keygen = sub.add_parser(
+        "keygen", help="Create a new dedicated EVM key, displaying only its address"
+    )
+    keygen.add_argument("--output", type=Path, required=True)
+    for command in [
+        "serve",
+        "wallet",
+        "wallet-serve",
+        "sync",
+        "recover",
+        "call",
+        "probe",
+        "tools",
+        "status",
+        "reconcile",
+        "host-config",
+        "doctor",
+    ]:
+        item = sub.add_parser(command)
+        item.add_argument("--config", type=Path, required=True)
+        if command in ("call", "probe", "tools"):
+            item.add_argument("--peer", required=True)
+        if command in ("call", "probe"):
+            item.add_argument("--tool", required=True)
+            item.add_argument("--arguments", default="{}", help="JSON object")
+        if command == "call":
+            item.add_argument(
+                "--request-id", required=True, help="Stable ID; reuse for the same request"
+            )
+        if command == "recover":
+            item.add_argument("--request-id", required=True)
+        if command == "sync":
+            item.add_argument("--watch", action="store_true")
+        if command in ("status", "reconcile"):
+            item.add_argument("--operation-id", required=command == "reconcile")
+        if command == "host-config":
+            item.add_argument(
+                "--host", choices=["hermes", "openclaw", "opencode", "goose"], required=True
+            )
+        if command == "doctor":
+            item.add_argument("--online", action="store_true", help="Also read RPC chain ID")
+    return root
+
+
+async def read_or_call(args: argparse.Namespace) -> dict | list:
+    from x402 import x402Client
+    from x402.mcp.client import x402MCPSession
+
+    from .transport import connect
+    from .wallet import WalletService
+
+    config = load_config(args.config)
+    if args.command == "sync":
+        from .directory import Envar
+
+        if not config.connection:
+            raise PaymentError("Configure [connection] before synchronizing reports")
+        envar = Envar(config.connection, Store(config.state_dir))
+        while True:
+            result = await envar.flush()
+            if not args.watch:
+                return result
+            await asyncio.sleep(5)
+    if args.command == "recover":
+        return await WalletService(config).recover(args.request_id)
+    if args.command == "doctor":
+        endpoint = config.seller or config.service
+        if endpoint and endpoint.backend.kind == "http":
+            from .runtime_http import RuntimeHTTP
+
+            RuntimeHTTP(endpoint.backend, config.timeout_seconds).credential()
+        if config.service:
+            from .service import AgentService
+
+            AgentService(config)
+        rpc_checked = bool(args.online and (config.seller or config.wallet))
+        if rpc_checked:
+            await Chain(config).check_network()
+        if args.online and endpoint:
+            from .backend import AgentBackend
+
+            await AgentBackend(endpoint.backend, config.timeout_seconds).list_tools()
+        return {
+            "valid": True,
+            **describe_config(config),
+            "rpc_checked": rpc_checked,
+            "versions": {name: version(name) for name in ("envarpay", "x402", "mcp")},
+        }
+    if args.command in ("status", "reconcile"):
+        store = Store(config.state_dir)
+        if args.command == "status":
+            return store.public_status(args.operation_id)
+        row = store.get(args.operation_id)
+        if not row or not row["data"].get("transaction") or not row["data"].get("payload"):
+            raise PaymentError(
+                "No recorded transaction to reconcile; this command never resubmits payment"
+            )
+        return await Chain(config).prove(
+            row["data"]["transaction"], row["data"]["payload"]["payload"]["authorization"]
+        )
+    service = WalletService(config)
+    if args.command == "tools":
+        return await service.list_tools(args.peer)
+    arguments = json.loads(args.arguments)
+    if not isinstance(arguments, dict):
+        raise PaymentError("--arguments must be a JSON object")
+    if args.command == "call":
+        return await service.call(args.peer, args.tool, arguments, args.request_id)
+    peer = service.peer(args.peer, args.tool)
+    async with connect(peer, config.timeout_seconds) as session:
+        result = await x402MCPSession(session, x402Client(), auto_payment=False).call_tool(
+            args.tool, arguments
+        )
+    return {
+        "payment_made": False,
+        "result": result.raw_result.model_dump(mode="json", by_alias=True),
+    }
+
+
+def main() -> None:
+    logger.remove()
+    logger.add(sys.stderr, level="WARNING", format="{level}: {message}")
+    args = parser().parse_args()
+    try:
+        if args.command == "task":
+            from .tasks.cli import run
+
+            run(args)
+            return
+        if args.command == "init":
+            result = initialize(
+                args.directory,
+                args.pay_to,
+                args.backend,
+                mode=args.mode,
+                agent=args.agent,
+                role=args.role,
+                upstream=args.upstream,
+                peer_url=args.peer_url,
+                peer_pay_to=args.peer_pay_to,
+                tool=args.tool,
+                price=args.price,
+                max_per_call=args.max_per_call,
+                budget=args.budget,
+                allow_http=args.allow_http,
+            )
+            if not args.json:
+                print(f"EnvarPay · {result['agent']} · {result['role']}")
+                print(f"Network: {result['network']} | Buyer payments: OFF")
+                if result["buyer"]:
+                    buyer = result["buyer"]
+                    print(f"\nBuy from: {buyer['peer_url']}")
+                    print(f"  Recipient: {buyer['recipient']}")
+                    print(f"  Tool: {buyer['tool']}")
+                    print(
+                        f"  Limit: {buyer['max_per_call_usdc']} USDC/call; "
+                        f"{buyer['budget_usdc']} USDC cumulative"
+                    )
+                if result["seller"]:
+                    seller = result["seller"]
+                    print(f"\nSell: {seller['tool']} for {seller['price_usdc']} USDC/call")
+                    print(f"  Receive at: {seller['recipient']}")
+                    print(f"  Private upstream: {seller['upstream']} ({seller['backend']})")
+                print("\nCreated in " + result["directory"] + ": " + ", ".join(result["files"]))
+                print("\nNext:")
+                for index, step in enumerate(result["next_steps"], 1):
+                    print(f"  {index}. {step}")
+                print("\nGuide: " + result["guide"])
+                return
+        elif args.command == "keygen":
+            account = Account.create()
+            write_new(args.output.expanduser(), account.key.hex() + "\n")
+            result = {
+                "address": account.address,
+                "key_file": str(args.output),
+                "private_key_printed": False,
+            }
+        elif args.command == "host-config":
+            from .host_config import host_config
+
+            result = host_config(args.host, args.config)
+        elif args.command == "wallet":
+            from .wallet import WalletService, wallet_mcp
+
+            wallet_mcp(WalletService(load_config(args.config))).run(transport="stdio")
+            return
+        elif args.command == "wallet-serve":
+            import uvicorn
+
+            from .wallet import WalletService, wallet_app
+
+            config = load_config(args.config)
+            app = wallet_app(WalletService(config))
+            uvicorn.run(
+                app,
+                host=config.wallet_server.host,
+                port=config.wallet_server.port,
+                log_level="warning",
+            )
+            return
+        elif args.command == "serve":
+            import uvicorn
+
+            from .seller import PaidServer
+            from .service import AgentService
+
+            config = load_config(args.config)
+            service = PaidServer(config) if config.seller else AgentService(config)
+            uvicorn.run(
+                service.app(config_path=args.config) if config.seller else service.app(),
+                host=service.policy.host,
+                port=service.policy.port,
+                log_level="warning",
+            )
+            return
+        else:
+            result = asyncio.run(read_or_call(args))
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+    except (PaymentError, FileExistsError, FileNotFoundError) as error:
+        print(f"envarpay: {error}", file=sys.stderr)
+        raise SystemExit(1) from None
+    except ValidationError as error:
+        print(
+            "envarpay: invalid configuration: "
+            + "; ".join(
+                f"{'.'.join(map(str, e['loc']))}: {e['msg']}"
+                for e in error.errors(include_input=False)
+            ),
+            file=sys.stderr,
+        )
+        raise SystemExit(1) from None
+    except Exception as error:
+        print(f"envarpay: {type(error).__name__}; operation did not complete", file=sys.stderr)
+        raise SystemExit(1) from None