Transaction Assembly, Simulation, Fee-Bump & Retry Pipeline

[meshackyaro]

Description

This issue aims to address the implementation of Transaction Assembly, Simulation, Fee-Bump & Retry Pipeline.

The core objective is to: Build a unified pipeline that assembles, simulates, auto-adjusts resource fees, fee-bumps, and retries Soroban transactions with typed, actionable error surfacing.

By completing this feature, we will ensure that the TrustFlow protocol maintains its high standards for security, usability, and decentralized logic. This issue requires careful attention to the SDK Wrapper 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

SDK Wrapper

Difficulty

🔴 Hard

Tasks

• Review existing Typescript abstract classes
• Implement SDK method for: Transaction Assembly, Simulation, Fee-Bump & Retry Pipeline
• Ensure Tsup successfully exports to ESM and CJS
• Update typedoc comments for the new feature
• Write Jest tests validating XDR payloads
• Run npm run build to verify standard bundling

Acceptance Criteria

• Feature accurately implements the objective: Build a unified pipeline that assembles, simulates, auto-adjusts resource fees, fee-bumps, and retries Soroban transactions with typed, actionable error surfacing.
• Any PR that introduces TypeScript errors is automatically blocked
• CI pipeline runs in under 3 minutes per PR
• Code is properly reviewed and approved by codeowners

Estimated Time

3-5 days

[Benedict07749]

Can i work on this issue

[DSOTec]

Hi maintainer, I'd like to take this. The transaction pipeline is the most load-bearing part of any Soroban SDK wrapper — every contract call flows through it, so the simulation loop, fee adjustment, and retry semantics need to be right before anything builds on top.

Key design decisions:

Pipeline shape: Typed async stages (assemble → simulate → adjust resources → sign → submit → retry/fee-bump) where each stage returns a discriminated union so errors are caught and typed at the stage they occur. SimulationFailed carries the raw result; ResourceAdjustmentFailed carries the computed fee and exceeded limit — that's what makes error surfacing actionable rather than generic.

Simulation: simulateTransaction via RPC, auto-adjust sorobanData with a configurable safety multiplier (default 110%, overridable per call).

Fee-bump: Configurable fee-bump source account independent of inner tx source, triggered on initial submit or txInsufficientFee response.

Retry: Exponential backoff with jitter on transient errors (txTooEarly, txTooLate, timeouts), hard stop on terminal errors (txBadAuth, txBadSeq, non-resource simulation failures). Error type distinguishes retryable from terminal so callers know whether to show a spinner or an error state.

Types: PipelineResult<T>, PipelineError discriminated union, PipelineOptions — all exported, no any on public API surface, named exports only for tree-shaking.

Tests: XDR payload validation, simulation mock (success + TRY_AGAIN_LATER + hard failure), fee adjustment, fee-bump wrapping, retry count, terminal error non-retry.

Draft PR after core pipeline + types for early feedback on the error model before retry and fee-bump layers go in.

[grantfox-oss]

🦊 GrantFox — @DSOTec 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 #68)
2. Your PR will be reviewed by the trustflow-protocol maintainers

Good luck! Track your progress on GrantFox.