* feat: add TVM exact-payment mechanism to Python SDK - add TVM exact client, server, and facilitator implementations - add TVM signers, codecs, provider, and settlement helpers - add unit and integration coverage for TON testnet/mainnet flows - add Python examples and e2e wiring for TVM * Enable TVM exact flows in Python e2e and tighten facilitator validation Add TVM support to the Python e2e clients and servers, switch TVM usage to direct `ExactTvm*Scheme` registration after removing the old register helpers, and refresh docs/examples for testnet setup. Also reject exact TVM settlements with excessively large attached TON amounts and cover the new validation with tests. * fix: clarify minimum balance of the facilitator * refactor(tvm): release settlement cache entry on confirmed settlement On-chain seqno advances after a successful relay, so any retry of the same settlement BOC will fail at the W5 contract's seqno check regardless of the dedup reservation. Drop the entry as soon as the confirmation worker records success, so the invariant becomes "every is_duplicate=False is paired with a release" and TTL pruning is left as a crash safety-net only. * feat(tvm): add TonAPI provider support * feat(tvm): update e2e tests to make them compatible with new providers * fix(tvm): update timeouts * fix(tvm): increase http client timeout * fix(tvm): align unit tests * revert(e2e): remove .env-local config load Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
506 lines
18 KiB
Python
506 lines
18 KiB
Python
"""x402 Python Facilitator for E2E Testing.
|
|
|
|
FastAPI-based facilitator service that verifies and settles payments
|
|
on-chain for the x402 protocol.
|
|
|
|
Supports:
|
|
- EVM networks (Base Sepolia) via web3.py
|
|
- SVM networks (Solana Devnet) via solders
|
|
- TVM networks (TON testnet/mainnet) via pytoniq + Toncenter/TonAPI
|
|
- Bazaar discovery extension for resource cataloging
|
|
- EIP-2612 gas sponsoring extension (gasless Permit2 approval via permit)
|
|
- ERC-20 approval gas sponsoring extension (gasless Permit2 via signed tx relay)
|
|
- V1 and V2 protocol versions
|
|
|
|
Run with: uv run uvicorn main:app --port 4022
|
|
"""
|
|
|
|
import logging
|
|
import os
|
|
import sys
|
|
from typing import Any
|
|
|
|
logging.basicConfig(level=logging.INFO, format="%(name)s %(levelname)s: %(message)s")
|
|
logging.getLogger("x402.permit2").setLevel(logging.DEBUG)
|
|
logging.getLogger("x402.signers").setLevel(logging.DEBUG)
|
|
|
|
from bazaar import BazaarCatalog
|
|
from dotenv import load_dotenv
|
|
from fastapi import FastAPI, HTTPException
|
|
from pydantic import BaseModel
|
|
from solders.keypair import Keypair
|
|
|
|
from x402 import x402Facilitator
|
|
from x402.extensions.bazaar import extract_discovery_info
|
|
from x402.extensions.eip2612_gas_sponsoring import EIP2612_GAS_SPONSORING
|
|
from x402.extensions.erc20_approval_gas_sponsoring import (
|
|
Erc20ApprovalFacilitatorExtension,
|
|
WriteContractCall,
|
|
)
|
|
from x402.mechanisms.evm import FacilitatorWeb3Signer
|
|
from x402.mechanisms.evm.constants import TX_STATUS_SUCCESS
|
|
from x402.mechanisms.evm.exact import register_exact_evm_facilitator
|
|
from x402.mechanisms.evm.types import TransactionReceipt
|
|
from x402.mechanisms.evm.upto import UptoEvmFacilitatorScheme
|
|
from x402.mechanisms.svm import FacilitatorKeypairSigner
|
|
from x402.mechanisms.svm.exact import register_exact_svm_facilitator
|
|
from x402.mechanisms.tvm import (
|
|
TVM_TESTNET,
|
|
TVM_PROVIDER_TONAPI,
|
|
HighloadV3Config,
|
|
FacilitatorHighloadV3Signer,
|
|
)
|
|
from x402.mechanisms.tvm.exact import ExactTvmFacilitatorScheme
|
|
|
|
# Load environment variables
|
|
load_dotenv()
|
|
|
|
# Configuration
|
|
PORT = int(os.environ.get("PORT", "4022"))
|
|
|
|
# Initialize bazaar catalog
|
|
bazaar_catalog = BazaarCatalog()
|
|
|
|
# Validate that at least one chain is configured
|
|
if not any(
|
|
[
|
|
os.environ.get("EVM_PRIVATE_KEY"),
|
|
os.environ.get("SVM_PRIVATE_KEY"),
|
|
os.environ.get("TVM_PRIVATE_KEY"),
|
|
]
|
|
):
|
|
print(
|
|
"❌ At least one of EVM_PRIVATE_KEY, SVM_PRIVATE_KEY, or TVM_PRIVATE_KEY is required"
|
|
)
|
|
sys.exit(1)
|
|
|
|
# Network configuration
|
|
EVM_NETWORK = os.environ.get("EVM_NETWORK", "eip155:84532")
|
|
SVM_NETWORK = os.environ.get("SVM_NETWORK", "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1")
|
|
TVM_NETWORK = os.environ.get("TVM_NETWORK", TVM_TESTNET)
|
|
|
|
# Initialize the EVM signer from private key when configured
|
|
evm_signer = None
|
|
if os.environ.get("EVM_PRIVATE_KEY"):
|
|
evm_rpc_url = os.environ.get("EVM_RPC_URL") or "https://sepolia.base.org"
|
|
evm_signer = FacilitatorWeb3Signer(
|
|
private_key=os.environ["EVM_PRIVATE_KEY"],
|
|
rpc_url=evm_rpc_url,
|
|
)
|
|
print(f"EVM Facilitator account: {evm_signer.get_addresses()[0]}")
|
|
|
|
# Initialize the SVM signer from private key when configured
|
|
svm_signer = None
|
|
if os.environ.get("SVM_PRIVATE_KEY"):
|
|
svm_keypair = Keypair.from_base58_string(os.environ["SVM_PRIVATE_KEY"])
|
|
svm_signer = FacilitatorKeypairSigner(svm_keypair)
|
|
print(f"SVM Facilitator account: {svm_signer.get_addresses()[0]}")
|
|
|
|
# Initialize the TVM signer from private key when configured
|
|
tvm_signer = None
|
|
if os.environ.get("TVM_PRIVATE_KEY"):
|
|
tvm_config = HighloadV3Config.from_private_key(os.environ["TVM_PRIVATE_KEY"])
|
|
tvm_provider = (os.environ.get("TVM_PROVIDER") or "").strip().lower()
|
|
tvm_config.provider = tvm_provider or tvm_config.provider
|
|
tvm_config.api_key = (
|
|
os.environ.get("TONAPI_API_KEY")
|
|
if tvm_provider == TVM_PROVIDER_TONAPI
|
|
else os.environ.get("TONCENTER_API_KEY")
|
|
)
|
|
tvm_config.provider_base_url = (
|
|
os.environ.get("TONAPI_BASE_URL")
|
|
if tvm_provider == TVM_PROVIDER_TONAPI
|
|
else os.environ.get("TONCENTER_BASE_URL")
|
|
)
|
|
tvm_signer = FacilitatorHighloadV3Signer({TVM_NETWORK: tvm_config})
|
|
print(f"TVM Facilitator account: {tvm_signer.get_addresses()[0]}")
|
|
|
|
|
|
class Erc20ApprovalSigner:
|
|
"""Wraps FacilitatorWeb3Signer with send_transactions for ERC-20 approval sponsoring.
|
|
|
|
Broadcasts pre-signed approval txs and settles via the proxy contract,
|
|
matching the Go/TS facilitator pattern.
|
|
"""
|
|
|
|
def __init__(self, base_signer: FacilitatorWeb3Signer):
|
|
self._signer = base_signer
|
|
|
|
def send_transactions(self, transactions: list) -> list[str]:
|
|
hashes: list[str] = []
|
|
for tx in transactions:
|
|
if isinstance(tx, str):
|
|
raw_bytes = bytes.fromhex(tx[2:] if tx.startswith("0x") else tx)
|
|
w3 = self._signer._w3
|
|
|
|
payer_address = w3.eth.account.recover_transaction(tx)
|
|
# Use the same gas constants as the library's approve tx builder
|
|
gas_cost = (
|
|
70_000 * 1_000_000_000
|
|
) # ERC20_APPROVE_GAS_LIMIT * DEFAULT_MAX_FEE_PER_GAS
|
|
|
|
payer_balance = w3.eth.get_balance(payer_address)
|
|
if payer_balance < gas_cost:
|
|
deficit = gas_cost - payer_balance
|
|
print(
|
|
f"⛽ Funding payer {payer_address} with {deficit} wei for gas"
|
|
)
|
|
fund_tx = {
|
|
"to": payer_address,
|
|
"value": deficit,
|
|
"gas": 21000,
|
|
"gasPrice": w3.eth.gas_price,
|
|
"nonce": w3.eth.get_transaction_count(
|
|
self._signer._account.address
|
|
),
|
|
"chainId": w3.eth.chain_id,
|
|
}
|
|
signed_fund = self._signer._account.sign_transaction(fund_tx)
|
|
fund_hash = w3.eth.send_raw_transaction(
|
|
signed_fund.raw_transaction
|
|
).hex()
|
|
fund_receipt = w3.eth.wait_for_transaction_receipt(fund_hash)
|
|
if fund_receipt["status"] != 1:
|
|
raise RuntimeError(f"gas_funding_failed: {fund_hash}")
|
|
print(f"⛽ Gas funding confirmed: {fund_hash}")
|
|
|
|
tx_hash = w3.eth.send_raw_transaction(raw_bytes).hex()
|
|
elif isinstance(tx, dict) or isinstance(tx, WriteContractCall):
|
|
if isinstance(tx, dict):
|
|
call = WriteContractCall(**tx)
|
|
else:
|
|
call = tx
|
|
tx_hash = self._signer.write_contract(
|
|
call.address, call.abi, call.function, *call.args
|
|
)
|
|
else:
|
|
raise ValueError(f"Unsupported transaction type: {type(tx)}")
|
|
|
|
receipt = self._signer.wait_for_transaction_receipt(tx_hash)
|
|
if receipt.status != TX_STATUS_SUCCESS:
|
|
raise RuntimeError(f"transaction_failed: {tx_hash}")
|
|
hashes.append(tx_hash)
|
|
return hashes
|
|
|
|
def wait_for_transaction_receipt(self, tx_hash: str) -> TransactionReceipt:
|
|
return self._signer.wait_for_transaction_receipt(tx_hash)
|
|
|
|
|
|
erc20_approval_signer = (
|
|
Erc20ApprovalSigner(evm_signer) if evm_signer is not None else None
|
|
)
|
|
|
|
|
|
def _handle_after_verify(ctx: Any) -> None:
|
|
"""Handle after verify hook - extract discovery info and catalog."""
|
|
print("✅ Payment verified")
|
|
|
|
# Extract discovered resource from payment for bazaar catalog
|
|
try:
|
|
discovered = extract_discovery_info(
|
|
ctx.payment_payload,
|
|
ctx.requirements,
|
|
validate=True,
|
|
)
|
|
|
|
if discovered:
|
|
print(f" 📝 Discovered resource: {discovered.resource_url}")
|
|
print(f" 📝 Method: {discovered.method}")
|
|
print(f" 📝 X402Version: {discovered.x402_version}")
|
|
|
|
# Convert discovery_info to dict for serialization
|
|
discovery_info_dict = None
|
|
if discovered.discovery_info:
|
|
if hasattr(discovered.discovery_info, "model_dump"):
|
|
discovery_info_dict = discovered.discovery_info.model_dump(
|
|
by_alias=True, exclude_none=True
|
|
)
|
|
else:
|
|
discovery_info_dict = discovered.discovery_info
|
|
|
|
bazaar_catalog.catalog_resource(
|
|
resource_url=discovered.resource_url,
|
|
method=discovered.method,
|
|
x402_version=discovered.x402_version,
|
|
discovery_info=discovery_info_dict,
|
|
payment_requirements=ctx.requirements.model_dump(by_alias=True)
|
|
if hasattr(ctx.requirements, "model_dump")
|
|
else ctx.requirements,
|
|
route_template=getattr(discovered, "route_template", None),
|
|
)
|
|
print(" ✅ Added to bazaar catalog")
|
|
except Exception as err:
|
|
print(f" ⚠️ Failed to extract discovery info: {err}")
|
|
|
|
|
|
# Initialize the x402 Facilitator with optional EVM/SVM/TVM support
|
|
facilitator = (
|
|
x402Facilitator()
|
|
.on_before_verify(lambda ctx: print("Before verify", ctx))
|
|
.on_after_verify(lambda ctx: _handle_after_verify(ctx))
|
|
.on_verify_failure(lambda ctx: print("Verify failure", ctx))
|
|
.on_before_settle(lambda ctx: print("Before settle", ctx))
|
|
.on_after_settle(lambda ctx: print(f"🎉 Payment settled: {ctx.result.transaction}"))
|
|
.on_settle_failure(lambda ctx: print("Settle failure", ctx))
|
|
)
|
|
|
|
# Register EVM schemes (V1 and V2)
|
|
if evm_signer is not None:
|
|
register_exact_evm_facilitator(
|
|
facilitator,
|
|
evm_signer,
|
|
networks=EVM_NETWORK,
|
|
deploy_erc4337_with_eip6492=True,
|
|
)
|
|
|
|
# Register upto EVM scheme (V2 only)
|
|
facilitator.register([EVM_NETWORK], UptoEvmFacilitatorScheme(evm_signer))
|
|
|
|
# Register SVM schemes (V1 and V2)
|
|
if svm_signer is not None:
|
|
register_exact_svm_facilitator(
|
|
facilitator,
|
|
svm_signer,
|
|
networks=SVM_NETWORK,
|
|
)
|
|
|
|
# Register TVM schemes (V2)
|
|
if tvm_signer is not None:
|
|
facilitator.register(
|
|
[TVM_NETWORK],
|
|
ExactTvmFacilitatorScheme(tvm_signer),
|
|
)
|
|
|
|
# Register gas sponsoring extensions
|
|
if evm_signer is not None and erc20_approval_signer is not None:
|
|
facilitator.register_extension(EIP2612_GAS_SPONSORING)
|
|
facilitator.register_extension(
|
|
Erc20ApprovalFacilitatorExtension(signer=erc20_approval_signer)
|
|
)
|
|
|
|
|
|
# Pydantic models for request/response
|
|
class VerifyRequest(BaseModel):
|
|
"""Verify endpoint request body."""
|
|
|
|
paymentPayload: dict
|
|
paymentRequirements: dict
|
|
|
|
|
|
class SettleRequest(BaseModel):
|
|
"""Settle endpoint request body."""
|
|
|
|
paymentPayload: dict
|
|
paymentRequirements: dict
|
|
|
|
|
|
# Initialize FastAPI app
|
|
app = FastAPI(
|
|
title="x402 Python Facilitator (E2E)",
|
|
description="Verifies and settles x402 payments on-chain for e2e testing",
|
|
version="2.0.0",
|
|
)
|
|
|
|
|
|
@app.post("/verify")
|
|
async def verify(request: VerifyRequest):
|
|
"""Verify a payment against requirements.
|
|
|
|
Note: Payment tracking and bazaar discovery are handled by lifecycle hooks.
|
|
|
|
Args:
|
|
request: Payment payload and requirements to verify.
|
|
|
|
Returns:
|
|
VerifyResponse with isValid and payer (if valid) or invalidReason.
|
|
"""
|
|
try:
|
|
from x402.schemas import parse_payment_payload, parse_payment_requirements
|
|
|
|
# Parse payload (auto-detects V1/V2) and requirements (based on payload version)
|
|
payload = parse_payment_payload(request.paymentPayload)
|
|
requirements = parse_payment_requirements(
|
|
payload.x402_version, request.paymentRequirements
|
|
)
|
|
|
|
# Hooks will automatically:
|
|
# - Track verified payment (on_after_verify)
|
|
# - Extract and catalog discovery info (on_after_verify)
|
|
response = await facilitator.verify(payload, requirements)
|
|
|
|
if not response.is_valid:
|
|
print(
|
|
f" ❌ Verify rejected: {response.invalid_reason} (payer={response.payer})"
|
|
)
|
|
|
|
return response.model_dump(by_alias=True, exclude_none=True)
|
|
except Exception as e:
|
|
import traceback
|
|
|
|
print(f"Verify error: {e}")
|
|
traceback.print_exc()
|
|
raise HTTPException(status_code=500, detail=str(e))
|
|
|
|
|
|
@app.post("/settle")
|
|
async def settle(request: SettleRequest):
|
|
"""Settle a payment on-chain.
|
|
|
|
Note: Verification validation and cleanup are handled by lifecycle hooks.
|
|
|
|
Args:
|
|
request: Payment payload and requirements to settle.
|
|
|
|
Returns:
|
|
SettleResponse with success, transaction, network, and payer.
|
|
"""
|
|
try:
|
|
from x402.schemas import parse_payment_payload, parse_payment_requirements
|
|
|
|
# Parse payload (auto-detects V1/V2) and requirements (based on payload version)
|
|
payload = parse_payment_payload(request.paymentPayload)
|
|
requirements = parse_payment_requirements(
|
|
payload.x402_version, request.paymentRequirements
|
|
)
|
|
|
|
# Hooks will automatically:
|
|
# - Validate payment was verified (on_before_settle - will abort if not)
|
|
# - Check verification timeout (on_before_settle)
|
|
# - Clean up tracking (on_after_settle / on_settle_failure)
|
|
response = await facilitator.settle(payload, requirements)
|
|
|
|
return response.model_dump(by_alias=True, exclude_none=True)
|
|
except Exception as e:
|
|
print(f"Settle error: {e}")
|
|
|
|
# Check if this was an abort from hook
|
|
if "aborted" in str(e).lower() or "Settlement aborted" in str(e):
|
|
from x402.schemas import SettleResponse
|
|
|
|
abort = SettleResponse(
|
|
success=False,
|
|
error_reason=str(e).replace("Settlement aborted: ", ""),
|
|
network=request.paymentPayload.get("accepted", {}).get(
|
|
"network", "unknown"
|
|
),
|
|
transaction="",
|
|
)
|
|
return abort.model_dump(by_alias=True, exclude_none=True)
|
|
|
|
raise HTTPException(status_code=500, detail=str(e))
|
|
|
|
|
|
@app.get("/supported")
|
|
async def supported():
|
|
"""Get supported payment kinds and extensions.
|
|
|
|
Returns:
|
|
SupportedResponse with kinds, extensions, and signers.
|
|
"""
|
|
try:
|
|
response = facilitator.get_supported()
|
|
|
|
return {
|
|
"kinds": [
|
|
k.model_dump(by_alias=True, exclude_none=True) for k in response.kinds
|
|
],
|
|
"extensions": response.extensions,
|
|
"signers": response.signers,
|
|
}
|
|
except Exception as e:
|
|
print(f"Supported error: {e}")
|
|
raise HTTPException(status_code=500, detail=str(e))
|
|
|
|
|
|
@app.get("/discovery/resources")
|
|
async def discovery_resources(limit: int = 100, offset: int = 0):
|
|
"""List all discovered resources from bazaar.
|
|
|
|
Returns:
|
|
Discovery response with x402Version, items, and pagination.
|
|
"""
|
|
try:
|
|
return bazaar_catalog.get_resources(limit, offset)
|
|
except Exception as e:
|
|
print(f"Discovery error: {e}")
|
|
raise HTTPException(status_code=500, detail=str(e))
|
|
|
|
|
|
@app.get("/discovery/search")
|
|
async def discovery_search(query: str, type: str | None = None, limit: int | None = None):
|
|
"""Search discovered resources using keyword matching.
|
|
|
|
Args:
|
|
query: The search query string (required).
|
|
type: Optional filter by resource type.
|
|
limit: Optional advisory maximum number of results.
|
|
|
|
Returns:
|
|
Search response with x402Version, items, and optional pagination hints.
|
|
"""
|
|
try:
|
|
return bazaar_catalog.search_resources(query, type, limit)
|
|
except Exception as e:
|
|
print(f"Discovery search error: {e}")
|
|
raise HTTPException(status_code=500, detail=str(e)) from e
|
|
|
|
|
|
@app.get("/health")
|
|
async def health():
|
|
"""Health check endpoint."""
|
|
return {
|
|
"status": "ok",
|
|
"networks": [kind.network for kind in facilitator.get_supported().kinds],
|
|
"facilitator": "python",
|
|
"version": "2.0.0",
|
|
"extensions": facilitator.get_extensions(),
|
|
"discoveredResources": bazaar_catalog.get_count(),
|
|
}
|
|
|
|
|
|
@app.post("/close")
|
|
async def close():
|
|
"""Graceful shutdown endpoint."""
|
|
import asyncio
|
|
|
|
print("Received shutdown request")
|
|
if tvm_signer is not None:
|
|
tvm_signer.close()
|
|
|
|
async def shutdown():
|
|
await asyncio.sleep(0.1)
|
|
os._exit(0)
|
|
|
|
asyncio.create_task(shutdown())
|
|
return {"message": "Facilitator shutting down gracefully"}
|
|
|
|
|
|
if __name__ == "__main__":
|
|
import uvicorn
|
|
|
|
supported_networks = [kind.network for kind in facilitator.get_supported().kinds]
|
|
active_extensions = facilitator.get_extensions()
|
|
|
|
print(f"""
|
|
╔════════════════════════════════════════════════════════╗
|
|
║ x402 Python Facilitator (E2E) ║
|
|
╠════════════════════════════════════════════════════════╣
|
|
║ Server: http://localhost:{PORT} ║
|
|
║ Networks: {", ".join(supported_networks[:2])[:36]:<36}║
|
|
║ Extensions: {", ".join(active_extensions)[:36]:<36}║
|
|
║ ║
|
|
║ Endpoints: ║
|
|
║ • POST /verify (verify payment) ║
|
|
║ • POST /settle (settle payment) ║
|
|
║ • GET /supported (get supported kinds) ║
|
|
║ • GET /discovery/resources (list discovered) ║
|
|
║ • GET /health (health check) ║
|
|
║ • POST /close (shutdown server) ║
|
|
╚════════════════════════════════════════════════════════╝
|
|
""")
|
|
|
|
# Log that facilitator is ready (needed for e2e test discovery)
|
|
print("Facilitator listening")
|
|
|
|
uvicorn.run(app, host="0.0.0.0", port=PORT, log_level="warning")
|