@alphafi/alphafi-sdk 0.0.106 → 1.0.0

package/README.md

@@ -1,224 +1,476 @@
-# AlphaFi TypeScript SDK
+# AlphaFi SDK for JavaScript
+
+A comprehensive TypeScript/JavaScript SDK for interacting with the AlphaFi DeFi platform on Sui blockchain.
+This SDK provides seamless integration with multiple DeFi protocols and strategies including lending,
+LP farming, leveraged yield farming, and more.
+
+## Features
+
+- **Multi-Protocol Support**: Bluefin, Navi, Cetus, Bucket, AlphaLend, and AlphaFi protocols
+- **Complete DeFi Suite**: Deposits, withdrawals, swaps, portfolio management, and reward claims
+- **Advanced Strategies**: Lending, LP farming, leveraged yield farming (LYF), looping, and Alpha vaults
+- **Portfolio Management**: Real-time portfolio tracking with aggregated metrics and alpha rewards
+- **Token Swaps**: Integrated Cetus aggregator for optimal token routing
+- **Type Safety**: Full TypeScript support with comprehensive type definitions
+- **Options-Based API**: Consistent, easy-to-use interface across all methods
 
 ## Installation
 
 ```bash
-npm i @alphafi/alphafi-sdk
+npm install @alphafi/alphafi-sdk
 ```
 
+## Quick Start
+
+```typescript
+import { AlphaFiSDK } from '@alphafi/alphafi-sdk';
+import { SuiClient } from '@mysten/sui/client';
+
+// Initialize the SDK
+const suiClient = new SuiClient({ url: 'https://fullnode.mainnet.sui.io:443' });
+const sdk = new AlphaFiSDK({
+  suiClient,
+  network: 'mainnet',
+});
+
+const userAddress = 'your_sui_address_here';
+
+// Get all available pools
+const pools = await sdk.getPoolsData();
+console.log('Available pools:', pools);
+
+// Get user portfolio
+const portfolio = await sdk.getUserPortfolio(userAddress);
+console.log('Portfolio:', {
+  netWorth: portfolio.netWorth.toString(),
+  aggregatedApy: portfolio.aggregatedApy.toString(),
+  alphaRewards: portfolio.alphaRewardsToClaim.toString(),
+});
+
+// Build an unsigned deposit transaction
+const depositTx = await sdk.deposit({
+  poolId: '0x...', // Pool ID
+  address: userAddress,
+  amount: 1000000000n, // 1 SUI in base units
+  isAmountA: true, // For LP pools: which token this amount represents
+});
+// Sign & execute with your wallet / client
+// await suiClient.signAndExecuteTransactionBlock({ transactionBlock: depositTx, signer });
+
+// Build an unsigned withdraw transaction
+const withdrawTx = await sdk.withdraw({
+  poolId: '0x...',
+  address: userAddress,
+  amount: '500000000', // Amount to withdraw
+  withdrawMax: false, // Set to true to withdraw entire position
+});
+
+// Claim all rewards (builds unsigned transaction)
+const claimTx = await sdk.claim({
+  address: userAddress,
+});
+```
+
+> **How transactions work**: `deposit`, `withdraw`, `zapDeposit`, swaps, and reward helpers return
+> **unsigned** `Transaction` objects from `@mysten/sui/transactions`. You must sign and execute them
+> with your wallet or client of choice.
+>
+> **Amounts & precision**:
+>
+> - Deposits and zap inputs use `bigint` in base units (`1000000000n` = 1 SUI).
+> - Withdraw inputs and most quotes use `string` for flexibility across strategies.
+> - Responses return `Decimal` instances (from `decimal.js`) to avoid floating-point errors.
+
+## Supported Protocols
+
+### Bluefin Protocol
+
+- **Pool Types**: SUI-USDC, USDT-USDC, STSUI-SUI, and more
+- **Strategies**: Regular liquidity pools, autobalance pools, fungible pools
+- **Special Features**: Support for different tick ranges (175, zero-zero)
+
+### Navi Protocol
+
+- **Pool Types**: Single-asset pools (SUI, USDC, USDT, etc.)
+- **Strategies**: Regular lending, looping strategies
+- **Special Features**: Support for NAVI-LOOP pools with supply/borrow mechanics
+
+### Cetus Protocol
+
+- **Pool Types**: CETUS-SUI, ALPHA-SUI, and other trading pairs
+- **Strategies**: Concentrated liquidity with tick-based ranges
+- **Special Features**: Support for different pool configurations
+
+### Bucket Protocol
+
+- **Pool Types**: BUCK token pools
+- **Strategies**: Single-asset staking
+- **Special Features**: Simple deposit/withdraw mechanics
+
+### AlphaLend Protocol
+
+- **Pool Types**: SUI-STSUI looping, single-loop pools (TBTC, SUIBTC, XAUM)
+- **Strategies**: Looping strategies, single-asset looping
+- **Special Features**: Advanced lending strategies with leverage
+
 ## API Reference
 
