Utilitycoder · Sep 11, 2026 · Sep 10, 2026 · Sep 10, 2026 · coderabbitai · Sep 11, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,28 @@
 
 All notable changes to `@fundable/sdk` are documented here.
 
+## 0.2.0
+
+Mainnet-readiness integration release.
+
+### Added
+
+- authenticated Stellar wallet sessions for the Fundable backend;
+- typed sponsorship quote, build, authorization signing, and idempotent submit;
+- explicit sponsorship fee and authorization-expiration fields;
+- canonical Router stream metadata, status, owner, and core-ID reads;
+- first-class Lockup cancellation, status, and amount reads;
+- immutable Stream NFT transferability reads;
+- Router Flow initial funding and per-stream transferability inputs.
+
+### Changed
+
+- regenerated Flow, Lockup, Router, and Stream NFT bindings from the verified
+  mainnet-readiness release artifacts;
+- distinguished confirmed Stream NFT token IDs from transaction hashes in
+  sponsorship results;
+- marked the custom Fundable Paymaster client as deprecated and migration-only.
+
 ## 0.1.0
 
 First stable Fundable SDK release.

diff --git a/README.md b/README.md
@@ -17,6 +17,7 @@ Detailed, GitBook-ready guides live in [`docs/`](./docs):
 - [Configuration](./docs/configuration.md)
 - [Flow streams](./docs/flows.md)
 - [Transactions and authorization](./docs/transactions.md)
+- [Sponsored transactions](./docs/sponsorship.md)
 - [Example implementations](./docs/examples.md)
 - [Backend indexing](./docs/backend-indexing.md)
 - [Multichain architecture](./docs/multichain-architecture.md)
@@ -41,13 +42,12 @@ const fundable = createFundableClient({
   network: "testnet",
   rpcUrl: "https://soroban-testnet.stellar.org",
   networkPassphrase: "Test SDF Network ; September 2015",
-  contracts: {
-    flow: "C...",
-  },
+  contracts: { flow: "C...", router: "C...", streamNft: "C..." },
+  sponsorship: { backendUrl: "https://api.fundable.finance" },
 });
 ```
 
-The top-level client exposes Flow, Router, Stream NFT, and Paymaster capability
+The top-level client exposes Flow, Router, Stream NFT, and sponsorship capability
 groups when their contract IDs are configured:
 
 ```ts
