@scallop-io/sui-scallop-sdk 0.37.3

package/src/models/scallopClient.ts

@@ -0,0 +1,461 @@
+import { normalizeSuiAddress } from '@mysten/sui.js';
+import { SuiKit } from '@scallop-io/sui-kit';
+import { ScallopAddress } from './scallopAddress';
+import { ScallopUtils } from './scallopUtils';
+import { newScallopTxBlock } from '../txBuilders';
+import { queryObligation, queryMarket, getObligations } from '../queries';
+import type {
+  TransactionArgument,
+  SuiTransactionBlockResponse,
+} from '@mysten/sui.js';
+import type { SuiTxArg } from '@scallop-io/sui-kit';
+import type {
+  ScallopClientFnReturnType,
+  ScallopParams,
+  SupportAssetCoins,
+  SupportCollateralCoins,
+  SupportCoins,
+  ScallopTxBlock,
+} from '../types';
+
+/**
+ * ### Scallop Client
+ *
+ * it provides contract interaction operations for general users.
+ *
+ * #### Usage
+ *
+ * ```typescript
+ * const client  = new Scallop(<parameters>);
+ * client.<interact functions>();
+ * ```
+ */
+export class ScallopClient {
+  public suiKit: SuiKit;
+  public address: ScallopAddress;
+  public walletAddress: string;
+
+  private readonly _utils: ScallopUtils;
+  private readonly _isTestnet: boolean;
+
+  public constructor(
+    params: ScallopParams,
+    address: ScallopAddress,
+    walletAddress?: string,
+    isTestnet?: boolean
+  ) {
+    this.suiKit = new SuiKit(params);
+    this.address = address;
+    this.walletAddress = normalizeSuiAddress(
+      walletAddress || this.suiKit.currentAddress()
+    );
+    this._utils = new ScallopUtils(params);
+    this._isTestnet =
+      isTestnet ||
+      (params.networkType ? params.networkType === 'testnet' : false);
+  }
+
+  createTxBlock() {
+    return newScallopTxBlock(
+      this.suiKit,
+      this.address,
+      this._utils,
+      this._isTestnet
+    );
+  }
+
+  /**
+   * Query market data.
+   *
+   * @return Market data
+   */
+  public async queryMarket() {
+    return queryMarket(this.address, this.suiKit);
+  }
+
+  /**
+   * Query obligations data.
+   *
+   * @param ownerAddress - The owner address.
+   * @return Obligations data
+   */
+  async getObligations(ownerAddress?: string) {
+    const owner = ownerAddress || this.walletAddress;
+    return getObligations(owner, this.address, this.suiKit);
+  }
+
+  /**
+   * Query obligation data.
+   *
+   * @param obligationId - The obligation id from protocol package.
+   * @return Obligation data
+   */
+  public async queryObligation(obligationId: string) {
+    return queryObligation(obligationId, this.address, this.suiKit);
+  }
+
+  /**
+   * Open obligation.
+   *
+   * @param sign - Decide to directly sign the transaction or return the transaction block.
+   * @return Transaction block response or transaction block
+   */
+  public async openObligation(): Promise<SuiTransactionBlockResponse>;
+  public async openObligation<S extends boolean>(
+    sign?: S
+  ): Promise<ScallopClientFnReturnType<S>>;
+  public async openObligation<S extends boolean>(
+    sign: S = true as S
+  ): Promise<ScallopClientFnReturnType<S>> {
+    const txBlock = this.createTxBlock();
+    txBlock.openObligationEntry();
+    if (sign) {
+      return (await this.suiKit.signAndSendTxn(
+        txBlock
+      )) as ScallopClientFnReturnType<S>;
+    } else {
+      return txBlock.txBlock as ScallopClientFnReturnType<S>;
+    }
+  }
+
+  /**
+   * Deposit collateral into the specific pool.
+   *
+   * @param coinName - Types of collateral coin.
+   * @param amount - The amount of coins would deposit.
+   * @param sign - Decide to directly sign the transaction or return the transaction block.
+   * @param obligationId - The obligation object.
+   * @param walletAddress - The wallet address of the owner.
+   * @return Transaction block response or transaction block
+   */
+  public async depositCollateral(
+    coinName: SupportCollateralCoins,
+    amount: number
+  ): Promise<SuiTransactionBlockResponse>;
+  public async depositCollateral<S extends boolean>(
+    coinName: SupportCollateralCoins,
+    amount: number,
+    sign?: S,
+    obligationId?: SuiTxArg,
+    walletAddress?: string
+  ): Promise<ScallopClientFnReturnType<S>>;
+  public async depositCollateral<S extends boolean>(
+    coinName: SupportCollateralCoins,
+    amount: number,
+    sign: S = true as S,
+    obligationId?: SuiTxArg,
+    walletAddress?: string
+  ): Promise<ScallopClientFnReturnType<S>> {
+    const txBlock = this.createTxBlock();
+    const sender = walletAddress || this.walletAddress;
+    txBlock.setSender(sender);
+
+    if (obligationId) {
+      await txBlock.addCollateralQuick(amount, coinName, obligationId);
+    } else {
+      const [obligation, obligationKey, hotPotato] = txBlock.openObligation();
+      await txBlock.addCollateralQuick(amount, coinName, obligation);
+      txBlock.returnObligation(obligation, hotPotato);
+      txBlock.transferObjects([obligationKey], sender);
+    }
+
+    if (sign) {
+      return (await this.suiKit.signAndSendTxn(
+        txBlock
+      )) as ScallopClientFnReturnType<S>;
+    } else {
+      return txBlock.txBlock as ScallopClientFnReturnType<S>;
+    }
+  }
+
+  /**
+   * Withdraw collateral from the specific pool.
+   *
+   * @param coinName - Types of collateral coin.
+   * @param amount - The amount of coins would deposit.
+   * @param sign - Decide to directly sign the transaction or return the transaction block.
+   * @param obligationId - The obligation object.
+   * @param obligationKey - The obligation key object to verifying obligation authority.
+   * @param walletAddress - The wallet address of the owner.
+   * @return Transaction block response or transaction block
+   */
+  public async withdrawCollateral<S extends boolean>(
+    coinName: SupportCollateralCoins,
+    amount: number,
+    sign: S = true as S,
+    obligationId: string,
+    obligationKey: string,
+    walletAddress?: string
+  ): Promise<ScallopClientFnReturnType<S>> {
+    const txBlock = this.createTxBlock();
+    const sender = walletAddress || this.walletAddress;
+    txBlock.setSender(sender);
+
+    const collateralCoin = await txBlock.takeCollateralQuick(
+      amount,
+      coinName,
+      obligationId,
+      obligationKey
+    );
+    txBlock.transferObjects([collateralCoin], sender);
+
+    if (sign) {
+      return (await this.suiKit.signAndSendTxn(
+        txBlock
+      )) as ScallopClientFnReturnType<S>;
+    } else {
+      return txBlock.txBlock as ScallopClientFnReturnType<S>;
+    }
+  }
+
+  /**
+   * Deposit asset into the specific pool.
+   *
+   * @param coinName - Types of asset coin.
+   * @param amount - The amount of coins would deposit.
+   * @param sign - Decide to directly sign the transaction or return the transaction block.
+   * @param walletAddress - The wallet address of the owner.
+   * @return Transaction block response or transaction block
+   */
+  public async deposit(
+    coinName: SupportAssetCoins,
+    amount: number
+  ): Promise<SuiTransactionBlockResponse>;
+  public async deposit<S extends boolean>(
+    coinName: SupportAssetCoins,
+    amount: number,
+    sign?: S,
+    walletAddress?: string
+  ): Promise<ScallopClientFnReturnType<S>>;
+  public async deposit<S extends boolean>(
+    coinName: SupportAssetCoins,
+    amount: number,
+    sign: S = true as S,
+    walletAddress?: string
+  ): Promise<ScallopClientFnReturnType<S>> {
+    const txBlock = this.createTxBlock();
+    const sender = walletAddress || this.walletAddress;
+    txBlock.setSender(sender);
+
+    const marketCoin = await txBlock.depositQuick(amount, coinName);
+    txBlock.transferObjects([marketCoin], sender);
+
+    if (sign) {
+      return (await this.suiKit.signAndSendTxn(
+        txBlock
+      )) as ScallopClientFnReturnType<S>;
+    } else {
+      return txBlock.txBlock as ScallopClientFnReturnType<S>;
+    }
+  }
+
+  /**
+   * Withdraw asset from the specific pool, must return market coin.
+   *
+   * @param coinName - Types of asset coin.
+   * @param amount - The amount of coins would withdraw.
+   * @param sign - Decide to directly sign the transaction or return the transaction block.
+   * @param walletAddress - The wallet address of the owner.
+   * @return Transaction block response or transaction block
+   */
+  public async withdraw(
+    coinName: SupportAssetCoins,
+    amount: number
+  ): Promise<SuiTransactionBlockResponse>;
+  public async withdraw<S extends boolean>(
+    coinName: SupportAssetCoins,
+    amount: number,
+    sign?: S,
+    walletAddress?: string
+  ): Promise<ScallopClientFnReturnType<S>>;
+  public async withdraw<S extends boolean>(
+    coinName: SupportAssetCoins,
+    amount: number,
+    sign: S = true as S,
+    walletAddress?: string
+  ): Promise<ScallopClientFnReturnType<S>> {
+    const txBlock = this.createTxBlock();
+    const sender = walletAddress || this.walletAddress;
+    txBlock.setSender(sender);
+
+    const coin = await txBlock.withdrawQuick(amount, coinName);
+    txBlock.transferObjects([coin], sender);
+
+    if (sign) {
+      return (await this.suiKit.signAndSendTxn(
+        txBlock
+      )) as ScallopClientFnReturnType<S>;
+    } else {
+      return txBlock.txBlock as ScallopClientFnReturnType<S>;
+    }
+  }
+
+  /**
+   * borrow asset from the specific pool.
+   *
+   * @param coinName - Types of asset coin.
+   * @param amount - The amount of coins would borrow.
+   * @param sign - Decide to directly sign the transaction or return the transaction block.
+   * @param obligationId - The obligation object.
+   * @param obligationKey - The obligation key object to verifying obligation authority.
+   * @param walletAddress - The wallet address of the owner.
+   * @return Transaction block response or transaction block
+   */
+  public async borrow<S extends boolean>(
+    coinName: SupportAssetCoins,
+    amount: number,
+    sign: S = true as S,
+    obligationId: string,
+    obligationKey: string,
+    walletAddress?: string
+  ): Promise<ScallopClientFnReturnType<S>> {
+    const txBlock = this.createTxBlock();
+    const sender = walletAddress || this.walletAddress;
+    txBlock.setSender(sender);
+
+    const coin = await txBlock.borrowQuick(
+      amount,
+      coinName,
+      obligationId,
+      obligationKey
+    );
+    txBlock.transferObjects([coin], sender);
+
+    if (sign) {
+      return (await this.suiKit.signAndSendTxn(
+        txBlock
+      )) as ScallopClientFnReturnType<S>;
+    } else {
+      return txBlock.txBlock as ScallopClientFnReturnType<S>;
+    }
+  }
+
+  /**
+   * Repay asset into the specific pool.
+   *
+   * @param coinName - Types of asset coin.
+   * @param amount - The amount of coins would repay.
+   * @param sign - Decide to directly sign the transaction or return the transaction block.
+   * @param obligationId - The obligation object.
+   * @param walletAddress - The wallet address of the owner.
+   * @return Transaction block response or transaction block
+   */
+  public async repay<S extends boolean>(
+    coinName: SupportAssetCoins,
+    amount: number,
+    sign: S = true as S,
+    obligationId: string,
+    walletAddress?: string
+  ): Promise<ScallopClientFnReturnType<S>> {
+    const txBlock = this.createTxBlock();
+    const sender = walletAddress || this.walletAddress;
+    txBlock.setSender(sender);
+
+    await txBlock.repayQuick(amount, coinName, obligationId);
+
+    if (sign) {
+      return (await this.suiKit.signAndSendTxn(
+        txBlock
+      )) as ScallopClientFnReturnType<S>;
+    } else {
+      return txBlock.txBlock as ScallopClientFnReturnType<S>;
+    }
+  }
+
+  /**
+   * FlashLoan asset from the specific pool.
+   *
+   * @param coinName - Types of asset coin.
+   * @param amount - The amount of coins would repay.
+   * @param callback - The callback function to build transaction block and return coin argument.
+   * @param sign - Decide to directly sign the transaction or return the transaction block.
+   * @return Transaction block response or transaction block
+   */
+  public async flashLoan(
+    coinName: SupportAssetCoins,
+    amount: number,
+    callback: (
+      txBlock: ScallopTxBlock,
+      coin: TransactionArgument
+    ) => TransactionArgument
+  ): Promise<SuiTransactionBlockResponse>;
+  public async flashLoan<S extends boolean>(
+    coinName: SupportAssetCoins,
+    amount: number,
+    callback: (
+      txBlock: ScallopTxBlock,
+      coin: TransactionArgument
+    ) => TransactionArgument,
+    sign?: S
+  ): Promise<ScallopClientFnReturnType<S>>;
+  public async flashLoan<S extends boolean>(
+    coinName: SupportAssetCoins,
+    amount: number,
+    callback: (
+      txBlock: ScallopTxBlock,
+      coin: TransactionArgument
+    ) => TransactionArgument,
+    sign: S = true as S
+  ): Promise<ScallopClientFnReturnType<S>> {
+    const txBlock = this.createTxBlock();
+    const [coin, loan] = txBlock.borrowFlashLoan(amount, coinName);
+    txBlock.repayFlashLoan(callback(txBlock, coin), loan, coinName);
+
+    if (sign) {
+      return (await this.suiKit.signAndSendTxn(
+        txBlock
+      )) as ScallopClientFnReturnType<S>;
+    } else {
+      return txBlock.txBlock as ScallopClientFnReturnType<S>;
+    }
+  }
+
+  /**
+   * Mint and get test coin.
+   *
+   * @remarks
+   *  Only be used on the test network.
+   *
+   * @param coinName - Types of coins supported on the test network.
+   * @param amount - The amount of coins minted and received.
+   * @param receiveAddress - The wallet address that receives the coins.
+   * @param sign - Decide to directly sign the transaction or return the transaction block.
+   * @return Transaction block response or transaction block
+   */
+  public async mintTestCoin(
+    coinName: Exclude<SupportCoins, 'sui'>,
+    amount: number
+  ): Promise<SuiTransactionBlockResponse>;
+  public async mintTestCoin<S extends boolean>(
+    coinName: Exclude<SupportCoins, 'sui'>,
+    amount: number,
+    sign?: S,
+    receiveAddress?: string
+  ): Promise<ScallopClientFnReturnType<S>>;
+  public async mintTestCoin<S extends boolean>(
+    coinName: Exclude<SupportCoins, 'sui'>,
+    amount: number,
+    sign: S = true as S,
+    receiveAddress?: string
+  ): Promise<ScallopClientFnReturnType<S>> {
+    if (!this._isTestnet) {
+      throw new Error('Only be used on the test network.');
+    }
+
+    const txBlock = this.createTxBlock();
+    const recipient = receiveAddress || this.walletAddress;
+    const packageId = this.address.get('core.packages.testCoin.id');
+    const treasuryId = this.address.get(`core.coins.${coinName}.treasury`);
+    const target = `${packageId}::${coinName}::mint`;
+    const coin = txBlock.moveCall(target, [treasuryId, amount]);
+    txBlock.transferObjects([coin], recipient);
+
+    if (sign) {
+      return (await this.suiKit.signAndSendTxn(
+        txBlock
+      )) as ScallopClientFnReturnType<S>;
+    } else {
+      return txBlock.txBlock as ScallopClientFnReturnType<S>;
+    }
+  }
+}