-## `getVaults`
+### AlphaFiSDK Class
 
-Call this to get all Vaults that a particular user has deposited in.
+#### Constructor
 
 ```typescript
-import { getVaults, AlphaFiVault } from "@alphafi/alphafi-sdk";
+new AlphaFiSDK(config: AlphaFiSDKConfig)
+```
+
+#### Configuration Interface
 
-const vaults: AlphaFiVault[] | undefined = await getVaults(address);
+```typescript
+interface AlphaFiSDKConfig {
+  suiClient: SuiClient; // Sui blockchain client
+  network: 'mainnet' | 'testnet' | 'devnet' | 'localnet';
+}
 ```
 
-## `getSingleAssetVaults`
+#### Core Methods
 
-Call this to get all Single Asset Vaults that a particular user has deposited in.
+##### getPoolsData(strategiesType?: StrategyType[]): Promise\<Map\<string, PoolData>>
 
-```typescript
-import { getSingleAssetVaults, AlphaFiVault } from "@alphafi/alphafi-sdk";
+Get comprehensive data for all available DeFi pools.
 
-const vaults: AlphaFiVault[] | undefined = await getSingleAssetVaults(address);
+```typescript
+const pools = await sdk.getPoolsData(['Lending', 'Lp']); // Filter by strategy types
+const allPools = await sdk.getPoolsData(); // Get all pools
 ```
 
-## `getDoubleAssetVaults`
+##### getSinglePoolData(poolId: string): Promise\<PoolData>
 
-Call this to get all Double Asset Vaults that a particular user has deposited in.
+Get data for a single pool.
 
 ```typescript
-import { getDoubleAssetVaults, AlphaFiVault } from "@alphafi/alphafi-sdk";
-
-const vaults: AlphaFiVault[] | undefined = await getDoubleAssetVaults(address);
+const poolData = await sdk.getSinglePoolData('0x...'); // Get data for specific pool
 ```
 
-## `getAllVaults`
+##### getUserSinglePoolBalance(address: string, poolId: string): Promise\<PoolBalance>
 
-Call this to get all Vaults on AlphaFi Protocol.
+Get balance for a single pool.
 
 ```typescript
-import { getAllVaults } from "@alphafi/alphafi-sdk";
-
-const vaults: string[] = await getAllVaults();
+const balance = await sdk.getUserSinglePoolBalance(userAddress, '0x...');
 ```
 
-## `getAllSingleAssetVaults`
+##### getUserPortfolio(address: string, strategiesType?: StrategyType[]): Promise\<UserPortfolioData>
 
-Call this to get all Single Asset Vaults on AlphaFi Protocol.
+Get complete portfolio summary for a user address.
 
 ```typescript
