Migrate `withdrawal_audit` to async flusher w/ Postgres sink (with multi-instance lock)

[ibrahimmosouf-png]

Migrate withdrawal_audit to async flusher w/ Postgres sink (with multi-instance lock)

Labels: cli, infrastructure, priority/medium
Difficulty: High · Effort: L
Backlog slot: 52

Problem Statement

WithdrawalAuditLog is in-memory + on-disk JSONL. No durable multi-host store; no scheduled flush. Critically, two concurrent CLI processes writing to the same JSONL file can interleave bytes, corrupt records, or duplicate appends — this is single-writer-only but the file system does not enforce it.

Why it Matters

• A serious operational tool needs a back-end store that survives container eviction and supports analytics.
• Audit logs must be tamper-evident; interleaved writes silently violate that.

Expected Outcome

• Background tokio task flushes every 5s.
• Plugin arch: AuditSink trait with JsonlSink and PostgresSink impls.
• Process-policy lock: a flock(2) advisory lock on a sidecar file (audit.lock) gates every flush; flushers in degraded Postgres mode rotate through a leader-election pattern anchored on the lock. Two CLI processes running concurrently must produce append-only output without interleaving.

Acceptance Criteria

• Two-process race test: cargo test --features integration flush_concurrent_processes_succeeds passes.
• Documented operational guide + runbook including "what the advisory lock does under transient network partition".

Files Likely Affected

• crates/tools/src/withdrawal_audit.rs

Dependencies

None.

---

[Heazzy500]

Hello, I’ve gone through the requirements and I’m confident I can implement a proper solution that matches the acceptance criteria. Kindly assign this issue to me.

[Adiz4415]

i would love to work on this issue, please assign.

[grantfox-oss]

🦊 GrantFox — @Adiz4415 has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

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

Good luck! Track your progress on GrantFox.