Stand-alone scripts that exercise the canonical ERC-8183 flows from the client side. Mirrors erc8183-contracts/test/e2e/flows/* one-to-one, plus an end-to-end IPFS integration test.
All scripts share _helpers.py for env loading, job description, expiry, and provider address.
| Script | Flow | Outcome |
|---|---|---|
happy.py |
create → register → fund → provider submits → settle → COMPLETED |
payment released, no dispute |
zero_price.py |
create → register → set_budget(0) → fund(0) → provider submits → settle → COMPLETED |
zero price: no escrow, nobody paid |
dispute_reject.py |
submit → client dispute → whitelisted voters voteReject → settle → REJECTED |
refund to client |
stalemate_expire.py |
submit → client dispute → quorum not reached → job expires → claimRefund → EXPIRED |
refund via expiry |
never_submit.py |
provider never submits → job expires → claimRefund → EXPIRED |
refund via expiry |
cancel_open.py |
client cancels before funding (reject) → REJECTED |
nothing escrowed |
create_and_verify.py |
client funds → agent's funded-poll loop submits → IPFS verify (add --dispute to also exercise the dispute branch) |
integration test against agent-server |
uv sync
cp .env.example .env
# Fill in PRIVATE_KEY (client) and PROVIDER_ADDRESS at minimum.WALLET_PASSWORD keystore password (any string)
PRIVATE_KEY client private key (0x...) - not needed when WALLET_KIND=twak
PROVIDER_ADDRESS provider EOA
# Optional
WALLET_KIND evm (default) | twak - client wallet backend
NETWORK bsc-testnet (default)
RPC_URL override RPC
ERC8183_COMMERCE_ADDRESS override commerce proxy
ERC8183_ROUTER_ADDRESS override router proxy
ERC8183_POLICY_ADDRESS override policy
One env var switches the client wallet from a local private key to the Trust Wallet Agent Kit (twak) CLI:
WALLET_KIND=twak uv run python happy.pyAll five flows run unchanged - create_job, register_job, set_budget, fund, dispute, settle, cancel, claim_refund all go through twak erc8183 ... instead of local web3 signing. This is the SDK's wallet polymorphism at work: the flow scripts contain zero if twak branching - make_primary_client() picks the wallet, and ERC8183Client routes every write through wallet.make_executor().
What switches and what doesn't:
- Client role: twak.
PRIVATE_KEYbecomes optional - twak owns custody, so the client address is whatevertwak wallet addresssays, and the wallet password is resolved by twak itself (TWAK_WALLET_PASSWORDor the OS keychain) - the SDK never sees it. - Provider / voter roles: stay EVM in these examples (
PROVIDER_PRIVATE_KEY/VOTER_PRIVATE_KEY). The seller role itself works on twak since v0.19.0 (submitcarries thedeliverable_urloptParams), but a machine has exactly one twak wallet (per HOME), so twak cannot play two distinct parties locally - these flows keep the counterparty on EVM for that reason. See the capability referencedocs/twak.md. (For a fully twak-driven both-roles self-deal, seeexamples/twak/e2e_smoke.py.)
Prerequisites (one-time):
npm install -g @trustwallet/cli(>= 0.20).- twak API credentials:
twak init --api-key <id> --api-secret <secret>, orTWAK_ACCESS_ID/TWAK_HMAC_SECRETenv vars. - A created twak wallet on the target network, funded with testnet BNB (gas) and the payment token -
twak wallet addressto find it. - The wallet password reachable by twak:
TWAK_WALLET_PASSWORD(e.g. in.env.local) ortwak wallet keychain save.
For a hermetic, no-funds-required twak tour, see examples/twak/.
- Expiry is set to
now + 10 minutesfor flows that should complete quickly andnow + 65 minutesfor flows that rely on expiry (the on-chain minimum isnow + 5 minutes). - The dispute-reject and stalemate-expire flows rely on a whitelisted voter. Provide
VOTER_PRIVATE_KEYin the env if you want the script to cast the reject vote itself; otherwise it prints the jobId and expects an out-of-band vote (seeexamples/voter/). - Every script is idempotent-ish: it creates a new job each run, so reruns don't collide.
zero_price.pydemonstrates zero price (ERC-8183budget == 0).set_budget(0)may be sent by either the client or the provider - the demo drives the buyer flow (client sets the budget) and still requiresPROVIDER_PRIVATE_KEYfor the provider-onlysubmit.fund(0)moves no tokens and the SDK skips the ERC-20 approve entirely, so the client needs no payment-token balance or allowance.
End-to-end test against a running agent-server. Requires the agent-server to be started first with IPFS storage configured:
# Terminal 1
cd examples/agent-server && uv run python scripts/run_agent.py
# Terminal 2
cd examples/client && python create_and_verify.pyThe script:
- Creates, registers, budgets, and funds a job for the agent-server provider.
- Waits for the agent-server's funded-job poll loop to pick up the job.
- Polls until the job reaches
SUBMITTED. - Fetches the
DeliverableManifestfrom the IPFS gateway and verifies its keccak256 hash against the on-chaindeliverablebytes32. - (only with
--dispute) Raises a dispute - leaving the voter to review viaexamples/voter/watch.py. Without the flag, the script ends here and the job can be settled toCOMPLETEDafter the dispute window elapses.