@paxoslabs/amplify-sdk 0.4.0-alpha.1 → 0.4.0

package/CHANGELOG.md

@@ -7,6 +7,97 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 <!-- auto-changelog-above -->
 
+
+## [0.4.0](///compare/v0.2.4...v0.4.0) (2026-02-18)
+
+### ⚠ BREAKING CHANGES
+
+* **core:** Minimum Node.js version increased from 20 to 22.
+
+### Features
+
+* **client:** migrate vault data fetching from REST v1 to GraphQL b71bbd6
+* **config:** add PRIME yield type support 7b7e60d
+* **core:** bump minimum Node.js requirement from 20 to 22 d96f256
+* **deposit:** improve TypeScript inference and add eth_signTypedData_v4 helper 7feb7b6
+* **display:** add display module with UI helper functions 868d722
+* **init:** make SDK initialization fully non-blocking 3cfb510
+* **wallets:** add smart contract wallet detection for deposit and withdrawal flows 1547072
+* **withdraw:** add prepareWithdrawal wrapper and forceMethod authorization overrides 1deef81
+* **withdraw:** add prepareWithdrawalAuthorization and fix approval bugs 88baaaf
+* **withdraw:** add WithdrawQueue contract integration 901bb5e
+
+### Bug Fixes
+
+* address CodeRabbit PR review findings 299cc64
+* address CodeRabbit review findings across withdraw, deposit, and display modules 8b52868
+* align stale API references with current naming (PR review) d2a2655
+* **auth:** remove redundant allowance fields from approval authorization results f6236a4
+* **ci:** restrict dry-run job permissions to read-only af546e1
+* **ci:** separate dry-run job to skip environment approval 7c88088
+* **deposit:** verify asset is supported on target chain d4a6eae
+* **display:** add multicall error handling in getMinimumMint 2fe41d5
+* **display:** use AND separator in v2 API filter query strings 46bdec5
+* **errors:** ensure instanceof checks work in transpiled code 9167032
+* reset version to 0.3.0 for release-it minor bump to 0.4.0 79d7b6d
+* **withdraw:** remove legacy AtomicQueue utils and update tests 67f6703
+
+## [0.4.0] - 2026-02-18
+
+### BREAKING CHANGES
+
+- **withdraw:** Replace AtomicQueue with WithdrawQueue contract ([7c521f4](https://github.com/Ion-Protocol/amplify-sdk/commit/7c521f4))
+  - `prepareWithdrawTransactionData()` → `prepareWithdrawOrderTxData()`
+  - `prepareApproveWithdrawToken()` → `prepareApproveWithdrawOrderTxData()`
+  - Added `prepareCancelWithdrawOrderTxData()` for order cancellation
+  - Slippage params no longer required for withdrawals
+- **withdraw:** Rename WithdrawQueue functions for API clarity ([6b287de](https://github.com/Ion-Protocol/amplify-sdk/commit/6b287de))
+- **auth:** Remove redundant allowance fields from approval authorization results ([f6236a4](https://github.com/Ion-Protocol/amplify-sdk/commit/f6236a4))
+- **client:** Migrate vault data fetching from REST v1 to GraphQL ([b71bbd6](https://github.com/Ion-Protocol/amplify-sdk/commit/b71bbd6))
+
+### Features
+
+- **withdraw:** add `prepareWithdrawal` unified wrapper and `forceMethod` authorization overrides ([1deef81](https://github.com/Ion-Protocol/amplify-sdk/commit/1deef81))
+  - `prepareWithdrawal()` provides a stable high-level API wrapping `prepareWithdrawOrderTxData()`
+  - `forceMethod` parameter on both deposit and withdrawal authorization for explicit routing control
+  - Auth logic reordered: force override → smart wallet heuristic → auto-detect
+- **withdraw:** add WithdrawQueue contract integration ([901bb5e](https://github.com/Ion-Protocol/amplify-sdk/commit/901bb5e))
+- **withdraw:** add `prepareWithdrawalAuthorization` unified wrapper and fix approval bugs ([88baaaf](https://github.com/Ion-Protocol/amplify-sdk/commit/88baaaf))
+- **display:** add display module with UI helper functions (`getVaultAPY`, `getVaultTVL`, `getMinimumMint`, `getMinimumWithdrawalOrderSize`, `getWithdrawalFee`, `getWithdrawalRequests`) ([868d722](https://github.com/Ion-Protocol/amplify-sdk/commit/868d722))
+- **init:** make SDK initialization fully non-blocking ([3cfb510](https://github.com/Ion-Protocol/amplify-sdk/commit/3cfb510))
+- **wallets:** add smart contract wallet detection for deposit and withdrawal flows ([1547072](https://github.com/Ion-Protocol/amplify-sdk/commit/1547072))
+
+### Bug Fixes
+
+- **withdraw:** remove legacy AtomicQueue utils and update tests ([67f6703](https://github.com/Ion-Protocol/amplify-sdk/commit/67f6703))
+- **display:** use AND separator in v2 API filter query strings ([46bdec5](https://github.com/Ion-Protocol/amplify-sdk/commit/46bdec5))
+- **display:** add multicall error handling in `getMinimumMint` ([2fe41d5](https://github.com/Ion-Protocol/amplify-sdk/commit/2fe41d5))
+- **auth:** remove redundant allowance fields from approval authorization results ([f6236a4](https://github.com/Ion-Protocol/amplify-sdk/commit/f6236a4))
+- address CodeRabbit review findings across withdraw, deposit, and display modules ([8b52868](https://github.com/Ion-Protocol/amplify-sdk/commit/8b52868))
+
+### Code Refactoring
+
+- **withdraw:** add ApprovalMethod enum for signature params ([21e0ae9](https://github.com/Ion-Protocol/amplify-sdk/commit/21e0ae9))
+- **client:** make `fetchVaults` and `fetchSupportedAssets` cache-aware ([a50a345](https://github.com/Ion-Protocol/amplify-sdk/commit/a50a345))
+- **client:** move API client from `api/` to `client/` folder ([a6523db](https://github.com/Ion-Protocol/amplify-sdk/commit/a6523db))
+
+### Styles
+
+- apply biome formatting to codebase ([d034237](https://github.com/Ion-Protocol/amplify-sdk/commit/d034237))
+
+### Documentation
+
+- update API reference and guides for new withdrawal API ([623fbf0](https://github.com/Ion-Protocol/amplify-sdk/commit/623fbf0))
+- align Mintlify docs with current SDK state ([df67147](https://github.com/Ion-Protocol/amplify-sdk/commit/df67147))
+- update withdrawal docs from AtomicQueue to WithdrawQueue terminology ([4ff639d](https://github.com/Ion-Protocol/amplify-sdk/commit/4ff639d))
+- fix withdrawal examples and smart wallet guide per code review ([bacca7c](https://github.com/Ion-Protocol/amplify-sdk/commit/bacca7c))
+
+### Chores
+
+- **deps:** add version overrides for brace-expansion and lodash ([4dba204](https://github.com/Ion-Protocol/amplify-sdk/commit/4dba204))
+- **test:** remove unused getMockAssets import ([b3e9bd0](https://github.com/Ion-Protocol/amplify-sdk/commit/b3e9bd0))
+
+
 ## [0.3.0-beta.0] - 2025-01-30
 
 ### BREAKING CHANGES
@@ -183,86 +274,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 * **chain-utils:** remove redundant optional chaining after null check ([22f1181](https://github.com/Ion-Protocol/amplify-sdk/commit/22f1181e9e670436a2eda1d6ef7e6921a4c61188))
 
-## [Unreleased]
-
-### BREAKING CHANGES
-
-- **Product Rename**: Earn SDK renamed to Amplify SDK
-  - Package name: `@paxoslabs/earn-sdk` → `@paxoslabs/amplify-sdk`
-  - Function: `initEarnSDK()` → `initAmplifySDK()`
-  - Type: `AmplifyVault` → `AmplifyVault`
-  - Repository: `Ion-Protocol/earn-sdk` → `Ion-Protocol/amplify-sdk`
-  - 7 source files renamed (earn-* → amplify-*)
-
-### Migration Guide
-
-**For Existing Users**:
-
-1. Update package in `package.json`:
-   ```bash
-   npm uninstall @paxoslabs/earn-sdk
-   npm install @paxoslabs/amplify-sdk
-   ```
-
-2. Update import statements:
-   ```typescript
-   // Old
-   import { initEarnSDK, type EarnVault } from "@paxoslabs/earn-sdk";
-
-   // New
-   import { initAmplifySDK, type AmplifyVault } from "@paxoslabs/amplify-sdk";
-   ```
-
-3. Update function calls:
-   ```typescript
-   // Old
-   await initEarnSDK("pxl_internal_your_api_key");
-
-   // New
-   await initAmplifySDK("pxl_internal_your_api_key");
-   ```
-
-4. Update type references:
-   ```typescript
-   // Old
-   const vault: EarnVault = ...;
-
-   // New
-   const vault: AmplifyVault = ...;
-   ```
-
-### Notes
-- API endpoints continue to use `/v1/earn-sdk/*` for backwards compatibility
-- No changes required to backend integration
-- Old package `@paxoslabs/earn-sdk` will be deprecated but remain functional
-- Endpoint migration to `/v1/amplify-sdk/*` planned for future release
-
-### Documentation
-- **Comprehensive SDK Documentation (Phase 008)**:
-  - Complete README.md overhaul with 5-minute quick start guide
-  - New documentation structure under `docs/`:
-    - `getting-started.md` - Detailed installation and first API call guide
-    - `api-reference/` - Complete API documentation for all SDK functions
-      - `vault-discovery.md` - Vault and asset discovery via Amplify API
-      - `deposits.md` - Standard deposit flows (viem + wagmi patterns)
-      - `deposits-permit.md` - Gas-optimized permit deposits (EIP-2612)
-      - `withdrawals.md` - Complete withdrawal flows with deadline protection
-      - `caching.md` - Performance optimization with vault caching
-      - `types.md` - TypeScript type definitions reference
-    - `guides/` - Tutorial-style integration guides
-      - `react-integration.md` - Three React patterns (direct, custom hooks, TanStack Query)
-      - `error-handling.md` - Error handling patterns for API and transactions
-      - `multi-chain.md` - Multi-chain deployment and chain selection
-    - `examples/` - Fully executable example projects
-      - `viem-deposit/` - Complete viem deposit example with tests
-      - `wagmi-deposit/` - Complete wagmi deposit example with React hooks
-      - `wagmi-withdraw/` - Complete wagmi withdrawal example
-  - 56 viem code examples and 33 wagmi code examples across all documentation
-  - 100% coverage of all 48 functional requirements
-  - All code examples are TypeScript with full type safety
-  - MSW (Mock Service Worker) integration for runnable examples
-  - Validation script for documentation quality assurance
-
 ## [0.0.1-alpha.1] - 2025-11-01
 
 ### Features

package/README.md

@@ -57,18 +57,18 @@ await initAmplifySDK("pxl_your_api_key");
 // Prepare deposit authorization (auto-detects permit vs approval)
 const auth = await prepareDepositAuthorization({
   yieldType: "CORE",
-  depositToken: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
+  depositAsset: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
   depositAmount: "1000.0",
-  recipientAddress: userAddress,
+  to: userAddress,
   chainId: 1,
 });
 
 // Shared deposit parameters
 const depositParams = {
   yieldType: "CORE",
-  depositToken: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+  depositAsset: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
   depositAmount: "1000.0",
-  recipientAddress: userAddress,
+  to: userAddress,
   chainId: 1,
 };
 

package/dist/{chunk-JHBZLKKP.mjs → chunk-5VVP4RVO.mjs}

@@ -462,22 +462,11 @@ async function prepareDepositTxData(params) {
   } = params;
   try {
     const normalizedChainId = toChainId(chainId);
-    let vault;
-    try {
-      vault = await findVaultByConfig({
-        assetAddress: depositAsset,
-        yieldType,
-        chainId: normalizedChainId
-      });
-    } catch (error) {
-      throw new APIError(
-        `Failed to resolve vault for token ${depositAsset} with yield type ${yieldType} on chain ${normalizedChainId}: ${error instanceof Error ? error.message : "Unknown error"}`,
-        {
-          endpoint: "prepareDepositTransactionData",
-          cause: error
-        }
-      );
-    }
+    const vault = await findVaultByConfig({
+      assetAddress: depositAsset,
+      yieldType,
+      chainId: normalizedChainId
+    });
     if (!vault) {
       throw new APIError(
         `No vault found for token address ${depositAsset} with yield type '${yieldType}' on chain ${normalizedChainId}. This combination may not be supported.`,
@@ -486,11 +475,8 @@ async function prepareDepositTxData(params) {
         }
       );
     }
-    let asset = null;
     const assets = await getAssetsFromCache({ address: depositAsset });
-    if (assets.length > 0) {
-      asset = assets.find((a) => a.chains.includes(normalizedChainId)) || assets[0] || null;
-    }
+    const asset = assets.find((a) => a.chains.includes(normalizedChainId)) || assets.find((a) => a.address.toLowerCase() === depositAsset.toLowerCase());
     if (!asset) {
       throw new APIError(
         `Asset metadata not found for token ${depositAsset} on chain ${normalizedChainId}`,
@@ -948,6 +934,15 @@ async function prepareDepositWithPermitTxData(params) {
     );
   }
 }
+
+// src/utils/wallet.ts
+async function isSmartContractWallet(address, chainId) {
+  const client = await getClient(chainId);
+  const code = await client.getCode({ address });
+  return !!code && code !== "0x";
+}
+
+// src/vaults/deposit/index.ts
 var DepositAuthMethod = {
   PERMIT: "permit",
   APPROVAL: "approval",
@@ -985,13 +980,25 @@ async function prepareDepositAuthorization(params) {
         { endpoint: "prepareDepositAuthorization" }
       );
     }
-    const tokenInfo = await isDepositSpendApproved({
-      yieldType,
-      chainId: normalizedChainId,
-      depositAssetAddress: depositAsset,
-      recipientAddress: to
-    });
+    if (forceMethod === "approval") {
+      const txData2 = await prepareApproveDepositTokenTxData({
+        yieldType,
+        depositAsset,
+        approvalAmount: depositAmount,
+        chainId: normalizedChainId
+      });
+      return {
+        method: DepositAuthMethod.APPROVAL,
+        txData: txData2
+      };
+    }
     if (forceMethod === "permit") {
+      const tokenInfo2 = await isDepositSpendApproved({
+        yieldType,
+        chainId: normalizedChainId,
+        depositAssetAddress: depositAsset,
+        recipientAddress: to
+      });
       const permitData = await prepareDepositPermitSignature({
         yieldType,
         depositAsset,
@@ -1000,17 +1007,21 @@ async function prepareDepositAuthorization(params) {
         chainId: normalizedChainId,
         deadline,
         // Pass pre-fetched data to avoid redundant RPC calls
-        nonce: tokenInfo.nonce ?? void 0,
-        decimals: tokenInfo.decimals,
-        tokenName: tokenInfo.tokenName,
-        tokenVersion: tokenInfo.tokenVersion
+        nonce: tokenInfo2.nonce ?? void 0,
+        decimals: tokenInfo2.decimals,
+        tokenName: tokenInfo2.tokenName,
+        tokenVersion: tokenInfo2.tokenVersion
       });
       return {
         method: DepositAuthMethod.PERMIT,
         permitData
       };
     }
-    if (forceMethod === "approval") {
+    const smartWallet = await isSmartContractWallet(
+      to,
+      normalizedChainId
+    );
+    if (smartWallet) {
       const txData2 = await prepareApproveDepositTokenTxData({
         yieldType,
         depositAsset,
@@ -1019,11 +1030,15 @@ async function prepareDepositAuthorization(params) {
       });
       return {
         method: DepositAuthMethod.APPROVAL,
-        txData: txData2,
-        allowance: tokenInfo.allowance,
-        allowanceAsBigInt: tokenInfo.allowanceAsBigInt
+        txData: txData2
       };
     }
+    const tokenInfo = await isDepositSpendApproved({
+      yieldType,
+      chainId: normalizedChainId,
+      depositAssetAddress: depositAsset,
+      recipientAddress: to
+    });
     if (tokenInfo.supportsPermit) {
       const permitData = await prepareDepositPermitSignature({
         yieldType,
@@ -1060,9 +1075,7 @@ async function prepareDepositAuthorization(params) {
     });
     return {
       method: DepositAuthMethod.APPROVAL,
-      txData,
-      allowance: tokenInfo.allowance,
-      allowanceAsBigInt: tokenInfo.allowanceAsBigInt
+      txData
     };
   } catch (error) {
     if (error instanceof APIError) {
@@ -1164,19 +1177,19 @@ async function prepareApproveWithdrawOrderTxData({
     if (!config || config.chainId !== normalizedChainId) {
       throw new APIError(
         `Vault chain mismatch: vault is on chain ${config?.chainId}, requested chain ${normalizedChainId}`,
-        { endpoint: "prepareApproveWithdrawToken" }
+        { endpoint: "prepareApproveWithdrawOrderTxData" }
       );
     }
     if (!config.vault.boringVaultAddress) {
       throw new APIError(
         `BoringVault contract address not configured for vault ${config.id}`,
-        { endpoint: "prepareApproveWithdrawToken" }
+        { endpoint: "prepareApproveWithdrawOrderTxData" }
       );
     }
     if (!config.vault.withdrawQueueAddress) {
       throw new APIError(
         `WithdrawQueue contract address not configured for vault ${config.id}`,
-        { endpoint: "prepareApproveWithdrawToken" }
+        { endpoint: "prepareApproveWithdrawOrderTxData" }
       );
     }
     const boringVaultAddress = config.vault.boringVaultAddress;
@@ -1199,7 +1212,7 @@ async function prepareApproveWithdrawOrderTxData({
     throw new APIError(
       `Failed to prepare approval transaction: ${error instanceof Error ? error.message : String(error)}`,
       {
-        endpoint: "prepareApproveWithdrawToken",
+        endpoint: "prepareApproveWithdrawOrderTxData",
         cause: error
       }
     );
@@ -1275,8 +1288,7 @@ var prepareWithdrawOrderTxData = async ({
   wantAsset,
   userAddress,
   chainId,
-  amountOffer,
-  skipApprovalCheck
+  amountOffer
 }) => {
   try {
     const normalizedChainId = toChainId(chainId);
@@ -1309,20 +1321,6 @@ var prepareWithdrawOrderTxData = async ({
         { endpoint: "prepareWithdrawOrderTxData" }
       );
     }
-    if (!skipApprovalCheck) {
-      const approvalInfo = await isWithdrawalSpendApproved({
-        yieldType,
-        chainId: normalizedChainId,
-        wantAssetAddress: wantAsset,
-        recipientAddress: userAddress
-      });
-      if (!approvalInfo.isApproved) {
-        throw new APIError(
-          `Vault shares not approved for withdrawal`,
-          { endpoint: "prepareWithdrawOrderTxData" }
-        );
-      }
-    }
     const sharesDecimals = await getErc20Decimals({
       tokenAddress: config.vault.boringVaultAddress,
       chainId: normalizedChainId
@@ -1367,8 +1365,38 @@ function isWithdrawApprovalAuth(result) {
 function isWithdrawAlreadyApprovedAuth(result) {
   return result.method === WithdrawAuthMethod.ALREADY_APPROVED;
 }
-async function prepareWithdrawalAuthorization(params) {
+async function prepareWithdrawal(params) {
   const { yieldType, wantAsset, withdrawAmount, userAddress, chainId } = params;
+  try {
+    return await prepareWithdrawOrderTxData({
+      yieldType,
+      wantAsset,
+      userAddress,
+      chainId,
+      amountOffer: withdrawAmount
+    });
+  } catch (error) {
+    if (error instanceof APIError) {
+      throw error;
+    }
+    throw new APIError(
+      `Failed to prepare withdrawal: ${error instanceof Error ? error.message : String(error)}`,
+      {
+        endpoint: "prepareWithdrawal",
+        cause: error
+      }
+    );
+  }
+}
+async function prepareWithdrawalAuthorization(params) {
+  const {
+    yieldType,
+    wantAsset,
+    withdrawAmount,
+    userAddress,
+    chainId,
+    forceMethod
+  } = params;
   try {
     const normalizedChainId = toChainId(chainId);
     const vault = await findVaultByConfig({
@@ -1382,6 +1410,36 @@ async function prepareWithdrawalAuthorization(params) {
         { endpoint: "prepareWithdrawalAuthorization" }
       );
     }
+    if (forceMethod === "approval") {
+      const txData2 = await prepareApproveWithdrawOrderTxData({
+        yieldType,
+        wantAssetAddress: wantAsset,
+        withdrawAmount,
+        chainId: normalizedChainId
+      });
+      return {
+        method: WithdrawAuthMethod.APPROVAL,
+        txData: txData2
+      };
+    }
+    if (forceMethod !== "allowance_check") {
+      const smartWallet = await isSmartContractWallet(
+        userAddress,
+        normalizedChainId
+      );
+      if (smartWallet) {
+        const txData2 = await prepareApproveWithdrawOrderTxData({
+          yieldType,
+          wantAssetAddress: wantAsset,
+          withdrawAmount,
+          chainId: normalizedChainId
+        });
+        return {
+          method: WithdrawAuthMethod.APPROVAL,
+          txData: txData2
+        };
+      }
+    }
     const approvalInfo = await isWithdrawalSpendApproved({
       yieldType,
       chainId: normalizedChainId,
@@ -1415,9 +1473,7 @@ async function prepareWithdrawalAuthorization(params) {
     });
     return {
       method: WithdrawAuthMethod.APPROVAL,
-      txData,
-      allowance: approvalInfo.allowance,
-      allowanceAsBigInt: approvalInfo.allowanceAsBigInt
+      txData
     };
   } catch (error) {
     if (error instanceof APIError) {
@@ -1433,6 +1489,6 @@ async function prepareWithdrawalAuthorization(params) {
   }
 }
 
-export { DepositAuthMethod, PERMIT_TYPES, WithdrawAuthMethod, isAlreadyApprovedAuth, isApprovalAuth, isDepositSpendApproved, isPermitAuth, isWithdrawAlreadyApprovedAuth, isWithdrawApprovalAuth, isWithdrawalSpendApproved, parsePermitSignature, prepareApproveDepositTokenTxData, prepareApproveWithdrawOrderTxData, prepareCancelWithdrawOrderTxData, prepareDeposit, prepareDepositAuthorization, prepareDepositPermitSignature, prepareDepositTxData, prepareDepositWithPermitTxData, prepareWithdrawOrderTxData, prepareWithdrawalAuthorization, toEthSignTypedDataV4 };
-//# sourceMappingURL=chunk-JHBZLKKP.mjs.map
-//# sourceMappingURL=chunk-JHBZLKKP.mjs.map
+export { DepositAuthMethod, PERMIT_TYPES, WithdrawAuthMethod, isAlreadyApprovedAuth, isApprovalAuth, isDepositSpendApproved, isPermitAuth, isWithdrawAlreadyApprovedAuth, isWithdrawApprovalAuth, isWithdrawalSpendApproved, parsePermitSignature, prepareApproveDepositTokenTxData, prepareApproveWithdrawOrderTxData, prepareCancelWithdrawOrderTxData, prepareDeposit, prepareDepositAuthorization, prepareDepositPermitSignature, prepareDepositTxData, prepareDepositWithPermitTxData, prepareWithdrawOrderTxData, prepareWithdrawal, prepareWithdrawalAuthorization, toEthSignTypedDataV4 };
+//# sourceMappingURL=chunk-5VVP4RVO.mjs.map
+//# sourceMappingURL=chunk-5VVP4RVO.mjs.map