@apex_labs/sdk 0.1.0 → 0.1.2

package/README.md

@@ -1,6 +1,6 @@
 # Apex SDK
 
-Frontend SDK for Apex CL and Classic pools. It vendors a pinned `@pancakeswap/v3-sdk@3.10.0` snapshot as an Apex-owned fork, then adds Apex fee tiers, Apex CREATE2 address helpers, Classic AMM quoting, mixed CL/Classic path encoding, and exact ABI exports for the Apex contracts.
+SDK for Apex CL and Classic pools. It vendors a pinned `@pancakeswap/v3-sdk@3.10.0` snapshot as an Apex-owned fork, then adds Apex fee tiers, Apex CREATE2 address helpers, Classic AMM quoting, mixed CL/Classic path encoding, and exact ABI exports for the Apex contracts.
 
 ## Setup
 
@@ -43,37 +43,37 @@ export const apex: ApexDeploymentConfig = {
 };
 ```
 
-## Functions frontend should care about
+## Core exports
 
 ```ts
 import {
-  ApexFeeAmount,
+  CLFeeAmount,
   APEX_CL_POOL_INIT_CODE_HASH,
   APEX_CL_TICK_SPACINGS,
   APEX_CLASSIC_PAIR_INIT_CODE_HASH,
-  ApexClassicFarm,
-  ApexCLFarm,
-  ApexSmartRouter,
-  ApexVaultPosition,
-  getApexTickSpacing,
-  createApexPool,
+  ClassicChef,
+  CLMasterChef,
+  SmartRouter,
+  ApexVault,
+  getCLTickSpacing,
+  createCLPool,
   computeCLPoolAddress,
   computeClassicPoolAddress,
-  quoteApexClassicExactInput,
-  encodeApexMixedRouteToPath,
-  encodeApexMixedRouteToPancakeQuoteParams,
-  decodeApexMixedRoutePath,
-  parseApexProtocolFeePacked,
-  apexCLPoolAbi,
-  apexCLFactoryAbi,
-  apexCLMasterChefAbi,
-  apexNonfungiblePositionManagerAbi,
-  apexSwapRouterAbi,
-  apexSmartRouterAbi,
-  apexMixedQuoterAbi,
-  apexQuoterV2Abi,
-  apexClassicFactoryAbi,
-  apexClassicPairAbi,
+  quoteClassicExactInput,
+  encodeMixedRouteToPath,
+  encodeMixedRouteToPancakeQuoteParams,
+  decodeMixedRoutePath,
+  parseProtocolFeePacked,
+  clPoolAbi,
+  clFactoryAbi,
+  clMasterChefAbi,
+  nonfungiblePositionManagerAbi,
+  swapRouterAbi,
+  smartRouterAbi,
+  mixedQuoterAbi,
+  quoterV2Abi,
+  classicFactoryAbi,
+  classicPoolAbi,
   Pool,
   Route,
   Trade,
@@ -93,17 +93,17 @@ const pool = computeCLPoolAddress({
   config: apex,
   tokenA,
   tokenB,
-  fee: ApexFeeAmount.FEE_0_30,
+  fee: CLFeeAmount.FEE_0_30,
 });
 ```
 
 ### CL pool object
 
 ```ts
-const pool = createApexPool({
+const pool = createCLPool({
   tokenA,
   tokenB,
-  fee: ApexFeeAmount.FEE_0_30,
+  fee: CLFeeAmount.FEE_0_30,
   sqrtRatioX96,
   liquidity,
   tickCurrent,
@@ -111,7 +111,7 @@ const pool = createApexPool({
 });
 ```
 
-`createApexPool` returns the forked Pancake `Pool`, with Apex fee tiers installed. Position, trade, route, quoter, swap-router, and NFT-position-manager logic should use the classes re-exported by `@apex_labs/sdk`.
+`createCLPool` returns the forked Pancake `Pool`, with Apex fee tiers installed. Position, trade, route, quoter, swap-router, and NFT-position-manager logic should use the classes re-exported by `@apex_labs/sdk`.
 
 ### Periphery ABIs
 
@@ -119,19 +119,19 @@ Use the exact ABIs exported from compiled Apex contracts:
 
 ```ts
 import {
-  apexNonfungiblePositionManagerAbi,
-  apexSwapRouterAbi,
-  apexQuoterAbi,
-  apexQuoterV2Abi,
-  apexSmartRouterAbi,
-  apexMixedQuoterAbi,
-  apexTickLensAbi,
-  apexInterfaceMulticallAbi,
-  apexCLFactoryAbi,
-  apexCLMasterChefAbi,
-  apexCLPoolAbi,
-  apexClassicFactoryAbi,
-  apexClassicPairAbi,
+  nonfungiblePositionManagerAbi,
+  swapRouterAbi,
+  quoterAbi,
+  quoterV2Abi,
+  smartRouterAbi,
+  mixedQuoterAbi,
+  tickLensAbi,
+  interfaceMulticallAbi,
+  clFactoryAbi,
+  clMasterChefAbi,
+  clPoolAbi,
+  classicFactoryAbi,
+  classicPoolAbi,
 } from "@apex_labs/sdk";
 ```
 
@@ -149,7 +149,7 @@ const stablePair = computeClassicPoolAddress({
 ### Classic quote
 
 ```ts
-const amountOut = quoteApexClassicExactInput({
+const amountOut = quoteClassicExactInput({
   amountIn,
   tokenIn: tokenA.address,
   token0,
@@ -165,19 +165,19 @@ const amountOut = quoteApexClassicExactInput({
 
 ### Classic farm UX
 
-Use `ApexClassicFarm` for Classic LP staking. Pools are pid-based; read `ClassicChef.pidOf(pair)` from the exported ABI or an indexed farm list, then encode normal stake/claim/exit calls:
+Use `ClassicChef` for Classic LP staking. Pools are pid-based; read `ClassicChef.pidOf(pair)` from the exported ABI or an indexed farm list, then encode normal stake/claim/exit calls:
 
 ```ts
-const stakeClassic = ApexClassicFarm.depositCallParameters({
+const stakeClassic = ClassicChef.depositCallParameters({
   pid,
   amount,
 });
 
-const claimClassic = ApexClassicFarm.harvestCallParameters({
+const claimClassic = ClassicChef.harvestCallParameters({
   pid,
 });
 
-const exitClassic = ApexClassicFarm.withdrawCallParameters({
+const exitClassic = ClassicChef.withdrawCallParameters({
   pid,
   amount,
 });
@@ -186,23 +186,23 @@ const exitClassic = ApexClassicFarm.withdrawCallParameters({
 ### Mixed CL/Classic path
 
 ```ts
-const path = encodeApexMixedRouteToPath([
+const path = encodeMixedRouteToPath([
   {
     kind: "CL",
     tokenIn: tokenA.address,
     tokenOut: tokenB.address,
-    fee: ApexFeeAmount.FEE_0_30,
+    fee: CLFeeAmount.FEE_0_30,
   },
   { kind: "CLASSIC_STABLE", tokenIn: tokenB.address, tokenOut: tokenC.address },
 ]);
 ```
 
 Quote that path through `MixedQuoter.quoteExactInput(path, amountIn)`, then execute it with
-`ApexSmartRouter`. The high-level helpers follow Pancake SmartRouter’s safety pattern:
+`SmartRouter`. The high-level helpers follow Pancake SmartRouter’s safety pattern:
 they encode the swap, then wrap it in `SmartRouter.multicall(deadlineOrPreviousBlockhash, data)`.
 
 ```ts
-const swap = ApexSmartRouter.mixedExactInputCallParameters(
+const swap = SmartRouter.mixedExactInputCallParameters(
   { hops, recipient: account, amountIn, amountOutMinimum },
   { deadlineOrPreviousBlockhash: deadline },
 );
@@ -211,10 +211,10 @@ const swap = ApexSmartRouter.mixedExactInputCallParameters(
 If you fork Pancake SmartRouter’s mixed quote provider, use Pancake-style quote params:
 
 ```ts
-const { path, flags } = encodeApexMixedRouteToPancakeQuoteParams(hops);
+const { path, flags } = encodeMixedRouteToPancakeQuoteParams(hops);
 const quote = await publicClient.readContract({
   address: apex.mixedQuoter,
-  abi: apexMixedQuoterAbi,
+  abi: mixedQuoterAbi,
   functionName: "quoteExactInput",
   args: [path, flags, amountIn],
 });
@@ -224,38 +224,40 @@ For routes that Pancake SmartRouter partitions by protocol:
 
 ```ts
 // Classic volatile section
-ApexSmartRouter.classicExactInputCallParameters(
+SmartRouter.classicExactInputCallParameters(
   { amountIn, amountOutMin, path, recipient },
   { deadlineOrPreviousBlockhash: deadline },
 );
 
 // Classic stable section
-ApexSmartRouter.stableExactInputCallParameters(
+SmartRouter.stableExactInputCallParameters(
   { amountIn, amountOutMin, path, flags, recipient },
   { deadlineOrPreviousBlockhash: deadline },
 );
 
 // CL section
-ApexSmartRouter.exactInputCallParameters(
+SmartRouter.exactInputCallParameters(
   { path, recipient, amountIn, amountOutMinimum },
   { deadlineOrPreviousBlockhash: deadline },
 );
 ```
 
-Use the raw `encode*` helpers only when deliberately assembling a custom multicall. User-facing swaps should use `*CallParameters`, or `ApexSmartRouter.swapCallParameters(rawCalls, options)` for custom batches. These require a deadline or previous blockhash and support cleanup calls such as `refundETH`, `sweepToken`, and `unwrapWETH9`.
+Use the raw `encode*` helpers only when deliberately assembling a custom multicall. User-facing swaps should use `*CallParameters`, or `SmartRouter.swapCallParameters(rawCalls, options)` for custom batches. These require a deadline or previous blockhash.
+
+When `value` is nonzero, `SmartRouter` call-parameter helpers append `refundETH()` automatically. Token sweeps and WETH unwraps require explicit cleanup entries because the SDK cannot infer the intended token, recipient, or minimum amount for every route.
 
 The mixed periphery is exact-input only. Use the CL-only `SwapRouter`/`QuoterV2` for CL exact-output routes.
 
 ### CL farm UX
 
-Use `ApexCLFarm` for staked CL positions. It encodes the Apex-safe paths instead of making the frontend assemble Chef calls by hand.
+Use `CLMasterChef` for staked CL positions. It encodes the supported paths without requiring applications to assemble Chef calls directly.
 
 ```ts
-const { calldata, value } = ApexCLFarm.mintAndStakeCallParameters(
+const { calldata, value } = CLMasterChef.mintAndStakeCallParameters(
   {
     token0: tokenA.address,
     token1: tokenB.address,
-    fee: ApexFeeAmount.FEE_0_30,
+    fee: CLFeeAmount.FEE_0_30,
     tickLower,
     tickUpper,
     amount0Desired,
@@ -272,19 +274,19 @@ const { calldata, value } = ApexCLFarm.mintAndStakeCallParameters(
 );
 ```
 
-`mintAndStakeCallParameters` takes `account` and encodes it as the staked NFT owner. It rejects the Chef and NFP manager as owners so frontend callers cannot strand positions in protocol contracts.
+`mintAndStakeCallParameters` takes `account` and encodes it as the staked NFT owner. It rejects the Chef and NFP manager as owners so callers cannot strand positions in protocol contracts.
 
 When minting with native ETH, pass `value` in the options object. The SDK appends `refundETH()` in the same NFP multicall only when value is nonzero.
 
 For fee collection on staked NFTs, prefer `collectCallParameters` or `decreaseAndCollectCallParameters`:
 
 ```ts
-const collect = ApexCLFarm.collectCallParameters({
+const collect = CLMasterChef.collectCallParameters({
   tokenId,
   recipient: account,
 });
 
-const exitPart = ApexCLFarm.decreaseAndCollectCallParameters(
+const exitPart = CLMasterChef.decreaseAndCollectCallParameters(
   { tokenId, liquidity, amount0Min, amount1Min, deadline },
   { tokenId, recipient: account },
 );
@@ -295,7 +297,7 @@ These helpers call `CLMasterChef.multicall(...)` and use `collectTo` with the in
 For a full exit, use `closeAndBurnCallParameters`:
 
 ```ts
-const close = ApexCLFarm.closeAndBurnCallParameters(
+const close = CLMasterChef.closeAndBurnCallParameters(
   { tokenId, liquidity, amount0Min, amount1Min, deadline },
   { tokenId, recipient: account },
 );
@@ -303,17 +305,17 @@ const close = ApexCLFarm.closeAndBurnCallParameters(
 
 This encodes `harvest -> decreaseLiquidity -> collectTo -> burn`. The harvest happens before liquidity is removed, so it is safe even when rewards are zero and keeps `burn` compatible with Pancake-style strict empty-position semantics.
 
-### Apex Vault UX
+### ApexVault UX
 
-Use `ApexVaultPosition` for user-facing VeApexToken vault actions. Users choose reward-token percentages and a compound percentage. Compound is not user-claimable APEX; the user config only selects the compound bucket, and the protocol operator later calls the controller/vault compound functions.
+Use `ApexVault` for user-facing VeApexToken actions. Users choose reward-token percentages and a compound percentage. Compound is not user-claimable APEX; the user config selects the compound bucket, and the protocol operator later calls the controller and ApexVault compound functions.
 
 ```ts
-const approveVault = ApexVaultPosition.encodeVeApexTokenApprove({
+const approveVault = ApexVault.encodeVeApexTokenApprove({
   tokenId,
   spender: apexVault,
 });
 
-const stake = ApexVaultPosition.stakeCallParameters(tokenId, {
+const stake = ApexVault.stakeCallParameters(tokenId, {
   rewardConfigs: [
     { rewardToken: weth, bps: 5_000 },
     { rewardToken: usdc, bps: 2_000 },
@@ -327,28 +329,28 @@ The helper rejects configs that do not sum to exactly `10_000` bps, repeat a rew
 For an existing staked veNFT:
 
 ```ts
-const updateConfig = ApexVaultPosition.setUserConfigCallParameters(tokenId, {
+const updateConfig = ApexVault.setUserConfigCallParameters(tokenId, {
   rewardConfigs: [{ rewardToken: weth, bps: 7_000 }],
   compoundBps: 3_000,
 });
 
-const claim = ApexVaultPosition.claimCallParameters({
+const claim = ApexVault.claimCallParameters({
   tokenId,
   rewardTokens: [weth, usdc],
 });
 
-const extend = ApexVaultPosition.extendLockCallParameters({
+const extend = ApexVault.extendLockCallParameters({
   tokenId,
   lockDuration: 26n * 7n * 86_400n,
 });
 
-const increase = ApexVaultPosition.increaseAmountCallParameters({
+const increase = ApexVault.increaseAmountCallParameters({
   tokenId,
   amount,
 });
 ```
 
-The vault is custodial while staked. For staked veNFTs, route amount increases through `ApexVaultPosition.increaseAmountCallParameters(...)`, not raw `VeApexToken.depositFor(...)`, so Vault reward weights are refreshed. A direct VeApexToken transfer outside the vault is just a normal NFT transfer; the SDK should treat vault stake/unstake as the canonical earning path.
+ApexVault is custodial while a veNFT is staked. For staked veNFTs, route amount increases through `ApexVault.increaseAmountCallParameters(...)`, not raw `VeApexToken.depositFor(...)`, so ApexVault reward weights are refreshed. A direct VeApexToken transfer outside ApexVault is a normal NFT transfer; treat ApexVault stake and unstake as the canonical earning path.
 
 ### ABI refresh