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/hermez-node/metric"
 35	"github.com/hermeznetwork/tracerr"
 36)
 37
 38// API serves HTTP requests to allow external interaction with the Hermez node
 39type API struct {
 40	h             *historydb.HistoryDB
 41	cg            *configAPI
 42	l2            *l2db.L2DB
 43	chainID       uint16
 44	hermezAddress ethCommon.Address
 45}
 46
 47// NewAPI sets the endpoints and the appropriate handlers, but doesn't start the server
 48func NewAPI(
 49	coordinatorEndpoints, explorerEndpoints bool,
 50	server *gin.Engine,
 51	hdb *historydb.HistoryDB,
 52	l2db *l2db.L2DB,
 53) (*API, error) {
 54	// Check input
 55	if coordinatorEndpoints && l2db == nil {
 56		return nil, tracerr.Wrap(errors.New("cannot serve Coordinator endpoints without L2DB"))
 57	}
 58	if explorerEndpoints && hdb == nil {
 59		return nil, tracerr.Wrap(errors.New("cannot serve Explorer endpoints without HistoryDB"))
 60	}
 61	consts, err := hdb.GetConstants()
 62	if err != nil {
 63		return nil, err
 64	}
 65	a := &API{
 66		h: hdb,
 67		cg: &configAPI{
 68			RollupConstants:   *newRollupConstants(consts.Rollup),
 69			AuctionConstants:  consts.Auction,
 70			WDelayerConstants: consts.WDelayer,
 71		},
 72		l2:            l2db,
 73		chainID:       consts.ChainID,
 74		hermezAddress: consts.HermezAddress,
 75	}
 76
 77	middleware, err := metric.PrometheusMiddleware()
 78	if err != nil {
 79		return nil, err
 80	}
 81	server.Use(middleware)
 82
 83	v1 := server.Group("/v1")
 84
 85	// Add coordinator endpoints
 86	if coordinatorEndpoints {
 87		// Account creation authorization
 88		v1.POST("/account-creation-authorization", a.postAccountCreationAuth)
 89		v1.GET("/account-creation-authorization/:hezEthereumAddress", a.getAccountCreationAuth)
 90		// Transaction
 91		v1.POST("/transactions-pool", a.postPoolTx)
 92		v1.GET("/transactions-pool/:id", a.getPoolTx)
 93	}
 94
 95	// Add explorer endpoints
 96	if explorerEndpoints {
 97		// Account
 98		v1.GET("/accounts", a.getAccounts)
 99		v1.GET("/accounts/:accountIndex", a.getAccount)
100		v1.GET("/exits", a.getExits)
101		v1.GET("/exits/:batchNum/:accountIndex", a.getExit)
102		// Transaction
103		v1.GET("/transactions-history", a.getHistoryTxs)
104		v1.GET("/transactions-history/:id", a.getHistoryTx)
105		// Batches
106		v1.GET("/batches", a.getBatches)
107		v1.GET("/batches/:batchNum", a.getBatch)
108		v1.GET("/full-batches/:batchNum", a.getFullBatch)
109		// Slots
110		v1.GET("/slots", a.getSlots)
111		v1.GET("/slots/:slotNum", a.getSlot)
112		// Bids
113		v1.GET("/bids", a.getBids)
114		// State
115		v1.GET("/state", a.getState)
116		// Config
117		v1.GET("/config", a.getConfig)
118		// Tokens
119		v1.GET("/tokens", a.getTokens)
120		v1.GET("/tokens/:id", a.getToken)
121		// Coordinators
122		v1.GET("/coordinators", a.getCoordinators)
123	}
124
125	return a, nil
126}