api

README

Conventions Followed in datanode/api Code Implementation

Errors

For all types of errors that are handled in the datanode/api scope, please use errors part of the package. Example:

return nil, apiError(codes.InvalidArgument, ErrMalformedRequest)

The purpose is to have a common way of handling error reporting outside of the core component and keep them clean and simple. Some gradual refactoring work on places where the above is not yet applied is welcomed, though as a friendly and respectful reminder - please consider not breaking the current state.

Documentation

Overview

Package api contains code for running the gRPC server.

In order to add a new gRPC endpoint, add proto content (rpc call, request and response messages), then add the endpoint function implementation in `api/somefile.go`. Example:

func (s *tradingService) SomeNewEndpoint(
    ctx context.Context, req *protoapi.SomeNewEndpointRequest,
) (*protoapi.SomeNewEndpointResponse, error) {
    /* Implementation goes here */
    return &protoapi.SomeNewEndpointResponse{/* ... */}, nil
}

Add a test for the newly created endpoint in `api/trading_test.go`.

Index

• Variables
• func ErrorMap() map[string]int32
• type BlockService
• type Config
  • func NewDefaultConfig() Config
• type CoreServiceClient
• type DeHistoryService
• type EventService
• type GRPCServer
  • func NewGRPCServer(log *logging.Logger, config Config, coreServiceClient CoreServiceClient, ...) *GRPCServer
  • func (g *GRPCServer) ReloadConf(cfg Config)
  • func (g *GRPCServer) Start(ctx context.Context, lis net.Listener) error
• type GetBlockFunc
• type GetStateFunc
• type VegaCoreServiceClient
  • func NewVegaCoreServiceClient(coreServiceClient vegaprotoapi.CoreServiceClient, getState GetStateFunc) *VegaCoreServiceClient
  • func (c VegaCoreServiceClient) GetState() connectivity.State

Variables

