Skip to content

Latest commit

 

History

History
236 lines (172 loc) · 6.19 KB

README.md

File metadata and controls

236 lines (172 loc) · 6.19 KB
Raw

JavaScript SDK for StarkEx

starkex-js is a JavaScript wrapper around the StarkEx API that can be used in both NodeJS and Browser environments.

starkex-js is written in ECMAScript6 and strongly typed and transpiled to ECMAScript5 using TypeScript.

Installation

This package is Typescript ready

// using npm
npm i @starkware-industries/starkex-js

// using yarn
yarn add @starkware-industries/starkex-js

How to use it

The library is a default export.

Browser

To use it browser, you need to use the code from browser.js file.

<script src="path-to-local-library/browser.js"></script>

or via CDN

<script src="https://path-to-cdn-library/browser.js"></script>

In this scenario, the library will be bound to the global window object with the property StarkExAPI.

window.StarkExAPI or simple StarkExAPI can be used to access the library.

If you have a toolchain available you can use an import statement.

import StarkExAPI from '@starkware-industries/starkex-js/browser';
const StarkExAPI = require('@starkware-industries/starkex-js/browser');

Because is a default export, here you can import it with what name you want

Node

For NodeJS environment, just replace browser with node

import StarkExAPI from 'starkex-js/node';
const StarkExAPI = require('@starkware-industries/starkex-js/node');

Usage

The object imported is a class that first needs to be instantiated:

new StarkExAPI(config: StarkExClientConfig): StarkExClient;

Where config is a configuration object of form:

interface StarkExClientConfig {
  endpoint: string;
  // optional - relevant only for node environment
  certs?: {
    cert: string;
    key: string;
    ca?: string;
  };
}

Example

const starkExAPI = new StarkExAPI({
  endpoint: 'https://gw.playground-v2.starkex.co'
});

Example with certs (NodeJS environment)

const starkExAPI = new StarkExAPI({
  endpoint: 'https://playground.starkex.co',
  certs: {
    cert: 'USER_CERT',
    key: 'USER_KEY'
  }
});

The StarkExClient object returned from the constructor exposing the different gateways existing on this API:

public gateway: Gateway

This is the StarkEx Services HTTP gateway version2 for all external trading interactions.

Example for is_alive

const isAlive = await starkExAPI.gateway.isAlive();
console.log(isAlive); // gateway is alive!

Example for get_first_unused_tx_id

const txId = await starkExAPI.gateway.getFirstUnusedTxId();
console.log(txId); // 69

Example for a DepositRequest

const request = {
  txId: 10234993,
  amount: "4029557120079369747",
  starkKey: "0x7c65c1e82e2e662f728b4fa42485e3a0a5d2f346baa9455e3e70682c2094cac",
  tokenId: "0x2dd48fd7a024204f7c1bd874da5e709d4713d60c8a70639eb1167b367a9c378",
  vaultId: 1654615998
};
const response = await starkExAPI.gateway.deposit(request);
console.log(response); // {txId: 10234993, code: "TRANSACTION_PENDING"}

Example for a MultiTransactionRequest

const response = await starkExClient.gateway.multiTransaction({
  txId: 10234994,
  txs: [
    {
      type: StarkExClient.GatewayRequestType.DEPOSIT_REQUEST,
      amount: "4029557120079369747",
      starkKey: "0x7c65c1e82e2e662f728b4fa42485e3a0a5d2f346baa9455e3e70682c2094cac",
      tokenId: "0x2dd48fd7a024204f7c1bd874da5e709d4713d60c8a70639eb1167b367a9c378",
      vaultId: 1654615998
    },
    {
      type: StarkExClient.GatewayRequestType.WITHDRAWAL_REQUEST,
      amount: "4029557120079369747",
      starkKey: "0x7c65c1e82e2e662f728b4fa42485e3a0a5d2f346baa9455e3e70682c2094cac",
      tokenId: "0x2dd48fd7a024204f7c1bd874da5e709d4713d60c8a70639eb1167b367a9c378",
      vaultId: 1654615998
    },
  ],
});
console.log(response); // {txId: 10234994, code: "TRANSACTION_PENDING"}

Full API docs for gateway can be found here.

public feederGateway: FeederGateway

This is the StarkEx Services HTTP gateway for feeder interactions. The Feeder is a gateway to the StarkEx system for retrieving transaction batch information by external parties

Example for get_batch_ids

const batchIdsRequest = {
  vaultRoot: '0x46bc9d7b7716bc33b1db5b7509c0a076ab9424ba5e16dd26de8097a62f1ef1d1',
  orderRoot: '0x84695d9d13ec0eeafc07b7d0c5da3f30e42e468bc69413c2b77e62cd8cdeb9a8',
  sequenceNumber: 5678
};
const batchIds = await starkExAPI.feederGateway.getBatchIds(batchIdsRequest);
console.log(batchIds); // [123, 456]

Full API docs for feederGateway can be found here.

Deprecated functionality

Since StarkEx v4.5, gateway and feeder gateway apis expect to receive http requests for version 2 (v2 prefix inside the request url).

Deprecated functions, that still uses the old version of the StarkEx api (no url prefix), are marked with a DEPRECATED prefix by the SDK. This was done in order to inform the user that even though those methods are still supported by the api, they will be deleted in the next version.

For example, a request to /v2/feeder_gateway/get_batch_info will be made by:

await starkExAPI.feederGateway.getBatchInfo(1);

While:

await starkExAPI.feederGateway.DEPRECATED_getBatchInfo(1);

will make a request to /feeder_gateway/get_batch_info.

Note: All results will be exactly the raw response from the API.

API Docs

Click here for full API documentation.