1/*
  2Package api implements the public interface of the hermez-node using a HTTP REST API.
  3There are two subsets of endpoints:
  4- coordinatorEndpoints: used to receive L2 transactions and account creation authorizations. Targeted for wallets.
  5- explorerEndpoints: used to provide all sorts of information about the network. Targeted for explorers and similar services.
  6
  7About the configuration of the API:
  8- The API is supposed to be launched using the cli found at the package cli/node, and configured through the configuration file.
  9- The mentioned configuration file allows exposing any combination of the endpoint subsets.
 10- Although the API can run in a "standalone" manner using the serveapi command, it won't work properly
 11unless another process acting as a coord or sync is filling the HistoryDB.
 12
 13Design principles and considerations:
 14- In order to decouple the API process from the rest of the node, all the communication between this package and the rest of
 15the system is done through the SQL database. As a matter of fact, the only public function of the package is the constructor NewAPI.
 16All the information needed for the API to work should be obtained through the configuration file of the cli or the database.
 17- The format of the requests / responses doesn't match directly with the common types, and for this reason, the package api/apitypes is used
 18to facilitate the format conversion. Most of the time, this is done directly at the db level.
 19- The API endpoints are fully documented using OpenAPI aka Swagger. All the endpoints are tested against the spec to ensure consistency
 20between implementation and specification. To get a sense of which endpoints exist and how they work, it's strongly recommended to check this specification.
 21The specification can be found at api/swagger.yml.
 22- 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
 23the /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.
 24*/
 25package api
 26
 27import (
 28	"errors"
 29
 30	ethCommon "github.com/ethereum/go-ethereum/common"
 31	"github.com/gin-gonic/gin"
 32	"github.com/hermeznetwork/hermez-node/db/historydb"
 33	"github.com/hermeznetwork/hermez-node/db/l2db"
 34	"github.com/hermeznetwork/tracerr"
 35)
 36
 37// API serves HTTP requests to allow external interaction with the Hermez node
 38type API struct {
 39	h             *historydb.HistoryDB
 40	cg            *configAPI
 41	l2            *l2db.L2DB
 42	chainID       uint16
 43	hermezAddress ethCommon.Address
 44}
 45
 46// NewAPI sets the endpoints and the appropriate handlers, but doesn't start the server
 47func NewAPI(
 48	coordinatorEndpoints, explorerEndpoints bool,
 49	server *gin.Engine,
 50	hdb *historydb.HistoryDB,
 51	l2db *l2db.L2DB,
 52) (*API, error) {
 53	// Check input
 54	if coordinatorEndpoints && l2db == nil {
 55		return nil, tracerr.Wrap(errors.New("cannot serve Coordinator endpoints without L2DB"))
 56	}
 57	if explorerEndpoints && hdb == nil {
 58		return nil, tracerr.Wrap(errors.New("cannot serve Explorer endpoints without HistoryDB"))
 59	}
 60	consts, err := hdb.GetConstants()
 61	if err != nil {
 62		return nil, err
 63	}
 64	a := &API{
 65		h: hdb,
 66		cg: &configAPI{
 67			RollupConstants:   *newRollupConstants(consts.Rollup),
 68			AuctionConstants:  consts.Auction,
 69			WDelayerConstants: consts.WDelayer,
 70		},
 71		l2:            l2db,
 72		chainID:       consts.ChainID,
 73		hermezAddress: consts.HermezAddress,
 74	}
 75
 76	v1 := server.Group("/v1")
 77
 78	// Add coordinator endpoints
 79	if coordinatorEndpoints {
 80		// Account creation authorization
 81		v1.POST("/account-creation-authorization", a.postAccountCreationAuth)
 82		v1.GET("/account-creation-authorization/:hezEthereumAddress", a.getAccountCreationAuth)
 83		// Transaction
 84		v1.POST("/transactions-pool", a.postPoolTx)
 85		v1.GET("/transactions-pool/:id", a.getPoolTx)
 86	}
 87
 88	// Add explorer endpoints
 89	if explorerEndpoints {
 90		// Account
 91		v1.GET("/accounts", a.getAccounts)
 92		v1.GET("/accounts/:accountIndex", a.getAccount)
 93		v1.GET("/exits", a.getExits)
 94		v1.GET("/exits/:batchNum/:accountIndex", a.getExit)
 95		// Transaction
 96		v1.GET("/transactions-history", a.getHistoryTxs)
 97		v1.GET("/transactions-history/:id", a.getHistoryTx)
 98		// Batches
 99		v1.GET("/batches", a.getBatches)
100		v1.GET("/batches/:batchNum", a.getBatch)
101		v1.GET("/full-batches/:batchNum", a.getFullBatch)
102		// Slots
103		v1.GET("/slots", a.getSlots)
104		v1.GET("/slots/:slotNum", a.getSlot)
105		// Bids
106		v1.GET("/bids", a.getBids)
107		// State
108		v1.GET("/state", a.getState)
109		// Config
110		v1.GET("/config", a.getConfig)
111		// Tokens
112		v1.GET("/tokens", a.getTokens)
113		v1.GET("/tokens/:id", a.getToken)
114		// Coordinators
115		v1.GET("/coordinators", a.getCoordinators)
116	}
117
118	return a, nil
119}