Spike: Define the on-chain write path for escrow actions (create/release/dispute)

[meshackyaro]

Description

EscrowService (src/escrow/escrow.service.ts) is a purely in-memory store — create, release, and raiseDispute never build, sign, or submit a Soroban transaction. Meanwhile the event-ingestion pipeline (src/event-ingestion/ledger-cursor.service.ts → event-processor.service.ts) already consumes on-chain Soroban events and applies them to EscrowService, so a read path from chain to API state exists, but no write path from the API back to chain exists at all.

It's unclear whether the intended design is:

• The backend itself builds/signs/submits transactions server-side (requiring custody of a signing key), or
• Escrow actions are meant to be client-signed via trustflow-sdk / the frontend, with the backend acting as a pure event-driven read cache and the REST endpoints (POST /escrows, POST /escrows/:id/release, POST /escrows/:id/dispute) only reflecting/validating local state until the on-chain event round-trips back through ingestion.

This ambiguity blocks writing a real implementation ticket, and it directly affects the SDK's TrustFlowEscrowClient (currently mocked) and the contract's missing non-disputed release entrypoint — both flagged in sibling spike issues in their respective repos.

Component

Backend

Difficulty

🟣 Spike — investigation required, scope not yet defined

Tasks

• Map every escrow action against whether it currently ever touches the chain (it doesn't) vs. whether event-ingestion would eventually observe it
• Evaluate server-side signing/custody vs. client-signed-only architectures, including security and key-management trade-offs
• Prototype one end-to-end escrow action (e.g. release) using the chosen approach against Soroban testnet
• Document how this reconciles with stellar/soroban.helper.ts / stellar/stellar.service.ts, which exist but aren't wired into EscrowService
• Write up findings with a recommended architecture

Acceptance Criteria

• A written recommendation covering the chosen write-path architecture and its trade-offs
• A working prototype (even if not merged) demonstrating one escrow action actually reaching chain
• Follow-up implementation issue(s) filed based on the conclusion
• Any blocking unknowns (e.g. key custody, HSM/signing service needs) explicitly flagged

Estimated Time

2-3 days (time-boxed spike)

[onyekachi66]

I would like to work on this issue having worked on something similar in the past

[kris-nana]

Hi, I’d like to work on this spike because it sits at an important architectural boundary in the project: the backend already has a clear chain → event ingestion → API state path, but the reverse API/SDK → Soroban → event ingestion → API state path has not yet been established.

My goal would be to turn that ambiguity into a concrete, testable architecture rather than prematurely implementing one of the possible approaches.

Proposed approach

I would start by tracing the complete lifecycle of each escrow action:

• create
• release
• raiseDispute

For each action, I’d map the current EscrowService behavior, the corresponding Soroban contract/event behavior, and where LedgerCursorService and EventProcessorService would observe the resulting on-chain state. This should establish exactly what is currently local-only versus what can be reconciled through event ingestion.

From there, I would investigate the two primary write-path models:

1. Server-side transaction submission

   • Backend constructs, signs, and submits Soroban transactions.
   • Evaluate signing-key custody, authorization boundaries, operational security, key rotation, and whether an HSM/external signing service would eventually be required.
   • Determine how this fits with the existing stellar/soroban.helper.ts and stellar/stellar.service.ts.

2. Client-signed transactions

   • Backend remains an event-driven read/cache layer.
   • trustflow-sdk or the frontend constructs and signs the transaction, submits it to Soroban, and the backend eventually reflects the result through event ingestion.
   • Evaluate how REST endpoints should behave while a transaction is pending, how transaction hashes/statuses should be represented, and what validation belongs on the backend versus the contract.

I would use the existing SDK/frontend and contract behavior as constraints rather than assuming that the backend should become a transaction custodian simply because EscrowService currently exposes mutation methods.

Prototype

Once the architecture is narrowed down, I would implement a minimal end-to-end prototype for one action, preferably release:

caller → selected write path → Soroban testnet → emitted event → event ingestion → EscrowService/API state

The prototype would explicitly verify that the transaction reaches the network and that the resulting chain event eventually reconciles the backend state. I would also document any contract limitation encountered, particularly the currently missing non-disputed release entrypoint.

Deliverables

The spike would produce:

• A written recommendation for the write-path architecture and its trade-offs.
• A lifecycle map for all current escrow actions.
• A working Soroban testnet prototype demonstrating one action reaching chain and round-tripping through ingestion.
• Documentation explaining how the chosen approach interacts with soroban.helper.ts and stellar.service.ts.
• Follow-up implementation issues for backend, SDK/frontend, and/or contract work discovered during the investigation.
• An explicit list of unresolved blockers, including key custody, signing infrastructure, contract capabilities, transaction status handling, and authorization assumptions.

What I would optimize for

The key outcome for me would not simply be “make EscrowService submit a transaction.” I’d want to establish where transaction authority belongs and make the resulting state model consistent with the existing event-driven architecture.

In particular, I would avoid creating a backend mutation path that gives the server signing authority without first establishing why that authority is required. If client signing is sufficient for the product and security model, keeping the backend as a validation/read-cache layer could substantially reduce key-custody risk. Conversely, if server-side execution is required for the intended trust model, the spike should identify the appropriate signing boundary and operational controls before implementation.

I’m comfortable working across the NestJS backend, Soroban transaction flow, event ingestion, and SDK/contract boundaries needed to answer those questions. The acceptance criteria make this a good fit for an investigation-first contribution: establish the architecture with evidence, prove the critical path on testnet, and leave behind actionable implementation issues rather than an ambiguous design.

[grantfox-oss]

🦊 GrantFox — @kris-nana 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 #180)
2. Your PR will be reviewed by the trustflow-protocol 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!

@kris-nana's PR #186 was approved and merged by @meshackyaro.

🏆 @kris-nana: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (271 total points). Track your full progress on GrantFox.

👏 Great work, @kris-nana! Keep contributing to trustflow-protocol.