orbiter-bridge-sdks 0.1.15

package/README.md

@@ -0,0 +1,347 @@
+# Orbiter SDK Document
+
+## 🌕 Overview
+
+-   The Orbiter SDK package provides a simplest, out-of-the-box approach to access the Orbiter API to find and execute
+    the best on-chain and cross-chain swapping and bridging.
+
+-   For more information about API, please see page:
+    [Orbiter REST API](https://docs.orbiter.finance/developer/rest-api/overview).
+
+## 📦 Installation
+
+You can use following ways to get the latest version of Orbiter SDK.
+
+-   npm
+
+    ```shell
+    npm install @orbiter-finance/bridge-sdk
+    ```
+
+-   yarn
+
+    ```shell
+    yarn add @orbiter-finance/bridge-sdk
+    ```
+
+-   pnpm
+
+    ```shell
+    pnpm add @orbiter-finance/bridge-sdk
+    ```
+
+Feel free to [report](https://discord.com/invite/FbztTBvnBT) if you encounter any problems.
+
+## 👾 Quick Start
+
+-   ### Set up the SDK
+
+    ```javascript
+    import {  OrbiterClient, ENDPOINT } from "@orbiter-finance/bridge-sdk";
+    const config: ConfigOptions = {
+      apiEndpoint: ENDPOINT.TESTNET
+      defaultRouterType: RouterType.CONTRACT //Optional, which give priority to the transfer type
+    }
+    let orbiter: OrbiterClient = await OrbiterClient.create(config);
+    ```
+
+-   ### Check Available TradePair
+
+    ```typescript
+    // get all available chains
+    const chains: Chain[] = orbiter.getAllChains()
+
+    // choose a chain from list to get availabletokens
+    const tokens: Token[] = orbiter.getAvailableTokens("chainId")
+
+    // choose a chain and a token symbol to get available trade pairs
+    const tradePairs: TradePair[] = orbiter.getAvailableTradePairs("chainId", "symbol")
+
+    // or directly get all available trade pairs
+    const tradePairs: TradePair[] = orbiter.getAllTradePairs()
+
+    // in case you want show all symbols
+    const symbols = orbiter.getAllSymbols()
+    ```
+
+    > 💡Tips:
+    >
+    > -   You don't have to care about the router type you send transaction, SDK will automatically using the availlable
+    >     type, unless you know what that way means.
+
+-   ### Create Router and Send Transaction
+
+    ##### From EVM Chains
+
+    ```typescript
+    import { Wallet, JsonRpcProvider } from "ethers"
+
+    // choose a tradePair to create router
+    const tradePair: TradePair = {
+        srcChainId: "11155111",
+        dstChainId: "421614",
+        srcTokenSymbol: "ETH",
+        dstTokenSymbol: "ETH",
+    }
+    const router = orbiter.createRouter(tradePair)
+
+    // check min and max value
+    const min = router.getMinSendAmount()
+    const max = router.getMaxSendAmount()
+
+    // simulationAmount
+    const { sendAmount, receiveAmount } = router.simulationAmount("amountBetweenMinAndMax")
+
+    // connect wallet
+    const provider = new JsonRpcProvider("https://ethereum-sepolia-rpc.publicnode.com")
+    const wallet = new Wallet("privateKey", provider)
+    // check if balance sufficient
+    const balance = (await provider.getBalance(wallet)).toString()
+
+    // if is erc20 token, need approve
+    // const approve = await router.createApprove(account.address, sendAmount);
+    // const approveResponce = await wallet.sendTransaction(approve);
+    // const approveReceipt = await approveRes.wait();
+
+    // create transaction
+    const transactionParams = router.createTransaction(wallet.address, "receiver", sendAmount)
+    // send transaction
+    const transactionResponce = await wallet.sendTransaction(transactionParams.raw as TransactionRequest)
+    const transactionReceipt = await transferResponce.wait()
+    ```
+
+    ##### From BTC Chains
+
+    ```typescript
+    import * as bitcoin from 'bitcoinjs-lib'
+    import * as ecc from 'tiny-secp256k1';
+    import { ECPairFactory, networks } from 'ecpair';
+
+    // choose a tradePair to create router
+    const tradePair: TradePair = {
+      srcChainId: 'FRACTAL_TEST',
+      dstChainId: '11155111',
+      srcTokenSymbol: 'BTC',
+      dstTokenSymbol: 'BTC'
+    }
+    const router = orbiter.createRouter(tradePair);
+
+    // check min and max value
+    const min = router.getMinSendAmount();
+    const max = router.getMaxSendAmount();
+
+    // simulationAmount
+    const { sendAmount, receiveAmount } = router.simulationAmount('amountBetweenMinAndMax');
+
+    // creat payment
+    const network = networks.bitcoin;
+    const ECPair = ECPairFactory(ecc);
+    const keyPair = ECPair.fromWIF(btcPrivateKey, network);
+    const payment = bitcoin.payments.p2wpkh({
+      pubkey: keyPair.publicKey,
+      network,
+    });
+
+    // create transaction and add output
+    const transactionParams = await router.createTransaction(payment.address, 'receiver', sendAmount);
+    const psbt = transactionParams.raw as bitcoin.Psbt;
+
+    // get utxos from chain
+    const utxos = ...
+
+    // add inputs
+    const script = payment.output;
+    utxos.forEach((utxo: any) => {
+      const inputData = {
+        hash: utxo.txid,
+        index: utxo.vout,
+        witnessUtxo: {
+          script,
+          value: utxo.satoshi
+        },
+      }
+      psbt.addInput(inputData);
+    });
+
+    // estimate fee from oracle or explorer
+    const fee = ...
+
+    // add change !!!important!!!
+    const change = totalAmount - Number(sendAmount) - fee;
+    if (change > 0) {
+      psbt.addOutput({
+        script,
+        value: change
+      });
+    }
+
+    // sign inputs
+    for (let i = 0; i < psbt.inputCount; i++) {
+      psbt.signInput(i, keyPair);
+      psbt.validateSignaturesOfInput(i, (
+        pubkey: Buffer,
+        msghash: Buffer,
+        signature: Buffer,
+      ) => ECPair.fromPublicKey(pubkey).verify(msghash, signature));
+    }
+    psbt.finalizeAllInputs();
+
+    // broadcast
+    const broadcastResult = ...
+
+    ```
+
+    ##### From Tron Chains
+
+    ```typescript
+    import { TronWeb } from "tronweb"
+
+    // choose a tradePair to create router
+    const tradePair: TradePair = {
+        srcChainId: "3448148188",
+        dstChainId: "11155111",
+        srcTokenSymbol: "JST",
+        dstTokenSymbol: "JST",
+    }
+    const router = orbiter.createRouter(tradePair)
+
+    // check min and max value
+    const min = router.getMinSendAmount()
+    const max = router.getMaxSendAmount()
+
+    // simulationAmount
+    const { sendAmount, receiveAmount } = router.simulationAmount("amountBetweenMinAndMax")
+
+    // connect to tronweb
+    const tronWeb = new TronWeb({
+        fullHost: "https://nile.trongrid.io",
+        headers: { "TRON-PRO-API-KEY": "API key" },
+        privateKey: "privateKey",
+    })
+
+    // create approve
+    const approveParams = await router.createApprove(address, sendAmount)
+    // sign and send approve
+    const signedApprove = await tronWeb.trx.sign((approveParams.raw as Types.TransactionWrapper).transaction)
+    const approveRes = await tronWeb.trx.sendRawTransaction(signedApprove)
+
+    // create transaction
+    const transactionParams = await router.createTransaction(address, evmAddress, sendAmount)
+    // sign and send transaction
+    const signedTransaction = await tronWeb.trx.sign((transactionParams.raw as Types.TransactionWrapper).transaction)
+    const transferRes = await tronWeb.trx.sendRawTransaction(signedTransaction)
+    ```
+
+    ##### From Starknet Chains
+
+    ```typescript
+    import { Account, Provider, constants } from "starknet"
+
+    // choose a tradePair to create router
+    const tradePair: TradePair = {
+        srcChainId: "SN_SEPOLIA",
+        dstChainId: "11155111",
+        srcTokenSymbol: "ETH",
+        dstTokenSymbol: "ETH",
+    }
+    const router = orbiter.createRouter(tradePair)
+
+    // check min and max value
+    const min = router.getMinSendAmount()
+    const max = router.getMaxSendAmount()
+
+    // simulationAmount
+    const { sendAmount, receiveAmount } = router.simulationAmount("amountBetweenMinAndMax")
+
+    // connect account
+    const provider = new Provider({ nodeUrl: constants.NetworkName.SN_SEPOLIA })
+    const account = new Account(provider, starknetAddress, privateKey)
+
+    // create approve
+    const approveParams = await router.createApprove(account.address, sendAmount)
+
+    // create transaction
+    const transactionParams = router.createTransaction(wallet.address, "receiver", sendAmount)
+
+    // send approve and transaction
+    const transactionResponce = await account.execute([approveParams.raw as Call, transactionParams.raw as Call])
+    const transactionReceipt = await provider.waitForTransaction(transactionResponce.transaction_hash)
+    ```
+
+    ##### From Solana Chains
+
+    ```typescript
+    import bs58 from "bs58"
+    import { Connection, Keypair, TransactionMessage, VersionedTransaction, LAMPORTS_PER_SOL } from "@solana/web3.js"
+
+    // choose a tradePair to create router
+    const tradePair: TradePair = {
+        srcChainId: "SOLANA_DEV",
+        dstChainId: "11155111",
+        srcTokenSymbol: "USDC",
+        dstTokenSymbol: "USDC",
+    }
+    const router = orbiter.createRouter(tradePair)
+
+    // check min and max value
+    const min = router.getMinSendAmount()
+    const max = router.getMaxSendAmount()
+
+    // simulationAmount
+    const { sendAmount, receiveAmount } = router.simulationAmount("amountBetweenMinAndMax")
+
+    // connect wallet
+    const connection = new Connection("solana-endpoint", "confirmed")
+    const sender = Keypair.fromSecretKey(bs58.decode("privateKey"))
+
+    // create transaction
+    const transactionParams = await router.createTransaction(sender.publicKey.toString(), "receiver", sendAmount)
+
+    // process transaction
+    const transaction = transactionParams.raw as Transaction
+    const blockhash = await connection.getLatestBlockhash()
+    transaction.recentBlockhash = blockhash.blockhash
+    transaction.feePayer = sender.publicKey
+    const modifyComputeUnits = ComputeBudgetProgram.setComputeUnitLimit({
+        units: 1000000,
+    })
+    const addPriorityFee = ComputeBudgetProgram.setComputeUnitPrice({
+        microLamports: 100,
+    })
+    transaction.add(modifyComputeUnits).add(addPriorityFee)
+    transaction.sign(sender)
+
+    const signature = await connection.sendRawTransaction(transaction.serialize())
+
+    //check transaction status
+    const status = await connection.getSignatureStatus(signature, {
+        searchTransactionHistory: false,
+    })
+    ```
+
+    > 💡Tips:
+    >
+    > -   The function [createTransfer] will return deferent type of transfer structure which depends on source chain
+    >     type, for EVM it will be TransactionRequest, for BTC will be a PSBT for Starknet will be Call, etc. For more
+    >     information please see their official document.
+
+-   ### Check Bridge Status
+
+    ```typescript
+    const transactionStatus = await orbiter.checkTransactionStatus(hash)
+    ```
+
+-   ### Check User Opoints and Transaction History
+
+    ```typescript
+    // get user Opoints
+    const opoints = await orbiter.getUserOpoint(wallet.address)
+
+    // get user transaction history
+    const history = await orbiter.getTransactionHistory(wallet.address, TxType.BRIDGE, 0)
+    ```
+
+    > 💡Tips:
+    >
+    > -   For structure of result on these two function, please check
+    >     [Orbiter REST API](https://docs.orbiter.finance/developer/rest-api/overview).

package/dist/index.d.mts

@@ -0,0 +1,335 @@
+import { VMType } from '@orbiter-finance/vm-core';
+
+interface APIResponse<T> {
+    status: string;
+    message: string;
+    result: T;
+}
+interface APIPageResponse<T> {
+    count: number;
+    rows: T[];
+    offset?: number;
+    limit?: number;
+}
+interface ChainConfig {
+    chainId: string;
+    networkId: string;
+    internalId: number;
+    name: string;
+    nativeCurrency: Token;
+    tokens: Token[];
+    contracts: Contract[];
+    vm: VMType;
+}
+interface Token {
+    name: string;
+    symbol: string;
+    decimals: number;
+    coinKey: string;
+    address: string;
+    isNative?: boolean;
+}
+interface Contract {
+    name: string;
+    address: string;
+}
+interface RouterConfig {
+    line: string;
+    endpoint: string;
+    endpointContract?: string;
+    srcChain: string;
+    tgtChain: string;
+    srcToken: string;
+    tgtToken: string;
+    maxAmt: string;
+    minAmt: string;
+    tradeFee: string;
+    withholdingFee: string;
+    vc: string;
+    state: RouterState;
+    type: string;
+    opool?: {
+        [key: string]: string;
+    };
+    compRatio: number;
+    spentTime: number;
+    tieredFee: TieredFee[];
+    point?: number | undefined;
+}
+interface TieredFee {
+    range: [number, number];
+    tradeFee: number;
+    withholdingFee: number;
+}
+declare enum RouterState {
+    AVAILABLE = "available",
+    DISABLED = "disabled"
+}
+interface Transaction {
+    sourceId: string;
+    targetId: string;
+    sourceChain: string;
+    targetChain: string;
+    sourceAmount: string;
+    sourceMaker: string;
+    sourceAddress: string;
+    targetAddress: string;
+    sourceSymbol: string;
+    targetSymbol: string;
+    status: number;
+    sourceTime: string;
+    targetTime: string;
+    points?: string;
+}
+interface PointRule {
+    [chain: string]: {
+        [symbol: string]: string;
+    };
+}
+declare enum TxType {
+    BRIDGE = "0",
+    COLLECTOR = "1",
+    SWAP = "2",
+    COMMISSION = "3",
+    SAME_CHAIN_SWAP = "4"
+}
+interface TxHistoryItem extends Transaction {
+    txType: TxType;
+    targetAmount?: string;
+    finalAmount?: string | null;
+    originSymbol?: string | null;
+    originToken?: string | null;
+    originAmount?: string | null;
+    finalSymbol?: string | null;
+    finalToken?: string | null;
+    sourceTokenInfo?: TokenInfo;
+    targetTokenInfo?: TokenInfo;
+    sourceToken?: string;
+}
+interface TokenInfo {
+    chainId: number;
+    address: string;
+    symbol: string;
+    name: string;
+    decimals: number;
+    priceUSD: string;
+    coinKey: string;
+    logoURI: string;
+}
+
+interface ConfigOptions {
+    apiEndpoint: ENDPOINT;
+    dealerId?: string;
+    apiKey?: string;
+    channelId?: string;
+    defaultRouterType?: RouterType;
+}
+declare enum ENDPOINT {
+    TESTNET = "https://testnet-api.orbiter.finance/sdk",
+    MAINNET = "https://api.orbiter.finance/sdk"
+}
+declare enum CDNENDPOINT {
+    TESTNET = "https://testnet-cdn.orbiter.finance/config",
+    MAINNET = "https://cdn.orbiter.finance/config"
+}
+interface TradePair {
+    srcChainId: string;
+    dstChainId: string;
+    srcTokenSymbol: string;
+    dstTokenSymbol: string;
+    routerType?: RouterType;
+}
+declare enum RouterType {
+    EOA = "EOA",
+    CONTRACT = "CONTRACT"
+}
+interface Chain {
+    id: string;
+    name: string;
+}
+interface TransactionParams {
+    routerType: RouterType;
+    srcAddress: string;
+    dstAddress: string;
+    value: string;
+    amount: string;
+    raw: unknown;
+    simulationAmountPlusWithHoldingFee?: SimulationAmountPlusWithHoldingFeeType;
+}
+interface SimulationAmountPlusWithHoldingFeeType {
+    sendAmount: {
+        amount: string;
+        isNativeCurrency: boolean;
+        token?: Token;
+    };
+    withholdingFee: {
+        amount: string;
+        isNativeCurrency: boolean;
+        token?: Token;
+    };
+    isOPool: boolean;
+    type: string;
+    opool: any;
+}
+interface ApproveParams {
+    ownerAddress: string;
+    spenderAddress: string;
+    value: string;
+    amount: string;
+    raw: unknown;
+}
+interface DynamicPointParams {
+    chainId: string;
+    symbol: string;
+    withholdingFee: string;
+    tradeFee: string;
+}
+
+declare class ApiService {
+    private apiEndpoint;
+    private cdnEndpoint;
+    private apiKey?;
+    private channelId?;
+    constructor(apiEndpoint: ENDPOINT, apiKey?: string, channelId?: string);
+    private fetchAPIGet;
+    private fetchCDNGet;
+    getChainList(): Promise<ChainConfig[]>;
+    getTokenList(): Promise<Record<string, Token[]>>;
+    getRouterList(dealerId?: string): Promise<RouterConfig[]>;
+    getBasePointRules(): Promise<PointRule>;
+    getSimulatedReceiveAmount(line: string, value: string, nonce?: string, dealer?: string, brokerageTradeFeeRate?: number): Promise<{
+        receiveAmount: string;
+        router: RouterConfig;
+    }>;
+    getTransactionHistory(address: string, txType: TxType, offset?: number): Promise<APIPageResponse<TxHistoryItem>>;
+    getTransactionStatus(hash: string, chainId?: string, address?: string, value?: string): Promise<any>;
+    getUserOpoint(address: string): Promise<any>;
+    getDynamicPoint(param: DynamicPointParams): Promise<string>;
+}
+
+declare class ConfigService {
+    private readonly _apiService;
+    private readonly _config;
+    private _chainConfigs?;
+    private _routerConfigs?;
+    private _basePointRules?;
+    constructor(_apiService: ApiService, _config: ConfigOptions);
+    initConfig(): Promise<void>;
+    initChainConfigs(): Promise<void>;
+    initRouterConfigs(): Promise<void>;
+    initBasePointRules(): Promise<void>;
+    getRouterConfigs(): RouterConfig[];
+    getRouterConfig(tradePair: TradePair): RouterConfig | undefined;
+    getChainConfigs(): ChainConfig[];
+    getChainConfigByName(chainName: string): ChainConfig | undefined;
+    getChainConfigById(chainId: string): ChainConfig | undefined;
+    getBasePointRule(chainId: string, symbol: string): string;
+}
+
+declare class VMService {
+    private readonly _configService;
+    constructor(configService: ConfigService);
+    isValidTransferType(routerType: RouterType): boolean;
+    getAmountWithVc(amount: string, token: Token, vc: string): string;
+    createTransaction(srcAddress: string, srcToken: Token, dstAddress: string, dstToken: Token, value: string, vc: string, routerType: RouterType, makerAddress: string, chainId: string, contractAddress?: string, channelId?: string, simulationAmountPlusWithHoldingFee?: SimulationAmountPlusWithHoldingFeeType, ext?: any): Promise<TransactionParams>;
+    createApprove(ownerAddress: string, spenderAddress: string, approveToken: Token, chainId: string, value: string): Promise<ApproveParams>;
+    createAllowance(ownerAddress: string, spenderAddress: string, approveToken: Token, chainId: string): Promise<unknown>;
+}
+
+declare class Router {
+    readonly srcChainConfig: ChainConfig;
+    readonly srcToken: Token;
+    readonly dstChainConfig: ChainConfig;
+    readonly dstToken: Token;
+    readonly basePoint: string;
+    private readonly _VMService;
+    readonly routerConfig: RouterConfig;
+    readonly routerTypes: RouterType[];
+    private readonly _channelId?;
+    constructor(srcChainConfig: ChainConfig, srcToken: Token, dstChainConfig: ChainConfig, dstToken: Token, basePoint: string, _VMService: VMService, routerConfig: RouterConfig, routerTypes: RouterType[], _channelId?: string | undefined);
+    get routerId(): string;
+    get vc(): string;
+    get withholdingFee(): string;
+    get tradeFee(): string;
+    get makerAddress(): string;
+    get contractAddress(): string | undefined;
+    get spentTime(): number;
+    createTransaction(srcAddress: string, dstAddress: string, amount: string, ext?: any): Promise<TransactionParams>;
+    createApprove(ownerAddress: string, amount: string, token?: Token): Promise<ApproveParams>;
+    createAllowance(ownerAddress: string, token?: Token): Promise<unknown>;
+    getMinSendAmountMinusWithHoldingFee(): string;
+    getMinSendAmount(): string;
+    getMaxSendAmount(): string;
+    getIsOPool(): boolean;
+    equalFeeTokenBridgeToken(): boolean;
+    simulationAmountPlusWithHoldingFee(amount: string): {
+        sendAmount: {
+            amount: string;
+            token: Token | undefined;
+            isNativeCurrency: boolean;
+        };
+        withholdingFee: {
+            amount: string;
+            token: Token | undefined;
+            isNativeCurrency: boolean;
+        };
+        tradeFeeRate: string;
+        type: string;
+        isOPool: boolean;
+        receiveAmount: string;
+        opool: {
+            [key: string]: string;
+        } | undefined;
+    };
+    simulationAmount(amount: string): {
+        sendAmount: string;
+        receiveAmount: string;
+    };
+    private _getResponseIntent;
+    private _getTargetAmountSafeLengthByToken;
+}
+
+declare class OrbiterClient {
+    private readonly _config;
+    private readonly _apiService;
+    private readonly _configService;
+    private readonly _VMServiceFactory;
+    private readonly _defaultRouterType;
+    constructor(config: ConfigOptions);
+    init(): Promise<void>;
+    static create(config: ConfigOptions): Promise<OrbiterClient>;
+    createRouter(tradePair: TradePair): Router;
+    private checkTradePairType;
+    getAllChains(): Chain[];
+    getAllSymbols(): string[];
+    getChainConfig(chainId: string): ChainConfig | undefined;
+    getAvailableTokens(chainId: string): Token[];
+    getAllTradePairs(): TradePair[];
+    getAvailableTradePairs(srcChainId?: string, srcTokenSymbol?: string): TradePair[];
+    getTransactionHistory(address: string, txType: TxType, offset?: number): Promise<APIPageResponse<TxHistoryItem>>;
+    getTransactionStatus(hash: string, chainId?: string, address?: string, value?: string): Promise<{
+        chainId: string;
+        hash: string;
+        sender: string;
+        receiver: string;
+        amount: string;
+        symbol: string;
+        timestamp: string;
+        status: number;
+        opStatus: number;
+        targetId: string;
+        targetAmount: string;
+        targetSymbol: string;
+        targetChain: string;
+    }>;
+    getUserOpoint(address: string): Promise<{
+        address: string;
+        summary: {
+            [key: string]: number;
+        };
+        points: number;
+    }>;
+    getDynamicPoint(param: DynamicPointParams): Promise<string>;
+}
+
+export { type APIPageResponse, type APIResponse, ApiService, type ApproveParams, CDNENDPOINT, type Chain, type ChainConfig, type ConfigOptions, type Contract, type DynamicPointParams, ENDPOINT, OrbiterClient, type PointRule, Router, type RouterConfig, RouterState, RouterType, type SimulationAmountPlusWithHoldingFeeType, type TieredFee, type Token, type TokenInfo, type TradePair, type Transaction, type TransactionParams, type TxHistoryItem, TxType };