Spike: Define retry/resilience policy and auth/session + multisig state lifecycle

[meshackyaro]

Description

Two related resilience/lifecycle gaps:

1. Dead retry code. src/utils/retry.ts implements a generic retry() helper, but it is never called anywhere in src/ — no Soroban RPC call (stellar/rpc.ts's simulateAndAssemble) and no backend fetch (auth/challenge.ts) has any retry, timeout, or handling of transient errors (rate limits, simulation TRY_AGAIN_LATER states). The README's own roadmap lists "Auto-retry logic for RPC endpoints" as unimplemented.

2. Incomplete session/multisig state. auth/session.ts persists the auth token to localStorage only — silently a no-op outside a browser, so Node.js/CLI/backend integrators get no persistence at all — and the token carries no expiry metadata, so nothing re-triggers the challenge flow on a 401. Separately, MultiSigEscrowClient (src/escrow/multisig.ts) keeps in-progress multisig operation state in an in-memory Map, but per the README, signers are expected to "submit their signed XDR independently" — which can't work if the state coordinating them only exists in one process's memory.

Component

SDK

Difficulty

🟣 Spike — investigation required, scope not yet defined

Tasks

• Define where retry() should actually apply, respecting idempotency differences between simulate (safe to retry) and submit (not safely retryable)
• Design a Node-vs-browser-aware session storage strategy and a token-expiry/401 re-auth flow
• Design where multisig operation state should live so independent signer processes can coordinate (backend API? on-chain? a relay service?)
• Prototype the chosen retry policy and multisig state strategy

Acceptance Criteria

• A written recommendation for the retry policy, with idempotency rules per call type
• A written recommendation for session storage and token lifecycle across Node/browser
• A written recommendation for multisig operation-state coordination
• Follow-up implementation issue(s) filed
• Any blocking unknowns flagged

Estimated Time

1-2 days (time-boxed spike)

[bbjiggy]

Hi Maintainer, I’d like to take on this spike because it combines SDK reliability with some important lifecycle and architecture questions. I’d focus first on validating the failure modes and idempotency boundaries, then prototype the smallest practical solution.

Approach

Retry policy

• Audit retry.ts, stellar/rpc.ts, and auth/challenge.ts.
• Apply bounded exponential backoff + jitter to transient, safe-to-retry operations such as simulation.
• Explicitly avoid blind retries for transaction submission.
• Document retryable errors, idempotency rules, and configuration options.

Session lifecycle

• Introduce a storage abstraction that works across browser and Node environments.
• Define token expiry/401 handling so expired sessions trigger re-authentication.
• Keep storage injectable so Node/backend users can provide their own secure persistence.
• Flag any backend limitations around token expiry as blocking unknowns.

Multisig state

• Trace what state must be shared between independent signers.
• Evaluate backend persistence, relay service, and on-chain approaches.
• My initial preference is backend/API coordination, while keeping private keys and signing authority entirely client-side.
• Prototype cross-process operation/signature coordination.

Deliverables

• Written recommendations for retry, session lifecycle, and multisig coordination.
• Prototypes validating the chosen approaches.
• Follow-up implementation issue(s).
• A clear list of assumptions and blocking unknowns.

I’d keep the spike focused on resolving the architectural questions and producing implementation-ready recommendations rather than prematurely expanding the SDK API.

[grantfox-oss]

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

Good luck! Track your progress on GrantFox.