api

README

Hermez API

Easy to deploy and scale API for Hermez operators. You will need to have docker and docker-compose installed on your machine in order to use this repo.

Documentation

As of now the documentation is not hosted anywhere, but you can easily do it yourself by running ./run.sh doc and then opening the documentation in your browser

Mock Up

To use a mock up of the endpoints in the API run ./run.sh doc (UI + mock up server) or ./run.sh mock (only mock up server). You can play with the mocked up endpoints using the web UI, importing swagger.yml into Postman or using your preferred language and using http://localhost:4010 as base URL.

Editor

It is recommended to edit swagger.yml using a dedicated editor as they provide spec validation and real time visualization. Of course you can use your prefered editor. To use the editor run ./run.sh editor and then opening the editor in your browser. Keep in mind that you will need to manually save the file otherwise you will lose the changes you made once you close your browser seshion or stop the server.

Note: Your browser may cache the swagger definition, so in order to see updated changes it may be needed to refresh the page without cache (Ctrl + Shift + R).

Documentation

Overview

Package api implements the public interface of the hermez-node using a HTTP REST API. There are two subsets of endpoints: - coordinatorEndpoints: used to receive L2 transactions and account creation authorizations. Targeted for wallets. - explorerEndpoints: used to provide all sorts of information about the network. Targeted for explorers and similar services.

About the configuration of the API: - The API is supposed to be launched using the cli found at the package cli/node, and configured through the configuration file. - The mentioned configuration file allows exposing any combination of the endpoint subsets. - Although the API can run in a "standalone" manner using the serveapi command, it won't work properly unless another process acting as a coord or sync is filling the HistoryDB.

Design principles and considerations: - In order to decouple the API process from the rest of the node, all the communication between this package and the rest of the system is done through the SQL database. As a matter of fact, the only public function of the package is the constructor NewAPI. All the information needed for the API to work should be obtained through the configuration file of the cli or the database. - The format of the requests / responses doesn't match directly with the common types, and for this reason, the package api/apitypes is used to facilitate the format conversion. Most of the time, this is done directly at the db level. - The API endpoints are fully documented using OpenAPI aka Swagger. All the endpoints are tested against the spec to ensure consistency between implementation and specification. To get a sense of which endpoints exist and how they work, it's strongly recommended to check this specification. The specification can be found at api/swagger.yml. - In general, all the API endpoints produce queries to the SQL database in order to retrieve / insert the requested information. The most notable exceptions to this are the /config endpoint, which returns a static object generated at construction time, and the /state, which also is retrieved from the database, but it's generated by API/stateapiupdater package.

Index

• Constants
• func RequestOffset2RelativePosition(rqoffset uint8) (int, error)
• type API
  • func NewAPI(version string, coordinatorEndpoints, explorerEndpoints bool, ...) (*API, error)
• type Config
• type CurrenciesResponse
• type SlotAPI

Constants

