[Tracking Issue] Implement Orderbook Withdrawals

[freesig]

Overview

Implement complete trustless withdrawal flow for the orderbook system, enabling users to withdraw funds from the off-chain orderbook back to on-chain with ZK-verified state proofs.

Goals

• Add burn proof API endpoint to generate merkle proofs for withdrawals
• Enable Groth16 proving in void-toolkit for on-chain verification
• Complete executeWithdrawal contract verification with ZK-verified state roots

Technical Notes

Full Withdrawal Flow

1. User calls requestWithdrawal(token, amount, nonce) on contract → emits Withdraw event
2. Orderbook app processes event via oracle, calls handle_withdraw() which burns funds in state
3. User fetches burn proof from API: GET /get-burn-proof/{owner}/{nonce} → gets merkle proof + height
4. User requests ZK proof at that height from the app
5. User calls executeWithdrawal() with both the burn merkle proof and ZK proof
6. Contract verifies ZK proof → extracts state root from journal (not stored on-chain)
7. Contract verifies merkle proof against the state root from the ZK proof
8. Tokens transferred to user

Note: State roots are never stored on-chain. The ZK proof and merkle proof are verified together in the same transaction.

Key Data Formats

• Address type: 33 bytes (1 byte type + 32 bytes data)
• Burned key: 42 bytes [BURNED:1][owner:33][nonce:8]
• Burned value: 97 bytes [amount:32][asset:33][chain_id:32]
• Merkle trie uses SHA3-256 (Keccak) for hashing

Dependencies

• Sub-issues 1 and 2 can be implemented in parallel
• Sub-issue 3 depends on understanding exact proof format from sub-issue 1

Out of Scope

• Frontend UI changes for withdrawal flow
• Cross-chain withdrawal support (Solana)