augustdigital-sdk 8.20.1

package/lib/services/octavfi/utils.js

@@ -0,0 +1,212 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.transformOctavfiToDebank = transformOctavfiToDebank;
+exports.transformOctavfiPortfoliosToDebank = transformOctavfiPortfoliosToDebank;
+/**
+ * Transforms Octavfi portfolio response to DeBank-compatible format.
+ * This allows Solana addresses to use Octavfi data while maintaining
+ * compatibility with existing DeBank parsing functions.
+ *
+ * @param octavfiPortfolio - Octavfi portfolio response
+ * @returns DeBank-compatible response structure
+ */
+function transformOctavfiToDebank(octavfiPortfolio) {
+    if (!octavfiPortfolio) {
+        return {
+            subaccount: {
+                positions: [],
+                tokens: [],
+            },
+        };
+    }
+    const positions = [];
+    const tokens = [];
+    // Transform protocols (assetByProtocols) into DeBank positions format
+    const assetByProtocols = octavfiPortfolio.assetByProtocols || {};
+    Object.entries(assetByProtocols).forEach(([protocolKey, protocol]) => {
+        // Skip wallet protocol - we'll handle it separately in tokens
+        if (protocolKey === 'wallet') {
+            return;
+        }
+        // Extract all assets from nested structure: chains -> protocolPositions -> assets
+        const allAssets = [];
+        if (protocol.chains) {
+            Object.values(protocol.chains).forEach((chain) => {
+                if (chain.protocolPositions) {
+                    Object.values(chain.protocolPositions).forEach((protocolPosition) => {
+                        // Direct assets
+                        if (protocolPosition.assets &&
+                            Array.isArray(protocolPosition.assets)) {
+                            allAssets.push(...protocolPosition.assets);
+                        }
+                        // Nested protocolPositions (like in Kamino)
+                        if (protocolPosition.protocolPositions &&
+                            Array.isArray(protocolPosition.protocolPositions)) {
+                            protocolPosition.protocolPositions.forEach((nestedPos) => {
+                                if (nestedPos.assets && Array.isArray(nestedPos.assets)) {
+                                    allAssets.push(...nestedPos.assets);
+                                }
+                            });
+                        }
+                    });
+                }
+            });
+        }
+        // Create position structure matching DeBank format
+        const position = {
+            id: protocolKey,
+            chain: getChainFromProtocol(protocol, octavfiPortfolio),
+            name: protocol.name || protocolKey,
+            logo_url: '', // Octavfi doesn't provide protocol logos
+            site_url: '', // Octavfi doesn't provide protocol URLs
+            portfolio_item_list: [
+                {
+                    name: protocol.name || protocolKey,
+                    stats: {
+                        asset_usd_value: parseFloat(protocol.value || '0') || 0,
+                        debt_usd_value: 0, // Octavfi doesn't distinguish debt, default to 0
+                        net_usd_value: parseFloat(protocol.value || '0') || 0,
+                    },
+                    detail: {
+                        supply_token_list: allAssets
+                            .map((asset) => transformAssetToDebankToken(asset, 'supply'))
+                            .filter((token) => token !== null),
+                        borrow_token_list: [], // Octavfi doesn't provide borrow data
+                    },
+                },
+            ],
+        };
+        positions.push(position);
+    });
+    // Transform wallet assets to tokens array
+    const walletProtocol = assetByProtocols['wallet'];
+    if (walletProtocol && walletProtocol.chains) {
+        // Extract assets from nested structure: chains -> protocolPositions -> assets
+        Object.values(walletProtocol.chains).forEach((chain) => {
+            if (chain.protocolPositions) {
+                Object.values(chain.protocolPositions).forEach((protocolPosition) => {
+                    if (protocolPosition.assets &&
+                        Array.isArray(protocolPosition.assets)) {
+                        protocolPosition.assets.forEach((asset) => {
+                            tokens.push({
+                                ...transformAssetToDebankToken(asset, 'wallet'),
+                                is_wallet: true,
+                                is_core: true, // Assume wallet tokens are core tokens
+                            });
+                        });
+                    }
+                });
+            }
+        });
+    }
+    // Also add protocol assets as tokens (non-wallet)
+    Object.entries(assetByProtocols).forEach(([protocolKey, protocol]) => {
+        if (protocolKey === 'wallet')
+            return;
+        if (!protocol || !protocol.chains)
+            return;
+        // Extract assets from nested structure
+        Object.values(protocol.chains).forEach((chain) => {
+            if (chain.protocolPositions) {
+                Object.values(chain.protocolPositions).forEach((protocolPosition) => {
+                    // Direct assets
+                    if (protocolPosition.assets &&
+                        Array.isArray(protocolPosition.assets)) {
+                        protocolPosition.assets.forEach((asset) => {
+                            // Check if token already exists (from wallet)
+                            const existingToken = tokens.find((t) => t.symbol === asset.symbol &&
+                                t.chain === (asset.chainKey || asset.chain));
+                            if (!existingToken) {
+                                tokens.push({
+                                    ...transformAssetToDebankToken(asset, 'supply'),
+                                    is_wallet: false,
+                                    is_core: true, // Assume protocol tokens are core
+                                });
+                            }
+                        });
+                    }
+                    // Nested protocolPositions (like in Kamino)
+                    if (protocolPosition.protocolPositions &&
+                        Array.isArray(protocolPosition.protocolPositions)) {
+                        protocolPosition.protocolPositions.forEach((nestedPos) => {
+                            if (nestedPos.assets && Array.isArray(nestedPos.assets)) {
+                                nestedPos.assets.forEach((asset) => {
+                                    const existingToken = tokens.find((t) => t.symbol === asset.symbol &&
+                                        t.chain === (asset.chainKey || asset.chain));
+                                    if (!existingToken) {
+                                        tokens.push({
+                                            ...transformAssetToDebankToken(asset, 'supply'),
+                                            is_wallet: false,
+                                            is_core: true,
+                                        });
+                                    }
+                                });
+                            }
+                        });
+                    }
+                });
+            }
+        });
+    });
+    return {
+        subaccount: {
+            positions,
+            tokens,
+        },
+    };
+}
+/**
+ * Transforms Octavfi asset to DeBank token format
+ */
+function transformAssetToDebankToken(asset, // Using any since the actual structure differs from IOctavfiAsset
+exposureType) {
+    if (!asset) {
+        return null;
+    }
+    const balance = parseFloat(asset.balance || '0') || 0;
+    const price = parseFloat(asset.price || '0') || 0;
+    const amount = balance;
+    const chain = asset.chainKey || asset.chain || 'unknown';
+    const contract = asset.contract || asset.chainContract || asset.contractAddress;
+    const decimals = parseInt(asset.decimal || asset.decimals || '18', 10);
+    return {
+        id: contract || asset.symbol || 'unknown', // Use contract address if available, fallback to symbol
+        chain: chain,
+        name: asset.name || asset.symbol || 'Unknown',
+        symbol: asset.symbol || 'UNKNOWN',
+        optimized_symbol: asset.symbol || 'UNKNOWN',
+        decimals: decimals,
+        logo_url: '', // Octavfi doesn't provide token logos
+        amount,
+        price,
+        protocol_id: '', // Will be set by the calling context
+        supplying_exposure: exposureType === 'supply' ? 'true' : undefined,
+    };
+}
+/**
+ * Determines the chain from protocol data or portfolio chains
+ */
+function getChainFromProtocol(protocol, portfolio) {
+    // Try to get chain from protocol.chains structure
+    if (protocol.chains) {
+        const chainKeys = Object.keys(protocol.chains);
+        if (chainKeys.length > 0) {
+            return chainKeys[0];
+        }
+    }
+    // Fallback to first chain in portfolio
+    const chains = portfolio.chains || {};
+    const chainKeys = Object.keys(chains);
+    if (chainKeys.length > 0) {
+        return chainKeys[0];
+    }
+    return 'unknown';
+}
+/**
+ * Transforms multiple Octavfi portfolios to DeBank format.
+ * Used when fetching multiple addresses.
+ */
+function transformOctavfiPortfoliosToDebank(portfolios) {
+    return portfolios.map(transformOctavfiToDebank);
+}
+//# sourceMappingURL=utils.js.map

