[FEAT] Off-Chain P2P Emergency Settlement Recovery & Manual Proof Export

[jotel-dev]

telegram link : t.me/nullifiersystem

---

1. Summary & Core Promise

When users experience extended cellular network outages during a physical cash handover, the client app cannot reach Velo API servers to update trade state. Currently, if local queue items in mobile/frontend/src/lib/sync/queue.ts fail to sync, users have no mechanism to export signed transaction proofs locally to complete settlement manually.

This feature implements an Off-Chain P2P Emergency Settlement Recovery & Manual Proof Export Engine. It builds offline transaction queue serialization in mobile/frontend/src/lib/sync/queue.ts, cryptographically signed JSON/QR proof file exports, an offline proof validation route in apps/api/src/routes/cash.ts, and PostgreSQL row locking (SELECT FOR UPDATE).

---

2. Background & Architectural Risks

• Stuck Cash Settlements: Users paying cash in offline areas cannot complete escrow releases if server connections drop indefinitely.
• Proof Tampering: Allowing manual proof uploads without cryptographic signatures allows malicious users to forge offline release authorizations.

---

3. Database Layer Specifications

Migration SQL (034_add_offline_recovery_proofs.sql)

CREATE TABLE offline_recovery_proofs (
    proof_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    trade_id VARCHAR(64) NOT NULL UNIQUE REFERENCES cash_requests(id),
    signer_pubkey VARCHAR(56) NOT NULL,
    signature VARCHAR(128) NOT NULL,
    payload_json JSONB NOT NULL,
    processed_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);

---

4. Backend Route & Service Layer Specifications

Route: POST /api/v1/cash/emergency-recovery

1. Signature Verification: Verifies payload cryptographic signature against buyer/seller Ed25519 public keys.
2. Locking: DB transaction acquires SELECT FOR UPDATE on cash_requests.
3. Execution: Settles trade on-chain via submitReleaseTx().
4. Response: Returns HTTP 200 OK with settlement confirmation.

---

5. Background Processors / Workers

(Client-Side Sync Queue Worker in mobile/frontend/src/lib/sync/queue.ts)

---

6. Frontend / UI Component Specifications

Component: mobile/frontend/src/components/OfflineRecoveryModal.tsx

• UI modal allowing users to export encrypted proof JSON files offline, display backup recovery QR codes, or import proof files when network connection restores.

---

7. Rigor & Test Plan

1. Unit Tests (mobile/frontend/src/lib/sync/__tests__/queue.test.ts): Test offline transaction serialization and signature generation.
2. Recovery API Test (cash.test.ts): Upload valid signed proof file; assert trade releases cleanly.

---

8. Relevant Files Inventory

New Files to Create

• apps/api/src/db/migrations/034_add_offline_recovery_proofs.sql
• mobile/frontend/src/components/OfflineRecoveryModal.tsx
• mobile/frontend/src/lib/sync/__tests__/queue.test.ts

Existing Files to Modify

• mobile/frontend/src/lib/sync/queue.ts
• apps/api/src/routes/cash.ts
• apps/api/src/lib/store.ts
• mobile/frontend/src/pages/ClaimQR.tsx

---

9. Acceptance Criteria

• Offline claims can be exported as signed cryptographic JSON/QR files.
• Emergency recovery route validates signatures before releasing escrow.
• Prevents double-settlement using PostgreSQL row locks.

---

10. Contributor Notes

• ⚠️ Security Warning: ALWAYS verify payload Ed25519 signatures before processing manual proof uploads.

[Devadakene]

I am experienced enough to implement this issue having worked on similar issues in the past. Please assign

[Olamidepy]

Hi Maintainer,

I would love to be assigned to this issue.

I’m a Full-Stack Developer and I also actively explore blockchain development and smart contracts, which has strengthened my problem-solving skills and attention to code quality.

After reviewing the issue, I believe I can contribute effectively and deliver a well-tested solution within the expected standards of the project.

ETA: 6 hours

Thank you for your consideration.

[grantfox-oss]

🦊 GrantFox — @Olamidepy has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #432)
2. Your PR will be reviewed by the Nullifier-Systems maintainers

Good luck! Track your progress on GrantFox.