@augustdigital/sdk 4.1.0-alpha → 4.1.0

package/README.md

@@ -1,23 +1,201 @@
 # August Digital SDK
 
-This repo serves as the JS SDK powering the August Digital ecosystem that can easily be used in your web app.
+TypeScript SDK for interacting with August Digital vaults across EVM and Solana chains.
 
-** Note: there is not much logic found in this repo. Simply a centralized location that exports all other packages' logic. **
+## Installation
 
-## Available Modules
+```bash
+npm install @augustdigital/sdk ethers
+# or
+pnpm add @augustdigital/sdk ethers
+# or
+yarn add @augustdigital/sdk ethers
+```
+
+### Wagmi/Viem Support
 
-This repo, by default, exports the SDK class in addition to other helpful, stand-alone methods and variables that are commonly used.
+The SDK supports both ethers and wagmi/viem signers. If you're using wagmi in your React app, also install viem:
+
+```bash
+npm install viem
+```
 
-The default exported class is primarily used to fetch data respective to your initialization configuration.
+The SDK will automatically detect and convert viem WalletClient to ethers-compatible signers.
 
-Other stand-alone methods and variables are also exported including all items from "@augustdigital/utils". Additionally, all ABIs and interfaces are exported from here with "ABI\_" and "I" prefixes.
+## Quick Start
 
-## Usage
+```typescript
+import { AugustSDK } from '@augustdigital/sdk';
 
-Default exported class initialization and then fetching a lending pool:
+// Initialize with RPC providers
+const sdk = new AugustSDK({
+  providers: {
+    1: 'https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY',
+    42161: 'https://arb-mainnet.g.alchemy.com/v2/YOUR_KEY',
+    -1: 'https://api.mainnet-beta.solana.com', // Solana
+  },
+  keys: {
+    august: 'YOUR_API_KEY', // Optional
+  },
+  monitoring: {
+    env: 'DEV', // Optional: 'DEV' enables console logging (defaults to 'PROD')
+  },
+});
 
-```javascript
-import AugustDigitalSDK from '@augustdigital/sdk';
+// Fetch all vaults
+const vaults = await sdk.getVaults();
 
