@augustdigital/sdk 8.9.0 → 8.11.0

package/lib/adapters/stellar/actions.js

@@ -50,10 +50,10 @@ function buildSelfOperationArgs(amount, userAddress) {
  * @returns Base64-encoded XDR of the unsigned transaction, ready for wallet signing.
  */
 async function handleStellarDeposit(params) {
-    const { contractId, amount, senderAddress, network } = params;
+    const { contractId, amount, senderAddress, network, sorobanRpcUrl } = params;
     validateContractAddress(contractId);
     validateAccountAddress(senderAddress, 'sender');
-    const config = (0, soroban_1.resolveNetworkConfig)(network);
+    const config = (0, soroban_1.resolveNetworkConfig)(network, sorobanRpcUrl);
     const args = buildSelfOperationArgs((0, soroban_1.toBigIntAmount)(amount, 'deposit amount'), senderAddress);
     return (0, soroban_1.buildSorobanTx)(config, senderAddress, contractId, 'deposit', args);
 }
@@ -67,10 +67,10 @@ async function handleStellarDeposit(params) {
  *   XDR to {@link submitStellarTransaction}.
  */
 async function handleStellarRedeem(params) {
-    const { contractId, shares, receiverAddress, network } = params;
+    const { contractId, shares, receiverAddress, network, sorobanRpcUrl } = params;
     validateContractAddress(contractId);
     validateAccountAddress(receiverAddress, 'receiver');
-    const config = (0, soroban_1.resolveNetworkConfig)(network);
+    const config = (0, soroban_1.resolveNetworkConfig)(network, sorobanRpcUrl);
     const args = buildSelfOperationArgs((0, soroban_1.toBigIntAmount)(shares, 'redeem shares'), receiverAddress);
     return (0, soroban_1.buildSorobanTx)(config, receiverAddress, contractId, 'redeem', args);
 }

package/lib/adapters/stellar/getters.d.ts

@@ -16,7 +16,7 @@ import type { IStellarNetwork, IStellarUserPosition } from './types';
  * Falls back to backend `latest_reported_tvl` for total assets, or zero
  * for total supply, when on-chain queries fail.
  */
-export declare const getStellarVault: (tokenizedVault: ITokenizedVault, _options: IVaultBaseOptions) => Promise<IVault>;
+export declare const getStellarVault: (tokenizedVault: ITokenizedVault, options: IVaultBaseOptions) => Promise<IVault>;
 /**
  * Get user position for a Stellar vault.
  * Queries the vault contract's balance(address) and decimals() functions via Soroban RPC.
@@ -37,6 +37,9 @@ export declare const getStellarVault: (tokenizedVault: ITokenizedVault, _options
  * @param vaultAddress - Stellar vault contract ID (C… address)
  * @param walletAddress - User's Stellar account (G… address); validated upfront
  * @param network - 'mainnet' | 'testnet' (defaults to 'mainnet')
+ * @param sorobanRpcUrl - Optional override Soroban RPC endpoint (e.g. a keyed
+ *   Alchemy URL); becomes the primary with the SDK's public endpoints kept as
+ *   failover. Omit to use the public endpoints.
  * @returns The position, or `null` if the balance read failed or was unparseable.
  * @throws AugustValidationError on an invalid `walletAddress`.
  * @example
@@ -49,7 +52,7 @@ export declare const getStellarVault: (tokenizedVault: ITokenizedVault, _options
  * const human = Number(pos.shares) / 10 ** pos.decimals;
  * ```
  */
-export declare const getStellarUserPosition: (vaultAddress: string, walletAddress: string, network?: IStellarNetwork) => Promise<IStellarUserPosition | null>;
+export declare const getStellarUserPosition: (vaultAddress: string, walletAddress: string, network?: IStellarNetwork, sorobanRpcUrl?: string) => Promise<IStellarUserPosition | null>;
 /**
  * Query the vault's `convert_to_shares` to preview how many shares a deposit
  * amount would yield.  Returns the raw share amount as a string, or null on
@@ -58,5 +61,8 @@ export declare const getStellarUserPosition: (vaultAddress: string, walletAddres
  * @param vaultAddress  Stellar contract ID (C… address)
  * @param rawAmount     Deposit amount in the deposit token's smallest unit
  * @param network       'mainnet' | 'testnet'
+ * @param sorobanRpcUrl - Optional override Soroban RPC endpoint (e.g. a keyed
+ *   Alchemy URL); becomes the primary with the SDK's public endpoints kept as
+ *   failover. Omit to use the public endpoints.
  */
-export declare const convertToShares: (vaultAddress: string, rawAmount: string, network?: IStellarNetwork) => Promise<string | null>;
+export declare const convertToShares: (vaultAddress: string, rawAmount: string, network?: IStellarNetwork, sorobanRpcUrl?: string) => Promise<string | null>;

package/lib/adapters/stellar/getters.js

@@ -78,7 +78,7 @@ function resolveNetwork(tokenizedVault) {
  * Falls back to backend `latest_reported_tvl` for total assets, or zero
  * for total supply, when on-chain queries fail.
  */
-const getStellarVault = async (tokenizedVault, _options) => {
+const getStellarVault = async (tokenizedVault, options) => {
     const stellarMetadata = tokenizedVault.stellar_vault_metadata;
     const depositDecimals = stellarMetadata?.deposit_token_decimals ?? constants_1.STELLAR_FALLBACK_DECIMALS;
     if (stellarMetadata?.deposit_token_decimals == null) {
@@ -90,7 +90,13 @@ const getStellarVault = async (tokenizedVault, _options) => {
     }
     // Attempt on-chain queries for total assets, total supply, and share decimals
     const network = resolveNetwork(tokenizedVault);
-    const config = (0, soroban_1.resolveNetworkConfig)(network);
+    // Only apply the configured RPC override when it matches this vault's network
+    // (a testnet override must not be used for a mainnet read). `options` may be
+    // omitted by JS callers, so guard it.
+    const overrideRpcUrl = options?.stellarRpc?.network === network
+        ? options.stellarRpc.rpcUrl
+        : undefined;
+    const config = (0, soroban_1.resolveNetworkConfig)(network, overrideRpcUrl);
     const [assetsResult, supplyResult, decimalsResult] = await Promise.all([
         (0, soroban_1.queryContract)(config, tokenizedVault.address, 'total_assets'),
         (0, soroban_1.queryContract)(config, tokenizedVault.address, 'total_supply'),
@@ -171,6 +177,9 @@ exports.getStellarVault = getStellarVault;
  * @param vaultAddress - Stellar vault contract ID (C… address)
  * @param walletAddress - User's Stellar account (G… address); validated upfront
  * @param network - 'mainnet' | 'testnet' (defaults to 'mainnet')
+ * @param sorobanRpcUrl - Optional override Soroban RPC endpoint (e.g. a keyed
+ *   Alchemy URL); becomes the primary with the SDK's public endpoints kept as
+ *   failover. Omit to use the public endpoints.
  * @returns The position, or `null` if the balance read failed or was unparseable.
  * @throws AugustValidationError on an invalid `walletAddress`.
  * @example
@@ -183,8 +192,8 @@ exports.getStellarVault = getStellarVault;
  * const human = Number(pos.shares) / 10 ** pos.decimals;
  * ```
  */
-const getStellarUserPosition = async (vaultAddress, walletAddress, network = 'mainnet') => {
-    const config = (0, soroban_1.resolveNetworkConfig)(network);
+const getStellarUserPosition = async (vaultAddress, walletAddress, network = 'mainnet', sorobanRpcUrl) => {
+    const config = (0, soroban_1.resolveNetworkConfig)(network, sorobanRpcUrl);
     // Validate address upfront — invalid input is a caller bug, not an RPC issue
     let userAddress;
     try {
@@ -243,8 +252,11 @@ exports.getStellarUserPosition = getStellarUserPosition;
  * @param vaultAddress  Stellar contract ID (C… address)
  * @param rawAmount     Deposit amount in the deposit token's smallest unit
  * @param network       'mainnet' | 'testnet'
+ * @param sorobanRpcUrl - Optional override Soroban RPC endpoint (e.g. a keyed
+ *   Alchemy URL); becomes the primary with the SDK's public endpoints kept as
+ *   failover. Omit to use the public endpoints.
  */
-const convertToShares = async (vaultAddress, rawAmount, network = 'mainnet') => {
+const convertToShares = async (vaultAddress, rawAmount, network = 'mainnet', sorobanRpcUrl) => {
     // Validate address upfront — invalid input is a caller bug, not an RPC issue
     try {
         new stellar_sdk_1.Address(vaultAddress);
@@ -252,7 +264,7 @@ const convertToShares = async (vaultAddress, rawAmount, network = 'mainnet') =>
     catch (addrErr) {
         throw new core_1.AugustValidationError('INVALID_ADDRESS', `convertToShares: invalid vaultAddress "${vaultAddress}": ${String(addrErr)}`, { cause: addrErr });
     }
-    const config = (0, soroban_1.resolveNetworkConfig)(network);
+    const config = (0, soroban_1.resolveNetworkConfig)(network, sorobanRpcUrl);
     const amountBigInt = (0, soroban_1.toBigIntAmount)(rawAmount, 'rawAmount');
     const amountScVal = (0, stellar_sdk_1.nativeToScVal)(amountBigInt, { type: 'i128' });
     const result = await (0, soroban_1.queryContract)(config, vaultAddress, 'convert_to_shares', [amountScVal]);

package/lib/adapters/stellar/index.d.ts

@@ -36,9 +36,24 @@ export declare const Stellar: {
  * // Sign xdr with wallet (e.g. Freighter), then submit via adapter.submitTransaction()
  * ```
  */
-declare class StellarAdapter {
+export declare class StellarAdapter {
     private _network;
-    constructor(network?: IStellarNetwork);
+    /**
+     * Optional consumer-supplied Soroban RPC endpoint (e.g. a keyed Alchemy URL).
+     * When set it is the primary, with the SDK's public endpoints as failover.
+     */
+    private _sorobanRpcUrl?;
+    /**
+     * @param network - Stellar network to operate on; defaults to `'mainnet'`.
+     * @param options - Optional adapter configuration. Its `sorobanRpcUrl` field
+     *   overrides the Soroban RPC endpoint (e.g. a keyed Alchemy URL): it becomes
+     *   the primary with the SDK's built-in public endpoints kept behind it as
+     *   failover, and a per-call `sorobanRpcUrl` (on the deposit/redeem params)
+     *   takes precedence over this adapter-level one.
+     */
+    constructor(network?: IStellarNetwork, options?: {
+        sorobanRpcUrl?: string;
+    });
     get network(): IStellarNetwork;
     isStellarAddress(address: string): boolean;
     getExplorerLink(id: string, type?: 'contract' | 'account' | 'tx'): string;

package/lib/adapters/stellar/index.js

@@ -41,7 +41,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Stellar = void 0;
+exports.StellarAdapter = exports.Stellar = void 0;
 const StellarConstants = __importStar(require("./constants"));
 const StellarGetters = __importStar(require("./getters"));
 const StellarActions = __importStar(require("./actions"));
@@ -70,8 +70,22 @@ exports.Stellar = {
  */
 class StellarAdapter {
     _network;
-    constructor(network = 'mainnet') {
+    /**
+     * Optional consumer-supplied Soroban RPC endpoint (e.g. a keyed Alchemy URL).
+     * When set it is the primary, with the SDK's public endpoints as failover.
+     */
+    _sorobanRpcUrl;
+    /**
+     * @param network - Stellar network to operate on; defaults to `'mainnet'`.
+     * @param options - Optional adapter configuration. Its `sorobanRpcUrl` field
+     *   overrides the Soroban RPC endpoint (e.g. a keyed Alchemy URL): it becomes
+     *   the primary with the SDK's built-in public endpoints kept behind it as
+     *   failover, and a per-call `sorobanRpcUrl` (on the deposit/redeem params)
+     *   takes precedence over this adapter-level one.
+     */
+    constructor(network = 'mainnet', options) {
         this._network = network;
+        this._sorobanRpcUrl = options?.sorobanRpcUrl;
     }
     get network() {
         return this._network;
@@ -90,6 +104,8 @@ class StellarAdapter {
         return StellarActions.handleStellarDeposit({
             ...params,
             network: this._network,
+            // A per-call override (params.sorobanRpcUrl) wins over the adapter-level one.
+            sorobanRpcUrl: params.sorobanRpcUrl ?? this._sorobanRpcUrl,
         });
     }
     /**
@@ -100,6 +116,8 @@ class StellarAdapter {
         return StellarActions.handleStellarRedeem({
             ...params,
             network: this._network,
+            // A per-call override (params.sorobanRpcUrl) wins over the adapter-level one.
+            sorobanRpcUrl: params.sorobanRpcUrl ?? this._sorobanRpcUrl,
         });
     }
     /**
@@ -129,7 +147,7 @@ class StellarAdapter {
      * ```
      */
     async submitTransaction(signedXdr) {
-        return StellarSubmit.submitStellarTransaction(signedXdr, this._network);
+        return StellarSubmit.submitStellarTransaction(signedXdr, this._network, this._sorobanRpcUrl);
     }
     /**
      * Get user's vault share balance.
@@ -140,7 +158,7 @@ class StellarAdapter {
      * a redeem MUST refuse rather than trust it (see AUGUST-6381).
      */
     async getUserPosition(vaultAddress, walletAddress) {
-        return StellarGetters.getStellarUserPosition(vaultAddress, walletAddress, this._network);
+        return StellarGetters.getStellarUserPosition(vaultAddress, walletAddress, this._network, this._sorobanRpcUrl);
     }
     /**
      * Preview how many vault shares a deposit amount would yield.
@@ -149,8 +167,9 @@ class StellarAdapter {
      * @returns Raw share amount as a string, or null if query fails.
      */
     async convertToShares(vaultAddress, rawAmount) {
-        return StellarGetters.convertToShares(vaultAddress, rawAmount, this._network);
+        return StellarGetters.convertToShares(vaultAddress, rawAmount, this._network, this._sorobanRpcUrl);
     }
 }
+exports.StellarAdapter = StellarAdapter;
 exports.default = StellarAdapter;
 //# sourceMappingURL=index.js.map

package/lib/adapters/stellar/soroban.d.ts

@@ -8,14 +8,101 @@ import { type xdr, rpc } from '@stellar/stellar-sdk';
 import type { IStellarNetwork } from './types';
 /** Resolved network configuration for Soroban RPC calls. */
 export interface ISorobanNetworkConfig {
+    /** Primary endpoint — the first of {@link rpcUrls}; kept for convenience. */
     rpcUrl: string;
+    /** Ordered endpoints for health-gated failover: primary first, fallbacks after. */
+    rpcUrls: readonly string[];
     passphrase: string;
 }
 export declare function createServer(rpcUrl: string): rpc.Server;
 /**
- * Resolve RPC URL and network passphrase for a Stellar network.
+ * Resolve the ordered RPC endpoints and network passphrase for a Stellar network.
+ *
+ * When `overrideRpcUrl` is supplied (e.g. a consumer's keyed Alchemy endpoint),
+ * it becomes the primary with the built-in public endpoints kept behind it as
+ * failover — so opting into a premium provider still degrades to the public
+ * network rather than becoming a new single point of failure. The endpoint is
+ * injected rather than hardcoded, so the adapter depends on configuration, not a
+ * constant.
+ */
+export declare function resolveNetworkConfig(network: IStellarNetwork, overrideRpcUrl?: string): ISorobanNetworkConfig;
+/**
+ * Clear the health-check cache and any in-flight probes. Test-only seam.
+ * @internal
+ */
+export declare function resetHealthyServerCache(): void;
+/**
+ * Host-only view of an RPC URL, safe for logs. Keyed provider endpoints put the
+ * API key in the path (e.g. Alchemy `/v2/<key>`), so logging the raw URL would
+ * leak the secret into SDK logs / crash reporters. Returns just protocol+host.
+ * @internal
+ */
+export declare function redactRpcUrl(url: string): string;
+/**
+ * Return a Soroban RPC server backed by a healthy endpoint for `config`. Thin
+ * wrapper over {@link resolveHealthyServer} for callers (e.g. submission) that
+ * only need the server, not the URL it resolved to.
+ *
+ * @internal
+ */
+export declare function getHealthyServer(config: ISorobanNetworkConfig): Promise<rpc.Server>;
+/**
+ * A thrown RPC error is retryable on another endpoint UNLESS it is one of our
+ * typed domain errors. Those mark a *deterministic* outcome — a contract revert,
+ * an unfunded account, archived state needing restore, a bad input, or a local
+ * assembly failure — which reproduces identically on every node, so retrying
+ * elsewhere only wastes calls. Any other throw (a transport hang/reset, or a
+ * method-specific node error from an endpoint that still answered `getHealth()`)
+ * is worth the next endpoint.
+ *
+ * Exported so an operation with different semantics (e.g. an idempotency-aware
+ * submission path) can compose or replace this policy via
+ * {@link FailoverOptions.isRetryable} — extension without editing the core.
+ * @internal
+ */
+export declare function isRetryableRpcError(err: unknown): boolean;
+/**
+ * Whether a simulation *error* string is a node/infrastructure failure (which
+ * clears on another endpoint) rather than a genuine contract revert (which
+ * reproduces on every node). `isSimulationError` alone can't tell these apart —
+ * both arrive as a populated `error` field — so callers use this to decide
+ * whether to fail over or treat the error as terminal.
+ * @internal
+ */
+export declare function isRetryableSimulationError(errorText: string): boolean;
+/**
+ * Tunables for {@link withEndpointFailover}, injected with sensible defaults so
+ * a new operation can vary retry policy or latency budget without editing the
+ * failover core (Open/Closed at the call site).
+ */
+export interface FailoverOptions {
+    /** Which thrown errors get the next endpoint. Defaults to {@link isRetryableRpcError}. */
+    isRetryable?: (err: unknown) => boolean;
+    /** Per-attempt timeout in ms. Defaults to {@link RPC_OPERATION_TIMEOUT_MS}. */
+    timeoutMs?: number;
+}
+/**
+ * Run an idempotent, side-effect-free `operation` (a read or a tx build) against
+ * a Soroban endpoint, failing over to the remaining endpoints on a retryable
+ * failure.
+ *
+ * {@link getHealthyServer} only proves an endpoint answered `getHealth()`, and
+ * caches that choice for {@link HEALTHY_SERVER_TTL_MS} — but the node can still
+ * hang or return a method-specific error on the *real* call. So we run the op on
+ * the health-gated server first (the fast, cached path) and, on a retryable
+ * failure, drop that cached choice and retry the op against every endpoint in
+ * priority order. Deterministic contract/domain errors short-circuit (see
+ * {@link isRetryableRpcError}); each attempt is time-boxed so a hung node can't
+ * stall the loop.
+ *
+ * The `operation` is a strategy (dependency-injected), so new read/build calls
+ * reuse this failover without changing it; `options` keeps retry policy and
+ * timeout open for extension. Submission is deliberately NOT routed through here
+ * — re-sending a signed transaction across endpoints risks a double-submit, so
+ * it needs sequence/DUPLICATE-based idempotency rather than blind retry.
+ * @internal
  */
-export declare function resolveNetworkConfig(network: IStellarNetwork): ISorobanNetworkConfig;
+export declare function withEndpointFailover<T>(config: ISorobanNetworkConfig, method: string, operation: (server: rpc.Server) => Promise<T>, options?: FailoverOptions): Promise<T>;
 /**
  * Validate and convert a string amount to a non-negative BigInt.
  * Throws a descriptive error if the value is not a valid non-negative integer string.