@sonicdex/sonic-js
v0.4.2
Published
Sonic-js is a library that holds an API for interacting with Swap Canister
Downloads
26
Readme
⚠️ 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
Table of Contents
Getting Started
Install 🛠️
npm install @sonicdex/sonic-js
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 createagent
andactors
. The object needs to follow the interfaceActorAdapter.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 interfaceActorAdapter.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:
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:
Utils 💼
The Utils module holds functions that have general propose usage. The available functions are:
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.
Token
Declared types that are used to represent tokens.
Pair
Declared types that are used to represent Sonic swap pairs.
Default
An object that stores the default values used inside the library.