-import { getAllSingleAssetVaults } from "@alphafi/alphafi-sdk";
-
-const vaults: string[] = await getAllSingleAssetVaults();
+const portfolio = await sdk.getUserPortfolio(userAddress);
+console.log({
+  netWorth: portfolio.netWorth.toString(),
+  aggregatedApy: portfolio.aggregatedApy.toString(),
+  alphaRewards: portfolio.alphaRewardsToClaim.toString(),
+  poolBalances: portfolio.poolBalances,
+});
 ```
 
-## `getAllDoubleAssetVaults`
+#### Transaction Methods
 
-Call this to get all Double Asset Vaults on AlphaFi Protocol.
+##### deposit(options: DepositOptions): Promise\<Transaction>
 
-```typescript
-import { getAllDoubleAssetVaults } from "@alphafi/alphafi-sdk";
+Build an **unsigned** transaction to deposit assets into a DeFi pool.
 
-const vaults: string[] = await getAllDoubleAssetVaults();
+```typescript
+interface DepositOptions {
+  poolId: string; // Unique pool identifier
+  address: string; // User's wallet address
+  amount: bigint; // Amount in base units
+  isAmountA?: boolean; // For LP pools: which token this amount represents
+}
 ```
 
-## `getAlphaVaultBalance`
+##### withdraw(options: WithdrawOptions): Promise\<Transaction>
 
-Call this to get user balance in Alpha Vault.
+Build an **unsigned** transaction to withdraw assets from a DeFi pool.
 
 ```typescript
-import { getAlphaVaultBalance, AlphaVaultBalance } from "@alphafi/alphafi-sdk";
-
-const balance: AlphaVaultBalance | undefined =
-  await getAlphaVaultBalance(address);
+interface WithdrawOptions {
+  poolId: string; // Unique pool identifier
+  address: string; // User's wallet address
+  amount: string; // Amount to withdraw (ignored if withdrawMax is true)
+  isAmountA?: boolean; // For LP pools: specify withdrawal in terms of token A
+  withdrawMax: boolean; // If true, withdraw entire position
+}
 ```
 
-## `getSingleAssetVaultBalance`
+##### estimateLpAmounts(options: EstimateLpAmountsOptions): Promise\<[string, string]>
 
-Call this to get user balance in Single Asset Vaults.
+Calculate required token amounts for balanced LP deposits.
 
 ```typescript
-import {
-  getSingleAssetVaultBalance,
-  SingleAssetVaultBalance,
-} from "@alphafi/alphafi-sdk";
-
-const balance: SingleAssetVaultBalance | undefined =
-  await getSingleAssetVaultBalance(address, poolName);
+interface EstimateLpAmountsOptions {
+  poolId: string; // LP pool identifier
+  amount: string; // Input token amount
+  isAmountA: boolean; // True if amount refers to token A
+}
 ```
 
-## `getDoubleAssetVaultBalance`
+##### claim(options: ClaimOptions): Promise\<Transaction>
 
-Call this to get user balance in Double Asset Vaults.
+Build an **unsigned** transaction to claim accumulated rewards (all pools or a specific pool).
 
 ```typescript
-import {
-  getDoubleAssetVaultBalance,
-  DoubleAssetVaultBalance,
-} from "@alphafi/alphafi-sdk";
-
-const balance: DoubleAssetVaultBalance | undefined =
-  await getDoubleAssetVaultBalance(address, poolName);
+interface ClaimOptions {
+  address: string; // User's wallet address
+  poolId?: string; // Optional: specific pool ID
+}
 ```
 
-## `getAllVaultBalances`
+#### dev-testing
 
-Call this to get user balance for all vaults.
+replace the code in fetchPoolLabelsByIds with the below code block to test transactions with testing pools.
 
 ```typescript
-import {
-  PoolName,
-  AlphaFiVaultBalance,
-  getAllVaultBalances,
-} from "@alphafi/alphafi-sdk";
-
-const balance: Map<PoolName, AlphaFiVaultBalance> =
-  await getAllVaultBalances(address);
+const { TEST_POOLS } = await import('../utils/testing-pools.js');
+for (const pool of TEST_POOLS) {
+  poolLabels.set(pool.poolId, pool);
+}
 ```
 