const (

	// ErrParamValidationFailedCode code for param validation failed error
	ErrParamValidationFailedCode apiErrorCode = 1
	// ErrParamValidationFailedType type for param validation failed error
	ErrParamValidationFailedType apiErrorType = "ErrParamValidationFailed"

	// ErrDuplicatedKey error message returned when trying to insert an item with duplicated key
	ErrDuplicatedKey = "Item already exists"
	// ErrDuplicatedKeyCode code for duplicated key error
	ErrDuplicatedKeyCode apiErrorCode = 2
	// ErrDuplicatedKeyType type for duplicated key error
	ErrDuplicatedKeyType apiErrorType = "ErrDuplicatedKey"

	// ErrSQLTimeout error message returned when timeout due to SQL connection
	ErrSQLTimeout = "The node is under heavy pressure, please try again later"
	// ErrSQLTimeoutCode code for sql timeout error
	ErrSQLTimeoutCode apiErrorCode = 3
	// ErrSQLTimeoutType type for sql timeout type
	ErrSQLTimeoutType apiErrorType = "ErrSQLTimeout"

	// ErrSQLNoRows error message returned when there is no such records
	ErrSQLNoRows = "record(s) were not found for this query and/or the parameters entered"
	// ErrSQLNoRowsCode code for no rows error
	ErrSQLNoRowsCode apiErrorCode = 4
	// ErrSQLNoRowsType type for now rows error
	ErrSQLNoRowsType apiErrorType = "ErrSQLNoRows"

	// ErrExitAmount0 error message returned when receiving (and rejecting) a tx of type exit with amount 0
	ErrExitAmount0 = "Transaction rejected because an exit with amount 0 has no sense"
	// ErrExitAmount0Code code for 0 exit amount error
	ErrExitAmount0Code apiErrorCode = 5
	// ErrExitAmount0Type type for 0 exit amount error
	ErrExitAmount0Type apiErrorType = "ErrExitAmount0"

	// ErrInvalidTxTypeOrTxIDCode code for invalid tx type or txID error
	ErrInvalidTxTypeOrTxIDCode apiErrorCode = 6
	// ErrInvalidTxTypeOrTxIDType type for invalid tx type or txID error
	ErrInvalidTxTypeOrTxIDType apiErrorType = "ErrInvalidTxTypeOrTxID"

	// ErrFeeOverflowCode code for fee overflow code error
	ErrFeeOverflowCode apiErrorCode = 7
	// ErrFeeOverflowType type for fee overflow code type
	ErrFeeOverflowType apiErrorType = "ErrFeeOverflow"

	// ErrGettingSenderAccountCode code for getting sender account error
	ErrGettingSenderAccountCode apiErrorCode = 8
	// ErrGettingSenderAccountType type for getting sender account error
	ErrGettingSenderAccountType apiErrorType = "ErrGettingSenderAccount"

	// ErrAccountTokenNotEqualTxTokenCode code for account token not equal tx token error
	ErrAccountTokenNotEqualTxTokenCode apiErrorCode = 9
	// ErrAccountTokenNotEqualTxTokenType type for account token not equal tx token type
	ErrAccountTokenNotEqualTxTokenType apiErrorType = "ErrAccountTokenNotEqualTxToken"

	// ErrInvalidNonceCode code for invalid nonce error
	ErrInvalidNonceCode apiErrorCode = 10
	// ErrInvalidNonceType type for invalid nonce error
	ErrInvalidNonceType apiErrorType = "ErrInvalidNonce"

	// ErrInvalidSignatureCode code for invalid signature error
	ErrInvalidSignatureCode apiErrorCode = 11
	// ErrInvalidSignatureType type for invalid signature error
	ErrInvalidSignatureType apiErrorType = "ErrInvalidSignature"

	// ErrGettingReceiverAccountCode code for getting receiver account error
	ErrGettingReceiverAccountCode apiErrorCode = 12
	// ErrGettingReceiverAccountType type for getting receiver account error
	ErrGettingReceiverAccountType apiErrorType = "ErrGettingReceiverAccount"

	// ErrCantSendToEthAddrCode code when can't send to eth addr code error appeared
	ErrCantSendToEthAddrCode apiErrorCode = 13
	// ErrCantSendToEthAddrType type when can't send to eth addr code error appeared
	ErrCantSendToEthAddrType apiErrorType = "ErrCantSendToEthAddr"

	// ErrNotAtomicTxsInPostPoolTx error message returned when received an non-atomic transaction inside atomic pool
	ErrNotAtomicTxsInPostPoolTx = "atomic transactions are only accepted in POST /atomic-pool"
	// ErrNotAtomicTxsInPostPoolTxCode code filter atomic transactions on POST /transactions-pool
	ErrNotAtomicTxsInPostPoolTxCode apiErrorCode = 14
	// ErrNotAtomicTxsInPostPoolTxType type filter atomic transactions on POST /transactions-pool
	ErrNotAtomicTxsInPostPoolTxType apiErrorType = "ErrNotAtomicTxsInPostPoolTx"

	// ErrFailedToGetCurrentBlockCode code when can't get current block in /slots request
	ErrFailedToGetCurrentBlockCode apiErrorCode = 15
	// ErrFailedToGetCurrentBlockType type when can't get current block in /slots request
	ErrFailedToGetCurrentBlockType apiErrorType = "ErrFailedToGetCurrentBlock"

	// ErrFailedToGetAuctionVarsCode code when can't get auction vars in /slots request
	ErrFailedToGetAuctionVarsCode apiErrorCode = 16
	// ErrFailedToGetAuctionVarsType type when can't get auction vars in /slots request
	ErrFailedToGetAuctionVarsType apiErrorType = "ErrFailedToGetAuctionVars"

	// ErrFailedToAddEmptySlotCode code when can't add empty slot in /slots request
	ErrFailedToAddEmptySlotCode apiErrorCode = 17
	// ErrFailedToAddEmptySlotType type when can't add empty slot in /slots request
	ErrFailedToAddEmptySlotType apiErrorType = "ErrFailedToAddEmptySlot"

	// ErrTxsNotAtomic error message returned when receiving (and rejecting) txs in the atomic endpoint with not all txs being atomic
	ErrTxsNotAtomic = "there is at least one transaction in the payload that could be forged without the others"
	// ErrTxsNotAtomicCode error code
	ErrTxsNotAtomicCode apiErrorCode = 18
	// ErrTxsNotAtomicType error type
	ErrTxsNotAtomicType apiErrorType = "ErrTxsNotAtomic"

	// ErrSingleTxInAtomicEndpoint only one tx sent to the atomic-pool endpoint
	ErrSingleTxInAtomicEndpoint = "to use the atomic-pool endpoint at least two transactions are required"
	// ErrSingleTxInAtomicEndpointCode error code
	ErrSingleTxInAtomicEndpointCode apiErrorCode = 19
	// ErrSingleTxInAtomicEndpointType error type
	ErrSingleTxInAtomicEndpointType apiErrorType = "ErrSingleTxInAtomicEndpoint"

	// ErrInvalidRqOffset error message returned when received an invalid request offset
	ErrInvalidRqOffset = "invalid requestOffset. Valid values goes from 0 to 7"

	// ErrRqOffsetOutOfBounds error message returned when transaction tries to access another out the bounds of the array
	ErrRqOffsetOutOfBounds = "one of the transactions requested another one outside the bounds of the provided array"
	// ErrRqOffsetOutOfBoundsCode error code
	ErrRqOffsetOutOfBoundsCode = 20
	// ErrRqOffsetOutOfBoundsType error type
	ErrRqOffsetOutOfBoundsType = "ErrRqOffsetOutOfBounds"

	// ErrInvalidAtomicGroupID error message returned when received an invalid AtomicGroupID
	ErrInvalidAtomicGroupID = "invalid atomicGroupId"
	// ErrInvalidAtomicGroupIDCode error code
	ErrInvalidAtomicGroupIDCode = 21
	// ErrInvalidAtomicGroupIDType error type
	ErrInvalidAtomicGroupIDType = "ErrInvalidAtomicGroupID"

	// ErrFailedToFindOffsetToRelativePositionCode error code when can't find offset to relative position
	ErrFailedToFindOffsetToRelativePositionCode = 22
	// ErrFailedToFindOffsetToRelativePositionType error type
	ErrFailedToFindOffsetToRelativePositionType = "ErrFailedToFindOffsetToRelativePosition"

	// ErrFeeTooLowCode code for fee too low error
	ErrFeeTooLowCode apiErrorCode = 23
	// ErrFeeTooLowType type for fee too low error
	ErrFeeTooLowType apiErrorType = "ErrFeeTooLow"

	// ErrFeeTooBigCode code for fee too big error
	ErrFeeTooBigCode apiErrorCode = 24
	// ErrFeeTooBigType type for fee too big error
	ErrFeeTooBigType apiErrorType = "ErrFeeTooBig"

	// ErrNothingToUpdateCode code for nothing to update error
	ErrNothingToUpdateCode apiErrorCode = 25
	// ErrNothingToUpdateType type for nothing to update type
	ErrNothingToUpdateType apiErrorType = "ErrNothingToUpdate"

	// ErrUnsupportedMaxNumBatch error message returned when tx.MaxNumBatch != 0 until the feature is fully implemented
	ErrUnsupportedMaxNumBatch = "currently only supported value for maxNumBatch is 0, this will change soon when the feature is fully implemented"
)

