starkware-libs / starkex-js

JavaScript SDK for StarkEx

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.

starkex-js's Issues

Using string for transaction id instead of number

Is your feature request related to a problem? Please describe.
Transaction id will be very very big for a period of time. It should be send to starkEx as a string. Can cause overflow.

Describe the solution you'd like
Receive string for transaction id instead of number.

How to connect to mainnet?

Hello guys,
What is the endpoint to connect to the off-chain StarkEx service? Couldn't find it anywhere.
Best,

error TypeError: Cannot read properties of undefined (reading 'vaultRoot')

Cannot read property 'vaultRoot' of undefined in Node Environment

Describe the bug
Runtime error when using the getBatchIds() function

To Reproduce
Steps to reproduce the behavior:

const StarkExAPI = require('@starkware-industries/starkex-js/node');
// (this actually doesn't work either, i have to use: 
// const StarkExAPI = require('../node_modules/@starkware-industries/starkex-js/dist/node');

const batchIds = await starkExAPI.feederGateway.getBatchIds();

// TypeError: Cannot read property 'vaultRoot' of undefined

Expected behavior
Batch ID's returned and no error

Desktop (please complete the following information):

• OS: macOs Catalina 10.15.7
• Node v14.17.6

Make feeLimit in FeeInfoUserRequest as NumericSequence

Hello Starkex team,

Could you please make feeLimit to NumericSequence as well?

https://github.com/starkware-libs/starkex-js/blob/dev/docs/interfaces/FeeInfoUserRequest.md#feelimit

Thank you!

Add option to pass custom txId to transaction

Cannot find module '@starkware-industries/starkex-js/node'

Describe the bug

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

I get the error: Cannot find module '@starkware-industries/starkex-js/node'

To Reproduce
Steps to reproduce the behavior:

• npm install @starkware-industries/starkex-js
• In NodeJS, using express: const StarkExAPI = require('@starkware-industries/starkex-js/node');
• See error: Error: Cannot find module '@starkware-industries/starkex-js/node'

Expected behavior
require('@starkware-industries/starkex-js/node') should return package.

var StarkExAPI = require('@starkware-industries/starkex-js seems to work.

Screenshots

Desktop (please complete the following information):

• OS: macOS 11.6
• Browser: Chrome
• Version 98.0.4758.102

Additional context
I just want to build with StarkEx!