package/src/models/scallopUtils.ts

@@ -0,0 +1,133 @@
+import {
+  SUI_FRAMEWORK_ADDRESS,
+  SUI_TYPE_ARG,
+  normalizeStructTag,
+} from '@mysten/sui.js';
+import { SuiKit } from '@scallop-io/sui-kit';
+import { PriceServiceConnection } from '@pythnetwork/price-service-client';
+import type { ScallopParams, SupportCoins } from '../types';
+
+/**
+ * ### Scallop Utils
+ *
+ * Integrates some helper functions frequently used in interactions with the Scallop contract.
+ *
+ * #### Usage
+ *
+ * ```typescript
+ * const utils  = new ScallopUtils(<parameters>);
+ * utils.<help functions>();
+ * ```
+ */
+export class ScallopUtils {
+  private _suiKit: SuiKit;
+
+  public constructor(params: ScallopParams) {
+    this._suiKit = new SuiKit(params);
+  }
+
+  /**
+   * @description Select coin id  that add up to the given amount as transaction arguments.
+   * @param owner The address of the owner.
+   * @param amount The amount that is needed for the coin.
+   * @param coinType The coin type, default is 0x2::SUI::SUI.
+   * @return The selected transaction coin arguments.
+   */
+  public async selectCoins(
+    owner: string,
+    amount: number,
+    coinType: string = SUI_TYPE_ARG
+  ) {
+    const coins = await this._suiKit.rpcProvider.selectCoins(
+      owner,
+      amount,
+      coinType
+    );
+    return coins.map((c) => c.objectId);
+  }
+
+  /**
+   * @description Fetch price feed VAAs of interest from the Pyth.
+   * @param priceIds Array of hex-encoded price ids.
+   * @param isTestnet Specify whether it is a test network.
+   * @return Array of base64 encoded VAAs.
+   */
+  public async getVaas(priceIds: string[], isTestnet?: boolean) {
+    const connection = new PriceServiceConnection(
+      isTestnet
+        ? 'https://xc-testnet.pyth.network'
+        : 'https://xc-mainnet.pyth.network',
+      {
+        priceFeedRequestConfig: {
+          binary: true,
+        },
+      }
+    );
+    return await connection.getLatestVaas(priceIds);
+  }
+
+  /**
+   * @description Handle non-standard coins.
+   * @param coinPackageId Package id of coin.
+   * @param coinName specific support coin name.
+   * @return coinType.
+   */
+  public parseCoinType(coinPackageId: string, coinName: string) {
+    if (coinName === 'sui') return normalizeStructTag(SUI_TYPE_ARG);
+    const wormHoleCoins = [
+      // USDC
+      '0x5d4b302506645c37ff133b98c4b50a5ae14841659738d6d733d59d0d217a93bf',
+      // USDT
+      '0xc060006111016b8a020ad5b33834984a437aaa7d3c74c18e09a95d48aceab08c',
+    ];
+    if (wormHoleCoins.includes(coinPackageId)) {
+      return `${coinPackageId}::coin::COIN`;
+    } else {
+      return `${coinPackageId}::${coinName}::${coinName.toUpperCase()}`;
+    }
+  }
+
+  /**
+   * @description Handle non-standard coin names.
+   * @param coinPackageId Package id of coin.
+   * @param coinName specific support coin name.
+   * @return coinType.
+   */
+  public getCoinNameFromCoinType(coinType: string) {
+    const wormHoleCoinTypes = [
+      // USDC
+      '0x5d4b302506645c37ff133b98c4b50a5ae14841659738d6d733d59d0d217a93bf::coin::COIN',
+      // USDT
+      '0xc060006111016b8a020ad5b33834984a437aaa7d3c74c18e09a95d48aceab08c::coin::COIN',
+    ];
+
+    if (coinType === wormHoleCoinTypes[0]) {
+      return 'usdc';
+    } else if (coinType === wormHoleCoinTypes[1]) {
+      return 'usdt';
+    } else {
+      return coinType.split('::')[2].toLowerCase() as SupportCoins;
+    }
+  }
+
+  /**
+   * @description Handle market coin types.
+   *
+   * @param coinPackageId Package id of coin.
+   * @param protocolPkgId Package id of protocol.
+   * @param coinName specific support coin name.
+   *
+   * @return marketCoinType.
+   */
+  public parseMarketCoinType(
+    coinPackageId: string,
+    protocolPkgId: string,
+    coinName: string
+  ) {
+    const coinType = this.parseCoinType(
+      coinName === 'sui' ? SUI_FRAMEWORK_ADDRESS : coinPackageId,
+      coinName
+    );
+    return `${protocolPkgId}::reserve::MarketCoin<${coinType}>`;
+  }
+}

