@aspan/sdk 0.4.0 → 0.4.2

package/src/client.ts

@@ -16,6 +16,43 @@ import {
   type Hash,
 } from "viem";
 import { bsc, bscTestnet } from "viem/chains";
+
+/** Pharos Atlantic Testnet chain definition */
+export const pharosTestnet: Chain = {
+  id: 688689,
+  name: "Pharos Atlantic Testnet",
+  nativeCurrency: { name: "PHRS", symbol: "PHRS", decimals: 18 },
+  rpcUrls: {
+    default: { http: ["https://atlantic.dplabs-internal.com"] },
+  },
+  blockExplorers: {
+    default: { name: "Pharos Explorer", url: "https://atlantic.pharosscan.xyz" },
+  },
+} as const satisfies Chain;
+
+/** Supported chain IDs */
+export const CHAIN_IDS = {
+  BSC: 56,
+  BSC_TESTNET: 97,
+  PHAROS: 688689,
+} as const;
+
+/** Internal: map chainId to viem Chain object */
+const CHAIN_MAP: Record<number, Chain> = {
+  [CHAIN_IDS.BSC]: bsc,
+  [CHAIN_IDS.BSC_TESTNET]: bscTestnet,
+  [CHAIN_IDS.PHAROS]: pharosTestnet,
+};
+
+/**
+ * Get the viem Chain object for a given chainId.
+ * @throws if the chainId is not supported
+ */
+export function getChainById(chainId: number): Chain {
+  const chain = CHAIN_MAP[chainId];
+  if (!chain) throw new Error(`[Aspan SDK] Unsupported chainId: ${chainId}`);
+  return chain;
+}
 import { DiamondABI } from "./abi/diamond";
 import type {
   LSTInfo,
@@ -65,7 +102,7 @@ export interface AspanWriteClientConfig extends AspanClientConfig {
  */
 export class AspanReadClient {
   protected readonly publicClient: PublicClient;
-  protected readonly diamondAddress: Address;
+  public readonly diamondAddress: Address;
   protected readonly chain: Chain;
 
   // Known error signatures for zero supply states
@@ -798,6 +835,32 @@ export class AspanReadClient {
     });
   }
 
+  // ============ Bootstrap View Functions ============
+
+  /**
+   * Check if xBNB liquidity has been bootstrapped
+   * @returns true if bootstrap has been called
+   */
+  async isBootstrapped(): Promise<boolean> {
+    return this.publicClient.readContract({
+      address: this.diamondAddress,
+      abi: DiamondABI,
+      functionName: "isBootstrapped",
+    });
+  }
+
+  /**
+   * Get the amount of xBNB locked in bootstrap (burned to dead address)
+   * @returns xBNB amount in wei
+   */
+  async getBootstrapXBNBAmount(): Promise<bigint> {
+    return this.publicClient.readContract({
+      address: this.diamondAddress,
+      abi: DiamondABI,
+      functionName: "getBootstrapXBNBAmount",
+    });
+  }
+
   // ============ Stability Mode View Functions ============
 
   async getStabilityMode(): Promise<StabilityModeInfo> {
@@ -1031,6 +1094,89 @@ export class AspanClient extends AspanReadClient {
     });
   }
 
