x402/go/test/integration
Carson Roscoe 2b7914c72e
feat: batch settlement go sdk (#2230)
* feat: add batch-settlement implementation to Go SDK

* feat: add batch-settlement examples for go sdk

* feat: updated typescript examples to match go examples

* feat: add e2e testing for batch-settlement in go

* Batch-settlement: go-ts parity (#2227)

* fix PendingRequest and refund cleanup

* fix lint

* remove duplicate payer info from storage

* fix PAYMENT-RESPONSE field ordering

* clean up comments

* consolidate ProcessSettlementWithExtensions into ProcessSettlement

---------

Co-authored-by: phdargen <p.dargent@cern.ch>
2026-05-07 18:26:39 -07:00
..

Integration Tests

These integration tests verify the complete x402 payment flows with real mechanism implementations. The EVM and SVM tests can make real on-chain transactions when configured with private keys.

Test Overview

Core Integration Tests (Always Run)

  • โœ… TestCoreIntegration - Core x402 client/service/facilitator flow (mock cash)
  • โœ… TestHTTPIntegration - HTTP layer integration (mock cash)

Mechanism Integration Tests (Require Configuration)

  • ๐Ÿ” TestEVMIntegrationV2 - Full EVM V2 payment flow (Base Sepolia)
  • ๐Ÿ” TestEVMIntegrationV1 - Full EVM V1 payment flow (Base Sepolia)
  • ๐Ÿ” TestSVMIntegrationV2 - Full SVM V2 payment flow (Solana Devnet)
  • ๐Ÿ” TestSVMIntegrationV1 - Full SVM V1 payment flow (Solana Devnet)

Batch-Settlement (Batched) Integration Tests (Require Configuration)

EVM batched mechanism tests in evm_batch_settlement_test.go. All tests issue real Base Sepolia transactions and skip when env vars are missing.

  • ๐Ÿ” TestBatchSettlementIntegration_DepositThenVoucher โ€” direct API: deposit + follow-up voucher
  • ๐Ÿ” TestBatchSettlementIntegration_HTTPMiddleware โ€” full HTTP middleware end-to-end
  • ๐Ÿ” TestBatchSettlementIntegration_MultiVoucherClaimSettle โ€” 4 requests + manager.Claim + manager.Settle
  • ๐Ÿ” TestBatchSettlementIntegration_RefundPartial โ€” partial refund leaves channel open
  • ๐Ÿ” TestBatchSettlementIntegration_RefundDrainedChannelShortCircuit โ€” local short-circuit on drained channel
  • ๐Ÿ” TestBatchSettlementIntegration_RefundNonRecoverableFastFail โ€” amount_exceeds_balance errors immediately
  • ๐Ÿ” TestBatchSettlementIntegration_RefundRecoverableRetryExhaustion โ€” recoverable 402 โ†’ retry โ†’ exhaust
  • ๐Ÿ” TestBatchSettlementIntegration_AutoClaimTick โ€” ClaimIntervalSecs triggers OnClaim
  • ๐Ÿ” TestBatchSettlementIntegration_AutoClaimAndSettleTick โ€” both OnClaim and OnSettle fire
  • ๐Ÿ” TestBatchSettlementIntegration_WithdrawalPendingRefund โ€” pending-withdraw detection + manager.Refund

Tests marked with ๐Ÿ” require environment variables and will skip if not configured.

Running Tests

Without Configuration (Core Tests Only)

make test-integration

Output:

โœ… TestCoreIntegration - PASS
โœ… TestHTTPIntegration - PASS
โญ๏ธ  TestEVMIntegrationV2 - SKIP (env vars not set)
โญ๏ธ  TestEVMIntegrationV1 - SKIP (env vars not set)
โญ๏ธ  TestSVMIntegrationV2 - SKIP (env vars not set)
โญ๏ธ  TestSVMIntegrationV1 - SKIP (env vars not set)

With Configuration (All Tests + Real Transactions)

# Set environment variables
source .env

# Run integration tests
make test-integration

Output:

โœ… TestCoreIntegration - PASS
โœ… TestHTTPIntegration - PASS
โœ… TestEVMIntegrationV2 - PASS (real Base Sepolia transaction)
โœ… TestEVMIntegrationV1 - PASS (real Base Sepolia transaction)
โœ… TestSVMIntegrationV2 - PASS (real Solana Devnet transaction)
โœ… TestSVMIntegrationV1 - PASS (real Solana Devnet transaction)

Configuration

Create a .env file in the go/ directory:

# EVM Configuration (Base Sepolia)
EVM_CLIENT_PRIVATE_KEY=<hex_private_key_without_0x>
EVM_FACILITATOR_PRIVATE_KEY=<hex_private_key_without_0x>
EVM_RESOURCE_SERVER_ADDRESS=<0x_ethereum_address>

# Batch-Settlement reuses the EVM_* keys above (EVM_RESOURCE_SERVER_ADDRESS is the payee)
EVM_AUTHORIZER_PRIVATE_KEY=<hex_private_key>        # optional, defaults to EVM_FACILITATOR_PRIVATE_KEY
EVM_RPC_URL=https://sepolia.base.org                # optional, defaults to Base Sepolia public RPC

# SVM Configuration (Solana Devnet)
SVM_CLIENT_PRIVATE_KEY=<base58_private_key>
SVM_FACILITATOR_PRIVATE_KEY=<base58_private_key>
SVM_FACILITATOR_ADDRESS=<base58_solana_address>
SVM_RESOURCE_SERVER_ADDRESS=<base58_solana_address>

Required Setup

EVM (Base Sepolia)

  1. Client Wallet: Must have USDC balance on Base Sepolia
  2. Facilitator Wallet: Must have ETH for gas fees
  3. Resource Server Address: Destination for payments
  4. Network: Base Sepolia (ChainID: 84532)
  5. Token: USDC (0x036CbD53842c5426634e7929541eC2318f3dCF7e)

Get Testnet USDC:

SVM (Solana Devnet)

  1. Client Wallet: Must have USDC balance on Solana Devnet
  2. Client ATA: Must have Associated Token Account for USDC
  3. Resource Server ATA: Must have Associated Token Account for USDC
  4. Facilitator Wallet: Must have SOL for transaction fees
  5. Network: Solana Devnet
  6. Token: USDC (4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU)

Get Testnet USDC:

# Get SOL from faucet
solana airdrop 2 <your_address> --url devnet

# Create ATA for USDC
spl-token create-account 4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU --url devnet

# Get USDC from faucet (if available)
# Or use Solana Devnet USDC faucet

What the Tests Do

EVM Integration Tests

  1. โœ… Creates real client with private key
  2. โœ… Creates real facilitator with private key
  3. โœ… Builds payment requirements (0.001 USDC)
  4. โœ… Client creates EIP-3009 authorization and signs with EIP-712
  5. โœ… Service verifies authorization signature
  6. โœ… Service validates amount, recipient, nonce
  7. โœ… Facilitator submits transferWithAuthorization on-chain
  8. โœ… Waits for transaction confirmation
  9. โœ… Verifies transaction succeeded

SVM Integration Tests

  1. โœ… Creates real client with private key
  2. โœ… Creates real facilitator with private key
  3. โœ… Builds payment requirements (0.001 USDC)
  4. โœ… Client creates Solana transaction with:
    • Compute budget instructions
    • SPL Token TransferChecked instruction
  5. โœ… Client partially signs transaction
  6. โœ… Service decodes and validates transaction structure
  7. โœ… Service validates compute prices, amount, mint, recipient
  8. โœ… Facilitator co-signs transaction
  9. โœ… Facilitator submits transaction to Solana Devnet
  10. โœ… Waits for transaction confirmation (with retries)
  11. โœ… Verifies transaction succeeded

Test Output Examples

EVM Test Output (With Configuration)

=== RUN   TestEVMIntegrationV2
  evm_test.go:400: โœ… Payment verified successfully from 0x1234...
  evm_test.go:429: โœ… Payment settled successfully! Transaction: 0xabcd...
--- PASS: TestEVMIntegrationV2 (5.2s)

SVM Test Output (With Configuration)

=== RUN   TestSVMIntegrationV2
  svm_test.go:288: โœ… Payment payload created with transaction: 512 bytes
  svm_test.go:309: โœ… Payment verified successfully from ABC123...
  svm_test.go:336: โœ… Payment settled successfully! Transaction: 5J7...
  svm_test.go:337:    View on Solana Explorer: https://explorer.solana.com/tx/5J7.../devnet
--- PASS: TestSVMIntegrationV2 (8.1s)

Troubleshooting

EVM Tests Failing

Error: "insufficient balance"

Error: "invalid signature"

  • โžก๏ธ Check EVM_CLIENT_PRIVATE_KEY is correct (no 0x prefix)
  • โžก๏ธ Verify ChainID is 84532 (Base Sepolia)

Error: "nonce already used"

  • โžก๏ธ Wait a bit and retry (nonce was used in previous test)
  • โžก๏ธ Or use a new nonce (automatic in code)

SVM Tests Failing

Error: "ATA not found"

  • โžก๏ธ Create Associated Token Accounts for USDC:
    spl-token create-account 4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU --url devnet
    
  • โžก๏ธ Must create ATAs for both client and resource server addresses

Error: "insufficient lamports"

  • โžก๏ธ Get SOL from devnet faucet:
    solana airdrop 2 <address> --url devnet
    

Error: "transaction simulation failed"

  • โžก๏ธ Check all ATAs exist
  • โžก๏ธ Check client has USDC balance
  • โžก๏ธ Check facilitator has SOL for fees

Security Notes

โš ๏ธ NEVER commit private keys to git โš ๏ธ Use .env file and ensure it's in .gitignore โš ๏ธ Only use testnet keys with no real value โš ๏ธ These tests use devnet/testnet networks only

CI/CD Integration

For CI/CD pipelines, you can:

  1. Skip tests by default (no env vars)
  2. Run with secrets in protected branches:
    env:
      EVM_CLIENT_PRIVATE_KEY: ${{ secrets.EVM_CLIENT_PRIVATE_KEY }}
      EVM_FACILITATOR_PRIVATE_KEY: ${{ secrets.EVM_FACILITATOR_PRIVATE_KEY }}
      # ... other secrets
    

Comparison with TypeScript

The Go integration tests match the TypeScript implementation:

Feature TypeScript Go Status
Real signers โœ… โœ… Implemented
On-chain transactions โœ… โœ… Implemented
Environment variables โœ… โœ… Implemented
Skip if not configured โœ… โœ… Implemented
EVM (Base Sepolia) โœ… โœ… Implemented
SVM (Solana Devnet) โœ… โœ… Implemented

Performance

Without Configuration: ~1.5s (skips mechanism tests) With Configuration: ~10-20s (includes real blockchain transactions)

Next Steps

To run full on-chain tests:

  1. Generate test wallets
  2. Fund wallets with testnet tokens
  3. Create ATAs (for SVM)
  4. Set environment variables
  5. Run make test-integration
  6. Watch real transactions execute! ๐Ÿš€