package/src/queries/index.ts

@@ -0,0 +1,2 @@
+export { queryMarket } from './market';
+export { queryObligation, getObligations } from './obligation';

package/src/queries/market.ts

@@ -0,0 +1,16 @@
+import { SuiKit, SuiTxBlock } from '@scallop-io/sui-kit';
+import { ScallopAddress } from '../models';
+import { MarketInterface } from '../types';
+
+export const queryMarket = async (
+  scallopAddress: ScallopAddress,
+  suiKit: SuiKit
+) => {
+  const packageId = scallopAddress.get('core.packages.query.id');
+  const marketId = scallopAddress.get('core.market');
+  const txBlock = new SuiTxBlock();
+  const queryTarget = `${packageId}::market_query::market_data`;
+  txBlock.moveCall(queryTarget, [marketId]);
+  const queryResult = await suiKit.inspectTxn(txBlock);
+  return queryResult.events[0].parsedJson as MarketInterface;
+};

package/src/queries/obligation.ts

@@ -0,0 +1,44 @@
+import { SuiKit, SuiTxBlock } from '@scallop-io/sui-kit';
+import { ScallopAddress } from '../models';
+import { ObligationInterface } from '../types';
+
+export const queryObligation = async (
+  obligationId: string,
+  scallopAddress: ScallopAddress,
+  suiKit: SuiKit
+) => {
+  const packageId = scallopAddress.get('core.packages.query.id');
+  const queryTarget = `${packageId}::obligation_query::obligation_data`;
+  const txBlock = new SuiTxBlock();
+  txBlock.moveCall(queryTarget, [obligationId]);
+  const queryResult = await suiKit.inspectTxn(txBlock);
+  return queryResult.events[0].parsedJson as ObligationInterface;
+};
+
+export const getObligations = async (
+  ownerAddress: string,
+  scallopAddress: ScallopAddress,
+  suiKit: SuiKit
+) => {
+  const owner = ownerAddress || suiKit.currentAddress();
+  const keyObjectRefs = await suiKit.provider().getOwnedObjects({
+    owner,
+    filter: {
+      StructType: `${scallopAddress.get(
+        'core.packages.protocol.id'
+      )}::obligation::ObligationKey`,
+    },
+  });
+  const keyIds = keyObjectRefs.data
+    .map((ref: any) => ref?.data?.objectId)
+    .filter((id: any) => id !== undefined) as string[];
+  const keyObjects = await suiKit.getObjects(keyIds);
+  const obligations: { id: string; keyId: string }[] = [];
+  for (const keyObject of keyObjects) {
+    const keyId = keyObject.objectId;
+    const fields = keyObject.objectFields as any;
+    const obligationId = fields['ownership']['fields']['of'];
+    obligations.push({ id: obligationId, keyId });
+  }
+  return obligations;
+};

