perpsv3_Go

package module
v0.1.9 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 15, 2023 License: MIT Imports: 12 Imported by: 0

README

perpsv3-Go

This repository contains a Go library for interacting with smart contracts related to a Synthetix V3 DeFi protocol. It includes components to work with Core, Spot Market, and Perps Market contracts deployed on the Optimism mainnet and Optimistic Goerli testnet.

Table of Contents

Getting started

To install a library use:

go get github.com/gateway-fm/perpsv3-Go
go mod tidy

A usage example:

package main

import (
	"log"

	perpsv3_Go "github.com/gateway-fm/perpsv3-Go"
	"github.com/gateway-fm/perpsv3-Go/config"
)

func main() {
	perpsLib, err := perpsv3_Go.Create(config.GetGoerliDefaultPerpsvConfig())
	if err != nil {
		log.Fatal(err)
	}
	//...
}

Configuration

You can use a default configurations. For now only two default configurations are available:

A configuration for Goerli Optimistic testnet:

func GetGoerliDefaultPerpsvConfig() *PerpsvConfig {
	return &PerpsvConfig{
		RPC: "https://rpc.goerli.optimism.gateway.fm",
		ContractAddresses: &ContractAddresses{
			Core:        "0x76490713314fCEC173f44e99346F54c6e92a8E42",
			SpotMarket:  "0x5FF4b3aacdeC86782d8c757FAa638d8790799E83",
			PerpsMarket: "0xf272382cB3BE898A8CdB1A23BE056fA2Fcf4513b",
		},
		FirstContractBlocks: &FirstContractBlocks{
			Core:        11664658,
			SpotMarket:  10875051,
			PerpsMarket: 12708889,
		},
		ConnectionTimeout: time.Second * 30,
		ReadTimeout:       time.Second * 15,
	}
}

And a configuration for Optimism mainnet. Be informed that mainnet configs will return an error at this version due to the luck of Perps Market contract address on mainnnet.

func GetOptimismDefaultPerpsvConfig() *PerpsvConfig {
	return &PerpsvConfig{
		RPC: "https://rpc.optimism.gateway.fm",
		ContractAddresses: &ContractAddresses{
			Core:        "0xffffffaEff0B96Ea8e4f94b2253f31abdD875847",
			SpotMarket:  "0x38908Ee087D7db73A1Bd1ecab9AAb8E8c9C74595",
			PerpsMarket: "",
		},
		FirstContractBlocks: &FirstContractBlocks{
			Core:        94847041,
			SpotMarket:  94846457,
			PerpsMarket: 0,
		},
		ConnectionTimeout: time.Second * 30,
		ReadTimeout:       time.Second * 15,
	}
}

You can use you own configuration by creating a Config instance:

package main

import (
	"log"
	perpsv3_Go "github.com/gateway-fm/perpsv3-Go"
	"github.com/gateway-fm/perpsv3-Go/config"
)

func main() {
	conf := &config.PerpsvConfig{
		RPC: "https://rpc.optimism.gateway.fm",
		//...
	}

	perpsLib, err := perpsv3_Go.Create(conf)
	if err != nil {
		log.Fatal(err)
	}
	//...
}

API Reference

=== Trades ===
== Model ==

Using Trades services you operate with Trades model which represents a OrderSettled event of Perps Market smart-contract with some additional fields:

type Trade struct {
	// Event fields:
	MarketID         uint64          // ID of the market used for the trade
	AccountID        uint64          // ID of the account used for the trade
	FillPrice        *big.Int        // Price at which the order was settled
	PnL              *big.Int        // PL of the previous closed position
	AccruedFunding   *big.Int        // Accrued funding of the previous closed position
	SizeDelta        *big.Int        // Size delta from the order
	NewSize          *big.Int        // New size of the position after settlement
	TotalFees        *big.Int        // Amount of fees collected by the protocol
	ReferralFees     *big.Int        // Amount of fees collected by the referrer
	CollectedFees    *big.Int        // Amount of fees collected by the fee collector
	SettlementReward *big.Int        // Amount of fees collected by the settler
	TrackingCode     [32]byte        // Optional code for integrator tracking purposes
	Settler          common.Address  // Address of the settler of the order
	// Additional fields:
	BlockNumber      uint64          // Block number where the trade was settled
	BlockTimestamp   uint64          // Timestamp of the block where the trade was settled
	TransactionHash  string          // Hash of the transaction where the trade was settled
}
== RetrieveTrades ==

