@augustdigital/sdk 8.3.2 → 8.6.0

package/lib/adapters/stellar/soroban.js

@@ -1,4 +1,10 @@
 "use strict";
+/**
+ * Shared Soroban RPC utilities
+ *
+ * Common transaction building and read-only query helpers used by
+ * actions, submit, and getters modules.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createServer = createServer;
 exports.resolveNetworkConfig = resolveNetworkConfig;
@@ -13,12 +19,19 @@ function createServer(rpcUrl) {
         allowHttp: rpcUrl.startsWith('http://'),
     });
 }
+/**
+ * Resolve RPC URL and network passphrase for a Stellar network.
+ */
 function resolveNetworkConfig(network) {
     return {
         rpcUrl: constants_1.SOROBAN_RPC_URLS[network],
         passphrase: constants_1.NETWORK_PASSPHRASES[network],
     };
 }
+/**
+ * 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.
+ */
 function toBigIntAmount(value, label) {
     if (value === '') {
         throw new core_1.AugustValidationError('INVALID_INPUT', `Invalid ${label}: value must not be empty`);
@@ -35,6 +48,11 @@ function toBigIntAmount(value, label) {
     }
     return result;
 }
+/**
+ * Query a read-only Soroban contract function via simulation.
+ * Uses a throwaway source account — simulation is off-chain and has no on-chain side effects.
+ * Returns the ScVal result, or null if the call fails.
+ */
 function extractSimulationError(simulated) {
     return 'error' in simulated
         ? String(simulated.error)
@@ -46,6 +64,8 @@ async function queryContract(config, contractId, method, args = []) {
         const contract = new stellar_sdk_1.Contract(contractId);
         const sourceKeypair = stellar_sdk_1.Keypair.random();
         const account = new stellar_sdk_1.Account(sourceKeypair.publicKey(), '0');
+        // Minimal fee — simulation is off-chain; these values don't affect execution cost.
+        // Short timeout to avoid blocking vault listing if Soroban RPC is slow.
         const tx = new stellar_sdk_1.TransactionBuilder(account, {
             fee: '100',
             networkPassphrase: config.passphrase,
@@ -76,9 +96,22 @@ async function queryContract(config, contractId, method, args = []) {
         return null;
     }
 }
+/**
+ * Read the network's wall-clock time (unix seconds) from the latest closed
+ * ledger, or null if the RPC can't report it.
+ *
+ * Soroban validators reject a transaction whose `maxTime` precedes the ledger
+ * close time (`txTOO_LATE`). Anchoring `maxTime` to the *network* clock instead
+ * of the signer's `Date.now()` immunises the deadline against a skewed device
+ * clock — a machine lagging behind real time was silently building
+ * already-expired transactions. Best-effort: on any RPC failure the caller
+ * falls back to the local clock, so this never regresses the prior behaviour.
+ */
 async function getNetworkCloseTime(server) {
     try {
         const { sequence } = await server.getLatestLedger();
+        // `latestLedgerCloseTime` on the response envelope is the freshest network
+        // time; the single-ledger page is just the cheapest valid request shape.
         const page = await server.getLedgers({
             startLedger: sequence,
             pagination: { limit: 1 },
@@ -92,18 +125,29 @@ async function getNetworkCloseTime(server) {
         return null;
     }
 }
+/**
+ * Build an unsigned Soroban contract invocation transaction.
+ * Fetches the real source account from the network (the account must exist and be funded).
+ * Simulates via Soroban RPC to attach resource footprint and auth entries,
+ * using MAX_FEE_STROOPS as the fee ceiling and incorporating the simulated resource fee.
+ */
 async function buildSorobanTx(config, sourceAddress, contractId, method, args) {
     const server = createServer(config.rpcUrl);
+    // Read the network clock in parallel with the account fetch — it overlaps the
+    // account round-trip, so it adds no latency on the happy path.
     const networkCloseTimePromise = getNetworkCloseTime(server);
     let account;
     try {
         account = await server.getAccount(sourceAddress);
     }
     catch (err) {
+        // Soroban rpc currently throws plain `Error("Account not found: ...")`
+        // for unfunded accounts; check `NotFoundError` too so this survives an
+        // SDK refactor to typed errors.
         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;
     }
@@ -114,9 +158,11 @@ async function buildSorobanTx(config, sourceAddress, contractId, method, args) {
     }).addOperation(contract.call(method, ...args));
     const networkCloseTime = await networkCloseTimePromise;
     if (networkCloseTime !== null) {
+        // Absolute deadline anchored to the network clock — survives signer skew.
         builder.setTimebounds(0, networkCloseTime + constants_1.TX_TIMEOUT_SECONDS);
     }
     else {
+        // RPC couldn't report network time; fall back to the local-clock window.
         builder.setTimeout(constants_1.TX_TIMEOUT_SECONDS);
     }
     const tx = builder.build();

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

@@ -1,2 +1,31 @@
+/**
+ * Stellar Transaction Submission
+ *
+ * Submits signed Soroban transactions and polls for confirmation.
+ */
 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 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>;

package/lib/adapters/stellar/submit.js

@@ -1,23 +1,97 @@
 "use strict";
+/**
+ * Stellar Transaction Submission
+ *
+ * Submits signed Soroban transactions and polls for confirmation.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.submitStellarTransaction = submitStellarTransaction;
 const stellar_sdk_1 = require("@stellar/stellar-sdk");
 const core_1 = require("../../core");
 const soroban_1 = require("./soroban");
 const constants_1 = require("./constants");
+/**
+ * Best-effort decode of the transaction-level result code (the XDR union
+ * discriminant, e.g. `"txBadSeq"`, `"txTooLate"`) from a Soroban
+ * `TransactionResult`. Typed `unknown` and probed structurally so it stays
+ * robust to RPC/SDK shape drift; returns `undefined` for anything that isn't a
+ * decoded union, so callers fall back to the stringified XDR in the message.
+ */
+function extractTxResultCode(result) {
+    try {
+        const decoded = result;
+        if (typeof decoded?.result !== 'function')
+            return undefined;
+        // `|| undefined`: an empty discriminant shares the clean "no code" path.
+        return decoded.result().switch().name || undefined;
+    }
+    catch (e) {
+        // Only reached on a malformed / shape-drifted union (the non-union case
+        // already returned above). Breadcrumb it so decoder rot stays detectable;
+        // the caller still throws with the stringified XDR in the message.
+        core_1.Logger.log.warn('extractTxResultCode', { decodeError: String(e) });
+        return undefined;
+    }
+}
+/**
+ * `JSON.stringify` that never throws. A real `xdr.TransactionResult` can hold
+ * `bigint` fields (e.g. `feeCharged`), which make `JSON.stringify` throw a
+ * `TypeError` — that would escape and replace the `AugustSDKError` this detail
+ * is only meant to enrich. Returns `''` on failure so the caller falls back to
+ * the status; the decoded `resultCode` still carries the precise reason.
+ */
+function safeStringify(value) {
+    try {
+        return JSON.stringify(value) ?? '';
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Submit a signed Soroban transaction and poll until confirmed.
+ *
+ * @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
+ *   }
+ * }
+ * ```
+ */
 async function submitStellarTransaction(signedXdr, network) {
     const { rpcUrl, passphrase } = (0, soroban_1.resolveNetworkConfig)(network);
     const server = (0, soroban_1.createServer)(rpcUrl);
     const tx = stellar_sdk_1.TransactionBuilder.fromXDR(signedXdr, passphrase);
     const sendResult = await server.sendTransaction(tx);
     if (sendResult.status === 'ERROR') {
-        const detail = 'errorResult' in sendResult ? JSON.stringify(sendResult.errorResult) : '';
+        const errorResult = 'errorResult' in sendResult ? sendResult.errorResult : undefined;
+        const resultCode = extractTxResultCode(errorResult);
+        const detail = errorResult ? safeStringify(errorResult) : '';
         const msg = `Transaction submission failed: ${detail || sendResult.status}`;
-        core_1.Logger.log.error('submitStellarTransaction', msg, { network });
+        core_1.Logger.log.error('submitStellarTransaction', msg, { network, resultCode });
         throw new core_1.AugustSDKError('UNKNOWN', msg, {
-            context: { network, status: sendResult.status },
+            context: { network, status: sendResult.status, resultCode },
         });
     }
+    // Only PENDING (and DUPLICATE) mean the tx was accepted by the RPC.
+    // DUPLICATE means this exact transaction was already submitted — it may
+    // already be confirmed or still pending from a prior submission.
+    // TRY_AGAIN_LATER and any other status should be surfaced immediately
+    // so callers can retry submission instead of waiting for a poll timeout.
     if (sendResult.status !== 'PENDING' && sendResult.status !== 'DUPLICATE') {
         const msg = `Transaction not accepted by RPC (status: ${sendResult.status}). ` +
             'This may be retryable — the RPC node could be overloaded.';
@@ -26,6 +100,8 @@ async function submitStellarTransaction(signedXdr, network) {
             context: { network, status: sendResult.status },
         });
     }
+    // Geometric backoff (start POLL_INTERVAL_MS, ×POLL_INTERVAL_BACKOFF up to
+    // POLL_INTERVAL_MAX_MS) — fast on the happy path, gentler on slow ledgers.
     let getResult = await server.getTransaction(sendResult.hash);
     let polls = 0;
     let nextDelay = constants_1.POLL_INTERVAL_MS;
@@ -47,14 +123,23 @@ async function submitStellarTransaction(signedXdr, network) {
     if (getResult.status === 'SUCCESS') {
         return sendResult.hash;
     }
-    const failDetail = 'resultXdr' in getResult ? ` (${JSON.stringify(getResult.resultXdr)})` : '';
+    const resultXdr = 'resultXdr' in getResult ? getResult.resultXdr : undefined;
+    const resultCode = extractTxResultCode(resultXdr);
+    const detail = resultXdr ? safeStringify(resultXdr) : '';
+    const failDetail = detail ? ` (${detail})` : '';
     const msg = `Transaction failed: ${getResult.status}${failDetail}`;
     core_1.Logger.log.error('submitStellarTransaction', msg, {
         hash: sendResult.hash,
         network,
+        resultCode,
     });
     throw new core_1.AugustSDKError('UNKNOWN', msg, {
-        context: { hash: sendResult.hash, network, status: getResult.status },
+        context: {
+            hash: sendResult.hash,
+            network,
+            status: getResult.status,
+            resultCode,
+        },
     });
 }
 //# sourceMappingURL=submit.js.map

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

@@ -1,19 +1,46 @@
+/**
+ * Stellar Vault Types
+ */
 import type { IStellarNetwork } from '../../types/web3';
 export type { IStellarNetwork };
+/** Parameters for building an unsigned Stellar vault deposit transaction. */
 export interface IStellarDepositParams {
     contractId: string;
     amount: string;
     senderAddress: string;
     network: IStellarNetwork;
 }
+/** Parameters for building an unsigned Stellar vault redeem transaction. */
 export interface IStellarRedeemParams {
     contractId: string;
     shares: string;
     receiverAddress: string;
     network: IStellarNetwork;
 }
+/**
+ * User vault position returned by on-chain balance queries.
+ *
+ * `decimals` carries the share-token scale used to interpret `shares`. When the
+ * on-chain `decimals()` read fails, it falls back to STELLAR_FALLBACK_DECIMALS
+ * (7) and `decimalsFromFallback` is set to `true`. Callers that size a redeem
+ * from this position MUST check `decimalsFromFallback` and refuse to settle
+ * when it is `true` — trusting a fabricated 7 against an ERC4626 offset vault
+ * (share decimals = asset + offset) under-redeems by `10^offset`. See
+ * AUGUST-6381.
+ */
 export interface IStellarUserPosition {
+    /** Raw share balance in smallest unit, as a non-negative integer string */
     shares: string;
+    /** Share-token decimals; may be the fallback — see `decimalsFromFallback`. */
     decimals: number;
+    /**
+     * `true` when `decimals` is the fallback (the on-chain `decimals()` read
+     * failed), `false` when it is the authoritative on-chain value. Treat `true`
+     * as a decimals read failure: do not trust `decimals` to scale or redeem.
+     *
+     * Optional for source back-compat (a consumer's existing object literal still
+     * compiles), but `getStellarUserPosition` always populates it — so a position
+     * obtained from the SDK never omits it.
+     */
     decimalsFromFallback?: boolean;
 }

package/lib/adapters/stellar/types.js

@@ -1,3 +1,6 @@
 "use strict";
+/**
+ * Stellar Vault Types
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 //# sourceMappingURL=types.js.map

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

@@ -1,11 +1,21 @@
+/**
+ * Stellar Utilities
+ */
 import type { IStellarNetwork } from './types';
 import { isStellarAddress } from '../../core/helpers/chain-address';
 export { isStellarAddress };
+/**
+ * Get the Stellar explorer URL for a given address or transaction.
+ */
 export declare function getExplorerLink({ id, type, network, }: {
     id: string;
     type?: 'contract' | 'account' | 'tx';
     network?: IStellarNetwork;
 }): string;
+/**
+ * Throw if the given address is a Stellar address.
+ * Used as a guard in vault operations that don't yet support Stellar.
+ */
 export declare function assertNotStellar(address: string, operation: string): void;
 export declare const StellarUtils: {
     isStellarAddress: typeof isStellarAddress;

package/lib/adapters/stellar/utils.js

@@ -1,4 +1,7 @@
 "use strict";
+/**
+ * Stellar Utilities
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StellarUtils = exports.isStellarAddress = void 0;
 exports.getExplorerLink = getExplorerLink;
@@ -6,11 +9,18 @@ exports.assertNotStellar = assertNotStellar;
 const core_1 = require("../../core");
 const chain_address_1 = require("../../core/helpers/chain-address");
 Object.defineProperty(exports, "isStellarAddress", { enumerable: true, get: function () { return chain_address_1.isStellarAddress; } });
+/**
+ * Get the Stellar explorer URL for a given address or transaction.
+ */
 function getExplorerLink({ id, type = 'contract', network = 'mainnet', }) {
     const baseUrl = 'https://stellar.expert/explorer';
     const net = network === 'mainnet' ? 'public' : 'testnet';
     return `${baseUrl}/${net}/${type}/${id}`;
 }
+/**
+ * Throw if the given address is a Stellar address.
+ * Used as a guard in vault operations that don't yet support Stellar.
+ */
 function assertNotStellar(address, operation) {
     if ((0, chain_address_1.isStellarAddress)(address)) {
         throw new core_1.AugustValidationError('INVALID_CHAIN', `${operation} is not yet supported for Stellar vaults: ${address}`);

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

@@ -1,3 +1,9 @@
-import { IEmberVault, IFetchEmberVaultsOptions } from './types';
+import type { IEmberVault, IFetchEmberVaultsOptions } from './types';
+/**
+ * Fetch Ember vaults from API
+ */
 export declare function getEmberVaults(options?: IFetchEmberVaultsOptions): Promise<IEmberVault[]>;
+/**
+ * Fetch Ember TVL data
+ */
 export declare function getEmberTVL(limit?: number): Promise<number>;

package/lib/adapters/sui/getters.js

@@ -5,6 +5,9 @@ exports.getEmberTVL = getEmberTVL;
 const constants_1 = require("./constants");
 const core_1 = require("../../core");
 const logger_1 = require("../../core/logger");
+/**
+ * Fetch Ember vaults from API
+ */
 async function getEmberVaults(options) {
     try {
         const params = new URLSearchParams();
@@ -28,6 +31,9 @@ async function getEmberVaults(options) {
         return [];
     }
 }
+/**
+ * Fetch Ember TVL data
+ */
 async function getEmberTVL(limit = 1) {
     try {
         const params = new URLSearchParams();

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

@@ -1,8 +1,13 @@
+/**
+ * Sui Adapter for August SDK
+ *
+ * @module SuiAdapter
+ */
 import * as SuiConstants from './constants';
 import * as SuiGetters from './getters';
 import * as SuiUtils from './utils';
 import { transformEmberVaultToIVault, transformEmberVaultsToIVaults } from './transformer';
-import { IEmberVault, IFetchEmberVaultsOptions } from './types';
+import type { IEmberVault, IFetchEmberVaultsOptions } from './types';
 export declare const Sui: {
     utils: typeof SuiUtils;
     constants: typeof SuiConstants;
@@ -12,6 +17,16 @@ export declare const Sui: {
         transformEmberVaultsToIVaults: typeof transformEmberVaultsToIVaults;
     };
 };
+/**
+ * Sui Adapter for August SDK
+ *
+ * @example
+ * To access the Sui adapter instance
+ * ```
+ * const sdk = new AugustSDK()
+ * sdk.sui.getEmberVaults()
+ * ```
+ */
 declare class SuiAdapter {
     private _apiBaseUrl;
     private _chainId;

package/lib/adapters/sui/index.js

@@ -34,6 +34,11 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Sui = void 0;
+/**
+ * Sui Adapter for August SDK
+ *
+ * @module SuiAdapter
+ */
 const SuiConstants = __importStar(require("./constants"));
 const SuiGetters = __importStar(require("./getters"));
 const SuiUtils = __importStar(require("./utils"));
@@ -44,7 +49,19 @@ exports.Sui = {
     getters: SuiGetters,
     transformer: { transformEmberVaultToIVault: transformer_1.transformEmberVaultToIVault, transformEmberVaultsToIVaults: transformer_1.transformEmberVaultsToIVaults },
 };
+/**
+ * Sui Adapter for August SDK
+ *
+ * @example
+ * To access the Sui adapter instance
+ * ```
+ * const sdk = new AugustSDK()
+ * sdk.sui.getEmberVaults()
+ * ```
+ */
 class SuiAdapter {
+    _apiBaseUrl;
+    _chainId;
     constructor(apiBaseUrl = SuiConstants.EMBER_API_BASE_URL, chainId = SuiConstants.SUI_CHAIN_ID) {
         this._apiBaseUrl = apiBaseUrl;
         this._chainId = chainId;

package/lib/adapters/sui/transformer.d.ts

@@ -1,4 +1,10 @@
-import { IVault } from '../../types';
-import { IEmberVault } from './types';
+import type { IVault } from '../../types';
+import type { IEmberVault } from './types';
+/**
+ * Transform Ember vault to IVault format
+ */
 export declare function transformEmberVaultToIVault(emberVault: IEmberVault): IVault;
+/**
+ * Transform multiple Ember vaults
+ */
 export declare function transformEmberVaultsToIVaults(emberVaults: IEmberVault[]): IVault[];

package/lib/adapters/sui/transformer.js

@@ -5,6 +5,9 @@ exports.transformEmberVaultsToIVaults = transformEmberVaultsToIVaults;
 const core_1 = require("../../core");
 const constants_1 = require("./constants");
 const utils_1 = require("./utils");
+/**
+ * Transform Ember vault to IVault format
+ */
 function transformEmberVaultToIVault(emberVault) {
     const depositTokenDecimals = emberVault.depositCoin?.decimals || constants_1.EMBER_DEFAULTS.DECIMALS;
     const receiptTokenDecimals = emberVault.receiptCoin?.decimals || constants_1.EMBER_DEFAULTS.DECIMALS;
@@ -56,6 +59,7 @@ function transformEmberVaultToIVault(emberVault) {
             multiplier: 0,
             multipliers: [],
             additionalPoints: [],
+            additionalPointsDetailed: [],
         },
         version: constants_1.EMBER_DEFAULTS.VERSION,
         description: emberVault.description || '',
@@ -94,6 +98,9 @@ function transformEmberVaultToIVault(emberVault) {
     };
     return returnObj;
 }
+/**
+ * Transform multiple Ember vaults
+ */
 function transformEmberVaultsToIVaults(emberVaults) {
     return emberVaults.map(transformEmberVaultToIVault);
 }

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

@@ -1,4 +1,4 @@
-import { IHIstoricalSnapshot } from '../../types';
+import type { IHIstoricalSnapshot } from '../../types';
 export interface IEmberVault {
     address: string;
     id: string;

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

@@ -1,4 +1,10 @@
+/**
+ * Convert E9 format to regular number
+ */
 export declare function convertFromE9(value: string | number): number;
+/**
+ * Calculate capacity utilization percentage
+ */
 export declare function calculateUtilization(current: string | number, maximum: string | number): number;
 export { isSuiAddress } from '../../core/helpers/chain-address';
 export declare function isSuiVault(chainId: number): boolean;

package/lib/adapters/sui/utils.js

@@ -5,9 +5,15 @@ exports.convertFromE9 = convertFromE9;
 exports.calculateUtilization = calculateUtilization;
 exports.isSuiVault = isSuiVault;
 const constants_1 = require("./constants");
+/**
+ * Convert E9 format to regular number
+ */
 function convertFromE9(value) {
     return Number(value) / constants_1.EMBER_DEFAULTS.E9_DIVISOR;
 }
+/**
+ * Calculate capacity utilization percentage
+ */
 function calculateUtilization(current, maximum) {
     const currentValue = Number(current) || 0;
     const maxValue = Number(maximum) || 0;

package/lib/core/analytics/chain-name.d.ts

@@ -1 +1,9 @@
+/**
+ * Map a numeric `chainId` to a stable lowercase slug for use as a Sentry tag
+ * value. Resolves both EVM chains ({@link NETWORKS}) and synthetic non-EVM
+ * chain IDs ({@link SPECIAL_CHAINS}); unknown IDs return `'unknown:<id>'`.
+ *
+ * @param chainId - Numeric chain ID, including negative IDs for non-EVM chains.
+ * @returns Slugified chain label (e.g. `'ethereum'`, `'arbitrum-one'`, `'solana'`).
+ */
 export declare function chainIdToTagValue(chainId: number | undefined): string;

package/lib/core/analytics/chain-name.js

@@ -2,6 +2,14 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.chainIdToTagValue = chainIdToTagValue;
 const web3_1 = require("../constants/web3");
+/**
+ * Map a numeric `chainId` to a stable lowercase slug for use as a Sentry tag
+ * value. Resolves both EVM chains ({@link NETWORKS}) and synthetic non-EVM
+ * chain IDs ({@link SPECIAL_CHAINS}); unknown IDs return `'unknown:<id>'`.
+ *
+ * @param chainId - Numeric chain ID, including negative IDs for non-EVM chains.
+ * @returns Slugified chain label (e.g. `'ethereum'`, `'arbitrum-one'`, `'solana'`).
+ */
 function chainIdToTagValue(chainId) {
     if (chainId === undefined || chainId === null || Number.isNaN(chainId)) {
         return 'unknown';

package/lib/core/analytics/constants.d.ts

@@ -1 +1,5 @@
+/**
+ * Sentry DSN for SDK analytics.
+ * This is an internal constant - not exposed to SDK users.
+ */
 export declare const SENTRY_DSN = "https://d73b6a85fe14960b8dac8ac61a743a94@o4507215496609792.ingest.de.sentry.io/4510699327389776";

package/lib/core/analytics/constants.js

@@ -1,5 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SENTRY_DSN = void 0;
+/**
+ * Sentry DSN for SDK analytics.
+ * This is an internal constant - not exposed to SDK users.
+ */
 exports.SENTRY_DSN = 'https://d73b6a85fe14960b8dac8ac61a743a94@o4507215496609792.ingest.de.sentry.io/4510699327389776';
 //# sourceMappingURL=constants.js.map

package/lib/core/analytics/env.d.ts

@@ -1,4 +1,29 @@
+/**
+ * Environment-variable gates for analytics. Pure functions — safe to import
+ * anywhere, no Sentry side effects. Tested directly in `analytics.test.js`.
+ */
+/**
+ * Read a process env var without crashing in browsers or in bundles where
+ * `process.env` is a frozen / proxied object that throws on missing keys.
+ */
 export declare function readEnv(name: string): string | undefined;
+/**
+ * `AUGUST_SDK_FORCE_ANALYTICS=1` bypasses the dev/test and localhost gates.
+ * Used by our own smoke-test script and by partners deliberately exercising
+ * telemetry in a non-prod environment.
+ */
 export declare function isAnalyticsForcedOnViaEnv(): boolean;
+/**
+ * `AUGUST_SDK_DISABLE_ANALYTICS=1` is the env equivalent of passing
+ * `analytics: { enabled: false }`. Useful when partners can't easily plumb
+ * config through (CI runners, ops scripts).
+ */
 export declare function isAnalyticsDisabledViaEnv(): boolean;
+/**
+ * True when `NODE_ENV` is `'development'` or `'test'`. The SDK auto-disables
+ * analytics in these environments so partners' local dev runs and Jest suites
+ * don't pollute the production Sentry project.
+ *
+ * `NODE_ENV` undefined / `'production'` / `'staging'` / anything else → false.
+ */
 export declare function isNodeDevOrTestEnv(): boolean;