package/lib/services/subgraph/fetcher.d.ts

@@ -0,0 +1,2 @@
+export declare function fetchSubgraph(graphUrl: string, query: string, apiKey?: string): Promise<Response>;
+export declare function fetchSubgraphWithRetry(graphUrl: string, query: string, apiKey?: string, maxRetries?: number, baseDelay?: number): Promise<Response>;

package/lib/services/subgraph/fetcher.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchSubgraph = fetchSubgraph;
+exports.fetchSubgraphWithRetry = fetchSubgraphWithRetry;
+const core_1 = require("../../core");
+async function fetchSubgraph(graphUrl, query, apiKey) {
+    return fetchSubgraphWithRetry(graphUrl, query, apiKey);
+}
+async function fetchSubgraphWithRetry(graphUrl, query, apiKey, maxRetries = 3, baseDelay = 1000) {
+    if (!graphUrl) {
+        throw new Error('#fetchSubgraph: URL is not defined');
+    }
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), core_1.REQUEST_TIMEOUT_MS / 3); // 30 second timeout
+            try {
+                const headers = {
+                    'Content-Type': 'application/json',
+                };
+                if (apiKey) {
+                    headers['Authorization'] = `Bearer ${apiKey}`;
+                }
+                const response = await fetch(graphUrl, {
+                    method: 'POST',
+                    headers,
+                    body: JSON.stringify({
+                        query: `query ${query}`,
+                    }),
+                    signal: controller.signal,
+                });
+                clearTimeout(timeoutId);
+                return response;
+            }
+            catch (fetchError) {
+                clearTimeout(timeoutId);
+                throw fetchError;
+            }
+        }
+        catch (error) {
+            lastError = error;
+            // If it's a timeout error, abort error, or network error and we have retries left
+            if (attempt < maxRetries &&
+                ((error instanceof TypeError &&
+                    error.message.includes('fetch failed')) ||
+                    error.name === 'AbortError' ||
+                    error.message.includes('ETIMEDOUT') ||
+                    error.message.includes('timeout'))) {
+                const delay = baseDelay * 2 ** attempt; // Exponential backoff
+                core_1.Logger.log.warn(`fetchSubgraph`, `${graphUrl?.includes('/subgraphs') ? graphUrl?.split('/subgraphs/')?.[1]?.split('/')?.[0] : graphUrl}: Attempt ${attempt + 1} failed, retrying in ${delay}ms`);
+                await new Promise((resolve) => setTimeout(resolve, delay));
+                continue;
+            }
+            // If it's not a retryable error or we're out of retries, throw
+            throw error;
+        }
+    }
+    throw lastError;
+}
+//# sourceMappingURL=fetcher.js.map