Functions

func RequestOffset2RelativePosition

func RequestOffset2RelativePosition(rqoffset uint8) (int, error)

RequestOffset2RelativePosition translates from 0 to 7 to protocol position

Types

type API

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

API serves HTTP requests to allow external interaction with the Hermez node

func NewAPI

func NewAPI(
	version string,
	coordinatorEndpoints, explorerEndpoints bool,
	server *gin.Engine,
	hdb *historydb.HistoryDB,
	l2db *l2db.L2DB,
	stateDB *statedb.StateDB,
	ethClient *ethclient.Client,
	forgerAddress *ethCommon.Address,
) (*API, error)

NewAPI sets the endpoints and the appropriate handlers, but doesn't start the server

type Config

type Config struct {
	RollupConstants   common.RollupConstants
	AuctionConstants  common.AuctionConstants
	WDelayerConstants common.WDelayerConstants
	ChainID           uint16
	HermezAddress     ethCommon.Address
}

Config of the API

type CurrenciesResponse

type CurrenciesResponse struct {
	Currencies []historydb.FiatCurrency `json:"currencies"`
}

CurrenciesResponse is the response object for multiple fiat prices

type SlotAPI

type SlotAPI struct {
	ItemID      uint64            `json:"itemId"`
	SlotNum     int64             `json:"slotNum"`
	FirstBlock  int64             `json:"firstBlock"`
	LastBlock   int64             `json:"lastBlock"`
	OpenAuction bool              `json:"openAuction"`
	WinnerBid   *historydb.BidAPI `json:"bestBid"`
}

SlotAPI is a representation of a slot information