-## `claimRewardTxb`
+##### vote(voteIndex: number, proposalId: string): Promise\<Transaction | undefined>
 
-Call this to withdraw from Vaults on AlphaFi Protocol.
+Build an **unsigned** transaction to vote on a governance proposal.
 
 ```typescript
-import { claimRewardTxb } from "@alphafi/alphafi-sdk";
-import { Transaction } from "@mysten/sui/transactions";
-
-const vaults: Transaction = await claimRewardTxb(address);
+// voteIndex: The index of the vote to cast (e.g. 0 = Against, 1 = For, etc.)
+// proposalId: The object ID of the proposal to vote on
+const voteTx = await sdk.vote(1, '0x...'); // Vote "For" on proposal 0x...
+// Sign & execute with your wallet / client
 ```
 
-## `depositSingleAssetTxb`
+Returns `undefined` if `voteIndex` is undefined (and logs an error).
+Otherwise returns a `Transaction` ready for signing and execution.
 
-Call this to deposit in Single Asset Vaults on AlphaFi Protocol.
+#### Alpha Token Methods
 
-```typescript
-import { depositSingleAssetTxb } from "@alphafi/alphafi-sdk";
-import { Transaction } from "@mysten/sui/transactions";
+##### initiateWithdrawAlpha(options: WithdrawOptions): Promise\<Transaction>
 
-const vaults: Transaction = await depositSingleAssetTxb(
-  poolName,
-  address,
-  amount,
-);
-```
+Initiate ALPHA token withdrawal (creates withdrawal ticket).
 
-## `depositDoubleAssetTxb`
+##### claimWithdrawAlpha(options: ClaimWithdrawAlphaOptions): Promise\<Transaction>
 
-Call this to deposit in Double Asset Vaults on AlphaFi Protocol.
+Complete ALPHA token withdrawal using previously created ticket.
 
 ```typescript
-import { depositDoubleAssetTxb } from "@alphafi/alphafi-sdk";
-import { Transaction } from "@mysten/sui/transactions";
+interface ClaimWithdrawAlphaOptions {
+  ticketId: string; // Withdrawal ticket ID
+  address: string; // User's wallet address
+}
+```
 
-const vaults: Transaction = await depositDoubleAssetTxb(
-  poolName,
-  address,
-  amount,
-  isAmountA,
-);
+##### claimAirdrop(options: ClaimAirdropOptions): Promise\<Transaction>
+
+Claim available airdrop tokens.
+
+```typescript
+interface ClaimAirdropOptions {
+  address: string; // User's wallet address
+  transferToWallet: boolean; // Whether to transfer directly to wallet
+}
 ```
 
-## `withdrawTxb`
+#### Zap Deposit Methods
+
+##### zapDepositQuote(options: ZapDepositQuoteOptions): Promise\<[string, string] | undefined>
 
-Call this to withdraw from Vaults on AlphaFi Protocol.
-xTokensAmount can be calculated using coinAmountToXTokensSingleAsset or coinAmountToXTokensDoubleAsset function depending on whether the pool is singleAsset or doubleAsset.
+Get quote for zap deposit operation (single token to LP).
 
 ```typescript
-import { withdrawTxb } from "@alphafi/alphafi-sdk";
-import { Transaction } from "@mysten/sui/transactions";
+interface ZapDepositQuoteOptions {
+  poolId: string; // LP pool identifier
+  inputCoinAmount: bigint; // Input token amount in base units
+  isInputA: boolean; // True if input token is token A
+  slippage: number; // Max slippage (e.g., 0.005 = 0.5%)
+}
+```
+
+##### zapDeposit(options: ZapDepositOptions): Promise\<Transaction | undefined>
 
