upshift-sdk 8.20.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 August Digital
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,349 @@
+# August Digital SDK
+
+TypeScript SDK for interacting with August Digital vaults across EVM, Solana, Stellar, and Sui 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 automatically converts viem `WalletClient` to an ethers-compatible signer.
+
+## Quick Start
+
+```typescript
+import AugustSDK from '@augustdigital/sdk';
+
+const sdk = new AugustSDK({
+  // Required: stable kebab-case slug identifying your application.
+  appName: 'acme-trader',
+  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: required for allocations, health factors, and sub-account operations
+  },
+  monitoring: {
+    env: 'DEV', // Optional: 'DEV' enables console logging (defaults to 'PROD')
+  },
+});
+
+// Fetch all vaults
+const vaults = await sdk.getVaults();
+
+// Fetch a 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,
+});
+```
+
+### App Name
+
+`appName` is required on every `AugustSDK` constructor call. Pass a stable kebab-case slug
+identifying your application (e.g. `'acme-trader'`, `'my-defi-app'`):
+
+- **What it's used for.** August Digital tags analytics events with `app.name = <yourSlug>` to
+  attribute error spikes and prioritize bug fixes by consuming app.
+- **What it is not.** Not a secret, not a license key, not a display label. Pick a slug once
+  and reuse it across deployments.
+- **Constraints.** 3–64 characters, only `[a-zA-Z0-9._-]`. The SDK throws synchronously from
+  the constructor if the value is missing or invalid.
+
+```typescript
+// Will throw — appName is required.
+new AugustSDK({ providers: { /* ... */ } } as any);
+
+// Will throw — spaces not allowed. Use 'acme-trader'.
+new AugustSDK({ appName: 'Acme Trader', providers: { /* ... */ } });
+
+// Correct.
+new AugustSDK({ appName: 'acme-trader', providers: { /* ... */ } });
+```
+
+## 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 adapter (approve, deposit, redeem, read helpers)
+│   ├── solana/          # Solana program adapters
+│   ├── stellar/         # Stellar vault adapters
+│   └── sui/             # Sui (Ember) vault adapters
+├── evm/                 # EVM cross-chain (LayerZero OVault)
+├── modules/             # Feature modules
+│   ├── vaults/          # Vault read operations
+│   ├── sub-accounts/    # Sub-account queries
+│   └── api/             # August backend API integration
+├── 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, and more — `wagmi/viem` and `ethers` signers supported
+- **Solana**: Native Solana program support with full vault functionality
+- **Stellar**: Stellar vault deposit, redeem, and position queries
+- **Sui**: Ember vault read operations
+- 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
+- `stellar-0`: Stellar-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
+
+## API Reference
+
+### Vault Queries
+
+| Method | Description |
+| --- | --- |
+| `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 |
+| `getVaultHistoricalTimeseries({ vault, chainId? })` | Historical APY and TVL timeseries |
+| `getVaultApy({ vault, historical? })` | **@deprecated** — use `getVaultHistoricalTimeseries` |
+| `getVaultTvl({ vault, historical? })` | Current/historical TVL |
+| `getVaultAnnualizedApy({ vault })` | Annualized APY for a vault |
+| `getVaultSummary({ vault })` | Aggregated vault summary |
+| `getVaultPnl({ vault, chainId? })` | Vault-level PnL |
+| `getVaultUnrealizedPnlHistory({ vault, chainId?, ... })` | Unrealized PnL timeseries |
+| `getLatestUnrealizedPnl()` | Latest unrealized PnL snapshot across all vaults |
+| `getYieldLastRealizedOn({ vault, chainId? })` | Timestamp of last yield realization |
+| `getTotalDeposited(options?)` | Total deposited across vaults |
+
+### User Positions
+
+| Method | Description |
+| --- | --- |
+| `getVaultPositions({ wallet?, vault?, chainId? })` | User vault positions |
+| `getVaultAvailableRedemptions({ vault, wallet?, chainId, verbose? })` | Claimable redemptions |
+| `getVaultRedemptionHistory({ vault, wallet?, chainId? })` | Historical redemptions |
+| `getVaultUserHistory({ wallet, vault?, chainId? })` | Transaction history |
+| `getVaultUserTransfers({ wallet, vault?, chainId? })` | Transfer history |
+| `getVaultUserLifetimePnl({ wallet, vault?, chainId? })` | Lifetime PnL for a wallet |
+| `getVaultStakingPositions({ wallet, chainId })` | Staking positions |
+| `getVaultBorrowerHealthFactor(props?)` | Borrower health factor |
+| `getVaultWithdrawals({ vault, chainId? })` | Pending withdrawals |
+
+### Points
+
+| Method | Description |
+| --- | --- |
+| `getUserPoints(userAddress)` | Points balance for a wallet |
+| `registerUserForPoints({ wallet, referral? })` | Register a wallet for the points program |
+| `fetchPointsLeaderboard(params?)` | Points leaderboard |
+
+### Write Operations (top-level)
+
+| Method | Description |
+| --- | --- |
+| `vaultDeposit(signer, options)` | Deposit into a vault |
+| `previewRedemption(props)` | Preview redemption output before broadcasting |
+
+### Cross-Chain (LayerZero)
+
+| Method | Description |
+| --- | --- |
+| `getLayerZeroDeposits({ wallet?, chainId? })` | LayerZero deposit history |
+| `getLayerZeroRedeems(props?)` | LayerZero redemption history |
+
+### Utilities
+
+| Method | Description |
+| --- | --- |
+| `getPrice(symbol)` | Token price in USD |
+| `switchNetwork(chainId)` | Change active chain |
+| `updateWallet(address)` | Set active wallet for tracking |
+
+### Sub-Accounts (`sdk.subAccountsModule`)
+
+| Method | Description |
+| --- | --- |
+| `getSubaccountHealthFactor(address)` | Health factor for a sub-account |
+| `getSubaccountLoans(address)` | Active loans for a sub-account |
+| `getSubaccountCefiPositions(address)` | CeFi positions |
+| `getSubaccountOtcPositions(address)` | OTC positions |
+| `getSubaccountSummary(address)` | Aggregated sub-account summary |
+
+### EVM Adapter (`sdk.evm`)
+
+Set a signer before calling write methods:
+
+```typescript
+// ethers
+import { JsonRpcProvider, Wallet } from 'ethers';
+const wallet = new Wallet(process.env.PRIVATE_KEY!, new JsonRpcProvider(rpcUrl));
+sdk.evm.setSigner(wallet);
+
+// wagmi/viem (browser)
+import { useWalletClient } from 'wagmi';
+const { data: walletClient } = useWalletClient();
+if (walletClient) sdk.evm.setSigner(walletClient);
+```
+
+**Write methods:**
+
+| Method | Description |
+| --- | --- |
+| `vaultApprove(options)` | Approve token spend for a vault |
+| `approve(options)` | Generic ERC-20 approve |
+| `vaultDeposit(options)` | Deposit assets into a vault |
+| `vaultRequestRedeem(options)` | Request a withdrawal/redemption |
+| `vaultRedeem(signer, options)` | Claim an available redemption |
+| `depositNative(options)` | Deposit native tokens (ETH, etc.) |
+| `swapAndDeposit(options)` | Swap and deposit in one call |
+| `depositViaSwapRouter(options)` | Deposit via the swap router |
+| `depositNativeViaSwapRouter(options)` | Deposit native via the swap router |
+
+**Read helpers (return raw `bigint`):**
+
+| Method | Description |
+| --- | --- |
+| `previewDeposit(options)` | Shares minted for a deposit amount |
+| `previewRedeem(options)` | Assets returned for a share amount |
+| `allowance(options)` | ERC-20 allowance granted to the vault |
+| `balanceOf(options)` | ERC-20 balance for any token/owner |
+| `maxDeposit(options)` | Maximum deposit accepted by the vault |
+| `vaultAllowance(options)` | Vault-specific allowance check |
+| `getDeposited(options)` | Current deposited balance |
+| `getRemainingAllocations(options)` | Remaining allocation capacity |
+| `isWhitelisted(options)` | Check whitelist status |
+
+### Solana Adapter (`sdk.solana`)
+
+| Method | Description |
+| --- | --- |
+| `getVaultState(...)` | Vault state from the Solana program |
+| `getVaultStateReadOnly(...)` | Read-only vault state |
+| `getToken(mintAddress)` | SPL token info |
+| `getTokenSymbol(mintAddress)` | Token symbol |
+| `fetchUserTokenBalance(publicKey, mint)` | User SPL token balance |
+| `fetchUserShareBalance(publicKey, vault)` | User share balance |
+| `fetchUserShareBalanceRaw(publicKey, vault)` | Raw share balance (bigint) |
+
+### Stellar Adapter (`sdk.stellar`)
+
+| Method | Description |
+| --- | --- |
+| `vaultDeposit(options)` | Deposit into a Stellar vault |
+| `vaultRedeem(options)` | Redeem from a Stellar vault |
+| `submitTransaction(signedXdr)` | Submit a signed XDR transaction |
+| `getUserPosition(options)` | User position in a Stellar vault |
+| `convertToShares(options)` | Convert an asset amount to shares |
+
+### Sui Adapter (`sdk.sui`)
+
+| Method | Description |
+| --- | --- |
+| `getEmberVaults()` | List all Ember (Sui) vaults |
+| `getEmberTVL(limit?)` | Total value locked across Ember vaults |
+
+## 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`)
+
+### Special Comment Tags
+
+Search the codebase for these to find important areas:
+
+- `@todo`: Planned improvements or missing features
+- `@hardcoded`: Hardcoded values that may need configuration
+- `@solana`: Solana-specific logic or notes
+
+### Error Handling
+
+Every public method throws typed errors that subclass `AugustSDKError`:
+
+```typescript
+import { AugustValidationError, AugustTimeoutError, AugustSDKError } from '@augustdigital/sdk';
+
+try {
+  await sdk.evm.vaultDeposit({ target: '0x...', wallet: owner, amount: '1' });
+} catch (err) {
+  if (err instanceof AugustValidationError) showFormError(err.message);
+  else if (err instanceof AugustTimeoutError) scheduleRetry(err.timeoutMs);
+  else if (err instanceof AugustSDKError) reportError(err.code, err.cause);
+  else throw err;
+}
+```
+
+- Automatic retry with exponential backoff for network errors
+- 90-second request timeout (configurable via `REQUEST_TIMEOUT_MS`)
+- Correlation IDs in errors for debugging
+
+### Environment Configuration
+
+```typescript
+// Development mode — enables console logging
+const sdk = new AugustSDK({ appName: 'my-app', providers: { /* ... */ }, monitoring: { env: 'DEV' } });
+
+// Production mode — default, no console logs
+const sdk = new AugustSDK({ appName: 'my-app', providers: { /* ... */ } });
+```
+
+## Development
+
+### Running Tests
+
+```bash
+pnpm test
+```
+
+### Building
+
+```bash
+pnpm build
+```
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/fractal-protocol/js-sdk/issues)
+- **Documentation**: [docs.augustdigital.io](https://docs.augustdigital.io/developers/javascript-sdk)
+- **Example App**: [starter.upshift.finance](https://starter.upshift.finance/)

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