npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

gfx-perp-sdk

v1.3.0

Published

SDK for interacting with GooseFX Perpetual futures trading platform

Downloads

426

Readme

This SDK contains 3 classes to interact with the GooseFX on-chain perpetual futures.

  • Perp
  • Product
  • Trader

The Perp class is required to initialise the connection and wallet that is going to be used for subsequent interaction. Initialising the Perp class should be the first step irrespective of the type of operation in the following manner:

const perp = new Perp(connection, 'mainnet', wallet);
await perp.init();

Product

An instance of the product class signfies one of the perp product we offer to trade. Initialization of the product class can be done in one of two ways:

  1. By index:
const perp = new Perp(connection, 'mainnet', wallet);
await perp.init();
const product = new Product(perp);
product.initByIndex(0);
  1. By name:
const perp = new Perp(connection, 'mainnet', wallet);
await perp.init();
const product = new Product(perp);
product.initByName('SOL-PERP');

This product instance will be useful for the following functions:

  • GET L2 Orderbook: Get the latest layer 2 orderbook
const orderbook = await product.getOrderbookL2();
  • GET L3 Orderbook: Get the latest layer 3 orderbook. (Orders mapped to users)
const orderbook = await product.getOrderbookL3();
  • Subscribe to Orderbook: Subscribe to the orderbook account and listen to changes. In the example below, handleAccountChange is the callback function which will be called on each state change of the orderbook. Pass your function as the parameter to the subscribeToOrderbook function to handle orderbook changes and do not forget to unsubscribe when not needed anymore!
  async function handleAccountChange(){
    const res = await product.getOrderbookL2();
    console.log("Updated orderbook: ", res);
  }
  const subscribeId = product.subscribeToOrderbook(handleAccountChange);
  connection.removeAccountChangeListener(subscribeId); //To close the subscription

Trader

The Trader class is required to get instructions to send transactions to the program. Each wallet must have a unique trader account initialized to be able to place orders and deposit funds. This account needs to be created once using the createTraderAccountIxs instruction. After it has been created once, for all subsequent interactions by the wallet, the Trader class needs to be initialized using the init function.

  • To create a new Trader account on-chain:
  const perp = new Perp(connection, 'mainnet', wallet);
  await perp.init();
  const trader = new Trader(perp);
  const [ixs, signers] = await trader.createTraderAccountIxs();

where ixs is an array of required instructions and signers is an array of required keypairs for signature. The wallet must also sign the transaction along with the keypairs in the signers array

  • Once the account is created successfully, the Trader instance must be initialised in the following way:
  const perp = new Perp(connection, 'mainnet', wallet);
  await perp.init();
  const trader = new Trader(perp);
  await trader.init();

Fractional Datatype

The Fractional data type uses a simple formula to represent a fractional number based on its mantissa (m) and exponent (exp): number = mantissa / (10 ^ exponent)

Trader Instructions

Deposit Funds

To start placing new orders, traders need to deposit some collateral. This instruction will transfer the required USDC from the wallet to the trader account which will be used as collateral to place new orders.

The only parameter to this function is the amount of USDC to be depositted.

  const perp = new Perp(connection, 'mainnet', wallet);
  await perp.init();
  const trader = new Trader(perp);
  await trader.init();
  const ix = await trader.depositFundsIx(new Fractional({
    m: new BN(1),
    exp: new BN(0)
  }));

Withdraw Funds

Similar to deposit funds, this function takes the amount of USDC to be withdrawn as the only parameter. This instruction will transfer funds from the trader account to the wallet address.

  const perp = new Perp(connection, 'mainnet', wallet);
  await perp.init();
  const trader = new Trader(perp);
  await trader.init();
  const ix = await trader.withdrawFundsIx(new Fractional({
    m: new BN(1),
    exp: new BN(0)
  }));

NOTE: The above two instructions do not need a product instance as a parameter since the market is cross collateralized and the amount of USDC deposited can be used across products. The following two instructions to place a new order and cancel an order are specific to products and hence need a product instance as one of the parameters.

Trader's open orders for a prouct

To get all open orders for a Trader for a product:

  const perp = new Perp(connection, 'mainnet', wallet);
  await perp.init();
  const product = new Product(perp);
  product.initByIndex(0);
  const trader = new Trader(perp);
  await trader.init();
  const orderbookData = await trader.getOpenOrders(product);
  console.log("orderbook: ", orderbookData);

New Order

The New order instruction needs the following as parameters

  • Quantity (Fractional) Please note: 1 unit of the product is denoted by 1 * 100000 units. So to buy 1 unit, the parameter to pass as quantity should be
  new Fractional({
    m: new BN(100000),
    exp: new BN(0)
  })
  • Price (Fractional)
  • Order side ('buy' or 'sell')
  • Order Type ('limit', 'market', 'immediateOrCancel', 'postOnly')
  • Product instance
  • Call back ID: A number between 0 and 4294967295 to uniquely identiy the order in trade events
  const perp = new Perp(connection, "mainnet", wallet);
  await perp.init();
  const product = new Product(perp);
  product.initByIndex(0);
  const trader = new Trader(perp);
  await trader.init();
  const ix = await trader.newOrderIx(
    new Fractional({
      m: new BN(10000), //Implies 0.1 units
      exp: new BN(0),
    }),
    new Fractional({
      m: new BN(2245), //Price 22.45$
      exp: new BN(2),
    }),
    "buy",
    "limit",
    product,
    1435
  );

Cancel Order

The cancel order instruction needs the orderId in string format to cancel the order. Use getOpenOrders() to get open orders and its id's to pass as a parameter to cancel the order

  const perp = new Perp(connection, "mainnet", wallet);
  await perp.init();
  const product = new Product(perp);
  product.initByIndex(0);
  const trader = new Trader(perp);
  await trader.init();
  const ix = await trader.cancelOrderIx("7922816251444880503428103912726", product);

Get all Trader addresses

To get the list of all the trader addresses use getAllTraderAddresses() function.

  const perp = new Perp(connection, "mainnet", wallet);
  await perp.init();
  const trader = new Trader(perp);
  await trader.init();
  const traderAddresses = await trader.getAllTraderAddresses()
  console.log(traderAddresses)

Close Trader Risk Group

To close the trader risk group and claim the initial deposited SOL, Use closetrgIx() function.

  const perp = new Perp(connection, "mainnet", wallet);
  await perp.init();
  const product = new Product(perp);
  product.initByIndex(0);
  const trader = new Trader(perp);
  await trader.init();
  const ix = await trader.closetrgIx();

Checkout https://github.com/GooseFX1/gfx-perp-ts-sdk/blob/main/test/index.test.js for examples on the above functionalities! Happy trading!