ZK-073: Redesign relayer binding and zero-relayer semantics across SDK and contract code

[ANAVHEOBA]

Wave: PrivacyLayer ZK Wave 2
Issue Key: ZK-073
Area: withdraw
Priority: High
Drips Complexity: High

Summary

Recipient binding is not the only mismatch. Relayer handling still mixes zero-field sentinels, decoded addresses, and fee rules in ways that are easy to misapply across stacks.

Relevant Code

• sdk/src/encoding.ts
• sdk/src/proof.ts
• circuits/withdraw/src/spend.nr
• contracts/privacy_pool/src/core/withdraw.rs
• contracts/privacy_pool/src/utils/address_decoder.rs
• contracts/privacy_pool/src/utils/validation.rs

Scope

• Define one relayer binding contract for no-relayer, relayer-with-fee, and malformed-relayer cases.
• Align SDK serialization, circuit validation, and Soroban withdraw handling around that contract.
• Cover fee zero, relayer zero, and relayer mismatch cases in end-to-end tests.

Acceptance Criteria

• Relayer handling no longer depends on ad hoc zero-address assumptions in multiple modules.
• The contract accepts only relayer encodings that the SDK can produce canonically.
• Regression tests distinguish absent relayer from malformed relayer cleanly.

Out of Scope

• New wallet UX and non-ZK frontend polish
• Unrelated Soroban business logic outside the withdrawal proof boundary

Dependencies

• ZK-036
• ZK-072

Validation

• Inspect derived checks: node scripts/zk_ticket_check.mjs --issue-key ZK-073
• Run derived checks: node scripts/zk_ticket_check.mjs --issue-key ZK-073 --run
• Pull requests should include Wave Issue Key: ZK-073 in the title or body.

References

• sdk/src/encoding.ts
• sdk/src/proof.ts
• circuits/withdraw/src/spend.nr
• contracts/privacy_pool/src/core/withdraw.rs
• contracts/privacy_pool/src/utils/address_decoder.rs
• contracts/privacy_pool/src/utils/validation.rs

[Mrchinedum]

@Mrchinedum has applied to work on this issue as part of the Stellar Wave Program's 4th wave.

Hi, I’d like to take this on.

I’ll standardize relayer handling across SDK, circuit, and contract into a single consistent model.

Approach:

• Define a strict relayer encoding contract:

  • no relayer (absent)
  • valid relayer + fee
  • malformed relayer (explicitly rejected)

• Align:

  • sdk/src/encoding.ts (canonical serialization)
  • sdk/src/proof.ts (proof inputs)
  • circuits/withdraw/src/spend.nr (validation rules)
  • contract withdraw + address validation logic

• Remove reliance on ad-hoc zero-address checks across modules

• Ensure only SDK-canonical relayer formats are accepted by contract

• Add end-to-end tests covering:

  • no relayer vs zero relayer vs malformed relayer
  • fee = 0 edge case
  • relayer mismatch rejection

I’ll make relayer semantics consistent and enforceable across the full stack.

Wave Issue Key: ZK-073

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Mrchinedum to this issue.

[soomtochukwu]

@soomtochukwu has applied to work on this issue as part of the Stellar Wave Program's 4th wave.

Hello, you can trust me to take care of this ASAP

ℹ️ Repo Maintainers: To accept this application, review their application or assign @soomtochukwu to this issue.

[drips-wave]

Congratulations, @soomtochukwu! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on April 29, 2026.

🧑‍💻 @soomtochukwu: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