To get trades for specific block range use the RetrieveTrades function:

func RetrieveTrades(fromBlock uint64, toBLock *uint64) ([]*models.Trade, error) {}
  • Default value for fromBlock is a first contract block that you give in the configs
  • Default value for toBlock is a latest blockchain block
  • To use default values set 0 for fromBlock and nil for toBlock
  • For specific block data use same values for fromBlock and toBlock
  • For all contract data use default values
  • For a range of blocks use required block IDs

Warning

If you want to query more than 20 000 block or query old block be sure you use a private PRC provider

== ListenTrades ==

To subscribe on the contract OrederSettled event use the ListenTrades function.

func ListenTrades() (*events.TradeSubscription, error) {}

The goroutine will return events as a Trade model on the TradesChan chanel and errors on the ErrChan chanel. To close the subscription use the Close function.

You can see an example of the usage here:

package main

import (
	"fmt"
	"log"
	"time"

	perpsv3_Go "github.com/gateway-fm/perpsv3-Go"
	"github.com/gateway-fm/perpsv3-Go/config"
)

func main() {
	lib, err := perpsv3_Go.Create(config.GetGoerliDefaultPerpsvConfig())
	if err != nil {
		log.Fatal(err)
	}

	subs, err := lib.ListenTrades()
	if err != nil {
		log.Fatal(err)
	}

	stopChan := make(chan struct{})

	// handle events
	go func() {
		for {
			select {
			case <-stopChan:
				subs.Close()
				return
			case err = <-subs.ErrChan:
				log.Println(err.Error())
			case trade := <-subs.TradesChan:
				fmt.Println(trade.AccountID)
				fmt.Println(trade.AccruedFunding)
			}
		}
	}()

	time.Sleep(10 * time.Second)

	// stop listening
	close(stopChan)

	time.Sleep(5 * time.Second)

}
=== Orders ===
== Model ==

Using Orders services you operate with Orders model which represents a OrderCommitted event of Perps Market smart-contract with some additional fields:

type Order struct {
    // Event fields:
	MarketID        uint64          // ID of the market used for the trade
	AccountID       uint64          // ID of the account used for the trade
    OrderType       uint8           // Represents the transaction type (0 at the time of writing)
	SizeDelta       *big.Int        // Requested change in size of the order
    AcceptablePrice *big.Int        // Maximum or minimum accepted price to settle the order.
    SettlementTime  uint64          // Time at which the order can be settled.
    ExpirationTime  uint64          // Time at which the order expired.
    TrackingCode    [32]byte        // Optional code for integrator tracking purposes.
    Sender          common.Address  // Address of the sender of the order.
    // Additional fields:
    BlockNumber      uint64         // Block number where the trade was settled
    BlockTimestamp   uint64         // Timestamp of the block where the trade was settled
}
== RetrieveOrders ==

To get orders for specific block range use the RetrieveOrders function:

func RetrieveOrders(fromBlock uint64, toBLock *uint64) ([]*models.Order, error) {}
  • Default value for fromBlock is a first contract block that you give in the configs
  • Default value for toBlock is a latest blockchain block
  • To use default values set 0 for fromBlock and nil for toBlock
  • For specific block data use same values for fromBlock and toBlock
  • For all contract data use default values
  • For a range of blocks use required block IDs

Warning

If you want to query more than 20 000 block or query old block be sure you use a private PRC provider

== ListenOrders ==

To subscribe on the contract OrederCommitted event use the ListenOrders function.

func ListenOrders() (*events.OrderSubscription, error) {}

The goroutine will return events as a Order model on the OrdersChan chanel and errors on the ErrChan chanel. To close the subscription use the Close function.

=== MarketUpdate ===
== Model ==

Using MarketData services you operate with MarketUpdate model which represents a MarketUpdated event of Perps Market smart-contract with some additional fields:

type MarketUpdate struct {
	// Event fields
    MarketID               uint64  // ID of the market.
    Price                  uint64  // Price at the time of the event.
    Skew                   int64   // Market skew at the time of the event. Positive values indicate more longs.
    Size                   uint64  // Size of the entire market after settlement.
    SizeDelta              int64   // Change in market size during the update.
    CurrentFundingRate     int64   // Current funding rate of the market.
    CurrentFundingVelocity int64   // Current rate of change of the funding rate.
	// Additional fields
    BlockNumber            uint64  // Block number at which the market data was fetched.
    BlockTimestamp         uint64  // Timestamp of the block at which the market data was fetched.
    TransactionHash        string  // Hash of the transaction where the market update occurred.
}
== RetrieveMarketUpdate ==

