Repository navigation
Stellar Key Custody & Transaction Signing Service with KMS Abstraction, Sequence Management & Fee-Bump Retries #40
Description
Description
This issue aims to address the implementation of Stellar Key Custody & Transaction Signing Service with KMS Abstraction, Sequence Management & Fee-Bump Retries.
The core objective is to: Build the signing layer the backend needs to submit Soroban transactions safely — pluggable key custody (env/local for dev, KMS/HSM for production), serialized sequence-number allocation with channel accounts, and fee-bump-based resubmission for transactions that stall in the mempool.
By completing this feature, we will ensure that the GuildWorkman protocol maintains its high standards for security, usability, and decentralized logic. This issue requires careful attention to the Backend architecture and adherence to the existing project conventions.
When picking up this issue, please ensure you document any new dependencies or architectural decisions made during development.
Component
Backend (Spring Boot / Java 17)
Difficulty
⚫ Very Hard
Current state
The backend has no Stellar/Soroban signing capability at all, and no key material handling worth the name — utils/JwtUtils.java signs with a literal HMAC256("secret"), which is a fair indication of the current bar. Every on-chain feature on the roadmap (escrow orchestration, settlement, loyalty minting) is blocked on a service that can hold a key, allocate a sequence number without racing itself, and get a transaction to final status.
Sequence-number handling is the sharp edge: a single source account serializes all submissions and one stuck transaction blocks the queue, while naive parallel submission produces tx_bad_seq storms. Channel accounts and a proper allocation strategy are the point of this issue, not an optional extra.
Tasks
- Review the existing Spring Boot structure under
backend-api/src/main/java - Implement the service and REST endpoints for: Stellar Key Custody & Transaction Signing Service with KMS Abstraction, Sequence Management & Fee-Bump Retries
- Define a
SigningProviderabstraction with at least a local/dev implementation and one externalized-KMS implementation, selected by profile — no secret key may ever be logged, serialized into a response, or committed - Implement sequence-number allocation that is safe under concurrent submission, using a channel-account pool with database-backed leasing
- Implement submission with polling to final status, plus fee-bump resubmission for transactions that stall, with a bounded fee ceiling
- Classify and handle Soroban/Horizon failure modes distinctly:
tx_bad_seq,tx_insufficient_fee,tx_too_late, and simulation failures each need their own recovery path - Persist every submission attempt with its hash and terminal status so a restart can resume rather than double-submit
- Add or adjust JPA entities, repositories, and schema migrations as needed
- Write unit and integration tests (Spring Boot Test; MockWebServer for external RPC calls), including a concurrency test that proves N parallel submissions produce N distinct sequence numbers
- Add caching for Maven dependencies in CI
- Run
./mvnw verifyand./mvnw testto validate build and coverage
Acceptance Criteria
- Feature accurately implements the objective: Build the signing layer the backend needs to submit Soroban transactions safely — pluggable key custody (env/local for dev, KMS/HSM for production), serialized sequence-number allocation with channel accounts, and fee-bump-based resubmission for transactions that stall in the mempool.
- Secret key material never appears in logs, responses, exception messages, or the repository
- Concurrent submissions never collide on a sequence number, demonstrated by a test
- A stalled transaction is fee-bumped and reaches a terminal state rather than hanging forever
- A restart mid-submission does not double-submit an already-broadcast transaction
- Any PR that introduces failing tests or compilation errors is automatically blocked
- Endpoints/services are covered by tests including failure and concurrency paths
- Public API is documented (OpenAPI) and errors follow a consistent response contract
- Code is properly reviewed and approved by codeowners
Estimated Time
4-6 days
Activity
kris-nana commentedon Aug 19, 2026
Hi maintainer,
I’d like to take on this issue. I’m particularly interested in it because it sits at the boundary between backend architecture, distributed concurrency, and secure transaction infrastructure. I’d approach the implementation with the goal of making the signing layer reliable enough to serve as the foundation for the protocol’s upcoming on-chain features, rather than treating it as simply an RPC wrapper.
Proposed approach
I’d start by reviewing the existing
backend-apistructure, persistence conventions, configuration, exception handling, and test setup before introducing new abstractions.The implementation would be organized around a few explicit responsibilities:
SigningProviderinterface with a profile-selected local/dev implementation and an external KMS-backed implementation. Private keys would remain confined to the provider boundary and would never be logged, returned through APIs, persisted unnecessarily, or included in exception messages.tx_bad_seq,tx_insufficient_fee,tx_too_late, simulation failures, and other terminal errors distinctly, with recovery limited to cases where retrying is actually safe.Concurrency and recovery
The sequence allocator is the part I would treat as the highest-risk area.
I would add a concurrency-focused integration test that launches N parallel submissions against the same channel-account pool and verifies that all N allocations are distinct. I’d also test lease expiration/recovery and contention between workers, rather than relying only on a unit test around an increment operation.
For restart safety, I’d make submission state durable enough to distinguish:
That allows recovery logic to inspect existing attempts before broadcasting again.
Testing
I’d cover the implementation with Spring Boot integration tests and MockWebServer-based RPC tests, including:
tx_bad_seq;tx_insufficient_fee;tx_too_late;I’d also run both
./mvnw testand./mvnw verifybefore considering the implementation complete, and ensure CI caches Maven dependencies and blocks merges on compilation/test failures.Security and architectural decisions
I would document the KMS/provider boundary and explain why key material is intentionally never represented in persistence or API DTOs. The local provider would exist strictly for development/testing, while production configuration would select the externalized provider.
I’d also document the sequence allocation model, lease semantics, retry/fee-bump policy, and any additional dependencies introduced. If the existing project conventions provide suitable patterns, I’d prefer extending them rather than introducing unnecessary infrastructure.
The goal would be a small, explicit set of abstractions with strong invariants: keys stay outside application state, sequences are allocated exactly once, every broadcast is durable, retries are bounded, and every failure has a defined recovery path.
I’m happy to break the work into reviewable commits—for example, persistence/schema + allocation, signing abstraction/providers, submission/retry state machine, API, and tests/CI—so the security- and concurrency-sensitive pieces can be reviewed independently.
I’d also make sure the final PR includes the architectural/dependency documentation and leaves the project passing
./mvnw testand./mvnw verify.Sparexonzy95 commentedon Aug 19, 2026
I’m interested in taking this issue. I have experience with React and Stellar/Soroban integrations, and I’ve reviewed the requirements and existing transaction flow carefully. I’m confident I can implement the required signing, sequence management, retry, and testing logic and submit a clean PR within 2 days.
Sparexonzy95 commentedon Aug 19, 2026
I’m interested in taking this issue. I have experience working with Stellar/Soroban transaction flows and backend integrations, and I understand the key requirements around secure signing, concurrency-safe sequence management, persistent transaction recovery, and fee-bump retries. I’m confident I can implement this cleanly within the existing Spring Boot architecture, cover the critical failure and concurrency paths with tests, and submit a solid PR within 2-3 days.
grantfox-oss commentedon Aug 19, 2026
🦊 GrantFox — @kris-nana has been assigned to this issue as part of the Third Campaign campaign!
Next steps:
Closes #40)Good luck! Track your progress on GrantFox.
grantfox-oss commentedon Aug 22, 2026
🎉 This issue has been marked as completed on GrantFox as part of the Third Campaign campaign!
@kris-nana's PR #48 was approved and merged by @meshackyaro.
🏆 @kris-nana: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (306 total points). Track your full progress on GrantFox.
👏 Great work, @kris-nana! Keep contributing to workman-labs.
feat(backend): Stellar key custody & transaction signing service with…