feat(v2): collateral plumbing — USDC.e → pUSD

[smypmsa]

Context

With the V2 parallel stack in place from the prep issue in this series, this issue migrates the collateral plumbing across the bot. Behind the POLYMARKET_V2_ENABLED flag, every USDC.e reference becomes pUSD, and the deposit helper switches from USDC.e swap to pUSD wrap.

• Cutover: 2026-04-28 ~11:00 UTC
• pUSD is an ERC-20 on Polygon, backed 1:1 by native USDC, backing enforced onchain
• Frontend auto-wraps for retail users; API/bot integrators must call wrap() on the Collateral Onramp contract

References:

• V2 Migration Guide
• Contract Addresses
• Changelog: CLOB V2 Upgrade

Scope

Production code

Behind the V2 flag, swap collateral references:

• backend/core/trading/executor.py — splitPosition collateral arg → pUSD
• backend/core/positions/manager.py — mergePositions collateral arg → pUSD
• backend/core/wallet/manager.py — balance check reads pUSD; approvals target the V2 exchange + V2 NegRisk exchange addresses; allowance asset is pUSD

Experiments (kept mirrored with production)

• Replace experiments/trading/02_swap_to_usdc_e.py with 02_wrap_to_pusd.py — calls wrap() on Collateral Onramp with native USDC input
• Update experiments/trading/01_setup_wallet.py, 03_buy_position.py, 04_transfer_tokens.py to read pUSD when the V2 flag is set
• experiments/onchain-otc/* use the NegRisk adapter directly, which is a separate contract from CTF Exchange — verify against the migration guide whether the adapter ABI changes under V2; if unchanged, no edits needed

Pre-cutover ops checklist (PR description)

• Wallet pre-funded with pUSD (or native USDC ready to wrap) by 2026-04-28 10:00 UTC
• No resting V1 limit orders at cutover (bot does not place GTC orders by default — verify)
• Wrap path tested end-to-end against mainnet: native USDC → wrap() → pUSD balance increases

Out of scope

• ClobClient V2 flip + order-struct changes + fee-model adaptation — separate issue.
• Removing V1 collateral paths — separate post-cutover cleanup issue.

Deadline

Land + tested by 2026-04-27 EOD.

Prerequisites

• feat(v2-prep): parallel V2 stack — py-clob-client-v2, V2 contracts, pUSD config #27 must merge first — provides py-clob-client-v2, V2_CONTRACTS dict (with pUSD + Collateral Onramp addresses), and the POLYMARKET_V2_ENABLED feature flag.

Blocks

• feat(v2): flip ClobClient to V2 — order struct, EIP-712 v2, match-time fees #36 (ClobClient V2 flip) — collateral must be pUSD before V2 orders are signed
• chore(v2): retire V1 paths post-cutover #37 (V1 retirement)