Add perpOB on-chain settlement helpers to sdk/reya_rpc/ (deferred from v2.3.0 migration)

[arturbeg]

The v2.3.0 perpOB SDK migration intentionally deferred all sdk/reya_rpc/ changes — the matching engine handles fill collection and on-chain settlement, so most users don't need an on-chain entry point. This issue tracks the work to expose those primitives for SDK users who do want to settle directly (matching-engine operators, custom liquidation bots, integrators bypassing the REST API).

Context

The on-chain pieces shipped in reya-network feat/perpOB and the off-chain integration is tracked in reya-off-chain-monorepo#2575. The Python SDK migration PR at e755105 ships the REST/WS surface but skips the RPC layer; existing sdk/reya_rpc/actions/trade.py (AMM passive-pool counterparty) is left untouched and will continue to work for legacy AMM positions.

Scope

1. OrdersGatewayProxy ABI

Drop the orders-gateway proxy ABI into sdk/reya_rpc/abis/OrdersGatewayProxy.json, sourced from reya-network/orders-gateway/src/interfaces/IFillExecutionModule.sol and IBatchExecutionModule.sol.

Wire it into sdk/reya_rpc/config.py::get_network_addresses with the OrdersGateway proxy address per chain (mainnet 0xfc8c96be87da63cecddbf54abfa7b13ee8044739, devnet1/cronos 0x5a0ac2f89e0bdeafc5c549e354842210a3e87ca5).

2. New actions

sdk/reya_rpc/actions/settle_fill.py

Wrap IFillExecutionModule.executeFill(ExecuteFillInput). The ExecuteFillInput struct (from orders-gateway/src/libraries/DataTypes.sol) contains:

• accountOrder: OrderDetails — taker order signed via the EIP-712 typehash documented in specs/docs/eip712.md
• counterpartyOrder: OrderDetails — maker order
• accountSignature: EIP712Signature
• counterpartySignature: EIP712Signature
• mePayload: SignedMatchingEnginePayload — fill details + matching-engine signature

Plus IBatchExecutionModule.batchExecuteFill(ExecuteFillInput[]) for batched submission.

sdk/reya_rpc/actions/cancel_nonce.py

Wrap IFillExecutionModule.cancelNonce(address signer, uint256 nonce) for explicit on-chain nonce invalidation (independent of the matching-engine layer's OrderCancel envelope).

3. Event decoding

Add a PassivePerpExecutionV3 decoder so SDK users tailing on-chain logs can parse the new event shape (accountOrderId, counterpartyOrderId, counterpartyExchangeId, PerpFillFees with signed maker fees, executionType enum including DUST). The old PassivePerpExecutionV2 decoder can stay for legacy AMM trades.

4. Examples

• examples/rpc/settle_fill.py — end-to-end example: sign a maker + taker OrderDetails, build the matching-engine payload (mock or real), submit executeFill.
• examples/rpc/cancel_nonce.py — invalidate a signer's nonce on-chain.

5. Tests

• Unit tests for ABI encoding parity (cross-check against TS SDK in reya-off-chain-monorepo/packages/api-v2-sdk).
• Integration test on devnet1 that signs a fill via Python, submits via executeFill, and asserts PassivePerpExecutionV3 event decoded correctly.

Definition of done

• OrdersGatewayProxy.json ABI in place + wired into config.py.
• sdk/reya_rpc/actions/settle_fill.py with executeFill and batchExecuteFill helpers.
• sdk/reya_rpc/actions/cancel_nonce.py.
• PassivePerpExecutionV3 event decoder.
• One end-to-end example under examples/rpc/.
• At least one integration test that signs in Python and decodes the resulting on-chain event.
• Cross-SDK signature parity test against reya-off-chain-monorepo/packages/api-v2-sdk.

Notes

• Order signing already works correctly in sdk/reya_rest_api/auth/signatures.py::sign_order (uses the v2.3.0 Order/OrderDetails typehash). That helper is reusable here — no need for a duplicate signer in sdk/reya_rpc/.
• The matching-engine signature carried in mePayload is produced off-chain by the ME service; SDK users typically receive it from the REST/WS surface rather than constructing it themselves. Document this in the example.
• Verify the OrdersGateway proxy address for devnet1 hasn't been redeployed during the perpOB rollout before pinning it in config.