@imtbl/bridge-sdk 2.0.0-alpha.0

package/dist/types/tokenBridge.d.ts

@@ -0,0 +1,354 @@
+import { BridgeConfiguration } from './config';
+import { BridgeFeeRequest, BridgeFeeResponse, BridgeTxRequest, ApproveBridgeRequest, ApproveBridgeResponse, BridgeTxResponse, TokenMappingRequest, TokenMappingResponse, TxStatusRequest, TxStatusResponse, FlowRateInfoResponse, PendingWithdrawalsRequest, PendingWithdrawalsResponse, FlowRateWithdrawRequest, FlowRateWithdrawResponse, FlowRateInfoRequest, BridgeBundledTxRequest, BridgeBundledTxResponse } from './types';
+/**
+ * Represents a token bridge, which manages asset transfers between two chains.
+ */
+export declare class TokenBridge {
+    /**
+     * @property {BridgeConfiguration} config - The bridge configuration object.
+     */
+    private config;
+    /**
+     * @property {boolean} initialised - Flag to indicate whether this token bridge has been initialised.
+     */
+    private initialised;
+    /**
+     * Constructs a TokenBridge instance.
+     *
+     * @param {BridgeConfiguration} config - The bridge configuration object.
+     */
+    constructor(config: BridgeConfiguration);
+    /**
+     * Initialise the TokenBridge instance.
+     */
+    initialise(): Promise<void>;
+    /**
+     * Retrieves the bridge fee for a specific token.
+     *
+     * @param {BridgeFeeRequest} req - The fee request object containing the token address for which the fee is required.
+     * @returns {Promise<BridgeFeeResponse>} - A promise that resolves to an object containing the bridge fee for the specified
+     * token and a flag indicating if the token is bridgeable.
+     * @throws {BridgeError} - If an error occurs during the fee retrieval, a BridgeError will be thrown with a specific error type.
+     *
+     * Possible BridgeError types include:
+     * - INVALID_ADDRESS: The token address provided in the request is invalid.
+     *
+     * @example
+     * const feeRequest = {
+     *   action: 'WITHDRAW', // BridgeFeeActions
+     *   gasMultiplier: 1.2, // Buffer to add to the gas estimate, 1.2 = 20% buffer
+     *   sourceChainId: '13371', // Immutable zkEVM
+     *   destinationChainId: '1' // Ethereum
+     * };
+     *
+     * @example
+     * const feeRequest = {
+     *   action: 'DEPOSIT', // BridgeFeeActions
+     *   gasMultiplier: 1.2, // Buffer to add to the gas estimate, 1.2 = 20% buffer
+     *   sourceChainId: '1', // Ethereum
+     *   destinationChainId: '13371', // Immutable zkEVM
+     * };
+     *
+     * bridgeSdk.getFee(feeRequest)
+     *   .then((feeResponse) => {
+     *     console.log('Source chain gas fee:', feeResponse.sourceChainFee);
+     *     console.log('Destination chain gas fee:', feeResponse.destinationChainFee);
+     *     console.log('Axelar bridge fee (includes destination execution):', feeResponse.bridgeFee);
+     *     console.log('Immutable fee:', feeResponse.networkFee);
+     *     console.log('Total Fees (sourceChainFee + bridgeFee + networkFee):', feeResponse.totalFee);
+     *   })
+     *   .catch((error) => {
+     *     console.error('Error:', error.message);
+     *   });
+     */
+    getFee(req: BridgeFeeRequest): Promise<BridgeFeeResponse>;
+    private getFinaliseWithdrawFee;
+    private getDepositOrWithdrawFee;
+    private getFeePrivate;
+    /**
+     * Retrieves the unsigned approval transaction for deposit or withdrawal.
+     * Approval is required before depositing or withdrawing tokens to the bridge using
+     *
+     * @param {ApproveBridgeRequest} req - The approve bridge request object.
+     * @returns {Promise<ApproveBridgeResponse>} - A promise that resolves to an object containing the unsigned
+     * approval transaction or null if no approaval is required.
+     * @throws {BridgeError} - If an error occurs during the transaction creation, a BridgeError will be thrown with a specific error type.
+     *
+     * Possible BridgeError types include:
+     * - UNSUPPORTED_ERROR: The operation is not supported. Currently thrown when attempting to deposit native tokens.
+     * - INVALID_ADDRESS: An Ethereum address provided in the request is invalid.
+     * - INVALID_AMOUNT: The deposit amount provided in the request is invalid (less than or equal to 0).
+     * - INTERNAL_ERROR: An unexpected error occurred during the execution, likely due to the bridge SDK implementation.
+     * - PROVIDER_ERROR: An error occurred while interacting with the Ethereum provider. This includes issues calling the ERC20 smart contract
+     *
+     * @example
+     * const approveDepositRequest = {
+     *   senderAddress: '0x123456...', // Senders address
+     *   token: '0xabcdef...', // ERC20 token address
+     *   amount: ethers.utils.parseUnits('100', 18), // amount being bridged in token's smallest unit (e.g., wei for Ether)
+     *   sourceChainId: '1', // Ethereum
+     *   destinationChainId: '13371', // Immutable zkEVM
+     * };
+     *
+     * @example
+     * const approveWithdrawalRequest = {
+     *   senderAddress: '0x123456...', // Senders address
+     *   token: '0xabcdef...', // ERC20 token address
+     *   amount: ethers.utils.parseUnits('100', 18), // amount being bridged in token's smallest unit (e.g., wei for Ether)
+     *   sourceChainId: '13371', // Immutable zkEVM
+     *   destinationChainId: '1', // Ethereum
+     * };
+     *
+     * bridgeSdk.getUnsignedApproveBridgeTx(approveDepositRequest)
+     *   .then((approveResponse) => {
+     *     if (approveResponse.unsignedTx !== null) {
+     *       // Send the unsigned approval transaction to the depositor to sign and send
+     *     } else {
+     *      // No approval is required
+     *     }
+     *   })
+     *   .catch((error) => {
+     *     console.error('Error:', error.message);
+     *   });
+     */
+    getUnsignedApproveBridgeTx(req: ApproveBridgeRequest): Promise<ApproveBridgeResponse>;
+    /**
+     * Get the smart contract function names depending on whether the request is a deposit or withdrawal.
+     */
+    private getBridgeMethods;
+    /**
+     * Get the bridge contract which will be interacted with. Root bridge if deposit, child bridge if withdrawal.
+     */
+    private getBridgeContract;
+    /**
+     * Get the transaction data for a bridge transaction.
+     * This will either be a deposit or withdraw, with either the native token or an ERC20 token,
+     * and either to the sender or to a different address.
+     * This means there are 8 possible transactions:
+     *     - Deposit native token
+     *     - Deposit native token TO
+     *     - Deposit ERC20 token
+     *     - Deposit ERC20 token TO
+     *     - Withdraw native token
+     *     - Withdraw native token TO
+     *     - Withdraw ERC20 token
+     *     - Withdraw ERC20 token TO
+     * @param sender Bridge depositer/withdrawer
+     * @param recipient Deposit or withdrawal recipient
+     * @param amount Amount to deposit or withdraw
+     * @param token Token to deposit or withdraw. NATIVE if native asset on the source chain.
+     * @param sourceChainId Chain ID of the source chain
+     * @returns calldata for the requested bridge transaction (i.e. tx.data)
+     */
+    private getConfigAndBridgeTxCalldata;
+    /**
+     * Generates an unsigned deposit or withdrawal transaction for a user to sign and submit to the bridge.
+     * Must be called after bridgeSdk.getUnsignedApproveBridgeTx to ensure user has approved sufficient tokens for deposit.
+     *
+     * @param {BridgeTxRequest} req - The tx request object containing the required data for depositing or withdrawing tokens.
+     * @returns {Promise<BridgeTxResponse>} - A promise that resolves to an object containing the fee data and unsigned transaction data.
+     * @throws {BridgeError} - If an error occurs during the generation of the unsigned transaction, a BridgeError
+     * will be thrown with a specific error type.
+     *
+     * Possible BridgeError types include:
+     * - UNSUPPORTED_ERROR: The operation is not supported. Currently thrown when attempting to deposit native tokens.
+     * - INVALID_ADDRESS: An Ethereum address provided in the request is invalid. This could be the depositor's,
+     * recipient's or the token's address.
+     * - INVALID_AMOUNT: The deposit amount provided in the request is invalid (less than or equal to 0).
+     * - INTERNAL_ERROR: An unexpected error occurred during the execution, likely due to the bridge SDK implementation.
+     *
+     * @example
+     * const depositERC20Request = {
+     *   senderAddress: '0x123456...', // Senders address
+     *   recipientAddress: '0x123456...', // Recipient address
+     *   token: '0x123456...', // ERC20 token address
+     *   amount: ethers.utils.parseUnits('100', 18), // Bridge amount in wei
+     *   sourceChainId: '1', // Ethereum
+     *   destinationChainId: '13371', // Immutable zkEVM
+     *   gasMultiplier: 1.2, // Buffer to add to the gas estimate, 1.2 = 20% buffer
+     * };
+     *
+     * @example
+     * const depositEtherTokenRequest = {
+     *   senderAddress: '0x123456...', // Senders address
+     *   recipientAddress: '0x123456...', // Recipient address
+     *   token: 'NATIVE', // The chain's native token
+     *   amount: ethers.utils.parseUnits('100', 18), // Bridge amount in wei
+     *   sourceChainId: '1', // Ethereum
+     *   destinationChainId: '13371', // Immutable zkEVM
+     *   gasMultiplier: 1.2, // Buffer to add to the gas estimate, 1.2 = 20% buffer
+     * };
+     *
+     * @example
+     * const withdrawERC20Request = {
+     *   senderAddress: '0x123456...', // Senders address
+     *   recipientAddress: '0x123456...', // Recipient address
+     *   token: '0x123456...', // ERC20 token address
+     *   amount: ethers.utils.parseUnits('100', 18), // Bridge amount in wei
+     *   sourceChainId: '13371', // Immutable zkEVM
+     *   destinationChainId: '1', // Ethereum
+     *   gasMultiplier: 1.2, // Buffer to add to the gas estimate, 1.2 = 20% buffer
+     * };
+     *
+     * @example
+     * const withdrawIMXTokenRequest = {
+     *   senderAddress: '0x123456...', // Senders address
+     *   recipientAddress: '0x123456...', // Recipient address
+     *   token: 'NATIVE', // The chain's native token
+     *   amount: ethers.utils.parseUnits('100', 18), // Bridge amount in wei
+     *   sourceChainId: '13371', // Immutable zkEVM
+     *   destinationChainId: '1', // Ethereum
+     *   gasMultiplier: 1.2, // Buffer to add to the gas estimate, 1.2 = 20% buffer
+     * };
+     *
+     * bridgeSdk.getUnsignedBridgeTx(depositERC20Request)
+     *   .then((depositResponse) => {
+     *     console.log('Fee Data', depositResponse.feeData);
+     *     console.log('Unsigned Tx', depositResponse.unsignedTx);
+     *   })
+     *   .catch((error) => {
+     *     console.error('Error:', error.message);
+     *   });
+     */
+    getUnsignedBridgeTx(req: BridgeTxRequest): Promise<BridgeTxResponse>;
+    /**
+     * Generates the optional approval transaction AND an unsigned deposit or withdrawal transaction for a user to sign
+     * and submit to the bridge.
+     * It is the combination of bridgeSdk.getUnsignedApproveBridgeTx and bridgeSdk.getUnsignedBridgeTx.
+     *
+     * @param {BridgeBundledTxRequest} req - The tx request object containing the required data for depositing or withdrawing tokens.
+     * @returns {Promise<BridgeBundledTxResponse>} - A promise that resolves to an object containing the optional contract to approve,
+     * optional unsigned approval transaction, fee data and unsigned transaction data.
+     * @throws {BridgeError} - If an error occurs during the generation of the unsigned transaction, a BridgeError
+     * will be thrown with a specific error type.
+     *
+     * Possible BridgeError types include:
+     * - UNSUPPORTED_ERROR: The operation is not supported. Currently thrown when attempting to deposit native tokens.
+     * - INVALID_ADDRESS: An Ethereum address provided in the request is invalid. This could be the depositor's,
+     * recipient's or the token's address.
+     * - INVALID_AMOUNT: The deposit amount provided in the request is invalid (less than or equal to 0).
+     * - INTERNAL_ERROR: An unexpected error occurred during the execution, likely due to the bridge SDK implementation.
+     *
+     * @example
+     * const depositERC20Request = {
+     *   senderAddress: '0x123456...', // Senders address
+     *   recipientAddress: '0x123456...', // Recipient address
+     *   token: '0x123456...', // ERC20 token address
+     *   amount: ethers.utils.parseUnits('100', 18), // Bridge amount in wei
+     *   sourceChainId: '1', // Ethereum
+     *   destinationChainId: '13371', // Immutable zkEVM
+     *   gasMultiplier: 1.2, // Buffer to add to the gas estimate, 1.2 = 20% buffer
+     * };
+     *
+     * @example
+     * const depositEtherTokenRequest = {
+     *   senderAddress: '0x123456...', // Senders address
+     *   recipientAddress: '0x123456...', // Recipient address
+     *   token: 'NATIVE', // The chain's native token
+     *   amount: ethers.utils.parseUnits('100', 18), // Bridge amount in wei
+     *   sourceChainId: '1', // Ethereum
+     *   destinationChainId: '13371', // Immutable zkEVM
+     *   gasMultiplier: 1.2, // Buffer to add to the gas estimate, 1.2 = 20% buffer
+     * };
+     *
+     * @example
+     * const withdrawERC20Request = {
+     *   senderAddress: '0x123456...', // Senders address
+     *   recipientAddress: '0x123456...', // Recipient address
+     *   token: '0x123456...', // ERC20 token address
+     *   amount: ethers.utils.parseUnits('100', 18), // Bridge amount in wei
+     *   sourceChainId: '13371', // Immutable zkEVM
+     *   destinationChainId: '1', // Ethereum
+     *   gasMultiplier: 1.2, // Buffer to add to the gas estimate, 1.2 = 20% buffer
+     * };
+     *
+     * @example
+     * const withdrawIMXTokenRequest = {
+     *   senderAddress: '0x123456...', // Senders address
+     *   recipientAddress: '0x123456...', // Recipient address
+     *   token: 'NATIVE', // The chain's native token
+     *   amount: ethers.utils.parseUnits('100', 18), // Bridge amount in wei
+     *   sourceChainId: '13371', // Immutable zkEVM
+     *   destinationChainId: '1', // Ethereum
+     *   gasMultiplier: 1.2, // Buffer to add to the gas estimate, 1.2 = 20% buffer
+     * };
+     *
+     * bridgeSdk.getUnsignedBridgeBundledTx(depositERC20Request)
+     *   .then((depositResponse) => {
+     *     console.log('Fee Data', depositResponse.feeData);
+     *     console.log('Optional contract to approve', depositResponse.contractToApprove);
+     *     console.log('Optional unsigned approval Tx', depositResponse.unsignedApprovalTx);
+     *     console.log('Unsigned bridge Tx', depositResponse.unsignedBridgeTx);
+     *   })
+     *   .catch((error) => {
+     *     console.error('Error:', error.message);
+     *   });
+     */
+    getUnsignedBridgeBundledTx(req: BridgeBundledTxRequest): Promise<BridgeBundledTxResponse>;
+    private getUnsignedBridgeBundledTxPrivate;
+    private getUnsignedBridgeDepositBundledTxPrivate;
+    private getUnsignedBridgeWithdrawBundledTxPrivate;
+    private getDynamicDepositGas;
+    /**
+     * Use Tenderly simulations to estimate the gas cost of the destination (root) chain transaction of a withdraw
+     */
+    private getDynamicWithdrawGasRootChain;
+    private getAllowance;
+    /**
+   * Query the axelar fee for a transaction using axelarjs-sdk.
+   * @param {*} sourceChainId - The source chainId.
+   * @param {*} destinationChainId - The destination chainId.
+   * @param {*} destinationChainGaslimit - The gas limit for the desired operation.
+   * @param {*} gasMultiplier - The gas multiplier to add buffer to the fees.
+   * @returns {ethers.BigNumber} - The Axelar Gas amount in the source chain currency.
+   */
+    private getAxelarFee;
+    /**
+   * Queries the status of a bridge transaction.
+   *
+   * @param {TxStatusRequest} req - The request object containing an array of transactions to query.
+   * @returns {Promise<TxStatusResponse>} - A promise that resolves to an array of transaction statuses.
+   * @throws {BridgeError} - If an error occurs during the query, a BridgeError will be thrown with a specific error type.
+   */
+    getTransactionStatus(req: TxStatusRequest): Promise<TxStatusResponse>;
+    private getUniqueReceivers;
+    private getAxelarStatus;
+    /**
+   * Queries for the information about which tokens are flowrated and how long the delay is.
+   *
+   * @param {void} - no params required.
+   * @returns {Promise<FlowRateInfoResponse>} - A promise that resolves to an object containing the flow rate information.
+   * @throws {BridgeError} - If an error occurs during the query, a BridgeError will be thrown with a specific error type.
+   * @dev this SDK method is currently stubbed
+   */
+    getFlowRateInfo(req: FlowRateInfoRequest): Promise<FlowRateInfoResponse>;
+    /**
+   * Fetches the pending withdrawals for a given address.
+   *
+   * @param {PendingWithdrawalsRequest} req - The request object containing the reciever address.
+   * @returns {Promise<PendingWithdrawalsResponse>} - A promise that resolves to an object containing the child token address.
+   * @throws {BridgeError} - If an error occurs during the query, a BridgeError will be thrown with a specific error type.
+   * @dev this SDK method is currently stubbed
+   */
+    getPendingWithdrawals(req: PendingWithdrawalsRequest): Promise<PendingWithdrawalsResponse>;
+    /**
+   * Retrieves the unsigned flow rate withdrawal transaction
+   *
+   * @param {FlowRateWithdrawRequest} req - The request object containing the receiver address and pending withdrawal index.
+   * @returns {Promise<FlowRateWithdrawResponse>} - A promise that resolves to an object containing the unsigned transaction.
+   * @throws {BridgeError} - If an error occurs during the query, a BridgeError will be thrown with a specific error type.
+   * @dev this SDK method is currently stubbed
+   */
+    getFlowRateWithdrawTx(req: FlowRateWithdrawRequest): Promise<FlowRateWithdrawResponse>;
+    /**
+   * Retrieves the corresponding token mappings for a given address.
+   * This function is used to map a root token to its child token in the context of a bridging system between chains.
+   * If the token is native, a special key is used to represent it.
+   *
+   * @param {TokenMappingRequest} req - The request object containing the root token address or the string 'NATIVE'.
+   * @returns {Promise<TokenMappingResponse>} - A promise that resolves to an object containing the child token address.
+   * @throws {BridgeError} - If an error occurs during the query, a BridgeError will be thrown with a specific error type.
+   * @dev this SDK method is currently stubbed
+   */
+    getTokenMapping(req: TokenMappingRequest): Promise<TokenMappingResponse>;
+}

