@augustdigital/sdk 8.5.0 → 8.6.1

package/README.md

@@ -1,6 +1,6 @@
 # August Digital SDK
 
-TypeScript SDK for interacting with August Digital vaults across EVM and Solana chains.
+TypeScript SDK for interacting with August Digital vaults across EVM, Solana, Stellar, and Sui chains.
 
 ## Installation
 
@@ -20,17 +20,15 @@ The SDK supports both ethers and wagmi/viem signers. If you're using wagmi in yo
 npm install viem
 ```
 
-The SDK will automatically detect and convert viem WalletClient to ethers-compatible signers.
+The SDK automatically converts viem `WalletClient` to an ethers-compatible signer.
 
 ## Quick Start
 
 ```typescript
-import { AugustSDK } from '@augustdigital/sdk';
+import AugustSDK from '@augustdigital/sdk';
 
-// Initialize with RPC providers
 const sdk = new AugustSDK({
-  // Required: a stable kebab-case slug identifying your application.
-  // See "App Name" below for what this is used for.
+  // Required: stable kebab-case slug identifying your application.
   appName: 'acme-trader',
   providers: {
     1: 'https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY',
@@ -38,7 +36,7 @@ const sdk = new AugustSDK({
     -1: 'https://api.mainnet-beta.solana.com', // Solana
   },
   keys: {
-    august: 'YOUR_API_KEY', // Optional: required for allocations, health factors, and subaccount operations
+    august: 'YOUR_API_KEY', // Optional: required for allocations, health factors, and sub-account operations
   },
   monitoring: {
     env: 'DEV', // Optional: 'DEV' enables console logging (defaults to 'PROD')
@@ -48,10 +46,10 @@ const sdk = new AugustSDK({
 // Fetch all vaults
 const vaults = await sdk.getVaults();
 
-// Fetch specific vault with loans and allocations
+// Fetch a specific vault with loans and allocations
 const vault = await sdk.getVault({
   vault: '0x...',
-  options: { loans: true, allocations: true }
+  options: { loans: true, allocations: true },
 });
 
 // Get user positions
@@ -63,57 +61,25 @@ const positions = await sdk.getVaultPositions({
 
 ### App Name
 
-`appName` is required on every `AugustSDK` constructor call. Pass a
-stable kebab-case slug identifying your application (e.g.
-`'acme-trader'`, `'my-defi-app'`):
-
-- **What it's used for.** August Digital tags outbound analytics events
-  with `app.name = <yourSlug>`. We use this to (a) reach out about
-  breaking changes that will affect you, (b) attribute error spikes to
-  the right consuming app, and (c) prioritize bug fixes by impact.
-- **What it is _not_.** It's not a secret, not a license key, not an
-  auth token, and despite the friendly name it's **not a display
-  label**. It's a self-issued identifier — pick a slug once and reuse
-  it across deployments.
-- **Constraints.** 3–64 characters, only `[a-zA-Z0-9._-]`. Use a slug
-  like `'acme-trader'`, **not** a display name like `'Acme Trader'`
-  (spaces and special characters will throw). The SDK throws
-  synchronously from the constructor if the value is missing or
-  invalid, so a wrong value fails loudly at integration time rather
-  than silently in production.
+`appName` is required on every `AugustSDK` constructor call. Pass a stable kebab-case slug
+identifying your application (e.g. `'acme-trader'`, `'my-defi-app'`):
+
+- **What it's used for.** August Digital tags analytics events with `app.name = <yourSlug>` to
+  attribute error spikes and prioritize bug fixes by consuming app.
+- **What it is not.** Not a secret, not a license key, not a display label. Pick a slug once
+  and reuse it across deployments.
+- **Constraints.** 3–64 characters, only `[a-zA-Z0-9._-]`. The SDK throws synchronously from
+  the constructor if the value is missing or invalid.
 
 ```typescript
 // Will throw — appName is required.
-new AugustSDK({
-  providers: {
-    /* ... */
-  },
-  keys: {
-    /* ... */
-  },
-} as any);
+new AugustSDK({ providers: { /* ... */ } } as any);
 
-// Will throw — display name, not a slug. Use 'acme-trader' instead.
-new AugustSDK({
-  appName: 'Acme Trader',
-  providers: {
-    /* ... */
-  },
-  keys: {
-    /* ... */
-  },
-});
+// Will throw — spaces not allowed. Use 'acme-trader'.
+new AugustSDK({ appName: 'Acme Trader', providers: { /* ... */ } });
 
 // Correct.
-new AugustSDK({
-  appName: 'acme-trader',
-  providers: {
-    /* ... */
-  },
-  keys: {
-    /* ... */
-  },
-});
+new AugustSDK({ appName: 'acme-trader', providers: { /* ... */ } });
 ```
 
 ## Architecture
@@ -126,13 +92,15 @@ src.ts/
 │   ├── fetcher.ts       # API client with retry logic
 │   └── web3.helpers.ts  # Blockchain utilities
 ├── adapters/            # Chain-specific implementations
-│   ├── evm/             # EVM vault adapters (v1, v2)
-│   └── solana/          # Solana program adapters
+│   ├── evm/             # EVM adapter (approve, deposit, redeem, read helpers)
+│   ├── solana/          # Solana program adapters
+│   ├── stellar/         # Stellar vault adapters
+│   └── sui/             # Sui (Ember) vault adapters
+├── evm/                 # EVM cross-chain (LayerZero OVault)
 ├── modules/             # Feature modules
-│   └── vaults/          # Vault operations
-│       ├── main.ts      # AugustVaults class
-│       ├── getters.ts   # Data fetching functions
-│       └── utils.ts     # Helper utilities
+│   ├── vaults/          # Vault read operations
+│   ├── sub-accounts/    # Sub-account queries
+│   └── api/             # August backend API integration
 ├── services/            # External service integrations
 │   ├── debank/          # DeFi allocation data
 │   ├── coingecko/       # Token pricing
@@ -144,8 +112,10 @@ src.ts/
 
 ### Multi-Chain Support
 
-- **EVM Chains**: Ethereum, Arbitrum, Base, BSC, Avalanche
-- **Solana**: Native Solana program support
+- **EVM Chains**: Ethereum, Arbitrum, Base, BSC, Avalanche, and more — `wagmi/viem` and `ethers` signers supported
+- **Solana**: Native Solana program support with full vault functionality
+- **Stellar**: Stellar vault deposit, redeem, and position queries
+- **Sui**: Ember vault read operations
 - Unified interface across all chains
 
 ### Vault Versions
@@ -153,6 +123,7 @@ src.ts/
 - `evm-0/evm-1`: Legacy vault contracts
 - `evm-2`: Current EVM vault architecture (separate receipt tokens)
 - `sol-0`: Solana program-based vaults
+- `stellar-0`: Stellar-based vaults
 
 ### Data Enrichment
 
@@ -162,6 +133,154 @@ All vault queries support optional enrichment:
 - `allocations`: DeFi/CeFi/OTC position breakdowns
 - `wallet`: User-specific position data
 
+## API Reference
+
+### Vault Queries
+
+| Method | Description |
+| --- | --- |
+| `getVaults(options?)` | Fetch all vaults across chains |
+| `getVault({ vault, chainId?, options? })` | Get single vault details |
+| `getVaultLoans({ vault, chainId? })` | Fetch active loans |
+| `getVaultAllocations({ vault, chainId? })` | Get allocation breakdown |
+| `getVaultHistoricalTimeseries({ vault, chainId? })` | Historical APY and TVL timeseries |
+| `getVaultApy({ vault, historical? })` | **@deprecated** — use `getVaultHistoricalTimeseries` |
+| `getVaultTvl({ vault, historical? })` | Current/historical TVL |
+| `getVaultAnnualizedApy({ vault })` | Annualized APY for a vault |
+| `getVaultSummary({ vault })` | Aggregated vault summary |
+| `getVaultPnl({ vault, chainId? })` | Vault-level PnL |
+| `getVaultUnrealizedPnlHistory({ vault, chainId?, ... })` | Unrealized PnL timeseries |
+| `getLatestUnrealizedPnl()` | Latest unrealized PnL snapshot across all vaults |
+| `getYieldLastRealizedOn({ vault, chainId? })` | Timestamp of last yield realization |
+| `getTotalDeposited(options?)` | Total deposited across vaults |
+
+### User Positions
+
+| Method | Description |
+| --- | --- |
+| `getVaultPositions({ wallet?, vault?, chainId? })` | User vault positions |
+| `getVaultAvailableRedemptions({ vault, wallet?, chainId, verbose? })` | Claimable redemptions |
+| `getVaultRedemptionHistory({ vault, wallet?, chainId? })` | Historical redemptions |
+| `getVaultUserHistory({ wallet, vault?, chainId? })` | Transaction history |
+| `getVaultUserTransfers({ wallet, vault?, chainId? })` | Transfer history |
+| `getVaultUserLifetimePnl({ wallet, vault?, chainId? })` | Lifetime PnL for a wallet |
+| `getVaultStakingPositions({ wallet, chainId })` | Staking positions |
+| `getVaultBorrowerHealthFactor(props?)` | Borrower health factor |
+| `getVaultWithdrawals({ vault, chainId? })` | Pending withdrawals |
+
+### Points
+
+| Method | Description |
+| --- | --- |
+| `getUserPoints(userAddress)` | Points balance for a wallet |
+| `registerUserForPoints({ wallet, referral? })` | Register a wallet for the points program |
+| `fetchPointsLeaderboard(params?)` | Points leaderboard |
+
+### Write Operations (top-level)
+
+| Method | Description |
+| --- | --- |
+| `vaultDeposit(signer, options)` | Deposit into a vault |
+| `previewRedemption(props)` | Preview redemption output before broadcasting |
+
+### Cross-Chain (LayerZero)
+
+| Method | Description |
+| --- | --- |
+| `getLayerZeroDeposits({ wallet?, chainId? })` | LayerZero deposit history |
+| `getLayerZeroRedeems(props?)` | LayerZero redemption history |
+
+### Utilities
+
+| Method | Description |
+| --- | --- |
+| `getPrice(symbol)` | Token price in USD |
+| `switchNetwork(chainId)` | Change active chain |
+| `updateWallet(address)` | Set active wallet for tracking |
+
+### Sub-Accounts (`sdk.subAccountsModule`)
+
+| Method | Description |
+| --- | --- |
+| `getSubaccountHealthFactor(address)` | Health factor for a sub-account |
+| `getSubaccountLoans(address)` | Active loans for a sub-account |
+| `getSubaccountCefiPositions(address)` | CeFi positions |
+| `getSubaccountOtcPositions(address)` | OTC positions |
+| `getSubaccountSummary(address)` | Aggregated sub-account summary |
+
+### EVM Adapter (`sdk.evm`)
+
+Set a signer before calling write methods:
+
+```typescript
+// ethers
+import { JsonRpcProvider, Wallet } from 'ethers';
+const wallet = new Wallet(process.env.PRIVATE_KEY!, new JsonRpcProvider(rpcUrl));
+sdk.evm.setSigner(wallet);
+
+// wagmi/viem (browser)
+import { useWalletClient } from 'wagmi';
+const { data: walletClient } = useWalletClient();
+if (walletClient) sdk.evm.setSigner(walletClient);
+```
+
+**Write methods:**
+
+| Method | Description |
+| --- | --- |
+| `vaultApprove(options)` | Approve token spend for a vault |
+| `approve(options)` | Generic ERC-20 approve |
+| `vaultDeposit(options)` | Deposit assets into a vault |
+| `vaultRequestRedeem(options)` | Request a withdrawal/redemption |
+| `vaultRedeem(signer, options)` | Claim an available redemption |
+| `depositNative(options)` | Deposit native tokens (ETH, etc.) |
+| `swapAndDeposit(options)` | Swap and deposit in one call |
+| `depositViaSwapRouter(options)` | Deposit via the swap router |
+| `depositNativeViaSwapRouter(options)` | Deposit native via the swap router |
+
+**Read helpers (return raw `bigint`):**
+
+| Method | Description |
+| --- | --- |
+| `previewDeposit(options)` | Shares minted for a deposit amount |
+| `previewRedeem(options)` | Assets returned for a share amount |
+| `allowance(options)` | ERC-20 allowance granted to the vault |
+| `balanceOf(options)` | ERC-20 balance for any token/owner |
+| `maxDeposit(options)` | Maximum deposit accepted by the vault |
+| `vaultAllowance(options)` | Vault-specific allowance check |
+| `getDeposited(options)` | Current deposited balance |
+| `getRemainingAllocations(options)` | Remaining allocation capacity |
+| `isWhitelisted(options)` | Check whitelist status |
+
+### Solana Adapter (`sdk.solana`)
+
+| Method | Description |
+| --- | --- |
+| `getVaultState(...)` | Vault state from the Solana program |
+| `getVaultStateReadOnly(...)` | Read-only vault state |
+| `getToken(mintAddress)` | SPL token info |
+| `getTokenSymbol(mintAddress)` | Token symbol |
+| `fetchUserTokenBalance(publicKey, mint)` | User SPL token balance |
+| `fetchUserShareBalance(publicKey, vault)` | User share balance |
+| `fetchUserShareBalanceRaw(publicKey, vault)` | Raw share balance (bigint) |
+
+### Stellar Adapter (`sdk.stellar`)
+
+| Method | Description |
+| --- | --- |
+| `vaultDeposit(options)` | Deposit into a Stellar vault |
+| `vaultRedeem(options)` | Redeem from a Stellar vault |
+| `submitTransaction(signedXdr)` | Submit a signed XDR transaction |
+| `getUserPosition(options)` | User position in a Stellar vault |
+| `convertToShares(options)` | Convert an asset amount to shares |
+
+### Sui Adapter (`sdk.sui`)
+
+| Method | Description |
+| --- | --- |
+| `getEmberVaults()` | List all Ember (Sui) vaults |
+| `getEmberTVL(limit?)` | Total value locked across Ember vaults |
+
 ## Code Conventions
 
 ### Naming Patterns
@@ -170,9 +289,9 @@ All vault queries support optional enrichment:
 - **ABIs**: Prefixed with `ABI_` (e.g., `ABI_LENDING_POOL_V2`)
 - **Types**: Descriptive names (e.g., `IAddress`, `IChainId`)
 
-### Important Tags
+### Special Comment Tags
 
-Search codebase for these comments to find areas needing attention:
+Search the codebase for these to find important areas:
 
 - `@todo`: Planned improvements or missing features
 - `@hardcoded`: Hardcoded values that may need configuration
@@ -180,61 +299,34 @@ Search codebase for these comments to find areas needing attention:
 
 ### Error Handling
 
-- Automatic retry logic for network errors with exponential backoff
-- 90-second request timeout (configurable via `REQUEST_TIMEOUT_MS`)
-- Correlation IDs logged for debugging failed requests
-- Write actions throw errors instead of silent failures
-
-### Environment Configuration
+Every public method throws typed errors that subclass `AugustSDKError`:
 
 ```typescript
-// Development mode (enables console logging)
-const devSdk = new AugustSDK({
-  providers: {
-    /* ... */
-  },
-  monitoring: {
-    env: 'DEV',
-  },
-});
-
-// Production mode (default - no console logs)
-const prodSdk = new AugustSDK({
-  providers: {
-    /* ... */
-  },
-  // monitoring is optional - defaults to PROD
-});
+import { AugustValidationError, AugustTimeoutError, AugustSDKError } from '@augustdigital/sdk';
+
+try {
+  await sdk.evm.vaultDeposit({ target: '0x...', wallet: owner, amount: '1' });
+} catch (err) {
+  if (err instanceof AugustValidationError) showFormError(err.message);
+  else if (err instanceof AugustTimeoutError) scheduleRetry(err.timeoutMs);
+  else if (err instanceof AugustSDKError) reportError(err.code, err.cause);
+  else throw err;
+}
 ```
 
-- `env: 'DEV'` - Enables console logging for debugging
-- `env: 'PROD'` or omitted - Disables console, uses custom logger only (safer default)
-
-## API Reference
-
-### Main Methods
-
-#### Vault Queries
-
-- `getVaults(options?)`: Fetch all vaults across chains
-- `getVault({ vault, chainId?, options? })`: Get single vault details
-- `getVaultLoans({ vault, chainId })`: Fetch active loans
-- `getVaultAllocations({ vault, chainId })`: Get allocation breakdown
-- `getVaultApy({ vault, historical? })`: Current/historical APY
-- `getVaultTvl({ vault, historical? })`: Current/historical TVL
-
-#### User Positions
+- Automatic retry with exponential backoff for network errors
+- 90-second request timeout (configurable via `REQUEST_TIMEOUT_MS`)
+- Correlation IDs in errors for debugging
 
-- `getVaultPositions({ wallet?, vault?, chainId? })`: User vault positions
-- `getVaultAvailableRedemptions({ vault, wallet?, chainId, verbose?})`: Claimable redemptions
-- `getVaultUserHistory({ wallet, vault?, chainId? })`: Transaction history
-- `getVaultStakingPositions({ wallet, chainId })`: Staking positions
+### Environment Configuration
 
-#### Utilities
+```typescript
+// Development mode — enables console logging
+const sdk = new AugustSDK({ appName: 'my-app', providers: { /* ... */ }, monitoring: { env: 'DEV' } });
 
-- `getPrice(symbol)`: Get token price in USD
-- `switchNetwork(chainId)`: Change active chain
-- `updateWallet(address)`: Set active wallet for tracking
+// Production mode — default, no console logs
+const sdk = new AugustSDK({ appName: 'my-app', providers: { /* ... */ } });
+```
 
 ## Development
 
@@ -250,10 +342,8 @@ pnpm test
 pnpm build
 ```
 
-### Type Checking
-
-All exports are fully typed. Use TypeScript for best developer experience.
-
 ## Support
 
-For issues or questions, refer to the [main repository](https://github.com/fractal-protocol/js-sdk) or contact the August Digital team.
+- **Issues**: [GitHub Issues](https://github.com/fractal-protocol/js-sdk/issues)
+- **Documentation**: [docs.augustdigital.io](https://docs.augustdigital.io/developers/javascript-sdk)
+- **Example App**: [starter.upshift.finance](https://starter.upshift.finance/)

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

@@ -1,8 +1,8 @@
-import { IContractWriteOptions, INativeDepositOptions, ApproveResult } from '../../modules/vaults/write.actions';
+import { type IContractWriteOptions, type INativeDepositOptions, type ApproveResult } from '../../modules/vaults/write.actions';
 import type { ISwapAndDepositOptions, ISwapRouterDirectDepositOptions, ISwapRouterNativeDepositOptions } from '../../types';
-import { IPreviewDepositOptions, IPreviewRedeemOptions, IAllowanceOptions, IBalanceOfOptions, IMaxDepositOptions } from '../../modules/vaults/read.actions';
-import { CompatibleSigner } from '../../core/helpers/signer';
-import { IAddress } from '../../types';
+import { type IPreviewDepositOptions, type IPreviewRedeemOptions, type IAllowanceOptions, type IBalanceOfOptions, type IMaxDepositOptions } from '../../modules/vaults/read.actions';
+import { type CompatibleSigner } from '../../core/helpers/signer';
+import type { IAddress } from '../../types';
 export * from './getters';
 /**
  * EVM Adapter for August SDK

package/lib/adapters/evm/index.js

@@ -30,6 +30,8 @@ __exportStar(require("./getters"), exports);
  * ```
  */
 class EVMAdapter {
+    signer;
+    rawSigner;
     constructor(signer) {
         this.rawSigner = signer;
         // Don't normalize in constructor - do it lazily when needed

package/lib/adapters/solana/constants.d.ts

@@ -1,4 +1,4 @@
-import { ISolanaNetwork } from '../../types';
+import type { ISolanaNetwork } from '../../types';
 import { vaultIdl } from './idl/vault-idl';
 declare const fallbackDecimals = 8;
 declare const fallbackNetwork: ISolanaNetwork;

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

@@ -1,4 +1,4 @@
-import { ITokenizedVault } from '../../types';
+import type { ITokenizedVault } from '../../types';
 import type { IVaultBaseOptions } from '../../modules/vaults/types';
 /**
  * Fetch Solana vault data from on-chain program state.

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

@@ -6,10 +6,10 @@
 import * as SolanaConstants from './constants';
 import * as SolanaGetters from './getters';
 import * as SolanaActions from './vault.actions';
-import { AnchorProvider, web3 } from '@coral-xyz/anchor';
-import { Connection, PublicKey, Transaction } from '@solana/web3.js';
-import { ISolanaNetwork, ISolanaRpcEndpoint } from './types';
-import { SendTransactionOptions } from '@solana/wallet-adapter-base';
+import type { AnchorProvider, web3 } from '@coral-xyz/anchor';
+import { Connection, PublicKey, type Transaction } from '@solana/web3.js';
+import type { ISolanaNetwork, ISolanaRpcEndpoint } from './types';
+import type { SendTransactionOptions } from '@solana/wallet-adapter-base';
 export declare const Solana: {
     utils: {
         getExplorerLink: ({ signature, type, network, }: {

package/lib/adapters/solana/index.js

@@ -63,6 +63,10 @@ exports.Solana = {
  * ```
  */
 class SolanaAdapter {
+    _endpoint;
+    _network;
+    _connection;
+    _provider;
     constructor(endpoint, network = utils_1.SolanaUtils.fallbackNetwork) {
         this._endpoint = endpoint;
         this._network = network;

package/lib/adapters/solana/types.d.ts

@@ -1,4 +1,4 @@
-import { AnchorProvider } from '@coral-xyz/anchor';
+import type { AnchorProvider } from '@coral-xyz/anchor';
 import type { Connection, PublicKey } from '@solana/web3.js';
 export type ISolanaRpcEndpoint = `https://${string}`;
 export type ISolanaNetwork = 'devnet' | 'mainnet-beta' | 'testnet' | 'localnet';

package/lib/adapters/solana/utils.d.ts

@@ -1,6 +1,6 @@
-import { AnchorProvider, BN, Program, web3 } from '@coral-xyz/anchor';
-import { PublicKey, Transaction } from '@solana/web3.js';
-import { ISolanaConnectionOptions, ISolanaVaultState } from './types';
+import { AnchorProvider, BN, Program, type web3 } from '@coral-xyz/anchor';
+import { PublicKey, type Transaction } from '@solana/web3.js';
+import type { ISolanaConnectionOptions, ISolanaVaultState } from './types';
 declare function getExplorerLink({ signature, type, network, }: {
     signature: string;
     type: 'tx' | 'address' | 'token';

package/lib/adapters/solana/vault.actions.d.ts

@@ -1,7 +1,7 @@
-import { web3 } from '@coral-xyz/anchor';
-import { Connection, PublicKey, Transaction } from '@solana/web3.js';
-import { ISolanaConnectionOptions } from './types';
-import { SendTransactionOptions } from '@solana/wallet-adapter-base';
+import { type web3 } from '@coral-xyz/anchor';
+import { type Connection, PublicKey, Transaction } from '@solana/web3.js';
+import type { ISolanaConnectionOptions } from './types';
+import type { SendTransactionOptions } from '@solana/wallet-adapter-base';
 /**
  * Deposit funds into a Solana August vault and mint share tokens.
  *

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

@@ -4,7 +4,7 @@
  * Builds unsigned Soroban transactions for vault deposit/redeem operations.
  * Returns assembled XDR (base64) for wallet signing (e.g. Freighter).
  */
-import { IStellarDepositParams, IStellarRedeemParams } from './types';
+import type { IStellarDepositParams, IStellarRedeemParams } from './types';
 /**
  * Deposit assets into a Stellar vault (self-deposit).
  *

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

@@ -53,8 +53,30 @@ declare class StellarAdapter {
      */
     vaultRedeem(params: Omit<IStellarRedeemParams, 'network'>): Promise<string>;
     /**
-     * Submit a signed Soroban transaction and poll until confirmed.
-     * @returns Transaction hash on success
+     * Submit a signed Soroban transaction and poll until the network confirms it.
+     *
+     * Submits on the network this adapter was constructed with, so `signedXdr`
+     * must be signed for that same network.
+     *
+     * @param signedXdr - Base64-encoded XDR of the signed transaction.
+     * @returns The transaction hash once the network confirms it as successful.
+     * @throws {@link AugustTimeoutError} when the transaction is not confirmed
+     *   within the poll budget (`MAX_POLL_ATTEMPTS`).
+     * @throws {@link AugustSDKError} when the RPC rejects the submission or the
+     *   transaction confirms as failed. Its `context` carries `{ network, status }`
+     *   plus, when the result XDR decodes, a `resultCode` string holding the
+     *   transaction-level reason (e.g. `"txBadSeq"`, `"txTooLate"`); `resultCode`
+     *   is `undefined` when the code cannot be decoded.
+     * @example
+     * ```ts
+     * try {
+     *   const hash = await adapter.submitTransaction(signedXdr);
+     * } catch (err) {
+     *   if (err instanceof AugustSDKError && err.context?.resultCode === 'txBadSeq') {
+     *     // stale sequence number — rebuild the transaction and resubmit
+     *   }
+     * }
+     * ```
      */
     submitTransaction(signedXdr: string): Promise<string>;
     /**

package/lib/adapters/stellar/index.js

@@ -69,6 +69,7 @@ exports.Stellar = {
  * ```
  */
 class StellarAdapter {
+    _network;
     constructor(network = 'mainnet') {
         this._network = network;
     }
@@ -102,8 +103,30 @@ class StellarAdapter {
         });
     }
     /**
-     * Submit a signed Soroban transaction and poll until confirmed.
-     * @returns Transaction hash on success
+     * Submit a signed Soroban transaction and poll until the network confirms it.
+     *
+     * Submits on the network this adapter was constructed with, so `signedXdr`
+     * must be signed for that same network.
+     *
+     * @param signedXdr - Base64-encoded XDR of the signed transaction.
+     * @returns The transaction hash once the network confirms it as successful.
+     * @throws {@link AugustTimeoutError} when the transaction is not confirmed
+     *   within the poll budget (`MAX_POLL_ATTEMPTS`).
+     * @throws {@link AugustSDKError} when the RPC rejects the submission or the
+     *   transaction confirms as failed. Its `context` carries `{ network, status }`
+     *   plus, when the result XDR decodes, a `resultCode` string holding the
+     *   transaction-level reason (e.g. `"txBadSeq"`, `"txTooLate"`); `resultCode`
+     *   is `undefined` when the code cannot be decoded.
+     * @example
+     * ```ts
+     * try {
+     *   const hash = await adapter.submitTransaction(signedXdr);
+     * } catch (err) {
+     *   if (err instanceof AugustSDKError && err.context?.resultCode === 'txBadSeq') {
+     *     // stale sequence number — rebuild the transaction and resubmit
+     *   }
+     * }
+     * ```
      */
     async submitTransaction(signedXdr) {
         return StellarSubmit.submitStellarTransaction(signedXdr, this._network);

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

@@ -4,7 +4,7 @@
  * Common transaction building and read-only query helpers used by
  * actions, submit, and getters modules.
  */
-import { xdr, rpc } from '@stellar/stellar-sdk';
+import { type xdr, rpc } from '@stellar/stellar-sdk';
 import type { IStellarNetwork } from './types';
 /** Resolved network configuration for Soroban RPC calls. */
 export interface ISorobanNetworkConfig {

package/lib/adapters/stellar/soroban.js

@@ -147,7 +147,7 @@ async function buildSorobanTx(config, sourceAddress, contractId, method, args) {
         const msg = err instanceof Error ? err.message : String(err);
         const isAccountNotFound = err instanceof stellar_sdk_1.NotFoundError || /Account not found/.test(msg);
         if (isAccountNotFound) {
-            throw new core_1.AugustValidationError('INVALID_INPUT', `Stellar account ${sourceAddress} is not funded. Send at least 1 XLM to this address to activate it before depositing or redeeming.`, { cause: err, context: { sourceAddress, method, contractId } });
+            throw new core_1.AugustValidationError('ACCOUNT_NOT_FUNDED', `Stellar account ${sourceAddress} is not funded. Send at least 1 XLM to this address to activate it before depositing or redeeming.`, { cause: err, context: { sourceAddress, method, contractId } });
         }
         throw err;
     }

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

@@ -7,8 +7,25 @@ import type { IStellarNetwork } from './types';
 /**
  * Submit a signed Soroban transaction and poll until confirmed.
  *
- * @param signedXdr Base64-encoded XDR of the signed transaction
- * @param network Stellar network name
- * @returns Transaction hash on success
+ * @param signedXdr - Base64-encoded XDR of the signed transaction
+ * @param network - Stellar network name
+ * @returns The transaction hash once the network confirms it as successful
+ * @throws {@link AugustTimeoutError} when the transaction is not confirmed
+ *   within the poll budget (`MAX_POLL_ATTEMPTS`).
+ * @throws {@link AugustSDKError} when the RPC rejects the submission or the
+ *   transaction confirms as failed. Its `context` carries `{ network, status }`
+ *   plus, when the result XDR decodes, a `resultCode` string holding the
+ *   transaction-level reason (e.g. `"txBadSeq"`, `"txTooLate"`); `resultCode`
+ *   is `undefined` when the code cannot be decoded.
+ * @example
+ * ```ts
+ * try {
+ *   const hash = await submitStellarTransaction(signedXdr, 'mainnet');
+ * } catch (err) {
+ *   if (err instanceof AugustSDKError && err.context?.resultCode === 'txBadSeq') {
+ *     // stale sequence number — rebuild the transaction and resubmit
+ *   }
+ * }
+ * ```
  */
 export declare function submitStellarTransaction(signedXdr: string, network: IStellarNetwork): Promise<string>;