To get market update data for specific block range use the RetrieveOrders function:

func RetrieveMarketUpdates(fromBlock uint64, toBLock *uint64) ([]*models.MarketUpdate, error) {}
  • Default value for fromBlock is a first contract block that you give in the configs
  • Default value for toBlock is a latest blockchain block
  • To use default values set 0 for fromBlock and nil for toBlock
  • For specific block data use same values for fromBlock and toBlock
  • For all contract data use default values
  • For a range of blocks use required block IDs

Warning

If you want to query more than 20 000 block or query old block be sure you use a private PRC provider

== ListenMarketUpdate ==

To subscribe on the contract MarketUpdated event use the ListenMarketUpdates function.

func ListenMarketUpdates() (*events.MarketUpdateSubscription, error)

The goroutine will return events as a MarketUpdate model on the MarketUpdateChan chanel and errors on the ErrChan chanel. To close the subscription use the Close function.

=== Positions ===
== Model ==

Using Positions services you operate with Position model which represents a OpenPosition data struct of Perps Market smart-contract with some additional fields:

type Position struct {
	// Data from the contract
	TotalPnl       *big.Int // Represents the total profit and loss for the position
	AccruedFunding *big.Int // Represents the accrued funding for the position
	PositionSize   *big.Int // Represents the size of the position
	// Data from the latest block
	BlockNumber    uint64   // Represents the block number at which the position data was fetched
	BlockTimestamp uint64   // Represents the timestamp of the block at which the position data was fetched
}
== GetPosition ==

To get Position by reading contract with getOpenPosition method use the GetPosition function:

func GetPosition(accountID *big.Int, marketID *big.Int) (*models.Position, error) {}

It will return data from the contract in the latest block. Function can return contract error if the market ID is invalid. If account ID is invalid it will return model with blank fields.

License

This project is licensed under the MIT License.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type IPerpsv3 