package/lib/services/subgraph/index.d.ts

@@ -0,0 +1,2 @@
+export * from './vaults';
+export * from './fetcher';

package/lib/services/subgraph/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./vaults"), exports);
+__exportStar(require("./fetcher"), exports);
+//# sourceMappingURL=index.js.map

package/lib/services/subgraph/schema.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Which field-naming schema a deployed August vault subgraph uses:
+ * - `'old'` — snake_case fields (`block_number`, `timestamp_`, `transactionHash_`).
+ * - `'new'` — camelCase fields (`blockNumber`, `blockTimestamp`, `transactionHash`).
+ *
+ * The two templates are otherwise equivalent; the SDK aliases new-schema fields
+ * back to the old internal names when querying, so the rest of the code only ever
+ * sees the old (snake_case) shape.
+ */
+export type SubgraphSchema = 'old' | 'new';
+/**
+ * True when a GraphQL error array reports an unknown field on the queried type
+ * (message contains "has no field") — the signature of a schema mismatch.
+ *
+ * @param errors - GraphQL `errors` array from a subgraph response (may be undefined).
+ * @returns `true` if any error message indicates an unknown field, else `false`.
+ */
+export declare function isSubgraphSchemaFieldError(errors: {
+    message?: string;
+}[] | undefined): boolean;
+/**
+ * Detects whether a deployed subgraph uses the old or new field schema by probing
+ * a single field (`blockTimestamp`) that exists only on the new template.
+ *
+ * This replaces the previous heuristic — "vault symbol present in the deprecated
+ * `SUBGRAPH_VAULT_URLS` map ⇒ old schema, else new" — which mis-guessed any
+ * newly-added vault whose subgraph shipped on the old template (e.g.
+ * `august-citrea-earn-ctusd`). A wrong guess made every subgraph read query
+ * non-existent field names, so the subgraph returned GraphQL errors with no
+ * `data` and the SDK silently returned empty sets — emptying the Pending
+ * Withdrawals and History tabs for that vault (AUGUST-6568).
+ *
+ * Because the schema is immutable for a fixed subgraph deployment, the result is
+ * cached per URL ({@link SCHEMA_TTL_MS}); across a page's positions/history/
+ * withdrawals reads this amounts to a single extra lightweight query per subgraph.
+ *
+ * Side effects: at most one HTTP POST to the subgraph per URL per TTL window.
+ *
+ * @param goldskyUrl - Fully-qualified subgraph GraphQL endpoint.
+ * @param apiKey - Optional Goldsky API key sent as a Bearer token.
+ * @returns `'old'` or `'new'`. Defaults to `'new'` when the URL is empty or the
+ *   probe is inconclusive (network error / unexpected response) — the schema the
+ *   majority of current vaults use.
+ */
+export declare function resolveSubgraphSchema(goldskyUrl: string, apiKey?: string): Promise<SubgraphSchema>;

