JSPM

@axelar-network/axelarjs-sdk

0.4.5
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 4860
  • Score
    100M100P100Q178713F
  • License MIT

The JavaScript SDK for Axelar Network

Package Exports

  • @axelar-network/axelarjs-sdk
  • @axelar-network/axelarjs-sdk/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@axelar-network/axelarjs-sdk) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

AxelarJS SDK

Overview

The Axelar JS SDK was created to abstract a set of tools used to make requests into the Axelar Network from a frontend.

One of our early use cases is a simple transfer of crypto assets across any of our supported chains.

Day 1, this will include:

Supported Assets Supported Blockchain Networks
  • Axelar native tokens
  • LUNA (Terra native tokens)
  • UST (Terra stablecoin)
  • Avalanche
  • Axelar
  • Ethereum
  • Fantom
  • Polygon
  • Terra

The list will continue to grow, as will the use cases of this SDK.

Thank you for your support!

Technical Overview

The Axelar JS SDK is an npm dependency that includes libraries that make requests into the Axelar Network.

  • Any request from the JS SDK is routed through a node rest server that redirects requests through a coordinated collection of microservices controlled by Axelar.
  • These microservices facilitate the relay of cross-chain transactions that run on top of the Axelar Network.
  • See diagram below.

Architecture diagram

Note

This SDK repo is still in early development, and candidly, Axelar's own webapp has been its only consumer so far.

***We expect to continue iterating quickly until the ultimate launch, and there are several (potentially breaking) changes in the hopper including

  • requirements for API keys/tokens for SDK consumers
  • other potential refactoring

Accordingly, please ensure you have the latest and let us know of any issues you encounter using the SDK.

Either reach out to us directly or file a github issue on the repo.

Access Restrictions

Users of this SDK will notice that there is no explicit requirement for frontend users to connect to a Web3 wallet. This is by design and, we believe, an advantage as it relates to the adoption of the SDK and platform.

For the time, being, we have leveraged (among other things) Google's reCAPTCHA v3 authentication mechanism, so any request that goes into our services will need a valid reCAPTCHA v3 token. Read the docs here[https://developers.google.com/recaptcha/docs/v3].

Eventually, we will instill an API-key mechanism for our SDK users.

Onboarding process

Initially, we are gatekeeping the rollout of this SDK a bit as we work through some kinks.

For now, this means that we are whitelisting hosts that can access the APIs and underlying services downstream, i.e. it is restricted by both recaptcha validation and cors settings.

So, our proposed process is as follows:

  1. Install and integrate the API, as shown in the Installation and Getting Started steps below.
  2. Let us know the hostnames you intend to have access the APIs. We will add that to our list of approved domains. Note: API access will shortly be restricted by API keys

Installation

npm i --save @axelar-network/axelarjs-sdk

For the time being, the repo is a private repository that can only be accessed with an NPM token.

** Set your .npmrc file accordingly and secure your NPM TOKEN safely! (i.e. in secrets injected directly into your environment variables)

//registry.npmjs.org/:_authToken=${NPM_TOKEN}

Getting Started

First step, ensure your frontend is equipped with Google's reCAPTCHA v3 authentication mechanism. You can do this by loading the following script with this PUBLIC SITE KEY below.

<script src="https://www.google.com/recaptcha/api.js?render=6LcxwsocAAAAANQ1t72JEcligfeSr7SSq_pDC9vR"></script>

If that works, you should be able to see the grecaptcha object instantiated on the window object.

From there, you can use something like the following snippets to first set up the library consumer and then to instantiate it

For initial setup:

import {
    AssetInfoWithTrace,
    AssetTransferObject,
    CallbackStatus,
    TransferAssetBridge
} from "@axelar-network/axelarjs-sdk";

export class AxelarJSSDKFacade {

    private static environment: string;
    private static axelarJsSDK: TransferAssetBridge;

    constructor(environment: string) {
        AxelarJSSDKFacade.environment = environment;
        AxelarJSSDKFacade.axelarJsSDK = new TransferAssetBridge(AxelarJSSDKFacade.environment);
    }

    public static async transferAssets(
        payload: AssetTransferObject, 
        sourceCbs: CallbackStatus, 
        destCbs: CallbackStatus
    ): Promise<AssetInfoWithTrace> {

        try {
            return AxelarJSSDKFacade.axelarJsSDK.transferAssets(payload, sourceCbs, destCbs, false);
        } catch (e: any) {
            sourceCbs?.failCb();
            throw e;
        }
    }

}

