@equilab/api

EQUILIBRIUM API

API bindings to access Equilibruim substrate queries and transactions
NOTE Typescript bindings included

Equilibrium node list

• Mainnet node: wss://tge.equilibrium.io:9944
• Testnet node: wss://api.mvp.testnet.equilibrium.io (this node implements latest features)

Getting started

# Testnet version
$ npm i --save @equilab/api     # if you are using npm or  
$ yarn add @equilab/api         # for yarn package manager  

# Mainnet version
$ npm i --save @equilab/api@tge  
$ yarn add @equilab/api@tge       

Usage

API Init

Use createApi(node: string) factory from @equilab/api package

import { createApi } from "@equilab/api";  

(async () => { // async/await usage
  // Connect to TGE node with websocket
  const api = await createApi("wss://tge.equilibrium.io:9944");
  // do the interaction below
  const balance = await api.getBalance("YOUR_ADDRESS", "EQ"); // get EQ tokens
  console.log(balance.toJSON());
})();

createApi("wss://tge.equilibrium.io:9944")
  .then(api => api.getBalance("YOUR_ADDRESS", "EQ"))
  .then(balance => console.log(balance.toJSON())); // Promise usage

Types

type Currency = "Unknown" | "Usd" | "EQ" | "Eth" | "Btc" | "Eos" | "Dot";
type UserGroup = "Unknown" | "Balances" | "Bailsmen" | "Borrowers" | "Lenders";
type UnsubscribePromise = Promise<() => void /* call this func to unsubscribe */>;

interface SignedBalance {
  readonly isPositive: boolean;
  readonly asPositive: Balance;
  readonly isNegative: boolean;
  readonly asNegative: Balance;
}

interface DataPoint {
  price: u64;
  account_id: AccountId;
  block_number: BlockNumber;
  timestamp: u64;
}

interface PricePoint {
  block_number: BlockNumber;
  timestamp: u64;
  price: u64;
  data_points: Vec<DataPoint>;
}

API Methods

getAccounts(): Promise<string[]>

Fetch list of addresses in system

getBlockHash(blockNumber: number): Promise<Hash>

Fetch hash of block by its number

subscribeNewBlockHeads(blockHandler: (header: BlockHeader) => Promise<void> | void): UnsubscribePromise

Retrieves the best finalized header via subscription

setSigner(signer: Signer): void

Sets transaction signer, can be used with injected wallet

multi(calls: QueryableStorageMultiArg<"promise">[], callback: (result: Codec[]) => void | Promise<void>): UnsubscribePromise

Allows for the querying of multiple storage entries and the combination thereof into a single result. This is a very optimal way to make multiple queries since it only makes a single connection to the node and retrieves the data over one subscription. Refer to multiple queries section of polkadot.js api docs

getNonce(address: string): Promise<Index>

Fetch next available nonce for this address

API Storage queries

Storage queries are compliant with Polkadot.JS storage interfaces

getBalance(key1: AccountId, key2: Currency): Promise<SignedBalance>

Pallet storage - balances for all accounts

getRate(key: Currency): Promise<PricePoint>

Testnet only
Pallet storage for added price points

getVested(key: AccountId): Promise<BalanceOf>

Pallet storage: information about already vested balances for given account

getVesting(key: AccountId): Promise<VestingInfo>

Pallet storage: information regarding the vesting of a given account

getClaim(key: EthereumAddress): Promise<BalanceOf>

Pallet storage - stores amount to be claimed by each EthereumAddress

getClaimSigning(key: EthereumAddress): Promise<bool>

Pallet storage - stores Ethereum addresses from which additional statement
singing is required

getClaimVesting(key: EthereumAddress): Promise<(BalanceOf,BalanceOf,BlockNumber)>

Pallet storage - vesting schedule for a claim.
First balance is the total amount that should be held for vesting.
Second balance is how much should be unlocked per block.
The block number is when the vesting should start.

getTotalClaim(): Promise<BalanceOf>

