@augustdigital/sdk 4.0.5-alpha → 4.0.5-beta

package/README.md

@@ -1,23 +1,181 @@
 # 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. **
+## Quick Start
 
-## Available Modules
+```typescript
+import { AugustSDK } from '@augustdigital/sdk';
 
-This repo, by default, exports the SDK class in addition to other helpful, stand-alone methods and variables that are commonly used.
+// 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')
+  },
+});
 
-The default exported class is primarily used to fetch data respective to your initialization configuration.
+// Fetch all vaults
+const vaults = await sdk.getVaults();
 
-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.
+// Fetch specific vault with loans and allocations
+const vault = await sdk.getVault({
+  vault: '0x...',
+  options: { loans: true, allocations: true }
+});
 
-## Usage
+// 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
 
-Default exported class initialization and then fetching a lending pool:
+### Environment Configuration
 
-```javascript
-import AugustDigitalSDK from '@augustdigital/sdk';
+```typescript
+// Development mode (enables console logging)
+const devSdk = new AugustSDK({
+  providers: {
+    /* ... */
+  },
+  monitoring: {
+    env: 'DEV',
+  },
+});
 
-await new AugustDigitalSDK(config).pools.getPool(POOL_ADDRESS);
+// 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/AddressResolver.d.ts

@@ -0,0 +1,28 @@
+export declare const ABI_ADDRESS_RESOLVER: readonly [{
+    readonly name: "addr";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "name";
+        readonly type: "bytes32";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+    }];
+}, {
+    readonly name: "addr";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "name";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "coinType";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bytes";
+    }];
+}];

package/lib/abis/AddressResolver.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ABI_ADDRESS_RESOLVER = void 0;
+exports.ABI_ADDRESS_RESOLVER = [
+    {
+        name: 'addr',
+        type: 'function',
+        stateMutability: 'view',
+        inputs: [{ name: 'name', type: 'bytes32' }],
+        outputs: [{ name: '', type: 'address' }],
+    },
+    {
+        name: 'addr',
+        type: 'function',
+        stateMutability: 'view',
+        inputs: [
+            { name: 'name', type: 'bytes32' },
+            { name: 'coinType', type: 'uint256' },
+        ],
+        outputs: [{ name: '', type: 'bytes' }],
+    },
+];
+//# sourceMappingURL=AddressResolver.js.map

package/lib/abis/AddressResolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AddressResolver.js","sourceRoot":"","sources":["../../src.ts/abis/AddressResolver.ts"],"names":[],"mappings":";;;AAAa,QAAA,oBAAoB,GAAG;IAClC;QACE,IAAI,EAAE,MAAM;QACZ,IAAI,EAAE,UAAU;QAChB,eAAe,EAAE,MAAM;QACvB,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QAC3C,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;KACzC;IACD;QACE,IAAI,EAAE,MAAM;QACZ,IAAI,EAAE,UAAU;QAChB,eAAe,EAAE,MAAM;QACvB,MAAM,EAAE;YACN,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE;YACjC,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE;SACtC;QACD,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;KACvC;CACO,CAAC"}

package/lib/abis/ChainlinkV3.d.ts

@@ -0,0 +1,87 @@
+export declare const ABI_CHAINLINK_V3: readonly [{
+    readonly inputs: readonly [];
+    readonly name: "decimals";
+    readonly outputs: readonly [{
+        readonly internalType: "uint8";
+        readonly name: "";
+        readonly type: "uint8";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "description";
+    readonly outputs: readonly [{
+        readonly internalType: "string";
+        readonly name: "";
+        readonly type: "string";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly internalType: "uint80";
+        readonly name: "_roundId";
+        readonly type: "uint80";
+    }];
+    readonly name: "getRoundData";
+    readonly outputs: readonly [{
+        readonly internalType: "uint80";
+        readonly name: "roundId";
+        readonly type: "uint80";
+    }, {
+        readonly internalType: "int256";
+        readonly name: "answer";
+        readonly type: "int256";
+    }, {
+        readonly internalType: "uint256";
+        readonly name: "startedAt";
+        readonly type: "uint256";
+    }, {
+        readonly internalType: "uint256";
+        readonly name: "updatedAt";
+        readonly type: "uint256";
+    }, {
+        readonly internalType: "uint80";
+        readonly name: "answeredInRound";
+        readonly type: "uint80";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "latestRoundData";
+    readonly outputs: readonly [{
+        readonly internalType: "uint80";
+        readonly name: "roundId";
+        readonly type: "uint80";
+    }, {
+        readonly internalType: "int256";
+        readonly name: "answer";
+        readonly type: "int256";
+    }, {
+        readonly internalType: "uint256";
+        readonly name: "startedAt";
+        readonly type: "uint256";
+    }, {
+        readonly internalType: "uint256";
+        readonly name: "updatedAt";
+        readonly type: "uint256";
+    }, {
+        readonly internalType: "uint80";
+        readonly name: "answeredInRound";
+        readonly type: "uint80";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "version";
+    readonly outputs: readonly [{
+        readonly internalType: "uint256";
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}];

package/lib/abis/ChainlinkV3.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ABI_CHAINLINK_V3 = void 0;
+exports.ABI_CHAINLINK_V3 = [
+    {
+        inputs: [],
+        name: 'decimals',
+        outputs: [
+            {
+                internalType: 'uint8',
+                name: '',
+                type: 'uint8',
+            },
+        ],
+        stateMutability: 'view',
+        type: 'function',
+    },
+    {
+        inputs: [],
+        name: 'description',
+        outputs: [
+            {
+                internalType: 'string',
+                name: '',
+                type: 'string',
+            },
+        ],
+        stateMutability: 'view',
+        type: 'function',
+    },
+    {
+        inputs: [
+            {
+                internalType: 'uint80',
+                name: '_roundId',
+                type: 'uint80',
+            },
+        ],
+        name: 'getRoundData',
+        outputs: [
+            {
+                internalType: 'uint80',
+                name: 'roundId',
+                type: 'uint80',
+            },
+            {
+                internalType: 'int256',
+                name: 'answer',
+                type: 'int256',
+            },
+            {
+                internalType: 'uint256',
+                name: 'startedAt',
+                type: 'uint256',
+            },
+            {
+                internalType: 'uint256',
+                name: 'updatedAt',
+                type: 'uint256',
+            },
+            {
+                internalType: 'uint80',
+                name: 'answeredInRound',
+                type: 'uint80',
+            },
+        ],
+        stateMutability: 'view',
+        type: 'function',
+    },
+    {
+        inputs: [],
+        name: 'latestRoundData',
+        outputs: [
+            {
+                internalType: 'uint80',
+                name: 'roundId',
+                type: 'uint80',
+            },
+            {
+                internalType: 'int256',
+                name: 'answer',
+                type: 'int256',
+            },
+            {
+                internalType: 'uint256',
+                name: 'startedAt',
+                type: 'uint256',
+            },
+            {
+                internalType: 'uint256',
+                name: 'updatedAt',
+                type: 'uint256',
+            },
+            {
+                internalType: 'uint80',
+                name: 'answeredInRound',
+                type: 'uint80',
+            },
+        ],
+        stateMutability: 'view',
+        type: 'function',
+    },
+    {
+        inputs: [],
+        name: 'version',
+        outputs: [
+            {
+                internalType: 'uint256',
+                name: '',
+                type: 'uint256',
+            },
+        ],
+        stateMutability: 'view',
+        type: 'function',
+    },
+];
+//# sourceMappingURL=ChainlinkV3.js.map

package/lib/abis/ChainlinkV3.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChainlinkV3.js","sourceRoot":"","sources":["../../src.ts/abis/ChainlinkV3.ts"],"names":[],"mappings":";;;AAAa,QAAA,gBAAgB,GAAG;IAC9B;QACE,MAAM,EAAE,EAAE;QACV,IAAI,EAAE,UAAU;QAChB,OAAO,EAAE;YACP;gBACE,YAAY,EAAE,OAAO;gBACrB,IAAI,EAAE,EAAE;gBACR,IAAI,EAAE,OAAO;aACd;SACF;QACD,eAAe,EAAE,MAAM;QACvB,IAAI,EAAE,UAAU;KACjB;IACD;QACE,MAAM,EAAE,EAAE;QACV,IAAI,EAAE,aAAa;QACnB,OAAO,EAAE;YACP;gBACE,YAAY,EAAE,QAAQ;gBACtB,IAAI,EAAE,EAAE;gBACR,IAAI,EAAE,QAAQ;aACf;SACF;QACD,eAAe,EAAE,MAAM;QACvB,IAAI,EAAE,UAAU;KACjB;IACD;QACE,MAAM,EAAE;YACN;gBACE,YAAY,EAAE,QAAQ;gBACtB,IAAI,EAAE,UAAU;gBAChB,IAAI,EAAE,QAAQ;aACf;SACF;QACD,IAAI,EAAE,cAAc;QACpB,OAAO,EAAE;YACP;gBACE,YAAY,EAAE,QAAQ;gBACtB,IAAI,EAAE,SAAS;gBACf,IAAI,EAAE,QAAQ;aACf;YACD;gBACE,YAAY,EAAE,QAAQ;gBACtB,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,QAAQ;aACf;YACD;gBACE,YAAY,EAAE,SAAS;gBACvB,IAAI,EAAE,WAAW;gBACjB,IAAI,EAAE,SAAS;aAChB;YACD;gBACE,YAAY,EAAE,SAAS;gBACvB,IAAI,EAAE,WAAW;gBACjB,IAAI,EAAE,SAAS;aAChB;YACD;gBACE,YAAY,EAAE,QAAQ;gBACtB,IAAI,EAAE,iBAAiB;gBACvB,IAAI,EAAE,QAAQ;aACf;SACF;QACD,eAAe,EAAE,MAAM;QACvB,IAAI,EAAE,UAAU;KACjB;IACD;QACE,MAAM,EAAE,EAAE;QACV,IAAI,EAAE,iBAAiB;QACvB,OAAO,EAAE;YACP;gBACE,YAAY,EAAE,QAAQ;gBACtB,IAAI,EAAE,SAAS;gBACf,IAAI,EAAE,QAAQ;aACf;YACD;gBACE,YAAY,EAAE,QAAQ;gBACtB,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,QAAQ;aACf;YACD;gBACE,YAAY,EAAE,SAAS;gBACvB,IAAI,EAAE,WAAW;gBACjB,IAAI,EAAE,SAAS;aAChB;YACD;gBACE,YAAY,EAAE,SAAS;gBACvB,IAAI,EAAE,WAAW;gBACjB,IAAI,EAAE,SAAS;aAChB;YACD;gBACE,YAAY,EAAE,QAAQ;gBACtB,IAAI,EAAE,iBAAiB;gBACvB,IAAI,EAAE,QAAQ;aACf;SACF;QACD,eAAe,EAAE,MAAM;QACvB,IAAI,EAAE,UAAU;KACjB;IACD;QACE,MAAM,EAAE,EAAE;QACV,IAAI,EAAE,SAAS;QACf,OAAO,EAAE;YACP;gBACE,YAAY,EAAE,SAAS;gBACvB,IAAI,EAAE,EAAE;gBACR,IAAI,EAAE,SAAS;aAChB;SACF;QACD,eAAe,EAAE,MAAM;QACvB,IAAI,EAAE,UAAU;KACjB;CACO,CAAC"}

package/lib/abis/ERC20.d.ts

@@ -0,0 +1,168 @@
+export declare const ABI_ERC20: readonly [{
+    readonly constant: true;
+    readonly inputs: readonly [];
+    readonly name: "name";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "string";
+    }];
+    readonly payable: false;
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly constant: false;
+    readonly inputs: readonly [{
+        readonly name: "_spender";
+        readonly type: "address";
+    }, {
+        readonly name: "_value";
+        readonly type: "uint256";
+    }];
+    readonly name: "approve";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+    }];
+    readonly payable: false;
+    readonly stateMutability: "nonpayable";
+    readonly type: "function";
+}, {
+    readonly constant: true;
+    readonly inputs: readonly [];
+    readonly name: "totalSupply";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+    readonly payable: false;
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly constant: false;
+    readonly inputs: readonly [{
+        readonly name: "_from";
+        readonly type: "address";
+    }, {
+        readonly name: "_to";
+        readonly type: "address";
+    }, {
+        readonly name: "_value";
+        readonly type: "uint256";
+    }];
+    readonly name: "transferFrom";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+    }];
+    readonly payable: false;
+    readonly stateMutability: "nonpayable";
+    readonly type: "function";
+}, {
+    readonly constant: true;
+    readonly inputs: readonly [];
+    readonly name: "decimals";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint8";
+    }];
+    readonly payable: false;
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly constant: true;
+    readonly inputs: readonly [{
+        readonly name: "_owner";
+        readonly type: "address";
+    }];
+    readonly name: "balanceOf";
+    readonly outputs: readonly [{
+        readonly name: "balance";
+        readonly type: "uint256";
+    }];
+    readonly payable: false;
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly constant: true;
+    readonly inputs: readonly [];
+    readonly name: "symbol";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "string";
+    }];
+    readonly payable: false;
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly constant: false;
+    readonly inputs: readonly [{
+        readonly name: "_to";
+        readonly type: "address";
+    }, {
+        readonly name: "_value";
+        readonly type: "uint256";
+    }];
+    readonly name: "transfer";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+    }];
+    readonly payable: false;
+    readonly stateMutability: "nonpayable";
+    readonly type: "function";
+}, {
+    readonly constant: true;
+    readonly inputs: readonly [{
+        readonly name: "_owner";
+        readonly type: "address";
+    }, {
+        readonly name: "_spender";
+        readonly type: "address";
+    }];
+    readonly name: "allowance";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+    readonly payable: false;
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly payable: true;
+    readonly stateMutability: "payable";
+    readonly type: "fallback";
+}, {
+    readonly anonymous: false;
+    readonly inputs: readonly [{
+        readonly indexed: true;
+        readonly name: "owner";
+        readonly type: "address";
+    }, {
+        readonly indexed: true;
+        readonly name: "spender";
+        readonly type: "address";
+    }, {
+        readonly indexed: false;
+        readonly name: "value";
+        readonly type: "uint256";
+    }];
+    readonly name: "Approval";
+    readonly type: "event";
+}, {
+    readonly anonymous: false;
+    readonly inputs: readonly [{
+        readonly indexed: true;
+        readonly name: "from";
+        readonly type: "address";
+    }, {
+        readonly indexed: true;
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly indexed: false;
+        readonly name: "value";
+        readonly type: "uint256";
+    }];
+    readonly name: "Transfer";
+    readonly type: "event";
+}];