+  // ============ Risk Management Functions ============
+
+  /**
+   * Trigger Stability Mode 2 forced conversion
+   * @description Anyone can call when CR < 130%. Burns apUSD from stability pool
+   * and mints xBNB to compensate stakers.
+   * @param targetCR Target CR to restore to (in BPS, e.g., 14000 = 140%)
+   * @returns Transaction hash
+   */
+  async triggerStabilityMode2(targetCR: bigint = 14000n): Promise<Hash> {
+    return this.walletClient.writeContract({
+      chain: this.chain,
+      account: this.walletClient.account!,
+      address: this.diamondAddress,
+      abi: DiamondABI,
+      functionName: "triggerStabilityMode2",
+      args: [targetCR],
+    });
+  }
+
+  /**
+   * Clean underwater xBNB (burn without getting LST back)
+   * @description Only works when xBNB is underwater (price = 0)
+   * @param xBNBAmount Amount of xBNB to clean (burn)
+   * @returns Transaction hash
+   */
+  async cleanXbnb(xBNBAmount: bigint): Promise<Hash> {
+    return this.walletClient.writeContract({
+      chain: this.chain,
+      account: this.walletClient.account!,
+      address: this.diamondAddress,
+      abi: DiamondABI,
+      functionName: "cleanXbnb",
+      args: [xBNBAmount],
+    });
+  }
+
+  // ============ Fee Management Functions ============
+
+  /**
+   * Set fee tiers (requires feeManager or owner role)
+   * @param tiers Array of fee tier configurations
+   * @returns Transaction hash
+   */
+  async setFeeTiers(tiers: Array<{
+    minCR: bigint;
+    apUSDMintFee: number;
+    apUSDRedeemFee: number;
+    xBNBMintFee: number;
+    xBNBRedeemFee: number;
+    apUSDMintDisabled: boolean;
+  }>): Promise<Hash> {
+    return this.walletClient.writeContract({
+      chain: this.chain,
+      account: this.walletClient.account!,
+      address: this.diamondAddress,
+      abi: DiamondABI,
+      functionName: "setFeeTiers",
+      args: [tiers],
+    });
+  }
+
+  // ============ Admin Functions ============
+
+  /**
+   * Bootstrap xBNB liquidity (owner only)
+   * @description Initializes xBNB supply by minting to dead address, preventing extreme initial prices.
+   * Similar to Uniswap V2's MINIMUM_LIQUIDITY. Can only be called once.
+   * @param lstToken LST token address to deposit
+   * @param lstAmount Amount of LST to deposit for bootstrap
+   * @returns Transaction hash
+   */
+  async bootstrap(lstToken: Address, lstAmount: bigint): Promise<Hash> {
+    return this.walletClient.writeContract({
+      chain: this.chain,
+      account: this.walletClient.account!,
+      address: this.diamondAddress,
+      abi: DiamondABI,
+      functionName: "bootstrap",
+      args: [lstToken, lstAmount],
+    });
+  }
+
   // ============ Transaction Helpers ============
 
   /**
@@ -1104,3 +1250,71 @@ export function createAspanTestnetClient(
     rpcUrl,
   });
 }
+
+/**
+ * Create a read-only client for Pharos Atlantic Testnet
+ */
+export function createAspanPharosReadClient(
+  diamondAddress: Address,
+  rpcUrl?: string
+): AspanReadClient {
+  return new AspanReadClient({
+    diamondAddress,
+    chain: pharosTestnet,
+    rpcUrl,
+  });
+}
+
+/**
+ * Create a full client for Pharos Atlantic Testnet
+ */
+export function createAspanPharosClient(
+  diamondAddress: Address,
+  account: Account,
+  rpcUrl?: string
+): AspanClient {
+  return new AspanClient({
+    diamondAddress,
+    account,
+    chain: pharosTestnet,
+    rpcUrl,
+  });
+}
+
+// ============ Chain-ID-based Factory Functions ============
+
+/**
+ * Create a read-only Aspan client by chainId.
+ * Defaults to BSC mainnet (chainId = 56) if chainId is not provided.
+ *
+ * @param diamondAddress Diamond contract address for the target chain.
+ * @param chainId        Target chain ID (56 = BSC, 688689 = Pharos). Defaults to 56.
+ * @param rpcUrl         Optional custom RPC endpoint.
+ */
+export function createAspanReadClientForChain(
+  diamondAddress: Address,
+  chainId: number = CHAIN_IDS.BSC,
+  rpcUrl?: string
+): AspanReadClient {
+  const chain = getChainById(chainId);
+  return new AspanReadClient({ diamondAddress, chain, rpcUrl });
+}
+
+/**
+ * Create a write Aspan client by chainId using an external wagmi WalletClient.
+ * Defaults to BSC mainnet (chainId = 56) if chainId is not provided.
+ *
+ * @param diamondAddress Diamond contract address for the target chain.
+ * @param chainId        Target chain ID (56 = BSC, 688689 = Pharos). Defaults to 56.
+ * @param walletClient   External WalletClient from wagmi / viem.
+ * @param rpcUrl         Optional custom RPC endpoint.
+ */
+export function createAspanWriteClientForChain(
+  diamondAddress: Address,
+  chainId: number = CHAIN_IDS.BSC,
+  walletClient: WalletClient<Transport, Chain, Account>,
+  rpcUrl?: string
+): AspanClient {
+  const chain = getChainById(chainId);
+  return new AspanClient({ diamondAddress, chain, walletClient, rpcUrl });
+}

package/src/index.ts

@@ -13,6 +13,15 @@ export {
   createAspanClient,
   createAspanTestnetReadClient,
   createAspanTestnetClient,
+  createAspanPharosReadClient,
+  createAspanPharosClient,
+  // Chain-ID-based factory functions
+  createAspanReadClientForChain,
+  createAspanWriteClientForChain,
+  // Chain helpers
+  pharosTestnet,
+  CHAIN_IDS,
+  getChainById,
   type AspanClientConfig,
   type AspanWriteClientConfig,
 } from "./client";
@@ -25,6 +34,11 @@ export {
   createRouterClient,
   createRouterTestnetReadClient,
   createRouterTestnetClient,
+  createRouterPharosReadClient,
+  createRouterPharosClient,
+  // Chain-ID-based factory functions
+  createRouterReadClientForChain,
+  createRouterWriteClientForChain,
   type AspanRouterClientConfig,
   type AspanRouterWriteClientConfig,
 } from "./router";
