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 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 NetworkHistoryService

Variables

var (
	// ErrChannelClosed signals that the channel streaming data is closed.
	ErrChannelClosed = errors.New("channel closed")
	// ErrMissingResourceID signals to the caller that the request expected a
	// resource id but the field is missing or empty.
	ErrMissingResourceID = newInvalidArgumentError("missing resource ID")
	// ErrEmptyMissingMarketID signals to the caller that the request expected a
	// market id but the field is missing or empty.
	ErrEmptyMissingMarketID = newInvalidArgumentError("empty or missing market ID")
	// ErrMissingPrice signals to the caller that the request expected a price.
	ErrMissingPrice = newInvalidArgumentError("missing price")
	// ErrInvalidOrderPrice signals to the caller that the request expected a valid price.
	ErrInvalidOrderPrice = newInvalidArgumentError("invalid order price")
	// 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")
	// ErrMissingPartyID signals that the payload is expected to contain a party id.
	ErrMissingPartyID = newInvalidArgumentError("missing party id")
	// ErrInvalidPagination signals that the pagination is invalid.
	ErrInvalidPagination = newInvalidArgumentError("invalid pagination")
	// ErrInvalidFilter signals that the filter is invalid.
	ErrInvalidFilter = newInvalidArgumentError("invalid filter")
	// ErrMalformedRequest signals that the request was malformed.
	ErrMalformedRequest = newInvalidArgumentError("malformed request")
	// ErrMissingOrderID signals that an order ID was required but not specified.
	ErrMissingOrderID = newInvalidArgumentError("missing orderID parameter")
	// ErrMissingCandleID returned if candle with this id is missing.
	ErrMissingCandleID = newInvalidArgumentError("candle id is a required parameter")
	// ErrMissingProposalID returned if proposal with this id is missing.
	ErrMissingProposalID = newInvalidArgumentError("proposal id is a required parameter")
	// ErrMissingProposalIDAndPartyID returned if proposal id and party id is missing.
	ErrMissingProposalIDAndPartyID = newInvalidArgumentError("missing proposal id and party id")
	// ErrMissingProposalIDOrPartyID returned if proposal id and party id is missing.
	ErrMissingProposalIDOrPartyID = newInvalidArgumentError("missing proposal id or party id")
	// ErrMissingProposalIDOrReference returned if proposal id or reference is missing.
	ErrMissingProposalIDOrReference = newInvalidArgumentError("missing proposal ID or reference")
	// ErrInvalidProposalID returned if proposal id is invalid.
	ErrInvalidProposalID = newInvalidArgumentError("invalid proposal id")
	// ErrMissingWithdrawalID is returned when the withdrawal ID is missing from the request.
	ErrMissingWithdrawalID = newInvalidArgumentError("missing withdrawal ID")
	// ErrMissingOracleSpecID is returned when the ID is missing from the request.
	ErrMissingOracleSpecID = newInvalidArgumentError("missing oracle spec ID")
	// ErrMissingDepositID is returned when the deposit ID is missing from the request.
	ErrMissingDepositID = newInvalidArgumentError("missing deposit ID")
	// ErrMissingAssetID is returned when the Asset ID is missing from the request.
	ErrMissingAssetID   = newInvalidArgumentError("missing asset ID")
	ErrorInvalidAssetID = newInvalidArgumentError("invalid asset ID")
	// ErrMissingNodeID is returned when the node ID is missing from the request.
	ErrMissingNodeID = newInvalidArgumentError("missing node id")
	// ErrERC20InvalidTokenContractAddress is returned when the ERC20 token contract address is invalid.
	ErrERC20InvalidTokenContractAddress = errors.New("invalid erc20 token contract address")
	ErrSendingGRPCHeader                = errors.New("failed to send header")
	ErrEstimateFee                      = errors.New("failed to estimate fee")
	ErrEstimateMargin                   = errors.New("failed to estimate margin")
	// OrderService...
	ErrOrderServiceGetOrders   = errors.New("failed to get orders")
	ErrOrderServiceGetVersions = errors.New("failed to get order versions")
	ErrOrderNotFound           = errors.New("order not found")
	// NodeService...
	ErrNodeServiceGetNodes    = errors.New("failed to get nodes")
	ErrNodeServiceGetNodeData = errors.New("failed to get node data")
	// TradeService...
	ErrTradeServiceGetByMarket = errors.New("failed to get trades for market")
	ErrTradeServiceList        = errors.New("failed to list trades")
	// MarketService...
	ErrMarketServiceGetByID              = errors.New("failed to get market for ID")
	ErrMarketServiceGetAllPaged          = errors.New("failed to get all markets paged")
	ErrMarketServiceGetMarketData        = errors.New("failed to get market data")
	ErrMarketServiceGetMarketDataHistory = errors.New("failed to get market data history")
	// AccountService...
	ErrAccountServiceListAccounts = errors.New("failed to get accounts")
	ErrFailedToSendSnapshot       = errors.New("failed to send accounts snapshot")
	ErrAccountServiceGetBalances  = errors.New("failed to get balances")
	// DelegationService...
	ErrDelegationServiceGet = errors.New("failed to get delegation")
	// SummaryService...
	ErrSummaryServiceGet = errors.New("failed to get summary")
	// WithdrawalService...
	ErrWithdrawalServiceGet = errors.New("failed to get withdrawal")
	// PositionService...
	ErrPositionServiceGetByParty   = errors.New("failed to get positions for party")
	ErrPositionServiceSendSnapshot = errors.New("failed to send positions snapshot")
	// RiskService...
	ErrRiskServiceGetMarginLevelsByID = errors.New("failed to get margin levels")
	ErrInvalidOrderSide               = newInvalidArgumentError("invalid order side")
	// RiskFactorService...
	ErrRiskFactorServiceGet = errors.New("failed to get risk factor")
	// GovernanceService...
	ErrGovernanceServiceGet          = errors.New("failed to get proposal")
	ErrGovernanceServiceGetProposals = errors.New("failed to get proposals")
	ErrGovernanceServiceGetVotes     = errors.New("failed to get votes")
	// 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")
	// NotaryService...
	ErrNotaryServiceGetByResourceID = errors.New("failed to get notary for resource ID")
	// OracleSpecService...
	// ErrOracleSpecServiceGet is returned when there was no data found for the given ID.
	ErrOracleSpecServiceGet = errors.New("failed retrieve data for oracle spec")
	// ErrOracleSpecServiceGetAll is returned when there was no data found for the given ID.
	ErrOracleSpecServiceGetAll = errors.New("failed retrieve data for oracle specs")
	// OracleDataService...
	// ErrOracleDataServiceGet is returned when there was no data found for the given ID.
	ErrOracleDataServiceGet = errors.New("failed retrieve data for oracle data")
	// AssetService...
	ErrAssetServiceGetAll            = errors.New("failed to get assets")
	ErrAssetServiceGetByID           = errors.New("failed to get asset for ID")
	ErrScalingPriceFromMarketToAsset = errors.New("failed to scale price from market to asset")
	// DepositService...
	ErrDepositServiceGet = errors.New("failed to get deposit")
	// TransferService...
	ErrTransferServiceGet = errors.New("failed to get transfer")
	// NetworkLimits...
	ErrGetNetworkLimits = errors.New("failed to get network limits")
	// ErrGetNetworkParameters is returned when the network parameters cannot be retrieved.
	ErrGetNetworkParameters = errors.New("failed to get network parameters")
	// Rewards...
	ErrGetRewards = errors.New("failed to get rewards")
	// Network History...
	ErrGetConnectedPeerAddresses    = errors.New("failed to get connected peer addresses")
	ErrGetMostRecentHistorySegment  = errors.New("failed to get most recent history segment")
	ErrListAllNetworkHistorySegment = errors.New("failed to list all history segments")
	ErrGetIpfsAddress               = errors.New("failed to get node's ipfs address")
	// ErrGetEpoch is returned when the epoch cannot be retrieved.
	ErrGetEpoch     = errors.New("failed to get epoch")
	ErrEpochIDParse = newInvalidArgumentError("failed to parse epoch id")
	// LedgerService...
	ErrLedgerServiceGet    = errors.New("failed to query ledger entries")
	ErrLedgerServiceExport = errors.New("failed to export ledger entries")
	// MultiSigService...
	ErrMultiSigServiceGetAdded   = errors.New("failed to get added multisig events")
	ErrMultiSigServiceGetRemoved = errors.New("failed to get removed multisig events")
	// LiquidityProvisionService...
	ErrLiquidityProvisionServiceGet = errors.New("failed to get liquidity provision")
	// CheckpointService...
	ErrCheckpointServiceGet = errors.New("failed to get checkpoint")
	// StakeLinkingService...
	ErrStakeLinkingServiceGet = errors.New("failed to get stake linking")
	// CoreSnapshotService...
	ErrCoreSnapshotServiceListSnapshots = errors.New("failed to list core snapshots")
	// ProtocolUpgradeService...
	ErrProtocolUpgradeServiceListProposals = errors.New("failed to list protocol upgrade proposals")
	// KeyRotationService...
	ErrKeyRotationServiceGetPerNode = errors.New("failed to get key rotations for node")
	ErrKeyRotationServiceGetAll     = errors.New("failed to get all key rotations")
	// EthereumKeyRotationService...
	ErrEthereumKeyRotationServiceGetPerNode = errors.New("failed to get ethereum key rotations for node")
	ErrEthereumKeyRotationServiceGetAll     = errors.New("failed to get all ethereum key rotations")
	// BlockService...
	ErrBlockServiceGetLast = errors.New("failed to get last block")
)

API Errors and descriptions.

var FormatE = formatE

FormatE exports the formatE function (primarily for testing).

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"`
	RateLimit                ratelimit.Config  `group:"rate-limits"`
	MaxSubscriptionPerClient uint32            `long:"max-subscription-per-client"`
}

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
}

CoreServiceClient ...

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,
	networkHistoryService NetworkHistoryService,
	coreSnapshotService *service.SnapshotData,
) *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 starts the grpc server. Uses default TCP listener if no provided.

type NetworkHistoryService

type NetworkHistoryService interface {
	GetHighestBlockHeightHistorySegment() (networkhistory.Segment, error)
	ListAllHistorySegments() ([]networkhistory.Segment, error)
	FetchHistorySegment(ctx context.Context, historySegmentID string) (networkhistory.Segment, error)
	GetActivePeerIPAddresses() []string
	CopyHistorySegmentToFile(ctx context.Context, historySegmentID string, outFile string) error
	GetSwarmKeySeed() string
	GetConnectedPeerAddresses() ([]string, error)
	GetIpfsAddress() (string, error)
	GetSwarmKey() string
	GetBootstrapPeers() []string
}

NetworkHistoryService ...