type IPerpsv3 interface {
	// RetrieveTrades is used to get logs from the "OrderSettled" event perps market contract within given block range
	//   - use 0 for fromBlock to use default value of a first contract block
	//   - use nil for toBlock to use default value of a last blockchain block
	RetrieveTrades(fromBlock uint64, toBLock *uint64) ([]*models.Trade, error)

	// RetrieveTradesLimit is used to get all "OrderSettled" events and their additional data from the contract
	// with given block search limit. If given limit is 0 function will set default value to 20 000 blocks
	RetrieveTradesLimit(limit uint64) ([]*models.Trade, error)

	// RetrieveOrders is used to get logs from the "OrderCommitted" event perps market contract within given block range
	//   - use 0 for fromBlock to use default value of a first contract block
	//   - use nil for toBlock to use default value of a last blockchain block
	RetrieveOrders(fromBlock uint64, toBLock *uint64) ([]*models.Order, error)

	// RetrieveOrdersLimit is used to get all "OrderCommitted" events and their additional data from the contract
	// with given block search limit. If given limit is 0 function will set default value to 20 000 blocks
	RetrieveOrdersLimit(limit uint64) ([]*models.Order, error)

	// RetrieveMarketUpdates is used to get logs from the "MarketUpdated" event perps market contract within given block
	// range
	//   - use 0 for fromBlock to use default value of a first contract block
	//   - use nil for toBlock to use default value of a last blockchain block
	RetrieveMarketUpdates(fromBlock uint64, toBLock *uint64) ([]*models.MarketUpdate, error)

	// RetrieveMarketUpdatesBig is used to get logs from the "MarketUpdated" event perps market contract within given block
	// range
	//   - use 0 for fromBlock to use default value of a first contract block
	//   - use nil for toBlock to use default value of a last blockchain block
	// It will return a MarketUpdateBig model with big.Int values
	RetrieveMarketUpdatesBig(fromBlock uint64, toBLock *uint64) ([]*models.MarketUpdateBig, error)

	// RetrieveMarketUpdatesLimit is used to get all "MarketUpdated" events and their additional data from the contract
	// with given block search limit. If given limit is 0 function will set default value to 20 000 blocks
	RetrieveMarketUpdatesLimit(limit uint64) ([]*models.MarketUpdate, error)

	// RetrieveMarketUpdatesBigLimit is used to get all "MarketUpdated" events and their additional data from the contract
	// with given block search limit. If given limit is 0 function will set default value to 20 000 blocks
	// It will return a MarketUpdateBig model with big.Int values
	RetrieveMarketUpdatesBigLimit(limit uint64) ([]*models.MarketUpdateBig, error)

	// RetrieveLiquidations is used to get logs from the "PositionLiquidated" event perps market contract within given block
	// range
	//   - use 0 for fromBlock to use default value of a first contract block
	//   - use nil for toBlock to use default value of a last blockchain block
	RetrieveLiquidations(fromBlock uint64, toBLock *uint64) ([]*models.Liquidation, error)

	// RetrieveLiquidationsLimit is used to get all "PositionLiquidated" events and their additional data from the contract
	// with given block search limit. For most public RPC providers the value for limit is 20 000 blocks
	RetrieveLiquidationsLimit(limit uint64) ([]*models.Liquidation, error)

	// ListenTrades is used to subscribe on the contract "OrderSettled" event. The goroutine will return events on the
	// TradesChan chanel and errors on the ErrChan chanel.
	// To close the subscription use events.TradeSubscription `Close` function
	ListenTrades() (*events.TradeSubscription, error)

	// ListenOrders is used to subscribe on the contract "OrderCommitted" event. The goroutine will return events on the
	// OrdersChan chanel and errors on the ErrChan chanel.
	// To close the subscription use events.OrderSubscription `Close` function
	ListenOrders() (*events.OrderSubscription, error)

	// ListenMarketUpdates is used to subscribe on the contract "MarketUpdated" event. The goroutine will return events
	// on the MarketUpdateChan chanel and errors on the ErrChan chanel.
	// To close the subscription use events.MarketUpdateSubscription `Close` function
	ListenMarketUpdates() (*events.MarketUpdateSubscription, error)

	// ListenMarketUpdatesBig is used to subscribe on the contract "MarketUpdated" event. The goroutine will return events
	// on the MarketUpdateChan chanel and errors on the ErrChan chanel.
	// To close the subscription use events.MarketUpdateSubscription `Close` function
	ListenMarketUpdatesBig() (*events.MarketUpdateSubscriptionBig, error)

	// ListenLiquidations is used to subscribe on the contract "PositionLiquidated" event. The goroutine will return events
	// on the LiquidationsChan chanel and errors on the ErrChan chanel.
	// To close the subscription use events.LiquidationSubscription `Close` function
	ListenLiquidations() (*events.LiquidationSubscription, error)

	// GetPosition is used to get position data struct from latest block with given params
	// Function can return contract error if market ID is invalid
	GetPosition(accountID *big.Int, marketID *big.Int) (*models.Position, error)

	// GetMarketMetadata is used to get market metadata by given market ID. Given market id cannot be nil and should exist
	// in the smart contract
	GetMarketMetadata(marketID *big.Int) (*models.MarketMetadata, error)

	// GetMarketSummary is used to get market summary by given market ID. Given market id cannot be nil
	GetMarketSummary(marketID *big.Int) (*models.MarketSummary, error)

	// GetMarketIDs is used to get market IDs from the smart contract
	GetMarketIDs() ([]*big.Int, error)

	// FormatAccount is used to get account, and it's additional data from the contract by given account id
	FormatAccount(id *big.Int) (*models.Account, error)

	// FormatAccounts is used to get all accounts and their additional data from the contract
	FormatAccounts() ([]*models.Account, error)

	// FormatAccountsLimit is used to get all accounts and their additional data from the contract with given block search
	// limit. For most public RPC providers the value for limit is 20 000 blocks
	FormatAccountsLimit(limit uint64) ([]*models.Account, error)

	// Config is used to get current lib config
	Config() *config.PerpsvConfig

	// Close used to stop the lib work
	Close()
}

IPerpsv3 is an interface for perpsv3 lib

func Create 

func Create(conf *config.PerpsvConfig) (IPerpsv3, error)

Create used to get Perpsv3 instance with given configuration settings

type Perpsv3 

type Perpsv3 struct {
	// contains filtered or unexported fields
}

Perpsv3 is a main perpsv3 lib object, it is implementing IPerpsv3 interface

func (*Perpsv3) Close 

func (p *Perpsv3) Close()

func (*Perpsv3) Config added in v0.0.2 

func (p *Perpsv3) Config() *config.PerpsvConfig

func (*Perpsv3) FormatAccount added in v0.1.2 

func (p *Perpsv3) FormatAccount(id *big.Int) (*models.Account, error)

