@cetusprotocol/xcetus-sdk 1.0.0

package/README.md

@@ -0,0 +1,276 @@
+# @cetusprotocol/xcetus-sdk
+
+## xCETUS Overview
+
+**Platform equity tokens** are non-circulating currencies and cannot be transferred by default. These tokens are recorded in the user's **veNFT** account as points.
+
+### How to Obtain xCETUS:
+
+1. **Convert 1 CETUS to 1 xCETUS Mint**
+2. **LP NFT lock-up mining rewards** released.
+
+### Transfer of xCETUS:
+
+- xCETUS can be transferred under certain conditions.
+- To prevent special circumstances, only the platform has the permission to transfer xCETUS.
+
+---
+
+## veNFT Overview
+
+**veNFT** stores xCETUS in a **non-transferable** form under the user account.
+
+### Benefits of Holding xCETUS:
+
+- Holding xCETUS allows participation in **Cetus reward dividends**.
+- Dividends are distributed based on the proportion of xCETUS in the wallet's veNFT account relative to the total xCETUS in the market.
+
+## Getting Started
+
+## How to Use the Burn SDK ?
+
+## Installation
+
+To start using the `xcetus SDK`, you first need to install it in your TypeScript project:
+
+Github Link: https://github.com/CetusProtocol/xcetus-sdk
+
+NPM Link: [@cetusprotocol/xcetus-sdk](https://www.npmjs.com/package/@cetusprotocol/xcetus-sdk)
+
+```bash
+npm install @cetusprotocol/xcetus-sdk
+```
+
+### Setup
+
+Import the SDK into the TypeScript file where you intend to use it:
+
+```typescript
+import { CetusXcetusSDK } from '@cetusprotocol/xcetus-sdk'
+```
+
+### Initializing the SDK
+
+Initialize the SDK with the required configuration parameters. This typically includes setting up the network and API keys, if needed.
+
+If you would like to use the mainnet network and the official Sui rpc url, you can do so as follows:
+
+```typescript
+const sdk = CetusXcetusSDK.createSDK()
+```
+
+If you wish to set your own full node URL or network (You have the option to select either 'mainnet' or 'testnet' for the network), you can do so as follows:
+
+```typescript
+const env = 'mainnet'
+const full_rpc_url = 'YOUR_FULL_NODE_URL'
+const wallet = 'YOUR_WALLET_ADDRESS'
+
+const sdk = CetusXcetusSDK.createSDK({ env })
+```
+
+If you wish to set your own full node URL or SuiClient, you can do so as follows:
+
+```typescript
+const sdk = CetusXcetusSDK.createSDK({ env, sui_client })
+// or
+const sdk = CetusXcetusSDK.createSDK({ env, full_rpc_url })
+```
+
+## Usage
+
+After linking your wallet, if you need use your wallet address to do something, you should set it by `sdk.setSenderAddress`.
+
+```typescript
+const wallet = 'YOUR_WALLET_ADDRESS'
+sdk.setSenderAddress(wallet)
+```
+
+### 1. getOwnerVeNFT
+
+Gets the VeNFT object for the specified account address.
+
+```typescript
+const owner_venft = await sdk.XCetusModule.getOwnerVeNFT(wallet)
+  // ownerVeNFT
+    {
+        creator: 'Cetus',
+        description: "A non-transferrable NFT storing Cetus Escrowed Token xCETUS that represents a user's governance power on Cetus Protocol.",
+        image_url: 'https://x77unmxbojk6nincdlzd57hhk5qgp5223rrrxrsplqqcs23vu5ja.arweave.net/v_9GsuFyVeahohryPvznV2Bn91rcYxvGT1wgKWt1p1I',
+        link: 'https://app.cetus.zone',
+        name: 'Cetus veNFT #14562',
+        project_url: 'https://www.cetus.zone',
+        id: '0x12adbc7e726cf2a5a9d4c4f0bdd08b6a49c876be99b2e650778a68d3891584bc',
+        index: '14562',
+        type: '0x9e69acc50ca03bc943c4f7c5304c2a6002d507b51c11913b247159c60422c606::xcetus::VeNFT',
+        xcetus_balance: '1000000000'
+    }
+
+```
+
+### 2. getOwnerRedeemLockList.
+
+Gets the list of LockCetus objects owned by the specified account address.
+
+```typescript
+const redeem_lock_list = await sdk.XCetusModule.getOwnerRedeemLockList(wallet)
+
+redeem_lock_list: [
+  {
+    id: '0x005ba9202a5d9e41c73155a1b4e47...',
+    type: '0x9e69acc50ca03bc943c4f7c5304c2a6002d507b51c11913b247159c60422c606::lock_coin::LockedCoin<0x06864a6f921804860930db6ddbe2e16acdf8504495ea7481637a1c8b9a8fe54b::cetus::CETUS>',
+    locked_start_time: 1730442744,
+    locked_until_time: 1745994744,
+    cetus_amount: '500000000',
+    xcetus_amount: '500000000',
+    lock_day: 180,
+  },
+]
+```
+
+### 3. Convert Cetus to Xcetus
+
+```typescript
+const venft_id = 'YOUR_VENFT_ID'
+const payload = await sdk.XCetusModule.convertPayload({
+  amount: '10000000000',
+  venft_id,
+})
+```
+
+### 4. redeemLock
+
+```typescript
+const lock_day = 15
+const amount_input = 20000
+const amount = await sdk.XCetusModule.redeemNum(amount_input, lock_day)
+sdk.XCetusModule.redeemLockPayload({
+  venft_id,
+  amount,
+  lock_day,
+})
+```
+
+### 5. redeem
+
+```typescript
+const lock_id = '0x005ba9202a5d9e41c73155a1b4e47...'
+const lock_cetus = await sdk.XCetusModule.getLockCetus(lock_id)
+
+if (lock_cetus && !XCetusUtil.isLocked(lock_cetus)) {
+  const payload = sdk.XCetusModule.redeemPayload({
+    venft_id,
+    lock_id,
+  })
+}
+```
+
+### 6.redeemDividendV3Payload
+
+```typescript
+const venft_dividend_info = await sdk.XCetusModule.getVeNFTDividendInfo(venft_id)
+
+if (venft_dividend_info) {
+  const payload = await sdk.XCetusModule.redeemDividendV3Payload(venft_id, venft_dividend_info.rewards)
+}
+```
+
+### 7. cancelRedeemPayload
+
+```typescript
+const lock_id = '0x005ba9202a5d9e41c73155a1...'
+const lock_cetus = await sdk.XCetusModule.getLockCetus(lock_id)
+
+if (lock_cetus && XCetusUtil.isLocked(lock_cetus)) {
+  const payload = sdk.XCetusModule.cancelRedeemPayload({
+    venft_id,
+    lock_id,
+  })
+}
+```
+
+### 7. getVeNFTDividendInfo
+
+```typescript
+const dividend_manager = await sdk.XCetusModule.getDividendManager()
+const venft_dividend_info = await sdk.XCetusModule.getVeNFTDividendInfo(dividend_manager.venft_dividends.id)
+```
+
+### 8. redeemNum
+
+```typescript
+const lock_day = 15
+const amount_input = 20000
+const amount = await sdk.XCetusModule.redeemNum(amount_input, lock_day)
+```
+
+### 9. reverseRedeemNum
+
+```typescript
+const lock_day = 15
+const amount_input = 20000
+const amount = await sdk.XCetusModule.reverseRedeemNum(amount_input, lock_day)
+```
+
+### 10. getXCetusAmount
+
+```typescript
+const lock_id = '0x005ba9202a5d9e41c73155a1b...'
+const amount = await sdk.XCetusModule.getXCetusAmount(lock_id)
+```
+
+### 11. getPhaseDividendInfo
+
+```typescript
+const phase_dividend_info = await sdk.XCetusModule.getPhaseDividendInfo('10')
+```
+
+### 12. getXcetusManager & getVeNftAmount
+
+```typescript
+const owner_venft = await sdk.XCetusModule.getOwnerVeNFT(wallet)
+
+if (owner_venft) {
+  const xcetus_manager = await sdk.XCetusModule.getXcetusManager()
+
+  const venft_amount = await sdk.XCetusModule.getVeNftAmount(xcetus_manager.nfts.handle, owner_venft.id)
+
+  const rate = d(owner_venft.xcetus_balance).div(xcetus_manager.treasury)
+}
+```
+
+# Contract Error Codes
+
+the Cetus smart contract may return the following error codes:
+
+| Module    | Error Code | Description                                                                  | Contract Methods                                                    |
+| --------- | ---------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| lock_coin | 0          | The lock time must be greater than the current time                          | lock_coin                                                           |
+| lock_coin | 1          | The lock period has not ended                                                | unlock_coin                                                         |
+| locking   | 1          | Insufficient XCetus balance                                                  | redeem_lock                                                         |
+| locking   | 2          | Locking period for XCetus is out of allowed range                            | redeem_lock                                                         |
+| locking   | 3          | Invalid redeemable XCetus amount                                             | redeem_lock                                                         |
+| locking   | 4          | veNFT does not match the associated LockedCoin                               | cancel_redeem_lock, redeem                                          |
+| locking   | 5          | LockCoin has expired; locking has ended                                      | cancel_redeem_lock                                                  |
+| locking   | 7          | Unauthorized treasury manager                                                | redeem_treasury                                                     |
+| locking   | 8          | The version of the contract has been deprecated                              | The vast majority of methods                                        |
+| xcetus    | 1          | XCetus balance is not zero                                                   | burn_venft                                                          |
+| xcetus    | 5          | The address already has a VeNFT                                              | burn_lp                                                             |
+| xcetus    | 6          | XCetus in unlocking process is not zero                                      | request_transfer_venft_by_admin, approve_transfer_venft, mint_venft |
+| xcetus    | 7          | VeNFT does not exist                                                         | approve_transfer_venft                                              |
+| xcetus    | 8          | Transfer request already exists                                              | request_transfer_venft_by_admin                                     |
+| xcetus    | 9          | Transfer request does not exist                                              | approve_transfer_venft, cancel_transfer_venft_request_by_admin      |
+| xcetus    | 10         | TransferVeNFTRequest does not match the VeNFT                                | approve_transfer_venft                                              |
+| xcetus    | 11         | The destination address is inconsistent with the one in TransferVeNFTRequest | approve_transfer_venft                                              |
+
+# More About Cetus
+
+Use the following links to learn more about Cetus:
+
+Learn more about working with Cetus in the [Cetus Documentation](https://cetus-1.gitbook.io/cetus-docs).
+
+Join the Cetus community on [Cetus Discord](https://discord.com/channels/1009749448022315008/1009751382783447072).
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,356 @@
+import { SuiObjectIdType, SuiAddressType, NFT, IModule, CoinAsset, SdkWrapper, BaseSdkOptions, Package } from '@cetusprotocol/common-sdk';
+import { Transaction } from '@mysten/sui/transactions';
+
+declare const XcetusRouterModule = "router";
+declare const DividendsRouterModule = "router";
+declare const ONE_DAY_SECONDS: number;
+declare const EXCHANGE_RATE_MULTIPLIER = 1000;
+declare const REDEEM_NUM_MULTIPLIER = 100000000000;
+type XcetusConfig = {
+    xcetus_manager_id: SuiObjectIdType;
+    lock_manager_id: SuiObjectIdType;
+    lock_handle_id: SuiObjectIdType;
+};
+type DividendConfig = {
+    dividend_admin_id?: SuiObjectIdType;
+    dividend_settle_id?: SuiObjectIdType;
+    dividend_manager_id: SuiObjectIdType;
+    venft_dividends_id: SuiAddressType;
+    venft_dividends_id_v2: SuiAddressType;
+};
+type LockUpConfig = {
+    min_lock_day: number;
+    max_lock_day: number;
+    max_percent_numerator: number;
+    min_percent_numerator: number;
+};
+declare const defaultLockUpConfig: LockUpConfig;
+type LockUpManager = {
+    id: string;
+    balance: string;
+    treasury_manager: string;
+    extra_treasury: string;
+    lock_infos: {
+        lock_handle_id: string;
+        size: number;
+    };
+    type_name: string;
+    min_lock_day: number;
+    max_lock_day: number;
+    package_version: number;
+    max_percent_numerator: number;
+    min_percent_numerator: number;
+};
+type VeNFT = {
+    id: SuiObjectIdType;
+    type: string;
+    index: string;
+    xcetus_balance: string;
+} & NFT;
+type LockCetus = {
+    id: SuiObjectIdType;
+    type: SuiAddressType;
+    locked_start_time: number;
+    locked_until_time: number;
+    lock_day: number;
+    cetus_amount: string;
+    xcetus_amount: string;
+};
+type ConvertParams = {
+    amount: string;
+    venft_id?: SuiObjectIdType;
+};
+type RedeemLockParams = {
+    amount: string;
+    venft_id: SuiObjectIdType;
+    lock_day: number;
+};
+type RedeemXcetusParams = {
+    venft_id: SuiObjectIdType;
+    lock_id: SuiObjectIdType;
+};
+type CancelRedeemParams = {
+    venft_id: SuiObjectIdType;
+    lock_id: SuiObjectIdType;
+};
+type XcetusManager = {
+    id: SuiObjectIdType;
+    index: number;
+    has_venft: {
+        handle: SuiObjectIdType;
+        size: number;
+    };
+    nfts: {
+        handle: SuiObjectIdType;
+        size: number;
+    };
+    total_locked: string;
+    treasury: string;
+};
+type VeNFTDividendInfo = {
+    id: SuiObjectIdType;
+    venft_id: SuiObjectIdType;
+    rewards: DividendReward[];
+};
+type DividendReward = {
+    period: number;
+    rewards: {
+        coin_type: SuiAddressType;
+        amount: string;
+    }[];
+    version: string;
+};
+type PhaseDividendInfo = {
+    id: string;
+    phase: string;
+    settled_num: string;
+    register_time: string;
+    redeemed_num: {
+        name: string;
+        value: string;
+    }[];
+    is_settled: boolean;
+    bonus_types: string[];
+    bonus: {
+        name: string;
+        value: string;
+    }[];
+    phase_end_time: string;
+};
+type DividendManager = {
+    id: SuiObjectIdType;
+    dividends: {
+        id: SuiObjectIdType;
+        size: number;
+    };
+    venft_dividends: {
+        id: SuiObjectIdType;
+        size: number;
+    };
+    bonus_types: SuiAddressType[];
+    start_time: number;
+    interval_day: number;
+    balances: {
+        id: SuiObjectIdType;
+        size: number;
+    };
+    is_open: boolean;
+};
+type BonusTypesV2 = Record<SuiAddressType, number[]>;
+
+/**
+ * Helper class to help interact with xcetus with a router interface.
+ */
+declare class XCetusModule implements IModule<CetusXcetusSDK> {
+    protected _sdk: CetusXcetusSDK;
+    private readonly _cache;
+    constructor(sdk: CetusXcetusSDK);
+    get sdk(): CetusXcetusSDK;
+    /**
+     * Gets the VeNFT object for the specified account address.
+     *
+     * @param account_address The address of the account that owns the VeNFT object.
+     * @param force_refresh Indicates whether to refresh the cache of the VeNFT object.
+     * @returns A Promise that resolves to the VeNFT object or `undefined` if the object is not found.
+     */
+    getOwnerVeNFT(account_address: SuiAddressType, force_refresh?: boolean): Promise<VeNFT | void>;
+    /**
+     * Gets the list of LockCetus objects owned by the specified account address.
+     *
+     * @param account_address The address of the account that owns the LockCetus objects.
+     * @returns A Promise that resolves to a list of LockCetus objects.
+     */
+    getOwnerRedeemLockList(account_address: SuiAddressType): Promise<LockCetus[]>;
+    /**
+     * Gets the LockCetus object with the specified ID.
+     *
+     * @param lock_id The ID of the LockCetus object.
+     * @returns A Promise that resolves to the LockCetus object or `undefined` if the object is not found.
+     */
+    getLockCetus(lock_id: SuiObjectIdType): Promise<LockCetus | undefined>;
+    /**
+     * Gets the list of Cetus coins owned by the specified account address.
+     *
+     * @param account_address The address of the account that owns the Cetus coins.
+     * @returns A Promise that resolves to a list of CoinAsset objects.
+     */
+    getOwnerCetusCoins(account_address: SuiAddressType): Promise<CoinAsset[]>;
+    /**
+     * mint venft
+     * @returns
+     */
+    mintVeNFTPayload(): Transaction;
+    /**
+     * Convert Cetus to Xcetus.
+     * @param params
+     * @returns
+     */
+    convertPayload(params: ConvertParams, tx?: Transaction): Transaction;
+    /**
+     * Convert Xcetus to Cetus, first step is to lock the Cetus for a period.
+     * When the time is reach, cetus can be redeem and xcetus will be burned.
+     * @param params
+     * @returns
+     */
+    redeemLockPayload(params: RedeemLockParams): Transaction;
+    /**
+     * lock time is reach and the cetus can be redeemed, the xcetus will be burned.
+     * @param params
+     * @returns
+     */
+    redeemPayload(params: RedeemXcetusParams): Transaction;
+    redeemDividendPayload(venft_id: SuiObjectIdType, bonus_types: SuiAddressType[]): Transaction;
+    redeemDividendV2Payload(venft_id: SuiObjectIdType, bonus_types: SuiAddressType[], x_token_type: SuiAddressType[]): Transaction;
+    redeemDividendV3Payload(venft_id: string, reward_list: DividendReward[]): Transaction;
+    redeemDividendXTokenPayload(venft_id: SuiObjectIdType, tx?: Transaction): Transaction;
+    buildCetusCoinType(): SuiAddressType;
+    buildXTokenCoinType(package_id?: string, module?: string, name?: string): SuiAddressType;
+    /**
+     * Cancel the redeem lock, the cetus locked will be return back to the manager and the xcetus will be available again.
+     * @param params
+     * @returns
+     */
+    cancelRedeemPayload(params: CancelRedeemParams): Transaction;
+    /**
+     * Gets the init factory event.
+     *
+     * @returns A Promise that resolves to the init factory event.
+     */
+    getInitConfigs(): Promise<XcetusConfig>;
+    /**
+     * Gets the lock up manager event.
+     *
+     * @returns A Promise that resolves to the lock up manager event.
+     */
+    getLockUpManager(lock_manager_id?: string, force_refresh?: boolean): Promise<LockUpManager>;
+    /**
+     * Gets the dividend manager event.
+     *
+     * @returns A Promise that resolves to the dividend manager event.
+     */
+    getDividendConfigs(): Promise<DividendConfig>;
+    /**
+     * Gets the dividend manager object.
+     *
+     * @param force_refresh Whether to force a refresh of the cache.
+     * @returns A Promise that resolves to the dividend manager object.
+     */
+    getDividendManager(force_refresh?: boolean): Promise<DividendManager>;
+    /**
+     * Gets the Xcetus manager object.
+     *
+     * @returns A Promise that resolves to the Xcetus manager object.
+     */
+    getXcetusManager(force_refresh?: boolean): Promise<XcetusManager>;
+    private fetchDividendInfo;
+    /**
+     * Gets the VeNFT dividend information for the specified VeNFT dividend handle and VeNFT ID.
+     *
+     * @param venft_id The VeNFT ID.
+     * @returns A Promise that resolves to the VeNFT dividend information or undefined if an error occurs.
+     */
+    getVeNFTDividendInfo(venft_id: string): Promise<VeNFTDividendInfo | void>;
+    private getVeNFTDividendInfoV2;
+    private getVeNFTDividendInfoV1;
+    /**
+     * Calculates the redeem number for the specified amount and lock day.
+     *
+     * @param redeem_amount The amount to redeem.
+     * @param lock_day The number of days to lock the amount for.
+     * @returns A Promise that resolves to an object with the amount out and percent.
+     */
+    redeemNum(redeem_amount: string | number, lock_day: number): {
+        amount_out: string;
+        percent: string;
+    };
+    /**
+     * Reverses the redeem number for the specified amount and lock day.
+     *
+     * @param amount The amount to redeem.
+     * @param lock_day The number of days to lock the amount for.
+     * @returns A Promise that resolves to an object with the reversed amount and percent.
+     */
+    reverseRedeemNum(amount: string | number, lock_day: number): {
+        amount_out: string;
+        percent: string;
+    };
+    /**
+     * Gets the XCetus amount for the specified lock ID.
+     *
+     * @param lock_id The ID of the lock.
+     * @returns A Promise that resolves to the XCetus amount.
+     */
+    getXCetusAmount(lock_id: string): Promise<string>;
+    /**
+     * Gets the amount of XCetus and lock for the specified VENFT.
+     *
+     * @param nft_handle_id The ID of the NFT handle.
+     * @param venft_id The ID of the VENFT.
+     * @returns A Promise that resolves to an object with the XCetus amount and lock amount.
+     */
+    getVeNftAmount(nft_handle_id: string, venft_id: string): Promise<{
+        xcetus_amount: string;
+        lock_amount: string;
+    }>;
+    /**
+     * @param phase_handle
+     * @param phase
+     * @param force_refresh
+     * @returns
+     */
+    getPhaseDividendInfo(phase: string, force_refresh?: boolean): Promise<PhaseDividendInfo | undefined>;
+    private updateCache;
+    private getCache;
+}
+
+/**
+ * Represents options and configurations for an SDK.
+ */
+interface SdkOptions extends BaseSdkOptions {
+    xcetus: Package<XcetusConfig>;
+    xcetus_dividends: Package<DividendConfig>;
+    cetus_faucet: Package;
+}
+/**
+ * The entry class of CetusXcetusSDK, which is almost responsible for all interactions with Xcetus.
+ */
+declare class CetusXcetusSDK extends SdkWrapper<SdkOptions> {
+    /**
+     * Provide interact with Xcetus interface.
+     */
+    protected _xcetusModule: XCetusModule;
+    constructor(options: SdkOptions);
+    /**
+     * Getter for the Xcetus property.
+     * @returns {XCetusModule} The Xcetus property value.
+     */
+    get XCetusModule(): XCetusModule;
+    /**
+     * Static factory method to initialize the SDK
+     * @param options SDK initialization options
+     * @returns An instance of CetusXcetusSDK
+     */
+    static createSDK(options: BaseSdkOptions): CetusXcetusSDK;
+    /**
+     * Create a custom SDK instance with the given options
+     * @param options The options for the SDK
+     * @returns An instance of CetusBurnSDK
+     */
+    static createCustomSDK<T extends BaseSdkOptions>(options: T & SdkOptions): CetusXcetusSDK;
+}
+
+declare class XCetusUtil {
+    static buildVeNFTDividendInfo(fields: any): VeNFTDividendInfo;
+    static buildDividendManager(fields: any): DividendManager;
+    static buildLockUpManager(fields: any): LockUpManager;
+    static buildLockCetus(data: any): LockCetus;
+    static getAvailableXCetus(venft: VeNFT, locks: LockCetus[]): string;
+    static getWaitUnLockCetus(locks: LockCetus[]): LockCetus[];
+    static getLockingCetus(locks: LockCetus[]): LockCetus[];
+    static isLocked(lock: LockCetus): boolean;
+    static buildDividendRewardTypeList(reward_list?: DividendReward[], reward_list_v2?: DividendReward[]): string[];
+    static buildDividendRewardTypeListV2(reward_list?: DividendReward[]): BonusTypesV2;
+    static getNextStartTime(dividend_manager: DividendManager): number;
+}
+
+export { type BonusTypesV2, type CancelRedeemParams, CetusXcetusSDK, type ConvertParams, type DividendConfig, type DividendManager, type DividendReward, DividendsRouterModule, EXCHANGE_RATE_MULTIPLIER, type LockCetus, type LockUpConfig, type LockUpManager, ONE_DAY_SECONDS, type PhaseDividendInfo, REDEEM_NUM_MULTIPLIER, type RedeemLockParams, type RedeemXcetusParams, type SdkOptions, type VeNFT, type VeNFTDividendInfo, XCetusModule, XCetusUtil, type XcetusConfig, type XcetusManager, XcetusRouterModule, CetusXcetusSDK as default, defaultLockUpConfig };