[SDK] TypeScript SDK Client-Side Signing & Transaction Builder Extensions

[blurbeast]

Overview & Background

packages/flowfi-sdk provides basic interfaces and generated bindings, but lacks high-level transaction construction, client-side wallet signing abstractions, and simulation pipelines. For third-party dApps, payroll providers, and automated bots to integrate with FlowFi without routing through the FlowFi backend API, the SDK needs full standalone transaction building capabilities.

---

Detailed Problem Statement

1. High Barrier for Third-Party Integrations:
   • External developers must manually build raw Soroban XDR operations and handle footprint resource estimation.
2. Tight Backend Coupling:
   • Currently, dApps are forced to depend on FlowFi's central backend API for stream operations rather than communicating directly with the Stellar ledger.

---

Technical Specification & Architecture

1. High-Level FlowFiClient API

Implement in packages/flowfi-sdk/src/client.ts:

export class FlowFiClient {
  constructor(config: { rpcUrl: string; networkPassphrase: string; contractId: string });

  async createStream(params: CreateStreamParams, signer: Signer): Promise<StreamResult>;
  async batchWithdraw(streamIds: bigint[], signer: Signer): Promise<WithdrawResult>;
  async topUpStream(streamId: bigint, amount: bigint, signer: Signer): Promise<void>;
  async cancelStream(streamId: bigint, signer: Signer): Promise<void>;
  async getStream(streamId: bigint): Promise<StreamDetails>;
  async getClaimableAmount(streamId: bigint): Promise<bigint>;
}

2. Modular Signer Adapters

Implement in packages/flowfi-sdk/src/signers/:

• FreighterSigner: In-browser extension signing.
• KeypairSigner: Node.js secret key signing for automated payroll daemons.
• CustomSigner: Generic interface for WalletConnect / hardware wallets.

3. Automatic Resource Simulation & Fee Padding

• Automatically invokes simulateTransaction on Soroban RPC.
• Attaches computed authorization entries and foot-print keys.
• Adds configurable safety resource fee buffer.

---

Target Files

• packages/flowfi-sdk/src/client.ts
• packages/flowfi-sdk/src/builder.ts
• packages/flowfi-sdk/src/signers/index.ts
• packages/flowfi-sdk/README.md
• packages/flowfi-sdk/tests/client.test.ts

---

Acceptance Criteria

• External dApps can create, withdraw, top-up, and cancel streams with 3 lines of TypeScript code.
• Works seamlessly in both browser and Node.js environments.
• Includes comprehensive mock tests for transaction building and simulation.
• Complete SDK documentation and quickstart examples added to SDK README.

[MarcusDavidG]

@MarcusDavidG has applied to work on this issue as part of the Stellar Wave Program's 9th wave.

I can handle this issue and will like to work on it, Please assign thank you.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @MarcusDavidG to this issue.

[Fran6ix-coder]

@Fran6ix-coder has applied to work on this issue as part of the Stellar Wave Program's 9th wave.

I’ve taken the time to understand the issue and its intended functionality. I’d be happy to work on this and provide an implementation that is cleanly integrated, properly tested, and considerate of existing functionality.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Fran6ix-coder to this issue.

[drips-wave]

Congratulations, @MarcusDavidG! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on September 30, 2026.

🧑‍💻 @MarcusDavidG: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox!

@MarcusDavidG's PR #1459 was approved and merged by @blurbeast.

🏆 @MarcusDavidG: You earned 40 FoxPoints for this contribution! Your current tier: Builder (1,748 total points). Track your full progress on GrantFox.

👏 Great work, @MarcusDavidG! Keep contributing to LabsCrypt.

[drips-wave]

This issue has been completed by @MarcusDavidG as part of the Stellar Wave Program's 9th Wave 🥳

😎 @MarcusDavidG: You earned 200 Points for completing this issue! After the current Wave ends, you'll be eligible for a percentage of the Wave's reward pool based on the percentage of total points you've earned. Learn more here. You can also Leave a review to share your experience working on this issue.

🧑‍💻 Repo maintainers: How'd the contributor do? Leave a review to share your experience working with them.