@@ -102,21 +116,31 @@ export const PRICE_PRECISION = 10n ** 8n; // Chainlink price precision
 
 // ============ Contract Addresses (BSC Mainnet) ============
 export const BSC_ADDRESSES = {
-  diamond: "0x10d25Ae0690533e0BA9E64EC7ae77dbD4fE8A46f" as const,
-  router: "0x813d3D1A3154950E2f1d8718305426a335A974A9" as const,
-  apUSD: "0x1977097E2E5697A6DD91b6732F368a14F50f6B3d" as const,
-  xBNB: "0xB78eB4d5928bAb158Eb23c3154544084cD2661d5" as const,
-  sApUSD: "0xE2BE739C4aA4126ee72D612d9548C38B1B0e5A1b" as const,
+  diamond: "0x6a11B30d3a70727d5477D6d8090e144443fA1c78" as const,
+  router: "0x29dd49b2e98674ee7531f17e4d40a7725918c3f6" as const,
+  apUSD: "0x4570047eeB5aDb4081c5d470494EB5134e34A287" as const,
+  xBNB: "0x0A0c9CD826e747D99F90D63e780B3727Da4D0d43" as const,
+  sApUSD: "0x73407A291c007a47CC926EcD5CaC256A1E2d00cF" as const,
   // LSTs
   slisBNB: "0xB0b84D294e0C75A6abe60171b70edEb2EFd14A1B" as const,
   asBNB: "0x77734e70b6E88b4d82fE632a168EDf6e700912b6" as const,
-  wclisBNB: "0x439faaC2229559121C4Ad4fd8B3FE13Dff038046" as const,
+  wclisBNB: "0x448f7c2fa4e5135a4a5B50879602cf3CD428e108" as const,
   // Stablecoins
   USDT: "0x55d398326f99059fF775485246999027B3197955" as const,
   USDC: "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d" as const,
   WBNB: "0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c" as const,
 } as const;
 
+export const PHAROS_ADDRESSES = {
+  diamond: "0x67011Ce4B5E534FA78dD9922559B7005197DBcc8" as const,
+  apUSD: "0x82ac96db027772cE8a770e099370b5D7941B3ae4" as const,
+  xBNB: "0xFF43b2f50b2c6c588d14Ea4565Ee5Eb93e438576" as const,
+  sApUSD: "0xFA4B826CfD5faaAfA48E4963d8a7d6Cf9889A9A8" as const,
+  mockLST: "0xc7BB55759e8e04AfAA620De96E9E133B1FAd3e18" as const,
+  mockPriceFeed: "0xa2B41DDE7a7BB0A897DE476Ea441fB27A6978682" as const,
+  mockExchangeRate: "0xffA1938e072Ea3b144EA7e61662dd8B0818D82B9" as const,
+} as const;
+
 // ============ Utility Functions ============
 
 /**

package/src/router.ts

@@ -18,6 +18,7 @@ import {
   type Hash,
 } from "viem";
 import { bsc, bscTestnet } from "viem/chains";
+import { pharosTestnet, CHAIN_IDS, getChainById } from "./client";
 import { RouterABI } from "./abi/router";
 import type {
   SwapAndMintParams,
@@ -514,3 +515,71 @@ export function createRouterTestnetClient(
     rpcUrl,
   });
 }
+
+/**
+ * Create a read-only router client for Pharos Atlantic Testnet
+ */
+export function createRouterPharosReadClient(
+  routerAddress: Address,
+  rpcUrl?: string
+): AspanRouterReadClient {
+  return new AspanRouterReadClient({
+    routerAddress,
+    chain: pharosTestnet,
+    rpcUrl,
+  });
+}
+
+/**
+ * Create a full router client for Pharos Atlantic Testnet
+ */
+export function createRouterPharosClient(
+  routerAddress: Address,
+  account: Account,
+  rpcUrl?: string
+): AspanRouterClient {
+  return new AspanRouterClient({
+    routerAddress,
+    account,
+    chain: pharosTestnet,
+    rpcUrl,
+  });
+}
+
+// ============ Chain-ID-based Factory Functions ============
+
+/**
+ * Create a read-only AspanRouter client by chainId.
+ * Defaults to BSC mainnet (chainId = 56) if chainId is not provided.
+ *
+ * @param routerAddress Router contract address for the target chain.
+ * @param chainId       Target chain ID (56 = BSC, 688689 = Pharos). Defaults to 56.
+ * @param rpcUrl        Optional custom RPC endpoint.
+ */
+export function createRouterReadClientForChain(
+  routerAddress: Address,
+  chainId: number = CHAIN_IDS.BSC,
+  rpcUrl?: string
+): AspanRouterReadClient {
+  const chain = getChainById(chainId);
+  return new AspanRouterReadClient({ routerAddress, chain, rpcUrl });
+}
+
+/**
+ * Create a write AspanRouter client by chainId using an external wagmi WalletClient.
+ * Defaults to BSC mainnet (chainId = 56) if chainId is not provided.
+ *
+ * @param routerAddress Router contract address for the target chain.
+ * @param chainId       Target chain ID (56 = BSC, 688689 = Pharos). Defaults to 56.
+ * @param walletClient  External WalletClient from wagmi / viem.
+ * @param rpcUrl        Optional custom RPC endpoint.
+ */
+export function createRouterWriteClientForChain(
+  routerAddress: Address,
+  chainId: number = CHAIN_IDS.BSC,
+  walletClient: WalletClient<Transport, Chain, Account>,
+  rpcUrl?: string
+): AspanRouterClient {
+  const chain = getChainById(chainId);
+  return new AspanRouterClient({ routerAddress, chain, walletClient, rpcUrl });
+}