Replace Mock API Layer with Real Soroban Contract Calls

[pragmaticAweds]

Context & Impact

The current API layer in src/lib/api.ts contains mock/placeholder implementations instead of real Soroban contract invocations. Every contract call — stream creation, withdrawal, distribution — returns fabricated data rather than interacting with the deployed smart contracts. This means the entire app is non-functional against a live or testnet blockchain.

Why this matters: This is the single biggest blocker to production readiness. Without real contract calls, the platform cannot process any actual payments, streams, or distributions. Users interacting with the app are getting fake responses, and no on-chain transactions are occurring.

Scope

• Replace all mock implementations in src/lib/api.ts with real Soroban RPC calls using the SDK (@fundable/sdk)
• Wire up PaymentStreamClient for stream creation, withdrawal, pause, resume, and cancel operations
• Wire up DistributorClient for equal and weighted token distribution
• Ensure all contract calls go through proper transaction signing via StellarWalletProvider
• Remove all hardcoded/mock response data
• Handle Soroban simulation before submitting transactions

Implementation Guidelines

• Use the existing SDK clients in packages/sdk/src/ — PaymentStreamClient.ts and DistributorClient.ts
• All contract invocations must be simulated before submission (simulateTransaction)
• Transaction signing must use the wallet kit from StellarWalletProvider
• Maintain the same function signatures so hooks (use-create-stream.ts, use-streams.ts, etc.) continue to work
• Use the existing error classes in services/errors.ts to wrap contract errors meaningfully
• Test against Stellar Testnet with deployed contract IDs from environment variables

Acceptance Criteria

• All mock implementations in src/lib/api.ts are replaced with real Soroban contract calls
• createStream() submits a real transaction and returns the on-chain stream ID
• getStreams() fetches actual stream data from the payment-stream contract
• withdraw(), pause(), resume(), cancel() invoke the correct contract methods
• distribute() calls the distributor contract for both equal and weighted distributions
• All transactions are signed via the connected wallet
• Transactions are simulated before submission to catch errors early
• Error responses from the contract are mapped to the appropriate custom error classes
• No mock data or placeholder responses remain in the codebase

Getting Started

1. Read the existing mock layer: src/lib/api.ts
2. Study the SDK clients: packages/sdk/src/PaymentStreamClient.ts and DistributorClient.ts
3. Review how the wallet provider exposes signing: src/providers/StellarWalletProvider.tsx
4. Review the generated contract bindings: packages/sdk/src/generated/
5. Replace each mock function with real SDK calls, starting with createStream
6. Test each operation on Stellar Testnet using Freighter wallet
7. Verify error handling by simulating failures (wrong address, insufficient funds, etc.)

---

PR Submission Guide

This section applies to every PR for this issue. Follow it exactly.

Before You Start

• Pull the latest main branch: git checkout main && git pull origin main
• Create your feature branch from main: git checkout -b feat/<issue-number>-replace-mock-api

While Working

• Make atomic commits — one concern per commit, each commit must build
• Use Conventional Commits: feat(scope): description, fix(scope): description
• Keep your branch up to date: git pull origin main --rebase regularly

Before Submitting the PR

• Pull latest main and rebase: git checkout main && git pull origin main && git checkout <your-branch> && git rebase main
• Ensure the build passes: pnpm build
• Ensure linting passes: pnpm lint
• Record a screen recording of your implementation showing the feature/fix working in the browser. Attach it to the PR.

PR Requirements

• Link this issue in your PR description using Closes #<issue-number>
• Fill out the full PR template — Summary, What Was Implemented, Implementation Details, How to Test
• Attach your screen recording demonstrating the implementation
• Request a review from a maintainer

PRs without a screen recording or without a linked issue will not be reviewed.

[dinahmaccodes]

@dinahmaccodes has applied to work on this issue as part of the Stellar Wave Program's 3rd wave.

Hello, I can work on this well and do it properly. Can i work on it?

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

[drips-wave]

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

🧑‍💻 @dinahmaccodes: 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 🌊