[FEAT] Cross-Ledger Settlement Time-Lock Atomic Swap Dispute Bridge

[jotel-dev]

telegram link : t.me/nullifiersystem

1. Summary & Core Promise

In contracts/atomic-swap/src/lib.rs and contracts/htlc-core/src/lib.rs, cross-chain HTLC atomic swaps rely on counterparties manually revealing secret preimages before expiration. If one counterparty fails to fulfill their side of the swap on an external chain, the trade hangs until full timeout expiration, locking the honest party's funds without an automated dispute claims path.
This feature implements a Cross-Ledger Settlement Time-Lock Atomic Swap Dispute Bridge. It adds automated dual-side secret extraction (apps/api/src/lib/timeouts.ts), automatic refund claim triggers upon counterparty expiration, PostgreSQL transaction locking (SELECT FOR UPDATE), and automated alert webhooks (apps/api/src/lib/webhook.ts).

2. Background & Architectural Risks

• Asymmetric Lockup Risk: One party reveals the secret on Chain A while the counterpart delays revealing on Chain B, risking partial trade execution.
• Relayer Secret Leakage: Failing to extract revealed secrets from on-chain event logs before the local HTLC timeout expires leads to unrecoverable collateral loss.

3. Database Layer Specifications

Migration SQL (029_add_atomic_swap_dispute_bridge.sql)

CREATE TYPE swap_dispute_state AS ENUM ('ACTIVE', 'SECRET_EXTRACTED', 'REFUND_CLAIMABLE', 'RESOLVED');
CREATE TABLE atomic_swap_dispute_bridges (
    swap_id VARCHAR(64) PRIMARY KEY,
    initiator_address VARCHAR(56) NOT NULL,
    counterparty_address VARCHAR(56) NOT NULL,
    secret_hash VARCHAR(64) NOT NULL,
    secret_preimage VARCHAR(64) NULL,
    expiration_ledger INT NOT NULL,
    state swap_dispute_state NOT NULL DEFAULT 'ACTIVE',
    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);
CREATE INDEX idx_swap_expiration ON atomic_swap_dispute_bridges(expiration_ledger, state);

Data Locking (SELECT FOR UPDATE)

BEGIN;
SELECT swap_id, state, expiration_ledger 
FROM atomic_swap_dispute_bridges 
WHERE swap_id = $1 
FOR UPDATE;
-- Update state to REFUND_CLAIMABLE or RESOLVED...
COMMIT;

---

4. Backend Route & Service Layer Specifications

Route: POST /api/v1/swaps/dispute-claim

1. Validation: Zod validates swapId and checks current ledger height.
2. Locking: DB transaction acquires SELECT FOR UPDATE on atomic_swap_dispute_bridges.
3. Preimage Check: If secret preimage was revealed on-chain, extracts secret and completes swap; if expired, triggers automatic refund.
4. Response: Returns HTTP 200 OK with execution proof.

---

5. Background Processors / Workers

Atomic Swap Secret Extraction Worker (apps/api/src/lib/workers/swapDisputeWorker.ts)

• Watches Stellar and EVM ledger event logs for SecretRevealed events, extracts preimages, and resolves pending cross-chain legs automatically.

---

6. Frontend / UI Component Specifications

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

• Renders real-time HTLC lockup status, secret extraction progress, and one-click "Claim Dispute Refund" button when timeout threshold is breached.

---

7. Rigor & Test Plan

1. Unit Tests (contracts/atomic-swap/src/test.rs): Test secret extraction and automated HTLC refund claim on counterparty timeout.
2. Concurrency Stress Test (tests/concurrency/swap_dispute_stress.test.ts): 50 concurrent swap secret extraction calls verifying zero duplicate refund executions.

---

8. Relevant Files Inventory

New Files to Create

• apps/api/src/db/migrations/029_add_atomic_swap_dispute_bridge.sql
• apps/api/src/routes/swap-dispute.ts
• apps/api/src/lib/workers/swapDisputeWorker.ts
• tests/concurrency/swap_dispute_stress.test.ts
• mobile/frontend/src/components/AtomicSwapDisputeCard.tsx

Existing Files to Modify

• contracts/atomic-swap/src/lib.rs
• contracts/htlc-core/src/lib.rs
• contracts/atomic-swap/src/test.rs
• apps/api/src/lib/timeouts.ts
• apps/api/src/lib/webhook.ts
• apps/api/src/lib/stellar.ts

---

9. Acceptance Criteria

• Automated worker extracts on-chain secret preimages within 1 ledger sequence.
• Expired swaps automatically trigger refund() for honest counterparties.
• Concurrent claim attempts resolved safely via SELECT FOR UPDATE.

---

10. Contributor Notes

• ⚠️ Atomic Safety: ALWAYS extract and store revealed secret preimages off-chain immediately upon on-chain event emission.

[N-thnI]

Dear sir please assign

[sebas11042]

Hi! I’m a software developer and open-source contributor with experience in backend development, Stellar/Soroban-related payment flows, databases, concurrency control, and financial state transitions where retries and partial settlement must never produce duplicate payouts. I’m particularly interested in HTLC and cross-ledger settlement logic because secret propagation, timeout handling, and refund execution all need to preserve atomicity even when one side of a swap stops cooperating.

For this issue, I’d implement the dispute bridge around a durable swap state machine backed by transactional row locking, with the worker continuously reconciling Stellar/EVM SecretRevealed events against pending swaps and persisting extracted preimages before any follow-up action. I’d make completion versus refund mutually exclusive and idempotent, add explicit ledger-expiry checks and webhook/status updates, and build concurrency tests proving that dozens of simultaneous claim/refund attempts produce exactly one settlement outcome with no duplicate refund or double-resolution path.

[grantfox-oss]

🦊 GrantFox — @N-thnI 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 #446)
2. Your PR will be reviewed by the Nullifier-Systems maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Third Campaign campaign!

@N-thnI's PR #449 was approved and merged by @jotel-dev.

🏆 @N-thnI: You earned 40 FoxPoints for this contribution! Your current tier: Builder (1,414 total points). Track your full progress on GrantFox.

👏 Great work, @N-thnI! Keep contributing to Nullifier-Systems.