feat(sequencer): implement deterministic transaction sequencer and su…

[Alaka-ibr]

feat(sequencer): implement deterministic transaction sequencer and supply drift guard (#758)

Summary

Closes #758

When concurrent buy/sell operations hit the same creator, optimistic database commits can cause supply drift when on-chain execution sequence differs from read order. This PR implements a per-creator in-process FIFO sequencer and Redis distributed lock to serialize mutating operations per creator and halt operations if supply drift is detected.

Changes

1. In-Process FIFO Queue (src/utils/creator-sequencer.utils.ts)

• CreatorSequencer maintains a Map<creatorWallet, AsyncQueue>.
• Operations are executed strictly in FIFO order per creator.
• Queues created lazily and garbage-collected after 5 minutes of inactivity.
• Requests waiting > 10 seconds in queue are dequeued and rejected with SequencerTimeoutError (503 sequencer_timeout).

2. Redis Distributed Lock (src/utils/sequencer-lock.utils.ts)

• Cross-instance locking via seq_lock:{creatorWallet} (15s TTL, 5s background renewal interval).
• Acquire timeout of 8s returns SequencerContentionError (503 sequencer_contention).

3. Supply Drift Guard (src/utils/supply-drift-guard.utils.ts)

• verifySupplyAndGuard: compares expected post-operation supply against actual supply returned on-chain.
• On mismatch: logs error supply_drift_detected and sets Redis flag drift:{creatorWallet} to halt further operations.
• assertNoSupplyDrift: checks drift flag before operations.
• clearDrift: clears the Redis flag.

4. Admin Clearance Endpoint (src/modules/admin/sequencer.controllers.ts, src/modules/admin/sequencer.routes.ts)

• POST /api/v1/internal/sequencer/clear-drift/:creatorWallet: allows operators to clear the drift flag.

Test Coverage

Unit tests in src/utils/creator-sequencer.utils.test.ts & src/utils/supply-drift-guard.utils.test.ts (8 passed):

• Serializes operations for the same creator in FIFO order.
• Allows concurrent operations across different creators.
• Rejects queued operations waiting > 10s with SequencerTimeoutError.
• Cleans up idle queues after 5 minutes.
• Verifies supply match and detects supply drift on divergence.
• Halts operations when drift flag is set and resumes after clearDrift.

[Chucks1093]

LGTM