@aspan/sdk 0.1.4

package/src/client.ts

@@ -0,0 +1,1030 @@
+/**
+ * Aspan SDK Client
+ * TypeScript client for interacting with the Aspan Protocol
+ */
+
+import {
+  createPublicClient,
+  createWalletClient,
+  http,
+  type Address,
+  type PublicClient,
+  type WalletClient,
+  type Transport,
+  type Chain,
+  type Account,
+  type Hash,
+} from "viem";
+import { bsc, bscTestnet } from "viem/chains";
+import { DiamondABI } from "./abi/diamond";
+import type {
+  LSTInfo,
+  LSTYieldInfo,
+  FeeTier,
+  CurrentFeeTier,
+  CurrentFees,
+  OracleBounds,
+  StabilityModeInfo,
+  StabilityMode2Info,
+  ProtocolStats,
+  StabilityPoolStats,
+  YieldStats,
+  UserStabilityPoolPosition,
+  TokenAddresses,
+  MintApUSDParams,
+  RedeemApUSDParams,
+  MintXBNBParams,
+  RedeemXBNBParams,
+  DepositParams,
+  WithdrawParams,
+  WithdrawAssetsParams,
+} from "./types";
+
+// ============ Configuration ============
+
+export interface AspanClientConfig {
+  /** Diamond contract address */
+  diamondAddress: Address;
+  /** Chain to connect to */
+  chain?: Chain;
+  /** RPC URL (optional, uses default if not provided) */
+  rpcUrl?: string;
+}
+
+export interface AspanWriteClientConfig extends AspanClientConfig {
+  /** Account for signing transactions */
+  account: Account;
+}
+
+// ============ Read-Only Client ============
+
+/**
+ * Read-only client for querying Aspan Protocol state
+ */
+export class AspanReadClient {
+  protected readonly publicClient: PublicClient;
+  protected readonly diamondAddress: Address;
+  protected readonly chain: Chain;
+
+  // Known error signatures for zero supply states
+  private static readonly ZERO_SUPPLY_ERROR_SIGNATURES = [
+    "0x403e7fa6", // Custom error when xBNB supply is zero
+  ];
+
+  constructor(config: AspanClientConfig) {
+    this.diamondAddress = config.diamondAddress;
+    this.chain = config.chain ?? bsc;
+
+    this.publicClient = createPublicClient({
+      chain: this.chain,
+      transport: http(config.rpcUrl),
+    });
+  }
+
+  /**
+   * Check if error is a known zero supply error from the contract
+   */
+  protected isZeroSupplyError(error: unknown): boolean {
+    if (error && typeof error === "object" && "message" in error) {
+      const message = (error as { message: string }).message;
+      return AspanReadClient.ZERO_SUPPLY_ERROR_SIGNATURES.some((sig) =>
+        message.includes(sig)
+      );
+    }
+    return false;
+  }
+
+  // ============ Protocol Stats ============
+
+  /**
+   * Get comprehensive protocol statistics
+   */
+  async getProtocolStats(): Promise<ProtocolStats> {
+    const [
+      tvlInBNB,
+      tvlInUSD,
+      collateralRatio,
+      apUSDSupply,
+      xBNBSupply,
+      xBNBPriceBNB,
+      xBNBPriceUSD,
+      effectiveLeverage,
+    ] = await Promise.all([
+      this.getTVLInBNB(),
+      this.getTVLInUSD(),
+      this.getCollateralRatio(),
+      this.getApUSDSupply(),
+      this.getXBNBSupply(),
+      this.getXBNBPriceBNB(),
+      this.getXBNBPriceUSD(),
+      this.getEffectiveLeverage(),
+    ]);
+
+    return {
+      tvlInBNB,
+      tvlInUSD,
+      collateralRatio,
+      apUSDSupply,
+      xBNBSupply,
+      xBNBPriceBNB,
+      xBNBPriceUSD,
+      effectiveLeverage,
+    };
+  }
+
+  /**
+   * Get stability pool statistics
+   */
+  async getStabilityPoolStats(): Promise<StabilityPoolStats> {
+    const [totalStaked, exchangeRate, pendingYield] = await Promise.all([
+      this.getTotalStaked(),
+      this.getExchangeRate(),
+      this.getPendingYield(),
+    ]);
+
+    return {
+      totalStaked,
+      exchangeRate,
+      pendingYield,
+    };
+  }
+
+  /**
+   * Get yield statistics
+   */
+  async getYieldStats(): Promise<YieldStats> {
+    const [
+      totalYieldGenerated,
+      pendingYield,
+      lastHarvestTimestamp,
+      minHarvestInterval,
+      previewedHarvest,
+    ] = await Promise.all([
+      this.getTotalYieldGenerated(),
+      this.getPendingYield(),
+      this.getLastHarvestTimestamp(),
+      this.getMinHarvestInterval(),
+      this.previewHarvest(),
+    ]);
+
+    return {
+      totalYieldGenerated,
+      pendingYield,
+      lastHarvestTimestamp,
+      minHarvestInterval,
+      previewedHarvest,
+    };
+  }
+
+  // ============ Pool View Functions ============
+
+  async getTVLInBNB(): Promise<bigint> {
+    try {
+      return await this.publicClient.readContract({
+        address: this.diamondAddress,
+        abi: DiamondABI,
+        functionName: "getTVLInBNB",
+      });
+    } catch (error) {
+      if (this.isZeroSupplyError(error)) {
+        return 0n;
+      }
+      throw error;
+    }
+  }
+
+  async getTVLInUSD(): Promise<bigint> {
+    try {
+      return await this.publicClient.readContract({
+        address: this.diamondAddress,
+        abi: DiamondABI,
+        functionName: "getTVLInUSD",
+      });
+    } catch (error) {
+      if (this.isZeroSupplyError(error)) {
+        return 0n;
+      }
+      throw error;
+    }
+  }
+
+  async getCollateralRatio(): Promise<bigint> {
+    try {
+      const cr = await this.publicClient.readContract({
+        address: this.diamondAddress,
+        abi: DiamondABI,
+        functionName: "getCollateralRatio",
+      });
+      // Contract returns max uint256 when supply is zero (infinite CR)
+      // Treat anything above 1000000% (10000 * 1e18) as zero/undefined
+      if (cr > 10000n * 10n ** 18n) {
+        return 0n;
+      }
+      return cr;
+    } catch (error) {
+      // CR undefined when no apUSD supply exists
+      if (this.isZeroSupplyError(error)) {
+        return 0n;
+      }
+      throw error;
+    }
+  }
+
+  async getXBNBPriceBNB(): Promise<bigint> {
+    try {
+      return await this.publicClient.readContract({
+        address: this.diamondAddress,
+        abi: DiamondABI,
+        functionName: "getXBNBPriceBNB",
+      });
+    } catch (error) {
+      // Price undefined when no xBNB exists
+      if (this.isZeroSupplyError(error)) {
+        return 0n;
+      }
+      throw error;
+    }
+  }
+
+  async getXBNBPriceUSD(): Promise<bigint> {
+    try {
+      return await this.publicClient.readContract({
+        address: this.diamondAddress,
+        abi: DiamondABI,
+        functionName: "getXBNBPriceUSD",
+      });
+    } catch (error) {
+      // Price undefined when no xBNB exists
+      if (this.isZeroSupplyError(error)) {
+        return 0n;
+      }
+      throw error;
+    }
+  }
+
+  async getEffectiveLeverage(): Promise<bigint> {
+    try {
+      return await this.publicClient.readContract({
+        address: this.diamondAddress,
+        abi: DiamondABI,
+        functionName: "getEffectiveLeverage",
+      });
+    } catch (error) {
+      // Leverage undefined when no xBNB exists
+      if (this.isZeroSupplyError(error)) {
+        return 0n;
+      }
+      throw error;
+    }
+  }
+
+  async getApUSDSupply(): Promise<bigint> {
+    try {
+      return await this.publicClient.readContract({
+        address: this.diamondAddress,
+        abi: DiamondABI,
+        functionName: "getApUSDSupply",
+      });
+    } catch (error) {
+      // Contract reverts with custom error when no apUSD has been minted
+      if (this.isZeroSupplyError(error)) {
+        return 0n;
+      }
+      throw error;
+    }
+  }
+
+  async getXBNBSupply(): Promise<bigint> {
+    try {
+      return await this.publicClient.readContract({
+        address: this.diamondAddress,
+        abi: DiamondABI,
+        functionName: "getXBNBSupply",
+      });
+    } catch (error) {
+      // Contract reverts with custom error when no xBNB has been minted
+      if (this.isZeroSupplyError(error)) {
+        return 0n;
+      }
+      throw error;
+    }
+  }
+
+  async getLSTCollateral(lstToken: Address): Promise<bigint> {
+    try {
+      return await this.publicClient.readContract({
+        address: this.diamondAddress,
+        abi: DiamondABI,
+        functionName: "getLSTCollateral",
+        args: [lstToken],
+      });
+    } catch (error) {
+      if (this.isZeroSupplyError(error)) {
+        return 0n;
+      }
+      throw error;
+    }
+  }
+
+  async getCurrentFees(): Promise<CurrentFees> {
+    try {
+      const result = await this.publicClient.readContract({
+        address: this.diamondAddress,
+        abi: DiamondABI,
+        functionName: "getCurrentFees",
+      });
+
+      return {
+        currentCR: result[0],
+        tierMinCR: result[1],
+        apUSDMintFee: result[2],
+        apUSDRedeemFee: result[3],
+        xBNBMintFee: result[4],
+        xBNBRedeemFee: result[5],
+        apUSDMintDisabled: result[6],
+      };
+    } catch (error) {
+      // Return default fees when protocol is empty
+      if (this.isZeroSupplyError(error)) {
+        return {
+          currentCR: 0n,
+          tierMinCR: 0n,
+          apUSDMintFee: 0,
+          apUSDRedeemFee: 0,
+          xBNBMintFee: 0,
+          xBNBRedeemFee: 0,
+          apUSDMintDisabled: false,
+        };
+      }
+      throw error;
+    }
+  }
+
+  // ============ Oracle View Functions ============
+
+  async getBNBPriceUSD(): Promise<bigint> {
+    return this.publicClient.readContract({
+      address: this.diamondAddress,
+      abi: DiamondABI,
+      functionName: "getBNBPriceUSD",
+    });
+  }
+
+  async getLSTPriceUSD(lstToken: Address): Promise<bigint> {
+    return this.publicClient.readContract({
+      address: this.diamondAddress,
+      abi: DiamondABI,
+      functionName: "getLSTPriceUSD",
+      args: [lstToken],
+    });
+  }
+
+  async getLSTInfo(lstToken: Address): Promise<LSTInfo> {
+    const result = await this.publicClient.readContract({
+      address: this.diamondAddress,
+      abi: DiamondABI,
+      functionName: "getLSTInfo",
+      args: [lstToken],
+    });
+
+    return {
+      isAccepted: result[0],
+      priceFeed: result[1],
+      manualPriceUSD: result[2],
+      collateralAmount: result[3],
+      decimals: result[4],
+      exchangeRateProvider: result[5],
+      useIntrinsicValue: result[6],
+    };
+  }
+
+  async getSupportedLSTs(): Promise<readonly Address[]> {
+    return this.publicClient.readContract({
+      address: this.diamondAddress,
+      abi: DiamondABI,
+      functionName: "getSupportedLSTs",
+    });
+  }
+
+  async isLSTSupported(lstToken: Address): Promise<boolean> {
+    return this.publicClient.readContract({
+      address: this.diamondAddress,
+      abi: DiamondABI,
+      functionName: "isLSTSupported",
+      args: [lstToken],
+    });
+  }
+
+  async getBNBPriceFeed(): Promise<Address> {
+    return this.publicClient.readContract({
+      address: this.diamondAddress,
+      abi: DiamondABI,
+      functionName: "bnbPriceFeed",
+    });
+  }
+
+  async getOracleBounds(priceFeed: Address): Promise<OracleBounds> {
+    const result = await this.publicClient.readContract({
+      address: this.diamondAddress,
+      abi: DiamondABI,
+      functionName: "getOracleBounds",
+      args: [priceFeed],
+    });
+
+    return {
+      minPrice: result[0],
+      maxPrice: result[1],
+    };
+  }
+
+  // ============ Stability Pool View Functions ============
+
+  async getShares(user: Address): Promise<bigint> {
+    return this.publicClient.readContract({
+      address: this.diamondAddress,
+      abi: DiamondABI,
+      functionName: "getShares",
+      args: [user],
+    });
+  }
+
+  async getBalance(user: Address): Promise<bigint> {
+    return this.publicClient.readContract({
+      address: this.diamondAddress,
+      abi: DiamondABI,
+      functionName: "getBalance",
+      args: [user],
+    });
+  }
+
+  async getUserStabilityPoolPosition(
+    user: Address
+  ): Promise<UserStabilityPoolPosition> {
+    const [shares, balance] = await Promise.all([
+      this.getShares(user),
+      this.getBalance(user),
+    ]);
+
+    return { shares, balance };
+  }
+
+  async getExchangeRate(): Promise<bigint> {
+    try {
+      return await this.publicClient.readContract({
+        address: this.diamondAddress,
+        abi: DiamondABI,
+        functionName: "getExchangeRate",
+      });
+    } catch (error) {
+      // Exchange rate defaults to 1e18 when stability pool is empty
+      if (this.isZeroSupplyError(error)) {
+        return 10n ** 18n; // 1:1 ratio
+      }
+      throw error;
+    }
+  }
+
+  async getTotalStaked(): Promise<bigint> {
+    try {
+      return await this.publicClient.readContract({
+        address: this.diamondAddress,
+        abi: DiamondABI,
+        functionName: "getTotalStaked",
+      });
+    } catch (error) {
+      if (this.isZeroSupplyError(error)) {
+        return 0n;
+      }
+      throw error;
+    }
+  }
+
+  async previewDeposit(assets: bigint): Promise<bigint> {
+    try {
+      return await this.publicClient.readContract({
+        address: this.diamondAddress,
+        abi: DiamondABI,
+        functionName: "previewDeposit",
+        args: [assets],
+      });
+    } catch (error) {
+      if (this.isZeroSupplyError(error)) {
+        return assets; // 1:1 when pool is empty
+      }
+      throw error;
+    }
+  }
+
+  async previewRedeem(shares: bigint): Promise<bigint> {
+    try {
+      return await this.publicClient.readContract({
+        address: this.diamondAddress,
+        abi: DiamondABI,
+        functionName: "previewRedeem",
+        args: [shares],
+      });
+    } catch (error) {
+      if (this.isZeroSupplyError(error)) {
+        return shares; // 1:1 when pool is empty
+      }
+      throw error;
+    }
+  }
+
+  async getPendingYield(): Promise<bigint> {
+    try {
+      return await this.publicClient.readContract({
+        address: this.diamondAddress,
+        abi: DiamondABI,
+        functionName: "getPendingYield",
+      });
+    } catch (error) {
+      if (this.isZeroSupplyError(error)) {
+        return 0n;
+      }
+      throw error;
+    }
+  }
+
+  // ============ Yield View Functions ============
+
+  async getTotalYieldGenerated(): Promise<bigint> {
+    try {
+      return await this.publicClient.readContract({
+        address: this.diamondAddress,
+        abi: DiamondABI,
+        functionName: "getTotalYieldGenerated",
+      });
+    } catch (error) {
+      if (this.isZeroSupplyError(error)) {
+        return 0n;
+      }
+      throw error;
+    }
+  }
+
+  async getLSTYieldInfo(lstToken: Address): Promise<LSTYieldInfo> {
+    try {
+      const result = await this.publicClient.readContract({
+        address: this.diamondAddress,
+        abi: DiamondABI,
+        functionName: "getLSTYieldInfo",
+        args: [lstToken],
+      });
+
+      return {
+        lastExchangeRate: result[0],
+        lastUpdateTimestamp: result[1],
+      };
+    } catch (error) {
+      if (this.isZeroSupplyError(error)) {
+        return {
+          lastExchangeRate: 0n,
+          lastUpdateTimestamp: 0n,
+        };
+      }
+      throw error;
+    }
+  }
+
+  async getMinHarvestInterval(): Promise<bigint> {
+    try {
+      return await this.publicClient.readContract({
+        address: this.diamondAddress,
+        abi: DiamondABI,
+        functionName: "getMinHarvestInterval",
+      });
+    } catch (error) {
+      if (this.isZeroSupplyError(error)) {
+        return 0n;
+      }
+      throw error;
+    }
+  }
+
+  async getLastHarvestTimestamp(): Promise<bigint> {
+    try {
+      return await this.publicClient.readContract({
+        address: this.diamondAddress,
+        abi: DiamondABI,
+        functionName: "getLastHarvestTimestamp",
+      });
+    } catch (error) {
+      if (this.isZeroSupplyError(error)) {
+        return 0n;
+      }
+      throw error;
+    }
+  }
+
+  async previewHarvest(): Promise<bigint> {
+    try {
+      return await this.publicClient.readContract({
+        address: this.diamondAddress,
+        abi: DiamondABI,
+        functionName: "previewHarvest",
+      });
+    } catch (error) {
+      // No yield to harvest when no collateral exists
+      if (this.isZeroSupplyError(error)) {
+        return 0n;
+      }
+      throw error;
+    }
+  }
+
+  // ============ Config View Functions ============
+
+  async getTokens(): Promise<TokenAddresses> {
+    const [tokens, sApUSD] = await Promise.all([
+      this.publicClient.readContract({
+        address: this.diamondAddress,
+        abi: DiamondABI,
+        functionName: "getTokens",
+      }),
+      this.getSApUSD(),
+    ]);
+
+    return {
+      apUSD: tokens[0],
+      xBNB: tokens[1],
+      sApUSD,
+    };
+  }
+
+  async getSApUSD(): Promise<Address> {
+    return this.publicClient.readContract({
+      address: this.diamondAddress,
+      abi: DiamondABI,
+      functionName: "getSApUSD",
+    });
+  }
+
+  async getStabilityPool(): Promise<Address> {
+    return this.publicClient.readContract({
+      address: this.diamondAddress,
+      abi: DiamondABI,
+      functionName: "getStabilityPool",
+    });
+  }
+
+  async getTreasury(): Promise<Address> {
+    return this.publicClient.readContract({
+      address: this.diamondAddress,
+      abi: DiamondABI,
+      functionName: "getTreasury",
+    });
+  }
+
+  async getFeeTierCount(): Promise<bigint> {
+    return this.publicClient.readContract({
+      address: this.diamondAddress,
+      abi: DiamondABI,
+      functionName: "getFeeTierCount",
+    });
+  }
+
+  async getFeeTier(index: bigint): Promise<FeeTier> {
+    const result = await this.publicClient.readContract({
+      address: this.diamondAddress,
+      abi: DiamondABI,
+      functionName: "getFeeTier",
+      args: [index],
+    });
+
+    return {
+      minCR: result[0],
+      apUSDMintFee: result[1],
+      apUSDRedeemFee: result[2],
+      xBNBMintFee: result[3],
+      xBNBRedeemFee: result[4],
+      apUSDMintDisabled: result[5],
+    };
+  }
+
+  async getCurrentFeeTier(): Promise<CurrentFeeTier> {
+    try {
+      const result = await this.publicClient.readContract({
+        address: this.diamondAddress,
+        abi: DiamondABI,
+        functionName: "getCurrentFeeTier",
+      });
+
+      return {
+        minCR: result[0],
+        apUSDMintFee: result[1],
+        apUSDRedeemFee: result[2],
+        xBNBMintFee: result[3],
+        xBNBRedeemFee: result[4],
+        apUSDMintDisabled: result[5],
+        currentCR: result[6],
+      };
+    } catch (error) {
+      // Return default fee tier when protocol is empty
+      if (this.isZeroSupplyError(error)) {
+        return {
+          minCR: 0n,
+          apUSDMintFee: 0,
+          apUSDRedeemFee: 0,
+          xBNBMintFee: 0,
+          xBNBRedeemFee: 0,
+          apUSDMintDisabled: false,
+          currentCR: 0n,
+        };
+      }
+      throw error;
+    }
+  }
+
+  async getMaxPriceAge(): Promise<bigint> {
+    return this.publicClient.readContract({
+      address: this.diamondAddress,
+      abi: DiamondABI,
+      functionName: "getMaxPriceAge",
+    });
+  }
+
+  async getMinDepositPeriod(): Promise<bigint> {
+    return this.publicClient.readContract({
+      address: this.diamondAddress,
+      abi: DiamondABI,
+      functionName: "getMinDepositPeriod",
+    });
+  }
+
+  async isPaused(): Promise<boolean> {
+    return this.publicClient.readContract({
+      address: this.diamondAddress,
+      abi: DiamondABI,
+      functionName: "isPaused",
+    });
+  }
+
+  // ============ Stability Mode View Functions ============
+
+  async getStabilityMode(): Promise<StabilityModeInfo> {
+    try {
+      const result = await this.publicClient.readContract({
+        address: this.diamondAddress,
+        abi: DiamondABI,
+        functionName: "getStabilityMode",
+      });
+
+      return {
+        mode: result[0],
+        currentCR: result[1],
+      };
+    } catch (error) {
+      // Return normal mode when protocol is empty
+      if (this.isZeroSupplyError(error)) {
+        return {
+          mode: 0, // Normal mode
+          currentCR: 0n,
+        };
+      }
+      throw error;
+    }
+  }
+
+  async canTriggerStabilityMode2(): Promise<StabilityMode2Info> {
+    try {
+      const result = await this.publicClient.readContract({
+        address: this.diamondAddress,
+        abi: DiamondABI,
+        functionName: "canTriggerStabilityMode2",
+      });
+
+      return {
+        canTrigger: result[0],
+        currentCR: result[1],
+        potentialConversion: result[2],
+      };
+    } catch (error) {
+      // Cannot trigger when protocol is empty
+      if (this.isZeroSupplyError(error)) {
+        return {
+          canTrigger: false,
+          currentCR: 0n,
+          potentialConversion: 0n,
+        };
+      }
+      throw error;
+    }
+  }
+
+  // ============ Ownership View Functions ============
+
+  async getOwner(): Promise<Address> {
+    return this.publicClient.readContract({
+      address: this.diamondAddress,
+      abi: DiamondABI,
+      functionName: "owner",
+    });
+  }
+}
+
+// ============ Write Client ============
+
+/**
+ * Full client with write capabilities for interacting with Aspan Protocol
+ */
+export class AspanClient extends AspanReadClient {
+  private readonly walletClient: WalletClient<Transport, Chain, Account>;
+
+  constructor(config: AspanWriteClientConfig) {
+    super(config);
+
+    this.walletClient = createWalletClient({
+      account: config.account,
+      chain: this.chain,
+      transport: http(config.rpcUrl),
+    });
+  }
+
+  // ============ Pool Write Functions ============
+
+  /**
+   * Mint apUSD by depositing LST
+   * @param params Mint parameters
+   * @returns Transaction hash
+   */
+  async mintApUSD(params: MintApUSDParams): Promise<Hash> {
+    return this.walletClient.writeContract({
+      address: this.diamondAddress,
+      abi: DiamondABI,
+      functionName: "mintApUSD",
+      args: [params.lstToken, params.lstAmount],
+    });
+  }
+
+  /**
+   * Redeem apUSD for LST
+   * @param params Redeem parameters
+   * @returns Transaction hash
+   */
+  async redeemApUSD(params: RedeemApUSDParams): Promise<Hash> {
+    return this.walletClient.writeContract({
+      address: this.diamondAddress,
+      abi: DiamondABI,
+      functionName: "redeemApUSD",
+      args: [params.lstToken, params.apUSDAmount],
+    });
+  }
+
+  /**
+   * Mint xBNB by depositing LST
+   * @param params Mint parameters
+   * @returns Transaction hash
+   */
+  async mintXBNB(params: MintXBNBParams): Promise<Hash> {
+    return this.walletClient.writeContract({
+      address: this.diamondAddress,
+      abi: DiamondABI,
+      functionName: "mintXBNB",
+      args: [params.lstToken, params.lstAmount],
+    });
+  }
+
+  /**
+   * Redeem xBNB for LST
+   * @param params Redeem parameters
+   * @returns Transaction hash
+   */
+  async redeemXBNB(params: RedeemXBNBParams): Promise<Hash> {
+    return this.walletClient.writeContract({
+      address: this.diamondAddress,
+      abi: DiamondABI,
+      functionName: "redeemXBNB",
+      args: [params.lstToken, params.xBNBAmount],
+    });
+  }
+
+  // ============ Stability Pool Write Functions ============
+
+  /**
+   * Deposit apUSD to stability pool to earn yield
+   * @param params Deposit parameters
+   * @returns Transaction hash
+   */
+  async deposit(params: DepositParams): Promise<Hash> {
+    return this.walletClient.writeContract({
+      address: this.diamondAddress,
+      abi: DiamondABI,
+      functionName: "deposit",
+      args: [params.apUSDAmount],
+    });
+  }
+
+  /**
+   * Withdraw from stability pool by shares
+   * @param params Withdraw parameters
+   * @returns Transaction hash
+   */
+  async withdraw(params: WithdrawParams): Promise<Hash> {
+    return this.walletClient.writeContract({
+      address: this.diamondAddress,
+      abi: DiamondABI,
+      functionName: "withdraw",
+      args: [params.shares],
+    });
+  }
+
+  /**
+   * Withdraw from stability pool by asset amount
+   * @param params Withdraw parameters
+   * @returns Transaction hash
+   */
+  async withdrawAssets(params: WithdrawAssetsParams): Promise<Hash> {
+    return this.walletClient.writeContract({
+      address: this.diamondAddress,
+      abi: DiamondABI,
+      functionName: "withdrawAssets",
+      args: [params.assets],
+    });
+  }
+
+  /**
+   * Harvest yield from LSTs
+   * @returns Transaction hash
+   */
+  async harvestYield(): Promise<Hash> {
+    return this.walletClient.writeContract({
+      address: this.diamondAddress,
+      abi: DiamondABI,
+      functionName: "harvestYield",
+    });
+  }
+
+  // ============ Transaction Helpers ============
+
+  /**
+   * Wait for transaction confirmation
+   * @param hash Transaction hash
+   * @returns Transaction receipt
+   */
+  async waitForTransaction(hash: Hash) {
+    return this.publicClient.waitForTransactionReceipt({ hash });
+  }
+}
+
+// ============ Factory Functions ============
+
+/**
+ * Create a read-only client for BSC mainnet
+ */
+export function createAspanReadClient(
+  diamondAddress: Address,
+  rpcUrl?: string
+): AspanReadClient {
+  return new AspanReadClient({
+    diamondAddress,
+    chain: bsc,
+    rpcUrl,
+  });
+}
+
+/**
+ * Create a full client for BSC mainnet
+ */
+export function createAspanClient(
+  diamondAddress: Address,
+  account: Account,
+  rpcUrl?: string
+): AspanClient {
+  return new AspanClient({
+    diamondAddress,
+    account,
+    chain: bsc,
+    rpcUrl,
+  });
+}
+
+/**
+ * Create a read-only client for BSC testnet
+ */
+export function createAspanTestnetReadClient(
+  diamondAddress: Address,
+  rpcUrl?: string
+): AspanReadClient {
+  return new AspanReadClient({
+    diamondAddress,
+    chain: bscTestnet,
+    rpcUrl,
+  });
+}
+
+/**
+ * Create a full client for BSC testnet
+ */
+export function createAspanTestnetClient(
+  diamondAddress: Address,
+  account: Account,
+  rpcUrl?: string
+): AspanClient {
+  return new AspanClient({
+    diamondAddress,
+    account,
+    chain: bscTestnet,
+    rpcUrl,
+  });
+}