package/lib/services/subgraph/schema.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSubgraphSchemaFieldError = isSubgraphSchemaFieldError;
+exports.resolveSubgraphSchema = resolveSubgraphSchema;
+const core_1 = require("../../core");
+const fetcher_1 = require("./fetcher");
+const SCHEMA_CACHE_PREFIX = 'subgraph-schema-';
+// A subgraph's schema is fixed for a given deployment/version, so one probe can
+// serve every subsequent read for a long time. Cache generously.
+const SCHEMA_TTL_MS = 60 * 60 * 1000; // 1 hour
+/**
+ * True when a GraphQL error array reports an unknown field on the queried type
+ * (message contains "has no field") — the signature of a schema mismatch.
+ *
+ * @param errors - GraphQL `errors` array from a subgraph response (may be undefined).
+ * @returns `true` if any error message indicates an unknown field, else `false`.
+ */
+function isSubgraphSchemaFieldError(errors) {
+    return Boolean(errors?.some((e) => e?.message?.includes('has no field')));
+}
+/**
+ * Detects whether a deployed subgraph uses the old or new field schema by probing
+ * a single field (`blockTimestamp`) that exists only on the new template.
+ *
+ * This replaces the previous heuristic — "vault symbol present in the deprecated
+ * `SUBGRAPH_VAULT_URLS` map ⇒ old schema, else new" — which mis-guessed any
+ * newly-added vault whose subgraph shipped on the old template (e.g.
+ * `august-citrea-earn-ctusd`). A wrong guess made every subgraph read query
+ * non-existent field names, so the subgraph returned GraphQL errors with no
+ * `data` and the SDK silently returned empty sets — emptying the Pending
+ * Withdrawals and History tabs for that vault (AUGUST-6568).
+ *
+ * Because the schema is immutable for a fixed subgraph deployment, the result is
+ * cached per URL ({@link SCHEMA_TTL_MS}); across a page's positions/history/
+ * withdrawals reads this amounts to a single extra lightweight query per subgraph.
+ *
+ * Side effects: at most one HTTP POST to the subgraph per URL per TTL window.
+ *
+ * @param goldskyUrl - Fully-qualified subgraph GraphQL endpoint.
+ * @param apiKey - Optional Goldsky API key sent as a Bearer token.
+ * @returns `'old'` or `'new'`. Defaults to `'new'` when the URL is empty or the
+ *   probe is inconclusive (network error / unexpected response) — the schema the
+ *   majority of current vaults use.
+ */
+async function resolveSubgraphSchema(goldskyUrl, apiKey) {
+    if (!goldskyUrl)
+        return 'new';
+    const key = `${SCHEMA_CACHE_PREFIX}${goldskyUrl}`;
+    const cached = core_1.CACHE.get(key);
+    if (cached)
+        return cached;
+    try {
+        // `blockTimestamp` is a new-schema-only field. If the subgraph rejects it
+        // with an unknown-field error, the deployment is old-schema. Schema
+        // validation is static, so this is authoritative even when the entity has
+        // zero rows.
+        const result = await (0, fetcher_1.fetchSubgraph)(goldskyUrl, `{ withdrawalRequesteds(first: 1) { blockTimestamp } }`, apiKey);
+        let schema = 'new';
+        if (result.status === 200) {
+            const json = (await result.json());
+            if (isSubgraphSchemaFieldError(json?.errors)) {
+                schema = 'old';
+            }
+        }
+        core_1.CACHE.set(key, schema, { ttl: SCHEMA_TTL_MS });
+        return schema;
+    }
+    catch (e) {
+        // Don't cache an inconclusive probe — let the next call retry. Default to
+        // 'new' so freshly-deployed vaults keep working when the probe is flaky.
+        core_1.Logger.log.warn('resolveSubgraphSchema', `probe failed for ${goldskyUrl}, defaulting to new schema: ${e instanceof Error ? e.message : 'unknown error'}`);
+        return 'new';
+    }
+}
+//# sourceMappingURL=schema.js.map