-await new AugustDigitalSDK(config).pools.getPool(POOL_ADDRESS);
+// Fetch specific vault with loans and allocations
+const vault = await sdk.getVault({
+  vault: '0x...',
+  options: { loans: true, allocations: true }
+});
+
+// Get user positions
+const positions = await sdk.getVaultPositions({
+  wallet: '0x...',
+  showAllVaults: true,
+});
 ```
+
+## Architecture
+
+```
+src.ts/
+├── main.ts              # Main SDK class (AugustSDK)
+├── core/                # Base utilities
+│   ├── base.class.ts    # Base SDK functionality
+│   ├── 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
+├── modules/             # Feature modules
+│   └── vaults/          # Vault operations
+│       ├── main.ts      # AugustVaults class
+│       ├── getters.ts   # Data fetching functions
+│       └── utils.ts     # Helper utilities
+├── services/            # External service integrations
+│   ├── debank/          # DeFi allocation data
+│   ├── coingecko/       # Token pricing
+│   └── subgraph/        # Historical transaction data
+└── types/               # TypeScript interfaces
+```
+
+## Key Concepts
+
+### Multi-Chain Support
+
+- **EVM Chains**: Ethereum, Arbitrum, Base, BSC, Avalanche
+- **Solana**: Native Solana program support
+- Unified interface across all chains
+
+### Vault Versions
+
+- `evm-0/evm-1`: Legacy vault contracts
+- `evm-2`: Current EVM vault architecture (separate receipt tokens)
+- `sol-0`: Solana program-based vaults
+
+### Data Enrichment
+
+All vault queries support optional enrichment:
+
+- `loans`: Include active loan data
+- `allocations`: DeFi/CeFi/OTC position breakdowns
+- `wallet`: User-specific position data
+
+## Code Conventions
+
+### Naming Patterns
+
+- **Interfaces**: Prefixed with `I` (e.g., `IVault`, `IVaultLoan`)
+- **ABIs**: Prefixed with `ABI_` (e.g., `ABI_LENDING_POOL_V2`)
+- **Types**: Descriptive names (e.g., `IAddress`, `IChainId`)
+
+### Important Tags
+
+Search codebase for these comments to find areas needing attention:
+
+- `@todo`: Planned improvements or missing features
+- `@hardcoded`: Hardcoded values that may need configuration
+- `@solana`: Solana-specific logic or notes
+
+### 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
+
+```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
+});
+```
+
+- `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
+
+- `getVaultPositions({ wallet?, vault?, chainId? })`: User vault positions
+- `getVaultAvailableRedemptions({ vault, wallet?, chainId })`: Claimable redemptions
+- `getVaultUserHistory({ wallet, vault?, chainId? })`: Transaction history
+- `getVaultStakingPositions({ wallet, chainId })`: Staking positions
+
+#### Utilities
+
+- `getPrice(symbol)`: Get token price in USD
+- `switchNetwork(chainId)`: Change active chain
+- `updateWallet(address)`: Set active wallet for tracking
+
+## Development
+
+### Running Tests
+
+```bash
+pnpm test
+```
+
+### Building
+
+```bash
+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.

package/lib/abis/Multicall3.js.map

@@ -1 +1 @@
-{"version":3,"file":"Multicall3.js","sourceRoot":"","sources":["../../src.ts/abis/Multicall3.ts"],"names":[],"mappings":";;;AACa,QAAA,cAAc,GAAG;IAC5B;QACE,MAAM,EAAE;YACN;gBACE,UAAU,EAAE;oBACV;wBACE,IAAI,EAAE,QAAQ;wBACd,IAAI,EAAE,SAAS;qBAChB;oBACD;wBACE,IAAI,EAAE,cAAc;wBACpB,IAAI,EAAE,MAAM;qBACb;oBACD;wBACE,IAAI,EAAE,UAAU;wBAChB,IAAI,EAAE,OAAO;qBACd;iBACF;gBACD,IAAI,EAAE,OAAO;gBACb,IAAI,EAAE,SAAS;aAChB;SACF;QACD,IAAI,EAAE,YAAY;QAClB,OAAO,EAAE;YACP;gBACE,UAAU,EAAE;oBACV;wBACE,IAAI,EAAE,SAAS;wBACf,IAAI,EAAE,MAAM;qBACb;oBACD;wBACE,IAAI,EAAE,YAAY;wBAClB,IAAI,EAAE,OAAO;qBACd;iBACF;gBACD,IAAI,EAAE,YAAY;gBAClB,IAAI,EAAE,SAAS;aAChB;SACF;QACD,eAAe,EAAE,MAAM;QACvB,IAAI,EAAE,UAAU;KACjB;CACO,CAAC;AAEX,MAAM,uBAAuB,GAAG;IAC9B;QACE,MAAM,EAAE,EAAE;QACV,IAAI,EAAE,kBAAkB;QACxB,IAAI,EAAE,OAAO;KACd;IACD;QACE,MAAM,EAAE,EAAE;QACV,IAAI,EAAE,8BAA8B;QACpC,IAAI,EAAE,OAAO;KACd;IACD;QACE,MAAM,EAAE,EAAE;QACV,IAAI,EAAE,qBAAqB;QAC3B,IAAI,EAAE,OAAO;KACd;IACD;QACE,MAAM,EAAE;YACN;gBACE,IAAI,EAAE,YAAY;gBAClB,IAAI,EAAE,OAAO;aACd;SACF;QACD,IAAI,EAAE,eAAe;QACrB,IAAI,EAAE,OAAO;KACd;IACD;QACE,MAAM,EAAE;YACN;gBACE,UAAU,EAAE;oBACV;wBACE,IAAI,EAAE,QAAQ;wBACd,IAAI,EAAE,QAAQ;qBACf;oBACD;wBACE,IAAI,EAAE,SAAS;wBACf,IAAI,EAAE,QAAQ;qBACf;iBACF;gBACD,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,SAAS;aAChB;SACF;QACD,IAAI,EAAE,WAAW;QACjB,IAAI,EAAE,OAAO;KACd;CACO,CAAC"}
+{"version":3,"file":"Multicall3.js","sourceRoot":"","sources":["../../src.ts/abis/Multicall3.ts"],"names":[],"mappings":";;;AACa,QAAA,cAAc,GAAG;IAC5B;QACE,MAAM,EAAE;YACN;gBACE,UAAU,EAAE;oBACV;wBACE,IAAI,EAAE,QAAQ;wBACd,IAAI,EAAE,SAAS;qBAChB;oBACD;wBACE,IAAI,EAAE,cAAc;wBACpB,IAAI,EAAE,MAAM;qBACb;oBACD;wBACE,IAAI,EAAE,UAAU;wBAChB,IAAI,EAAE,OAAO;qBACd;iBACF;gBACD,IAAI,EAAE,OAAO;gBACb,IAAI,EAAE,SAAS;aAChB;SACF;QACD,IAAI,EAAE,YAAY;QAClB,OAAO,EAAE;YACP;gBACE,UAAU,EAAE;oBACV;wBACE,IAAI,EAAE,SAAS;wBACf,IAAI,EAAE,MAAM;qBACb;oBACD;wBACE,IAAI,EAAE,YAAY;wBAClB,IAAI,EAAE,OAAO;qBACd;iBACF;gBACD,IAAI,EAAE,YAAY;gBAClB,IAAI,EAAE,SAAS;aAChB;SACF;QACD,eAAe,EAAE,MAAM;QACvB,IAAI,EAAE,UAAU;KACjB;CACO,CAAC;AAIX,MAAM,uBAAuB,GAAG;IAC9B;QACE,MAAM,EAAE,EAAE;QACV,IAAI,EAAE,kBAAkB;QACxB,IAAI,EAAE,OAAO;KACd;IACD;QACE,MAAM,EAAE,EAAE;QACV,IAAI,EAAE,8BAA8B;QACpC,IAAI,EAAE,OAAO;KACd;IACD;QACE,MAAM,EAAE,EAAE;QACV,IAAI,EAAE,qBAAqB;QAC3B,IAAI,EAAE,OAAO;KACd;IACD;QACE,MAAM,EAAE;YACN;gBACE,IAAI,EAAE,YAAY;gBAClB,IAAI,EAAE,OAAO;aACd;SACF;QACD,IAAI,EAAE,eAAe;QACrB,IAAI,EAAE,OAAO;KACd;IACD;QACE,MAAM,EAAE;YACN;gBACE,UAAU,EAAE;oBACV;wBACE,IAAI,EAAE,QAAQ;wBACd,IAAI,EAAE,QAAQ;qBACf;oBACD;wBACE,IAAI,EAAE,SAAS;wBACf,IAAI,EAAE,QAAQ;qBACf;iBACF;gBACD,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,SAAS;aAChB;SACF;QACD,IAAI,EAAE,WAAW;QACjB,IAAI,EAAE,OAAO;KACd;CACO,CAAC"}

package/lib/abis/PoolAdapter.d.ts

@@ -1,76 +1,36 @@
-export declare const ABI_POOL_ADAPTER: ({
-    inputs: ({
-        internalType: string;
-        name: string;
-        type: string;
-        components?: undefined;
-    } | {
-        components: {
-            internalType: string;
-            name: string;
-            type: string;
-        }[];
-        internalType: string;
-        name: string;
-        type: string;
-    })[];
-    stateMutability: string;
-    type: string;
-    name?: undefined;
-    anonymous?: undefined;
-    outputs?: undefined;
-} | {
-    inputs: any[];
-    name: string;
-    type: string;
-    stateMutability?: undefined;
-    anonymous?: undefined;
-    outputs?: undefined;
-} | {
-    anonymous: boolean;
-    inputs: {
-        indexed: boolean;
-        internalType: string;
-        name: string;
-        type: string;
-    }[];
-    name: string;
-    type: string;
-    stateMutability?: undefined;
-    outputs?: undefined;
-} | {
-    inputs: {
-        internalType: string;
-        name: string;
-        type: string;
-    }[];
-    name: string;
-    outputs: {
-        internalType: string;
-        name: string;
-        type: string;
-    }[];
-    stateMutability: string;
-    type: string;
-    anonymous?: undefined;
-} | {
-    inputs: {
-        components: {
-            internalType: string;
-            name: string;
-            type: string;
-        }[];
-        internalType: string;
-        name: string;
-        type: string;
-    }[];
-    name: string;
-    outputs: {
-        internalType: string;
-        name: string;
-        type: string;
-    }[];
-    stateMutability: string;
-    type: string;
-    anonymous?: undefined;
-})[];
+export declare const ABI_POOL_ADAPTER: readonly [{
+    readonly inputs: readonly [{
+        readonly components: readonly [{
+            readonly internalType: "uint256";
+            readonly name: "amountIn";
+            readonly type: "uint256";
+        }, {
+            readonly internalType: "uint256";
+            readonly name: "minAmountOut";
+            readonly type: "uint256";
+        }, {
+            readonly internalType: "address";
+            readonly name: "srcToken";
+            readonly type: "address";
+        }, {
+            readonly internalType: "address";
+            readonly name: "dstToken";
+            readonly type: "address";
+        }, {
+            readonly internalType: "uint256";
+            readonly name: "bridgeId";
+            readonly type: "uint256";
+        }, {
+            readonly internalType: "bytes";
+            readonly name: "quoteData";
+            readonly type: "bytes";
+        }];
+        readonly internalType: "struct PoolAdapter.SwapAndDepositParams";
+        readonly name: "params";
+        readonly type: "tuple";
+    }];
+    readonly name: "swapAndDeposit";
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+    readonly type: "function";
+}];