⚠️ The library is currently under a Beta version. It still a work in progress and can have braking changes through the new version releases.

💬 All feedback is accepted! Set up an issue.

A client library for the Sonic Open Internet Service (OIS), implemented in JavaScript.

The Sonic-js library is utilized to integrate UIs/FEs/Apps to transact with Sonic's Swap Canister on the Internet Computer blockchain.

• Visit our website
• Read Sonics's documentation
• Read our blog

Examples 🔮

Not sure where to start? Take a dive into our sonic-js-example application to checkout what an implementation of Sonic-js looks like!

Table of Contents

• Table of Contents
• Getting Started
  • Install
  • BigNumber
• Usage
  • Integration
    • Agent and Actor
      • Actor Adapter
      • Actor Factories
      • IDLs
    • Swap Canister Controller
  • Math
  • Utils
  • Declarations
    • Types
    • Token
    • Pair
    • Default

Getting Started

Install 🛠️

First we need to setup the .npmrc file to fetch the right package on Github Packages.

To do so, append the following line to your .npmrc file your project's root directory. If you don't have a .npmrc file, create a new one.

@psychedelic:registry=https://npm.pkg.github.com

Now we need to setup our authentication on Github Packages. This step is compulsory, even for public packages.

To do so you're going to need a personal access token with the following configurations:

• repo
• read:packages

Next, authenticate yourself via the npm login command using your Github email for the username and the personal access token as your password:

npm login --registry=https://npm.pkg.github.com --scope=@psychedelic

With an authentication set up, now we need to run:

yarn add @psychedelic/sonic-js

Done! We have installed the package successfully.

Dependencies

BigNumber 🔟

This library relies on BigNumber.js to handle numbers and calculations. It is used because its ease of use and to avoid JavaScript limitations when dealing with large numbers or numbers with many decimal places.

To better deal and present inside your application you can use the cast functions like toString and toNumber.

Some functions were added to BigNumber class prototype because of the high number of utilization inside other of the functions inside the library:

toBigInt(): bigint;

Returns a bigint from a BigNumber

applyDecimals(decimals: number): BigNumber;

Returns a bigint from a BigNumber

removeDecimals(decimals: number): BigNumber;

Removes decimals from a number

applyTolerance(percentage: number, type?: 'min' | 'max'): BigNumber;

Returns the number for a given maximal/minimal tolerance

Usage 👷

This library holds a set of functions and interfaces that helps in the development of applications that interacts with Sonic's canisters.

The library is separated into modules:

Integration ⛓️

The integration module provides functions that helps to interact with Sonic directly.

Agent and Actor

To talk with Internet Computer we need to create actors that communicate with canisters. To create actors we need to first setup an agent that indicates who and how the communication to the Internet Computer netowkr is going to be realized. This library provides some functions that help to establish communication with Swap Canister and DIP20 token canisters by abstracting away actors creation.

Actor Adapter

The class ActorAdapter provides an abstraction of @dfinity/agent that helps to instantiate new actors and reuse them.

The class constructor has params to configure how you want to use the adapter:

• provider: This param receives an object that is used to create agent and actors. The object needs to follow the interface ActorAdapter.Provider. We highly recommended using @psychedelic/plug-inpage-provider if you want to instantiate actors linked to a user:

const adapter = new ActorAdapter(window.ic.plug);

• options: This param is used for selecting some settings of network host and whitelisting canister ids. It follows the interface ActorAdapter.Options:

const adapter = new ActorAdapter(window.ic.plug, {
  host: 'https://boundary.ic0.app/',
  whitelist: ['3xwpq-ziaaa-aaaah-qcn4a-cai'],
});

You can also use default parameters and no provider:

const adapter = new ActorAdapter();

IDLs

All actors that communicate with IC needs to have an IDL to indicate which functions are callable on the canister. The library already provide this IDLs for Swap and DIP20 canisters and they can be found here.

Our Actor Factories make use of these saved IDL's to generate actors for you.

Actor Factories

To make actor creation even easier, Sonic-js provides two functions that automatically create configurable actors for Sonic's Swap canister and any DIP20 canister:

• createSwapActor
• createTokenActor

Swap Canister Controller

The class SwapCanisterController provides methods that give access to the main functionalities of Swap Canister. Instantiation of a non-anonymous controller uses a Swap Actor.

You can create an anonymous controller (not linked to any user):

const swapActor = await createTokenActor();
const controller = new SwapCanisterController(swapActor);

Or adding a custom actor with your adapter:

const swapActor = await createSwapActor({
  actorAdapter: new ActorAdapter(window.ic.plug),
});
const controller = new SwapCanisterController(swapActor);

For a list of the available SwapCanisterController methods, click here.

Math 🖩

The Math module consists of functions used in calculations to be displayed to the user or sent in requests. The module has four available classes, here are links to descriptions of those classes and their available methods:

• Swap
• Liquidity
• Assets
• Price

Utils 💼

The Utils module holds functions that have general propose usage. The available functions are:

• toBigNumber
• toExponential
• formatAmount
• deserialize
• serialize

Declarations 📝

The declarations module provides the default constants used and typescript interfaces to help consuming the library.

Types

Declared types that are used in the overall application to standardize our params.

Find it here.

Token

Declared types that are used to represent tokens.

Find it here.

Pair

Declared types that are used to represent Sonic swap pairs.

Find it here.

Default

An object that stores the default values used inside the library.

Find it here.