Project Summary
Zcash Durable Payment Outbox is a self-hosted Zallet payout service that preserves a business payment’s identity and saves its final transaction before broadcasting, allowing eligible retries to reuse the recorded transaction. This grant will turn the working regtest MVP into a reviewed release with verified restoration, wallet authority controls, supported recovery and network upgrade qualification.
Project Description
Automated payout applications must handle a common operational problem: a wallet or node completes an operation, but the application loses the response. Retrying the business request as a new payment can create another payout.
Outbox provides a durable payment record between an application and its dedicated Zallet wallet. Developers submit a stable bounty, refund, reward or withdrawal ID together with the approved payment details. Outbox preserves that identity throughout transaction construction, verification, submission and status tracking.
The service binds each payment ID to its recipient, amount and memo; retains ownership of wallet construction operations; independently verifies transaction effects and authorization; saves the chosen transaction bytes; and submits those bytes to Zebra.
Applications receive a persistent status they can query after a timeout or restart.
The existing MVP includes:
- A Rust service with SQLite persistence.
- An authenticated local API and CLI.
- A Zallet PCZT adapter.
- A separate transaction verifier.
- A durable bounty/refund reference application.
- Recorded results for 43 Rust tests and 10 compiled API/CLI checks.
- A corrected-build qualification run covering nine scenarios using real Zallet and Zebra processes.
- An additional real-wallet recovery test demonstrating that payments with identical details cannot adopt each other’s saved construction response.
Results are tied to the tested source, executable and qualification tooling.
The executed MVP profile is disposable NU6.3 regtest, with one positive Ironwood sender input, one recipient and two through eight actions. The funded work will qualify the supported operational release.
Proposed Problem
A successful Zcash payout can look like a failed request. The wallet sends the transaction, but the application crashes or loses the response before recording it. The funds have moved; the application still says “unpaid.”
For example, a bounty platform paying 2 ZEC may retry that unpaid record and send another 2 ZEC. The operator must then reconcile the discrepancy and seek repayment. Simply avoiding retries creates the opposite problem: legitimate payments remain unresolved, requiring manual investigation and delaying recipients.
The application cannot safely decide whether to retry from a timeout alone. Request deduplication does not establish what the wallet completed or which transaction was published.
This failure class has already appeared in Zcash development. ZecHub payout issue #159 documented transaction-persistence and duplicate-payment problems. Although that issue is closed, it illustrates the consequences of leaving payment reliability to individual application implementations.
Developers building automated rewards, refunds, bounties and withdrawals through Zallet need a reusable way to preserve each payment’s identity and transaction before publication, so recovering from an ordinary crash does not become another spending decision.
Proposed Solution
Outbox gives applications a durable payment record that survives lost responses, retries and restarts.
Before requesting wallet construction, the service saves the application’s original payment ID and approved recipient, amount and memo. It retains the associated wallet-operation identity, then verifies and saves the final transaction bytes before broadcasting.
For the 2 ZEC bounty example, the application retries using the same bounty ID. If the transaction was already committed, Outbox submits those same recorded bytes instead of constructing another payout. Reusing that ID with different payment details is rejected.
If a crash happens earlier and the wallet’s outcome remains uncertain, Outbox preserves the operation record and pauses further construction until supported recovery establishes what happened. An uncertain response never becomes automatic permission to pay again.
A persistent status API lets applications distinguish payments awaiting recovery, submitted transactions and observed confirmations. Operators receive a documented recovery path instead of having to guess whether a timeout means failure.
The funded release adds verified restoration, dedicated-wallet authority controls and expanded failure testing, so the same payment history remains authoritative through the supported deployment and recovery procedures.
Solution Format
An MIT-licensed repository containing:
- Rust service, authenticated API and CLI.
- Zallet adapter and independent transaction verifier.
- Linux deployment package and configuration checks.
- Bounty/refund reference integration.
- Automated tests, CI and qualification tooling.
- Compatibility table and operator recovery/restore documentation.
- Published external review findings and remediation records.
- Versioned release and 90 days of bounded maintenance.
The initial operational profile is one host, one dedicated Zallet wallet/account, one retained Outbox database and one recipient per payment.
Spending keys remain in Zallet. Operators must protect wallet RPC access and service credentials as spending authority.
Dependencies
The project depends on Zallet PCZT APIs, Zebra, compatible Zcash Rust libraries, SQLite, Rust/native build tools and Python qualification tooling.
Verified restoration also requires an independently retained freshness record outside the snapshots being restored.
The executed MVP pins Zallet v0.1.0-beta.3 and Zebra v6.2.3. NU7 compatibility is a funded acceptance gate. Compatible wallet, node and verifier revisions will be pinned and exercised together.
If a required upstream capability is unavailable, the affected acceptance and payment will remain pending until a revised plan is agreed with ZCG.
A qualified external reviewer and an intended-user representative will be selected for review and milestone validation.
Technical Approach
- Durable payment identity
Preserve immutable intent, original operation bindings and persistent construction ownership. After final transaction commitment, retries use only the committed bytes; construction and extraction cannot run again for that payment.
- Wallet authority
Verify disabled wallet auto-broadcasting, protect RPC access and establish exclusive construction authority for the dedicated wallet. Changed or unknown settings and a second uncoordinated construction client must block sending.
- Verified restoration
Check the application ledger, Outbox and wallet against an independently retained monotonic freshness record. Missing, old or inconsistent state must stop construction and publication.
This protection depends on the independent record remaining outside the restored snapshots.
- Supported recovery
Publish an operation/error matrix and implement recovery where original provenance and operation completion can be established. Unknown outcomes retain ownership and require operator review.
- Bounded transaction coverage
Extend support to one through four positive Ironwood inputs, one recipient and the documented action cap. Verify actual transaction effects, change, fees and authorization. Explicitly reject unsupported transaction shapes.
- Compatibility and failure qualification
Exercise actual expiry and rejection, relevant wallet restarts and controlled reorgs. Verify a real NU7 shielded payment on compatible wallet, node and verifier revisions.
Publish results against exact tested artifacts, keeping synthetic tests and real-wallet evidence separately identified.
- Deployment scope
The supported release covers the documented single-host, dedicated-wallet profile. Multi-host writers, arbitrary wallet backends, hosted custody, TEX/multistep payments and automatic replacement are outside this request.
The service preserves its documented retry contract; it does not promise global exactly-once execution or automatic recovery from every uncertainty.
Upstream Merge Opportunities
The deliverable is a standalone service using upstream APIs. No upstream merge is assumed for acceptance. Any upstream defects identified during qualification will be reported with reproducible evidence and handled through the relevant project’s contribution process.
Open Source License
MIT
Hardware/Software Costs (USD)
$400
Hardware/Software Justification
$400 is allocated for temporary compute and storage: $200 for isolated Zallet/Zebra integration and failure testing, and $200 for release verification and compatibility checks during the 90-day maintenance period. These environments allow destructive recovery tests without affecting operational wallets. Existing development equipment and open-source software will be used; no hardware purchase is requested
Service Costs (USD)
$4000
Service Costs Justification
$4,000 is allocated for a focused independent technical review of payment-operation binding, wallet authority, backup restoration and transaction publication. The review will assess whether the implemented controls preserve the documented payment guarantees across retries and failures. Deliverables include written findings and verification of remediation. The reviewer and final engagement scope will be confirmed before the engagement begins.
Compensation Costs (USD)
$25,600
Compensation Costs Justification
| Work | Hours | Rate (USD/hour) | Total |
|---|---|---|---|
| Rust service and wallet integration | 280 | $75 | $21,000 |
| QA, deployment, reproducible testing and documentation | 45 | $40 | $1,800 |
| Delivery coordination and milestone reporting | 20 | $50 | $1,000 |
| Maintenance over 90 days after release | 30 | $60 | $1,800 |
| Total | 375 | $25,600 |
Total Budget (USD)
$30,000
Previous Funding
No
Previous Funding Details
No response
Other Funding Sources
No
Other Funding Sources Details
No response
Implementation Risks
- Upstream compatibility: Wallet APIs and upgrade dependencies can change. Qualification uses explicit version pins; unmet prerequisites leave the affected release gate pending.
- Uncertain outcomes: Some operations cannot be resolved automatically. Retained ownership protects payment history but can interrupt payouts.
- Restoration and authority: Sending depends on verified freshness and controlled wallet access. Failed checks stop the workflow.
- External review: Material findings must be resolved or the affected capability disabled before acceptance.
Material scope or schedule changes will be reported and agreed with ZCG
Potential Side Effects
Conservative recovery can delay legitimate payments and require operator intervention. Persistent statuses and a documented recovery workflow will make these cases visible.
Applications must retain their original payment IDs and must not treat an uncertain response as permission to issue a replacement or refund.
Operator documentation will cover RPC credentials, sensitive artifacts and the supported backup/restore procedure. Chain observations will remain distinct from permanent settlement claims.
Success Metrics
Applicable baseline and new scenarios pass against the exact release artifacts using the supported real wallet/node profile.
Lost submission responses and restarts result in identical-byte retries without additional construction after commitment.
Cross-payment recovery artifacts and changed payment details are rejected.
Failed final database commits prevent publication.
Stale or mismatched restores and uncoordinated construction clients produce no prohibited wallet mutation or publication.
Real supported one-to-four-input payments pass independent checks.
Actual expiry/rejection and relevant reorg/restart cases preserve payment identity without automatic replacement.
An intended-user representative records fresh-environment replay and milestone acceptance.
External review findings and their resolutions are published.
The maintenance period concludes with an issue ledger, monthly updates and handover notes.
Startup Funding (USD)
$0
Startup Funding Justification
na
Milestone Details
Milestone 1: Wallet Authority and Verified Restoration
Amount: $8,000
Completion: End of week 3
User story: As a payout operator, I need restored or competing service instances to stop before they can send from unverified state.
Deliverables:
- Supported deployment model and wallet authority checks.
- Independently anchored restore verification.
- Recovery runbook.
- Fault tests and qualification evidence.
Acceptance: The evaluator verifies refusal of stale snapshots, missing freshness records, wallet/Outbox mismatch, business-ledger rollback, changed broadcast settings and a second uncoordinated construction client. Refused cases produce no prohibited wallet mutation or publication, while a valid deployment completes a normal payout.
Cost allocation: Engineering $7,500; coordination $300; infrastructure $200.
Milestone 2: Recovery, Input Coverage and Network Qualification
Amount: $10,000
Completion: End of week 7, subject to upstream qualification prerequisites
User story: As an application developer, I need supported payouts and recovery paths to work without treating an uncertain response as permission to pay again.
Deliverables:
- Qualified recovery/error matrix and supported recovery paths.
- One-to-four-input, single-recipient support within the action cap.
- Actual expiry/rejection experiments.
- NU7 qualification on compatible wallet/node/verifier revisions.
- Updated API and status documentation.
Acceptance: The evaluator replays supported recovery under the original operation binding, verifies genuine supported input cases, observes expiry/rejection without automatic replacement, and verifies a real NU7 shielded payment using the independent verifier. Unknown operations retain ownership.
An unavailable upstream prerequisite leaves the affected acceptance and payment pending until an agreed resolution.
Cost allocation: Engineering $9,000; QA/release $800; coordination $200.
Milestone 3: Independent Review and Reproducible Release
Amount: $10,000
Completion: End of week 10, after preceding acceptance gates
User story: As a Zallet application developer, I need a reviewed release that I can deploy and evaluate against a documented payout contract.
Deliverables:
- Focused independent review and remediation.
- Linux build/deployment package and CI.
- Updated bounty/refund reference integration.
- Versioned release and pinned artifact records.
- One-command qualification after documented provisioning.
- Operator recovery and restoration documentation.
Acceptance: A qualified evaluator reproduces the workflow in a fresh environment. Applicable baseline and new failure cases pass, including original-operation recovery, wallet restart and controlled reorg checks. Review findings and fixes are published, and unsupported or unqualified behavior remains disabled.
Cost allocation: Engineering $4,500; QA/release $1,000; coordination $500; external review $4,000.
Milestone 4: Maintenance and Handover
Amount: $2,000
Completion: 90 calendar days after milestone 3 acceptance
User story: As an operator, I need a clear route for reporting defects and receiving compatibility/security triage after release.
Deliverables:
- Up to 30 hours of maintenance.
- Public monthly updates.
- Issue and response ledger.
- Justified fixes with corresponding validation.
- Final compatibility and handover notes.
Acceptance: The evaluator reviews the maintenance record, supported build/replay status, issue resolutions and remaining limitations. Additional features and upgrades require separate agreement.
Cost allocation: Maintenance $1,800; infrastructure $200.
Supporting Documents
MVP baseline: fd21e966a74798231104206056a66e976ead1b44.