Transactional Escrow Orchestration Service with Soroban RPC & Idempotent Retries

[meshackyaro]

Description

This issue aims to address the implementation of Transactional Escrow Orchestration Service with Soroban RPC & Idempotent Retries.

The core objective is to: Implement a backend orchestration service that submits and confirms escrow contract operations over Soroban RPC with idempotency keys, exactly-once semantics, and reconciliation of on-chain versus off-chain state.

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

Tasks

• Review the existing Spring Boot structure under backend-api/src/main/java
• Implement the service and REST endpoints for: Transactional Escrow Orchestration Service with Soroban RPC & Idempotent Retries
• Add or adjust JPA entities, repositories, and schema migrations as needed
• Write unit and integration tests (Spring Boot Test; MockWebServer for external RPC calls)
• Add caching for Maven dependencies in CI
• Run ./mvnw verify and ./mvnw test to validate build and coverage

Acceptance Criteria

• Feature accurately implements the objective: Implement a backend orchestration service that submits and confirms escrow contract operations over Soroban RPC with idempotency keys, exactly-once semantics, and reconciliation of on-chain versus off-chain state.
• 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

3-5 days

[ebubeb683-ship-it]

Hello boss, Please assign this issue to me. i checked it out and im confident i will solve it
my eta is 4 hours

[tecch-wiz]

I’m interested in tackling this! I have a strong background in smart contract development and full-stack systems, so I'm well-equipped to handle the requirements here. Could you please assign this to me?

[kris-nana]

Hi Maintainer,

I would like to apply to work on this issue! Building a resilient, exactly-once escrow orchestration service that bridges off-chain Spring Boot backend state with on-chain Soroban RPC execution requires careful handling of concurrency, idempotency, and state reconciliation.

Here is my proposed technical architecture and execution strategy:

Architecture & Implementation Breakdown

1. Idempotency & Transaction State Machine
   Idempotency Key Tracking: Implement an EscrowTransaction JPA entity with a unique idempotencyKey, tracking transaction states (PENDING, SUBMITTED, CONFIRMED, FAILED_RETRYABLE, FAILED_FATAL).

Exactly-Once Semantics: Use DB-level unique constraints and optimistic locking (@Version) on transaction state records to guarantee that concurrent API requests with the same idempotency key return the active transaction status rather than duplicate on-chain submissions.

2. Soroban RPC Integration & Retries
   Soroban RPC Client: Integrate Stellar Java SDK / RPC client with exponential backoff and jitter for transient RPC errors (e.g., node timeout, sequence number mismatch).

State Reconciliation Worker: Build a scheduled reconciliation service (@scheduled / Spring Batch) to poll Soroban RPC for unconfirmed on-chain transactions, resolving potential network partitions where a transaction succeeded on-chain but dropped off-chain.

3. REST API & OpenAPI Documentation
   Create clean REST endpoints under backend-api for initiating, retrying, and fetching escrow transaction status.

Document public API contracts using standard OpenAPI / Swagger annotations, ensuring error payloads adhere to a consistent RFC 7807 ProblemDetail response contract.

4. Testing & CI Performance
   MockWebServer & Integration Tests: Write comprehensive @SpringBootTest suites using MockWebServer to mock Soroban RPC node responses across happy paths, network timeouts, bad signatures, and race conditions.

Maven CI Caching: Update GitHub Actions CI workflows to add actions/cache for local Maven repository dependencies (~/.m2/repository) to improve build times.

[grantfox-oss]

🦊 GrantFox — @kris-nana 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 #21)
2. Your PR will be reviewed by the workman-labs maintainers

Good luck! Track your progress on GrantFox.