feat(client): add collateral return plan/execute to secure clients

[kartojal]

Summary

Adds Collateral Return support (DEV-445): a combos Protocol V2 position-lifecycle workflow that returns idle collateral to the wallet.

Sync

while True:
    plan = client.plan_collateral_return()

    handle = client.execute_collateral_return_plan(plan=plan)
    handle.wait()

    if not plan.truncated:
        break

Async

while True:
    plan = await client.plan_collateral_return()

    handle = await client.execute_collateral_return_plan(plan=plan)
    await handle.wait()

    if not plan.truncated:
        break

Available on both SecureClient and AsyncSecureClient (async is identical with await). Supports Deposit Wallet, Safe, and Proxy accounts; EOA-bound clients are rejected before anything is planned or signed.

What's included

• CollateralReturnPlan — an inspectable execution artifact: Decimal collateral amounts, position_summary with consumed/created positions, and forward-compatible operation kinds (known kinds coerce to CollateralReturnOperationKind, unknown kinds parse as plain strings).
• Execution submits the plan's router call exactly as planned — nothing is recomputed client-side. Missing trading approvals fail fast with MissingTradingApprovalsError before any signature; no approval transactions run implicitly. Stale plans raise CollateralReturnPlanRejectedError (never retried; recovery is a fresh plan), while transient submission errors re-sign with a fresh nonce.
• Per-wallet-type envelope signing extracted into shared build_signed_*_payload helpers reused by the existing gasless path; transports gained an optional per-request timeout so only the plan call waits up to 2 minutes.

Tests

• 18 unit tests: wire parsing (renames, base-unit decimals, omitted zero fields, unknown kinds), envelopes for all three wallet types, gates (EOA, wallet/chain mismatch, empty plan), fail-fast approval pre-check, 409 no-retry, and transient wallet-busy re-sign.
• Live integration suite: plan assertions per wallet type, EOA rejection, empty-plan contract (skips while inventory is pending), and a metered seed → plan → execute → wait round trip (net-zero by construction) that finishes by re-submitting the executed plan and asserting it is rejected. All verified against production.

---

Note

Medium Risk
New on-chain execution path via signed router calls and relayer envelopes; mistakes in plan validation or signing could submit wrong transactions, though client-side wallet/chain checks and non-retry on 409 mitigate stale-plan risk.

Overview
Adds collateral return to sync and async secure clients: plan_collateral_return() calls the combos collateral-return service (120s read timeout) and returns a typed CollateralReturnPlanResponse; execute_collateral_return_plan(plan=...) signs the plan’s router_call and submits it to /v1/collateral-return/submit as a gasless transaction. Deposit Wallet, Safe, and Proxy are supported; EOAs are rejected up front; execution needs a Builder or Relayer API key and validates wallet/chain against the plan.

Wires a new combos transport (collateral_return_url on Environment), exports collateral-return models and shared e6 decimal validators, and refactors gasless signing into reusable build_signed_*_payload helpers plus submit_gasless_with_retry (collateral submit uses combos, not the relayer /submit). RelayerEnvelope NewType guards relayer payloads; post_json accepts an optional per-request timeout.

^{Reviewed by Cursor Bugbot for commit 6b4fa14. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 0c13450. Configure here.}