package/src/txBuilders/coin.ts

@@ -0,0 +1,38 @@
+import { SuiTxBlock } from '@scallop-io/sui-kit';
+import { ScallopAddress, ScallopUtils } from '../models';
+import { SupportCoins } from '../types';
+
+export const selectCoin = async (
+  txBlock: SuiTxBlock,
+  scallopAddress: ScallopAddress,
+  scallopUtils: ScallopUtils,
+  coinName: SupportCoins,
+  amount: number,
+  sender: string
+) => {
+  const coinPackageId = scallopAddress.get(`core.coins.${coinName}.id`);
+  const coinType = scallopUtils.parseCoinType(coinPackageId, coinName);
+  const coins = await scallopUtils.selectCoins(sender, amount, coinType);
+  const [takeCoin, leftCoin] = txBlock.takeAmountFromCoins(coins, amount);
+  return { takeCoin, leftCoin };
+};
+
+export const selectMarketCoin = async (
+  txBlock: SuiTxBlock,
+  scallopAddress: ScallopAddress,
+  scallopUtils: ScallopUtils,
+  coinName: SupportCoins,
+  amount: number,
+  sender: string
+) => {
+  const coinPackageId = scallopAddress.get(`core.coins.${coinName}.id`);
+  const protocolPackageId = scallopAddress.get('core.packages.protocol.id');
+  const coinType = scallopUtils.parseMarketCoinType(
+    coinPackageId,
+    protocolPackageId,
+    coinName
+  );
+  const coins = await scallopUtils.selectCoins(sender, amount, coinType);
+  const [takeCoin, leftCoin] = txBlock.takeAmountFromCoins(coins, amount);
+  return { takeCoin, leftCoin };
+};

package/src/txBuilders/index.ts

@@ -0,0 +1 @@
+export { newScallopTxBlock } from './quickMethods';