package/dist/types/tokenBridge.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/types/axelar.d.ts

@@ -0,0 +1,43 @@
+export declare enum GMPStatus {
+    SRC_GATEWAY_CALLED = "source_gateway_called",
+    DEST_GATEWAY_APPROVED = "destination_gateway_approved",
+    DEST_EXECUTED = "destination_executed",
+    EXPRESS_EXECUTED = "express_executed",
+    DEST_EXECUTE_ERROR = "error",
+    DEST_EXECUTING = "executing",
+    APPROVING = "approving",
+    FORECALLED = "forecalled",
+    FORECALLED_WITHOUT_GAS_PAID = "forecalled_without_gas_paid",
+    NOT_EXECUTED = "not_executed",
+    NOT_EXECUTED_WITHOUT_GAS_PAID = "not_executed_without_gas_paid",
+    INSUFFICIENT_FEE = "insufficient_fee",
+    UNKNOWN_ERROR = "unknown_error",
+    CANNOT_FETCH_STATUS = "cannot_fetch_status",
+    SRC_GATEWAY_CONFIRMED = "confirmed"
+}
+export declare enum GasPaidStatus {
+    GAS_UNPAID = "gas_unpaid",
+    GAS_PAID = "gas_paid",
+    GAS_PAID_NOT_ENOUGH_GAS = "gas_paid_not_enough_gas",
+    GAS_PAID_ENOUGH_GAS = "gas_paid_enough_gas"
+}
+export interface GasPaidInfo {
+    status: GasPaidStatus;
+    details?: any;
+}
+export interface GMPStatusResponse {
+    status: GMPStatus | string;
+    timeSpent?: Record<string, number>;
+    gasPaidInfo?: GasPaidInfo;
+    error?: GMPError;
+    callTx?: any;
+    executed?: any;
+    expressExecuted?: any;
+    approved?: any;
+    callback?: any;
+}
+export interface GMPError {
+    txHash: string;
+    chain: string;
+    message: string;
+}