+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| File | ++ | Statements | ++ | Branches | ++ | Functions | ++ | Lines | ++ |
|---|---|---|---|---|---|---|---|---|---|
| src | +
+
+ |
+ 96.26% | +1081/1123 | +89.98% | +728/809 | +98.28% | +172/175 | +98.1% | +1033/1053 | +
| src/adapters | +
+
+ |
+ 92.4% | +73/79 | +74.41% | +64/86 | +93.75% | +15/16 | +92.2% | +71/77 | +
| src/dashboard | +
+
+ |
+ 94.61% | +158/167 | +91.94% | +194/211 | +100% | +20/20 | +96.37% | +133/138 | +
| src/nonce | +
+
+ |
+ 93.1% | +81/87 | +82.97% | +39/47 | +95% | +19/20 | +94.04% | +79/84 | +
| src/relayer | +
+
+ |
+ 77.72% | +164/211 | +65.45% | +72/110 | +83.33% | +30/36 | +80.8% | +160/198 | +
| src/types | +
+
+ |
+ 0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| File | ++ | Statements | ++ | Branches | ++ | Functions | ++ | Lines | ++ |
|---|---|---|---|---|---|---|---|---|---|
| index.ts | +
+
+ |
+ 0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +
| keypair.ts | +
+
+ |
+ 100% | +11/11 | +100% | +4/4 | +100% | +4/4 | +100% | +11/11 | +
| types.ts | +
+
+ |
+ 0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +
| walletconnect.ts | +
+
+ |
+ 91.17% | +62/68 | +73.17% | +60/82 | +91.66% | +11/12 | +90.9% | +60/66 | +
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 | + + + + + + + | export type { WalletAdapter, SignTransactionOptions } from './types.js';
+export { KeypairWalletAdapter } from './keypair.js';
+export {
+ WalletConnectAdapter,
+ type WalletConnectAdapterOptions,
+ type WalletConnectAppMetadata,
+} from './walletconnect.js';
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 | + + + + + + + +50x + + +34x + + + + + + +17x +2x +1x + + + + +1x +1x +1x + + +15x +15x + + + +1x + + + | import { Keypair, Transaction } from '@stellar/stellar-sdk';
+import type { WalletAdapter, SignTransactionOptions } from './types.js';
+
+/**
+ * Adapter wrapping a standard @stellar/stellar-sdk Keypair.
+ * Allows secret keys / keypairs to be used seamlessly through the WalletAdapter interface.
+ */
+export class KeypairWalletAdapter implements WalletAdapter {
+ constructor(private readonly keypair: Keypair) {}
+
+ getPublicKey(): string {
+ return this.keypair.publicKey();
+ }
+
+ async signTransaction(
+ tx: Transaction | string,
+ _opts?: SignTransactionOptions,
+ ): Promise<Transaction | string> {
+ if (typeof tx === 'string') {
+ if (!_opts?.networkPassphrase) {
+ throw new Error(
+ 'networkPassphrase is required when signing a raw XDR string. ' +
+ 'Pass { networkPassphrase } in the options argument.',
+ );
+ }
+ const parsedTx = new Transaction(tx, _opts.networkPassphrase);
+ parsedTx.sign(this.keypair);
+ return parsedTx.toXDR();
+ }
+
+ tx.sign(this.keypair);
+ return tx;
+ }
+
+ isConnected(): boolean {
+ return true;
+ }
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + | import type { Transaction } from '@stellar/stellar-sdk';
+
+/**
+ * Common sign transaction options.
+ */
+export interface SignTransactionOptions {
+ networkPassphrase?: string;
+ accountToSign?: string;
+}
+
+/**
+ * Generic wallet adapter interface for Stellar / Soroban transaction signing.
+ * Allows StreamFi SDK to support browser wallets, mobile wallets (WalletConnect v2),
+ * Freighter, Albedo, or direct Keypairs uniformly.
+ */
+export interface WalletAdapter {
+ /**
+ * Returns the Stellar public key / G-address of the active account.
+ */
+ getPublicKey(): Promise<string> | string;
+
+ /**
+ * Signs a Soroban Transaction instance or XDR string.
+ * Returns the signed Transaction instance or signed XDR string.
+ */
+ signTransaction(
+ tx: Transaction | string,
+ opts?: SignTransactionOptions,
+ ): Promise<Transaction | string>;
+
+ /**
+ * Checks if the wallet is currently connected.
+ */
+ isConnected?(): boolean;
+
+ /**
+ * Initiates wallet connection / session handshake if applicable.
+ * Returns the connected account public key.
+ */
+ connect?(): Promise<string>;
+
+ /**
+ * Disconnects the wallet session if applicable.
+ */
+ disconnect?(): Promise<void>;
+ chainId?: string;
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +7x + + + + + + + + + + + + + + + + + + +51x +51x + + + + +51x +6x +6x + + + + + +45x +45x +45x +51x +51x + + + + + + + + + + + + + +26x + + + + + + +11x +11x +3x + +8x + + + + + + +6x +1x + + +5x +5x + + + + + + + + + + + + +2x +1x +1x +1x + + + + + + +1x +1x + + + +1x + + + + + + + + + +10x +10x +5x + + + +10x + + + + + + +5x +5x +5x +4x + + + + + + + + +5x + + + + + + + + + + +1x +1x +1x + +1x + + + +1x +1x + + + + +1x + + + + + + + + + + + + +1x +1x + + + +1x + + + +1x + + + +1x + + + + + + + + +28x + + +26x +8x + + + + + +18x +18x +8x +8x +7x + + + + +11x +5x +5x + + +6x + + + | import { Transaction } from '@stellar/stellar-sdk';
+import type { WalletAdapter, SignTransactionOptions } from './types.js';
+
+export interface WalletConnectAppMetadata {
+ name: string;
+ description: string;
+ url: string;
+ icons: string[];
+}
+
+export interface WalletConnectSignClient {
+ connect?: (opts: unknown) => Promise<{ session?: WalletConnectSession; approval?: () => Promise<WalletConnectSession> }>;
+ disconnect?: (opts: unknown) => Promise<void>;
+ request?: (opts: unknown) => Promise<unknown>;
+ [key: string]: unknown;
+}
+
+export interface WalletConnectSession {
+ topic?: string;
+ account?: string;
+ namespaces?: Record<string, { accounts?: string[] }>;
+ accounts?: string[];
+ [key: string]: unknown;
+}
+
+export interface WalletConnectAdapterOptions {
+ /** WalletConnect v2 Project ID */
+ projectId?: string;
+ /**
+ * CAIP-2 chain identifier (e.g., 'stellar:pubnet', 'stellar:testnet').
+ * Must be one of: 'stellar:pubnet', 'stellar:testnet', 'stellar:local'.
+ * Defaults to 'stellar:pubnet'.
+ */
+ chainId?: string | undefined;
+ /** DApp metadata for WalletConnect modal/handshake */
+ metadata?: WalletConnectAppMetadata;
+ /** Optional pre-existing WalletConnect SignClient or provider instance */
+ client?: WalletConnectSignClient | unknown;
+ /** Optional active session object or mock session */
+ session?: WalletConnectSession | unknown;
+ /** Milliseconds to wait for the connect handshake before rejecting. Defaults to 30000. */
+ connectTimeoutMs?: number;
+}
+
+/**
+ * Exhaustive map of CAIP-2 identifiers this adapter accepts to their
+ * human-readable Stellar network names. Anything not in this map is
+ * rejected at construction time so an invalid chain ID never silently
+ * reaches the smart contract (fixes #157).
+ */
+const SUPPORTED_CAIP2_CHAINS: Readonly<Record<string, string>> = {
+ 'stellar:pubnet': 'mainnet',
+ 'stellar:testnet': 'testnet',
+ 'stellar:local': 'local',
+};
+
+/**
+ * Native WalletConnect v2 adapter for mobile and browser-based wallet integration.
+ * Supports Stellar / Soroban transaction signing via CAIP-2 RPC protocols.
+ */
+export class WalletConnectAdapter implements WalletAdapter {
+ private readonly projectId?: string | undefined;
+ public readonly chainId: string;
+ private readonly metadata?: WalletConnectAppMetadata | undefined;
+ private client: WalletConnectSignClient | null;
+ private session: WalletConnectSession | null;
+ private readonly connectTimeoutMs: number;
+
+ constructor(options: WalletConnectAdapterOptions = {}) {
+ this.projectId = options.projectId;
+ const chainId = options.chainId ?? 'stellar:pubnet';
+
+ // Validate the CAIP-2 chain identifier at construction time so callers
+ // get an immediate, descriptive error instead of a silent cross-chain
+ // payload submission later (fixes #157).
+ if (!(chainId in SUPPORTED_CAIP2_CHAINS)) {
+ const supported = Object.keys(SUPPORTED_CAIP2_CHAINS).join(', ');
+ throw new Error(
+ `WalletConnectAdapter: unsupported chainId '${chainId}'. ` +
+ `Supported chains: ${supported}.`,
+ );
+ }
+
+ this.chainId = chainId;
+ this.metadata = options.metadata;
+ this.client = (options.client as WalletConnectSignClient) ?? null;
+ this.session = (options.session as WalletConnectSession) ?? null;
+ this.connectTimeoutMs = options.connectTimeoutMs ?? 30000;
+ }
+
+ /**
+ * Set or update active session.
+ */
+ setSession(session: WalletConnectSession | unknown): void {
+ this.session = (session as WalletConnectSession) ?? null;
+ }
+
+ /**
+ * Returns true if an active WalletConnect session exists.
+ */
+ isConnected(): boolean {
+ return Boolean(this.session && this.getPublicKeyFromSession());
+ }
+
+ /**
+ * Gets active public key from session or throws error if not connected.
+ */
+ async getPublicKey(): Promise<string> {
+ const pubKey = this.getPublicKeyFromSession();
+ if (!pubKey) {
+ throw new Error('WalletConnect adapter is not connected. Call connect() first.');
+ }
+ return pubKey;
+ }
+
+ /**
+ * Connect to wallet via WalletConnect v2 handshake or pairing.
+ */
+ async connect(): Promise<string> {
+ if (this.isConnected()) {
+ return this.getPublicKey();
+ }
+
+ Eif (this.client && typeof this.client.connect === 'function') {
+ const connectResult = await this._withTimeout(
+ this.client.connect({
+ requiredNamespaces: {
+ stellar: {
+ methods: ['stellar_signTransaction', 'stellar_signXdr', 'soroban_signTransaction'],
+ chains: [this.chainId],
+ events: ['accountsChanged', 'chainChanged'],
+ },
+ },
+ }),
+ 'WalletConnect connect() handshake'
+ );
+
+ if (connectResult.session) {
+ this.session = connectResult.session;
+ } else Eif (connectResult.approval) {
+ this.session = await this._withTimeout(
+ connectResult.approval(),
+ 'WalletConnect approval()'
+ );
+ }
+ }
+
+ const pubKey = this.getPublicKeyFromSession();
+ Iif (!pubKey) {
+ throw new Error('Failed to establish WalletConnect session or obtain public key.');
+ }
+
+ return pubKey;
+ }
+
+ /**
+ * Races a network-bound promise against a timeout so that a dropped
+ * connection during the handshake rejects cleanly instead of hanging
+ * the init promise indefinitely (see #116).
+ */
+ private _withTimeout<T>(promise: Promise<T>, label: string): Promise<T> {
+ let timer: ReturnType<typeof setTimeout>;
+ const timeout = new Promise<never>((_, reject) => {
+ timer = setTimeout(() => {
+ reject(new Error(`${label} timed out after ${this.connectTimeoutMs}ms (possible network interruption)`));
+ }, this.connectTimeoutMs);
+ });
+
+ return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+ }
+
+ /**
+ * Disconnect the WalletConnect session.
+ */
+ async disconnect(): Promise<void> {
+ const session = this.session;
+ try {
+ if (this.client && session && typeof this.client.disconnect === 'function') {
+ await this._withTimeout(
+ this.client.disconnect({
+ topic: session.topic,
+ reason: { code: 6000, message: 'User disconnected' },
+ }),
+ 'WalletConnect disconnect()'
+ );
+ }
+ } finally {
+ this.session = null;
+ }
+ }
+
+ /**
+ * Sign a transaction using WalletConnect v2 RPC call.
+ */
+ async signTransaction(
+ tx: Transaction | string,
+ opts?: SignTransactionOptions,
+ ): Promise<Transaction | string> {
+ const pubKey = await this.getPublicKey();
+ const xdrString = typeof tx === 'string' ? tx : tx.toXDR();
+ const passphrase = opts?.networkPassphrase;
+
+ Iif (!this.client || typeof this.client.request !== 'function') {
+ throw new Error('WalletConnect SignClient request handler is not available.');
+ }
+
+ const topic = this.session?.topic;
+ Iif (!topic) {
+ throw new Error('No active WalletConnect session topic found.');
+ }
+
+ // Send RPC request via WalletConnect v2
+ const result = await this.client.request({
+ topic,
+ chainId: this.chainId,
+ request: {
+ method: 'stellar_signTransaction',
+ params: {
+ xdr: xdrString,
+ accountToSign: opts?.accountToSign ?? pubKey,
+ networkPassphrase: passphrase,
+ },
+ },
+ });
+
+ const resRecord = result as Record<string, unknown> | string | undefined;
+ const signedXdr = typeof resRecord === 'string'
+ ? resRecord
+ : (resRecord?.['signedXdr'] ?? resRecord?.['xdr'] ?? resRecord);
+
+ Iif (typeof signedXdr !== 'string') {
+ throw new Error('WalletConnect response did not return valid signed XDR.');
+ }
+
+ Iif (typeof tx === 'string') {
+ return signedXdr;
+ }
+
+ return new Transaction(signedXdr, passphrase ?? '');
+ }
+
+ /**
+ * Extract account public key from CAIP-10 address format in WalletConnect session.
+ * e.g., 'stellar:pubnet:GABC123...' -> 'GABC123...'
+ * Uses safe fallback handling with nullish coalescing to prevent crashes from malformed formats.
+ */
+ private getPublicKeyFromSession(): string | null {
+ if (!this.session) return null;
+
+ // Direct account string on session
+ if (typeof this.session.account === 'string') {
+ return this.session.account.includes(':')
+ ? this.session.account.split(':').at(-1) ?? this.session.account
+ : this.session.account;
+ }
+
+ // CAIP-10 accounts in namespaces
+ const namespaces = this.session.namespaces;
+ if (namespaces && namespaces['stellar'] && Array.isArray(namespaces['stellar'].accounts)) {
+ const fullAccount = namespaces['stellar'].accounts[0];
+ if (fullAccount) {
+ return fullAccount.includes(':') ? fullAccount.split(':').at(-1) ?? fullAccount : fullAccount;
+ }
+ }
+
+ // Fallback: direct accounts array
+ if (Array.isArray(this.session.accounts) && this.session.accounts[0]) {
+ const fullAccount = this.session.accounts[0];
+ return fullAccount.includes(':') ? fullAccount.split(':').at(-1) ?? fullAccount : fullAccount;
+ }
+
+ return null;
+ }
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 +461 +462 +463 +464 +465 +466 +467 +468 +469 +470 +471 +472 +473 +474 +475 +476 +477 +478 +479 +480 +481 +482 +483 +484 +485 +486 +487 +488 +489 +490 +491 +492 +493 +494 +495 +496 +497 +498 +499 +500 +501 +502 +503 +504 +505 +506 +507 +508 +509 +510 +511 +512 +513 +514 +515 +516 +517 +518 +519 +520 +521 +522 +523 +524 +525 +526 +527 +528 +529 +530 +531 +532 +533 +534 +535 +536 +537 +538 +539 +540 +541 +542 +543 +544 +545 +546 +547 +548 +549 +550 +551 +552 +553 +554 +555 +556 +557 | + + + + + + + + + + + + + +8x +8x + + +52x +52x + + + +52x + + + +16x +8x +8x + +8x + + + +16x +16x +8x +8x + + + + + + + + + + + + +52x +52x +52x + + + + +52x +52x + + + + + + + + +36x +36x + + + + + + + + +32x +32x + + + + + + + + +30x +30x + + + + + + + + +28x +6x + +22x +22x + + + + + + + + + + + +9x +4x +3x + + +5x +4x + + +2x +2x + + + + + + + + + + +29x +1x + +28x + + + +5x + + +23x + + + + + +23x +2x + + +23x + + + + + + + + + + + + + + + + +20x +1x + +19x +1x + + +18x +18x +1x + + + +17x +1x + + + + + +16x +16x +16x + +16x +20x + +20x +16x +16x + + +16x +19x + + + +19x + + + +19x +19x +13x +13x + +6x +1x + +5x +5x +5x + +3x +3x +3x +3x +3x + +3x + +3x + + + + + + + + + + + + + +2x + + + + + +16x + + + + +3x + + + +4x +4x + + +4x +4x + + + +98x +9x + + +89x +31x +2x + + + + + +58x +3x + + + + + +84x + + + + + + + + + + + + + + + + + + + + +8x + + + + + + + + +120x + +120x +7x +7x + + +113x +6x +6x + + +107x +562x +562x +8x +554x +4x + + +550x + + +550x +148x +148x +3x + + + + +550x +144x +144x +3x + + + + +550x +144x +144x +3x + + + + +550x +143x +143x +4x + + + + + +107x + + + + + + + + + +8x +8x +8x +8x + + + + + + + + + + + + + + + + +63x +4x + + +59x +59x +30x + + + + + + + +29x +29x +63x + +63x + + + + + + + + + + + + + + + +67x +1x + + +66x +66x +66x + +66x +66x + +66x + +66x +66x + + +66x + + + + +65x +65x + +65x +65x +65x + +65x + +65x +65x +65x +5x +4x + +1x + + + +65x +65x +4x +4x + + +61x +61x +3x + + + + + +3x + + +58x + + + + +58x + + + + + +65x +1x + + + + +65x + + + + + + + +100x + +100x +100x + +100x +1x + + +100x + + +100x + + + + + + + +9x +9x + + + + + + + +90x +90x + + + | import { StrKey } from '@stellar/stellar-sdk';
+import { bigintSafeStringify } from './utils.js';
+
+export interface SubmitOptions {
+ maxRetries?: number;
+ retryDelayMs?: number;
+ /** Max concurrent in-flight submissions. Default 10. */
+ concurrency?: number;
+ /** Max pending queue size before backpressure kicks in. Default 100. */
+ maxQueueSize?: number;
+ /** AbortSignal to cancel the submission while in-flight. */
+ signal?: AbortSignal;
+}
+
+const DEFAULT_CONCURRENCY = 10;
+const DEFAULT_MAX_QUEUE_SIZE = 100;
+
+class Semaphore {
+ private _running = 0;
+ private _queue: Array<() => void> = [];
+ private readonly _max: number;
+
+ constructor(max: number) {
+ this._max = max;
+ }
+
+ async acquire(): Promise<void> {
+ if (this._running < this._max) {
+ this._running++;
+ return;
+ }
+ return new Promise<void>(resolve => { this._queue.push(resolve); });
+ }
+
+ release(): void {
+ this._running--;
+ if (this._queue.length > 0) {
+ this._running++;
+ this._queue.shift()!();
+ }
+ }
+}
+
+/** Fluent builder for constructing stream configurations. */
+export class StreamBuilder {
+ private _token?: string | undefined;
+ private _sender?: string | undefined;
+ private _recipient?: string | undefined;
+ private _amount?: number | undefined;
+ private _ratePerSecond?: number | bigint | undefined;
+
+ private pendingQueue: Set<Record<string, unknown>> = new Set();
+ private activeTimers: Set<NodeJS.Timeout> = new Set();
+ private isDestroyed = false;
+ private _semaphore: Semaphore;
+ private _maxQueueSize: number;
+
+ constructor(options?: { concurrency?: number; maxQueueSize?: number }) {
+ this._semaphore = new Semaphore(options?.concurrency ?? DEFAULT_CONCURRENCY);
+ this._maxQueueSize = options?.maxQueueSize ?? DEFAULT_MAX_QUEUE_SIZE;
+ }
+
+ /**
+ * Sets the token contract address for the stream.
+ * @param address - The Soroban token contract address.
+ * @returns The builder instance for chaining.
+ */
+ token(address: string): this {
+ this._token = StreamBuilder._validateAddress(address, 'token');
+ return this;
+ }
+
+ /**
+ * Sets the sender address for the stream.
+ * @param address - The address that will send tokens.
+ * @returns The builder instance for chaining.
+ */
+ sender(address: string): this {
+ this._sender = StreamBuilder._validateAddress(address, 'sender');
+ return this;
+ }
+
+ /**
+ * Sets the recipient address for the stream.
+ * @param address - The address that will receive tokens.
+ * @returns The builder instance for chaining.
+ */
+ recipient(address: string): this {
+ this._recipient = StreamBuilder._validateAddress(address, 'recipient');
+ return this;
+ }
+
+ /**
+ * Sets the amount of tokens to stream.
+ * @param val - The amount in the token's smallest unit.
+ * @returns The builder instance for chaining.
+ */
+ amount(val: number): this {
+ if (!Number.isFinite(val) || val <= 0) {
+ throw new Error('Invalid StreamBuilder parameter: amount must be a positive finite number');
+ }
+ this._amount = val;
+ return this;
+ }
+
+ /**
+ * Sets the rate of tokens per second (in stroops).
+ * Accepts a number or bigint; bigint values are serialised to
+ * strings before network submission to avoid Safari/WebKit
+ * JSON.stringify quirks.
+ * @param val - The rate per second in stroops.
+ * @returns The builder instance for chaining.
+ */
+ ratePerSecond(val: number | bigint): this {
+ if (typeof val === 'bigint') {
+ if (val <= 0n) {
+ throw new Error('Invalid StreamBuilder parameter: ratePerSecond must be a positive value');
+ }
+ } else {
+ if (!Number.isFinite(val) || val <= 0) {
+ throw new Error('Invalid StreamBuilder parameter: ratePerSecond must be a positive finite number');
+ }
+ }
+ this._ratePerSecond = val;
+ return this;
+ }
+
+ /**
+ * Validates and produces the final stream configuration.
+ * Any bigint fields are converted to strings to guarantee safe
+ * serialisation across all browsers (Safari/WebKit included).
+ * @returns An object containing `token`, `sender`, `recipient`, `amount`, and optionally `ratePerSecond`.
+ * @throws {Error} If any required field (`token`, `sender`, `recipient`, `amount`) is missing or malformed.
+ */
+ build() {
+ if (this.isDestroyed) {
+ throw new Error('StreamBuilder has been destroyed');
+ }
+ if (this._token === undefined || this._token === null ||
+ this._sender === undefined || this._sender === null ||
+ this._recipient === undefined || this._recipient === null ||
+ this._amount === undefined || this._amount === null) {
+ throw new Error('Missing required parameters for StreamBuilder');
+ }
+
+ const config: Record<string, unknown> = {
+ token: this._token,
+ sender: this._sender,
+ recipient: this._recipient,
+ amount: this._amount,
+ };
+ if (this._ratePerSecond !== undefined && this._ratePerSecond !== null) {
+ config.ratePerSecond = this._ratePerSecond;
+ }
+
+ return bigintSafeStringify(config) as {
+ token: string;
+ sender: string;
+ recipient: string;
+ amount: number;
+ ratePerSecond?: string;
+ };
+ }
+
+ /**
+ * Submit built payload over network with automatic retries, payload queueing,
+ * and concurrency control to prevent degradation under high load.
+ */
+ async submit(
+ submitFn: (payload: Record<string, unknown>) => Promise<unknown>,
+ options: SubmitOptions = {}
+ ): Promise<unknown> {
+ if (this.isDestroyed) {
+ throw new Error('StreamBuilder has been destroyed');
+ }
+ if (typeof submitFn !== 'function') {
+ throw new Error('submitFn must be a valid function');
+ }
+
+ const { signal } = options;
+ if (signal?.aborted) {
+ throw new DOMException('Aborted', 'AbortError');
+ }
+
+ // Backpressure: reject if queue is full
+ if (this.pendingQueue.size >= this._maxQueueSize) {
+ throw new Error(
+ `StreamBuilder queue is full (${this._maxQueueSize} pending). ` +
+ 'Retry later or increase maxQueueSize.'
+ );
+ }
+
+ const payload = this.build();
+ const payloadRecord = payload as unknown as Record<string, unknown>;
+ this.pendingQueue.add(payloadRecord);
+
+ const maxRetries = options.maxRetries ?? 3;
+ const baseRetryDelay = options.retryDelayMs ?? 100;
+
+ await this._semaphore.acquire();
+ try {
+ let attempt = 0;
+ let lastError: Error | unknown;
+
+ while (attempt <= maxRetries) {
+ Iif (this.isDestroyed) {
+ throw new Error('StreamBuilder was destroyed during submission');
+ }
+
+ Iif (signal?.aborted) {
+ throw new DOMException('Aborted', 'AbortError');
+ }
+
+ try {
+ const result = await submitFn(payloadRecord);
+ this.pendingQueue.delete(payloadRecord);
+ return result;
+ } catch (err) {
+ if (signal?.aborted) {
+ throw new DOMException('Aborted', 'AbortError');
+ }
+ lastError = err;
+ attempt++;
+ if (attempt <= maxRetries) {
+ // Exponential backoff: delay doubles each retry
+ const delay = baseRetryDelay * Math.pow(2, attempt - 1);
+ await new Promise<void>((resolve, reject) => {
+ const timer = setTimeout(() => {
+ this.activeTimers.delete(timer);
+ resolve();
+ }, delay);
+ this.activeTimers.add(timer);
+
+ Iif (signal) {
+ const onAbort = () => {
+ clearTimeout(timer);
+ this.activeTimers.delete(timer);
+ signal.removeEventListener('abort', onAbort);
+ reject(new DOMException('Aborted', 'AbortError'));
+ };
+ signal.addEventListener('abort', onAbort, { once: true });
+ }
+ });
+ }
+ }
+ }
+
+ throw new Error(
+ `StreamBuilder network payload submission failed after ${maxRetries} retries without payload drop: ${
+ lastError instanceof Error ? lastError.message : String(lastError)
+ }`
+ );
+ } finally {
+ this._semaphore.release();
+ }
+ }
+
+ getPendingQueue(): Array<Record<string, unknown>> {
+ return [...this.pendingQueue];
+ }
+
+ cleanup(): void {
+ this.isDestroyed = true;
+ for (const timer of this.activeTimers) {
+ clearTimeout(timer);
+ }
+ this.activeTimers.clear();
+ this.pendingQueue.clear();
+ }
+
+ private static _validateAddress(address: string, field: string): string {
+ if (typeof address !== 'string' || address.trim().length === 0) {
+ throw new Error(`Invalid StreamBuilder parameter: ${field} must be a non-empty string`);
+ }
+
+ if (field === 'token') {
+ if (!StrKey.isValidContract(address)) {
+ throw new Error(
+ `Invalid StreamBuilder parameter: ${field} must be a valid Soroban contract ID (C-address), got "${address}"`,
+ );
+ }
+ } else {
+ // sender / recipient — must be valid Ed25519 public keys (G-addresses)
+ if (!StrKey.isValidEd25519PublicKey(address)) {
+ throw new Error(
+ `Invalid StreamBuilder parameter: ${field} must be a valid Stellar public key (G-address), got "${address}"`,
+ );
+ }
+ }
+
+ return address;
+ }
+}
+
+export interface BatchOperation {
+ method: string;
+ params: Record<string, unknown>;
+}
+
+export interface BatchExecuteOptions {
+ maxBatchSize?: number;
+}
+
+export interface BatchResult {
+ success: boolean;
+ operations: number;
+ xdr: string;
+ chunks?: number;
+ errors?: string[];
+}
+
+const DEFAULT_MAX_BATCH_SIZE = 50;
+
+/**
+ * Validate that the input is a non-null, non-empty array of objects.
+ * Also validates individual fields (token, sender, recipient) for address format correctness.
+ * Returns an array of error messages, or an empty array if valid.
+ * Mandatory client-side validation prevents invalid payloads from reaching the smart contract.
+ */
+function validatePayload(streams: unknown): string[] {
+ const errors: string[] = [];
+
+ if (streams === null || streams === undefined) {
+ errors.push('Batch payload cannot be null or undefined');
+ return errors;
+ }
+
+ if (!Array.isArray(streams)) {
+ errors.push('Batch payload must be an array');
+ return errors;
+ }
+
+ for (let i = 0; i < streams.length; i++) {
+ const item = streams[i];
+ if (item === null || item === undefined) {
+ errors.push(`Batch item at index ${i} cannot be null or undefined`);
+ } else if (typeof item !== 'object') {
+ errors.push(`Batch item at index ${i} must be an object, got ${typeof item}`);
+ } else {
+ // Field-level validation for known address-type fields
+ const obj = item as Record<string, unknown>;
+
+ // Validate token field — must be a valid Soroban contract ID (C-address)
+ if (obj.token !== undefined && obj.token !== null) {
+ const token = String(obj.token);
+ if (!StrKey.isValidContract(token)) {
+ errors.push(`Batch item at index ${i}: token must be a valid Soroban contract ID (C-address), got "${token}"`);
+ }
+ }
+
+ // Validate sender field — must be a valid Ed25519 public key (G-address)
+ if (obj.sender !== undefined && obj.sender !== null) {
+ const sender = String(obj.sender);
+ if (!StrKey.isValidEd25519PublicKey(sender)) {
+ errors.push(`Batch item at index ${i}: sender must be a valid Stellar public key (G-address), got "${sender}"`);
+ }
+ }
+
+ // Validate recipient field — must be a valid Ed25519 public key (G-address)
+ if (obj.recipient !== undefined && obj.recipient !== null) {
+ const recipient = String(obj.recipient);
+ if (!StrKey.isValidEd25519PublicKey(recipient)) {
+ errors.push(`Batch item at index ${i}: recipient must be a valid Stellar public key (G-address), got "${recipient}"`);
+ }
+ }
+
+ // Validate amount field — must be a positive finite number (where present)
+ if (obj.amount !== undefined && obj.amount !== null) {
+ const amount = Number(obj.amount);
+ if (!Number.isFinite(amount) || amount <= 0) {
+ errors.push(`Batch item at index ${i}: amount must be a positive finite number, got "${obj.amount}"`);
+ }
+ }
+ }
+ }
+
+ return errors;
+}
+
+interface PendingBatch {
+ operations: BatchOperation[];
+ signal?: AbortSignal | undefined;
+ resolve: (result: BatchResult) => void;
+}
+
+export class ConduitBatcher {
+ private static activeCallbacks: Set<() => void> = new Set();
+ private static isDestroyed = false;
+ private static batchQueue: PendingBatch[] = [];
+ private static processingBatch = false;
+
+ /**
+ * Bundle multiple stream operations into a single transaction.
+ *
+ * Any `bigint` fields inside the stream objects are converted to
+ * strings before further processing so that downstream
+ * `JSON.stringify` calls produce valid payloads on Safari / WebKit
+ * browsers (which serialise bigint as `{}` instead of throwing).
+ *
+ * Invalid payloads return `{ success: false, errors: [...] }` rather
+ * than throwing. Only a destroyed batcher causes a throw.
+ */
+ static execute(
+ streams: Record<string, unknown>[],
+ options?: BatchExecuteOptions,
+ ): BatchResult {
+ if (ConduitBatcher.isDestroyed) {
+ throw new Error('ConduitBatcher has been destroyed');
+ }
+
+ const validationErrors = validatePayload(streams);
+ if (validationErrors.length > 0) {
+ return {
+ success: false,
+ operations: 0,
+ xdr: '',
+ errors: validationErrors,
+ };
+ }
+
+ const sanitized = streams.map(bigintSafeStringify);
+ const resolvedMaxBatchSize = options?.maxBatchSize ?? DEFAULT_MAX_BATCH_SIZE;
+ const chunks = sanitized.length === 0 ? 0 : Math.ceil(sanitized.length / resolvedMaxBatchSize);
+
+ return {
+ success: true,
+ operations: sanitized.length,
+ xdr: 'AAAA...mock...batch...XDR',
+ chunks,
+ };
+ }
+
+ /**
+ * Asynchronously execute a batch with lifecycle tracking.
+ * Ensures pending callbacks are tracked and can be cleaned up on teardown.
+ */
+ static async executeAsync(
+ operations: BatchOperation[],
+ signal?: AbortSignal,
+ ): Promise<BatchResult> {
+ if (ConduitBatcher.isDestroyed) {
+ throw new Error('ConduitBatcher has been destroyed');
+ }
+
+ return new Promise<BatchResult>((resolve) => {
+ const entry: PendingBatch = { operations, signal, resolve };
+ ConduitBatcher.batchQueue.push(entry);
+
+ const cleanup = () => {
+ ConduitBatcher.activeCallbacks.delete(cleanup);
+ };
+ ConduitBatcher.activeCallbacks.add(cleanup);
+
+ Eif (!ConduitBatcher.processingBatch) {
+ ConduitBatcher.processQueue();
+ }
+
+ cleanup();
+ });
+ }
+
+ private static async processQueue(): Promise<void> {
+ Iif (ConduitBatcher.processingBatch || ConduitBatcher.isDestroyed) return;
+ ConduitBatcher.processingBatch = true;
+
+ while (ConduitBatcher.batchQueue.length > 0 && !ConduitBatcher.isDestroyed) {
+ const entry = ConduitBatcher.batchQueue.shift();
+ Iif (!entry) continue;
+
+ const { operations: ops, signal, resolve } = entry;
+
+ let cancelled = false;
+ const onAbort = () => { cancelled = true; };
+ if (signal) {
+ if (signal.aborted) {
+ cancelled = true;
+ } else {
+ signal.addEventListener('abort', onAbort);
+ }
+ }
+
+ try {
+ if (cancelled) {
+ resolve({ success: false, operations: 0, xdr: '', errors: ['Operation aborted'] });
+ continue;
+ }
+
+ const validationErrors = validatePayload(ops);
+ if (validationErrors.length > 0) {
+ resolve({
+ success: false,
+ operations: 0,
+ xdr: '',
+ errors: validationErrors,
+ });
+ continue;
+ }
+
+ const sanitized = ops.map(op => ({
+ ...op,
+ params: bigintSafeStringify(op.params),
+ }));
+
+ resolve({
+ success: true,
+ operations: sanitized.length,
+ xdr: "AAAA...mock...batch...XDR",
+ });
+ } finally {
+ if (signal && !cancelled) {
+ signal.removeEventListener('abort', onAbort);
+ }
+ }
+ }
+
+ ConduitBatcher.processingBatch = false;
+ }
+
+ /**
+ * Clean up all pending callbacks and reset state.
+ * Does NOT reset the destroyed flag — use destroy() for permanent teardown.
+ */
+ static cleanup(): void {
+ ConduitBatcher.processingBatch = false;
+
+ const oldQueue = ConduitBatcher.batchQueue;
+ ConduitBatcher.batchQueue = [];
+
+ oldQueue.forEach((entry) => {
+ entry.resolve({ success: false, operations: 0, xdr: '', errors: ['ConduitBatcher cleaned up'] });
+ });
+
+ for (const cb of ConduitBatcher.activeCallbacks) {
+ cb();
+ }
+ ConduitBatcher.activeCallbacks.clear();
+ }
+
+ /**
+ * Permanently destroy the batcher. All pending operations are rejected
+ * and subsequent calls to execute/executeAsync will throw.
+ */
+ static destroy(): void {
+ ConduitBatcher.isDestroyed = true;
+ ConduitBatcher.cleanup();
+ }
+
+ /**
+ * Full reset: clears destroyed flag and cleans up pending operations.
+ * Allows the batcher to be reused after destroy.
+ */
+ static reset(): void {
+ ConduitBatcher.isDestroyed = false;
+ ConduitBatcher.cleanup();
+ }
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 | + + + + + + + + + + + + + +15x + + + + + + + + + + + + + + + + + + + + + + + +11x +11x + +9x +9x + +9x +1x + + +8x +4x + + + + + + + + + + + + + + + +26x +9x + + +17x + + + + + +26x +3x + + +16x +16x +16x + + + + + + + + + + + + + + + + + + + + + + + +8x +8x +8x + + + + | import type { ConduitConfig } from './types/index.js';
+import type { WalletAdapter } from './adapters/types.js';
+import { DEFAULT_RPC } from './soroban.js';
+import { StreamsModule } from './streams.js';
+import { FactoryModule } from './factory.js';
+import { GovernorModule } from './governor.js';
+import { SUPPORTED_NETWORKS, UnsupportedChainError } from './errors.js';
+
+/**
+ * Map from CAIP-2 chain identifiers used by WalletConnect adapters to the
+ * canonical SDK network names they correspond to. Any CAIP-2 value not
+ * present here is considered unsupported and will be rejected by
+ * `assertWalletNetworkMatch`.
+ */
+const CAIP2_TO_NETWORK: Readonly<Record<string, string>> = {
+ 'stellar:pubnet': 'mainnet',
+ 'stellar:testnet': 'testnet',
+ 'stellar:local': 'local',
+};
+
+/**
+ * Validate that `wallet`'s network/chain matches the SDK's configured
+ * `network`. Throws `UnsupportedChainError` when:
+ *
+ * - The wallet exposes a `chainId` property (WalletConnect CAIP-2 string)
+ * that resolves to a network different from `expectedNetwork`.
+ * - The wallet exposes a `chainId` that is not in the supported CAIP-2
+ * mapping at all (i.e. it's an EVM chain or an unknown Stellar variant).
+ *
+ * If the wallet has no `chainId` the check is skipped — adapters that do
+ * not expose chain information (e.g. `KeypairWalletAdapter`) are always
+ * accepted, because they sign whatever transaction the SDK constructs and
+ * never independently specify a chain.
+ */
+function assertWalletNetworkMatch(
+ wallet: WalletAdapter,
+ expectedNetwork: string,
+): void {
+ const raw = wallet.chainId;
+ if (raw === undefined || raw === null) return;
+
+ const caip2 = String(raw);
+ const resolved = CAIP2_TO_NETWORK[caip2];
+
+ if (resolved === undefined) {
+ throw new UnsupportedChainError(caip2);
+ }
+
+ if (resolved !== expectedNetwork) {
+ throw new UnsupportedChainError(
+ `${caip2} (wallet is on '${resolved}' but client is configured for '${expectedNetwork}')`,
+ );
+ }
+}
+
+export class ConduitClient {
+ readonly streams: StreamsModule;
+ readonly factory: FactoryModule;
+ readonly governor: GovernorModule;
+
+ private readonly config: Required<Pick<ConduitConfig, 'network' | 'rpcUrl'>> & ConduitConfig;
+
+ constructor(config: ConduitConfig) {
+ // Validate the network immediately so developers get a clear error at
+ // initialisation time rather than an obscure RPC failure later.
+ if (!(SUPPORTED_NETWORKS as readonly string[]).includes(config.network)) {
+ throw new UnsupportedChainError(config.network);
+ }
+
+ this.config = {
+ ...config,
+ rpcUrl: config.rpcUrl ?? DEFAULT_RPC[config.network],
+ };
+
+ // If a wallet is provided at construction time, validate its chain too.
+ if (this.config.wallet) {
+ assertWalletNetworkMatch(this.config.wallet, this.config.network);
+ }
+
+ this.streams = new StreamsModule(this.config);
+ this.factory = new FactoryModule(this.config);
+ this.governor = new GovernorModule(this.config);
+ }
+
+ /**
+ * Dynamically attach or change the active wallet adapter.
+ *
+ * Validates that the new wallet's chain matches the client's configured
+ * network before accepting it — prevents silent cross-chain mismatches
+ * from reaching the smart contract (fixes #157).
+ *
+ * **Wallet propagation contract:**
+ * - {@link StreamsModule}: Updated immediately — all subsequent stream
+ * operations (create, withdraw, cancel, etc.) use the new wallet.
+ * - {@link FactoryModule}: NOT updated — this module is read-only and
+ * uses `config.keypair` for simulation fee sourcing. It does not hold
+ * a wallet reference and is unaffected by `setWallet()`.
+ * - {@link GovernorModule}: NOT updated — this module is read-only and
+ * uses `config.keypair` for simulation fee sourcing. It does not hold
+ * a wallet reference and is unaffected by `setWallet()`.
+ *
+ * @throws {UnsupportedChainError} if the wallet's `chainId` is on a
+ * different network than the one this client was initialised with.
+ */
+ setWallet(wallet: WalletAdapter): void {
+ assertWalletNetworkMatch(wallet, this.config.network);
+ this.config.wallet = wallet;
+ this.streams.setWallet(wallet);
+ }
+}
+
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 | + + + + + + +30x + | /** + * A syntactically valid Stellar G-address with no known keypair. Used only + * as the transaction source for read-only simulation calls when no real + * keypair is configured — Soroban's simulateTransaction doesn't require the + * source account to actually exist or sign anything for a read-only + * invocation. Never used to sign or move funds. + */ +export const ZERO_ADDR = 'GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWHF'; + |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| File | ++ | Statements | ++ | Branches | ++ | Functions | ++ | Lines | ++ |
|---|---|---|---|---|---|---|---|---|---|
| transaction-history.ts | +
+
+ |
+ 94.61% | +158/167 | +91.94% | +194/211 | +100% | +20/20 | +96.37% | +133/138 | +
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 +461 +462 +463 +464 +465 +466 +467 +468 +469 +470 +471 +472 +473 +474 +475 +476 +477 +478 +479 +480 +481 +482 +483 +484 +485 +486 +487 +488 +489 +490 +491 +492 +493 +494 +495 +496 +497 +498 +499 +500 +501 +502 +503 +504 +505 +506 +507 +508 +509 +510 +511 +512 +513 +514 +515 +516 +517 +518 +519 +520 +521 +522 +523 +524 +525 +526 +527 +528 +529 +530 +531 +532 +533 +534 +535 +536 +537 +538 +539 +540 +541 +542 +543 +544 +545 +546 +547 | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +1x + + +1x + + + + + + + + + + + + + + + + +23x + + + + + + + + + +23x + + + + + + + + + +23x + + +1x + + + + + + + +1x + + + + + + + + + +1x + + + + + + + + + + +262x +16x +15x +14x + + + +34x + +29x + +5x +3x +3x +3x +3x + +4x + + + +4x + + + + + + + +83x +80x +80x + + + + + + + +9x +7x +4x +2x +2x + +3x + + + + + + + + + + + + +38x + +30x + +30x +38x + + + +38x + +27x + +38x + + + + + + + + + + + + + + + + + + + + +24x + +24x +11x +11x + + + + + + + + +1x + + + + + + +24x + +15x +15x + +15x +27x +27x + + +19x +17x +17x + + +15x + + + + + + + +36x +36x +34x +34x +33x +33x + + + + + + + + + + + +41x + +41x +2x + + +39x + + + +5x + + +9x +9x + + + +9x + + + + + + + + + + + + + + + +4x + + + + + + +5x +5x + +5x +2x + +5x + + +5x + + +5x +2x + + +5x + + + + + + + + +5x +5x + + + +5x + + + + +8x + + + +8x + + +8x + + + +2x + + +1x + + + + + + + + + + + +45x +45x +45x + +45x +42x +42x +38x +38x + + +38x + +9x +27x + + + + + + + + +22x +22x + +22x +22x +22x +22x + +22x + + + + + + +3x +3x +3x + + + + + + + + + + +12x +12x + +12x +10x +7x +3x + + + + + + + + +8x +8x +5x +5x +4x + + + + +12x +12x +12x +12x + +10x +10x +10x +12x +12x + +12x +12x + +12x + + + + + + +7x +7x +4x +4x +4x + + | /**
+ * Framework-agnostic state model for the Transaction History view.
+ *
+ * ## Why this module exists (#136 / #103)
+ *
+ * The Transaction History component crashed immediately on render because its
+ * state hook read variables that were never initialised:
+ *
+ * ```ts
+ * // BROKEN — `transactions` and `filters` are `undefined` on first render
+ * const [state, setState] = useState<HistoryState>();
+ * ...
+ * state.transactions.map(...) // TypeError: Cannot read properties of
+ * // undefined (reading 'map')
+ * ```
+ *
+ * Two distinct undefined-variable hazards were involved:
+ *
+ * 1. **Undefined initial state.** `useState()` / `useReducer(reducer)` invoked
+ * without an initial value yields `undefined` on the very first render, so
+ * every property access in the render body throws before the data ever
+ * arrives from the indexer.
+ * 2. **Undefined payloads from the network.** Even with an initial value, the
+ * GraphQL response may be `undefined` (in-flight, aborted by the 15s
+ * timeout, or an `errorPolicy: 'all'` partial response), and individual
+ * records may be missing `amount`, `counterparty`, `status`, etc.
+ *
+ * Both classes of failure are eliminated here rather than in the React layer:
+ * the state shape is *always* fully populated, every reducer transition is
+ * total (unknown actions return the previous state unchanged), and every
+ * selector is defensive about `null` / `undefined` / wrong-typed input. The
+ * React component is then a thin, crash-proof projection of this state.
+ *
+ * Keeping the logic outside the component also makes it testable in the SDK's
+ * Node-based vitest suite — `examples/dashboard` has no test runner and the
+ * root package has no React dependency (see the note on the reverted
+ * `token-selector-rendering.test.ts` in #159).
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Lifecycle status of a single transaction row. */
+export type TransactionStatus =
+ | 'PENDING'
+ | 'CONFIRMED'
+ | 'FAILED'
+ | 'CANCELLED'
+ | 'UNKNOWN';
+
+/** Direction of value flow relative to the connected wallet. */
+export type TransactionDirection = 'IN' | 'OUT' | 'UNKNOWN';
+
+/** Transaction kinds surfaced by the indexer. */
+export type TransactionKind =
+ | 'CREATE'
+ | 'WITHDRAW'
+ | 'PAUSE'
+ | 'RESUME'
+ | 'CANCEL'
+ | 'TOP_UP'
+ | 'UNKNOWN';
+
+/**
+ * A normalised transaction record. Every field is non-optional: normalisation
+ * substitutes safe defaults so the render layer never has to null-check.
+ */
+export interface TransactionRecord {
+ id: string;
+ hash: string;
+ streamId: string;
+ kind: TransactionKind;
+ direction: TransactionDirection;
+ status: TransactionStatus;
+ /** Amount in stroops, kept as a string to avoid precision loss. */
+ amount: string;
+ asset: string;
+ counterparty: string;
+ /** Unix epoch milliseconds. `0` when the indexer omitted a timestamp. */
+ timestamp: number;
+}
+
+/** User-controlled filters applied client-side to the fetched page. */
+export interface TransactionFilters {
+ status: TransactionStatus | 'ALL';
+ kind: TransactionKind | 'ALL';
+ direction: TransactionDirection | 'ALL';
+ /** Free-text match against hash, stream id, counterparty and asset. */
+ search: string;
+}
+
+/** Complete Transaction History state. Never `undefined`, never partial. */
+export interface TransactionHistoryState {
+ transactions: TransactionRecord[];
+ filters: TransactionFilters;
+ page: number;
+ pageSize: number;
+ loading: boolean;
+ /** Human-readable error message, or `null` when there is no error. */
+ error: string | null;
+ /** Epoch ms of the last successful load; `0` before the first success. */
+ lastUpdated: number;
+}
+
+export type TransactionHistoryAction =
+ | { type: 'LOAD_START' }
+ | { type: 'LOAD_SUCCESS'; payload: unknown; receivedAt?: number }
+ | { type: 'LOAD_FAILURE'; error: unknown }
+ | { type: 'SET_FILTER'; filter: Partial<TransactionFilters> }
+ | { type: 'SET_PAGE'; page: unknown }
+ | { type: 'SET_PAGE_SIZE'; pageSize: unknown }
+ | { type: 'RESET' };
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+export const DEFAULT_PAGE_SIZE = 10;
+
+export const INITIAL_TRANSACTION_FILTERS: Readonly<TransactionFilters> =
+ Object.freeze({
+ status: 'ALL',
+ kind: 'ALL',
+ direction: 'ALL',
+ search: '',
+ });
+
+/**
+ * The single source of truth for the initial state.
+ *
+ * Passing this to `useReducer` (or `useState`) is what prevents the
+ * first-render crash: `state.transactions` is an array from the very first
+ * paint, before any network response exists.
+ */
+export function createInitialTransactionHistoryState(
+ overrides: Partial<TransactionHistoryState> = {},
+): TransactionHistoryState {
+ const base: TransactionHistoryState = {
+ transactions: [],
+ filters: { ...INITIAL_TRANSACTION_FILTERS },
+ page: 0,
+ pageSize: DEFAULT_PAGE_SIZE,
+ loading: false,
+ error: null,
+ lastUpdated: 0,
+ };
+
+ const merged: TransactionHistoryState = {
+ ...base,
+ ...overrides,
+ // Guard the two nested/array members against explicit `null` overrides.
+ transactions: Array.isArray(overrides.transactions)
+ ? overrides.transactions
+ : base.transactions,
+ filters: { ...base.filters, ...(overrides.filters ?? {}) },
+ };
+
+ return merged;
+}
+
+const VALID_STATUSES: readonly TransactionStatus[] = [
+ 'PENDING',
+ 'CONFIRMED',
+ 'FAILED',
+ 'CANCELLED',
+ 'UNKNOWN',
+];
+
+const VALID_KINDS: readonly TransactionKind[] = [
+ 'CREATE',
+ 'WITHDRAW',
+ 'PAUSE',
+ 'RESUME',
+ 'CANCEL',
+ 'TOP_UP',
+ 'UNKNOWN',
+];
+
+const VALID_DIRECTIONS: readonly TransactionDirection[] = [
+ 'IN',
+ 'OUT',
+ 'UNKNOWN',
+];
+
+// ---------------------------------------------------------------------------
+// Coercion helpers — all total functions, never throw
+// ---------------------------------------------------------------------------
+
+function asString(value: unknown, fallback = ''): string {
+ if (typeof value === 'string') return value;
+ if (typeof value === 'number' && Number.isFinite(value)) return String(value);
+ if (typeof value === 'bigint') return value.toString();
+ return fallback;
+}
+
+function asTimestamp(value: unknown): number {
+ if (typeof value === 'number' && Number.isFinite(value)) {
+ // Indexers emit seconds for `createdAt`; normalise to milliseconds.
+ return value < 1e12 ? Math.trunc(value) * 1000 : Math.trunc(value);
+ }
+ if (typeof value === 'string' && value.trim() !== '') {
+ const numeric = Number(value);
+ Iif (Number.isFinite(numeric)) return asTimestamp(numeric);
+ const parsed = Date.parse(value);
+ if (!Number.isNaN(parsed)) return parsed;
+ }
+ Iif (value instanceof Date) {
+ const time = value.getTime();
+ return Number.isNaN(time) ? 0 : time;
+ }
+ return 0;
+}
+
+function asEnum<T extends string>(
+ value: unknown,
+ allowed: readonly T[],
+ fallback: T,
+): T {
+ if (typeof value !== 'string') return fallback;
+ const upper = value.trim().toUpperCase();
+ return (allowed as readonly string[]).includes(upper) ? (upper as T) : fallback;
+}
+
+/** Extracts a readable message from anything that was thrown or returned. */
+export function toErrorMessage(
+ error: unknown,
+ fallback = 'Failed to load transaction history.',
+): string {
+ if (typeof error === 'string' && error.trim() !== '') return error;
+ if (error instanceof Error && error.message.trim() !== '') return error.message;
+ if (error && typeof error === 'object') {
+ const message = (error as { message?: unknown }).message;
+ if (typeof message === 'string' && message.trim() !== '') return message;
+ }
+ return fallback;
+}
+
+// ---------------------------------------------------------------------------
+// Normalisation
+// ---------------------------------------------------------------------------
+
+/**
+ * Turns one raw indexer record into a fully-populated `TransactionRecord`.
+ * Returns `null` for values that cannot possibly be a record (`null`,
+ * primitives, arrays) so the caller can drop them.
+ */
+export function normalizeTransaction(raw: unknown): TransactionRecord | null {
+ if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return null;
+
+ const record = raw as Record<string, unknown>;
+
+ const id = asString(record['id'] ?? record['hash'] ?? record['streamId']);
+ const hash = asString(record['hash'] ?? record['txHash'] ?? record['id']);
+
+ // A record with no identity at all is unusable — drop it rather than
+ // rendering a row with an empty React key.
+ if (id === '' && hash === '') return null;
+
+ const amountRaw = record['amount'] ?? record['value'] ?? record['ratePerSecond'];
+
+ return {
+ id: id === '' ? hash : id,
+ hash,
+ streamId: asString(record['streamId'] ?? record['stream_id']),
+ kind: asEnum(record['kind'] ?? record['type'], VALID_KINDS, 'UNKNOWN'),
+ direction: asEnum(record['direction'], VALID_DIRECTIONS, 'UNKNOWN'),
+ status: asEnum(record['status'], VALID_STATUSES, 'UNKNOWN'),
+ amount: asString(amountRaw, '0'),
+ asset: asString(record['asset'] ?? record['token'] ?? record['symbol'], 'XLM'),
+ counterparty: asString(
+ record['counterparty'] ?? record['recipient'] ?? record['sender'],
+ ),
+ timestamp: asTimestamp(record['timestamp'] ?? record['createdAt']),
+ };
+}
+
+/**
+ * Normalises a whole payload. Accepts the raw GraphQL `data` object, a bare
+ * array, `null`, `undefined` or garbage — and always returns an array.
+ */
+export function normalizeTransactions(payload: unknown): TransactionRecord[] {
+ let list: unknown = payload;
+
+ if (payload && typeof payload === 'object' && !Array.isArray(payload)) {
+ const container = payload as Record<string, unknown>;
+ list =
+ container['transactions'] ??
+ container['transactionHistory'] ??
+ container['streams'] ??
+ container['items'] ??
+ container['data'] ??
+ // Support the relay-style `{ edges: [{ node }] }` shape.
+ (Array.isArray(container['edges'])
+ ? (container['edges'] as unknown[]).map((edge) =>
+ edge && typeof edge === 'object'
+ ? (edge as Record<string, unknown>)['node']
+ : edge,
+ )
+ : undefined);
+ }
+
+ if (!Array.isArray(list)) return [];
+
+ const seen = new Set<string>();
+ const normalized: TransactionRecord[] = [];
+
+ for (const entry of list) {
+ const record = normalizeTransaction(entry);
+ if (record === null) continue;
+ // De-duplicate on id so a refetch racing a poll cannot produce duplicate
+ // React keys.
+ if (seen.has(record.id)) continue;
+ seen.add(record.id);
+ normalized.push(record);
+ }
+
+ return normalized;
+}
+
+// ---------------------------------------------------------------------------
+// Reducer
+// ---------------------------------------------------------------------------
+
+function clampPage(page: unknown, totalPages: number): number {
+ const numeric = typeof page === 'number' ? page : Number(page);
+ if (!Number.isFinite(numeric)) return 0;
+ const floored = Math.trunc(numeric);
+ if (floored < 0) return 0;
+ const maxPage = Math.max(0, totalPages - 1);
+ return floored > maxPage ? maxPage : floored;
+}
+
+/**
+ * Total reducer: every action returns a complete state object, and an
+ * unrecognised action (or an `undefined` state from a hot reload / persisted
+ * store) falls back to a valid state instead of propagating `undefined`.
+ */
+export function transactionHistoryReducer(
+ state: TransactionHistoryState | undefined,
+ action: TransactionHistoryAction | undefined,
+): TransactionHistoryState {
+ const current = state ?? createInitialTransactionHistoryState();
+
+ if (!action || typeof action !== 'object' || typeof action.type !== 'string') {
+ return current;
+ }
+
+ switch (action.type) {
+ case 'LOAD_START':
+ // Keep the existing rows visible while refreshing so the table does not
+ // flash empty; clear the previous error.
+ return { ...current, loading: true, error: null };
+
+ case 'LOAD_SUCCESS': {
+ const transactions = normalizeTransactions(action.payload);
+ const totalPages = Math.max(
+ 1,
+ Math.ceil(transactions.length / Math.max(1, current.pageSize)),
+ );
+ return {
+ ...current,
+ transactions,
+ loading: false,
+ error: null,
+ page: clampPage(current.page, totalPages),
+ lastUpdated:
+ typeof action.receivedAt === 'number' && Number.isFinite(action.receivedAt)
+ ? action.receivedAt
+ : Date.now(),
+ };
+ }
+
+ case 'LOAD_FAILURE':
+ // Preserve any previously loaded rows: a failed refresh should degrade
+ // to "stale data + error banner", never to a crash or a blank screen.
+ return {
+ ...current,
+ loading: false,
+ error: toErrorMessage(action.error),
+ };
+
+ case 'SET_FILTER': {
+ const raw = action.filter ?? {};
+ const validated: Partial<TransactionFilters> = {};
+
+ if (raw.status !== undefined) {
+ validated.status = asEnum(raw.status, VALID_STATUSES, 'ALL') as TransactionStatus | 'ALL';
+ }
+ Iif (raw.kind !== undefined) {
+ validated.kind = asEnum(raw.kind, VALID_KINDS, 'ALL') as TransactionKind | 'ALL';
+ }
+ Iif (raw.direction !== undefined) {
+ validated.direction = asEnum(raw.direction, VALID_DIRECTIONS, 'ALL') as TransactionDirection | 'ALL';
+ }
+ if (raw.search !== undefined) {
+ validated.search = asString(raw.search);
+ }
+
+ return {
+ ...current,
+ filters: { ...current.filters, ...validated },
+ // Any filter change invalidates the current page offset.
+ page: 0,
+ };
+ }
+
+ case 'SET_PAGE': {
+ const visible = selectFilteredTransactions(current);
+ const totalPages = Math.max(
+ 1,
+ Math.ceil(visible.length / Math.max(1, current.pageSize)),
+ );
+ return { ...current, page: clampPage(action.page, totalPages) };
+ }
+
+ case 'SET_PAGE_SIZE': {
+ const numeric =
+ typeof action.pageSize === 'number'
+ ? action.pageSize
+ : Number(action.pageSize);
+ const pageSize =
+ Number.isFinite(numeric) && numeric > 0
+ ? Math.trunc(numeric)
+ : DEFAULT_PAGE_SIZE;
+ return { ...current, pageSize, page: 0 };
+ }
+
+ case 'RESET':
+ return createInitialTransactionHistoryState();
+
+ default:
+ return current;
+ }
+}
+
+// ---------------------------------------------------------------------------
+// Selectors
+// ---------------------------------------------------------------------------
+
+/** Applies the active filters. Safe against a malformed/absent state. */
+export function selectFilteredTransactions(
+ state: TransactionHistoryState | undefined,
+): TransactionRecord[] {
+ const transactions = Array.isArray(state?.transactions) ? state.transactions : [];
+ const filters = { ...INITIAL_TRANSACTION_FILTERS, ...(state?.filters ?? {}) };
+ const search = asString(filters.search).trim().toLowerCase();
+
+ return transactions.filter((tx) => {
+ Iif (!tx) return false;
+ if (filters.status !== 'ALL' && tx.status !== filters.status) return false;
+ Iif (filters.kind !== 'ALL' && tx.kind !== filters.kind) return false;
+ Iif (filters.direction !== 'ALL' && tx.direction !== filters.direction) {
+ return false;
+ }
+ if (search === '') return true;
+
+ return [tx.hash, tx.streamId, tx.counterparty, tx.asset].some((field) =>
+ asString(field).toLowerCase().includes(search),
+ );
+ });
+}
+
+/** Filtered rows, newest first, sliced to the current page. */
+export function selectVisibleTransactions(
+ state: TransactionHistoryState | undefined,
+): TransactionRecord[] {
+ const filtered = selectFilteredTransactions(state);
+ const sorted = [...filtered].sort((a, b) => b.timestamp - a.timestamp);
+
+ const pageSize = Math.max(1, Math.trunc(state?.pageSize ?? DEFAULT_PAGE_SIZE));
+ const totalPages = Math.max(1, Math.ceil(sorted.length / pageSize));
+ const page = clampPage(state?.page ?? 0, totalPages);
+ const start = page * pageSize;
+
+ return sorted.slice(start, start + pageSize);
+}
+
+/** Total number of pages for the current filters (always >= 1). */
+export function selectTotalPages(
+ state: TransactionHistoryState | undefined,
+): number {
+ const filtered = selectFilteredTransactions(state);
+ const pageSize = Math.max(1, Math.trunc(state?.pageSize ?? DEFAULT_PAGE_SIZE));
+ return Math.max(1, Math.ceil(filtered.length / pageSize));
+}
+
+/**
+ * Which of the mutually exclusive UI states the view should render.
+ * Centralised so the component cannot accidentally render a data table with
+ * no data (the original crash path).
+ */
+export function selectViewStatus(
+ state: TransactionHistoryState | undefined,
+): 'loading' | 'error' | 'empty' | 'ready' {
+ const current = state ?? createInitialTransactionHistoryState();
+ const hasRows = selectFilteredTransactions(current).length > 0;
+
+ if (current.loading && !hasRows) return 'loading';
+ if (current.error !== null && !hasRows) return 'error';
+ if (!hasRows) return 'empty';
+ return 'ready';
+}
+
+// ---------------------------------------------------------------------------
+// Display formatters
+// ---------------------------------------------------------------------------
+
+/** `GABC…WXYZ` — never throws on short, empty or non-string input. */
+export function formatAddress(address: unknown, visible = 6): string {
+ const value = asString(address);
+ if (value === '') return '—';
+ const head = Math.max(2, Math.trunc(visible));
+ if (value.length <= head + 4 + 1) return value;
+ return `${value.slice(0, head)}…${value.slice(-4)}`;
+}
+
+/** Stroops → decimal string. Falls back to `'0'` on unparseable input. */
+export function formatAmount(amount: unknown, decimals = 7): string {
+ const raw = asString(amount, '0').trim();
+ const negative = raw.startsWith('-');
+ const digits = (negative ? raw.slice(1) : raw).replace(/[^0-9]/g, '');
+ if (digits === '') return '0';
+
+ const places = Math.max(0, Math.trunc(decimals));
+ const padded = digits.padStart(places + 1, '0');
+ const whole = padded.slice(0, padded.length - places) || '0';
+ const fraction = places === 0 ? '' : padded.slice(padded.length - places);
+ const trimmedFraction = fraction.replace(/0+$/, '');
+
+ const formattedWhole = whole.replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+ const sign = negative ? '-' : '';
+
+ return trimmedFraction === ''
+ ? `${sign}${formattedWhole}`
+ : `${sign}${formattedWhole}.${trimmedFraction}`;
+}
+
+/** ISO-ish timestamp for display; `'—'` when the indexer omitted one. */
+export function formatTimestamp(timestamp: unknown): string {
+ const ms = asTimestamp(timestamp);
+ if (ms === 0) return '—';
+ const date = new Date(ms);
+ Iif (Number.isNaN(date.getTime())) return '—';
+ return date.toISOString().replace('T', ' ').slice(0, 19);
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 | + + + + + + + + + + + + + + + +39x + + + +39x +39x +39x +39x +39x +39x +39x +39x +39x +39x +39x +39x +39x +39x +39x +39x + + +39x + + + + + + + + + + + + + + + + + + + +39x +39x +39x +39x +39x +39x +39x +39x +39x +39x +39x + + +39x + + + + + + + + + + + + + + +39x +39x +39x +39x + + +39x + + + + + +39x + + + + + + + + + + + +39x + + + + + + + + + + + + + + + + + + + + + + + + + +29x +29x + + + +29x +29x +29x + +29x + + + + + + + + +50x +50x +50x +50x + + + + + + + + +2x + + + + +8x +7x +7x +6x + + +2x + + + + + + + + + + +7x +7x +5x +5x +5x + + + + + + + + + + + + + + + +8x +8x +8x +8x + + + +6x + +6x +6x + +6x +6x +3x + + +3x +3x +2x + + +1x + + + + + + + + + + + + + + + + +16x + +16x +16x +6x +6x +6x + + + + + + + + +10x +10x +2x + + +8x + + + | /**
+ * Each of the three Conduit contracts defines its own `Error` enum in Rust —
+ * the same numeric code means something different in each one (e.g. code 1
+ * is `NotAuthorized` on DripStream/DripGovernor, but `NotInitialized` on
+ * DripFactory). See each contract's README error table / errors.rs. Treating
+ * these as a single shared number space (as this module used to) means a
+ * Factory `NotInitialized` gets silently reported as `NotAuthorized`.
+ */
+export type ConduitContract = 'stream' | 'factory' | 'governor';
+
+/**
+ * Sentinel value used by {@link ConduitError.fromContractError} when the
+ * contract error code does not match any known code in the SDK's error
+ * catalogue. Use this constant (or {@link ConduitError.isKnown}) instead
+ * of hardcoding `-1` in consumer code.
+ */
+export const UNKNOWN_CONTRACT_ERROR_CODE = -1;
+
+// ── DripStream errors (contracts/stream/src/errors.rs) ────────────────────────
+
+export enum StreamErrorCode {
+ NotAuthorized = 1,
+ StreamNotFound = 2,
+ StreamCancelled = 3,
+ StreamNotStarted = 4,
+ StreamEnded = 5,
+ NothingToWithdraw = 6,
+ InsufficientDeposit = 7,
+ InvalidTimeRange = 8,
+ AlreadyPaused = 9,
+ NotPaused = 10,
+ ClawbackDisabled = 11,
+ ArithmeticOverflow = 12,
+ PauseThresholdNotMet = 13,
+ AlreadyInitialized = 14,
+ InvalidAmount = 15,
+}
+
+const STREAM_MESSAGES: Record<StreamErrorCode, string> = {
+ [StreamErrorCode.NotAuthorized]: 'Caller is not the sender or recipient of this stream.',
+ [StreamErrorCode.StreamNotFound]: 'Stream not found.',
+ [StreamErrorCode.StreamCancelled]: 'This stream has been cancelled.',
+ [StreamErrorCode.StreamNotStarted]: 'Stream has not started yet.',
+ [StreamErrorCode.StreamEnded]: 'Stream has passed its end time.',
+ [StreamErrorCode.NothingToWithdraw]: 'Nothing to withdraw — balance is zero.',
+ [StreamErrorCode.InsufficientDeposit]: 'Deposit is too small for the requested stream duration.',
+ [StreamErrorCode.InvalidTimeRange]: 'end_time must be greater than start_time.',
+ [StreamErrorCode.AlreadyPaused]: 'Stream is already paused.',
+ [StreamErrorCode.NotPaused]: 'Stream is not currently paused.',
+ [StreamErrorCode.ClawbackDisabled]: 'Clawback was not enabled when this stream was created.',
+ [StreamErrorCode.ArithmeticOverflow]: 'Integer overflow in stream calculation.',
+ [StreamErrorCode.PauseThresholdNotMet]: 'force_cancel called before the 30-day pause threshold elapsed.',
+ [StreamErrorCode.AlreadyInitialized]: 'Stream has already been initialized.',
+ [StreamErrorCode.InvalidAmount]: 'Amount must be greater than zero.',
+};
+
+// ── DripFactory errors (contracts/factory/src/errors.rs) ──────────────────────
+
+export enum FactoryErrorCode {
+ NotInitialized = 1,
+ InvalidDeposit = 2,
+ InvalidRate = 3,
+ InvalidTimeRange = 4,
+ InsufficientDeposit = 5,
+ BackdatedStream = 6,
+ AlreadyInitialized = 7,
+ RateExceedsMax = 8,
+ DurationTooShort = 9,
+ ArithmeticOverflow = 10,
+}
+
+const FACTORY_MESSAGES: Record<FactoryErrorCode, string> = {
+ [FactoryErrorCode.NotInitialized]: 'Factory has not been initialized.',
+ [FactoryErrorCode.InvalidDeposit]: 'Deposit must be greater than zero.',
+ [FactoryErrorCode.InvalidRate]: 'rate_per_sec must be greater than zero.',
+ [FactoryErrorCode.InvalidTimeRange]: 'end_time must be greater than start_time.',
+ [FactoryErrorCode.InsufficientDeposit]: "Deposit doesn't cover rate_per_sec for at least one second, or the full declared duration.",
+ [FactoryErrorCode.BackdatedStream]: 'start_time cannot be in the past.',
+ [FactoryErrorCode.AlreadyInitialized]: 'Factory has already been initialized.',
+ [FactoryErrorCode.RateExceedsMax]: "rate_per_sec exceeds the governor's max_rate_per_second.",
+ [FactoryErrorCode.DurationTooShort]: "Stream duration is below the governor's min_duration_seconds.",
+ [FactoryErrorCode.ArithmeticOverflow]: 'Integer overflow validating deposit against duration.',
+};
+
+// ── DripGovernor errors (contracts/governor/src/errors.rs) ────────────────────
+
+export enum GovernorErrorCode {
+ NotAuthorized = 1,
+ InvalidParam = 2,
+ AlreadyInitialized = 3,
+}
+
+const GOVERNOR_MESSAGES: Record<GovernorErrorCode, string> = {
+ [GovernorErrorCode.NotAuthorized]: 'Caller is not the current governor authority.',
+ [GovernorErrorCode.InvalidParam]: 'Parameter failed validation (e.g. fee_bps > 10_000, zero duration/rate).',
+ [GovernorErrorCode.AlreadyInitialized]: 'Governor has already been initialized.',
+};
+
+const MESSAGES_BY_CONTRACT: Record<ConduitContract, Record<number, string>> = {
+ stream: STREAM_MESSAGES,
+ factory: FACTORY_MESSAGES,
+ governor: GOVERNOR_MESSAGES,
+};
+
+// ── Network / chain validation ─────────────────────────────────────────────────
+
+/**
+ * The exhaustive list of network identifiers the Conduit SDK supports.
+ * Matches the `Network` type in `src/types/index.ts`.
+ */
+export const SUPPORTED_NETWORKS = ['mainnet', 'testnet', 'local'] as const;
+
+/**
+ * Thrown synchronously by `ConduitClient` constructor when an unrecognised
+ * network string is supplied — before any RPC connection is attempted.
+ *
+ * @example
+ * ```ts
+ * try {
+ * const client = new ConduitClient({ network: 'ropsten' as any });
+ * } catch (err) {
+ * if (err instanceof UnsupportedChainError) {
+ * console.error(err.message); // "Unsupported network: 'ropsten'. ..."
+ * console.error(err.providedNetwork); // "ropsten"
+ * console.error(err.supportedNetworks); // ["mainnet", "testnet", "local"]
+ * }
+ * }
+ * ```
+ */
+export class UnsupportedChainError extends Error {
+ /** The network value the caller passed in. */
+ readonly providedNetwork: string;
+ /** The full list of accepted network identifiers at the time of the throw. */
+ readonly supportedNetworks: readonly string[];
+
+ constructor(providedNetwork: string) {
+ const supported = SUPPORTED_NETWORKS.join(', ');
+ super(
+ `Unsupported network: '${providedNetwork}'. ` +
+ `The Conduit SDK currently supports: ${supported}.`,
+ );
+ this.name = 'UnsupportedChainError';
+ this.providedNetwork = providedNetwork;
+ this.supportedNetworks = SUPPORTED_NETWORKS;
+ // Maintain correct prototype chain for `instanceof` checks in transpiled JS.
+ Object.setPrototypeOf(this, new.target.prototype);
+ }
+}
+
+export class ConduitError extends Error {
+ readonly contract: ConduitContract;
+ readonly code: number;
+
+ constructor(contract: ConduitContract, code: number, detail?: string) {
+ super(detail ?? MESSAGES_BY_CONTRACT[contract][code] ?? `ConduitError(${contract}, #${code})`);
+ this.name = 'ConduitError';
+ this.contract = contract;
+ this.code = code;
+ }
+
+ /**
+ * Returns `true` when this error carries a known contract error code
+ * (i.e. the code exists in the SDK's error catalogue for this contract).
+ * Returns `false` when the code is {@link UNKNOWN_CONTRACT_ERROR_CODE}.
+ */
+ get isKnown(): boolean {
+ return this.code in MESSAGES_BY_CONTRACT[this.contract];
+ }
+
+ /** Builds a ConduitError from a raw `{ code: number }`-shaped contract error object. */
+ static fromContractError(contract: ConduitContract, raw: unknown): ConduitError {
+ if (raw && typeof raw === 'object' && 'code' in raw) {
+ const code = Number((raw as { code: unknown }).code);
+ if (code in MESSAGES_BY_CONTRACT[contract]) {
+ return new ConduitError(contract, code);
+ }
+ }
+ return new ConduitError(contract, UNKNOWN_CONTRACT_ERROR_CODE, String(raw));
+ }
+
+ /**
+ * Parses a Soroban simulation/transaction failure message (e.g.
+ * `"HostError: Error(Contract, #7)"`) into a typed ConduitError scoped to
+ * `contract`. Returns a plain Error (not a ConduitError) if no contract
+ * error code can be extracted — network failures, timeouts, and non-contract
+ * host traps don't carry one.
+ */
+ static fromSorobanMessage(contract: ConduitContract, message: string): Error {
+ const match = /Error\(Contract,\s*#(\d+)\)/.exec(message);
+ if (!match || !match[1]) return new Error(message);
+ const code = Number(match[1]);
+ Iif (!(code in MESSAGES_BY_CONTRACT[contract])) return new Error(message);
+ return new ConduitError(contract, code, `${MESSAGES_BY_CONTRACT[contract][code]} (${message})`);
+ }
+}
+
+
+/**
+ * Thrown when an RPC node responds with HTTP 429 (Too Many Requests) or
+ * an equivalent JSON-RPC rate-limit error code, instead of the previous
+ * generic/unclassified error that made rate limiting indistinguishable
+ * from any other network failure. See #120.
+ */
+export class RateLimitError extends Error {
+ /** Milliseconds to wait before retrying, parsed from a Retry-After header if present. */
+ readonly retryAfterMs: number | undefined;
+
+ constructor(message: string, retryAfterMs?: number) {
+ super(message);
+ this.name = 'RateLimitError';
+ this.retryAfterMs = retryAfterMs;
+ Object.setPrototypeOf(this, new.target.prototype);
+ }
+
+ private static parseRetryAfterMs(raw: unknown): number | undefined {
+ Iif (typeof raw !== 'string' && typeof raw !== 'number') return undefined;
+
+ const value = String(raw).trim();
+ Iif (!value) return undefined;
+
+ const delaySeconds = Number(value);
+ if (Number.isFinite(delaySeconds) && delaySeconds >= 0) {
+ return delaySeconds * 1000;
+ }
+
+ const retryAt = Date.parse(value);
+ if (!Number.isNaN(retryAt)) {
+ return Math.max(0, retryAt - Date.now());
+ }
+
+ return undefined;
+ }
+
+ /**
+ * Detects a rate-limit condition from a raw error thrown by the RPC
+ * client and converts it into a typed RateLimitError. Handles two shapes:
+ *
+ * 1. An axios-style error (network-level 429), shaped like
+ * `{ response: { status: 429, headers } }`.
+ * 2. A raw JSON-RPC error object (rpc/jsonrpc.js does `throw response.data.error`
+ * directly, so it is a plain object, not an Error instance), shaped
+ * like `{ code: -32029 }`.
+ *
+ * Returns null if `raw` is not a rate-limit error, so callers can fall
+ * back to their existing error handling.
+ */
+ static fromRpcError(raw: unknown): RateLimitError | null {
+ Iif (!raw || typeof raw !== 'object') return null;
+
+ const response = (raw as { response?: { status?: number; headers?: Record<string, unknown> } }).response;
+ if (response?.status === 429) {
+ const retryAfterHeader = response.headers?.['retry-after'];
+ const retryAfterMs = RateLimitError.parseRetryAfterMs(retryAfterHeader);
+ return new RateLimitError(
+ 'RPC node rate limit exceeded (429 Too Many Requests). Back off and retry.',
+ retryAfterMs,
+ );
+ }
+
+ // De facto "too many requests" JSON-RPC error code used by several
+ // Soroban RPC providers, plus a literal 429 in case a provider reuses
+ // the HTTP status as the JSON-RPC error code.
+ const code = (raw as { code?: unknown }).code;
+ if (code === 429 || code === -32029) {
+ return new RateLimitError('RPC node rate limit exceeded (JSON-RPC error). Back off and retry.');
+ }
+
+ return null;
+ }
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 | + + + + + + + + + + + + + + + + + + + + + +3x + + + + + + + + + + + + + + + + + +5x + + + +10x +10x + + + +1x +1x + + + + + + + + + +10x +10x +10x + +1x + + + + + + + + + + + + + + + + + + +8x +8x +8x +8x + + + +10x + +10x +10x + + + + + + + + +9x + +2x +2x + +2x +2x + + + + +1x + + +10x + + + +8x + +8x + +8x +8x +8x +8x + + + + + + +8x + + + + + + + + + + + + + +12x +12x + +10x + +12x + +12x + +2x + +1x +1x + + + + + +1x +1x + + + +2x + +2x +2x + + + + +2x +2x + + + +1x + +1x +1x + + + + +1x +1x + + + +1x + + +1x + + + +1x +1x + + + +1x + +1x +1x + + + + +1x +1x + + + +2x + +2x + + + +2x +2x + + + + | /**
+ * Event subscription for DripStream contracts.
+ *
+ * Polls the Soroban event ledger on an interval and dispatches typed events
+ * to registered handlers.
+ */
+
+import { Address, SorobanRpc, xdr } from '@stellar/stellar-sdk';
+import type {
+ StreamEventHandlers,
+ Subscription,
+ WithdrawEvent,
+ CancelEvent,
+ PauseEvent,
+ ResumeEvent,
+ TopUpEvent,
+ ClawbackEvent,
+} from './types/index.js';
+import { scValToI128, scValToU64, getServer } from './soroban.js';
+
+// ── Event topic names (match symbol_short!() values in Rust) ─────────────────
+
+const TOPIC = {
+ WITHDRAWN: 'withdrawn',
+ CANCELLED: 'cancelled',
+ PAUSED: 'paused',
+ RESUMED: 'resumed',
+ TOPPED_UP: 'topped_up',
+ CLAWBACK: 'clawback',
+} as const;
+
+// ── Parser helpers ────────────────────────────────────────────────────────────
+
+/**
+ * The stream contract publishes multi-field event data as a Rust tuple,
+ * which soroban-sdk encodes as an ScVec. Single-field events (resumed,
+ * clawback) publish the bare scalar instead — callers must know which shape
+ * to expect for a given topic (see contracts/stream/src/events.rs).
+ */
+function tupleFields(val: xdr.ScVal): xdr.ScVal[] {
+ return val.vec() ?? [];
+}
+
+function i128Field(fields: xdr.ScVal[], index: number): bigint {
+ const field = fields[index];
+ return field ? scValToI128(field) : 0n;
+}
+
+function u64Field(fields: xdr.ScVal[], index: number): number {
+ const field = fields[index];
+ return field ? Number(scValToU64(field)) : 0;
+}
+
+/**
+ * Decodes an address topic to its G.../C... string. `ScVal.address()?.accountId()`
+ * returns the raw XDR PublicKey object, not a string — calling `.toString()`
+ * on it yields `"[object Object]"`. `Address.fromScVal` handles both account
+ * and contract address variants correctly.
+ */
+function addressField(val: xdr.ScVal | undefined): string {
+ Iif (!val) return '';
+ try {
+ return Address.fromScVal(val).toString();
+ } catch {
+ return '';
+ }
+}
+
+// ── Subscription ──────────────────────────────────────────────────────────────
+
+/**
+ * Subscribe to on-chain events for a specific DripStream contract.
+ *
+ * @param rpcUrl Soroban RPC endpoint
+ * @param streamAddress DripStream contract address (C…)
+ * @param handlers Event handler callbacks
+ * @returns `{ unsubscribe }` — call to stop polling
+ */
+export function subscribeToStream(
+ rpcUrl: string,
+ streamAddress: string,
+ handlers: StreamEventHandlers,
+): Subscription {
+ const server = getServer(rpcUrl);
+ const pollInterval = handlers.pollInterval ?? 5000;
+ let startLedger = 0; // updated after each successful poll
+ let stopped = false;
+ let timer: ReturnType<typeof setTimeout> | undefined;
+
+ async function poll() {
+ Iif (stopped) return;
+
+ try {
+ const response = await server.getEvents({
+ ...(startLedger > 0 ? { startLedger } : {}),
+ filters: [{
+ type: 'contract',
+ contractIds: [streamAddress],
+ }],
+ limit: 100,
+ });
+
+ if (response.events.length > 0) {
+ // Update startLedger to avoid replaying events
+ const maxLedger = Math.max(...response.events.map(e => e.ledger));
+ startLedger = maxLedger + 1;
+
+ for (const event of response.events) {
+ dispatchEvent(event, handlers);
+ }
+ }
+ } catch (err) {
+ // Swallow polling errors; the subscription continues
+ console.warn('[conduit-sdk] event polling error:', err);
+ }
+
+ Eif (!stopped) timer = setTimeout(poll, pollInterval);
+ }
+
+ // Start polling immediately
+ poll();
+
+ return {
+ unsubscribe: () => {
+ stopped = true;
+ Eif (timer !== undefined) {
+ clearTimeout(timer);
+ timer = undefined;
+ }
+ // Release closure references to prevent memory leaks — without this,
+ // the handlers object, server instance, and everything they reference
+ // stay alive in the event loop until the JS engine garbage-collects
+ // the entire closure graph, which may never happen if any external
+ // reference to the Subscription object is kept.
+ handlers = {};
+ },
+ };
+}
+
+// ── Event dispatcher ──────────────────────────────────────────────────────────
+
+// Exported (but not re-exported from index.ts) so tests can exercise the
+// tuple-decoding logic directly without standing up a fake RPC server.
+export function dispatchEvent(
+ event: SorobanRpc.Api.EventResponse,
+ handlers: StreamEventHandlers,
+): void {
+ // Topics: [symbol, actor_address]
+ const topics = event.topic;
+ if (!topics || topics.length < 1) return;
+
+ const topicName = topics[0]?.sym()?.toString() ?? '';
+
+ const actor = addressField(topics[1]);
+
+ switch (topicName) {
+ case TOPIC.WITHDRAWN: {
+ if (!handlers.onWithdraw) break;
+ // data: (amount: i128, total_withdrawn: i128, remaining: i128)
+ const fields = tupleFields(event.value);
+ const data: WithdrawEvent = {
+ recipient: actor,
+ amount: i128Field(fields, 0),
+ totalWithdrawn: i128Field(fields, 1),
+ remaining: i128Field(fields, 2),
+ };
+ handlers.onWithdraw(data);
+ break;
+ }
+
+ case TOPIC.CANCELLED: {
+ Iif (!handlers.onCancel) break;
+ // data: (refund_amount: i128, withdrawn_so_far: i128)
+ const fields = tupleFields(event.value);
+ const data: CancelEvent = {
+ sender: actor,
+ refundAmount: i128Field(fields, 0),
+ withdrawnSoFar: i128Field(fields, 1),
+ };
+ handlers.onCancel(data);
+ break;
+ }
+
+ case TOPIC.PAUSED: {
+ Iif (!handlers.onPause) break;
+ // data: (paused_at: u64, withdrawable: i128)
+ const fields = tupleFields(event.value);
+ const data: PauseEvent = {
+ sender: actor,
+ pausedAt: u64Field(fields, 0),
+ withdrawable: i128Field(fields, 1),
+ };
+ handlers.onPause(data);
+ break;
+ }
+
+ case TOPIC.RESUMED: {
+ Iif (!handlers.onResume) break;
+ // data: resumed_at: u64 (bare scalar, not a tuple — resumed() only
+ // publishes one field, see contracts/stream/src/events.rs)
+ const data: ResumeEvent = {
+ sender: actor,
+ resumedAt: Number(scValToU64(event.value)),
+ };
+ handlers.onResume(data);
+ break;
+ }
+
+ case TOPIC.TOPPED_UP: {
+ Iif (!handlers.onTopUp) break;
+ // data: (amount: i128, new_balance: i128)
+ const fields = tupleFields(event.value);
+ const data: TopUpEvent = {
+ sender: actor,
+ amount: i128Field(fields, 0),
+ newBalance: i128Field(fields, 1),
+ };
+ handlers.onTopUp(data);
+ break;
+ }
+
+ case TOPIC.CLAWBACK: {
+ Iif (!handlers.onClawback) break;
+ // data: amount: i128 (bare scalar, not a tuple)
+ const data: ClawbackEvent = {
+ sender: actor,
+ amount: scValToI128(event.value),
+ };
+ handlers.onClawback(data);
+ break;
+ }
+ }
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 | + + + + + + + + + + + + + + + + + + + + + +49x + + + +49x +1x + +48x +49x + + + + +49x +1x + + + +47x + + +47x + + + + +2x + + + +2x +2x + + + + +2x +2x + + + + +2x + + +2x +1x +1x + + + + + + + +3x + + + + + + + + +3x +3x + + + + +1x + + + + + + + + +1x +1x + + + + +2x + + + +2x +2x + + + +4x +4x +4x + + + | /**
+ * FactoryModule — DripFactory read queries.
+ */
+
+import { nativeToScVal, xdr, Address } from '@stellar/stellar-sdk';
+import type { ConduitConfig } from './types/index.js';
+import { ZERO_ADDR } from './constants.js';
+import {
+ buildContractCallTx,
+ simulateReadOnly,
+ scValToU64,
+ NETWORK_PASSPHRASE,
+ DEFAULT_RPC,
+} from './soroban.js';
+import { SUPPORTED_NETWORKS, UnsupportedChainError } from './errors.js';
+
+export class FactoryModule {
+ private readonly rpcUrl: string;
+ private readonly passphrase: string;
+ private readonly factoryId: string;
+ private readonly callerAddr: string;
+
+ constructor(private readonly config: ConduitConfig) {
+ // Guard against direct construction with an unsupported network, which
+ // would bypass the ConduitClient validation gate and produce a confusing
+ // StrKey error deep inside stellar-sdk (fixes #157).
+ if (!(SUPPORTED_NETWORKS as readonly string[]).includes(config.network)) {
+ throw new UnsupportedChainError(config.network);
+ }
+ this.rpcUrl = config.rpcUrl ?? DEFAULT_RPC[config.network];
+ this.passphrase = NETWORK_PASSPHRASE[config.network];
+ // There is no known default DripFactory deployment for any network —
+ // shipping a placeholder string here means callers who forget to set
+ // this fail deep inside @stellar/stellar-sdk with a confusing StrKey
+ // error instead of a clear one at construction time.
+ if (!config.factoryAddress) {
+ throw new Error(
+ `ConduitConfig.factoryAddress is required (no default DripFactory is known for network "${config.network}").`,
+ );
+ }
+ this.factoryId = config.factoryAddress;
+ // For read-only calls we use the keypair's public key as the fee source;
+ // if no keypair, we use the zero address (simulation only — no real account needed).
+ this.callerAddr = config.keypair?.publicKey() ?? ZERO_ADDR;
+ }
+
+ /** Total number of streams ever created through this factory. */
+ async streamCount(): Promise<bigint> {
+ const tx = await buildContractCallTx(
+ this.rpcUrl, this.passphrase, this.callerAddr,
+ this.factoryId, 'stream_count', [],
+ );
+ const val = await simulateReadOnly(this.rpcUrl, this.passphrase, tx);
+ return scValToU64(val);
+ }
+
+ /** Resolve a stream ID to its deployed contract address. Returns null if not found. */
+ async streamAddress(streamId: bigint | string): Promise<string | null> {
+ const id = BigInt(streamId);
+ const tx = await buildContractCallTx(
+ this.rpcUrl, this.passphrase, this.callerAddr,
+ this.factoryId, 'stream_address',
+ [nativeToScVal(id, { type: 'u64' })],
+ );
+ const val = await simulateReadOnly(this.rpcUrl, this.passphrase, tx);
+
+ // Contract returns Option<Address> — void = None
+ if (val.switch().name === 'scvVoid') return null;
+ try {
+ return Address.fromScVal(val).toString();
+ } catch {
+ return null;
+ }
+ }
+
+ /** List stream IDs where `address` is the sender, paginated. */
+ async streamsBySender(address: string, offset = 0, limit = 20): Promise<bigint[]> {
+ const tx = await buildContractCallTx(
+ this.rpcUrl, this.passphrase, this.callerAddr,
+ this.factoryId, 'streams_by_sender',
+ [
+ new Address(address).toScVal(),
+ nativeToScVal(offset, { type: 'u32' }),
+ nativeToScVal(limit, { type: 'u32' }),
+ ],
+ );
+ const val = await simulateReadOnly(this.rpcUrl, this.passphrase, tx);
+ return this.parseU64Vec(val);
+ }
+
+ /** List stream IDs where `address` is the recipient, paginated. */
+ async streamsByRecipient(address: string, offset = 0, limit = 20): Promise<bigint[]> {
+ const tx = await buildContractCallTx(
+ this.rpcUrl, this.passphrase, this.callerAddr,
+ this.factoryId, 'streams_by_recipient',
+ [
+ new Address(address).toScVal(),
+ nativeToScVal(offset, { type: 'u32' }),
+ nativeToScVal(limit, { type: 'u32' }),
+ ],
+ );
+ const val = await simulateReadOnly(this.rpcUrl, this.passphrase, tx);
+ return this.parseU64Vec(val);
+ }
+
+ /** Current protocol fee in basis points (e.g. 30 = 0.3%). */
+ async protocolFeeBps(): Promise<number> {
+ const tx = await buildContractCallTx(
+ this.rpcUrl, this.passphrase, this.callerAddr,
+ this.factoryId, 'protocol_fee_bps', [],
+ );
+ const val = await simulateReadOnly(this.rpcUrl, this.passphrase, tx);
+ return Number(val.u32());
+ }
+
+ private parseU64Vec(val: xdr.ScVal): bigint[] {
+ const items = val.vec();
+ Iif (!items) return [];
+ return items.map(v => scValToU64(v));
+ }
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 | + + + + + + + + + + + + + + +16x +16x + +16x +16x + + +16x +16x + + + + + + + + + + + + + + +237x +217x + + + +20x +5x +5x +1x + + + +19x +19x +19x +19x + + +12x +1x + + + +11x +11x +11x +11x + +8x +8x +8x + + +8x + +19x +19x + + + +19x + + + + +1x + + + +2x + + + +3x + + + +6x + + + +7x + + + | export interface FeeEstimatorOptions {
+ /**
+ * Minimum interval in milliseconds between network fetches.
+ * Within this window, `estimateFee` serves the cached `baseFee`
+ * instead of calling `networkFetcher` again. Default: no interval (every call fetches).
+ */
+ minRefetchIntervalMs?: number;
+}
+
+export interface FeeEstimateOptions {
+ onError?: (error: Error) => void;
+}
+
+export class FeeEstimator {
+ private baseFee: number;
+ private isEstimating: boolean = false;
+ private currentPromise: Promise<number> | null = null;
+ private readonly minRefetchIntervalMs: number;
+ private lastSuccessfulFetchAtValue: number | null = null;
+ private lastErrorValue: Error | null = null;
+
+ constructor(initialFee: number = 100, options?: FeeEstimatorOptions) {
+ this.baseFee = initialFee;
+ this.minRefetchIntervalMs = options?.minRefetchIntervalMs ?? 0;
+ }
+
+ /**
+ * Safely estimates the fee by fetching it asynchronously.
+ * Utilizes an atomic state transition / locking mechanism to prevent race conditions
+ * when multiple async hooks fire simultaneously.
+ *
+ * If `minRefetchIntervalMs` was configured, returns the cached `baseFee` when
+ * called within that window after the last successful fetch.
+ */
+ async estimateFee(
+ networkFetcher: () => Promise<number>,
+ options: FeeEstimateOptions = {}
+ ): Promise<number> {
+ if (this.currentPromise) {
+ return this.currentPromise;
+ }
+
+ // Return cached fee if within the minimum re-fetch interval
+ if (this.minRefetchIntervalMs > 0) {
+ const elapsed = Date.now() - (this.lastSuccessfulFetchAtValue ?? 0);
+ if (elapsed < this.minRefetchIntervalMs) {
+ return this.baseFee;
+ }
+ }
+
+ this.currentPromise = (async () => {
+ try {
+ this.isEstimating = true;
+ const rawFee = await networkFetcher();
+
+ // Ensure floating point math precision and error-boundary handler
+ if (typeof rawFee !== 'number' || !Number.isFinite(rawFee) || rawFee < 0) {
+ throw new Error("Invalid network fee response");
+ }
+
+ // Round to 7 decimal places for precision handling
+ this.baseFee = Math.round(rawFee * 10000000) / 10000000;
+ this.lastSuccessfulFetchAtValue = Date.now();
+ this.lastErrorValue = null;
+ return this.baseFee;
+ } catch (error) {
+ const normalizedError = error instanceof Error ? error : new Error(String(error));
+ this.lastErrorValue = normalizedError;
+ options.onError?.(normalizedError);
+
+ // Fallback sequence: return the last known base fee
+ return this.baseFee;
+ } finally {
+ this.isEstimating = false;
+ this.currentPromise = null;
+ }
+ })();
+
+ return this.currentPromise;
+ }
+
+ // Exposed for testing internal state
+ get _isEstimating(): boolean {
+ return this.isEstimating;
+ }
+
+ getBaseFee(): number {
+ return this.baseFee;
+ }
+
+ get lastSuccessfulFetchAt(): number | null {
+ return this.lastSuccessfulFetchAtValue;
+ }
+
+ get lastError(): Error | null {
+ return this.lastErrorValue;
+ }
+
+ get isStale(): boolean {
+ return this.lastErrorValue !== null;
+ }
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +22x +1x + +21x +22x +22x +22x +22x + + + + +4x +1x + + + +3x + + + +3x +3x + + + + +3x +3x +3x +7x +7x + +3x + + + + + + + + + + + | /**
+ * GovernorModule — DripGovernor config reads.
+ */
+
+import { Address, xdr } from '@stellar/stellar-sdk';
+import type { ConduitConfig, GovernorConfig } from './types/index.js';
+import { ZERO_ADDR } from './constants.js';
+import {
+ buildContractCallTx,
+ simulateReadOnly,
+ scValToI128,
+ scValToU64,
+ NETWORK_PASSPHRASE,
+ DEFAULT_RPC,
+} from './soroban.js';
+import { SUPPORTED_NETWORKS, UnsupportedChainError } from './errors.js';
+
+export class GovernorModule {
+ private readonly rpcUrl: string;
+ private readonly passphrase: string;
+ private readonly governorId: string | undefined;
+ private readonly callerAddr: string;
+ private readonly network: ConduitConfig['network'];
+
+ // Unlike FactoryModule (a hard prerequisite for virtually all StreamsModule
+ // methods), GovernorModule is orthogonal to stream operations — a caller
+ // using only client.streams shouldn't be forced to supply a
+ // governorAddress they'll never touch. ConduitClient constructs this
+ // module unconditionally, so the missing-address check has to be deferred
+ // to first actual use (getConfig()) rather than thrown in the constructor.
+ constructor(cfg: ConduitConfig) {
+ // Guard against direct construction with an unsupported network, which
+ // would bypass the ConduitClient validation gate (fixes #157).
+ if (!(SUPPORTED_NETWORKS as readonly string[]).includes(cfg.network)) {
+ throw new UnsupportedChainError(cfg.network);
+ }
+ this.rpcUrl = cfg.rpcUrl ?? DEFAULT_RPC[cfg.network];
+ this.passphrase = NETWORK_PASSPHRASE[cfg.network];
+ this.governorId = cfg.governorAddress;
+ this.callerAddr = cfg.keypair?.publicKey() ?? ZERO_ADDR;
+ this.network = cfg.network;
+ }
+
+ /** Fetch the current protocol config from the DripGovernor contract. */
+ async getConfig(): Promise<GovernorConfig> {
+ if (!this.governorId) {
+ throw new Error(
+ `ConduitConfig.governorAddress is required (no default DripGovernor is known for network "${this.network}").`,
+ );
+ }
+ const tx = await buildContractCallTx(
+ this.rpcUrl, this.passphrase, this.callerAddr,
+ this.governorId, 'config', [],
+ );
+ const val = await simulateReadOnly(this.rpcUrl, this.passphrase, tx);
+ return parseGovernorConfig(val);
+ }
+}
+
+function parseGovernorConfig(val: xdr.ScVal): GovernorConfig {
+ const entries = val.map() ?? [];
+ const m: Record<string, xdr.ScVal> = {};
+ for (const e of entries) {
+ const k = e.key().sym()?.toString('utf8') ?? e.key().str()?.toString('utf8') ?? '';
+ m[k] = e.val();
+ }
+ return {
+ feeBps: m['fee_bps']?.u32() ?? 0,
+ minDurationSeconds: m['min_duration_seconds'] ? Number(scValToU64(m['min_duration_seconds'])) : 0,
+ maxRatePerSecond: m['max_rate_per_second'] ? scValToI128(m['max_rate_per_second']) : 0n,
+ // exactOptionalPropertyTypes forbids assigning `undefined` to an optional
+ // key directly — the key must be entirely absent instead, hence the
+ // conditional spreads rather than `feeRecipient: ... ? ... : undefined`.
+ ...(m['fee_recipient'] ? { feeRecipient: Address.fromScVal(m['fee_recipient']).toString() } : {}),
+ ...(m['factory_address'] ? { factoryAddress: Address.fromScVal(m['factory_address']).toString() } : {}),
+ };
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 | + +5x + + +5x + + + + + + + + +155x +155x + +153x +1x + + + +152x +152x +152x + +152x + +152x + + +155x + +155x + + + +3x + + + | export class GraphSyncAgent {
+ private currentState: number;
+ private updateQueue: Promise<void> = Promise.resolve();
+
+ constructor(initialState: number = 0) {
+ this.currentState = initialState;
+ }
+
+ /**
+ * Safely synchronizes state with fractional updates from the network.
+ * Utilizes an atomic state transition / strict locking mechanism to prevent race conditions
+ * and unhandled promise rejections under poor network conditions.
+ */
+ async syncState(networkFetcher: () => Promise<number>): Promise<number> {
+ const syncOperation = this.updateQueue.then(async () => {
+ const rawDelta = await networkFetcher();
+
+ if (typeof rawDelta !== 'number' || !Number.isFinite(rawDelta)) {
+ throw new Error("Invalid network delta response");
+ }
+
+ // Scale to 8 decimal places for safe fractional accumulation
+ const scale = 100000000;
+ const scaledState = Math.round(this.currentState * scale);
+ const scaledDelta = Math.round(rawDelta * scale);
+
+ this.currentState = (scaledState + scaledDelta) / scale;
+
+ return this.currentState;
+ });
+
+ this.updateQueue = syncOperation.catch(() => undefined);
+
+ return syncOperation;
+ }
+
+ getCurrentState(): number {
+ return this.currentState;
+ }
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| File | ++ | Statements | ++ | Branches | ++ | Functions | ++ | Lines | ++ |
|---|---|---|---|---|---|---|---|---|---|
| builder.ts | +
+
+ |
+ 93.56% | +189/202 | +95.03% | +134/141 | +93.33% | +28/30 | +94.89% | +186/196 | +
| client.ts | +
+
+ |
+ 100% | +21/21 | +100% | +14/14 | +100% | +3/3 | +100% | +20/20 | +
| constants.ts | +
+
+ |
+ 100% | +1/1 | +100% | +0/0 | +100% | +0/0 | +100% | +1/1 | +
| errors.ts | +
+
+ |
+ 95.4% | +83/87 | +86.84% | +33/38 | +100% | +11/11 | +100% | +82/82 | +
| events.ts | +
+
+ |
+ 90.66% | +68/75 | +70.45% | +31/44 | +100% | +9/9 | +100% | +64/64 | +
| factory.ts | +
+
+ |
+ 94.11% | +32/34 | +93.75% | +15/16 | +100% | +8/8 | +96.77% | +30/31 | +
| fee-estimator.ts | +
+
+ |
+ 100% | +34/34 | +100% | +19/19 | +100% | +8/8 | +100% | +34/34 | +
| governor.ts | +
+
+ |
+ 100% | +18/18 | +86.95% | +20/23 | +100% | +3/3 | +100% | +18/18 | +
| graph-sync-agent.ts | +
+
+ |
+ 100% | +15/15 | +100% | +5/5 | +100% | +5/5 | +100% | +14/14 | +
| index.ts | +
+
+ |
+ 0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +
| indexer.ts | +
+
+ |
+ 98.62% | +143/145 | +93.19% | +137/147 | +100% | +15/15 | +99.27% | +137/138 | +
| nonce-manager.ts | +
+
+ |
+ 100% | +18/18 | +100% | +5/5 | +100% | +4/4 | +100% | +18/18 | +
| signer.ts | +
+
+ |
+ 97.72% | +86/88 | +87.77% | +79/90 | +100% | +18/18 | +100% | +83/83 | +
| soroban.ts | +
+
+ |
+ 100% | +65/65 | +100% | +30/30 | +100% | +13/13 | +100% | +63/63 | +
| streams.ts | +
+
+ |
+ 95.86% | +232/242 | +85% | +153/180 | +97.43% | +38/39 | +96.44% | +217/225 | +
| utils.ts | +
+
+ |
+ 97.43% | +76/78 | +92.98% | +53/57 | +100% | +9/9 | +100% | +66/66 | +
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + | export { ConduitClient } from './client.js';
+export { StreamBuilder, ConduitBatcher } from './builder.js';
+export { GraphQLIndexer } from './indexer.js';
+export { KeypairSigner } from './signer.js';
+export type { Signer } from './signer.js';
+export {
+ ConduitError,
+ StreamErrorCode,
+ FactoryErrorCode,
+ GovernorErrorCode,
+ UnsupportedChainError,
+ SUPPORTED_NETWORKS,
+ UNKNOWN_CONTRACT_ERROR_CODE,
+} from './errors.js';
+export type { ConduitContract } from './errors.js';
+export type { StreamConfig, StreamState, Recipient } from './types/index.js';
+export * from './types/index.js';
+export * from './adapters/index.js';
+export { FeeEstimator } from './fee-estimator.js';
+export type { FeeEstimateOptions } from './fee-estimator.js';
+export { WebSocketRelayer } from './relayer/WebSocketRelayer.js';
+export { ErrorMapper } from './relayer/ErrorMapper.js';
+export type { MappedErrorHandler } from './relayer/ErrorMapper.js';
+
+// Utils are exported via the /utils subpath export, but also available here
+export {
+ toStroops,
+ fromStroops,
+ calculateRate,
+ streamProgress,
+ withdrawableLocal,
+ bigintSafeStringify,
+} from './utils.js';
+
+export {
+ formatAddress,
+ formatAmount,
+ formatTimestamp,
+} from './dashboard/transaction-history.js';
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 | + + + + + + + + + + + + + + + + + + + +67x +67x +67x + + +67x +4x + +63x + + + +15x +1x + +14x +2x + +12x +3x + + +9x +15x +1x + + +8x + + + + + +8x +15x +1x + + +7x + + + + + + + + +7x +2x + + +5x + + + +46x +3x + +43x +1x + +42x +1x + +41x +1x + + +40x +46x +1x + + +39x +39x + +39x +39x + +39x + +42x +39x + +39x +29x +29x +1x + +29x + + + +29x + + +39x +9x +9x + + + +9x + + +39x + + + +39x + +39x +39x +30x +30x + +30x +30x + +2x + +29x + +29x +3x +1x +1x + +2x +2x +2x + + + + + + + + + + +1x + + + +29x +9x +7x +7x +9x + +5x +3x +3x +2x +1x +1x +1x + + +1x + + + +29x +11x +1x + + +29x +12x +1x + + + +1x + + +9x +9x +9x +9x + + + + + +9x + + + + + + +8x +8x +1x +1x + +7x +6x +6x +6x +6x +13x +13x +7x +7x +7x +13x +18x +18x +9x +9x +8x +8x +8x + + + + + + + + + +1x +1x +1x + + + + + +39x + + + +16x + + + +63x +63x +27x + +63x + + + +41x +31x + +10x + + +10x + + + +33x +31x + +2x +1x + +1x + + + +12x +10x +10x + + + + + + + | export interface GraphQLQueryOptions {
+ query: string;
+ variables?: Record<string, unknown>;
+ headers?: Record<string, string>;
+}
+
+export interface GraphQLSubscriptionOptions {
+ query: string;
+ variables?: Record<string, unknown>;
+ headers?: Record<string, string>;
+ onData: (data: unknown) => void;
+ onError?: (error: Error) => void;
+}
+
+export interface IndexerSubscription {
+ unsubscribe: () => void;
+}
+
+export class GraphQLIndexer {
+ private endpoint: string;
+ private activeSubscriptions: Set<IndexerSubscription> = new Set();
+ private isDestroyed = false;
+ private subCounter = 0;
+
+ constructor(endpoint: string) {
+ if (!endpoint || typeof endpoint !== 'string' || endpoint.trim().length === 0) {
+ throw new Error('GraphQLIndexer endpoint must be a non-empty string');
+ }
+ this.endpoint = endpoint;
+ }
+
+ async query(options: GraphQLQueryOptions): Promise<unknown> {
+ if (this.isDestroyed) {
+ throw new Error('GraphQLIndexer has been destroyed');
+ }
+ if (!options || typeof options !== 'object') {
+ throw new Error('GraphQLQueryOptions cannot be null or undefined');
+ }
+ if (!options.query || typeof options.query !== 'string' || options.query.trim().length === 0) {
+ throw new Error('GraphQL query string cannot be null or empty');
+ }
+
+ const variables = options.variables ?? {};
+ if (typeof variables !== 'object' || variables === null) {
+ throw new Error('GraphQL query variables must be an object');
+ }
+
+ const headers: Record<string, string> = {
+ 'Content-Type': 'application/json',
+ 'Accept': 'application/json',
+ ...options.headers,
+ };
+
+ const fetchFn = typeof fetch !== 'undefined' ? fetch : (globalThis as unknown as { fetch?: typeof fetch }).fetch;
+ if (typeof fetchFn !== 'function') {
+ throw new Error('Fetch API is not available in the current environment');
+ }
+
+ const response = await fetchFn(this.endpoint, {
+ method: 'POST',
+ headers,
+ body: JSON.stringify({
+ query: options.query,
+ variables,
+ }),
+ });
+
+ if (!response.ok) {
+ throw new Error(`GraphQL query failed with status ${response.status}: ${response.statusText}`);
+ }
+
+ return await response.json();
+ }
+
+ subscribe(options: GraphQLSubscriptionOptions): IndexerSubscription {
+ if (this.isDestroyed) {
+ throw new Error('GraphQLIndexer has been destroyed');
+ }
+ if (!options || typeof options !== 'object') {
+ throw new Error('GraphQLSubscriptionOptions cannot be null or undefined');
+ }
+ if (!options.query || typeof options.query !== 'string' || options.query.trim().length === 0) {
+ throw new Error('GraphQL subscription query string cannot be null or empty');
+ }
+ if (typeof options.onData !== 'function') {
+ throw new Error('GraphQL subscription onData callback must be a function');
+ }
+
+ const variables = options.variables ?? {};
+ if (typeof variables !== 'object' || variables === null) {
+ throw new Error('GraphQL query variables must be an object');
+ }
+
+ let unsubscribed = false;
+ const subId = `sub_${++this.subCounter}_${Date.now()}`;
+
+ let ws: WebSocket | null = null;
+ let abortController: AbortController | null = null;
+
+ const subscription: IndexerSubscription = {
+ unsubscribe: () => {
+ if (unsubscribed) return;
+ unsubscribed = true;
+
+ if (ws) {
+ try {
+ if (ws.readyState === 1 /* OPEN */) {
+ ws.send(JSON.stringify({ id: subId, type: 'complete' }));
+ }
+ ws.close();
+ } catch {
+ // Ignore socket closure errors
+ }
+ ws = null;
+ }
+
+ if (abortController) {
+ try {
+ abortController.abort();
+ } catch {
+ // Ignore abort error
+ }
+ abortController = null;
+ }
+
+ this.activeSubscriptions.delete(subscription);
+ },
+ };
+
+ this.activeSubscriptions.add(subscription);
+
+ const WebSocketCtor = this.getWebSocketCtor();
+ if (WebSocketCtor) {
+ try {
+ const wsUrl = this.getWsUrl(this.endpoint);
+ let socket: WebSocket;
+ try {
+ socket = new WebSocketCtor(wsUrl, 'graphql-transport-ws');
+ } catch {
+ socket = new WebSocketCtor(wsUrl);
+ }
+ ws = socket;
+
+ socket.onopen = () => {
+ if (unsubscribed || this.isDestroyed) {
+ subscription.unsubscribe();
+ return;
+ }
+ try {
+ socket.send(JSON.stringify({ type: 'connection_init' }));
+ socket.send(
+ JSON.stringify({
+ id: subId,
+ type: 'subscribe',
+ payload: {
+ query: options.query,
+ variables,
+ },
+ })
+ );
+ } catch (err) {
+ this.handleError(options.onError, err);
+ }
+ };
+
+ socket.onmessage = (event: MessageEvent) => {
+ if (unsubscribed || this.isDestroyed) return;
+ try {
+ const data = typeof event.data === 'string' ? JSON.parse(event.data) : event.data;
+ if (!data || typeof data !== 'object') return;
+
+ if (data.type === 'next' || data.type === 'data') {
+ const payload = data.payload ?? data.data;
+ options.onData(payload);
+ } else if (data.type === 'error') {
+ const errPayload = data.payload ?? data.errors;
+ const errMsg = typeof errPayload === 'string' ? errPayload : JSON.stringify(errPayload);
+ this.handleError(options.onError, new Error(errMsg));
+ }
+ } catch (err) {
+ this.handleError(options.onError, err);
+ }
+ };
+
+ socket.onerror = (_event: Event) => {
+ if (unsubscribed || this.isDestroyed) return;
+ this.handleError(options.onError, new Error(`GraphQL subscription WebSocket error on ${this.endpoint}`));
+ };
+
+ socket.onclose = () => {
+ if (!unsubscribed && !this.isDestroyed) {
+ subscription.unsubscribe();
+ }
+ };
+ } catch (err) {
+ this.handleError(options.onError, err);
+ }
+ } else {
+ const fetchFn = typeof fetch !== 'undefined' ? fetch : (globalThis as unknown as { fetch?: typeof fetch }).fetch;
+ Eif (typeof fetchFn === 'function' && typeof AbortController !== 'undefined') {
+ abortController = new AbortController();
+ const headers: Record<string, string> = {
+ 'Content-Type': 'application/json',
+ 'Accept': 'text/event-stream, application/json',
+ ...options.headers,
+ };
+
+ fetchFn(this.endpoint, {
+ method: 'POST',
+ headers,
+ body: JSON.stringify({ query: options.query, variables }),
+ signal: abortController.signal,
+ })
+ .then(async (response: Response) => {
+ Iif (unsubscribed || this.isDestroyed) return;
+ if (!response.ok) {
+ this.handleError(options.onError, new Error(`GraphQL subscription HTTP error: ${response.status}`));
+ return;
+ }
+ if (response.body && typeof response.body.getReader === 'function') {
+ const reader = response.body.getReader();
+ const decoder = new TextDecoder();
+ let buffer = '';
+ while (!unsubscribed && !this.isDestroyed) {
+ const { value, done } = await reader.read();
+ if (done) break;
+ buffer += decoder.decode(value, { stream: true });
+ const lines = buffer.split('\n');
+ buffer = lines.pop() ?? '';
+ for (const line of lines) {
+ const trimmed = line.trim();
+ if (trimmed.startsWith('data:')) {
+ const dataStr = trimmed.slice(5).trim();
+ if (dataStr === '[DONE]') break;
+ try {
+ const parsed = JSON.parse(dataStr);
+ options.onData(parsed.data ?? parsed);
+ } catch {
+ // Ignore malformed line
+ }
+ }
+ }
+ }
+ }
+ })
+ .catch((err: unknown) => {
+ const isAbort = err instanceof Error && err.name === 'AbortError';
+ Eif (!unsubscribed && !this.isDestroyed && !isAbort) {
+ this.handleError(options.onError, err);
+ }
+ });
+ }
+ }
+
+ return subscription;
+ }
+
+ getSubscriptionCount(): number {
+ return this.activeSubscriptions.size;
+ }
+
+ cleanup(): void {
+ this.isDestroyed = true;
+ for (const sub of Array.from(this.activeSubscriptions)) {
+ sub.unsubscribe();
+ }
+ this.activeSubscriptions.clear();
+ }
+
+ private getWebSocketCtor(): (new (url: string | URL, protocols?: string | string[]) => WebSocket) | null {
+ if (typeof globalThis !== 'undefined' && 'WebSocket' in globalThis && typeof (globalThis as unknown as { WebSocket?: typeof WebSocket }).WebSocket === 'function') {
+ return (globalThis as unknown as { WebSocket?: typeof WebSocket }).WebSocket ?? null;
+ }
+ Iif (typeof WebSocket !== 'undefined' && typeof WebSocket === 'function') {
+ return WebSocket;
+ }
+ return null;
+ }
+
+ private getWsUrl(endpoint: string): string {
+ if (endpoint.startsWith('https://')) {
+ return 'wss://' + endpoint.slice(8);
+ }
+ if (endpoint.startsWith('http://')) {
+ return 'ws://' + endpoint.slice(7);
+ }
+ return endpoint;
+ }
+
+ private handleError(onError: ((err: Error) => void) | undefined, err: unknown): void {
+ if (onError && typeof onError === 'function') {
+ try {
+ onError(err instanceof Error ? err : new Error(String(err)));
+ } catch {
+ // Prevent uncaught errors from user error handlers
+ }
+ }
+ }
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 | + +5x + + +5x + + + + + + + +156x + + +156x +156x + + +156x + +156x +156x +154x + +156x +1x +1x + + +153x +153x + +2x +2x + +156x + + + + +1x + + + | export class NonceManager {
+ private currentNonce: number;
+ private updateQueue: Promise<void> = Promise.resolve();
+
+ constructor(initialNonce: number = 0) {
+ this.currentNonce = initialNonce;
+ }
+
+ /**
+ * Safely fetches and manages the next nonce asynchronously.
+ * Uses a serialized update queue so concurrent callers cannot race.
+ */
+ async getNextNonce(networkFetcher: () => Promise<number>): Promise<number> {
+ const previousUpdate = this.updateQueue;
+ let release: (() => void) | undefined;
+
+ this.updateQueue = new Promise<void>((resolve) => {
+ release = resolve;
+ });
+
+ await previousUpdate;
+
+ try {
+ const rawResponse = await networkFetcher();
+ const networkNonce = Number.isFinite(rawResponse) ? Math.floor(rawResponse) : NaN;
+
+ if (Number.isNaN(networkNonce)) {
+ this.currentNonce += 1;
+ return this.currentNonce;
+ }
+
+ this.currentNonce = Math.max(this.currentNonce + 1, networkNonce);
+ return this.currentNonce;
+ } catch {
+ this.currentNonce += 1;
+ return this.currentNonce;
+ } finally {
+ release?.();
+ }
+ }
+
+ getCurrentNonce(): number {
+ return this.currentNonce;
+ }
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 | + + + + + + + + + +1x + + + + +27x +27x +27x +27x + + +27x +27x + +27x +27x + +27x +1x + +26x +1x + +25x +1x + + + + +55x +6x +6x + +1x + + +49x + + + +121x + + + +124x + + + +124x +122x +122x + + +2x +2x + + + + +124x +124x +3x +3x + + +121x +121x +121x + +121x +125x +125x + + +121x + + + +128x +128x +2x +2x + +126x + + + + +5x + + + +3x + + + +5x + + + +1x + + + +1x + + + +1x +1x +1x +1x + + + +25x +25x +25x +25x + + + +9x +3x + +6x +6x +9x + +1x + + + + +4x + + + +4x + +4x +4x +1x + + + +4x +4x + +3x +3x + + + + + + + + + + +1x + +1x +2x +2x + +2x +2x +1x + + + + +2x + + | export interface NonceLock {
+ nonce: bigint;
+ release: () => void;
+}
+
+export interface NonceManagerOptions {
+ startNonce?: bigint | number | string;
+ maxNonce?: bigint | number | string;
+}
+
+const MAX_SAFE_U64 = 18446744073709551615n;
+
+export class NonceManager {
+ private currentNonce: bigint;
+ private maxNonce: bigint;
+ private isLocked = false;
+ private lockQueue: Array<(value: NonceLock) => void> = [];
+ private acquiredNonces: Set<string> = new Set();
+ private isDestroyed = false;
+
+ constructor(options: NonceManagerOptions = {}) {
+ const rawStart = options.startNonce ?? 0n;
+ const rawMax = options.maxNonce ?? MAX_SAFE_U64;
+
+ this.currentNonce = this.toSafeBigInt(rawStart);
+ this.maxNonce = this.toSafeBigInt(rawMax);
+
+ if (this.currentNonce < 0n) {
+ throw new Error('NonceManager: startNonce cannot be negative');
+ }
+ if (this.maxNonce <= this.currentNonce) {
+ throw new Error('NonceManager: maxNonce must be greater than startNonce');
+ }
+ if (this.maxNonce > MAX_SAFE_U64) {
+ this.maxNonce = MAX_SAFE_U64;
+ }
+ }
+
+ private toSafeBigInt(value: bigint | number | string): bigint {
+ if (typeof value === 'string') {
+ try {
+ return BigInt(value);
+ } catch {
+ return 0n;
+ }
+ }
+ return BigInt(value);
+ }
+
+ private nonceKey(nonce: bigint): string {
+ return nonce.toString();
+ }
+
+ async acquire(): Promise<NonceLock> {
+ Iif (this.isDestroyed) {
+ throw new Error('NonceManager has been destroyed');
+ }
+
+ if (!this.isLocked) {
+ this.isLocked = true;
+ return this.nextNonce();
+ }
+
+ return new Promise<NonceLock>((resolve) => {
+ this.lockQueue.push(resolve);
+ });
+ }
+
+ private nextNonce(): NonceLock {
+ const nonce = this.currentNonce;
+ if (nonce >= this.maxNonce) {
+ this.releaseLock();
+ throw new Error(`NonceManager: nonce ${nonce} exceeds maximum ${this.maxNonce}`);
+ }
+
+ this.currentNonce = nonce + 1n;
+ const key = this.nonceKey(nonce);
+ this.acquiredNonces.add(key);
+
+ const release = () => {
+ this.acquiredNonces.delete(key);
+ this.releaseLock();
+ };
+
+ return { nonce, release };
+ }
+
+ private releaseLock(): void {
+ const next = this.lockQueue.shift();
+ if (next) {
+ const lock = this.nextNonce();
+ next(lock);
+ } else {
+ this.isLocked = false;
+ }
+ }
+
+ get current(): bigint {
+ return this.currentNonce;
+ }
+
+ get remaining(): bigint {
+ return this.maxNonce - this.currentNonce;
+ }
+
+ get acquired(): number {
+ return this.acquiredNonces.size;
+ }
+
+ async reset(nonce?: bigint | number): Promise<void> {
+ Iif (this.isDestroyed) {
+ throw new Error('NonceManager has been destroyed');
+ }
+
+ while (this.isLocked) {
+ await new Promise<void>(resolve => setTimeout(resolve, 0));
+ }
+
+ this.currentNonce = nonce !== undefined ? this.toSafeBigInt(nonce) : 0n;
+ this.acquiredNonces.clear();
+ this.lockQueue = [];
+ this.isLocked = false;
+ }
+
+ destroy(): void {
+ this.isDestroyed = true;
+ this.lockQueue = [];
+ this.isLocked = false;
+ this.acquiredNonces.clear();
+ }
+
+ static isNonceValid(value: unknown): value is bigint {
+ if (typeof value !== 'bigint' && typeof value !== 'number' && typeof value !== 'string') {
+ return false;
+ }
+ try {
+ const n = typeof value === 'bigint' ? value : BigInt(value);
+ return n >= 0n && n <= MAX_SAFE_U64;
+ } catch {
+ return false;
+ }
+ }
+
+ async acquireWithFallback(timeoutMs = 5000): Promise<NonceLock> {
+ Iif (this.isDestroyed) {
+ throw new Error('NonceManager has been destroyed');
+ }
+
+ const acquirePromise = this.acquire();
+
+ const timeoutPromise = new Promise<never>((_, reject) => {
+ setTimeout(() => {
+ reject(new Error(`NonceManager: acquire timed out after ${timeoutMs}ms`));
+ }, timeoutMs);
+ });
+
+ try {
+ return await Promise.race([acquirePromise, timeoutPromise]);
+ } catch (err) {
+ Eif (err instanceof Error) {
+ throw err;
+ }
+ throw new Error(String(err));
+ }
+ }
+
+ /** Safe acquisition with retry logic and exponential backoff. */
+ async safeAcquire(
+ retries = 3,
+ delayMs = 100,
+ ): Promise<NonceLock> {
+ let lastError: Error | null = null;
+
+ for (let attempt = 0; attempt < retries; attempt++) {
+ try {
+ return await this.acquireWithFallback();
+ } catch (err) {
+ lastError = err instanceof Error ? err : new Error(String(err));
+ if (attempt < retries - 1) {
+ await new Promise(r => setTimeout(r, delayMs * (attempt + 1)));
+ }
+ }
+ }
+
+ throw lastError ?? new Error('NonceManager: safeAcquire failed');
+ }
+} |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| File | ++ | Statements | ++ | Branches | ++ | Functions | ++ | Lines | ++ |
|---|---|---|---|---|---|---|---|---|---|
| NonceManager.ts | +
+
+ |
+ 93.1% | +81/87 | +82.97% | +39/47 | +95% | +19/20 | +94.04% | +79/84 | +
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 | + + + + + + + + + + +2x + + + + + + + + + + + + + + + + + +7x +7x + + +7x +7x +7x + + + + + + + +10x +1x + + + + +9x + +9x +28x +28x + + + + + + +6x +2x + + +4x +4x + +4x + + + +4x + +4x + + + + +12x +15x + +12x + + + + +3x +3x + + + | import type { WebSocketRelayer, WebSocketMessage, MessageHandler } from './WebSocketRelayer.js';
+import { ConduitError, type ConduitContract } from '../errors.js';
+
+export type MappedErrorHandler = (error: Error) => void;
+export type ErrorMessageTypeMap = Record<string, ConduitContract>;
+
+export interface ErrorMapperOptions {
+ errorMessageTypes?: ErrorMessageTypeMap;
+}
+
+/** WebSocket message types that carry a raw on-chain error payload, and which contract each belongs to. */
+const ERROR_MESSAGE_TYPES: Record<string, ConduitContract> = {
+ stream_error: 'stream',
+ factory_error: 'factory',
+ governor_error: 'governor',
+};
+
+/**
+ * Subscribes to error-shaped messages on a `WebSocketRelayer` and forwards
+ * them to `onError` as typed `ConduitError` instances instead of raw payloads.
+ *
+ * Must be paired with `dispose()` — see #81. Without it, each `attach()`
+ * leaves its listeners registered on the relayer forever, and any handler
+ * call still in flight when the caller stops caring can fire late.
+ */
+export class ErrorMapper {
+ private readonly relayer: WebSocketRelayer;
+ private readonly onError: MappedErrorHandler;
+ private readonly errorMessageTypes: ErrorMessageTypeMap;
+ private unsubscribers: Array<() => void> = [];
+ private isDisposed = false;
+
+ constructor(relayer: WebSocketRelayer, onError: MappedErrorHandler, options: ErrorMapperOptions = {}) {
+ this.relayer = relayer;
+ this.onError = onError;
+ this.errorMessageTypes = {
+ ...ERROR_MESSAGE_TYPES,
+ ...(options.errorMessageTypes ?? {}),
+ };
+ }
+
+ /** Registers one relayer listener per error message type. Safe to call more than once. */
+ attach(): void {
+ if (this.isDisposed) {
+ throw new Error('ErrorMapper has been disposed and cannot be re-attached');
+ }
+
+ // Re-attaching without detaching first would register a second set of
+ // listeners on top of the first, leaking the originals. Guard against it.
+ this.detach();
+
+ for (const type of Object.keys(this.errorMessageTypes)) {
+ const handler: MessageHandler = (msg) => this.handleMessage(type, msg);
+ this.unsubscribers.push(this.relayer.on(type, handler));
+ }
+ }
+
+ private handleMessage(type: string, msg: WebSocketMessage): void {
+ // Boundary check: bail before touching a disposed mapper or a
+ // null/malformed payload, rather than passing it downstream.
+ if (this.isDisposed || !msg || typeof msg !== 'object' || msg.payload == null) {
+ return;
+ }
+
+ const contract = this.errorMessageTypes[type];
+ Iif (!contract) return;
+
+ const mapped = ConduitError.fromContractError(contract, msg.payload);
+
+ // Re-check disposal after mapping: dispose() may have run while this
+ // callback was pending, and state shouldn't mutate after teardown.
+ Iif (this.isDisposed) return;
+
+ this.onError(mapped);
+ }
+
+ /** Unsubscribes every listener this mapper registered on the relayer. */
+ detach(): void {
+ for (const unsubscribe of this.unsubscribers) {
+ unsubscribe();
+ }
+ this.unsubscribers = [];
+ }
+
+ /** Detaches all listeners and permanently blocks any in-flight callback from firing. */
+ dispose(): void {
+ this.isDisposed = true;
+ this.detach();
+ }
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 | + + + + + + + + + + + + + + + + + + + + + + + + + +34x +34x +34x +34x +34x +34x +34x +34x +34x + + +34x +34x + + +34x +34x +34x +34x + + + + + +98x + + + + + + + + +147x +29x +29x + +118x +118x + + + + +147x +147x +118x + +29x + + + + +95x + +92x +92x +92x +3x +3x + + + + + + + +47x + + +47x +47x + + + +47x +47x +47x +19x + + +28x +28x +28x + +47x +47x + + + + +28x +28x + + + + + + + + +28x +28x + + + + +28x +28x + +28x +28x + + + + +28x + + + +28x + +28x +27x +27x +27x +27x +27x +27x + + +28x +1119x + + +28x +2x +2x + + + +2x +2x + + + + +28x +1x +1x +1x + + + +28x + + + + + + + +1065x +1065x +1065x + + + + + +1x + + + + +1119x + + +1117x +1117x + +3x + + +1114x + +1114x +1114x + +1062x +1065x + + + + + + + + + + + + + + + +27x +27x +27x + + + + + + + + + + + + + + + + + + + + + + + + + +39x +36x + +39x + +39x +16x +16x +16x +16x +16x + + + + + + +1x + +1x +1x + + + + + + + + + + + + + + +153x + + + +153x +53x +53x + + +100x +100x +100x +100x + + + + +100x +100x + +100x + + + + +2x +2x +2x + +2x +2x +2x + + + +2x + +2x + + + +36x +36x +36x +36x +36x + +36x +16x +16x +16x +16x +16x + + + +16x + + +36x +36x +36x +36x +36x + + + | export interface WebSocketMessage {
+ type: string;
+ payload: unknown;
+ id?: string;
+}
+
+export type MessageHandler = (msg: WebSocketMessage) => Promise<void> | void;
+export type StateChangeHandler = (transition: RelayerStateTransition, state: RelayerState) => void;
+
+export interface RelayerState {
+ connected: boolean;
+ reconnecting: boolean;
+ destroyed: boolean;
+ pendingCount: number;
+}
+
+export type RelayerStateTransition = 'connecting' | 'connected' | 'disconnected' | 'reconnecting' | 'destroyed';
+
+export interface WebSocketRelayerOptions {
+ maxReconnectAttempts?: number;
+ reconnectDelayMs?: number;
+ onStateChange?: StateChangeHandler;
+}
+
+export class WebSocketRelayer {
+ private url: string;
+ private ws: WebSocket | null = null;
+ private handlers: Map<string, Set<MessageHandler>> = new Map();
+ private stateChangeHandlers: Set<StateChangeHandler> = new Set();
+ private isDestroyed = false;
+ private isLocked = false;
+ private lockQueue: Array<() => void> = [];
+ private connectPromise: Promise<void> | null = null;
+ private reconnectAttempts = 0;
+ private reconnectEnabled = true;
+ private maxReconnectAttempts: number;
+ private reconnectDelayMs: number;
+ private pendingMessages: WebSocketMessage[] = [];
+ private stateTransition: RelayerStateTransition = 'disconnected';
+
+ constructor(url: string, options?: WebSocketRelayerOptions) {
+ this.url = url;
+ this.maxReconnectAttempts = options?.maxReconnectAttempts ?? 5;
+ this.reconnectDelayMs = options?.reconnectDelayMs ?? 1000;
+ Iif (options?.onStateChange) {
+ this.stateChangeHandlers.add(options.onStateChange);
+ }
+ }
+
+ get state(): RelayerState {
+ return {
+ connected: this.ws !== null && this.ws.readyState === 1,
+ reconnecting: this.reconnectAttempts > 0,
+ destroyed: this.isDestroyed,
+ pendingCount: this.pendingMessages.length,
+ };
+ }
+
+ private async acquireLock(): Promise<void> {
+ if (!this.isLocked) {
+ this.isLocked = true;
+ return;
+ }
+ return new Promise((resolve) => {
+ this.lockQueue.push(resolve);
+ });
+ }
+
+ private releaseLock(): void {
+ const next = this.lockQueue.shift();
+ if (next) {
+ next();
+ } else {
+ this.isLocked = false;
+ }
+ }
+
+ private emitStateChange(transition: RelayerStateTransition): void {
+ if (this.stateTransition === transition) return;
+
+ this.stateTransition = transition;
+ const state = this.state;
+ for (const handler of this.stateChangeHandlers) {
+ try {
+ handler(transition, state);
+ } catch (err) {
+ console.warn('[WebSocketRelayer] state change handler error:', err);
+ }
+ }
+ }
+
+ async connect(): Promise<void> {
+ Iif (this.isDestroyed) {
+ throw new Error('WebSocketRelayer has been destroyed');
+ }
+ this.reconnectEnabled = true;
+ Iif (this.connectPromise) {
+ return this.connectPromise;
+ }
+
+ await this.acquireLock();
+ try {
+ if (this.ws && this.ws.readyState === 1) {
+ return;
+ }
+
+ this.emitStateChange('connecting');
+ this.connectPromise = this.establishConnection();
+ await this.connectPromise;
+ } finally {
+ this.releaseLock();
+ this.connectPromise = null;
+ }
+ }
+
+ private wsCtor(): typeof WebSocket | null {
+ Eif (typeof globalThis !== 'undefined' && 'WebSocket' in globalThis) {
+ return (globalThis as unknown as { WebSocket: typeof WebSocket }).WebSocket;
+ }
+ if (typeof WebSocket !== 'undefined') {
+ return WebSocket;
+ }
+ return null;
+ }
+
+ private async establishConnection(): Promise<void> {
+ const WebSocketCtor = this.wsCtor();
+ Iif (!WebSocketCtor) {
+ this.emitStateChange('disconnected');
+ return;
+ }
+
+ return new Promise((resolve, reject) => {
+ try {
+ let ws: WebSocket;
+ try {
+ ws = new WebSocketCtor(this.url);
+ } catch {
+ // Fallback for mocks that are plain functions.
+ ws = (WebSocketCtor as unknown as (url: string) => WebSocket)(this.url);
+ }
+ Iif (!ws) {
+ resolve();
+ return;
+ }
+ let settled = false;
+
+ ws.onopen = () => {
+ Iif (settled) return;
+ settled = true;
+ this.reconnectAttempts = 0;
+ this.flushPendingMessages();
+ this.emitStateChange('connected');
+ resolve();
+ };
+
+ ws.onmessage = (event: MessageEvent) => {
+ this.handleMessageSafe(event.data);
+ };
+
+ ws.onclose = () => {
+ this.ws = null;
+ Iif (!settled) {
+ settled = true;
+ reject(new Error(`WebSocket connection closed before opening: ${this.url}`));
+ }
+ this.emitStateChange('disconnected');
+ Iif (!this.isDestroyed && this.reconnectEnabled) {
+ this.attemptReconnect();
+ }
+ };
+
+ ws.onerror = () => {
+ Eif (!settled) {
+ settled = true;
+ reject(new Error(`WebSocket connection failed: ${this.url}`));
+ }
+ };
+
+ this.ws = ws;
+ } catch (err) {
+ reject(err);
+ }
+ });
+ }
+
+ private async safeInvokeHandler(handler: MessageHandler, msg: WebSocketMessage): Promise<void> {
+ try {
+ const result = handler(msg);
+ Iif (result && typeof (result as Promise<void>).catch === 'function') {
+ await (result as Promise<void>).catch((err: Error) => {
+ console.warn('[WebSocketRelayer] async handler error:', err);
+ });
+ }
+ } catch (err) {
+ console.warn('[WebSocketRelayer] handler error:', err);
+ }
+ }
+
+ private handleMessageSafe(data: string): void {
+ if (data === null || data === undefined) return;
+
+ let parsed: WebSocketMessage;
+ try {
+ parsed = JSON.parse(data) as WebSocketMessage;
+ } catch {
+ return;
+ }
+
+ Iif (!parsed || typeof parsed !== 'object' || !parsed.type || typeof parsed.type !== 'string') return;
+
+ const typeHandlers = this.handlers.get(parsed.type);
+ if (!typeHandlers) return;
+
+ for (const handler of typeHandlers) {
+ this.safeInvokeHandler(handler, parsed);
+ }
+ }
+
+
+ /** Idempotency guard: only reconnect if not already connected or reconnecting */
+ private shouldAttemptReconnect(): boolean {
+ return (
+ !this.isDestroyed &&
+ this.reconnectEnabled &&
+ this.reconnectAttempts < this.maxReconnectAttempts &&
+ (!this.ws || this.ws.readyState !== 1)
+ );
+ }
+
+ private flushPendingMessages(): void {
+ const pending = this.pendingMessages;
+ this.pendingMessages = [];
+ for (const msg of pending) {
+ this.send(msg).catch(() => {});
+ }
+ }
+
+ private async attemptReconnect(): Promise<void> {
+ if (!this.shouldAttemptReconnect()) return;
+
+ await this.acquireLock();
+ try {
+ if (!this.shouldAttemptReconnect()) return;
+
+ this.reconnectAttempts++;
+ this.emitStateChange('reconnecting');
+ await new Promise((r) => setTimeout(r, this.reconnectDelayMs * this.reconnectAttempts));
+ if (this.isDestroyed) return;
+
+ await this.establishConnection();
+ } catch {
+ // Reconnect attempt failed; the next scheduled attempt (if any) will retry.
+ } finally {
+ this.releaseLock();
+ }
+ }
+
+ on(type: string, handler: MessageHandler): () => void {
+ if (!this.handlers.has(type)) {
+ this.handlers.set(type, new Set());
+ }
+ this.handlers.get(type)!.add(handler);
+
+ return () => {
+ const handlers = this.handlers.get(type);
+ Eif (handlers) {
+ handlers.delete(handler);
+ Eif (handlers.size === 0) {
+ this.handlers.delete(type);
+ }
+ }
+ };
+ }
+
+ onStateChange(handler: StateChangeHandler): () => void {
+ this.stateChangeHandlers.add(handler);
+
+ return () => {
+ this.stateChangeHandlers.delete(handler);
+ };
+ }
+
+ off(type: string, handler: MessageHandler): void {
+ const handlers = this.handlers.get(type);
+ if (handlers) {
+ handlers.delete(handler);
+ if (handlers.size === 0) {
+ this.handlers.delete(type);
+ }
+ }
+ }
+
+ async send(message: WebSocketMessage): Promise<void> {
+ Iif (this.isDestroyed) {
+ throw new Error('WebSocketRelayer has been destroyed');
+ }
+
+ if (!this.ws || this.ws.readyState !== 1) {
+ this.pendingMessages.push(message);
+ return;
+ }
+
+ await this.acquireLock();
+ try {
+ Iif (this.isDestroyed) throw new Error('WebSocketRelayer has been destroyed');
+ Iif (!this.ws || this.ws.readyState !== 1) {
+ this.pendingMessages.push(message);
+ return;
+ }
+
+ const payload = JSON.stringify(message);
+ this.ws.send(payload);
+ } finally {
+ this.releaseLock();
+ }
+ }
+
+ disconnect(): void {
+ this.reconnectEnabled = false;
+ this.connectPromise = null;
+ this.reconnectAttempts = 0;
+
+ Eif (this.ws) {
+ try {
+ this.ws.close();
+ } catch {
+ // Socket already closed/closing; nothing to clean up.
+ }
+ this.ws = null;
+ }
+ this.emitStateChange('disconnected');
+ }
+
+ destroy(): void {
+ this.isDestroyed = true;
+ this.reconnectEnabled = false;
+ this.connectPromise = null;
+ this.pendingMessages = [];
+ this.reconnectAttempts = this.maxReconnectAttempts;
+
+ if (this.ws) {
+ try {
+ this.ws.onclose = null;
+ this.ws.onerror = null;
+ this.ws.onmessage = null;
+ this.ws.close();
+ } catch {
+ // Socket already closed/closing; nothing to clean up.
+ }
+ this.ws = null;
+ }
+
+ this.emitStateChange('destroyed');
+ this.handlers.clear();
+ this.stateChangeHandlers.clear();
+ this.lockQueue = [];
+ this.isLocked = false;
+ }
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| File | ++ | Statements | ++ | Branches | ++ | Functions | ++ | Lines | ++ |
|---|---|---|---|---|---|---|---|---|---|
| ErrorMapper.ts | +
+
+ |
+ 92.59% | +25/27 | +86.66% | +13/15 | +100% | +6/6 | +100% | +24/24 | +
| WebSocketRelayer.ts | +
+
+ |
+ 75.54% | +139/184 | +62.1% | +59/95 | +80% | +24/30 | +78.16% | +136/174 | +
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 | + + + + + + + + +2x + +1x + + +1x + + + + + + + + + + +5x +5x +5x +5x + + + + + + +52x +52x + + +52x +52x +52x +52x + + + +52x +21x + +31x + + + +52x +51x + +1x + + + +3x + + + + + + +11x +9x +5x +5x +5x + +7x +2x +2x +2x + + + +9x +2x +2x +2x + + +7x + + + + + + + +8x +1x + +7x +3x + +4x +2x + + +2x +2x + + + + +2x + + + + + + + + +5x +1x + +4x +3x + + +1x +1x +1x + + + +32x +2x + +30x +4x + + +26x +26x + +26x +26x +26x +26x +26x + + +26x +2x +2x +2x + + +26x + +26x + +26x +25x +25x +22x +1x + + +21x +21x + + +2x +2x + + + + + +2x +1x + +1x + + + +51x +51x +1x + +51x + + + | import { Keypair, Transaction } from '@stellar/stellar-sdk';
+import type { WalletAdapter } from './adapters/types.js';
+
+export interface Signer {
+ sign(tx: Transaction): void | Promise<void>;
+ publicKey(): string;
+}
+
+export class KeypairSigner implements Signer {
+ constructor(private readonly keypair: Keypair) {}
+ sign(tx: Transaction): void {
+ tx.sign(this.keypair);
+ }
+ publicKey(): string {
+ return this.keypair.publicKey();
+ }
+}
+
+export interface TransactionSignerOptions {
+ walletAdapter?: WalletAdapter;
+ rpcProvider?: { getChainId: () => Promise<number | string> };
+ timeoutMs?: number;
+ maxPayloadSize?: number;
+}
+
+const DEFAULT_TIMEOUT_MS = 5000;
+const MAX_TIMEOUT_MS = 300_000;
+const DEFAULT_MAX_PAYLOAD_SIZE = 1_048_576;
+const MAX_VALID_CHAIN_ID = 2147483647;
+
+export class TransactionSigner implements Signer {
+ private walletAdapter: WalletAdapter | undefined;
+ private rpcProvider: { getChainId: () => Promise<number | string> } | undefined;
+ private timeoutMs: number;
+ private maxPayloadSize: number;
+ private activeCallbacks: Set<() => void> = new Set();
+ private isDestroyed = false;
+
+ constructor(options: TransactionSignerOptions = {}) {
+ this.walletAdapter = options.walletAdapter;
+ this.rpcProvider = options.rpcProvider;
+ this.timeoutMs = TransactionSigner.normalizeTimeoutMs(options.timeoutMs);
+ this.maxPayloadSize = TransactionSigner.normalizeMaxPayloadSize(options.maxPayloadSize);
+ }
+
+ private static normalizeTimeoutMs(value: number | undefined): number {
+ if (value === undefined || isNaN(value) || value <= 0) {
+ return DEFAULT_TIMEOUT_MS;
+ }
+ return Math.min(value, MAX_TIMEOUT_MS);
+ }
+
+ private static normalizeMaxPayloadSize(value: number | undefined): number {
+ if (value === undefined || isNaN(value) || value <= 0 || value > DEFAULT_MAX_PAYLOAD_SIZE) {
+ return DEFAULT_MAX_PAYLOAD_SIZE;
+ }
+ return value;
+ }
+
+ isActive(): boolean {
+ return !this.isDestroyed;
+ }
+
+ /**
+ * Returns active chain ID extracted dynamically from wallet adapter or RPC provider.
+ */
+ async getChainId(): Promise<number> {
+ if (this.walletAdapter) {
+ if ('chainId' in this.walletAdapter && (this.walletAdapter as unknown as { chainId?: unknown }).chainId) {
+ const raw = (this.walletAdapter as unknown as { chainId: unknown }).chainId;
+ const parsed = typeof raw === 'number' ? raw : parseInt(String(raw).split(':').pop() || '1', 10);
+ if (!isNaN(parsed) && parsed > 0 && parsed <= MAX_VALID_CHAIN_ID) return parsed;
+ }
+ if ('getChainId' in this.walletAdapter && typeof (this.walletAdapter as unknown as { getChainId?: () => unknown }).getChainId === 'function') {
+ const raw = await (this.walletAdapter as unknown as { getChainId: () => Promise<unknown> }).getChainId();
+ const parsed = typeof raw === 'number' ? raw : parseInt(String(raw).split(':').pop() || '1', 10);
+ Iif (!isNaN(parsed) && parsed > 0 && parsed <= MAX_VALID_CHAIN_ID) return parsed;
+ }
+ }
+
+ if (this.rpcProvider && typeof this.rpcProvider.getChainId === 'function') {
+ const raw = await this.rpcProvider.getChainId();
+ const parsed = typeof raw === 'number' ? raw : parseInt(String(raw).split(':').pop() || '1', 10);
+ Eif (!isNaN(parsed) && parsed > 0) return parsed;
+ }
+
+ return 1;
+ }
+
+ async _signTypedData(
+ domain: Record<string, unknown>,
+ types: Record<string, unknown>,
+ value: Record<string, unknown>
+ ): Promise<Record<string, unknown>> {
+ if (this.isDestroyed) {
+ throw new Error('TransactionSigner has been destroyed');
+ }
+ if (domain === null || domain === undefined || typeof domain !== 'object') {
+ throw new Error('EIP-712 domain payload cannot be null or undefined');
+ }
+ if (value === null || value === undefined || typeof value !== 'object') {
+ throw new Error('Typed data value payload cannot be null or undefined');
+ }
+
+ const chainId = await this.getChainId();
+ const dynamicDomain = {
+ ...domain,
+ chainId,
+ };
+
+ return {
+ domain: dynamicDomain,
+ types,
+ value,
+ signature: '0x' + 'ab'.repeat(65),
+ };
+ }
+
+ async signProposal(streams: unknown[]): Promise<Record<string, unknown>> {
+ if (this.isDestroyed) {
+ throw new Error('TransactionSigner has been destroyed');
+ }
+ if (!Array.isArray(streams) || streams.length === 0) {
+ throw new Error('Proposal streams payload cannot be null, undefined, or empty');
+ }
+
+ const domain = { name: 'ConduitBatcher', version: '1' };
+ const types = { Proposal: [{ name: 'streams', type: 'string[]' }] };
+ return this._signTypedData(domain, types, { streams });
+ }
+
+ async sign(tx: Transaction): Promise<void> {
+ if (this.isDestroyed) {
+ throw new Error('TransactionSigner has been destroyed');
+ }
+ if (tx === null || tx === undefined) {
+ throw new Error('Transaction payload cannot be null or undefined');
+ }
+
+ return new Promise((resolve, reject) => {
+ let cleanedUp = false;
+
+ const cleanup = () => {
+ Iif (cleanedUp) return;
+ cleanedUp = true;
+ clearTimeout(timer);
+ this.activeCallbacks.delete(cleanup);
+ };
+
+ const timer = setTimeout(() => {
+ cleanup();
+ this.isDestroyed = true;
+ reject(new Error('TransactionSigner deadlocked or timed out waiting for async callback'));
+ }, this.timeoutMs);
+
+ this.activeCallbacks.add(cleanup);
+
+ Promise.resolve()
+ .then(async () => {
+ if (this.isDestroyed || cleanedUp) return;
+ Eif (this.walletAdapter) {
+ const res = await this.walletAdapter.signTransaction(tx);
+ if (res === null || res === undefined) {
+ throw new Error('Wallet adapter returned null or undefined transaction');
+ }
+ }
+ cleanup();
+ resolve();
+ })
+ .catch((err) => {
+ cleanup();
+ reject(err);
+ });
+ });
+ }
+
+ publicKey(): string {
+ if (this.isDestroyed) {
+ throw new Error('TransactionSigner has been destroyed');
+ }
+ return 'GTRANSACTIONSIGNERMOCKKEY';
+ }
+
+ cleanup(): void {
+ this.isDestroyed = true;
+ for (const callbackCleanup of this.activeCallbacks) {
+ callbackCleanup();
+ }
+ this.activeCallbacks.clear();
+ }
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 | + + + + + + + + + + + + + + + + + + + + + + +18x + + + + + +18x + + + + + + + + + + + +18x + + +41x +41x +15x +15x + +41x + + + + + + +12x + + + + + + + +18x +18x + + +9x + + + + + + + + + + + + + + + + + + + +11x + + +11x +11x + +2x + + +9x + +9x + + + + + + + + + + + + + + + + + + + +9x +9x + + + +9x +9x + +1x + +8x +1x + + + +7x + + +7x + + + +7x +7x + +1x + +6x +1x + + + +5x +5x +7x + +7x +7x + +1x + +6x +1x + +5x +1x + + +2x + + + + + + + + + + +6x + + +6x +6x + +2x + + +4x +1x + +3x +1x + +2x + + + + + + + + + + + + + + +3x +1x +1x + + + + +20x +20x +20x + +20x + + + + +12x + + + + +5x + + + + +9x + + + +7x + + | /**
+ * Low-level Soroban RPC helpers.
+ *
+ * Wraps @stellar/stellar-sdk's SorobanRpc to provide a thin
+ * simulate → assemble → sign → submit pipeline.
+ *
+ * Performance note: SorobanRpc.Server instances are cached per RPC URL
+ * so that repeated calls (e.g. simulate → submit → poll) reuse the
+ * same HTTP client, avoiding redundant TLS and connection-pool setup.
+ */
+
+import {
+ SorobanRpc,
+ TransactionBuilder,
+ Networks,
+ Contract,
+ xdr,
+ BASE_FEE,
+} from '@stellar/stellar-sdk';
+import type { Network } from './types/index.js';
+import type { Signer } from './signer.js';
+import { RateLimitError } from './errors.js';
+
+export const DEFAULT_RPC: Record<Network, string> = {
+ mainnet: 'https://soroban-mainnet.stellar.org',
+ testnet: 'https://soroban-testnet.stellar.org',
+ local: 'http://localhost:8000/soroban/rpc',
+};
+
+export const NETWORK_PASSPHRASE: Record<Network, string> = {
+ mainnet: Networks.PUBLIC,
+ testnet: Networks.TESTNET,
+ local: Networks.STANDALONE,
+};
+
+/**
+ * Cache SorobanRpc.Server instances per RPC URL so that callers
+ * who invoke multiple RPC methods sequentially or in parallel do
+ * not create a new HTTP client for every single call.
+ * Keyed by rpcUrl so different network targets get independent caches.
+ */
+const _serverCache = new Map<string, SorobanRpc.Server>();
+
+export function getServer(rpcUrl: string): SorobanRpc.Server {
+ let srv = _serverCache.get(rpcUrl);
+ if (!srv) {
+ srv = new SorobanRpc.Server(rpcUrl, { allowHttp: rpcUrl.startsWith('http://') });
+ _serverCache.set(rpcUrl, srv);
+ }
+ return srv;
+}
+
+/**
+ * Clear the server cache. Intended for use in tests.
+ */
+export function clearServerCache(): void {
+ _serverCache.clear();
+}
+
+export interface ConfirmationPollingOptions {
+ pollIntervalMs?: number;
+ maxAttempts?: number;
+}
+
+export const DEFAULT_CONFIRMATION_POLL_INTERVAL_MS = 1000;
+export const DEFAULT_CONFIRMATION_MAX_ATTEMPTS = 30;
+
+function normalizePollingOptions(options: ConfirmationPollingOptions = {}): Required<ConfirmationPollingOptions> {
+ return {
+ pollIntervalMs: options.pollIntervalMs ?? DEFAULT_CONFIRMATION_POLL_INTERVAL_MS,
+ maxAttempts: options.maxAttempts ?? DEFAULT_CONFIRMATION_MAX_ATTEMPTS,
+ };
+}
+
+/**
+ * Build a contract-call transaction for simulate or submit.
+ *
+ * Fetches the caller's account from the RPC to get the current sequence
+ * number, then wraps the call in a TransactionBuilder.
+ */
+export async function buildContractCallTx(
+ rpcUrl: string,
+ passphrase: string,
+ caller: string,
+ contractId: string,
+ method: string,
+ args: xdr.ScVal[],
+): Promise<ReturnType<TransactionBuilder['build']>> {
+ const server = getServer(rpcUrl);
+
+ let account;
+ try {
+ account = await server.getAccount(caller);
+ } catch (err) {
+ throw RateLimitError.fromRpcError(err) ?? err;
+ }
+
+ const contract = new Contract(contractId);
+
+ return new TransactionBuilder(account, {
+ fee: BASE_FEE,
+ networkPassphrase: passphrase,
+ })
+ .addOperation(contract.call(method, ...args))
+ .setTimeout(30)
+ .build();
+}
+
+/**
+ * Simulate a transaction, then assemble + sign + submit.
+ * Returns the transaction hash on success.
+ */
+export async function invokeContract(
+ rpcUrl: string,
+ passphrase: string,
+ signer: Signer,
+ tx: ReturnType<TransactionBuilder['build']>,
+ pollingOptions: ConfirmationPollingOptions = {},
+): Promise<string> {
+ const server = getServer(rpcUrl);
+ const polling = normalizePollingOptions(pollingOptions);
+
+ // Simulate
+ let simResult;
+ try {
+ simResult = await server.simulateTransaction(tx);
+ } catch (err) {
+ throw RateLimitError.fromRpcError(err) ?? err;
+ }
+ if (SorobanRpc.Api.isSimulationError(simResult)) {
+ throw new Error(`Simulation failed: ${simResult.error}`);
+ }
+
+ // Assemble (adds soroban auth + footprint)
+ const assembled = SorobanRpc.assembleTransaction(tx, simResult).build();
+
+ // Sign
+ await signer.sign(assembled);
+
+ // Submit
+ let sent;
+ try {
+ sent = await server.sendTransaction(assembled);
+ } catch (err) {
+ throw RateLimitError.fromRpcError(err) ?? err;
+ }
+ if (sent.status === 'ERROR') {
+ throw new Error(`Transaction rejected: ${JSON.stringify(sent.errorResult)}`);
+ }
+
+ // Poll for confirmation
+ const hash = sent.hash;
+ for (let i = 0; i < polling.maxAttempts; i++) {
+ await sleep(polling.pollIntervalMs);
+ let status;
+ try {
+ status = await server.getTransaction(hash);
+ } catch (err) {
+ throw RateLimitError.fromRpcError(err) ?? err;
+ }
+ if (status.status === SorobanRpc.Api.GetTransactionStatus.SUCCESS) {
+ return hash;
+ }
+ if (status.status === SorobanRpc.Api.GetTransactionStatus.FAILED) {
+ throw new Error(`Transaction failed: ${hash}`);
+ }
+ }
+ throw new Error(`Transaction timed out: ${hash}`);
+}
+
+/**
+ * Simulate a read-only call and return the result XDR.
+ */
+export async function simulateReadOnly(
+ rpcUrl: string,
+ passphrase: string,
+ tx: ReturnType<TransactionBuilder['build']>,
+): Promise<xdr.ScVal> {
+ const server = getServer(rpcUrl);
+
+ let result;
+ try {
+ result = await server.simulateTransaction(tx);
+ } catch (err) {
+ throw RateLimitError.fromRpcError(err) ?? err;
+ }
+
+ if (SorobanRpc.Api.isSimulationError(result)) {
+ throw new Error(`Simulation error: ${result.error}`);
+ }
+ if (!result.result) {
+ throw new Error('Simulation returned no result');
+ }
+ return xdr.ScVal.fromXDR(result.result.retval.toXDR());
+}
+
+/**
+ * Query a token contract's `decimals()` — part of the standard Stellar
+ * Asset / SEP-41 token interface every `CreateStreamParams.token` must
+ * implement. Callers must not assume 7 decimals (the native XLM/Stellar
+ * Asset Contract default) for arbitrary token addresses.
+ */
+export async function getTokenDecimals(
+ rpcUrl: string,
+ passphrase: string,
+ callerAddr: string,
+ tokenId: string,
+): Promise<number> {
+ const tx = await buildContractCallTx(rpcUrl, passphrase, callerAddr, tokenId, 'decimals', []);
+ const val = await simulateReadOnly(rpcUrl, passphrase, tx);
+ return val.u32();
+}
+
+/** Convert an ScVal i128 to bigint */
+export function scValToI128(val: xdr.ScVal): bigint {
+ const i128 = val.i128();
+ const hi = BigInt(i128.hi().toString());
+ const lo = BigInt(i128.lo().toString());
+ // hi is signed high 64 bits, lo is unsigned low 64 bits
+ return (hi << 64n) | lo;
+}
+
+/** Convert an ScVal u64 to bigint */
+export function scValToU64(val: xdr.ScVal): bigint {
+ return BigInt(val.u64().toString());
+}
+
+/** Encode a u64 value as ScVal */
+export function u64ToScVal(val: bigint | number): xdr.ScVal {
+ return xdr.ScVal.scvU64(xdr.Uint64.fromString(val.toString()));
+}
+
+/** Encode a boolean as ScVal */
+export function boolToScVal(val: boolean): xdr.ScVal {
+ return xdr.ScVal.scvBool(val);
+}
+
+function sleep(ms: number): Promise<void> {
+ return new Promise(r => setTimeout(r, ms));
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 +461 +462 +463 +464 +465 +466 +467 +468 +469 +470 +471 +472 +473 +474 +475 +476 +477 +478 +479 +480 +481 +482 +483 +484 +485 +486 +487 +488 +489 +490 +491 +492 +493 +494 +495 +496 +497 +498 +499 +500 +501 +502 +503 +504 +505 +506 +507 +508 +509 +510 +511 +512 +513 +514 +515 +516 +517 +518 +519 +520 +521 +522 +523 +524 +525 +526 +527 +528 +529 +530 +531 +532 +533 +534 +535 +536 +537 +538 +539 +540 +541 +542 +543 +544 +545 +546 +547 +548 +549 +550 +551 +552 +553 +554 +555 +556 +557 +558 +559 +560 +561 +562 +563 +564 +565 +566 +567 +568 +569 +570 +571 +572 +573 +574 +575 | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +22x + + + + + + + + + + + + +17x + + +17x +16x +4x +4x + + + + + + + + + + + + + + +102x +102x +102x +102x +102x + +102x +8x +94x +46x + + + + + + + +4x + + + +1x + + + +105x +2x +2x + +103x +95x +46x + + + + + + + + +40x +10x +10x + +31x +30x +29x + + + + + + + + + + + + + + + + + +17x +17x + + + + +16x + + +16x +1x + +15x +1x + +14x +1x + +13x +1x + +12x +1x + +11x +2x + + +9x + + +17x + +7x +7x + + +17x +17x + +17x + + + + + + + + + + +17x +7x +7x + +7x +1x + + +6x +6x +6x + +3x +1x + +2x + +2x +17x + + + + +34x +34x +33x +33x +33x +32x + + + + +1x +1x +1x +1x +1x +1x + + + + +2x +2x +2x + + + + + + + + + + + + + + + + + +6x + +6x +10x + + +5x +10x +10x +8x + +2x +2x + + + + + + + + + +2x +2x + + + + +4x +4x + + + + +2x +2x + + + + +2x +2x + + + + + + + + + +3x +3x +2x +2x +2x +2x + +2x +1x + + +1x +1x +1x + +1x + + +1x + + + + + + + + +17x +17x + + + + + +17x + +5x +5x + + + +5x +3x + +2x + + +14x +2x + +14x + +14x +13x +32x +13x +13x +13x + + + + + + + + + + + +14x +10x +4x +3x + + + +1x + + + + + + + +6x +6x +4x +4x + + + + +5x +5x + +5x +4x + +1x +1x +1x + + +5x + +5x +5x +1x +1x + + +5x + + + + + + + +24x +8x + + + + +28x +25x + +3x +1x + +2x +1x + +1x + + + +20x +16x + + +16x +2x + +14x + + +14x + +4x +3x +3x +1x + +3x + +1x +1x +1x + + + + + +50x +25x + + + +50x + + + +44x +44x +43x + + + +34x +34x +34x +1x + +33x +33x + + + + +7x +7x +7x +7x +7x + + +7x +7x +7x +5x + + + + + + + +18x +18x + +1x + +17x +2x + +15x +15x +18x +18x +19x + +19x +19x + +1x + +18x +10x + +8x +2x + + +2x + + + + + + +32x +32x +32x + + + +32x + + + + + + + + + + + + + + +32x +32x + + + +19x + + | /**
+ * StreamsModule - all DripStream + DripFactory operations.
+ */
+
+import { SorobanRpc, nativeToScVal, xdr, Address, Transaction } from '@stellar/stellar-sdk';
+import type { Signer } from './signer.js';
+import type {
+ ConduitConfig,
+ CreateStreamParams,
+ CreateStreamResult,
+ ListStreamsParams,
+ PaginatedStreams,
+ StreamEventHandlers,
+ StreamInfo,
+ Subscription,
+ BatchWithdrawItem,
+ BatchWithdrawResult,
+} from './types/index.js';
+import type { WalletAdapter } from './adapters/types.js';
+import { KeypairWalletAdapter } from './adapters/keypair.js';
+import { toStroops, calculateRate, bigintSafeStringify } from './utils.js';
+import {
+ buildContractCallTx,
+ scValToI128,
+ scValToU64,
+ boolToScVal,
+ getTokenDecimals,
+ DEFAULT_RPC,
+ NETWORK_PASSPHRASE,
+ DEFAULT_CONFIRMATION_MAX_ATTEMPTS,
+ DEFAULT_CONFIRMATION_POLL_INTERVAL_MS,
+} from './soroban.js';
+import { FactoryModule } from './factory.js';
+import { ConduitError, RateLimitError, StreamErrorCode } from './errors.js';
+
+// Deprecation warnings
+
+/**
+ * Tracks which v1-deprecated methods have already warned this session, so
+ * repeated calls (e.g. in a hot loop) do not spam the console.
+ */
+const _warnedDeprecations = new Set<string>();
+
+/**
+ * Logs a one-time console warning for a deprecated v1 method, but only in
+ * development mode. Safe to call in browser bundles: guards `process` with
+ * a `typeof` check since it is not guaranteed to exist outside Node/bundlers
+ * that define it at build time.
+ *
+ * @param methodName - The deprecated method, e.g. 'StreamsModule.create()'.
+ * @param replacement - The suggested replacement, e.g. 'StreamBuilder'.
+ */
+function warnV1Deprecated(methodName: string, replacement: string): void {
+ const isDev =
+ typeof process !== 'undefined' &&
+ typeof process.env !== 'undefined' &&
+ process.env.NODE_ENV !== 'production';
+ if (!isDev) return;
+ if (_warnedDeprecations.has(methodName)) return;
+ _warnedDeprecations.add(methodName);
+ console.warn(
+ `[conduit-sdk] ${methodName} is deprecated and will be removed in a future ` +
+ `major version. Use ${replacement} instead.`,
+ );
+}
+import { ZERO_ADDR } from './constants.js';
+
+export class StreamsModule {
+ private readonly rpcUrl: string;
+ private readonly passphrase: string;
+ private readonly callerAddr: string;
+ private readonly _factory: FactoryModule;
+ private _cachedServer?: SorobanRpc.Server;
+ private activeWallet?: WalletAdapter;
+
+ constructor(private readonly config: ConduitConfig) {
+ this.rpcUrl = config.rpcUrl ?? DEFAULT_RPC[config.network];
+ this.passphrase = NETWORK_PASSPHRASE[config.network];
+ this.callerAddr = this._signerPublicKey();
+ this._factory = new FactoryModule(config);
+
+ if (config.wallet) {
+ this.activeWallet = config.wallet;
+ } else if (config.keypair) {
+ this.activeWallet = new KeypairWalletAdapter(config.keypair);
+ }
+ }
+
+ /**
+ * Dynamically set or update the active wallet adapter.
+ */
+ setWallet(wallet: WalletAdapter): void {
+ this.activeWallet = wallet;
+ }
+
+ private _signer(): Signer | null {
+ return this.config.signer ?? null;
+ }
+
+ private _signerPublicKey(): string {
+ if (this.activeWallet) {
+ const pk = this.activeWallet.getPublicKey();
+ Eif (typeof pk === 'string') return pk;
+ }
+ if (this.config.signer) return this.config.signer.publicKey();
+ if (this.config.keypair) return this.config.keypair.publicKey();
+ return ZERO_ADDR;
+ }
+
+ /**
+ * Resolve the caller address, handling both sync and async getPublicKey().
+ * Unlike _signerPublicKey(), this can be used when the wallet adapter
+ * returns a promise - but it MUST only be called from async contexts.
+ */
+ private async _resolveCallerAddress(): Promise<string> {
+ if (this.activeWallet) {
+ const pk = await this.activeWallet.getPublicKey();
+ if (pk) return pk;
+ }
+ if (this.config.signer) return this.config.signer.publicKey();
+ if (this.config.keypair) return this.config.keypair.publicKey();
+ return ZERO_ADDR;
+ }
+
+ /**
+ /**
+ * Deploy a new DripStream via DripFactory.
+ *
+ * Simulates first to extract the assigned stream ID from the return value,
+ * then signs and submits the assembled transaction.
+ *
+ * @deprecated Use {@link StreamBuilder} instead (see `builder.ts`), which
+ * provides a fluent `.token().sender().recipient().amount().ratePerSecond()`
+ * config API plus `.build()` / `.submit()` with built-in concurrency and
+ * backpressure handling. This method will be removed in a future major
+ * version. In development mode (`NODE_ENV !== 'production'`) this method
+ * logs a one-time console warning when invoked.
+ */
+ async create(params: CreateStreamParams): Promise<CreateStreamResult> {
+ warnV1Deprecated('StreamsModule.create()', 'StreamBuilder');
+ const senderAddr = await this._getSenderAddress();
+ const {
+ recipient, token, depositAmount,
+ durationSeconds, ratePerSecond,
+ startTime, clawbackEnabled = false,
+ } = params;
+
+ // Client-side validation to prevent invalid payloads
+ if (!recipient || typeof recipient !== 'string' || !recipient.trim()) {
+ throw new Error('Invalid recipient address: must be a non-empty string');
+ }
+ if (!token || typeof token !== 'string' || !token.trim()) {
+ throw new Error('Invalid token address: must be a non-empty string');
+ }
+ if (!depositAmount || typeof depositAmount !== 'string' || !depositAmount.trim()) {
+ throw new Error('Invalid deposit amount: must be a non-empty string');
+ }
+ if (durationSeconds !== undefined && (typeof durationSeconds !== 'number' || durationSeconds <= 0)) {
+ throw new Error('Invalid durationSeconds: must be a positive number');
+ }
+ if (ratePerSecond !== undefined && (typeof ratePerSecond !== 'string' || !ratePerSecond.trim())) {
+ throw new Error('Invalid ratePerSecond: must be a non-empty string');
+ }
+ if (!durationSeconds && !ratePerSecond) {
+ throw new Error('Either durationSeconds or ratePerSecond must be provided');
+ }
+
+ const factoryId = this.config.factoryAddress ?? '';
+
+ // Query token decimals
+ const decimals = await getTokenDecimals(this.rpcUrl, this.passphrase, senderAddr, token);
+
+ const depositStroops = toStroops(depositAmount, decimals);
+ const rateStroops = ratePerSecond
+ ? BigInt(ratePerSecond)
+ : calculateRate(depositAmount, durationSeconds!, decimals);
+ const start = startTime ?? Math.floor(Date.now() / 1000);
+ const end = durationSeconds ? start + durationSeconds : 0;
+
+ const args = [
+ new Address(senderAddr).toScVal(),
+ new Address(recipient).toScVal(),
+ new Address(token).toScVal(),
+ nativeToScVal(depositStroops, { type: 'i128' }),
+ nativeToScVal(rateStroops, { type: 'i128' }),
+ nativeToScVal(start, { type: 'u64' }),
+ nativeToScVal(end, { type: 'u64' }),
+ boolToScVal(clawbackEnabled),
+ ];
+
+ const tx = await buildContractCallTx(this.rpcUrl, this.passphrase, senderAddr, factoryId, 'create_stream', args);
+ const server = this._server();
+ const sim = await server.simulateTransaction(tx);
+
+ if (SorobanRpc.Api.isSimulationError(sim)) {
+ throw ConduitError.fromSorobanMessage('factory', sim.error);
+ }
+
+ const assembled = SorobanRpc.assembleTransaction(tx, sim).build();
+ const signed = await this._signTx(assembled);
+ const { hash: txHash, returnValue } = await this._sendAndPoll(server, signed);
+
+ if (!returnValue) {
+ throw new Error(`Transaction ${txHash} succeeded but returned no value`);
+ }
+ const streamId = scValToU64(returnValue);
+
+ const streamAddress = await this._factory.streamAddress(streamId) ?? '';
+ return { streamId, streamAddress, txHash };
+ }
+
+ /** Fetch full stream state from the deployed DripStream contract. */
+ async get(streamId: bigint | string): Promise<StreamInfo> {
+ const id = BigInt(streamId);
+ const addr = await this._resolveAddr(id);
+ const caller = await this._resolveCallerAddress();
+ const tx = await buildContractCallTx(this.rpcUrl, this.passphrase, caller, addr, 'info', []);
+ const val = await this._simulateTx(tx);
+ return parseStreamInfo(id, addr, val);
+ }
+
+ /** Get withdrawable balance - read-only, no transaction. */
+ async withdrawable(streamId: bigint | string): Promise<bigint> {
+ const id = BigInt(streamId);
+ const addr = await this._resolveAddr(id);
+ const caller = await this._resolveCallerAddress();
+ const tx = await buildContractCallTx(this.rpcUrl, this.passphrase, caller, addr, 'withdrawable', []);
+ const val = await this._simulateTx(tx);
+ return scValToI128(val);
+ }
+
+ /** Withdraw tokens as the recipient. Defaults to full available balance. */
+ async withdraw(streamId: bigint | string, amount?: bigint): Promise<string> {
+ this._ensureCanMutate();
+ const id = BigInt(streamId);
+ const qty = amount ?? await this.withdrawable(id);
+ return this._invoke(await this._resolveAddr(id), 'withdraw', [
+ nativeToScVal(qty, { type: 'i128' }),
+ ]);
+ }
+
+ /**
+ * Withdraw from multiple streams concurrently.
+ *
+ * Note: Soroban currently permits only one invoke_host_function
+ * operation per transaction, so this cannot be assembled into a single
+ * atomic transaction the way classic Stellar payment operations can.
+ * Each withdrawal is submitted as its own transaction; they run
+ * concurrently and are reported independently so a failure on one
+ * streamId (e.g. StreamNotFound, insufficient balance) does not block
+ * or roll back the others.
+ */
+ async batchWithdraw(withdrawals: BatchWithdrawItem[]): Promise<BatchWithdrawResult[]> {
+ this._ensureCanMutate();
+
+ const settled = await Promise.allSettled(
+ withdrawals.map(w => this.withdraw(w.streamId, w.amount)),
+ );
+
+ return settled.map((result, i) => {
+ const streamId = BigInt(withdrawals[i]!.streamId);
+ if (result.status === 'fulfilled') {
+ return { streamId, success: true, txHash: result.value };
+ }
+ const err = result.reason;
+ return {
+ streamId,
+ success: false,
+ error: err instanceof Error ? err.message : String(err),
+ };
+ });
+ }
+
+ /** Cancel the stream (sender only). Settles all balances atomically. */
+ async cancel(streamId: bigint | string): Promise<string> {
+ this._ensureCanMutate();
+ return this._invoke(await this._resolveAddr(BigInt(streamId)), 'cancel', []);
+ }
+
+ /** Pause the stream (sender only). */
+ async pause(streamId: bigint | string): Promise<string> {
+ this._ensureCanMutate();
+ return this._invoke(await this._resolveAddr(BigInt(streamId)), 'pause', []);
+ }
+
+ /** Resume a paused stream (sender only). Shifts start/end times forward. */
+ async resume(streamId: bigint | string): Promise<string> {
+ this._ensureCanMutate();
+ return this._invoke(await this._resolveAddr(BigInt(streamId)), 'resume', []);
+ }
+
+ /** Deposit additional tokens into the stream (sender only). */
+ async topUp(streamId: bigint | string, amount: bigint): Promise<string> {
+ this._ensureCanMutate();
+ return this._invoke(await this._resolveAddr(BigInt(streamId)), 'top_up', [
+ nativeToScVal(amount, { type: 'i128' }),
+ ]);
+ }
+
+ /**
+ * Clawback unstreamed tokens (sender; only if enabled at creation).
+ * Returns the amount reclaimed (simulated before submission).
+ */
+ async clawback(streamId: bigint | string): Promise<bigint> {
+ this._ensureCanMutate();
+ const addr = await this._resolveAddr(BigInt(streamId));
+ const caller = await this._getSenderAddress();
+ const tx = await buildContractCallTx(this.rpcUrl, this.passphrase, caller, addr, 'clawback', []);
+ const server = this._server();
+ const sim = await server.simulateTransaction(tx);
+
+ if (SorobanRpc.Api.isSimulationError(sim)) {
+ throw ConduitError.fromSorobanMessage('stream', sim.error);
+ }
+
+ const assembled = SorobanRpc.assembleTransaction(tx, sim).build();
+ const signed = await this._signTx(assembled);
+ const { hash, returnValue } = await this._sendAndPoll(server, signed);
+
+ Iif (!returnValue) {
+ throw new Error(`Transaction ${hash} succeeded but returned no value`);
+ }
+ return scValToI128(returnValue);
+ }
+
+ /**
+ * List streams by sender or recipient with pagination metadata.
+ * Returns a page of StreamInfo along with pagination metadata so the
+ * frontend can implement infinite scrolling.
+ */
+ async list(params: ListStreamsParams): Promise<PaginatedStreams> {
+ const { sender, recipient, limit = 20 } = params;
+ let offset = params.offset ?? 0;
+
+ // A cursor from a previous page's nextCursor takes precedence over a
+ // manually-supplied offset. Cursors are opaque base64-encoded offset
+ // strings; anything that doesn't decode to a non-negative integer is
+ // rejected rather than silently falling back to page 1 (see #124).
+ if (params.cursor !== undefined) {
+ let decoded: string;
+ try {
+ decoded = Buffer.from(params.cursor, 'base64').toString('utf8');
+ } catch {
+ throw new Error(`Invalid cursor: "${params.cursor}"`);
+ }
+ if (!/^\d+$/.test(decoded)) {
+ throw new Error(`Invalid cursor: "${params.cursor}"`);
+ }
+ offset = Number(decoded);
+ }
+
+ const encodeCursor = (nextOffset: number): string =>
+ Buffer.from(String(nextOffset), 'utf8').toString('base64');
+
+ let ids: bigint[] = [];
+
+ const pageFromFilteredIds = async (filteredIds: bigint[]): Promise<PaginatedStreams> => {
+ ids = filteredIds;
+ const streams = await Promise.all(ids.map(id => this.get(id)));
+ const hasNextPage = ids.length === limit;
+ const totalCount = BigInt(offset + ids.length);
+ return {
+ streams,
+ hasNextPage,
+ totalCount,
+ offset,
+ limit,
+ ...(hasNextPage ? { nextCursor: encodeCursor(offset + limit) } : {}),
+ };
+ };
+
+ // Sender/recipient contract queries already return the filtered page.
+ // There is no scoped count method, so do not mix in global stream_count().
+ if (sender) {
+ return pageFromFilteredIds(await this._factory.streamsBySender(sender, offset, limit));
+ } else if (recipient) {
+ return pageFromFilteredIds(await this._factory.streamsByRecipient(recipient, offset, limit));
+ }
+
+ // Neither sender nor recipient - return empty page
+ return { streams: [], hasNextPage: false, totalCount: 0n, offset, limit };
+ }
+
+ /** Subscribe to on-chain stream events via polling. Returns an async subscription handle. */
+ async subscribeAsync(
+ streamId: bigint | string,
+ handlers: StreamEventHandlers,
+ ): Promise<Subscription> {
+ const address = await this._factory.streamAddress(BigInt(streamId));
+ if (!address) throw new Error(`Stream ${streamId} not found`);
+ const { subscribeToStream } = await import('./events.js');
+ return subscribeToStream(this.config.rpcUrl!, address, handlers);
+ }
+
+ /** Synchronous subscribe - resolves address lazily on first poll tick. */
+ subscribe(streamId: bigint | string, handlers: StreamEventHandlers): Subscription {
+ let inner: Subscription | null = null;
+ let stopped = false;
+
+ this.subscribeAsync(streamId, handlers)
+ .then(sub => { if (!stopped) inner = sub; else sub.unsubscribe(); })
+ .catch(err => {
+ const error = err instanceof Error ? err : new Error(String(err));
+ handlers.onError?.(error);
+ console.warn('[conduit-sdk] subscribe error:', error);
+ });
+
+ return {
+ unsubscribe: () => {
+ stopped = true;
+ if (inner) {
+ inner.unsubscribe();
+ inner = null;
+ }
+ // Release handler references to prevent memory leaks
+ handlers = {};
+ },
+ };
+ }
+
+ // Private helpers
+
+ private _ensureCanMutate(): void {
+ if (!this.activeWallet && !this.config.signer && !this.config.keypair) {
+ throw new Error('keypair, wallet adapter, or signer is required for mutating operations');
+ }
+ }
+
+ private async _getSenderAddress(): Promise<string> {
+ if (this.activeWallet) {
+ return this.activeWallet.getPublicKey();
+ }
+ if (this.config.signer) {
+ return this.config.signer.publicKey();
+ }
+ if (this.config.keypair) {
+ return this.config.keypair.publicKey();
+ }
+ throw new Error('keypair, wallet adapter, or signer is required for mutating operations');
+ }
+
+ private async _signTx(tx: Transaction): Promise<Transaction> {
+ if (this.activeWallet) {
+ const signed = await this.activeWallet.signTransaction(tx, {
+ networkPassphrase: this.passphrase,
+ });
+ if (signed == null) {
+ throw new Error('Wallet adapter signTransaction returned null or undefined');
+ }
+ Iif (typeof signed === 'string') {
+ return new Transaction(signed, this.passphrase);
+ }
+ return signed;
+ }
+ if (this.config.signer) {
+ const result = this.config.signer.sign(tx);
+ if (result != null) {
+ await result;
+ }
+ return tx;
+ }
+ Eif (this.config.keypair) {
+ tx.sign(this.config.keypair);
+ return tx;
+ }
+ throw new Error('keypair, wallet adapter, or signer is required for mutating operations');
+ }
+
+ private _server(): SorobanRpc.Server {
+ if (!this._cachedServer) {
+ this._cachedServer = new SorobanRpc.Server(this.rpcUrl, {
+ allowHttp: this.rpcUrl.startsWith('http://'),
+ });
+ }
+ return this._cachedServer;
+ }
+
+ private async _resolveAddr(id: bigint): Promise<string> {
+ const addr = await this._factory.streamAddress(id);
+ if (!addr) throw new ConduitError('stream', StreamErrorCode.StreamNotFound, `Stream ${id} not found`);
+ return addr;
+ }
+
+ private async _simulateTx(tx: Transaction): Promise<xdr.ScVal> {
+ const server = this._server();
+ const result = await server.simulateTransaction(tx);
+ if (SorobanRpc.Api.isSimulationError(result)) {
+ throw ConduitError.fromSorobanMessage('stream', result.error);
+ }
+ Iif (!result.result) throw new Error('Simulation returned no result');
+ return xdr.ScVal.fromXDR(result.result.retval.toXDR());
+ }
+
+ /** Simulate -> assemble -> sign -> submit -> poll. Returns txHash. */
+ private async _invoke(contractId: string, method: string, args: xdr.ScVal[]): Promise<string> {
+ const senderAddr = await this._getSenderAddress();
+ const tx = await buildContractCallTx(this.rpcUrl, this.passphrase, senderAddr, contractId, method, args);
+ const server = this._server();
+ const sim = await server.simulateTransaction(tx);
+ Iif (SorobanRpc.Api.isSimulationError(sim)) {
+ throw ConduitError.fromSorobanMessage('stream', sim.error);
+ }
+ const assembled = SorobanRpc.assembleTransaction(tx, sim).build();
+ const signed = await this._signTx(assembled);
+ const { hash } = await this._sendAndPoll(server, signed);
+ return hash;
+ }
+
+ private async _sendAndPoll(
+ server: SorobanRpc.Server,
+ tx: Transaction,
+ ): Promise<{ hash: string; returnValue: xdr.ScVal | undefined }> {
+ let sent;
+ try {
+ sent = await server.sendTransaction(tx);
+ } catch (err) {
+ throw RateLimitError.fromRpcError(err) ?? err;
+ }
+ if (sent.status === 'ERROR') {
+ throw new Error(`Transaction rejected: ${JSON.stringify(sent.errorResult)}`);
+ }
+ const hash = sent.hash;
+ const maxAttempts = this.config.confirmationMaxAttempts ?? DEFAULT_CONFIRMATION_MAX_ATTEMPTS;
+ const pollIntervalMs = this.config.confirmationPollIntervalMs ?? DEFAULT_CONFIRMATION_POLL_INTERVAL_MS;
+ for (let i = 0; i < maxAttempts; i++) {
+ await sleep(pollIntervalMs);
+ let s;
+ try {
+ s = await server.getTransaction(hash);
+ } catch (err) {
+ throw RateLimitError.fromRpcError(err) ?? err;
+ }
+ if (s.status === SorobanRpc.Api.GetTransactionStatus.SUCCESS) {
+ return { hash, returnValue: s.returnValue };
+ }
+ if (s.status === SorobanRpc.Api.GetTransactionStatus.FAILED) {
+ throw new Error(`Transaction failed: ${hash}`);
+ }
+ }
+ throw new Error(`Transaction timed out: ${hash}`);
+ }
+}
+
+// Parsing
+
+function parseStreamInfo(id: bigint, address: string, val: xdr.ScVal): StreamInfo {
+ const entries = val.map() ?? [];
+ const m: Record<string, xdr.ScVal> = {};
+ for (const e of entries) {
+ const k = e.key().sym()?.toString('utf8') ?? e.key().str()?.toString('utf8') ?? '';
+ m[k] = e.val();
+ }
+ const info: StreamInfo = {
+ id,
+ address,
+ sender: m['sender'] ? Address.fromScVal(m['sender']).toString() : '',
+ recipient: m['recipient'] ? Address.fromScVal(m['recipient']).toString() : '',
+ token: m['token'] ? Address.fromScVal(m['token']).toString() : '',
+ ratePerSecond: m['rate_per_second'] ? scValToI128(m['rate_per_second']) : 0n,
+ startTime: m['start_time'] ? Number(scValToU64(m['start_time'])) : 0,
+ endTime: m['end_time'] ? Number(scValToU64(m['end_time'])) : 0,
+ withdrawn: m['withdrawn'] ? scValToI128(m['withdrawn']) : 0n,
+ paused: m['paused']?.b() ?? false,
+ pausedAt: m['paused_at'] ? Number(scValToU64(m['paused_at'])) : 0,
+ cancelled: m['cancelled']?.b() ?? false,
+ clawbackEnabled: m['clawback_enabled']?.b() ?? false,
+ };
+ (info as StreamInfo & { toJSON(): Record<string, unknown> }).toJSON = () => bigintSafeStringify(info as unknown as Record<string, unknown>);
+ return info;
+}
+
+function sleep(ms: number): Promise<void> {
+ return new Promise(r => setTimeout(r, ms));
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| File | ++ | Statements | ++ | Branches | ++ | Functions | ++ | Lines | ++ |
|---|---|---|---|---|---|---|---|---|---|
| index.ts | +
+
+ |
+ 0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +0% | +0/0 | +
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + | import type { Signer } from '../signer.js';
+
+export type Network = 'mainnet' | 'testnet' | 'local';
+
+/** Configuration returned by StreamBuilder.build() */
+export interface StreamConfig {
+ token: string;
+ sender: string;
+ recipient: string;
+ amount: number;
+ ratePerSecond?: string;
+}
+
+/** A Stellar account address (G... string) */
+export type Recipient = string;
+
+export interface ConduitConfig {
+ /** Network to connect to */
+ network: Network;
+ /** Signing keypair — required for mutating operations */
+ keypair?: import('@stellar/stellar-sdk').Keypair;
+ /** Custom wallet adapter (e.g. WalletConnectAdapter) for browser/mobile wallet signing */
+ wallet?: import('../adapters/types.js').WalletAdapter;
+ /** Custom signer plugin (KMS/HSM). Takes precedence over keypair when set. */
+ signer?: Signer;
+ /** Override default Soroban RPC URL */
+ rpcUrl?: string;
+ /** Override deployed DripFactory contract ID */
+ factoryAddress?: string;
+ /** Override deployed DripGovernor contract ID */
+ governorAddress?: string;
+ /** Override Soroban confirmation poll interval in ms; default 1000 */
+ confirmationPollIntervalMs?: number;
+ /** Override Soroban confirmation polling attempts; default 30 */
+ confirmationMaxAttempts?: number;
+}
+
+export interface StreamInfo {
+ id: bigint;
+ /** DripStream contract address */
+ address: string;
+ sender: string;
+ recipient: string;
+ /** Token contract address or 'native' */
+ token: string;
+ /** Tokens released per second, in stroops */
+ ratePerSecond: bigint;
+ /** Unix timestamp */
+ startTime: number;
+ /** Unix timestamp; 0 = open-ended */
+ endTime: number;
+ /** Total withdrawn by recipient so far, in stroops */
+ withdrawn: bigint;
+ paused: boolean;
+ /** Timestamp when stream was last paused; 0 if not paused */
+ pausedAt: number;
+ cancelled: boolean;
+ clawbackEnabled: boolean;
+}
+
+/** On-chain state of a stream — alias for StreamInfo */
+export type StreamState = StreamInfo;
+
+export interface CreateStreamParams {
+ /** Stellar recipient address */
+ recipient: string;
+ /** 'native' (XLM), 'USDC', or a contract address */
+ token: string;
+ /** Total deposit in display units (e.g. '1000') */
+ depositAmount: string;
+ /** Stream duration in seconds (mutually exclusive with ratePerSecond) */
+ durationSeconds?: number;
+ /** Unix timestamp; defaults to current ledger time */
+ startTime?: number;
+ /** Whether the sender can claw back unstreamed tokens */
+ clawbackEnabled?: boolean;
+ /** Override rate in stroops/s (mutually exclusive with durationSeconds) */
+ ratePerSecond?: string;
+}
+
+export interface CreateStreamResult {
+ streamId: bigint;
+ streamAddress: string;
+ txHash: string;
+}
+
+export interface ListStreamsParams {
+ sender?: string;
+ recipient?: string;
+ offset?: number;
+ limit?: number;
+ /** Opaque pagination cursor from a previous page's `nextCursor`. Takes precedence over `offset` if both are given. */
+ cursor?: string;
+}
+
+export interface PaginatedStreams {
+ /** The stream info results for this page */
+ streams: StreamInfo[];
+ /** Whether there are more results after this page */
+ hasNextPage: boolean;
+ /** Number of filtered stream IDs seen through the end of this page */
+ totalCount: bigint;
+ /** The offset used for this page */
+ offset: number;
+ /** The limit used for this page */
+ limit: number;
+ /** Opaque cursor to pass as `cursor` to fetch the next page. Present only when `hasNextPage` is true. */
+ nextCursor?: string;
+}
+
+export interface GovernorConfig {
+ feeBps: number;
+ feeRecipient?: string;
+ minDurationSeconds: number;
+ maxRatePerSecond: bigint;
+ factoryAddress?: string;
+}
+
+// ── Events ──────────────────────────────────────────────────────────────────
+
+export interface WithdrawEvent { amount: bigint; recipient: string; totalWithdrawn: bigint; remaining: bigint; }
+export interface CancelEvent { refundAmount: bigint; withdrawnSoFar: bigint; sender: string; }
+export interface PauseEvent { pausedAt: number; withdrawable: bigint; sender: string; }
+export interface ResumeEvent { resumedAt: number; sender: string; }
+export interface TopUpEvent { amount: bigint; newBalance: bigint; sender: string; }
+export interface ClawbackEvent { amount: bigint; sender: string; }
+
+export interface StreamEventHandlers {
+ onWithdraw?: (e: WithdrawEvent) => void;
+ onCancel?: (e: CancelEvent) => void;
+ onPause?: (e: PauseEvent) => void;
+ onResume?: (e: ResumeEvent) => void;
+ onTopUp?: (e: TopUpEvent) => void;
+ onClawback?: (e: ClawbackEvent) => void;
+ onError?: (error: Error) => void;
+ /** Polling interval in ms; default 5000 */
+ pollInterval?: number;
+}
+
+export interface Subscription {
+ unsubscribe: () => void;
+}
+
+// -- Batch operations ----------------------------------------------------------
+
+export interface BatchWithdrawItem {
+ streamId: bigint | string;
+ /** Amount in stroops. Defaults to the full withdrawable balance if omitted. */
+ amount?: bigint;
+}
+
+export interface BatchWithdrawResult {
+ streamId: bigint;
+ success: boolean;
+ txHash?: string;
+ error?: string;
+}
+ |
+ Press n or j to go to the next uncovered block, b, p or k for the previous block. +
+ +| 1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 | + + +29x + + +41x +41x +3x +3x + +41x + + + + + + + + +34x +34x +20x + +14x +34x +34x + +34x +34x +4x +4x +3x + + +14x + + + + +7x +7x +7x +7x +26x +7x +7x + + + + + + + + + + +14x +14x +14x +13x +13x + +13x + + + + + + + + +4x +4x +3x +2x +1x + + + + + + + +6x + +5x + + + + + +6x + +4x +4x + +4x +4x +4x + + + + + + + + + + + + + + + + +573x + + + +2145x + +299x + +1846x +685x +685x + +685x +2x +2x +2x +8x + +2x + + +683x +683x +683x +683x +1564x +1564x + +683x + + + + + + + + + + + + +8x +3x + +5x + + | import type { StreamInfo } from './types/index.js';
+import { StrKey } from '@stellar/stellar-sdk';
+
+const _powCache: Record<number, bigint> = {};
+
+function _pow10(decimals: number): bigint {
+ let p = _powCache[decimals];
+ if (!p) {
+ p = BigInt(10) ** BigInt(decimals);
+ _powCache[decimals] = p;
+ }
+ return p;
+}
+
+/** Convert a display amount string to stroops (bigint).
+ *
+ * Cache-friendly — `10 ** decimals` is computed once per unique `decimals`
+ * value and reused across calls, avoiding repeated BigInt exponentiation.
+ */
+export function toStroops(amount: string, decimals = 7): bigint {
+ const dot = amount.indexOf('.');
+ if (dot === -1) {
+ return BigInt(amount) * _pow10(decimals);
+ }
+ const whole = amount.slice(0, dot) || '0';
+ const frac = amount.slice(dot + 1, dot + 1 + decimals);
+ const rest = amount.slice(dot + 1 + decimals);
+
+ let base = BigInt(whole) * _pow10(decimals) + BigInt(frac.padEnd(decimals, '0'));
+ if (rest) {
+ const roundingDigit = rest.charCodeAt(0) /* '0' … '9' */;
+ if (roundingDigit >= 53 /* charCode of '5' */) {
+ base += 1n;
+ }
+ }
+ return base;
+}
+
+/** Convert stroops (bigint) to a display amount string */
+export function fromStroops(stroops: bigint, decimals = 7): string {
+ const factor = _pow10(decimals);
+ const whole = stroops / factor;
+ const frac = (stroops % factor).toString().padStart(decimals, '0');
+ let end = frac.length;
+ while (end > 0 && frac.charCodeAt(end - 1) === 48 /* '0' */) end--;
+ const trimmed = end === 0 ? '0' : frac.slice(0, end);
+ return `${whole}.${trimmed}`;
+}
+
+/**
+ * Calculate the rate per second (in stroops) from a total deposit and duration.
+ *
+ * @param depositAmount Display amount string, e.g. '1000'
+ * @param durationSecs Duration in seconds
+ * @param decimals Token decimal places (default 7 for Stellar assets)
+ */
+export function calculateRate(depositAmount: string, durationSecs: number, decimals = 7): bigint {
+ const stroops = toStroops(depositAmount, decimals);
+ const divisor = BigInt(durationSecs);
+ if (divisor === 0n) return 0n;
+ const quotient = stroops / divisor;
+ const remainder = stroops % divisor;
+ // Round to nearest: if remainder >= half the divisor, round up
+ return remainder * 2n >= divisor ? quotient + 1n : quotient;
+}
+
+/**
+ * Current progress fraction (0-1) of a stream.
+ * Returns 0 if not started, 1 if ended, and NaN for open-ended streams
+ * that have started but do not have a finite completion percentage.
+ */
+export function streamProgress(stream: StreamInfo, nowSec = Math.floor(Date.now() / 1000)): number {
+ const { startTime, endTime } = stream;
+ if (nowSec < startTime) return 0;
+ if (endTime === 0) return Number.NaN; // open-ended
+ if (nowSec >= endTime) return 1;
+ return (nowSec - startTime) / (endTime - startTime);
+}
+
+/**
+ * Current withdrawable balance from a StreamInfo snapshot, without a contract call.
+ * Accounts for pause state.
+ */
+export function withdrawableLocal(stream: StreamInfo, nowSec = Math.floor(Date.now() / 1000)): bigint {
+ if (stream.cancelled) return 0n;
+
+ const effectiveNow = stream.paused
+ ? stream.pausedAt
+ : stream.endTime > 0 && nowSec > stream.endTime
+ ? stream.endTime
+ : nowSec;
+
+ if (effectiveNow < stream.startTime) return 0n;
+
+ const elapsed = effectiveNow - stream.startTime;
+ Iif (elapsed <= 0) return 0n;
+
+ const streamed = stream.ratePerSecond * BigInt(elapsed);
+ const available = streamed - stream.withdrawn;
+ return available > 0n ? available : 0n;
+}
+
+/**
+ * Recursively convert all bigint values in a value to their string
+ * representation. Safe for objects, arrays, and primitives.
+ *
+ * Safari / WebKit serialises `bigint` values as `{}` inside
+ * `JSON.stringify`, which breaks payloads sent to the GraphQL
+ * indexer. Call this before network submission to guarantee
+ * interoperability across all browsers.
+ *
+ * Uses a `WeakSet` to handle circular references without infinite
+ * recursion, and iterates with indexed loops instead of `.map()` /
+ * `.entries()` to minimise per-element allocations.
+ */
+export function bigintSafeStringify<T>(value: T): T {
+ return _safeStringify(value, new WeakSet());
+}
+
+function _safeStringify<T>(value: T, visited: WeakSet<object>): T {
+ if (typeof value === 'bigint') {
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ return value.toString() as any;
+ }
+ if (value === null || typeof value !== 'object') return value;
+ Iif (visited.has(value)) return value as T;
+ visited.add(value);
+
+ if (Array.isArray(value)) {
+ const { length } = value;
+ const out = new Array<unknown>(length);
+ for (let i = 0; i < length; i++) {
+ out[i] = _safeStringify(value[i], visited);
+ }
+ return out as unknown as T;
+ }
+
+ const obj = value as Record<string, unknown>;
+ const keys = Object.keys(obj);
+ const out: Record<string, unknown> = {};
+ for (let i = 0; i < keys.length; i++) {
+ const k = keys[i];
+ out[k] = _safeStringify(obj[k], visited);
+ }
+ return out as T;
+}
+
+/**
+ * Validates whether a string is a well-formed Stellar public key
+ * (account address, e.g. 'GABC...XYZ').
+ *
+ * Performs static format validation only (StrKey encoding, version byte,
+ * checksum) -- it does not check whether the account exists on-chain.
+ * Use this to fail fast before submission, e.g. before passing a recipient
+ * into client.streams.create().
+ */
+export function isValidAddress(address: string): boolean {
+ if (typeof address !== 'string' || address.length === 0) {
+ return false;
+ }
+ return StrKey.isValidEd25519PublicKey(address);
+}
+ |