-const vaults: Transaction = await withdrawTxb(xTokensAmount, poolName, address);
+Execute zap deposit: convert single token to balanced LP position.
+
+```typescript
+interface ZapDepositOptions {
+  poolId: string; // LP pool identifier
+  inputCoinAmount: bigint; // Input token amount in base units
+  isInputA: boolean; // True if input token is token A
+  address: string; // User's wallet address
+  slippage: number; // Max slippage (e.g., 0.005 = 0.5%)
+}
 ```
 
-## `withdrawAlphaTxb`
+#### Token Swap Methods
 
-Call this to withdraw from Alpha Vault on AlphaFi Protocol.
-xTokensAmount can be calculated using coinAmountToXTokensSingleAsset function.
-If you want to withdraw from locked alpha tokens then pass withdrawFromLocked as true, otherwise false.
+##### getCetusSwapQuote(options: CetusSwapQuoteOptions): Promise\<RouterDataV3 | undefined>
+
+Get quote for token swap via Cetus aggregator.
 
 ```typescript
-import { withdrawAlphaTxb } from "@alphafi/alphafi-sdk";
-import { Transaction } from "@mysten/sui/transactions";
+interface CetusSwapQuoteOptions {
+  from: string; // Source token type/address
+  target: string; // Destination token type/address
+  amount: string; // Amount to swap in source token units
+  byAmountIn: boolean; // True to fix input amount, false to fix output
+}
+```
+
+##### cetusSwapTxb(options: CetusSwapOptions): Promise\<Transaction>
+
+Execute token swap using Cetus aggregator.
 
-const vaults: Transaction = await withdrawAlphaTxb(
-  xTokensAmount,
-  withdrawFromLocked,
-  address,
-);
+```typescript
+interface CetusSwapOptions {
+  router: RouterDataV3; // Router data from getCetusSwapQuote
+  slippage: number; // Max slippage (e.g., 0.01 = 1%)
+}
 ```
 
-## `coinAmountToXTokensSingleAsset`
+## Supported Strategies
+
+The SDK supports multiple DeFi strategies across various protocols:
+
+### Strategy Types
+
+- **Lending**: Single-asset yield farming on protocols like Navi and Bucket
+- **Lp**: Liquidity provision on AMMs like Cetus and Bluefin
+- **Lyf** (Leveraged Yield Farming): Amplified returns with borrowed capital
+- **AutobalanceLp**: Self-rebalancing liquidity positions
+- **AlphaVault**: Optimized staking for ALPHA tokens
+- **Looping**: Leveraged single-asset positions with recursive borrowing
+- **SingleAssetLooping**: Single-token leverage strategies
+- **FungibleLp**: Fungible liquidity tokens for easy transfer
+- **SlushLending**: Slush protocol lending integration
+
+### Pool Discovery
+
+Use the SDK methods to discover available pools:
+
+```typescript
+// Get all pools
+const allPools = await sdk.getPoolsData();
+
+// Filter by strategy type
+const lendingPools = await sdk.getPoolsData(['Lending']);
+const lpPools = await sdk.getPoolsData(['Lp', 'AutobalanceLp']);
+
+// Explore pool details
+for (const [poolId, poolData] of allPools) {
+  console.log(`${poolData.poolName} (${poolId})`, {
+    apy: poolData.apr.apy.toString(),
+    tvl: poolData.tvl, // contains alphafi and parent TVL; see types section
+  });
+}
+```
 
-Call this to convert coin amount to xTokenAmount for any Single Asset pool on AlphaFi Protocol.
+### SDK Initialization
 
 ```typescript
-import { coinAmountToXTokensSingleAsset } from "@alphafi/alphafi-sdk";
-import { Transaction } from "@mysten/sui/transactions";
+import { AlphaFiSDK } from '@alphafi/alphafi-sdk';
+import { SuiClient } from '@mysten/sui/client';
+
+const suiClient = new SuiClient({
+  url: process.env.SUI_RPC_URL || 'https://fullnode.mainnet.sui.io:443',
+});
 
-const vaults: Transaction = await coinAmountToXTokensSingleAsset(
-  amount,
-  poolName,
-);
+const sdk = new AlphaFiSDK({
+  suiClient,
+  network: (process.env.NETWORK as any) || 'mainnet',
+});
+
+const userAddress = process.env.USER_ADDRESS;
 ```
 