func (*Perpsv3) FormatAccounts added in v0.1.2 

func (p *Perpsv3) FormatAccounts() ([]*models.Account, error)

func (*Perpsv3) FormatAccountsLimit added in v0.1.2 

func (p *Perpsv3) FormatAccountsLimit(limit uint64) ([]*models.Account, error)

func (*Perpsv3) GetMarketIDs added in v0.1.7 

func (p *Perpsv3) GetMarketIDs() ([]*big.Int, error)

func (*Perpsv3) GetMarketMetadata added in v0.1.6 

func (p *Perpsv3) GetMarketMetadata(marketID *big.Int) (*models.MarketMetadata, error)

func (*Perpsv3) GetMarketSummary added in v0.1.7 

func (p *Perpsv3) GetMarketSummary(marketID *big.Int) (*models.MarketSummary, error)

func (*Perpsv3) GetPosition added in v0.0.2 

func (p *Perpsv3) GetPosition(accountID *big.Int, marketID *big.Int) (*models.Position, error)

func (*Perpsv3) ListenLiquidations added in v0.1.3 

func (p *Perpsv3) ListenLiquidations() (*events.LiquidationSubscription, error)

func (*Perpsv3) ListenMarketUpdates added in v0.1.1 

func (p *Perpsv3) ListenMarketUpdates() (*events.MarketUpdateSubscription, error)

func (*Perpsv3) ListenMarketUpdatesBig added in v0.1.9 

func (p *Perpsv3) ListenMarketUpdatesBig() (*events.MarketUpdateSubscriptionBig, error)

func (*Perpsv3) ListenOrders added in v0.1.0 

func (p *Perpsv3) ListenOrders() (*events.OrderSubscription, error)

func (*Perpsv3) ListenTrades 

func (p *Perpsv3) ListenTrades() (*events.TradeSubscription, error)

func (*Perpsv3) RetrieveLiquidations added in v0.1.3 

func (p *Perpsv3) RetrieveLiquidations(fromBlock uint64, toBLock *uint64) ([]*models.Liquidation, error)

func (*Perpsv3) RetrieveLiquidationsLimit added in v0.1.3 

func (p *Perpsv3) RetrieveLiquidationsLimit(limit uint64) ([]*models.Liquidation, error)

func (*Perpsv3) RetrieveMarketUpdates added in v0.1.1 

func (p *Perpsv3) RetrieveMarketUpdates(fromBlock uint64, toBLock *uint64) ([]*models.MarketUpdate, error)

func (*Perpsv3) RetrieveMarketUpdatesBig added in v0.1.8 

func (p *Perpsv3) RetrieveMarketUpdatesBig(fromBlock uint64, toBLock *uint64) ([]*models.MarketUpdateBig, error)

func (*Perpsv3) RetrieveMarketUpdatesBigLimit added in v0.1.8 

func (p *Perpsv3) RetrieveMarketUpdatesBigLimit(limit uint64) ([]*models.MarketUpdateBig, error)

func (*Perpsv3) RetrieveMarketUpdatesLimit added in v0.1.4 

func (p *Perpsv3) RetrieveMarketUpdatesLimit(limit uint64) ([]*models.MarketUpdate, error)

func (*Perpsv3) RetrieveOrders added in v0.1.0 

func (p *Perpsv3) RetrieveOrders(fromBlock uint64, toBLock *uint64) ([]*models.Order, error)

func (*Perpsv3) RetrieveOrdersLimit added in v0.1.4 

func (p *Perpsv3) RetrieveOrdersLimit(limit uint64) ([]*models.Order, error)

func (*Perpsv3) RetrieveTrades 

func (p *Perpsv3) RetrieveTrades(fromBlock uint64, toBLock *uint64) ([]*models.Trade, error)

func (*Perpsv3) RetrieveTradesLimit added in v0.1.4 

func (p *Perpsv3) RetrieveTradesLimit(limit uint64) ([]*models.Trade, error)

Source Files

View all Source files

Directories

Path Synopsis
contracts
coreGoerli
coreOptimism
perpsMarketGoerli
sUSDTGoerli
spotMarketGoerli
spotMarketOptimism
mocks
events
Package mock_events is a generated GoMock package.
 Package mock_events is a generated GoMock package.
service
Package mock_services is a generated GoMock package.
 Package mock_services is a generated GoMock package.
pkg
logger
utils
getAbis
testing-contracts/perps-test
testing-contracts/perps-test/src

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.