Аркадий Стена e0ba324d0f
feat: add TVM exact-payment mechanism to Python SDK (#1944)
* 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>
2026-05-08 16:13:22 +02:00

4.8 KiB

Python x402 Facilitator (E2E)

A Python implementation of an x402 facilitator service for end-to-end testing.

Features

  • Multi-Chain Support: Handles EVM (Base Sepolia), SVM (Solana Devnet), and TVM (TON testnet/mainnet) networks
  • Protocol Versions: Supports both x402 V1 and V2 protocols
  • Bazaar Extension: Full support for resource discovery and cataloging
  • Lifecycle Hooks: Payment verification tracking and discovery info extraction

Requirements

  • Python 3.10+
  • uv for dependency management

Setup

# Install dependencies
./install.sh

# Or manually
uv sync

Running

# Using run.sh (recommended for e2e tests)
./run.sh

# Or manually
uv run python main.py

# Or with uvicorn directly
uv run uvicorn main:app --port 4022

Environment Variables

Variable Required Description
PORT No Server port (default: 4022)
EVM_PRIVATE_KEY Conditionally Private key for EVM transactions
SVM_PRIVATE_KEY Conditionally Private key for SVM transactions
TVM_PRIVATE_KEY Conditionally Private key for the TVM highload facilitator wallet
EVM_RPC_URL No Custom EVM RPC URL (default: Base Sepolia)
EVM_NETWORK No EVM network identifier
SVM_NETWORK No SVM network identifier
TVM_NETWORK No TVM network identifier (default: tvm:-3)
TVM_PROVIDER No TVM provider: toncenter (default) or tonapi
TONCENTER_API_KEY No Toncenter API key for TVM testnet
TONCENTER_BASE_URL No Custom Toncenter base URL for TVM
TONAPI_API_KEY No TonAPI API key when TVM_PROVIDER=tonapi
TONAPI_BASE_URL No Custom TonAPI base URL for TVM

TVM funding notes

To fund the TVM facilitator wallet, request testnet TON from @testgiver_ton_bot. The facilitator wallet only needs TON for relay fees and must hold at least 1.1 TON before running tests.

Note: the facilitator uses a highload-wallet-v3 account, so the facilitator's wallet address differs from your W5 address — fund the highload-v3 address, not the W5 one derived from the same key.

To get testnet-USDT for the payer wallet, open the testnet USDT transfer link or scan the QR code below: QR code for the testnet USDT transfer link

Endpoints

Method Path Description
POST /verify Verify a payment against requirements
POST /settle Settle a payment on-chain
GET /supported Get supported payment kinds and extensions
GET /discovery/resources List discovered resources (bazaar)
GET /health Health check
POST /close Graceful shutdown

API Examples

Verify Payment

curl -X POST http://localhost:4022/verify \
  -H "Content-Type: application/json" \
  -d '{
    "paymentPayload": {...},
    "paymentRequirements": {...}
  }'

Settle Payment

curl -X POST http://localhost:4022/settle \
  -H "Content-Type: application/json" \
  -d '{
    "paymentPayload": {...},
    "paymentRequirements": {...}
  }'

Health Check

curl http://localhost:4022/health

Architecture

The facilitator uses:

  • FastAPI: Web framework for HTTP endpoints
  • x402 Python SDK: Core x402 functionality
  • web3.py: EVM blockchain interactions
  • solders: SVM blockchain interactions
  • pytoniq + Toncenter/TonAPI: TVM blockchain interactions

E2E Test Integration

This facilitator is automatically discovered by the e2e test framework via test.config.json. The framework will:

  1. Start the facilitator on an available port
  2. Wait for the "Facilitator listening" log message
  3. Run tests through the facilitator
  4. Shut down via POST /close