-## `coinAmountToXTokensDoubleAsset`
+## Data Types
 
-Call this to convert coin amount to xTokenAmount for any Double Asset pool on AlphaFi Protocol.
-isAmountA parameter is true if you have passed amount of 1st coin, otherwise its false.
+### Key Response Types
 
 ```typescript
-import { coinAmountToXTokensDoubleAsset } from "@alphafi/alphafi-sdk";
-import { Transaction } from "@mysten/sui/transactions";
-
-const vaults: Transaction = await coinAmountToXTokensDoubleAsset(
-  amount,
-  poolName,
-  isAmountA,
-);
+type AprData = {
+  baseApr: Decimal;
+  alphaMiningApr: Decimal;
+  apy: Decimal;
+  lastAutocompounded: Date;
+};
+
+type SingleTvl = { tokenAmount: Decimal; usdValue: Decimal };
+type DoubleTvl = { tokenAmountA: Decimal; tokenAmountB: Decimal; usdValue: Decimal };
+type TvlData =
+  | { alphafi: SingleTvl; parent: SingleTvl }
+  | { alphafi: DoubleTvl; parent: DoubleTvl };
+
+type PoolData =
+  | {
+      poolId: string;
+      poolName: string;
+      apr: AprData;
+      tvl: TvlData;
+      lpBreakdown: { token1Amount: Decimal; token2Amount: Decimal; totalLiquidity: Decimal };
+      parentLpBreakdown: { token1Amount: Decimal; token2Amount: Decimal; totalLiquidity: Decimal };
+      currentLPPoolPrice: Decimal;
+      positionRange: { lowerPrice: Decimal; upperPrice: Decimal };
+    }
+  | {
+      poolId: string;
+      poolName: string;
+      apr: AprData;
+      tvl: TvlData;
+    };
+
+type PoolBalance =
+  | { tokenAAmount: Decimal; tokenBAmount: Decimal; usdValue: Decimal }
+  | { tokenAmount: Decimal; usdValue: Decimal }
+  | {
+      stakedAlphaAmount: Decimal;
+      stakedAlphaUsdValue: Decimal;
+      pendingDeposits: Decimal;
+      withdrawals: {
+        ticketId: string;
+        alphaAmount: string;
+        status: number; // 0 pending, 1 accepted, 2 claimable
+        withdrawalEtaTimestamp: number;
+      }[];
+      claimableAirdrop: Decimal;
+      totalAirdropClaimed: Decimal;
+    };
+
+type UserPortfolioData = {
+  netWorth: Decimal;
+  aggregatedApy: Decimal;
+  alphaRewardsToClaim: Decimal;
+  poolBalances: Map<string, PoolBalance>;
+};
+
+type StrategyType =
+  | 'Lending'
+  | 'Lp'
+  | 'Lyf'
+  | 'AutobalanceLp'
+  | 'AlphaVault'
+  | 'Looping'
+  | 'SingleAssetLooping'
+  | 'FungibleLp'
+  | 'SlushLending';
 ```
+
+### Security Guidelines
+
+- **Never commit your `.env` file** to version control
+- **Store private keys securely** and never expose them in client-side code
+- **Use environment variables** for sensitive configuration
+- **Always test on testnet first** before mainnet deployment
+- **Verify pool IDs and amounts** before executing transactions
+- **Check transaction gas estimates** before submission
+- **Implement proper error handling** for all SDK calls
+- **Use appropriate slippage settings** for swaps (typically 0.5-2%)
+
+## Support
+
+For issues, questions, or contributions, please refer to the project repository or contact the AlphaFi team.