var (
	// ErrChainNotConnected signals to the user that he cannot access a given endpoint
	// which require the chain, but the chain is actually offline.
	ErrChainNotConnected = errors.New("chain not connected")
	// ErrChannelClosed signals that the channel streaming data is closed.
	ErrChannelClosed = errors.New("channel closed")
	// ErrEmptyMissingMarketID signals to the caller that the request expected a
	// market id but the field is missing or empty.
	ErrEmptyMissingMarketID = errors.New("empty or missing market ID")
	// ErrEmptyMissingOrderID signals to the caller that the request expected an
	// order id but the field is missing or empty.
	ErrEmptyMissingOrderID = errors.New("empty or missing order ID")
	// ErrEmptyMissingOrderReference signals to the caller that the request expected an
	// order reference but the field is missing or empty.
	ErrEmptyMissingOrderReference = errors.New("empty or missing order reference")
	// ErrEmptyMissingPartyID signals to the caller that the request expected a
	// party id but the field is missing or empty.
	ErrEmptyMissingPartyID = errors.New("empty or missing party ID")
	// ErrEmptyMissingSinceTimestamp signals to the caller that the request expected a
	// timestamp but the field is missing or empty.
	ErrEmptyMissingSinceTimestamp = errors.New("empty or missing since-timestamp")
	// ErrServerShutdown signals to the client that the server  is shutting down.
	ErrServerShutdown = errors.New("server shutdown")
	// ErrStreamClosed signals to the users that the grpc stream is closing.
	ErrStreamClosed = errors.New("stream closed")
	// ErrStreamInternal signals to the users that the grpc stream has an internal problem.
	ErrStreamInternal = errors.New("internal stream failure")
	// ErrNotMapped is when an error cannot be found in the current error map/lookup table.
	ErrNotMapped = errors.New("error not found in error lookup table")
	// ErrInvalidMarketID signals that the market ID does not exists.
	ErrInvalidMarketID = errors.New("invalid market ID")
	// ErrMissingOrder signals that the actual payload is expected to contains an order.
	ErrMissingOrder = errors.New("missing order in request payload")
	// ErrMissingPartyID signals that the payload is expected to contain a party id.
	ErrMissingPartyID = errors.New("missing party id")
	// ErrMalformedRequest signals that the request was malformed.
	ErrMalformedRequest = errors.New("malformed request")
	// ErrMissingAsset signals that an asset was required but not specified.
	ErrMissingAsset = errors.New("missing asset")
	// ErrSubmitOrder is returned when submitting an order fails for some reason.
	ErrSubmitOrder = errors.New("submit order failure")
	// ErrAmendOrder is returned when amending an order fails for some reason.
	ErrAmendOrder = errors.New("amend order failure")
	// ErrCancelOrder is returned when cancelling an order fails for some reason.
	ErrCancelOrder = errors.New("cancel order failure")
	// OrderService...
	ErrOrderServiceGetByMarket      = errors.New("failed to get orders for market")
	ErrOrderServiceGetByMarketAndID = errors.New("failed to get orders for market and ID")
	ErrOrderServiceGetByParty       = errors.New("failed to get orders for party")
	ErrOrderServiceGetByReference   = errors.New("failed to get orders for reference")
	ErrMissingOrderIDParameter      = errors.New("missing orderID parameter")
	ErrOrderNotFound                = errors.New("order not found")
	// TradeService...
	ErrTradeServiceGetByParty          = errors.New("failed to get trades for party")
	ErrTradeServiceGetByMarket         = errors.New("failed to get trades for market")
	ErrTradeServiceGetPositionsByParty = errors.New("failed to get positions for party")
	ErrTradeServiceGetByOrderID        = errors.New("failed to get trades for order ID")
	// MarketService...
	ErrMarketServiceGetMarkets    = errors.New("failed to get markets")
	ErrMarketServiceGetByID       = errors.New("failed to get market for ID")
	ErrMarketServiceGetDepth      = errors.New("failed to get market depth")
	ErrMarketServiceGetMarketData = errors.New("failed to get market data")
	// AccountService...
	ErrAccountServiceListAccounts         = errors.New("failed to get accounts")
	ErrAccountServiceSQLStoreNotAvailable = errors.New("sql balance store for accounts not available")
	ErrAccountServiceGetMarketAccounts    = errors.New("failed to get market accounts")
	// AccountService...
	ErrAccountServiceGetFeeInfrastructureAccounts = errors.New("failed to get fee infrastructure accounts")
	ErrAccountServiceGetGlobalRewardPoolAccounts  = errors.New("failed to get global reward pool accounts")
	ErrAccountServiceGetPartyAccounts             = errors.New("failed to get party accounts")
	// RiskService...
	ErrRiskServiceGetMarginLevelsByID = errors.New("failed to get margin levels")
	ErrInvalidOrderSide               = errors.New("invalid order side")
	// CandleService...
	ErrCandleServiceGetCandleData       = errors.New("failed to get candle data")
	ErrCandleServiceSubscribeToCandles  = errors.New("failed to subscribe to candle data")
	ErrCandleServiceGetCandlesForMarket = errors.New("failed to get candles for market")
	// PartyService...
	ErrPartyServiceGetAll  = errors.New("failed to get parties")
	ErrPartyServiceGetByID = errors.New("failed to get party for ID")
	// TimeService...
	ErrTimeServiceGetTimeNow = errors.New("failed to get time now")
	// Blockchain...
	ErrBlockchainBacklogLength = errors.New("failed to get backlog length from blockchain")
	ErrBlockchainNetworkInfo   = errors.New("failed to get network info from blockchain")
	ErrBlockchainGenesisTime   = errors.New("failed to get genesis time from blockchain")
	ErrBlockchainChainID       = errors.New("failed to get chain ID from blockchain")
	// ErrMissingProposalID returned if proposal with this id is missing.
	ErrMissingProposalID = errors.New("missing proposal id")
	// ErrMissingProposalReference returned if proposal with this reference is not found.
	ErrMissingProposalReference = errors.New("failed to find proposal with the reference")
	// ErrMissingWithdrawalID is returned when the withdrawal ID is missing from the request.
	ErrMissingWithdrawalID = errors.New("missing withdrawal ID")
	// ErrMissingOracleSpecID is returned when the ID is missing from the request.
	ErrMissingOracleSpecID = errors.New("missing oracle spec ID")
	// ErrOracleServiceSpecID is returned when there was no data foind for the given ID.
	ErrOracleServiceGetSpec = errors.New("failed retrieve data for oracle spec")
	// ErrMissingDepositID is returned when the deposit ID is missing from the request.
	ErrMissingDepositID = errors.New("missing deposit ID")
	// ErrMissingAssetID is returned when the Asset ID is missing from the request.
	ErrMissingAssetID = errors.New("missing asset ID")
	// Network Limits...
	ErrGetNetworkLimits = errors.New("failed to get network limits")
	// Rewards.
	ErrGetRewards = errors.New("failed to get rewards")
	// Decentralized History.
	ErrGetActivePeerAddresses      = errors.New("failed to get active peer addresses")
	ErrGetMostRecentHistorySegment = errors.New("failed to get most recent history segment")
	ErrListAllDeHistorySegment     = errors.New("failed to list all history segments")
	ErrFetchDeHistorySegment       = errors.New("failed to fetch segment")
)

API Errors and descriptions.

Functions

func ErrorMap

