* 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>
4.8 KiB
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:
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:
- Start the facilitator on an available port
- Wait for the "Facilitator listening" log message
- Run tests through the facilitator
- Shut down via POST
/close