Pallet storage - total Claims amount

hasGroup(key1: UserGroup, key2: AccountId): Promise<bool>

Testnet only

aggregatesByGroup(key1: UserGroup, key2: Currency): Promise<TotalAggregates>

Testnet only
Pallet storage - stores aggregates for each user group

getAddress(key1: AccountId, key2: SubAccType): Promise<AccountId>

Pallet storage - double map storing subaccounts as AccountId where
user's main AccountId and SubAccType used as keys

getOwner(key: AccountId): Promise<(AccountId,SubAccType)>

Pallet storage - a map storing a tuple (AccountId, SubAccType)
for each existing subaccount. First element in stored tuple is
AccountId of main user account, owning the subaccount and second
is SubAccType of key subaccount

getMetrics(): Promise<FinancialMetrics>

Financial metrics for all known assets.

API Transaction methods

Transaction methods are compliant with Polkadot.JS transaction interfaces

transfer(currency: Currency,to: AccountId,value: Balance,): SubmittableExtrinsic

Testnet only
Transfers value amount of currency from trx sender to account id to

sudo(call: Call,): SubmittableExtrinsic

Authenticates the sudo key and dispatches a function call with Root origin.

The dispatch origin for this call must be Signed.

• O(1).
• Limited storage reads.
• One DB write (event).
• Weight of derivative call execution + 10,000.

setPrice(currency: Currency,price: FixedI64,): SubmittableExtrinsic

Testnet only
Adds new DataPoint containing currency price information. It
would be used for PricePoint calculation. Only whitelisted
accounts can add DataPoints

vest(): SubmittableExtrinsic

Unlock any vested funds of the sender account.

The dispatch origin for this call must be Signed and the sender must have funds still
locked under this module.

Emits either VestingCompleted or VestingUpdated.

vestTo(target: LookupSource,): SubmittableExtrinsic

Unlock any vested funds of a target account.

The dispatch origin for this call must be Signed.

• target: The account whose vested funds should be unlocked. Must have funds still
  locked under this module.

Emits either VestingCompleted or VestingUpdated.

claim(dest: AccountId,ethereum_signature: EcdsaSignature,): SubmittableExtrinsic

Make a claim to collect your currency.

The dispatch origin for this call must be None.

Unsigned Validation:
A call to claim is deemed valid if the signature provided matches
the expected signed message of:

Ethereum Signed Message:
(configured prefix string)(address)

and address matches the dest account.

Parameters:

• dest: The destination account to payout the claim.

• ethereum_signature: The signature of an ethereum signed message
  matching the format described above.

claimAttest(dest: AccountId,ethereum_signature: EcdsaSignature,statement: Bytes,): SubmittableExtrinsic

Make a claim to collect your currency by signing a statement.

The dispatch origin for this call must be None.

Unsigned Validation:
A call to claim_attest is deemed valid if the signature provided matches
the expected signed message of:

Ethereum Signed Message:
(configured prefix string)(address)(statement)

and address matches the dest account; the statement must match that which is
expected according to your purchase arrangement.

Parameters:

• dest: The destination account to payout the claim.

• ethereum_signature: The signature of an ethereum signed message
  matching the format described above.

• statement: The identity of the statement which is being attested to in the signature.

transferFrom(subacc_type: SubAccType,currency: Currency,amount: Balance,): SubmittableExtrinsic

Transfers amount of currency from subaccount to main account. If subacc_type
is Bailsman and it's total collateral value becomes less than minimal bailsman
collateral value - subaccount will be unregistered as bailsman.

transferTo(subacc_type: SubAccType,currency: Currency,value: Balance,): SubmittableExtrinsic

Transfers value amount of currency from main account to subacc_type subaccount

withdrawExternal(amount: Balance,recipient: Bytes,dest_id: ChainId,resource_id: ResourceId,): SubmittableExtrinsic

Transfers some amount of the native token to some recipient on a (whitelisted) destination chain.
Charges fee and accumulates it on the special account.