func ErrorMap() map[string]int32

ErrorMap returns a map of error to code, which is a mapping between API errors and Vega API specific numeric codes.

Types

type BlockService

type BlockService interface {
	GetLastBlock(ctx context.Context) (entities.Block, error)
}

BlockService ...

type Config

type Config struct {
	Level            encoding.LogLevel `long:"log-level"`
	Timeout          encoding.Duration `long:"timeout"`
	Port             int               `long:"port"`
	WebUIPort        int               `long:"web-ui-port"`
	WebUIEnabled     encoding.Bool     `long:"web-ui-enabled"`
	Reflection       encoding.Bool     `long:"reflection"`
	IP               string            `long:"ip"`
	StreamRetries    int               `long:"stream-retries"`
	CoreNodeIP       string            `long:"core-node-ip"`
	CoreNodeGRPCPort int               `long:"core-node-grpc-port"`
}

Config represents the configuration of the api package.

func NewDefaultConfig

func NewDefaultConfig() Config

NewDefaultConfig creates an instance of the package specific configuration, given a pointer to a logger instance to be used for logging within the package.

type CoreServiceClient

type CoreServiceClient interface {
	protoapi.CoreServiceClient
	GetState() connectivity.State
}

CoreServiceClient ...

type DeHistoryService

type DeHistoryService interface {
	GetHighestBlockHeightHistorySegment() (store.SegmentIndexEntry, error)
	ListAllHistorySegments() ([]store.SegmentIndexEntry, error)
	FetchHistorySegment(ctx context.Context, historySegmentID string) (store.SegmentIndexEntry, error)
	GetActivePeerAddresses() []string
}

DeHistoryService ...

type EventService

type EventService interface {
	ObserveEvents(ctx context.Context, retries int, eTypes []events.Type, batchSize int, filters ...subscribers.EventFilter) (<-chan []*eventspb.BusEvent, chan<- int)
}

EventService ...

type GRPCServer

type GRPCServer struct {
	Config
	// contains filtered or unexported fields
}

GRPCServer represent the grpc api provided by the vega node.

func NewGRPCServer

func NewGRPCServer(
	log *logging.Logger,
	config Config,
	coreServiceClient CoreServiceClient,
	eventService *subscribers.Service,
	orderService *service.Order,
	networkLimitsService *service.NetworkLimits,
	marketDataService *service.MarketData,
	tradeService *service.Trade,
	assetService *service.Asset,
	accountService *service.Account,
	rewardService *service.Reward,
	marketsService *service.Markets,
	delegationService *service.Delegation,
	epochService *service.Epoch,
	depositService *service.Deposit,
	withdrawalService *service.Withdrawal,
	governanceService *service.Governance,
	riskFactorService *service.RiskFactor,
	riskService *service.Risk,
	networkParameterService *service.NetworkParameter,
	blockService BlockService,
	checkpointService *service.Checkpoint,
	partyService *service.Party,
	candleService *candlesv2.Svc,
	oracleSpecService *service.OracleSpec,
	oracleDataService *service.OracleData,
	liquidityProvisionService *service.LiquidityProvision,
	positionService *service.Position,
	transferService *service.Transfer,
	stakeLinkingService *service.StakeLinking,
	notaryService *service.Notary,
	multiSigService *service.MultiSig,
	keyRotationService *service.KeyRotations,
	ethereumKeyRotationService *service.EthereumKeyRotation,
	nodeService *service.Node,
	marketDepthService *service.MarketDepth,
	ledgerService *service.Ledger,
	protocolUpgradeService *service.ProtocolUpgrade,
	deHistoryService DeHistoryService,
) *GRPCServer

NewGRPCServer create a new instance of the GPRC api for the vega node.

func (*GRPCServer) ReloadConf

func (g *GRPCServer) ReloadConf(cfg Config)

ReloadConf update the internal configuration of the GRPC server.

func (*GRPCServer) Start

func (g *GRPCServer) Start(ctx context.Context, lis net.Listener) error

Start start the grpc server. Uses default TCP listener if no provided.

type GetBlockFunc

type GetBlockFunc func(context.Context) (entities.Block, error)

type GetStateFunc

type GetStateFunc func() connectivity.State

type VegaCoreServiceClient

type VegaCoreServiceClient struct {
	vegaprotoapi.CoreServiceClient
	// contains filtered or unexported fields
}

func NewVegaCoreServiceClient

func NewVegaCoreServiceClient(coreServiceClient vegaprotoapi.CoreServiceClient, getState GetStateFunc) *VegaCoreServiceClient

func (VegaCoreServiceClient) GetState

func (c VegaCoreServiceClient) GetState() connectivity.State