|
|
openapi: 3.0.0
info:
description: |
This API server is the layer that allows 3rd party apps and services interfacing with the coordinator to explore, monitor and use the Hermez rollup.
Example of these apps are:
* Wallet: send L2 transactions, check balance, ...
* Explorer: List transactions, slots, batches, ...
* Exchange integrations
### Pagination
#### Usage
All the endpoints that return a list of undefined size use pagination. Unless the opposite is explicitly said.
In order to use pagination, three query parameters are used:
* `fromItem`: indicates the first item to be returned. In general, this parameter shouldn't be provided in the first call to the endpoint, and use the `itemId` of the last returned item (+/-) 1, if the order is (ascending/descending).
* `order`: all pginated items are ordered chronologicaly. However the specific fields to guarantee this order depend on each endpoint. For this purpose, `itemId` is used (itemId follows ascending chronological order except for unforged L1 user transactions). If the parameter is not provided, ascending order will be used by default.
* `limit`: maximum amount of items to include in each response. Default is 20, maximum 2049.
Responses for those endpoint will always include a `pendingItems` property. This property includes the amount of items that are not fetched yet. his can be used to:
* Calculate the amount of items that match the filters: `totalItems = length(alreadyFetchedItems) + pendingItems`
* Know when all items have been fetched: `if pendingItems == 0 {/* all items have been fetched */}`
#### Reorgs and safetyness
Since all the items are ordered chronologicaly, there are no safety problems when fetching items in ascending order, except for reorgs (more on this later).
On the other hand, when iterating in descending order, new items will be added at the beginning. This doesn't cause any safety problem, but to get those new items, it's necessary to start queryng without the `fromItem` set to `pagination.lastItem`.
To handle reorgs, the `itemId` can be used since it will change. This is important since other identifiers may be the same but with different content. As an example, if the batch 424 get's reorged, it will be deleted, but eventualy, a new batch 424 will appear with potentialy different content.
### Signatures
The POST endpoint require to be signed using BabyJubJub or Ethereum keys. TODO: add references to libraries / examples / ...
version: "0.0.1"
title: Hermez Network API
# termsOfService: 'http://swagger.io/terms/'
# contact:
# email: apiteam@swagger.io
# license:
# name: Apache 2.0
# url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
externalDocs:
description: Find out more about Hermez.
url: 'https://hermez.io'
servers:
- description: Hosted mock up
url: http://167.71.59.190:4010
- description: Localhost mock Up
url: http://localhost:4010
tags:
- name: Account
description: Hermez account and the tokens it holds.
externalDocs:
description: Find out more.
url: 'https://idocs.hermez.io/#/spec/zkrollup/README?id=account-types'
- name: Transaction
description: Send tokens off chain and track transactions.
externalDocs:
description: Find out more
url: 'https://idocs.hermez.io/#/spec/zkrollup/README?id=transaction-types'
- name: Hermez status
description: Info about operators, tokens, auctions and more.
externalDocs:
description: Find out more.
url: 'https://idocs.hermez.io/#/spec/zkrollup/README'
paths:
'/account-creation-authorization':
post:
tags:
- Account
summary: Send an authorization that will allow the coordinator to register accounts associated to an Ethereum address on behalf of the user.
description: >-
Send an authorization to create rollup accounts associated to an Ethereum address. Each account creation (an account can only hold a specific token) is effective once the coordinator forges the corresponding L1CoordinatorTx (which are always of type *account creation*).
operationId: postRegister
requestBody:
description: Account creation authorization.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AccountCreationAuthorizationPost'
responses:
'200':
description: Successful operation.
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
'/account-creation-authorization/{hezEthereumAddress}':
get:
tags:
- Account
summary: Get to know if the coordinator has the ability to create accounts associated to an Ethereum address.
description: >-
True if the coordinator has the required authorization to perform an account creation with the given Ethereum address on behalf of the Ethereum address holder.
operationId: getAccountCreationAuthorization
parameters:
- name: hezEthereumAddress
in: path
description: Ethereum address.
required: true
schema:
$ref: '#/components/schemas/HezEthereumAddress'
responses:
'200':
description: Successful operation.
content:
application/json:
schema:
$ref: '#/components/schemas/AccountCreationAuthorization'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'404':
description: Not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
'/accounts':
get:
tags:
- Account
summary: Get accounts balances and other associated information.
description: Get accounts balances and other associated information.
operationId: getAccounts
parameters:
- name: hezEthereumAddress
in: query
description: Only get accounts associated to an Ethereum address. Incompatible with the query `BJJ`.
required: false
schema:
$ref: '#/components/schemas/HezEthereumAddress'
- name: BJJ
in: query
description: Only get accounts associated to a BabyJubJub public key. Incompatible with the query `hezEthereumAddress`.
required: false
schema:
$ref: '#/components/schemas/BJJ'
- name: tokenIds
in: query
required: false
description: Only get accounts of specific tokens.
schema:
type: string
description: Comma separated list of token identifiers.
example: "3,87,91"
- name: fromItem
in: query
required: false
description: Indicates the desired first item (using the itemId property) to be included in the response.
schema:
type: number
- name: order
in: query
required: false
description: Order of the returned items. Accounts will be ordered by increasing account index.
schema:
type: string
default: ASC
enum:
- ASC
- DESC
- name: limit
in: query
required: false
description: Maximum number of items to be returned.
schema:
type: integer
minimum: 1
maximum: 2049
responses:
'200':
description: Successful operation.
content:
application/json:
schema:
$ref: '#/components/schemas/Accounts'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'404':
description: Not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
'/accounts/{accountIndex}':
get:
tags:
- Account
summary: Get an account by its index.
description: Get an account by its index.
operationId: getAccount
parameters:
- name: accountIndex
in: path
description: Identifier of an account.
required: true
schema:
$ref: '#/components/schemas/AccountIndex'
responses:
'200':
description: Successful operation.
content:
application/json:
schema:
$ref: '#/components/schemas/Account'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'404':
description: Not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
'/exits':
get:
tags:
- Account
summary: Get exit information. This information is required to perform a withdraw.
description: Get exit information. This information is required to perform a withdraw.
operationId: getExits
parameters:
- name: tokenId
in: query
required: false
description: Only get exits of specific token
schema:
$ref: '#/components/schemas/TokenId'
- name: hezEthereumAddress
in: query
description: Get exits associated to a Ethereum address. Incompatible with query `BJJ` and `accountIndex`.
required: false
schema:
$ref: '#/components/schemas/HezEthereumAddress'
- name: BJJ
in: query
description: Get exits associated to a BabyJubJub public key. Incompatible with query `hezEthereumAddress` and `accountIndex`.
required: false
schema:
$ref: '#/components/schemas/BJJ'
- name: accountIndex
in: query
description: Get exits associated to a specific account. Incompatible with queries `tokenId`, `hezEthereumAddress` and `BJJ`.
required: false
schema:
$ref: '#/components/schemas/AccountIndex'
- name: batchNum
in: query
description: Get exits from the exit tree of a specific batch.
required: false
schema:
$ref: '#/components/schemas/BatchNum'
- name: onlyPendingWithdraws
in: query
description: Get exits with pending withdrawals.
required: false
schema:
type: boolean
- name: fromItem
in: query
required: false
description: Indicates the desired first item (using the itemId property) to be included in the response.
schema:
type: number
- name: order
in: query
required: false
description: Order of the returned items. Exits will be ordered by increasing (batchNum, accountIndex).
schema:
type: string
default: ASC
enum:
- ASC
- DESC
- name: limit
in: query
required: false
description: Maximum number of items to be returned.
schema:
type: integer
minimum: 1
maximum: 2049
responses:
'200':
description: Successful operation.
content:
application/json:
schema:
$ref: '#/components/schemas/Exits'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'404':
description: Not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
'/exits/{batchNum}/{accountIndex}':
get:
tags:
- Account
summary: Get specific exit information.
description: Get exit information form a specific exit tree and account. This information is required to perform a withdraw. Exits are identified with accounIndex and batchNum since every batch that has exits has a different exit tree.
operationId: getExit
parameters:
- name: batchNum
in: path
description: Batch of the exit tree.
required: true
schema:
$ref: '#/components/schemas/BatchNum'
- name: accountIndex
in: path
description: Account identifier.
required: true
schema:
$ref: '#/components/schemas/AccountIndex'
responses:
'200':
description: Successful operation.
content:
application/json:
schema:
$ref: '#/components/schemas/Exit'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'404':
description: Not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
'/transactions-pool':
post:
tags:
- Transaction
summary: Add an L2 transaction to the coordinator's pool
description: >-
Send L2 transaction. The transaction will be stored in the transaction pool of the coordinator and eventually forged.
operationId: postTx
requestBody:
description: Signed transaction.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PostPoolL2Transaction'
responses:
'200':
description: Successful operation.
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionId'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
'/transactions-pool/{id}':
get:
tags:
- Transaction
summary: Get details and status of a transaction that is in the pool.
description: >-
Get transaction from the pool by its id. This endpoint is specially useful for tracking the status of a transaction that may not be forged yet.
Only transactions from the pool will be returned.
Note that the transaction pool is different for each coordinator and therefore only a coordinator that has received a specific transaction
will be able to provide information about that transaction.
operationId: getPoolTx
parameters:
- name: id
in: path
description: Transaction identifier.
required: true
schema:
$ref: '#/components/schemas/TransactionId'
responses:
'200':
description: Successful operation.
content:
application/json:
schema:
$ref: '#/components/schemas/PoolL2Transaction'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'404':
description: Not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
'/transactions-history':
get:
tags:
- Transaction
summary: Get details and status of transactions that have been forged.
description: >-
Get historical transactions. This endpoint will return all the different types of transactions except for:
- Transactions that are still in the transaction pool of any coordinator. These transactions can be fetched using `GET /transactions-pool/{id}`.
- L1 transactions sent by users that have not been forged yet. These transactions can be fetched using `GET /transactions-history/{id}`.
operationId: getHistoryTxs
parameters:
- name: tokenId
in: query
required: false
description: Only get transactions of specific token
schema:
$ref: '#/components/schemas/TokenId'
- name: hezEthereumAddress
in: query
required: false
description: Only get transactions sent from or to an account associated to an Ethereum address Incompatible with the queries `BJJ` and `accountIndex`.
schema:
$ref: '#/components/schemas/HezEthereumAddress'
- name: BJJ
in: query
description: Only get transactions associated to a BabyJubJub public key. Incompatible with the queries `hezEthereumAddress` and `accountIndex`.
required: false
schema:
$ref: '#/components/schemas/BJJ'
- name: accountIndex
in: query
required: false
description: Only get transactions sent from or to a specific account. Incompatible with the queries `tokenId`, `hezEthereumAddress` and `BJJ`.
schema:
$ref: '#/components/schemas/AccountIndex'
- name: batchNum
in: query
required: false
description: Only get transactions forged in a specific batch.
schema:
$ref: '#/components/schemas/BatchNum'
- name: type
in: query
required: false
description: Only get transactions of a specific type.
schema:
$ref: '#/components/schemas/TransactionType'
- name: fromItem
in: query
required: false
description: Indicates the desired first item (using the itemId property) to be included in the response.
schema:
type: number
- name: order
in: query
required: false
description: Order of the returned items. History transactions will be ordered by (batchNum, position).
schema:
type: string
default: ASC
enum:
- ASC
- DESC
- name: limit
in: query
required: false
description: Maximum number of items to be returned.
schema:
type: integer
minimum: 1
maximum: 2049
responses:
'200':
description: Successful operation.
content:
application/json:
schema:
$ref: '#/components/schemas/HistoryTransactions'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'404':
description: Not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
'/transactions-history/{id}':
get:
tags:
- Transaction
summary: Get details and status of a historical transaction.
description: >-
Get transaction from the history by its id. This endpoint will return all the different types of transactions except those that are still in the pool of any coordinator.
operationId: getHistoryTx
parameters:
- name: id
in: path
description: Transaction identifier.
required: true
schema:
$ref: '#/components/schemas/TransactionId'
responses:
'200':
description: Successful operation.
content:
application/json:
schema:
$ref: '#/components/schemas/HistoryTransaction'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'404':
description: Not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
'/batches':
get:
tags:
- Hermez status
summary: Get information about forged batches.
description: >-
Get information about forged batches.
operationId: getBatches
parameters:
- name: minBatchNum
in: query
required: false
description: Include only `batchNum > minBatchNum` batches.
schema:
$ref: '#/components/schemas/BatchNum'
- name: maxBatchNum
in: query
required: false
description: Include only `batchNum < maxBatchNum` batches.
schema:
type: number
- name: slotNum
in: query
required: false
description: Include only batches that were forged within the specified slot.
schema:
$ref: '#/components/schemas/SlotNum'
- name: forgerAddr
in: query
required: false
description: Include only batches forged by `forgerAddr`
schema:
$ref: '#/components/schemas/EthereumAddress'
- name: fromItem
in: query
required: false
description: Indicates the desired first item (using the itemId property) to be included in the response.
schema:
type: number
- name: order
in: query
required: false
description: Order of the returned items. Batches will be ordered by increasing `batchNum`.
schema:
type: string
default: ASC
enum:
- ASC
- DESC
- name: limit
in: query
required: false
description: Maximum number of items to be returned.
schema:
type: integer
minimum: 1
maximum: 2049
responses:
'200':
description: Successful operation.
content:
application/json:
schema:
$ref: '#/components/schemas/Batches'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'404':
description: Not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
'/batches/{batchNum}':
get:
tags:
- Hermez status
summary: Get a specific batch.
description: >-
Get a specific batch.
operationId: getBatch
parameters:
- name: batchNum
in: path
description: Batch identifier.
required: true
schema:
$ref: '#/components/schemas/BatchNum'
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/Batch'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'404':
description: Not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
'/full-batches/{batchNum}':
get:
tags:
- Hermez status
summary: Get a full batch
description: >-
Get a specific batch, including the associated transactions. The object returned in this method can be a bit heavy.
If you're devloping a front end, you may consider using a combinaton of `GET /batches/{batchnum}` and `GET /history-transactions?batchNum={batchNum}`.
operationId: getFullBatch
parameters:
- name: batchNum
in: path
description: Batch identifier
required: true
schema:
$ref: '#/components/schemas/BatchNum'
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/FullBatch'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'404':
description: Not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
'/slots':
get:
tags:
- Hermez status
summary: Get information about slots.
description: >-
Get information about slots.
operationId: getSlots
parameters:
- name: minSlotNum
in: query
required: false
description: Only include slots with `slotNum >= minSlotNum`. By default, `minSlotNum = 0`.
schema:
$ref: '#/components/schemas/SlotNum'
- name: maxSlothNum
in: query
required: false
description: Only include slots with `slotNum <= maxSlotNum`.
schema:
$ref: '#/components/schemas/SlotNum'
- name: wonByEthereumAddress
in: query
required: false
description: Only include slots won by a coordinator whose `bidderAddr == wonByEthereumAddress`.
schema:
$ref: '#/components/schemas/EthereumAddress'
- name: finishedAuction
in: query
required: false
description: If set to true, only include slots whose auction has finished.
schema:
type: boolean
- name: fromItem
in: query
required: false
description: Indicates the desired first item (using the itemId property) to be included in the response.
schema:
type: number
- name: order
in: query
required: false
description: Order of the returned items. Slots will be ordered by increasing `slotNum`.
schema:
type: string
default: ASC
enum:
- ASC
- DESC
- name: limit
in: query
required: false
description: Maximum number of items to be returned.
schema:
type: integer
minimum: 1
maximum: 2049
responses:
'200':
description: Successful operation.
content:
application/json:
schema:
$ref: '#/components/schemas/Slots'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'404':
description: Not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
'/slots/{slotNum}':
get:
tags:
- Hermez status
summary: Get information about a specific slot.
description: >-
Get information about a specific slot.
operationId: getSlot
parameters:
- name: slotNum
in: path
required: true
description: Identifier of the slot.
schema:
$ref: '#/components/schemas/SlotNum'
responses:
'200':
description: Successful operation.
content:
application/json:
schema:
$ref: '#/components/schemas/Slot'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'404':
description: Not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
'/bids':
get:
tags:
- Hermez status
summary: Get a list of bids made for a specific slot auction.
description: Get a list of bids made for a specific slot auction. Is necessary to add a filter (`slotNum` or `bidderAddr`).
operationId: getSlotBids
parameters:
- name: slotNum
in: query
description: Slot identifier. Specify the auction where the returned bids were made.
required: false
schema:
$ref: '#/components/schemas/SlotNum'
- name: bidderAddr
in: query
description: Get only bids made by a coordinator identified by its bidder address. In this case, the bids will be returned in the order that the coordinator made them.
required: false
schema:
$ref: '#/components/schemas/EthereumAddress'
- name: fromItem
in: query
required: false
description: Indicates the desired first item (using the itemId property) to be included in the response.
schema:
type: number
- name: order
in: query
required: false
description: Order of the returned items. Bids will be ordered by increasing (slotNum, bidValue)`.
schema:
type: string
default: ASC
enum:
- ASC
- DESC
- name: limit
in: query
required: false
description: Maximum number of items to be returned.
schema:
type: integer
minimum: 1
maximum: 2049
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/Bids'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'404':
description: Not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
'/state':
get:
tags:
- Hermez status
summary: Return information that represents the current state of the network.
description: Return information that represents the current state of the network. It also includes metrics and statistics.
operationId: getState
responses:
'200':
description: Successful operation.
content:
application/json:
schema:
$ref: '#/components/schemas/State'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
'/config':
get:
tags:
- Hermez status
summary: Return constant configuration of the network.
description: Return constant configuration of the network.
operationId: getConfig
responses:
'200':
description: Successful operation.
content:
application/json:
schema:
$ref: '#/components/schemas/Config'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
'/tokens':
get:
tags:
- Hermez status
summary: Get information of the supported tokens in the Hermez network.
description: Get information of the supported tokens in the Hermez network.
operationId: getTokens
parameters:
- name: ids
in: query
required: false
description: Include only specific tokens by their Hermez identifiers.
schema:
type: string
description: Comma separated list of token identifiers
example: "2,44,689"
- name: symbols
in: query
required: false
description: Include only specific tokens by their symbols.
schema:
type: string
description: Comma separated list of token symbols.
example: "DAI,NEC,UMA"
- name: name
in: query
required: false
description: Include token(s) by their names (or a substring of the name).
schema:
type: string
- name: fromItem
in: query
required: false
description: Indicates the desired first item (using the itemId property) to be included in the response.
schema:
type: number
- name: order
in: query
required: false
description: Order of the returned items. Tokens will be ordered by increasing tokenID.
schema:
type: string
default: ASC
enum:
- ASC
- DESC
- name: limit
in: query
required: false
description: Maximum number of items to be returned.
schema:
type: integer
minimum: 1
maximum: 2049
responses:
'200':
description: Successful operation.
content:
application/json:
schema:
$ref: '#/components/schemas/Tokens'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'404':
description: Not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
'/tokens/{id}':
get:
tags:
- Hermez status
summary: Get information of a token supported by Hermez network.
description: Get information of a token supported by Hermez network.
operationId: getToken
parameters:
- name: id
in: path
description: Token identifier
required: true
schema:
$ref: '#/components/schemas/TokenId'
responses:
'200':
description: Successful operation.
content:
application/json:
schema:
$ref: '#/components/schemas/Token'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'404':
description: Not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
'/coordinators':
get:
tags:
- Hermez status
summary: Get information about coordinators.
description: Get information about coordinators.
operationId: getCoordinators
parameters:
- name: fromItem
in: query
required: false
description: Indicates the desired first item (using the itemId property) to be included in the response.
schema:
type: number
- name: order
in: query
required: false
description: Order of the returned items. Coordinators will be ordered by increasing (ethereumBlock, forgerAddr).
schema:
type: string
default: ASC
enum:
- ASC
- DESC
- name: limit
in: query
required: false
description: Maximum number of items to be returned.
schema:
type: integer
minimum: 1
maximum: 2049
responses:
'200':
description: Successful operation.
content:
application/json:
schema:
$ref: '#/components/schemas/Coordinators'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
'/coordinators/{bidderAddr}':
get:
tags:
- Hermez status
summary: Get the information of a coordinator.
description: Get the information of a coordinator.
operationId: getCoordinator
parameters:
- name: bidderAddr
in: path
description: Coordinator identifier
required: true
schema:
$ref: '#/components/schemas/EthereumAddress'
responses:
'200':
description: Successful operation.
content:
application/json:
schema:
$ref: '#/components/schemas/Coordinator'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'404':
description: Not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
components:
schemas:
ItemId:
type: integer
description: Position of the item in the DB. This is useful for pagination, but has nothing to do with the protocol.
PostPoolL2Transaction:
type: object
description: L2 transaction to be posted.
properties:
id:
$ref: '#/components/schemas/TransactionId'
type:
$ref: '#/components/schemas/TransactionTypeL2'
tokenId:
$ref: '#/components/schemas/TokenId'
fromAccountIndex:
$ref: '#/components/schemas/AccountIndex'
toAccountIndex:
type: string
description: >-
Identifier of the destination account. It references the position where the account is inside the state Merkle tree.
The identifier is built using: `hez:` + `token symbol:` + `index`. If this is provided, toHezEthereumAddress and toBjj
must be null. To perform an exit the value hez:EXIT:1 must be used.
example: null
nullable: true
toHezEthereumAddress:
type: string
description: "Address of an Etherum account linked to the Hermez network. If this is provided, toAccountIndex and toBjj must be null."
pattern: "^hez:0x[a-fA-F0-9]{40}$"
example: "hez:0xaa942cfcd25ad4d90a62358b0dd84f33b398262a"
nullable: true
toBjj:
type: string
description: >-
BabyJubJub public key, encoded as base64 URL (RFC 4648), which result in 33 bytes. The padding byte is replaced by a sum of the encoded bytes.
If this is prvided, toAccountIndex must be null and toHezEthereumAddress must be hez:0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF.
pattern: "^hez:[A-Za-z0-9_-]{44}$"
example: null
nullable: true
amount:
allOf:
- $ref: '#/components/schemas/BigInt'
- description: Amount of tokens to be sent.
example: "6300000000000000000"
fee:
$ref: '#/components/schemas/FeeSelector'
nonce:
$ref: '#/components/schemas/Nonce'
signature:
allOf:
- $ref: '#/components/schemas/BJJSignature'
- description: Signature of the transaction. More info [here](https://idocs.hermez.io/#/spec/zkrollup/README?id=l2a-idl2).
- example: "72024a43f546b0e1d9d5d7c4c30c259102a9726363adcc4ec7b6aea686bcb5116f485c5542d27c4092ae0ceaf38e3bb44417639bd2070a58ba1aa1aab9d92c03"
requestFromAccountIndex:
type: string
description: References the `fromAccountIndex` of the requested transaction.
example: null
nullable: true
requestToAccountIndex:
type: string
description: References the `toAccountIndex` of the requested transaction.
example: null
nullable: true
requestToHezEthereumAddress:
type: string
description: References the `toHezEthereumAddress` of the requested transaction.
pattern: "^hez:0x[a-fA-F0-9]{40}$"
example: null
nullable: true
requestToBjj:
type: string
description: References the `toBjj` of the requested transaction.
pattern: "^hez:[A-Za-z0-9_-]{44}$"
example: null
nullable: true
requestTokenId:
type: integer
description: References the `tokenId` of the requested transaction.
example: null
nullable: true
requestAmount:
type: string
description: References the `amount` of the requested transaction.
example: null
nullable: true
requestFee:
type: integer
description: References the `fee` of the requested transaction.
example: null
nullable: true
requestNonce:
type: integer
description: References the `nonce` of the requested transaction.
example: null
nullable: true
required:
- id
- type
- tokenId
- fromAccountIndex
- amount
- fee
- nonce
- signature
PoolL2Transaction:
type: object
properties:
id:
$ref: '#/components/schemas/TransactionId'
type:
$ref: '#/components/schemas/TransactionTypeL2'
fromAccountIndex:
$ref: '#/components/schemas/AccountIndex'
fromHezEthereumAddress:
type: string
description: "Address of an Etherum account linked to the Hermez network."
pattern: "^hez:0x[a-fA-F0-9]{40}$"
example: "hez:0xaa942cfcd25ad4d90a62358b0dd84f33b398262a"
nullable: true
fromBJJ:
type: string
description: "BabyJubJub public key, encoded as base64 URL (RFC 4648), which result in 33 bytes. The padding byte is replaced by a sum of the encoded bytes."
pattern: "^hez:[A-Za-z0-9_-]{44}$"
example: "hez:9CK9fjQdMUTGm8KDvGLy3MB-vnP0NCcGX7Uh7OO6KRJm"
nullable: true
toAccountIndex:
type: string
description: >-
Identifier of the destination account. It references the position where the account is inside the state Merkle tree.
The identifier is built using: `hez:` + `token symbol:` + `index`
example: "hez:DAI:309"
nullable: true
toHezEthereumAddress:
type: string
description: "Address of an Etherum account linked to the Hermez network."
pattern: "^hez:0x[a-fA-F0-9]{40}$"
example: null
nullable: true
toBjj:
type: string
description: "BabyJubJub public key, encoded as base64 URL (RFC 4648), which result in 33 bytes. The padding byte is replaced by a sum of the encoded bytes."
pattern: "^hez:[A-Za-z0-9_-]{44}$"
example: null
nullable: true
amount:
allOf:
- $ref: '#/components/schemas/BigInt'
- description: Amount of tokens to be sent.
example: "6303020000000000000"
fee:
$ref: '#/components/schemas/FeeSelector'
nonce:
$ref: '#/components/schemas/Nonce'
state:
$ref: '#/components/schemas/PoolL2TransactionState'
signature:
allOf:
- $ref: '#/components/schemas/BJJSignature'
- description: Signature of the transaction. More info [here](https://idocs.hermez.io/#/spec/zkrollup/README?id=l2a-idl2).
- example: "72024a43f546b0e1d9d5d7c4c30c259102a9726363adcc4ec7b6aea686bcb5116f485c5542d27c4092ae0ceaf38e3bb44417639bd2070a58ba1aa1aab9d92c03"
timestamp:
type: string
description: Moment in which the transaction was added to the pool.
format: date-time
batchNum:
type: integer
description: Identifier of a batch. Every new forged batch increments by one the batchNum, starting at 0.
minimum: 0
maximum: 4294967295
nullable: true
example: null
requestFromAccountIndex:
type: string
description: >-
Identifier of an account. It references the position where the account is inside the state Merkle tree.
The identifier is built using: `hez:` + `token symbol:` + `index`
nullable: true
example: null
requestToAccountIndex:
type: string
description: >-
Identifier of an account. It references the position where the account is inside the state Merkle tree.
The identifier is built using: `hez:` + `token symbol:` + `index`
nullable: true
example: null
requestToHezEthereumAddress:
type: string
description: "Address of an Etherum account linked to the Hermez network."
pattern: "^hez:0x[a-fA-F0-9]{40}$"
nullable: true
example: null
requestToBJJ:
type: string
description: "BabyJubJub public key, encoded as base64 URL (RFC 4648), which result in 33 bytes. The padding byte is replaced by a sum of the encoded bytes."
pattern: "^hez:[A-Za-z0-9_-]{44}$"
nullable: true
example: null
requestTokenId:
type: integer
description: References the `tokenId` of the requested transaction.
example: null
nullable: true
requestAmount:
type: string
description: BigInt is an integer encoded as a string for numbers that are very large.
nullable: true
example: null
requestFee:
type: integer
description: Index of the fee type to select, more info [here](https://idocs.hermez.io/#/spec/zkrollup/fee-table?id=transaction-fee-table).
minimum: 0
maximum: 256
nullable: true
example: null
requestNonce:
type: integer
description: Number that can only be used once per account. Increments by one with each transaction.
minimum: 0
maximum: 1.84467440737096e+19
nullable: true
example: null
token:
$ref: '#/components/schemas/Token'
required:
- id
- type
- fromAccountIndex
- fromHezEthereumAddress
- fromBJJ
- toAccountIndex
- toHezEthereumAddress
- toBjj
- amount
- fee
- nonce
- state
- signature
- timestamp
- batchNum
- requestFromAccountIndex
- requestToAccountIndex
- requestToHezEthereumAddress
- requestToBJJ
- requestTokenId
- requestAmount
- requestFee
- requestNonce
- token
TransactionId:
type: string
description: Identifier for transactions. Used for any kind of transaction (both L1 and L2). More info on how the identifiers are built [here](https://idocs.hermez.io/#/spec/architecture/db/README?id=txid)
example: "0x00000000000001e240004700"
EthereumAddress:
type: string
description: "Address of an Etherum account."
pattern: "^0x[a-fA-F0-9]{40}$"
example: "0xaa942cfcd25ad4d90a62358b0dd84f33b398262a"
HezEthereumAddress:
type: string
description: "Address of an Etherum account linked to the Hermez network."
pattern: "^hez:0x[a-fA-F0-9]{40}$"
example: "hez:0xaa942cfcd25ad4d90a62358b0dd84f33b398262a"
BJJ:
type: string
description: "BabyJubJub public key, encoded as base64 URL (RFC 4648), which result in 33 bytes. The padding byte is replaced by a sum of the encoded bytes."
pattern: "^hez:[A-Za-z0-9_-]{44}$"
example: "hez:rR7LXKal-av7I56Y0dEBCVmwc9zpoLY5ERhy5w7G-xwe"
AccountIndex:
type: string
description: >-
Identifier of an account. It references the position where the account is inside the state Merkle tree.
The identifier is built using: `hez:` + `token symbol:` + `index`
example: "hez:DAI:4444"
TransactionType:
type: string
description: Type of transaction.
enum:
- Exit
- Transfer
- Deposit
- CreateAccountDeposit
- CreateAccountDepositTransfer
- DepositTransfer
- ForceTransfer
- ForceExit
- TransferToEthAddr
- TransferToBJJ
TransactionTypeL2:
type: string
description: Type of transaction.
enum:
- Exit
- Transfer
- TransferToEthAddr
- TransferToBJJ
TokenId:
type: integer
description: Identifier of a token registered in the network.
minimum: 0
maximum: 4294967295
example: 98765
BigInt:
type: string
description: BigInt is an integer encoded as a string for numbers that are very large.
example: "8708856933496328593"
pattern: "^\\d+$"
FeeSelector:
type: integer
description: Index of the fee type to select, more info [here](https://idocs.hermez.io/#/spec/zkrollup/fee-table?id=transaction-fee-table).
minimum: 0
maximum: 256
example: 36
Nonce:
type: integer
description: Number that can only be used once per account, increments by one at each transaction.
minimum: 0
maximum: 1.84467440737096e+19
example: 121
PoolL2TransactionState:
type: string
description: >
State of a L2 transaction from the coordinator pool.
* pend: Pending
* fing: Forging
* fged: Forged
* invl: Invalid
enum:
- pend
- fing
- fged
- invl
ETHSignature:
type: string
description: Ethereum signature.
pattern: "^0x[a-fA-F0-9]{130}$"
example: "0xf9161cd688394772d93aa3e7b3f8f9553ca4f94f65b7cece93ed4a239d5c0b4677dca6d1d459e3a5c271a34de735d4664a43e5a8960a9a6e027d12c562dd448e1c"
BJJSignature:
type: string
description: BabyJubJub compressed signature.
pattern: "^[a-fA-F0-9]{128}$"
example: "72024a43f546b0e1d9d5d7c4c30c259102a9726363adcc4ec7b6aea686bcb5116f485c5542d27c4092ae0ceaf38e3bb44417639bd2070a58ba1aa1aab9d92c03"
BatchNum:
type: integer
description: Identifier of a batch. Every new forged batch increments by one the batchNum, starting at 0.
minimum: 0
maximum: 4294967295
example: 5432
AccountCreationAuthorizationPost:
type: object
properties:
hezEthereumAddress:
$ref: '#/components/schemas/HezEthereumAddress'
bjj:
$ref: '#/components/schemas/BJJ'
signature:
$ref: '#/components/schemas/ETHSignature'
required:
- hezEthereumAddress
- bjj
- signature
AccountCreationAuthorization:
type: object
properties:
timestamp:
type: string
format: date-time
hezEthereumAddress:
$ref: '#/components/schemas/HezEthereumAddress'
bjj:
$ref: '#/components/schemas/BJJ'
signature:
$ref: '#/components/schemas/ETHSignature'
required:
- timestamp
- hezEthereumAddress
- bjj
- signature
HistoryTransaction:
type: object
description: Transaction of the Hermez network
properties:
L1orL2:
type: string
enum:
- L1
- L2
id:
$ref: '#/components/schemas/TransactionId'
itemId:
$ref: '#/components/schemas/ItemId'
type:
$ref: '#/components/schemas/TransactionType'
position:
$ref: '#/components/schemas/TransactionPosition'
fromAccountIndex:
type: string
description: >-
Identifier of an account. It references the position where the account is inside the state Merkle tree.
The identifier is built using: `hez:` + `token symbol:` + `index`
example: "hez:DAI:4444"
nullable: true
fromHezEthereumAddress:
type: string
description: "Address of an Etherum account linked to the Hermez network."
pattern: "^hez:0x[a-fA-F0-9]{40}$"
example: "hez:0xaa942cfcd25ad4d90a62358b0dd84f33b398262a"
nullable: true
fromBJJ:
type: string
description: "BabyJubJub public key, encoded as base64 URL (RFC 4648), which result in 33 bytes. The padding byte is replaced by a sum of the encoded bytes."
pattern: "^hez:[A-Za-z0-9_-]{44}$"
example: "hez:9CK9fjQdMUTGm8KDvGLy3MB-vnP0NCcGX7Uh7OO6KRJm"
nullable: true
toAccountIndex:
allOf:
- $ref: '#/components/schemas/AccountIndex'
- example: "hez:DAI:672"
toHezEthereumAddress:
type: string
description: "Address of an Etherum account linked to the Hermez network."
pattern: "^hez:0x[a-fA-F0-9]{40}$"
example: "hez:0xaa942cfcd25ad4d90a62358b0dd84f33b398262a"
nullable: true
toBJJ:
type: string
description: "BabyJubJub public key, encoded as base64 URL (RFC 4648), which result in 33 bytes. The padding byte is replaced by a sum of the encoded bytes."
pattern: "^hez:[A-Za-z0-9_-]{44}$"
example: "hez:f1J78_6uqTyjX6jrVCqN4RFeRBnWQAGl477ZFtOnH6Sm"
nullable: true
amount:
allOf:
- $ref: '#/components/schemas/BigInt'
- description: Amount of tokens to be sent.
- example: "4903020000000000000"
batchNum:
type: integer
description: Batch in which the transaction was forged. Null indicates not forged yet.
minimum: 0
maximum: 4294967295
example: 5432
nullable: true
historicUSD:
type: number
description: Value in USD at the moment the transaction was forged.
example: 49.7
nullable: true
timestamp:
type: string
format: date-time
description: In the case of L1 indicates the moment where the transaction was added in the smart contract. For L2 indicates when the transaction was forged.
token:
$ref: '#/components/schemas/Token'
L1Info:
type: object
description: Additional information that only applies to L1 transactions.
nullable: true
properties:
toForgeL1TransactionsNum:
$ref: '#/components/schemas/ToForgeL1TransactionsNum'
userOrigin:
type: boolean
description: True if the transaction was sent by a user. False if it was sent by a coordinator.
loadAmount:
allOf:
- $ref: '#/components/schemas/BigInt'
- description: Tokens transfered from L1 to L2.
- example: "4900000000000000000"
historicLoadAmountUSD:
type: number
description: Load amount in USD, at the moment the transaction was made.
example: 3.897
nullable: true
ethereumBlockNum:
allOf:
- $ref: '#/components/schemas/EthBlockNum'
- description: Ethereum block in which the transaction was added to the smart contract forge queue.
- example: 258723049
required:
- toForgeL1TransactionsNum
- userOrigin
- loadAmount
- historicLoadAmountUSD
- ethereumBlockNum
additionalProperties: false
L2Info:
type: object
description: Additional information that only applies to L2 transactions.
nullable: true
properties:
fee:
$ref: '#/components/schemas/FeeSelector'
historicFeeUSD:
type: number
description: Fee in USD, at the moment the transaction was forged.
example: 263.89
nullable: true
nonce:
$ref: '#/components/schemas/Nonce'
example: null
required:
- fee
- historicFeeUSD
- nonce
additionalProperties: false
required:
- L1orL2
- id
- itemId
- type
- position
- fromAccountIndex
- fromHezEthereumAddress
- fromBJJ
- toAccountIndex
- toHezEthereumAddress
- toBJJ
- amount
- batchNum
- historicUSD
- timestamp
- token
- L1Info
- L2Info
additionalProperties: false
HistoryTransactions:
type: object
properties:
transactions:
type: array
description: List of history transactions.
items:
$ref: '#/components/schemas/HistoryTransaction'
pendingItems:
$ref: '#/components/schemas/PendingItems'
required:
- transactions
- pendingItems
additionalProperties: false
EthBlockNum:
type: integer
description: Ethereum block number
minimum: 0
maximum: 1.84467440737096e+19
example: 762375478
ToForgeL1TransactionsNum:
type: integer
description: Reference to know in which batch a L1 transaction was forged / will be forged.
minimum: 0
maximum: 4294967295
example: 784
nullable: true
TransactionPosition:
type: integer
description: Position that a transaction occupies in a batch.
minimum: 0
example: 5
URL:
type: string
description: HTTP URL
example: "https://hermez.io"
TokenSymbol:
type: string
description: Abreviation of the token name.
example: "DAI"
TokenName:
type: string
description: Token name.
example: "Dai"
CollectedFees:
type: object
description: Collected fees by the forger of the batch, represented by a map of tokenId => amount. A maximum of 64 different tokens can be used.
additionalProperties:
type: string
example:
1234: "425632785672345647"
4321: "86538967235465432654352"
Batch:
type: object
description: Group of transactions forged in a coordinator and sent and validated in Ethereum.
properties:
itemId:
$ref: '#/components/schemas/ItemId'
batchNum:
$ref: '#/components/schemas/BatchNum'
ethereumBlockNum:
$ref: '#/components/schemas/EthBlockNum'
ethereumBlockHash:
type: string
description: hash of the Ethereum block in which the batch was forged
example: "0xfe88c94d860f01a17f961bf4bdfb6e0c6cd10d3fda5cc861e805ca1240c58553"
timestamp:
type: string
format: date-time
description: Time in which the batch was forged.
forgerAddr:
$ref: '#/components/schemas/EthereumAddress'
collectedFees:
$ref: '#/components/schemas/CollectedFees'
historicTotalCollectedFeesUSD:
type: number
description: Sum of the all the fees collected, in USD, at the moment the batch was forged.
example: 23.3
stateRoot:
allOf:
- $ref: '#/components/schemas/Hash'
- description: Root of the accounts Merkle Tree.
- example: "2734657026572a8708d883"
numAccounts:
type: integer
description: Number of registered accounts in this batch.
exitRoot:
allOf:
- $ref: '#/components/schemas/Hash'
- description: Root of the exit Merkle Tree associated to this batch.
- example: "2734657026572a8708d883"
forgeL1TransactionsNum:
type: integer
description: Identifier that corresponds to the group of L1 transactions forged in the current batch.
example: 5
nullable: true
slotNum:
$ref: '#/components/schemas/SlotNum'
additionalProperties: false
required:
- itemId
- batchNum
- ethereumBlockNum
- ethereumBlockHash
- timestamp
- forgerAddr
- collectedFees
- historicTotalCollectedFeesUSD
- stateRoot
- numAccounts
- exitRoot
- forgeL1TransactionsNum
- slotNum
FullBatch:
type: object
description: Group of transactions forged in a coordinator and sent and validated in Ethereum.
properties:
batch:
$ref: '#/components/schemas/Batch'
transactions:
type: array
description: List of forged transactions in the batch
items:
$ref: '#/components/schemas/HistoryTransaction'
additionalProperties: false
required:
- batch
- transactions
Hash:
type: string
description: hashed data
example: "2734657026572a8708d883"
SlotNum:
type: integer
description: Identifier of a slot.
minimum: 0
maximum: 4294967295
example: 784
Batches:
type: object
properties:
batches:
type: array
description: List of batches.
items:
$ref: '#/components/schemas/Batch'
pendingItems:
$ref: '#/components/schemas/PendingItems'
additionalProperties: false
required:
- batches
- pendingItems
Coordinator:
type: object
properties:
itemId:
$ref: '#/components/schemas/ItemId'
forgerAddr:
$ref: '#/components/schemas/EthereumAddress'
bidderAddr:
$ref: '#/components/schemas/EthereumAddress'
URL:
$ref: '#/components/schemas/URL'
ethereumBlock:
allOf:
- $ref: '#/components/schemas/EthBlockNum'
- description: Ethereum block in which the coordinator registered into the network.
- example: 5735943738
additionalProperties: false
required:
- itemId
- forgerAddr
- bidderAddr
- URL
- ethereumBlock
Coordinators:
type: object
properties:
coordinators:
type: array
description: List of coordinators.
items:
$ref: '#/components/schemas/Coordinator'
pendingItems:
$ref: '#/components/schemas/PendingItems'
additionalProperties: false
required:
- coordinators
- pendingItems
Bid:
type: object
description: Tokens placed in an auction by a coordinator to gain the right to forge batches during a specific slot.
properties:
itemId:
$ref: '#/components/schemas/ItemId'
bidderAddr:
$ref: '#/components/schemas/EthereumAddress'
forgerAddr:
$ref: '#/components/schemas/EthereumAddress'
slotNum:
$ref: '#/components/schemas/SlotNum'
URL:
$ref: '#/components/schemas/URL'
bidValue:
$ref: '#/components/schemas/BigInt'
ethereumBlockNum:
$ref: '#/components/schemas/EthBlockNum'
timestamp:
type: string
format: date-time
additionalProperties: false
require:
- bidderAddr
- forgerAddr
- slotNum
- URL
- bidValue
- ethereumBlockNum
- timestamp
Bids:
type: object
properties:
bids:
type: array
description: List of bids.
items:
$ref: '#/components/schemas/Bid'
pendingItems:
$ref: '#/components/schemas/PendingItems'
additionalProperties: false
require:
- bids
- pendingItems
RecommendedFee:
type: object
description: Fee that the coordinator recommends per transaction in USD.
properties:
existingAccount:
type: number
description: Recommended fee if the destination account of the transaction already exists.
minimum: 0
example: 0.1
createAccount:
type: number
description: Recommended fee if the destination account of the transaction doesn't exist, but the coordinator has an authorization to create a valid account associated to an Ethereum address and a BJJ public key controlled by the receiver.
minimum: 0
example: 1.3
createAccountInternal:
type: number
description: Recommended fee if the destination account of the transaction doesn't exist, but the coordinator has the ability to create a valid account associated to a BJJ public key controlled by the receiver. Note that these kind of accounts are not associated to an Ethereum address and therefore can only operate in L2.
minimum: 0
example: 0.5
Token:
type: object
description: Hermez network compatible and registered token.
properties:
id:
$ref: '#/components/schemas/TokenId'
ethereumAddress:
allOf:
- $ref: '#/components/schemas/EthereumAddress'
- description: Ethereum address in which the token is deployed.
- example: "0xaa942cfcd25ad4d90a62358b0dd84f33b398262a"
itemId:
$ref: '#/components/schemas/ItemId'
name:
type: string
description: full name of the token
example: Maker Dai
symbol:
allOf:
- $ref: '#/components/schemas/TokenSymbol'
- example: DAI
decimals:
type: integer
description: Number of decimals of the token.
example: 18
ethereumBlockNum:
allOf:
- $ref: '#/components/schemas/EthBlockNum'
- description: Ethereum block number in which the token was added to the Hermez network.
- example: 539847538
USD:
type: number
description: Value of the token in USD.
example: 1.01
nullable: true
fiatUpdate:
type: string
format: date-time
description: Timestamp of the moment the `USD` value was updated.
nullable: true
required:
- id
- ethereumAddress
- itemId
- name
- symbol
- decimals
- ethereumBlockNum
- USD
- fiatUpdate
additionalProperties: false
Tokens:
type: object
properties:
tokens:
type: array
description: List of tokens.
items:
$ref: '#/components/schemas/Token'
pendingItems:
$ref: '#/components/schemas/PendingItems'
Exit:
type: object
description: Exit tree leaf. It Contains the necessary information to perform a withdrawal.
properties:
batchNum:
allOf:
- $ref: '#/components/schemas/BatchNum'
- description: Batch in which the exit was forged.
- example: 7394
accountIndex:
$ref: '#/components/schemas/AccountIndex'
itemId:
$ref: '#/components/schemas/ItemId'
merkleProof:
type: object
description: Existence proof of a leaf in a given Merkle Root. Encoded as hexadecimal string.
properties:
Root:
$ref: '#/components/schemas/BigInt'
Siblings:
type: array
items:
$ref: '#/components/schemas/BigInt'
OldKey:
$ref: '#/components/schemas/BigInt'
OldValue:
$ref: '#/components/schemas/BigInt'
IsOld0:
type: boolean
Key:
$ref: '#/components/schemas/BigInt'
Value:
$ref: '#/components/schemas/BigInt'
Fnc:
type: integer
maximum: 3
minimum: 0
required:
- Root
- Siblings
- OldKey
- OldValue
- IsOld0
- Key
- Value
- Fnc
additionalProperties: false
balance:
$ref: '#/components/schemas/BigInt'
instantWithdrawn:
type: integer
description: Block in which the exit balance was instantly withdrawn. Null indicates that an instant withdrawn hasn't been performed.
minimum: 0
maximum: 1.84467440737096e+19
example: 74747363
nullable: true
delayedWithdrawRequest:
type: integer
description: Block in which the exit balance was requested to delay withdraw. Null indicates that a delay withdraw hasn't been performed.
minimum: 0
maximum: 1.84467440737096e+19
example: null
nullable: true
delayedWithdrawn:
type: integer
description: Block in which the exit balance was delayed withdrawn after a delay withdraw request. Null indicates that a delay withdraw hasn't been performed.
minimum: 0
maximum: 1.84467440737096e+19
example: null
nullable: true
token:
$ref: '#/components/schemas/Token'
required:
- batchNum
- accountIndex
- itemId
- merkleProof
- balance
- instantWithdrawn
- delayedWithdrawRequest
- delayedWithdrawn
- token
additionalProperties: false
Exits:
type: object
properties:
exits:
type: array
description: List of exits.
items:
$ref: '#/components/schemas/Exit'
pendingItems:
$ref: '#/components/schemas/PendingItems'
required:
- exits
- pendingItems
additionalProperties: false
Account:
type: object
description: State tree leaf. It contains balance and nonce of an account.
properties:
itemId:
$ref: '#/components/schemas/ItemId'
accountIndex:
$ref: '#/components/schemas/AccountIndex'
nonce:
$ref: '#/components/schemas/Nonce'
balance:
$ref: '#/components/schemas/BigInt'
bjj:
$ref: '#/components/schemas/BJJ'
hezEthereumAddress:
$ref: '#/components/schemas/HezEthereumAddress'
token:
$ref: '#/components/schemas/Token'
additionaProperties: false
required:
- itemId
- accountIndex
- nonce
- balance
- bjj
- hezEthereumAddress
- token
Accounts:
type: object
properties:
accounts:
type: array
description: List of accounts.
items:
$ref: '#/components/schemas/Account'
pendingItems:
$ref: '#/components/schemas/PendingItems'
additionalProperties: false
required:
- accounts
- pendingItems
Slot:
type: object
description: Slot information.
properties:
itemId:
$ref: '#/components/schemas/ItemId'
slotNum:
$ref: '#/components/schemas/SlotNum'
firstBlock:
allOf:
- $ref: '#/components/schemas/EthBlockNum'
- description: Block in which the slot began or will begin
- example: 76238647846
lastBlock:
allOf:
- $ref: '#/components/schemas/EthBlockNum'
- description: Block in which the slot ended or will end
- example: 4475934
openAuction:
type: boolean
description: Whether the auction of the slot is open or not.
winnerBid:
type: object
description: The winning bid of the auction. If openAuction == true, is the current winner. If the auction is closed because it has already been finalized, the bid is the final winner. If the winnerBid is null, it is because no coordinator has bid for that slot.
nullable: true
properties:
itemId:
$ref: '#/components/schemas/ItemId'
bidderAddr:
$ref: '#/components/schemas/EthereumAddress'
forgerAddr:
$ref: '#/components/schemas/EthereumAddress'
slotNum:
$ref: '#/components/schemas/SlotNum'
URL:
$ref: '#/components/schemas/URL'
bidValue:
type: string
description: BigInt is an integer encoded as a string for numbers that are very large.
example: "8708856933496328593"
pattern: "^\\d+$"
ethereumBlockNum:
$ref: '#/components/schemas/EthBlockNum'
timestamp:
type: string
format: date-time
additionalProperties: false
require:
- bidderAddr
- forgerAddr
- slotNum
- URL
- bidValue
- ethereumBlockNum
- timestamp
additionalProperties: false
require:
- slotNum
- firstBlock
- lastBlock
- openAuction
- winner
- winnerBid
Slots:
type: object
properties:
slots:
type: array
description: List of slots.
items:
allOf:
- $ref: '#/components/schemas/Slot'
- description: Last synchronized Etherum block.
pendingItems:
$ref: '#/components/schemas/PendingItems'
additionalProperties: false
require:
- slots
- pendingItems
NextForger:
type: object
description: Coordinator information along with the scheduled forging period
properties:
coordinator:
$ref: '#/components/schemas/Coordinator'
period:
type: object
description: Time period in which the coordinator will have the ability to forge. Specified both in Ethereum blocks and timestamp
properties:
slotNum:
$ref: '#/components/schemas/SlotNum'
fromBlock:
$ref: '#/components/schemas/EthBlockNum'
toBlock:
$ref: '#/components/schemas/EthBlockNum'
fromTimestamp:
type: string
format: date-time
toTimestamp:
type: string
format: date-time
required:
- slotNum
- fromBlock
- toBlock
- fromTimestamp
- toTimestamp
additionalProperties: false
required:
- coordinator
- period
additionalProperties: false
NextForgers:
type: array
description: List of next coordinators to forge.
items:
$ref: '#/components/schemas/NextForger'
State:
type: object
description: Gobal variables of the network
properties:
network:
$ref: '#/components/schemas/StateNetwork'
metrics:
$ref: '#/components/schemas/StateMetrics'
rollup:
$ref: '#/components/schemas/StateRollup'
auction:
$ref: '#/components/schemas/StateAuction'
withdrawalDelayer:
$ref: '#/components/schemas/StateWithdrawDelayer'
recommendedFee:
$ref: '#/components/schemas/RecommendedFee'
additionalProperties: false
required:
- network
- metrics
- rollup
- auction
- withdrawalDelayer
- recommendedFee
StateNetwork:
type: object
description: Gobal statistics of the network
properties:
lastBlock:
allOf:
- $ref: '#/components/schemas/EthBlockNum'
- description: Last synchronized Etherum block.
- example: 3457437
lastBatch:
$ref: '#/components/schemas/Batch'
currentSlot:
allOf:
- $ref: '#/components/schemas/SlotNum'
- description: Slot where batches are currently being forged.
- example: 2334
nextForgers:
$ref: '#/components/schemas/NextForgers'
additionalProperties: false
required:
- lastBlock
- lastBatch
- currentSlot
- nextForgers
StateAuction:
type: object
description: Auction parameters.
properties:
ethereumBlockNum:
$ref: '#/components/schemas/EthBlockNum'
bootCoordinator:
allOf:
- $ref: '#/components/schemas/EthereumAddress'
- description: Ethereum address of the boot coordinator.
- example: "0x997dc4262BCDbf85190C01c996b4C06a461d2430"
slotDeadline:
type: integer
description: Number of blocks after the beginning of a slot after which any coordinator can forge if the winner has not forged any batch in that slot.
example: 3
closedAuctionSlots:
type: integer
description: Amount of slots between the current slot and the slot auction that is closed. Example if the value is 2, when slot 10 begins, the auction of the slot 12 gets closed.
example: 2
openAuctionSlots:
type: integer
description: How many days in advance are auctions opened.
defaultSlotSetBid:
type: array
description: "Initial minimal bid for each auction. Expressed as an array of 6 values. To calculate which value corresponds to each slot: `initialMinimalBidding[slotNum%6]`."
items:
type: integer
example: [32,0,68,21,55,99]
outbidding:
type: number
description: Minimum outbid over the previous one to consider it valid.
example: 3.64
donationAddress:
allOf:
- $ref: '#/components/schemas/EthereumAddress'
- description: Ethereum address where the donations will go to.
- example: "0x887dc4262BCDbf85190C01c996b4C06a461d2430"
allocationRatio:
type: array
description: Percentage in which fees will be splitted between donations, governance and burning. The sum of the tree values should be 100.
items:
type: integer
example: [80,10,10]
additionalProperties: false
required:
- ethereumBlockNum
- bootCoordinator
- slotDeadline
- closedAuctionSlots
- openAuctionSlots
- defaultSlotSetBid
- outbidding
- donationAddress
- allocationRatio
StateRollup:
type: object
description: Rollup parameters
properties:
ethereumBlockNum:
$ref: '#/components/schemas/EthBlockNum'
forgeL1L2BatchTimeout:
type: integer
description: Max ethereum blocks after the last L1-L2-batch, when exceeds the timeout only L1-L2-batch are allowed.
example: 5
feeAddToken:
type: integer
description: Fee to pay when registering tokens into the network.
example: 5698
withdrawalDelay:
type: integer
description: Withdraw delay in seconds
example: 432000
buckets:
type: array
description: List of buckets state
items:
type: object
properties:
ceilUSD:
type: integer
description: Max USD value
example: 1000
blockStamp:
type: integer
description: Last time a withdrawal was added ( or removed if the bucket was full)
example: 4475934
withdrawals:
type: integer
description: Available withdrawals of the bucket
example: 4
blockWithdrawalRate:
type: integer
description: Every `blockWithdrawalRate` blocks add 1 withdrawal
example: 8
maxWithdrawals:
type: integer
description: Max withdrawals the bucket can hold
example: 4
additionalProperties: false
required:
- ceilUSD
- blockStamp
- withdrawals
- blockWithdrawalRate
- maxWithdrawals
additionalProperties: false
required:
- ethereumBlockNum
- forgeL1L2BatchTimeout
- feeAddToken
- withdrawalDelay
- buckets
StateWithdrawDelayer:
type: object
description: Withdrawal delayer parameters
properties:
ethereumBlockNum:
$ref: '#/components/schemas/EthBlockNum'
hermezGovernanceDAOAddress:
allOf:
- $ref: '#/components/schemas/EthereumAddress'
- description: Ethereum address of the governance DAO.
- example: "0x667dc4262BCDbf85190C01c996b4C06a461d2430"
whiteHackGroupAddress:
allOf:
- $ref: '#/components/schemas/EthereumAddress'
- description: Ethereum Address that can claim the funds in an emergency when the maximum emergency mode time is exceeded.
- example: "0x557dc4262BCDbf85190C01c996b4C06a461d2430"
hermezKeeperAddress:
allOf:
- $ref: '#/components/schemas/EthereumAddress'
- description: Ethereum Address that can enable emergency mode and modify the delay to make a withdrawal.
- example: "0x557dc4262BCDbf85190C01c996b4C06a461d2430"
withdrawalDelay:
allOf:
- $ref: '#/components/schemas/EthBlockNum'
- description: The time that anyone needs to wait until a withdrawal of the funds is allowed, in seconds.
- example: 539573849
emergencyModeStartingTime:
type: integer
description: Second (since unix epoch) in which the emergency mode has been activated.
example: 10
emergencyMode:
type: boolean
description: Indicates if emergency mode has been activated.
example: false
additionalProperties: false
required:
- ethereumBlockNum
- hermezGovernanceDAOAddress
- whiteHackGroupAddress
- hermezKeeperAddress
- withdrawalDelay
- emergencyModeStartingTime
- emergencyMode
StateMetrics:
type: object
description: Metrics of the network
properties:
transactionsPerBatch:
type: number
description: Average transactions per batch in the last 24 hours.
example: 2002.7
batchFrequency:
type: number
description: Average elapsed time between batches in the last 24 hours, in seconds.
example: 8.9
transactionsPerSecond:
type: number
description: Average transactions per second in the last 24 hours.
example: 302.3
totalAccounts:
type: integer
description: Number of created accounts.
example: 90473
totalBJJs:
type: integer
description: Number of different registered BJJs.
example: 23067
avgTransactionFee:
type: number
description: Average fee percentage paid for L2 transactions in the last 24 hours.
example: 1.54
additionalProperties: false
required:
- transactionsPerBatch
- batchFrequency
- transactionsPerSecond
- totalAccounts
- totalBJJs
- avgTransactionFee
PendingItems:
type: integer
description: Amount of items that will be returned in subsequent calls to the endpoint, as long as they are done with same filters. When the value is 0 it means that all items have been sent.
example: 15
Config:
type: object
description: Configuration parameters of the different smart contracts that power the Hermez network.
properties:
hermez:
type: object
description: Constant configuration of the Hermez smart contract.
properties:
publicConstants:
type: object
description: Public Hermez smart contract constants
properties:
tokenHEZ:
allOf:
- $ref: '#/components/schemas/EthereumAddress'
- description: Ethereum address of the HEZ token.
- example: "0x444dc4262BCDbf85190C01c996b4C06a461d2430"
absoluteMaxL1L2BatchTimeout:
type: integer
description: L1L2 Batch Timeout
example: 240
verifiers:
type: array
description: List of verifiers struct
items:
type: object
properties:
maxTx:
type: integer
description: Maximum rollup transactions in a batch
example: 512
nlevels:
type: integer
description: Number of levels of the circuit
example: 32
required:
- maxTx
- nlevels
additionalProperties: false
hermezAuctionContract:
allOf:
- $ref: '#/components/schemas/EthereumAddress'
- description: Ethereum address of the auction smart contract.
- example: "0x111dc4262BCDbf85190C01c996b4C06a461d2430"
hermezGovernanceDAOAddress:
allOf:
- $ref: '#/components/schemas/EthereumAddress'
- description: Ethereum address of the governanceDAO.
- example: "0x222dc4262BCDbf85190C01c996b4C06a461d2430"
safetyAddress:
allOf:
- $ref: '#/components/schemas/EthereumAddress'
- description: Ethereum address of the safety.
- example: "0x333dc4262BCDbf85190C01c996b4C06a461d2430"
withdrawDelayerContract:
allOf:
- $ref: '#/components/schemas/EthereumAddress'
- description: Ethereum address of the withdraw delayer contracts.
- example: "0x444dc4262BCDbf85190C01c996b4C06a461d2430"
required:
- tokenHEZ
- absoluteMaxL1L2BatchTimeout
- verifiers
- hermezAuctionContract
- hermezGovernanceDAOAddress
- safetyAddress
- withdrawDelayerContract
additionalProperties: false
maxFeeIdxCoordinator:
type: integer
description: is the maximum number of tokens the coordinator can use to collect fees.
example: 64
reservedIdx:
type: integer
description: First 256 indexes reserved, first user index will be the 256.
example: 255
exitIdx:
type: integer
description: Account index used to indicate that a transaction is an `exit` or `force exit`.
example: 1
limitLoadAmount:
type: integer
description: Maximum load amount (L1 to L2) allowed.
example: 321
limitL2TransferAmount:
type: integer
description: Maximum amount (L2 to L2) allowed.
example: 837
limitTokens:
type: integer
description: Maximum number of different tokens that can be registered in the network.
example: 4294967295
l1CoordinatorTotalBytes:
type: integer
description: Number of bytes that a L1 coordinator transaction has ([4 bytes] token + [32 bytes] babyjub + [65 bytes] compressedSignature).
example: 101
l1UserTotalBytes:
type: integer
description: Number of bytes that a L1 user transaction has ([20 bytes] fromEthAddr + [32 bytes] fromBjj-compressed + [6 bytes] fromIdx + [2 bytes] loadAmountFloat16 + [2 bytes] amountFloat16 + [4 bytes] tokenId + [6 bytes] toIdx).
example: 72
maxL1UserTx:
type: integer
description: Maximum L1-user transactions allowed to be queued in a batch.
example: 128
maxL1Tx:
type: integer
description: Maximum L1 transactions allowed to be queued in a batch.
example: 256
inputSHAConstantBytes:
type: integer
description: Input SHA constant bytes
example: 18542
numBuckets:
type: integer
description: Number of buckets
example: 5
maxWithdrawalDelay:
type: integer
description: Maximum delay to withdraw tokens. Time is measured in seconds.
example: 2 * 7 * 24 * 60 * 60
exchangeMultiplier:
type: integer
description: exchange multiplier
example: 1e14
required:
- publicConstants
- reservedIdx
- exitIdx
- limitLoadAmount
- limitL2TransferAmount
- limitTokens
- l1CoordinatorTotalBytes
- l1UserTotalBytes
- maxL1UserTx
- maxL1Tx
- inputSHAConstantBytes
- numBuckets
- maxWithdrawalDelay
- exchangeMultiplier
additionalProperties: false
auction:
type: object
description: Constant configuration of the auction smart contract.
properties:
blocksPerSlot:
type: integer
description: Blocks per slot.
initialMinimalBidding:
type: integer
description: Minimum bid when no one has bid yet.
genesisBlockNum:
allOf:
- $ref: '#/components/schemas/EthBlockNum'
- description: Ethereum block number in which the smart contract starts operating.
tokenHEZ:
allOf:
- $ref: '#/components/schemas/EthereumAddress'
- description: Ethereum address of the HEZ token.
- example: "0x333dc4262BCDbf85190C01c996b4C06a461d2430"
hermezRollup:
allOf:
- $ref: '#/components/schemas/EthereumAddress'
- description: Ethereum address of the rollup smart contract.
- example: "0x222dc4262BCDbf85190C01c996b4C06a461d2430"
governanceAddress:
allOf:
- $ref: '#/components/schemas/EthereumAddress'
- description: Ethereum address of the governance.
- example: "0x444dc4262BCDbf85190C01c996b4C06a461d2430"
required:
- blocksPerSlot
- initialMinimalBidding
- genesisBlockNum
- tokenHEZ
- hermezRollup
- governanceAddress
additionalProperties: false
withdrawalDelayer:
type: object
description: Constant configuration of the withdrawal delayer smart contract.
properties:
maxWithdrawalDelay:
type: integer
description: Maximum time delay in which the tokens can be locked in the contract. Time is measured in seconds.
example: 200
maxEmergencyModeTime:
type: integer
description: Maximum amount of time in which the contract can be in emergency mode. Time is measured in seconds.
example: 2000
hermezRollup:
allOf:
- $ref: '#/components/schemas/EthereumAddress'
- description: Ethereum address of the rollup smart contract.
- example: "0x222dc4262BCDbf85190C01c996b4C06a461d2430"
required:
- maxWithdrawalDelay
- maxEmergencyModeTime
- hermezRollup
additionalProperties: false
required:
- hermez
- auction
- withdrawalDelayer
additionalProperties: false
Error:
type: object
description: Error response.
properties:
message:
type: string
Error400:
allOf:
- $ref: '#/components/schemas/Error'
- example:
message: Invalid signature.
Error404:
allOf:
- $ref: '#/components/schemas/Error'
- example:
message: Item(s) not found.
Error500:
allOf:
- $ref: '#/components/schemas/Error'
- example:
message: Database error.
|