For instantiation and invocation:

    const environment: string = "testnet"; /*environment should be one of local | devnet | testnet*/
    
    const api: AxelarJSSDKFacade = new AxelarJSSDKFacade(environment);
    
    /*set up parmeters here; see sample parameters in `API Usage Details` below for more guidance*/
    const {requestPayload, sourceChainCbs, destinationChainCbs} = getParameters();

    const depositAddress: AssetInfo, traceId: string;
    
    authenticateWithRecaptcha().then(async (recaptchaToken: string) => {
        
        if (recaptchaToken !== null) {
        
            requestPayload.recaptchaToken = recaptchaToken;
        
            try {
                const res: AssetInfoWithTrace = await AxelarJSSDKFacade.axelarJsSDK.transferAssets(
                    requestPayload,
                    {
                        successCb: sourceChainCbs.successCb, 
                        failCb: sourceChainCbs.failCb
                    },{
                        successCb: destinationChainCbs.successCb,
                        failCb: destinationChainCbs.failCb
                    }
                );
                depositAddress = res.assetInfo;
                traceId = res.traceId;
            } catch (e: any) {
                /*
                your error handling here, i.e:            	
                reject("transfer asset api error" + e);
                * */
            }
    
        }
    })

Sample recaptcha authentication

//authenticateWithRecaptcha.ts

    /*This recaptcha public site key is intentionally made public for you to use
    * For more information on Google Recaptcha V3: https://developers.google.com/recaptcha/docs/v3
    * */
    const RECAPTCHA_SITE_KEY: string = "6LcxwsocAAAAANQ1t72JEcligfeSr7SSq_pDC9vR";
    
    declare const grecaptcha: any;

    const authenticateWithRecaptcha = (): Promise<string> => {
        return new Promise((resolve, reject) => {
            grecaptcha.ready(async () => {
                try {
                    const token = await grecaptcha.execute(RECAPTCHA_SITE_KEY);
                    resolve(token);
                } catch (e: any) {
                    /*error handling of failed recaptcha here*/
                }
            });
        });
    }

API Usage Details

The transferAssets method takes three parameters:

  1. requestPayload: a complex struct of type AssetTransferObject
  2. sourceChainCbs: an object of success(/fail) callbacks invoked on a success(/fail) result while attempting to confirm your deposit from the requestPayload on the source chain
  3. destinationChainCbs: an object of success(/fail) callbacks invoked on a success(/fail) result while attempting to confirm your asset on the destination chain

Sample parameters:

// getParameters.ts

const getParameters = () => {
    
    let requestPayload: AssetTransferObject = {
        sourceChainInfo: {
            chainSymbol: "ETH",
            chainName: "Ethereum",
            estimatedWaitTime: 15,
            fullySupported: true,
            assets: [],
            txFeeInPercent: 0.1
        },
        selectedSourceAsset: {
            assetAddress: "NA",
            assetSymbol: "AXL",
            common_key: "uaxl"
        },
        destinationChainInfo: {
            chainSymbol: "FTM",
            chainName: "Fantom",
            estimatedWaitTime: 5,
            fullySupported: true,
            assets: [],
            txFeeInPercent: 0.1
        },
        selectedDestinationAsset: {
            assetAddress: "YOUR_VALID_FANTOM_ADDRESS",
            assetSymbol: "AXL", 
            common_key: "uaxl"
        },
        recaptchaToken: null, // null for now, to be populated in authenticateWithRecaptcha's response callback, as shown above  
        transactionTraceId: "YOUR_OWN_UUID" //your own UUID, helpful for tracing purposes
    }
    
    const sourceChainCbs = {
        successCb: (data: any) => console.log("looks like deposit on the source chain was confirmed by Axelar. data=", JSON.stringify(data)),
        failCb: (data: any) => console.log("sad outcome on the source chain, :-( data=", JSON.stringify(data)),
    }
    const destinationChainCbs = {
        successCb: (data: any) => console.log("good outcome on the destination chain! data=", JSON.stringify(data)),
        failCb: (data: any) => console.log("sad outcome on the destination chain, :-( data=", JSON.stringify(data)),
    }
    
    return {requestPayload, sourceChainCbs, destinationChainCbs} as const;
}

Development

If you like, you can get this repo running locally:

First, clone this repo on your machine, navigate to its location in the terminal and run:

git clone git@github.com:axelarnetwork/axelarjs-sdk.git
npm install
npm run build
npm link # link your local repo to your global packages
npm run dev # build the files and watch for changes

Start coding! 🎉

For issues, file a github issue or feel free to put forward a pull request with a fix/enhancement.