Agent-to-Agent Payment Protocol

Implementation of Issue #4: Lightweight payment protocol for agent-to-agent settlement.

Overview

This PR adds:

1. Solidity Escrow Contract (contracts/AgentEscrow.sol) — trustless escrow with timeout/refund
2. Python Payment Client (src/payment_protocol.py) — full client implementation
3. Unit Tests (tests/test_payment_protocol.py) — comprehensive coverage

Payment Protocol Flow

┌─────────────┐ createPayment() ┌─────────────┐
│ Payer │ ─────────────────────▶ │ Escrow │
│ (client) │ + ETH in value │ Contract │
└─────────────┘ └──────┬──────┘
│ funds locked
┌──────────────────────────────────────┘
│ payer confirms work is done
▼
┌─────────────┐ confirmPayment() ┌─────────────┐
│ Payer │ ─────────────────────▶ │ Payee │
│ │ funds released │ receives │
└─────────────┘ └─────────────┘
(Alternative: timeout → challenge period → refund)

Files

switchboard/
├── contracts/
│ └── AgentEscrow.sol # Solidity escrow contract
├── src/
│ └── payment_protocol.py # Python client library + CLI
├── tests/
│ └── test_payment_protocol.py # Unit tests
└── README.md

Escrow Contract Features

• createPayment: Lock ETH in escrow with timeout + challenge period
• confirmPayment: Payer releases funds to payee (one-step)
• requestRefund: Payer reclaims after timeout + challenge period
• cancelPayment: Mutual cancellation before timeout
• Event logging: PaymentCreated, PaymentLocked, PaymentConfirmed, PaymentReleased, PaymentRefunded

Python Client Features

frompayment_protocolimportPaymentClientclient=PaymentClient(private_key, escrow_address, rpc_url)
# Create and lock paymentreq=client.create_payment(
payee="0xPayeeAddress",
amount_wei=10**18, # 1 ETHtimeout_blocks=100,
challenge_period_blocks=10
)
# Confirm (after work is done)client.confirm_payment(req.request_id)
# Check statusstate=client.get_payment_state(req.request_id)
details=client.get_payment_details(req.request_id)

CLI Usage

# Create payment
python -m payment_protocol --private-key KEY --escrow ADDR --rpc URL \
--action create --payee 0xPayee --amount "0.1 ETH"# Confirm payment
python -m payment_protocol --private-key KEY --escrow ADDR --rpc URL \
--action confirm --request-id REQ-ID
# Check status
python -m payment_protocol --private-key KEY --escrow ADDR --rpc URL \
--action status --request-id REQ-ID

Test Results

$ pytest tests/test_payment_protocol.py -v
test_payment_request_creation ✅
test_payment_request_from_dict ✅
test_format_wei ✅
test_parse_wei ✅
test_payment_state_enum ✅
test_content_hash_deterministic ✅
test_mock_contract_create ✅
test_payment_lifecycle ✅
test_timeout_and_refund ✅
test_payment_metadata ✅
10 passed ✅

Spec Compliance

Spec Requirement	Implementation
Payment request format	PaymentRequest dataclass with JSON serialization
Escrow smart contract	AgentEscrow.sol with full state machine
Confirmation flow	confirmPayment() one-step release
Timeout	timeoutBlocks tracked via block numbers
Refund	requestRefund() after challenge period
Python client	PaymentClient class with sync + async support
Tests	Mock chain state, 10 test cases

Foundry tests

Solidity-level tests for AgentEscrow.sol live in tests-foundry/ and run under Foundry.

# install foundry once
curl -L https://foundry.paradigm.xyz | bash && foundryup
# fetch forge-std submodule
git submodule update --init --recursive
# build + run
forge build
forge test -vvv

Coverage:

• happy path (create → confirm → release)
• timeout + challenge-period refund
• cancellation
• access-control on confirmPayment / requestRefund / cancelPayment
• reentrancy on every external call{value:} (via MaliciousReceiver mock)
• event emission for each state transition