@trantorapex/apex-sdk 0.1.0

package/README.md

@@ -0,0 +1,375 @@
+# 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.
+
+## Setup
+
+```bash
+cd apex-sdk
+npm install
+npm run sync:abis
+npm run build
+npm test
+```
+
+Install the published package:
+
+```bash
+npm install @trantorapex/apex-sdk
+```
+
+## Config
+
+Do not hardcode deployment addresses in app code. Keep one config object per chain:
+
+```ts
+import type { ApexDeploymentConfig } from "@trantorapex/apex-sdk";
+
+export const apex: ApexDeploymentConfig = {
+  chainId: 31337,
+  clFactory: "0x...",
+  clPoolDeployer: "0x...",
+  clSwapRouter: "0x...",
+  clQuoter: "0x...",
+  clNonfungiblePositionManager: "0x...",
+  clMasterChef: "0x...",
+  smartRouter: "0x...",
+  mixedQuoter: "0x...",
+  classicFactory: "0x...",
+  classicPairInitCodeHash: "0x...",
+  classicRouter: "0x...",
+  classicChef: "0x...",
+  weth: "0x...",
+};
+```
+
+## Functions frontend should care about
+
+```ts
+import {
+  ApexFeeAmount,
+  APEX_CL_POOL_INIT_CODE_HASH,
+  APEX_CL_TICK_SPACINGS,
+  APEX_CLASSIC_PAIR_INIT_CODE_HASH,
+  ApexClassicFarm,
+  ApexCLFarm,
+  ApexSmartRouter,
+  ApexVaultPosition,
+  getApexTickSpacing,
+  createApexPool,
+  computeCLPoolAddress,
+  computeClassicPoolAddress,
+  quoteApexClassicExactInput,
+  encodeApexMixedRouteToPath,
+  encodeApexMixedRouteToPancakeQuoteParams,
+  decodeApexMixedRoutePath,
+  parseApexProtocolFeePacked,
+  apexCLPoolAbi,
+  apexCLFactoryAbi,
+  apexCLMasterChefAbi,
+  apexNonfungiblePositionManagerAbi,
+  apexSwapRouterAbi,
+  apexSmartRouterAbi,
+  apexMixedQuoterAbi,
+  apexQuoterV2Abi,
+  apexClassicFactoryAbi,
+  apexClassicPairAbi,
+  Pool,
+  Route,
+  Trade,
+  SwapRouter,
+  NonfungiblePositionManager,
+  SwapQuoter,
+  TickMath,
+  nearestUsableTick,
+  encodeSqrtRatioX96,
+} from "@trantorapex/apex-sdk";
+```
+
+### CL pool address
+
+```ts
+const pool = computeCLPoolAddress({
+  config: apex,
+  tokenA,
+  tokenB,
+  fee: ApexFeeAmount.FEE_0_30,
+});
+```
+
+### CL pool object
+
+```ts
+const pool = createApexPool({
+  tokenA,
+  tokenB,
+  fee: ApexFeeAmount.FEE_0_30,
+  sqrtRatioX96,
+  liquidity,
+  tickCurrent,
+  ticks,
+});
+```
+
+`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 `@trantorapex/apex-sdk`.
+
+### Periphery ABIs
+
+Use the exact ABIs exported from compiled Apex contracts:
+
+```ts
+import {
+  apexNonfungiblePositionManagerAbi,
+  apexSwapRouterAbi,
+  apexQuoterAbi,
+  apexQuoterV2Abi,
+  apexSmartRouterAbi,
+  apexMixedQuoterAbi,
+  apexTickLensAbi,
+  apexInterfaceMulticallAbi,
+  apexCLFactoryAbi,
+  apexCLMasterChefAbi,
+  apexCLPoolAbi,
+  apexClassicFactoryAbi,
+  apexClassicPairAbi,
+} from "@trantorapex/apex-sdk";
+```
+
+### Classic pair address
+
+```ts
+const stablePair = computeClassicPoolAddress({
+  config: apex,
+  tokenA: tokenA.address,
+  tokenB: tokenB.address,
+  stable: true,
+});
+```
+
+### Classic quote
+
+```ts
+const amountOut = quoteApexClassicExactInput({
+  amountIn,
+  tokenIn: tokenA.address,
+  token0,
+  token1,
+  reserve0,
+  reserve1,
+  token0Decimals: 18,
+  token1Decimals: 18,
+  stable: false,
+  fee,
+});
+```
+
+### 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:
+
+```ts
+const stakeClassic = ApexClassicFarm.depositCallParameters({
+  pid,
+  amount,
+});
+
+const claimClassic = ApexClassicFarm.harvestCallParameters({
+  pid,
+});
+
+const exitClassic = ApexClassicFarm.withdrawCallParameters({
+  pid,
+  amount,
+});
+```
+
+### Mixed CL/Classic path
+
+```ts
+const path = encodeApexMixedRouteToPath([
+  {
+    kind: "CL",
+    tokenIn: tokenA.address,
+    tokenOut: tokenB.address,
+    fee: ApexFeeAmount.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:
+they encode the swap, then wrap it in `SmartRouter.multicall(deadlineOrPreviousBlockhash, data)`.
+
+```ts
+const swap = ApexSmartRouter.mixedExactInputCallParameters(
+  { hops, recipient: account, amountIn, amountOutMinimum },
+  { deadlineOrPreviousBlockhash: deadline },
+);
+```
+
+If you fork Pancake SmartRouter’s mixed quote provider, use Pancake-style quote params:
+
+```ts
+const { path, flags } = encodeApexMixedRouteToPancakeQuoteParams(hops);
+const quote = await publicClient.readContract({
+  address: apex.mixedQuoter,
+  abi: apexMixedQuoterAbi,
+  functionName: "quoteExactInput",
+  args: [path, flags, amountIn],
+});
+```
+
+For routes that Pancake SmartRouter partitions by protocol:
+
+```ts
+// Classic volatile section
+ApexSmartRouter.classicExactInputCallParameters(
+  { amountIn, amountOutMin, path, recipient },
+  { deadlineOrPreviousBlockhash: deadline },
+);
+
+// Classic stable section
+ApexSmartRouter.stableExactInputCallParameters(
+  { amountIn, amountOutMin, path, flags, recipient },
+  { deadlineOrPreviousBlockhash: deadline },
+);
+
+// CL section
+ApexSmartRouter.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`.
+
+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.
+
+```ts
+const { calldata, value } = ApexCLFarm.mintAndStakeCallParameters(
+  {
+    token0: tokenA.address,
+    token1: tokenB.address,
+    fee: ApexFeeAmount.FEE_0_30,
+    tickLower,
+    tickUpper,
+    amount0Desired,
+    amount1Desired,
+    amount0Min,
+    amount1Min,
+    account,
+    deadline,
+  },
+  {
+    stakingReceiver: apex.clMasterChef,
+    nonfungiblePositionManager: apex.clNonfungiblePositionManager,
+  },
+);
+```
+
+`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.
+
+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({
+  tokenId,
+  recipient: account,
+});
+
+const exitPart = ApexCLFarm.decreaseAndCollectCallParameters(
+  { tokenId, liquidity, amount0Min, amount1Min, deadline },
+  { tokenId, recipient: account },
+);
+```
+
+These helpers call `CLMasterChef.multicall(...)` and use `collectTo` with the inner collect recipient set to `address(0)`, so Chef receives the tokens first and immediately sweeps/unwraps them to the final recipient.
+
+For a full exit, use `closeAndBurnCallParameters`:
+
+```ts
+const close = ApexCLFarm.closeAndBurnCallParameters(
+  { tokenId, liquidity, amount0Min, amount1Min, deadline },
+  { tokenId, recipient: account },
+);
+```
+
+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
+
+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.
+
+```ts
+const approveVault = ApexVaultPosition.encodeVeApexTokenApprove({
+  tokenId,
+  spender: apexVault,
+});
+
+const stake = ApexVaultPosition.stakeCallParameters(tokenId, {
+  rewardConfigs: [
+    { rewardToken: weth, bps: 5_000 },
+    { rewardToken: usdc, bps: 2_000 },
+  ],
+  compoundBps: 3_000,
+});
+```
+
+The helper rejects configs that do not sum to exactly `10_000` bps, repeat a reward token, use zero bps for a reward token, or use the zero address as a reward token.
+
+For an existing staked veNFT:
+
+```ts
+const updateConfig = ApexVaultPosition.setUserConfigCallParameters(tokenId, {
+  rewardConfigs: [{ rewardToken: weth, bps: 7_000 }],
+  compoundBps: 3_000,
+});
+
+const claim = ApexVaultPosition.claimCallParameters({
+  tokenId,
+  rewardTokens: [weth, usdc],
+});
+
+const extend = ApexVaultPosition.extendLockCallParameters({
+  tokenId,
+  lockDuration: 26n * 7n * 86_400n,
+});
+
+const increase = ApexVaultPosition.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.
+
+### ABI refresh
+
+After Solidity changes, refresh SDK ABIs from Forge artifacts before testing or publishing:
+
+```bash
+forge build
+npm run sync:abis --prefix apex-sdk
+npm test --prefix apex-sdk
+npm run build --prefix apex-sdk
+```
+
+## Notes
+
+- Apex CL callbacks remain Pancake-compatible, so Pancake v3 periphery assumptions are preserved.
+- The Pancake v3 SDK base is vendored under `vendor/pancake-v3-sdk`; Apex does not depend on the live `@pancakeswap/v3-sdk` npm package at runtime.
+- Apex periphery exports include `NonfungiblePositionManager`, `SwapRouter`, `SmartRouter`, `Quoter`, `QuoterV2`, `MixedQuoter`, `TickLens`, and `InterfaceMulticall`.
+- `MixedQuoter` supports both Apex-native `quoteExactInput(bytes,uint256)` and Pancake SmartRouter-style `quoteExactInput(bytes,uint256[],uint256)` for Classic+CL route discovery.
+- Apex CL pool addresses use the Apex `CLPoolDeployer`, not the factory, matching the contract salt `keccak256(abi.encode(token0, token1, fee))`.
+- Apex Classic pair addresses use the Classic factory salt `keccak256(abi.encodePacked(token0, token1, stable))`.
+- `APEX_CL_POOL_INIT_CODE_HASH` and `APEX_CLASSIC_PAIR_INIT_CODE_HASH` are exported and used by default; override them only if the compiled contract bytecode changes.
+- Apex Classic fees are denominated by `1_000_000`.
+- Apex CL protocol fees are denominated by `10_000`, so `10_000` means 100%.
+- Classic protocol fees are first realized by `collectClassicProtocolFees(pair)`, which burns FeeCenter-held fee LP into raw pair tokens. `pushAndSplitFees(tokens)` only splits raw token balances that are already in FeeCenter.