# 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 ```bash # 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 ```typescript 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 ```typescript type Currency = "Unknown" | "Usd" | "EQ" | "Eth" | "Btc" | "Eos" | "Dot"; type UserGroup = "Unknown" | "Balances" | "Bailsman"; 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; } ``` ## 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](https://github.com/polkadot-js/extension/tree/master/packages/extension-dapp) ### 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](https://polkadot.js.org/api/start/api.query.multi.html) ### getNonce(address: string): Promise<Index> Fetch next available nonce for this address ## API Storage queries Storage queries are compliant with [Polkadot.JS storage interfaces](https://polkadot.js.org/docs/api/cookbook/storage) ### 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 ### getPrices(key1: Currency, key2: PricePeriod): Promise<Vec> _Testnet only_ Pallet storage - vectors of prices for every `Currency` for each `PricePeriod` ### 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 - the statement kind that must be signed, if any ### 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_ Pallet storage - stores user groups ### aggregatesByGroup(key1: UserGroup, key2: Currency): Promise<TotalAggregates> _Testnet only_ Pallet storage - stores aggregates for each user group ## API Transaction methods Transaction methods are compliant with [Polkadot.JS transaction interfaces](https://polkadot.js.org/docs/api/cookbook/tx) ### setBailsman(isBailsman: boolean): _SubmittableExtrinsic_ _Testnet only_ Sets the bailsman group to the _sender account_ ### 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_ ### 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.