@augustdigital/sdk/README.md

JS SDK powering the August Digital ecosystem.

# August Digital SDK

TypeScript SDK for interacting with August Digital vaults across EVM and Solana chains.

## Installation

```bash
npm install @augustdigital/sdk ethers
# or
pnpm add @augustdigital/sdk ethers
# or
yarn add @augustdigital/sdk ethers
```

### Wagmi/Viem Support

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 SDK will automatically detect and convert viem WalletClient to ethers-compatible signers.

## Quick Start

```typescript
import { AugustSDK } from '@augustdigital/sdk';

// 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')
  },
});

// Fetch all vaults
const vaults = await sdk.getVaults();

// 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.