package/lib/services/subgraph/vaults.d.ts

@@ -0,0 +1,25 @@
+import type { IAddress, IContractRunner, ISubgraphTransfer, ISubgraphUserHistoryItem, ISubgraphWithdrawProccessed, ISubgraphWithdrawRequest } from '../../types';
+export declare function isOldSubgraphSchema(vaultSymbol: string): boolean;
+/**
+ *
+ * @param pool
+ * @param provider
+ * @returns
+ */
+export declare function getSubgraphWithdrawRequests(pool: IAddress, provider: IContractRunner, slackWebookUrl?: string): Promise<ISubgraphWithdrawRequest[]>;
+export declare function getSubgraphWithdrawProccessed(pool: IAddress, provider: IContractRunner, slackWebookUrl?: string): Promise<ISubgraphWithdrawProccessed[]>;
+/**
+ *
+ * @param pool
+ * @param provider
+ * @returns
+ */
+export declare function getSubgraphAllWithdrawals(pool: IAddress, provider: IContractRunner, slackWebookUrl?: string): Promise<{
+    withdrawalRequesteds: ISubgraphWithdrawRequest[];
+    withdrawalProcesseds: ISubgraphWithdrawProccessed[];
+}>;
+export declare function getSubgraphUserHistory(user: IAddress, provider: IContractRunner, pool: IAddress, slackWebookUrl?: string): Promise<ISubgraphUserHistoryItem[]>;
+export declare function getSubgraphVaultHistory(provider: IContractRunner, pool: IAddress, slackWebookUrl?: string, opts?: {
+    sinceTs?: number;
+}): Promise<ISubgraphUserHistoryItem[]>;
+export declare function getSubgraphUserTransfers(user: IAddress, provider: IContractRunner, pool: IAddress, slackWebookUrl?: string): Promise<ISubgraphTransfer[]>;