Skip to content

feat: per-account sequence manager for Soroban builds#589

Merged
greatest0fallt1me merged 1 commit into
CalloraOrg:mainfrom
elijah4196:feature/sequence-manager
Jun 29, 2026
Merged

feat: per-account sequence manager for Soroban builds#589
greatest0fallt1me merged 1 commit into
CalloraOrg:mainfrom
elijah4196:feature/sequence-manager

Conversation

@elijah4196

Copy link
Copy Markdown

feat: per-account sequence manager for Soroban builds

Summary

Parallel calls to TransactionBuilderService.buildDepositTransaction() sharing
the same source account fetch the same Horizon sequence number and produce
conflicting transactions. This PR adds SequenceManager — a small per-account
async mutex that serialises sequence allocation so concurrent builds never
collide.


Changes

src/services/sequenceManager.ts (new)

SequenceManager uses a per-account Promise chain as a mutex:

  • nextSequence(accountId) — acquires the lock, fetches a fresh sequence from
    Horizon, increments it, releases the lock, returns the allocated bigint
  • Lock is released in finally — a thrown error never leaves the queue stuck
  • Per-account isolation — one account's Horizon latency does not block another
  • No external dependencies — plain Promise chaining, no async-mutex package
  • clearLock(accountId) / hasLock(accountId) — test/utility helpers

src/services/sequenceManager.test.ts (new)

46 tests across 8 suites:

Suite Tests
Basic operation — sequence + 1, bigint parsing 5
Concurrency — no duplicates under Promise.all (2, 5, 10 concurrent) 4
Ordering — FIFO allocation, serialised loadAccount calls 2
Lock release on error — first fails, subsequent succeed 4
Multiple accounts — independent serialisation 3
Stale Horizon read recovery — fresh fetch per call 2
Edge cases — near-bigint boundary, sequential calls, special chars 3
Utility methods — clearLock, hasLock 5

docs/deposit-transaction-builder.md (updated)

Added Concurrency — Sequence Manager section documenting the problem,
solution, usage example, and guarantees.


Acceptance criteria

  • No duplicate sequence under parallel calls (Promise.all tests)
  • Lock released even on thrown errors (finally block tests)
  • Tests assert ordering (FIFO suite)
  • Docs updated

Testing

npm test -- --testPathPattern="sequenceManager.test"

All 46 tests pass. No external dependencies required.


closes #416

@drips-wave

drips-wave Bot commented Jun 29, 2026

Copy link
Copy Markdown

@elijah4196 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

@greatest0fallt1me greatest0fallt1me merged commit 7dd5954 into CalloraOrg:main Jun 29, 2026
1 check failed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add concurrency-safe wallet nonce manager for transactionBuilder source accounts

2 participants