@@ -88,8 +88,10 @@ console.log(sent.result);
 ```
 
 Fundable's NFT-backed creation workflow goes through `fundable.router`. The
-`fundable.streamNft` and `fundable.paymaster` groups expose NFT ownership and
-bounded fee-forwarding operations. See the capability guide for examples.
+`fundable.streamNft` group exposes NFT ownership and transfer policy.
+`fundable.sponsorship` implements the production backend-mediated fee flow.
+The legacy `fundable.paymaster` group is deprecated and retained only for
+migration compatibility.
 
 ## Multichain boundary
 

diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
@@ -5,10 +5,11 @@
 - [Configuration](configuration.md)
 - [Flow streams](flows.md)
 - [Transactions and authorization](transactions.md)
+- [Sponsored transactions](sponsorship.md)
 - [Example implementations](examples.md)
 - [Backend indexing](backend-indexing.md)
 - [Multichain architecture](multichain-architecture.md)
-- [Router, Stream NFT, and Paymaster](router-paymaster.md)
+- [Router, Stream NFT, and legacy Paymaster](router-paymaster.md)
 - [API reference](api-reference.md)
 - [Generated Stellar bindings](generated-bindings.md)
 - [Troubleshooting and versioning](troubleshooting-and-versioning.md)
diff --git a/docs/api-reference.md b/docs/api-reference.md
@@ -16,9 +16,11 @@ import type { StellarFundableClientConfig } from "@fundable/sdk/stellar";
 | Property | Availability |
 | --- | --- |
 | `flows` | Always present; `contracts.flow` is required. |
+| `lockups` | Present when `contracts.lockup` is configured. |
 | `router` | Present when `contracts.router` is configured. |
 | `streamNft` | Present when `contracts.streamNft` is configured. |
-| `paymaster` | Present when `contracts.paymaster` is configured. |
+| `sponsorship` | Present when `sponsorship.backendUrl` is configured. |
+| `paymaster` | Deprecated; migration-only when `contracts.paymaster` is configured. |
 
 ## Flow client
 
@@ -40,6 +42,17 @@ import type { StellarFundableClientConfig } from "@fundable/sdk/stellar";
 | `createLockup` | Assembled transaction returning Stream NFT token ID. |
 | `withdraw` | Assembled transaction for an amount and token ID. |
 | `withdrawMax` | Assembled transaction returning the withdrawn amount. |
+| `ownerOf`, `statusOf`, `coreStreamId` | Canonical reads keyed by NFT token ID. |
+| `getStream` | Owner, type, status, transferability, token ID, and core ID. |
+| `voidFlow` | NFT-owner Flow void transaction. |
+
+## Lockup client
+
+| Method | Result |
+| --- | --- |
+| `cancel`, `renounce` | Sender-authorized Lockup transactions using a core stream ID. |
+| `statusOf`, `isCancelable` | Current Lockup lifecycle and cancellation state. |
+| `withdrawableAmount`, `refundableAmount` | Current amounts as `bigint`. |
 
 ## Stream NFT client
 
@@ -48,8 +61,22 @@ import type { StellarFundableClientConfig } from "@fundable/sdk/stellar";
 | `ownerOf` | Owner Stellar address. |
 | `balanceOf` | Number of Stream NFTs owned as `bigint`. |
 | `getStreamData` | `{ tokenId, streamId, streamKind }`. |
+| `isTransferable` | Immutable on-chain transfer policy. |
 | `transfer` | Assembled transfer transaction. |
 
+## Sponsorship client
+
+| Method | Result |
+| --- | --- |
+| `authenticate` | Signed-wallet backend session. |
+| `quote` | Fee token, estimate, maximum, and conversion rate. |
+| `build` | FeeForwarder transaction, user auth entry, and expiration. |
+| `submit` | Durable IDs, status, transaction hash, and confirmed NFT token ID. |
+| `isBuildExpired` | Whether a build must be rebuilt before signing or submission. |
+
+`fundable.signSponsorshipAuthorization(build)` signs the backend-issued user
+authorization entry with the configured wallet callback.
+
 ## Paymaster client
 
 | Method | Result |
@@ -89,6 +116,7 @@ try {
 
 The stable error codes are `INVALID_ARGUMENT`, `INVALID_CONFIGURATION`,
 `UNSUPPORTED_CHAIN`, `UNSUPPORTED_CAPABILITY`, `SIMULATION_FAILED`,
-`TRANSACTION_FAILED`, and `RPC_UNAVAILABLE`. The underlying failure may be
+`TRANSACTION_FAILED`, `RPC_UNAVAILABLE`, `API_REQUEST_FAILED`,
+`AUTHENTICATION_REQUIRED`, and `AUTHORIZATION_EXPIRED`. The underlying failure may be
 available as `error.cause`; do not display raw provider responses to end users
 without filtering sensitive data.
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -15,8 +15,8 @@ const fundable = createFundableClient({
     flow: process.env.FUNDABLE_FLOW_CONTRACT!,
     router: process.env.FUNDABLE_ROUTER_CONTRACT,
     streamNft: process.env.FUNDABLE_STREAM_NFT_CONTRACT,
-    paymaster: process.env.FUNDABLE_PAYMASTER_CONTRACT,
   },
+  sponsorship: { backendUrl: process.env.FUNDABLE_BACKEND_URL! },
   publicKey: connectedAccount,
   signTransaction: wallet.signTransaction,
   signAuthEntry: wallet.signAuthEntry,
@@ -39,8 +39,8 @@ cross-network signing errors.
 
 ## Optional capabilities
 
-`router`, `streamNft`, and `paymaster` are only present on the client when the
-matching contract ID is configured:
+`router`, `streamNft`, and `sponsorship` are only present on the client when
+their corresponding contract ID or backend URL is configured:
 
 ```ts
 if (!fundable.router) {
@@ -51,6 +51,10 @@ if (!fundable.router) {
 This makes a missing deployment explicit instead of sending a transaction to
 an invented or stale address.
 
+The custom `paymaster` contract option is deprecated and must not be used for
+production sponsorship. Configure `sponsorship.backendUrl` to use the
+backend-validated OpenZeppelin FeeForwarder flow.
+
 ## Signing callbacks
 
 `publicKey`, `signTransaction`, and `signAuthEntry` are optional for read-only

diff --git a/docs/generated-bindings.md b/docs/generated-bindings.md
@@ -70,3 +70,21 @@ bindings are compiled into the SDK behind chain-neutral high-level clients.
 
 `0.1.0-alpha.3` adds the high-level Lockup Router mapping without changing the
 generated bindings or contract artifacts, so it retains this exact provenance.
+
+## Mainnet-readiness release provenance
+
+- Contract commit: `62dfc41ac8c1fa48d66c5fe5e9c7e98f9e4f9529`
+- Stellar CLI: `stellar 27.0.0`
+
+Reproducible WASM SHA-256 values:
+
+| Contract | SHA-256 |
+| --- | --- |
+| Flow | `6201c10afc509b53bf3a9bb307730ee996accdcc4f17864126bbd8aa576dbee6` |
+| Lockup | `500f152a8ffb8126e36af6df149eee5712c9a575b9c1979142de2619fe8920d3` |
+| Router | `c1ddde9e7679fd1068523a7994a7fbc1390a0a98526ccfba0a317886f36b6f09` |
+| Stream NFT | `0e6440a0a2108b254459988c214bcb225ddd838fabdb7623450a65ccbdeddb63` |
+
+The SDK `0.2.0` bindings were generated from the four reproducible release
+artifacts with the corresponding `pnpm generate:* -- /absolute/path.wasm`
+commands. The transitional Paymaster was intentionally not regenerated.
diff --git a/docs/router-paymaster.md b/docs/router-paymaster.md
@@ -1,4 +1,8 @@
-# Router, Stream NFT, and Paymaster development
+# Router, Stream NFT, and legacy Paymaster development
+
+> The custom Fundable Paymaster is deprecated and retained for migration only.
+> Production applications must use the backend-mediated sponsorship API
+> documented in [Sponsored transactions](sponsorship.md).
 
 These capabilities are available from `0.1.0-alpha.2`. Router Lockup creation
 is available from `0.1.0-alpha.3`.

diff --git a/docs/sponsorship.md b/docs/sponsorship.md
@@ -0,0 +1,38 @@
+# Sponsored transactions
+
+Production sponsorship uses Fundable's authenticated backend and the native
+OpenZeppelin FeeForwarder flow. The browser prepares the intended Router or
+engine call; the backend chooses and validates the fee token, relayer, target,
+function, arguments, fee bounds, and authorization tree.
+
+```ts
+await fundable.sponsorship!.authenticate(
+  connectedAccount,
+  "TESTNET",
+  wallet.signMessage,
+);
+
+const unsignedXdr = transaction.toXDR();
+const quote = await fundable.sponsorship!.quote(unsignedXdr, "TESTNET");
+// Display quote.feeToken, estimatedFeeUi, maximumFeeUi, and the action.
+
+let build = await fundable.sponsorship!.build(unsignedXdr, "TESTNET");
+if (fundable.sponsorship!.isBuildExpired(build)) {
+  build = await fundable.sponsorship!.build(unsignedXdr, "TESTNET");
+}
+
+const signedAuthEntry =
+  await fundable.signSponsorshipAuthorization(build);
+const result = await fundable.sponsorship!.submit({
+  build,
+  signedAuthEntry,
+  network: "TESTNET",
+  intent,
+  idempotencyKey: crypto.randomUUID(),
+});
+```
+
+Use `result.streamTokenId` as the public stream identifier only after it is
+present in a confirmed backend result. `result.transactionHash` identifies the
+submission and must never be substituted for a stream ID. If authorization
+expires, rebuild and show the updated fee before asking the wallet to sign.
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
     "name": "@fundable/sdk",
-    "version": "0.1.0",
+    "version": "0.2.0",
     "private": false,
     "description": "Multichain TypeScript SDK for Fundable Protocol; Stellar adapter included",
     "license": "MIT",
@@ -46,6 +46,7 @@
         "build": "pnpm clean && tsc",
         "dev": "tsc --watch",
         "generate:flow": "node scripts/generate-stellar-binding.mjs flow",
+        "generate:lockup": "node scripts/generate-stellar-binding.mjs lockup",
         "generate:router": "node scripts/generate-stellar-binding.mjs router",
         "generate:stream-nft": "node scripts/generate-stellar-binding.mjs stream_nft",
         "generate:paymaster": "node scripts/generate-stellar-binding.mjs paymaster",

diff --git a/src/core/errors.ts b/src/core/errors.ts
@@ -8,6 +8,9 @@ export const FUNDABLE_ERROR_CODES = {
   SIMULATION_FAILED: "SIMULATION_FAILED",
   TRANSACTION_FAILED: "TRANSACTION_FAILED",
   RPC_UNAVAILABLE: "RPC_UNAVAILABLE",
+  API_REQUEST_FAILED: "API_REQUEST_FAILED",
+  AUTHENTICATION_REQUIRED: "AUTHENTICATION_REQUIRED",
+  AUTHORIZATION_EXPIRED: "AUTHORIZATION_EXPIRED",
 } as const;
 
 export type FundableErrorCode =

diff --git a/src/core/types.ts b/src/core/types.ts
@@ -18,6 +18,17 @@ export const FLOW_STATUSES = {
 export type FlowStatus =
   (typeof FLOW_STATUSES)[keyof typeof FLOW_STATUSES];
 
+export const LOCKUP_STATUSES = {
+  PENDING: "pending",
+  STREAMING: "streaming",
+  SETTLED: "settled",
+  CANCELED: "canceled",
+  DEPLETED: "depleted",
+} as const;
+
+export type LockupStatus =
+  (typeof LOCKUP_STATUSES)[keyof typeof LOCKUP_STATUSES];
+
 export interface TokenReference {
   address: string;
   decimals: number;
@@ -43,6 +54,8 @@ export interface CreateFlowInput {
   token: TokenReference;
   ratePerSecond: bigint;
   startTime?: bigint | Date;
+  initialAmount?: bigint;
+  transferable?: boolean;
 }
 
 export interface CreateAndDepositFlowInput extends CreateFlowInput {
@@ -61,6 +74,7 @@ export interface CreateLockupInput {
   cliffUnlockAmount?: bigint;
   granularitySeconds?: bigint;
   cancelable?: boolean;
+  transferable?: boolean;
 }
 
 export interface FlowAmountInput {
@@ -97,13 +111,39 @@ export const STREAM_KINDS = {
 
 export type StreamKind = (typeof STREAM_KINDS)[keyof typeof STREAM_KINDS];
 
+export const CANONICAL_STREAM_STATUSES = {
+  PENDING: "pending",
+  ACTIVE: "active",
+  PAUSED: "paused",
+  CANCELED: "canceled",
+  COMPLETED: "completed",
+  FAILED: "failed",
+} as const;
+
+export type CanonicalStreamStatus =
+  (typeof CANONICAL_STREAM_STATUSES)[keyof typeof CANONICAL_STREAM_STATUSES];
+
+export interface StreamMetadata {
+  tokenId: string;
+  coreStreamId: string;
+  streamKind: StreamKind;
+  status: CanonicalStreamStatus;
+  owner: string;
+  transferable: boolean;
+}
+
 export interface RouterWithdrawInput {
   tokenId: string | bigint;
   caller: string;
   to: string;
   amount: bigint;
 }
 
+export interface LockupActorInput {
+  streamId: string | bigint;
+  sender: string;
+}
+
 export interface StreamNftRecord {
   tokenId: string;
   streamId: string;