You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

2701 lines
94 KiB

  1. openapi: 3.0.0
  2. info:
  3. description: |
  4. 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.
  5. Example of these apps are:
  6. * Wallet: send L2 transactions, check balance, ...
  7. * Explorer: List transactions, slots, batches, ...
  8. * Exchange integrations
  9. ### Pagination
  10. #### Usage
  11. All the endpoints that return a list of undefined size use pagination. Unless the opposite is explicitly said.
  12. In order to use pagination, three query parameters are used:
  13. * `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).
  14. * `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.
  15. * `limit`: maximum amount of items to include in each response. Default is 20, maximum 2049.
  16. Responses for those endpoint will always include a `pagination` object. This object includes the total amount of items that the endpoint will return at a given time with the given filters. Apart from that, it also includes the `itemId` of the last and first items that will be returned (not in a single response but within the total items). These two properties can be used to know when to stop querying.
  17. #### Reorgs and safetyness
  18. 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).
  19. 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`.
  20. 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.
  21. ### Signatures
  22. The POST endpoint require to be signed using BabyJubJub or Ethereum keys. TODO: add references to libraries / examples / ...
  23. version: "0.0.1"
  24. title: Hermez Network API
  25. # termsOfService: 'http://swagger.io/terms/'
  26. # contact:
  27. # email: apiteam@swagger.io
  28. # license:
  29. # name: Apache 2.0
  30. # url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
  31. externalDocs:
  32. description: Find out more about Hermez.
  33. url: 'https://hermez.io'
  34. servers:
  35. - description: Hosted mock up
  36. url: http://167.71.59.190:4010
  37. - description: Localhost mock Up
  38. url: http://localhost:4010
  39. tags:
  40. - name: Account
  41. description: Hermez account and the tokens it holds.
  42. externalDocs:
  43. description: Find out more.
  44. url: 'https://idocs.hermez.io/#/spec/zkrollup/README?id=account-types'
  45. - name: Transaction
  46. description: Send tokens off chain and track transactions.
  47. externalDocs:
  48. description: Find out more
  49. url: 'https://idocs.hermez.io/#/spec/zkrollup/README?id=transaction-types'
  50. - name: Hermez status
  51. description: Info about operators, tokens, auctions and more.
  52. externalDocs:
  53. description: Find out more.
  54. url: 'https://idocs.hermez.io/#/spec/zkrollup/README'
  55. paths:
  56. '/account-creation-authorization':
  57. post:
  58. tags:
  59. - Account
  60. summary: Send an authorization that will allow the coordinator to register accounts associated to an Ethereum address on behalf of the user.
  61. description: >-
  62. 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*).
  63. operationId: postRegister
  64. requestBody:
  65. description: Account creation authorization.
  66. required: true
  67. content:
  68. application/json:
  69. schema:
  70. $ref: '#/components/schemas/AccountCreationAuthorizationPost'
  71. responses:
  72. '200':
  73. description: Successful operation.
  74. '400':
  75. description: Bad request.
  76. content:
  77. application/json:
  78. schema:
  79. $ref: '#/components/schemas/Error400'
  80. '500':
  81. description: Internal server error.
  82. content:
  83. application/json:
  84. schema:
  85. $ref: '#/components/schemas/Error500'
  86. '/account-creation-authorization/{hezEthereumAddress}':
  87. get:
  88. tags:
  89. - Account
  90. summary: Get to know if the coordinator has the ability to create accounts associated to an Ethereum address.
  91. description: >-
  92. 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.
  93. operationId: getAccountCreationAuthorization
  94. parameters:
  95. - name: hezEthereumAddress
  96. in: path
  97. description: Ethereum address.
  98. required: true
  99. schema:
  100. $ref: '#/components/schemas/HezEthereumAddress'
  101. responses:
  102. '200':
  103. description: Successful operation.
  104. content:
  105. application/json:
  106. schema:
  107. $ref: '#/components/schemas/AccountCreationAuthorization'
  108. '400':
  109. description: Bad request.
  110. content:
  111. application/json:
  112. schema:
  113. $ref: '#/components/schemas/Error400'
  114. '404':
  115. description: Not found.
  116. content:
  117. application/json:
  118. schema:
  119. $ref: '#/components/schemas/Error404'
  120. '500':
  121. description: Internal server error.
  122. content:
  123. application/json:
  124. schema:
  125. $ref: '#/components/schemas/Error500'
  126. '/accounts':
  127. get:
  128. tags:
  129. - Account
  130. summary: Get accounts balances and other associated information.
  131. description: Get accounts balances and other associated information.
  132. operationId: getAccounts
  133. parameters:
  134. - name: hezEthereumAddress
  135. in: query
  136. description: Only get accounts associated to an Ethereum address. Incompatible with the query `BJJ`.
  137. required: false
  138. schema:
  139. $ref: '#/components/schemas/HezEthereumAddress'
  140. - name: BJJ
  141. in: query
  142. description: Only get accounts associated to a BabyJubJub public key. Incompatible with the query `hezEthereumAddress`.
  143. required: false
  144. schema:
  145. $ref: '#/components/schemas/BJJ'
  146. - name: tokenIds
  147. in: query
  148. required: false
  149. description: Only get accounts of specific tokens.
  150. schema:
  151. type: string
  152. description: Comma separated list of token identifiers.
  153. example: "3,87,91"
  154. - name: fromItem
  155. in: query
  156. required: false
  157. description: Indicates the desired first item (using the itemId property) to be included in the response.
  158. schema:
  159. type: number
  160. - name: order
  161. in: query
  162. required: false
  163. description: Order of the returned items. Accounts will be ordered by increasing account index.
  164. schema:
  165. type: string
  166. default: ASC
  167. enum:
  168. - ASC
  169. - DESC
  170. - name: limit
  171. in: query
  172. required: false
  173. description: Maximum number of items to be returned.
  174. schema:
  175. type: integer
  176. minimum: 1
  177. maximum: 2049
  178. responses:
  179. '200':
  180. description: Successful operation.
  181. content:
  182. application/json:
  183. schema:
  184. $ref: '#/components/schemas/Accounts'
  185. '400':
  186. description: Bad request.
  187. content:
  188. application/json:
  189. schema:
  190. $ref: '#/components/schemas/Error400'
  191. '404':
  192. description: Not found.
  193. content:
  194. application/json:
  195. schema:
  196. $ref: '#/components/schemas/Error404'
  197. '500':
  198. description: Internal server error.
  199. content:
  200. application/json:
  201. schema:
  202. $ref: '#/components/schemas/Error500'
  203. '/accounts/{accountIndex}':
  204. get:
  205. tags:
  206. - Account
  207. summary: Get an account by its index.
  208. description: Get an account by its index.
  209. operationId: getAccount
  210. parameters:
  211. - name: accountIndex
  212. in: path
  213. description: Identifier of an account.
  214. required: true
  215. schema:
  216. $ref: '#/components/schemas/AccountIndex'
  217. responses:
  218. '200':
  219. description: Successful operation.
  220. content:
  221. application/json:
  222. schema:
  223. $ref: '#/components/schemas/Account'
  224. '400':
  225. description: Bad request.
  226. content:
  227. application/json:
  228. schema:
  229. $ref: '#/components/schemas/Error400'
  230. '404':
  231. description: Not found.
  232. content:
  233. application/json:
  234. schema:
  235. $ref: '#/components/schemas/Error404'
  236. '500':
  237. description: Internal server error.
  238. content:
  239. application/json:
  240. schema:
  241. $ref: '#/components/schemas/Error500'
  242. '/exits':
  243. get:
  244. tags:
  245. - Account
  246. summary: Get exit information. This information is required to perform a withdraw.
  247. description: Get exit information. This information is required to perform a withdraw.
  248. operationId: getExits
  249. parameters:
  250. - name: tokenId
  251. in: query
  252. required: false
  253. description: Only get exits of specific token
  254. schema:
  255. $ref: '#/components/schemas/TokenId'
  256. - name: hezEthereumAddress
  257. in: query
  258. description: Get exits associated to a Ethereum address. Incompatible with query `BJJ` and `accountIndex`.
  259. required: false
  260. schema:
  261. $ref: '#/components/schemas/HezEthereumAddress'
  262. - name: BJJ
  263. in: query
  264. description: Get exits associated to a BabyJubJub public key. Incompatible with query `hezEthereumAddress` and `accountIndex`.
  265. required: false
  266. schema:
  267. $ref: '#/components/schemas/BJJ'
  268. - name: accountIndex
  269. in: query
  270. description: Get exits associated to a specific account. Incompatible with queries `tokenId`, `hezEthereumAddress` and `BJJ`.
  271. required: false
  272. schema:
  273. $ref: '#/components/schemas/AccountIndex'
  274. - name: batchNum
  275. in: query
  276. description: Get exits from the exit tree of a specific batch.
  277. required: false
  278. schema:
  279. $ref: '#/components/schemas/BatchNum'
  280. - name: onlyPendingWithdraws
  281. in: query
  282. description: Get exits with pending withdrawals.
  283. required: false
  284. schema:
  285. type: boolean
  286. - name: fromItem
  287. in: query
  288. required: false
  289. description: Indicates the desired first item (using the itemId property) to be included in the response.
  290. schema:
  291. type: number
  292. - name: order
  293. in: query
  294. required: false
  295. description: Order of the returned items. Exits will be ordered by increasing (batchNum, accountIndex).
  296. schema:
  297. type: string
  298. default: ASC
  299. enum:
  300. - ASC
  301. - DESC
  302. - name: limit
  303. in: query
  304. required: false
  305. description: Maximum number of items to be returned.
  306. schema:
  307. type: integer
  308. minimum: 1
  309. maximum: 2049
  310. responses:
  311. '200':
  312. description: Successful operation.
  313. content:
  314. application/json:
  315. schema:
  316. $ref: '#/components/schemas/Exits'
  317. '400':
  318. description: Bad request.
  319. content:
  320. application/json:
  321. schema:
  322. $ref: '#/components/schemas/Error400'
  323. '404':
  324. description: Not found.
  325. content:
  326. application/json:
  327. schema:
  328. $ref: '#/components/schemas/Error404'
  329. '500':
  330. description: Internal server error.
  331. content:
  332. application/json:
  333. schema:
  334. $ref: '#/components/schemas/Error500'
  335. '/exits/{batchNum}/{accountIndex}':
  336. get:
  337. tags:
  338. - Account
  339. summary: Get specific exit information.
  340. 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.
  341. operationId: getExit
  342. parameters:
  343. - name: batchNum
  344. in: path
  345. description: Batch of the exit tree.
  346. required: true
  347. schema:
  348. $ref: '#/components/schemas/BatchNum'
  349. - name: accountIndex
  350. in: path
  351. description: Account identifier.
  352. required: true
  353. schema:
  354. $ref: '#/components/schemas/AccountIndex'
  355. responses:
  356. '200':
  357. description: Successful operation.
  358. content:
  359. application/json:
  360. schema:
  361. $ref: '#/components/schemas/Exit'
  362. '400':
  363. description: Bad request.
  364. content:
  365. application/json:
  366. schema:
  367. $ref: '#/components/schemas/Error400'
  368. '404':
  369. description: Not found.
  370. content:
  371. application/json:
  372. schema:
  373. $ref: '#/components/schemas/Error404'
  374. '500':
  375. description: Internal server error.
  376. content:
  377. application/json:
  378. schema:
  379. $ref: '#/components/schemas/Error500'
  380. '/transactions-pool':
  381. post:
  382. tags:
  383. - Transaction
  384. summary: Add an L2 transaction to the coordinator's pool
  385. description: >-
  386. Send L2 transaction. The transaction will be stored in the transaction pool of the coordinator and eventually forged.
  387. operationId: postTx
  388. requestBody:
  389. description: Signed transaction.
  390. required: true
  391. content:
  392. application/json:
  393. schema:
  394. $ref: '#/components/schemas/PostPoolL2Transaction'
  395. responses:
  396. '200':
  397. description: Successful operation.
  398. content:
  399. application/json:
  400. schema:
  401. $ref: '#/components/schemas/TransactionId'
  402. '400':
  403. description: Bad request.
  404. content:
  405. application/json:
  406. schema:
  407. $ref: '#/components/schemas/Error400'
  408. '500':
  409. description: Internal server error.
  410. content:
  411. application/json:
  412. schema:
  413. $ref: '#/components/schemas/Error500'
  414. '/transactions-pool/{id}':
  415. get:
  416. tags:
  417. - Transaction
  418. summary: Get details and status of a transaction that is in the pool.
  419. description: >-
  420. 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.
  421. Only transactions from the pool will be returned.
  422. Note that the transaction pool is different for each coordinator and therefore only a coordinator that has received a specific transaction
  423. will be able to provide information about that transaction.
  424. operationId: getPoolTx
  425. parameters:
  426. - name: id
  427. in: path
  428. description: Transaction identifier.
  429. required: true
  430. schema:
  431. $ref: '#/components/schemas/TransactionId'
  432. responses:
  433. '200':
  434. description: Successful operation.
  435. content:
  436. application/json:
  437. schema:
  438. $ref: '#/components/schemas/PoolL2Transaction'
  439. '400':
  440. description: Bad request.
  441. content:
  442. application/json:
  443. schema:
  444. $ref: '#/components/schemas/Error400'
  445. '404':
  446. description: Not found.
  447. content:
  448. application/json:
  449. schema:
  450. $ref: '#/components/schemas/Error404'
  451. '500':
  452. description: Internal server error.
  453. content:
  454. application/json:
  455. schema:
  456. $ref: '#/components/schemas/Error500'
  457. '/transactions-history':
  458. get:
  459. tags:
  460. - Transaction
  461. summary: Get details and status of transactions that have been forged.
  462. description: >-
  463. Get historical transactions. This endpoint will return all the different types of transactions except for:
  464. - Transactions that are still in the transaction pool of any coordinator. These transactions can be fetched using `GET /transactions-pool/{id}`.
  465. - L1 transactions sent by users that have not been forged yet. These transactions can be fetched using `GET /transactions-history/{id}`.
  466. operationId: getHistoryTxs
  467. parameters:
  468. - name: tokenId
  469. in: query
  470. required: false
  471. description: Only get transactions of specific token
  472. schema:
  473. $ref: '#/components/schemas/TokenId'
  474. - name: hezEthereumAddress
  475. in: query
  476. required: false
  477. description: Only get transactions sent from or to an account associated to an Ethereum address Incompatible with the queries `BJJ` and `accountIndex`.
  478. schema:
  479. $ref: '#/components/schemas/HezEthereumAddress'
  480. - name: BJJ
  481. in: query
  482. description: Only get transactions associated to a BabyJubJub public key. Incompatible with the queries `hezEthereumAddress` and `accountIndex`.
  483. required: false
  484. schema:
  485. $ref: '#/components/schemas/BJJ'
  486. - name: accountIndex
  487. in: query
  488. required: false
  489. description: Only get transactions sent from or to a specific account. Incompatible with the queries `tokenId`, `hezEthereumAddress` and `BJJ`.
  490. schema:
  491. $ref: '#/components/schemas/AccountIndex'
  492. - name: batchNum
  493. in: query
  494. required: false
  495. description: Only get transactions forged in a specific batch.
  496. schema:
  497. $ref: '#/components/schemas/BatchNum'
  498. - name: type
  499. in: query
  500. required: false
  501. description: Only get transactions of a specific type.
  502. schema:
  503. $ref: '#/components/schemas/TransactionType'
  504. - name: fromItem
  505. in: query
  506. required: false
  507. description: Indicates the desired first item (using the itemId property) to be included in the response.
  508. schema:
  509. type: number
  510. - name: order
  511. in: query
  512. required: false
  513. description: Order of the returned items. History transactions will be ordered by (batchNum, position).
  514. schema:
  515. type: string
  516. default: ASC
  517. enum:
  518. - ASC
  519. - DESC
  520. - name: limit
  521. in: query
  522. required: false
  523. description: Maximum number of items to be returned.
  524. schema:
  525. type: integer
  526. minimum: 1
  527. maximum: 2049
  528. responses:
  529. '200':
  530. description: Successful operation.
  531. content:
  532. application/json:
  533. schema:
  534. $ref: '#/components/schemas/HistoryTransactions'
  535. '400':
  536. description: Bad request.
  537. content:
  538. application/json:
  539. schema:
  540. $ref: '#/components/schemas/Error400'
  541. '404':
  542. description: Not found.
  543. content:
  544. application/json:
  545. schema:
  546. $ref: '#/components/schemas/Error404'
  547. '500':
  548. description: Internal server error.
  549. content:
  550. application/json:
  551. schema:
  552. $ref: '#/components/schemas/Error500'
  553. '/transactions-history/{id}':
  554. get:
  555. tags:
  556. - Transaction
  557. summary: Get details and status of a historical transaction.
  558. description: >-
  559. 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.
  560. operationId: getHistoryTx
  561. parameters:
  562. - name: id
  563. in: path
  564. description: Transaction identifier.
  565. required: true
  566. schema:
  567. $ref: '#/components/schemas/TransactionId'
  568. responses:
  569. '200':
  570. description: Successful operation.
  571. content:
  572. application/json:
  573. schema:
  574. $ref: '#/components/schemas/HistoryTransaction'
  575. '400':
  576. description: Bad request.
  577. content:
  578. application/json:
  579. schema:
  580. $ref: '#/components/schemas/Error400'
  581. '404':
  582. description: Not found.
  583. content:
  584. application/json:
  585. schema:
  586. $ref: '#/components/schemas/Error404'
  587. '500':
  588. description: Internal server error.
  589. content:
  590. application/json:
  591. schema:
  592. $ref: '#/components/schemas/Error500'
  593. '/batches':
  594. get:
  595. tags:
  596. - Hermez status
  597. summary: Get information about forged batches.
  598. description: >-
  599. Get information about forged batches.
  600. operationId: getBatches
  601. parameters:
  602. - name: minBatchNum
  603. in: query
  604. required: false
  605. description: Include only `batchNum > minBatchNum` batches.
  606. schema:
  607. $ref: '#/components/schemas/BatchNum'
  608. - name: maxBatchNum
  609. in: query
  610. required: false
  611. description: Include only `batchNum < maxBatchNum` batches.
  612. schema:
  613. type: number
  614. - name: slotNum
  615. in: query
  616. required: false
  617. description: Include only batches that were forged within the specified slot.
  618. schema:
  619. $ref: '#/components/schemas/SlotNum'
  620. - name: forgerAddr
  621. in: query
  622. required: false
  623. description: Include only batches forged by `forgerAddr`
  624. schema:
  625. $ref: '#/components/schemas/EthereumAddress'
  626. - name: fromItem
  627. in: query
  628. required: false
  629. description: Indicates the desired first item (using the itemId property) to be included in the response.
  630. schema:
  631. type: number
  632. - name: order
  633. in: query
  634. required: false
  635. description: Order of the returned items. Batches will be ordered by increasing `batchNum`.
  636. schema:
  637. type: string
  638. default: ASC
  639. enum:
  640. - ASC
  641. - DESC
  642. - name: limit
  643. in: query
  644. required: false
  645. description: Maximum number of items to be returned.
  646. schema:
  647. type: integer
  648. minimum: 1
  649. maximum: 2049
  650. responses:
  651. '200':
  652. description: Successful operation.
  653. content:
  654. application/json:
  655. schema:
  656. $ref: '#/components/schemas/Batches'
  657. '400':
  658. description: Bad request.
  659. content:
  660. application/json:
  661. schema:
  662. $ref: '#/components/schemas/Error400'
  663. '404':
  664. description: Not found.
  665. content:
  666. application/json:
  667. schema:
  668. $ref: '#/components/schemas/Error404'
  669. '500':
  670. description: Internal server error.
  671. content:
  672. application/json:
  673. schema:
  674. $ref: '#/components/schemas/Error500'
  675. '/batches/{batchNum}':
  676. get:
  677. tags:
  678. - Hermez status
  679. summary: Get a specific batch.
  680. description: >-
  681. Get a specific batch.
  682. operationId: getBatch
  683. parameters:
  684. - name: batchNum
  685. in: path
  686. description: Batch identifier.
  687. required: true
  688. schema:
  689. $ref: '#/components/schemas/BatchNum'
  690. responses:
  691. '200':
  692. description: Successful operation
  693. content:
  694. application/json:
  695. schema:
  696. $ref: '#/components/schemas/Batch'
  697. '400':
  698. description: Bad request.
  699. content:
  700. application/json:
  701. schema:
  702. $ref: '#/components/schemas/Error400'
  703. '404':
  704. description: Not found.
  705. content:
  706. application/json:
  707. schema:
  708. $ref: '#/components/schemas/Error404'
  709. '500':
  710. description: Internal server error.
  711. content:
  712. application/json:
  713. schema:
  714. $ref: '#/components/schemas/Error500'
  715. '/full-batches/{batchNum}':
  716. get:
  717. tags:
  718. - Hermez status
  719. summary: Get a full batch
  720. description: >-
  721. Get a specific batch, including the associated transactions. The object returned in this method can be a bit heavy.
  722. If you're devloping a front end, you may consider using a combinaton of `GET /batches/{batchnum}` and `GET /history-transactions?batchNum={batchNum}`.
  723. operationId: getFullBatch
  724. parameters:
  725. - name: batchNum
  726. in: path
  727. description: Batch identifier
  728. required: true
  729. schema:
  730. $ref: '#/components/schemas/BatchNum'
  731. responses:
  732. '200':
  733. description: successful operation
  734. content:
  735. application/json:
  736. schema:
  737. $ref: '#/components/schemas/FullBatch'
  738. '400':
  739. description: Bad request.
  740. content:
  741. application/json:
  742. schema:
  743. $ref: '#/components/schemas/Error400'
  744. '404':
  745. description: Not found.
  746. content:
  747. application/json:
  748. schema:
  749. $ref: '#/components/schemas/Error404'
  750. '500':
  751. description: Internal server error.
  752. content:
  753. application/json:
  754. schema:
  755. $ref: '#/components/schemas/Error500'
  756. '/slots':
  757. get:
  758. tags:
  759. - Hermez status
  760. summary: Get information about slots.
  761. description: >-
  762. Get information about slots.
  763. operationId: getSlots
  764. parameters:
  765. - name: minSlotNum
  766. in: query
  767. required: false
  768. description: Only include batches with `slotNum < minSlotNum`.
  769. schema:
  770. $ref: '#/components/schemas/SlotNum'
  771. - name: maxSlothNum
  772. in: query
  773. required: false
  774. description: Only include batches with `slotNum > maxSlotNum`.
  775. schema:
  776. $ref: '#/components/schemas/SlotNum'
  777. - name: wonByEthereumAddress
  778. in: query
  779. required: false
  780. description: Only include slots won by a coordinator whose `forgerAddr == wonByEthereumAddress`.
  781. schema:
  782. $ref: '#/components/schemas/EthereumAddress'
  783. - name: finishedAuction
  784. in: query
  785. required: false
  786. description: If set to true, only include slots whose auction has finished.
  787. schema:
  788. type: boolean
  789. - name: fromItem
  790. in: query
  791. required: false
  792. description: Indicates the desired first item (using the itemId property) to be included in the response.
  793. schema:
  794. type: number
  795. - name: order
  796. in: query
  797. required: false
  798. description: Order of the returned items. Slots will be ordered by increasing `slotNum`.
  799. schema:
  800. type: string
  801. default: ASC
  802. enum:
  803. - ASC
  804. - DESC
  805. - name: limit
  806. in: query
  807. required: false
  808. description: Maximum number of items to be returned.
  809. schema:
  810. type: integer
  811. minimum: 1
  812. maximum: 2049
  813. responses:
  814. '200':
  815. description: Successful operation.
  816. content:
  817. application/json:
  818. schema:
  819. $ref: '#/components/schemas/Slots'
  820. '400':
  821. description: Bad request.
  822. content:
  823. application/json:
  824. schema:
  825. $ref: '#/components/schemas/Error400'
  826. '404':
  827. description: Not found.
  828. content:
  829. application/json:
  830. schema:
  831. $ref: '#/components/schemas/Error404'
  832. '500':
  833. description: Internal server error.
  834. content:
  835. application/json:
  836. schema:
  837. $ref: '#/components/schemas/Error500'
  838. '/slots/{slotNum}':
  839. get:
  840. tags:
  841. - Hermez status
  842. summary: Get information about a specific slot.
  843. description: >-
  844. Get information about a specific slot.
  845. operationId: getSlot
  846. parameters:
  847. - name: slotNum
  848. in: path
  849. required: true
  850. description: Identifier of the slot.
  851. schema:
  852. $ref: '#/components/schemas/SlotNum'
  853. responses:
  854. '200':
  855. description: Successful operation.
  856. content:
  857. application/json:
  858. schema:
  859. $ref: '#/components/schemas/Slot'
  860. '400':
  861. description: Bad request.
  862. content:
  863. application/json:
  864. schema:
  865. $ref: '#/components/schemas/Error400'
  866. '404':
  867. description: Not found.
  868. content:
  869. application/json:
  870. schema:
  871. $ref: '#/components/schemas/Error404'
  872. '500':
  873. description: Internal server error.
  874. content:
  875. application/json:
  876. schema:
  877. $ref: '#/components/schemas/Error500'
  878. '/bids':
  879. get:
  880. tags:
  881. - Hermez status
  882. summary: Get a list of bids made for a specific slot auction.
  883. description: Get a list of bids made for a specific slot auction. Is necessary to add a filter (`slotNum` or `bidderAddr`).
  884. operationId: getSlotBids
  885. parameters:
  886. - name: slotNum
  887. in: query
  888. description: Slot identifier. Specify the auction where the returned bids were made.
  889. required: false
  890. schema:
  891. $ref: '#/components/schemas/SlotNum'
  892. - name: bidderAddr
  893. in: query
  894. 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.
  895. required: false
  896. schema:
  897. $ref: '#/components/schemas/EthereumAddress'
  898. - name: fromItem
  899. in: query
  900. required: false
  901. description: Indicates the desired first item (using the itemId property) to be included in the response.
  902. schema:
  903. type: number
  904. - name: order
  905. in: query
  906. required: false
  907. description: Order of the returned items. Bids will be ordered by increasing (slotNum, bidValue)`.
  908. schema:
  909. type: string
  910. default: ASC
  911. enum:
  912. - ASC
  913. - DESC
  914. - name: limit
  915. in: query
  916. required: false
  917. description: Maximum number of items to be returned.
  918. schema:
  919. type: integer
  920. minimum: 1
  921. maximum: 2049
  922. responses:
  923. '200':
  924. description: Successful operation
  925. content:
  926. application/json:
  927. schema:
  928. $ref: '#/components/schemas/Bids'
  929. '400':
  930. description: Bad request.
  931. content:
  932. application/json:
  933. schema:
  934. $ref: '#/components/schemas/Error400'
  935. '404':
  936. description: Not found.
  937. content:
  938. application/json:
  939. schema:
  940. $ref: '#/components/schemas/Error404'
  941. '500':
  942. description: Internal server error.
  943. content:
  944. application/json:
  945. schema:
  946. $ref: '#/components/schemas/Error500'
  947. '/state':
  948. get:
  949. tags:
  950. - Hermez status
  951. summary: Return information that represents the current state of the network.
  952. description: Return information that represents the current state of the network. It also includes metrics and statistics.
  953. operationId: getState
  954. responses:
  955. '200':
  956. description: Successful operation.
  957. content:
  958. application/json:
  959. schema:
  960. $ref: '#/components/schemas/State'
  961. '400':
  962. description: Bad request.
  963. content:
  964. application/json:
  965. schema:
  966. $ref: '#/components/schemas/Error400'
  967. '500':
  968. description: Internal server error.
  969. content:
  970. application/json:
  971. schema:
  972. $ref: '#/components/schemas/Error500'
  973. '/config':
  974. get:
  975. tags:
  976. - Hermez status
  977. summary: Return constant configuration of the network.
  978. description: Return constant configuration of the network.
  979. operationId: getConfig
  980. responses:
  981. '200':
  982. description: Successful operation.
  983. content:
  984. application/json:
  985. schema:
  986. $ref: '#/components/schemas/Config'
  987. '500':
  988. description: Internal server error.
  989. content:
  990. application/json:
  991. schema:
  992. $ref: '#/components/schemas/Error500'
  993. '/tokens':
  994. get:
  995. tags:
  996. - Hermez status
  997. summary: Get information of the supported tokens in the Hermez network.
  998. description: Get information of the supported tokens in the Hermez network.
  999. operationId: getTokens
  1000. parameters:
  1001. - name: ids
  1002. in: query
  1003. required: false
  1004. description: Include only specific tokens by their Hermez identifiers.
  1005. schema:
  1006. type: string
  1007. description: Comma separated list of token identifiers
  1008. example: "2,44,689"
  1009. - name: symbols
  1010. in: query
  1011. required: false
  1012. description: Include only specific tokens by their symbols.
  1013. schema:
  1014. type: string
  1015. description: Comma separated list of token symbols.
  1016. example: "DAI,NEC,UMA"
  1017. - name: name
  1018. in: query
  1019. required: false
  1020. description: Include token(s) by their names (or a substring of the name).
  1021. schema:
  1022. type: string
  1023. - name: fromItem
  1024. in: query
  1025. required: false
  1026. description: Indicates the desired first item (using the itemId property) to be included in the response.
  1027. schema:
  1028. type: number
  1029. - name: order
  1030. in: query
  1031. required: false
  1032. description: Order of the returned items. Tokens will be ordered by increasing tokenID.
  1033. schema:
  1034. type: string
  1035. default: ASC
  1036. enum:
  1037. - ASC
  1038. - DESC
  1039. - name: limit
  1040. in: query
  1041. required: false
  1042. description: Maximum number of items to be returned.
  1043. schema:
  1044. type: integer
  1045. minimum: 1
  1046. maximum: 2049
  1047. responses:
  1048. '200':
  1049. description: Successful operation.
  1050. content:
  1051. application/json:
  1052. schema:
  1053. $ref: '#/components/schemas/Tokens'
  1054. '400':
  1055. description: Bad request.
  1056. content:
  1057. application/json:
  1058. schema:
  1059. $ref: '#/components/schemas/Error400'
  1060. '404':
  1061. description: Not found.
  1062. content:
  1063. application/json:
  1064. schema:
  1065. $ref: '#/components/schemas/Error404'
  1066. '500':
  1067. description: Internal server error.
  1068. content:
  1069. application/json:
  1070. schema:
  1071. $ref: '#/components/schemas/Error500'
  1072. '/tokens/{id}':
  1073. get:
  1074. tags:
  1075. - Hermez status
  1076. summary: Get information of a token supported by Hermez network.
  1077. description: Get information of a token supported by Hermez network.
  1078. operationId: getToken
  1079. parameters:
  1080. - name: id
  1081. in: path
  1082. description: Token identifier
  1083. required: true
  1084. schema:
  1085. $ref: '#/components/schemas/TokenId'
  1086. responses:
  1087. '200':
  1088. description: Successful operation.
  1089. content:
  1090. application/json:
  1091. schema:
  1092. $ref: '#/components/schemas/Token'
  1093. '400':
  1094. description: Bad request.
  1095. content:
  1096. application/json:
  1097. schema:
  1098. $ref: '#/components/schemas/Error400'
  1099. '404':
  1100. description: Not found.
  1101. content:
  1102. application/json:
  1103. schema:
  1104. $ref: '#/components/schemas/Error404'
  1105. '500':
  1106. description: Internal server error.
  1107. content:
  1108. application/json:
  1109. schema:
  1110. $ref: '#/components/schemas/Error500'
  1111. '/coordinators':
  1112. get:
  1113. tags:
  1114. - Hermez status
  1115. summary: Get information about coordinators.
  1116. description: Get information about coordinators.
  1117. operationId: getCoordinators
  1118. parameters:
  1119. - name: fromItem
  1120. in: query
  1121. required: false
  1122. description: Indicates the desired first item (using the itemId property) to be included in the response.
  1123. schema:
  1124. type: number
  1125. - name: order
  1126. in: query
  1127. required: false
  1128. description: Order of the returned items. Coordinators will be ordered by increasing (ethereumBlock, forgerAddr).
  1129. schema:
  1130. type: string
  1131. default: ASC
  1132. enum:
  1133. - ASC
  1134. - DESC
  1135. - name: limit
  1136. in: query
  1137. required: false
  1138. description: Maximum number of items to be returned.
  1139. schema:
  1140. type: integer
  1141. minimum: 1
  1142. maximum: 2049
  1143. responses:
  1144. '200':
  1145. description: Successful operation.
  1146. content:
  1147. application/json:
  1148. schema:
  1149. $ref: '#/components/schemas/Coordinators'
  1150. '400':
  1151. description: Bad request.
  1152. content:
  1153. application/json:
  1154. schema:
  1155. $ref: '#/components/schemas/Error400'
  1156. '500':
  1157. description: Internal server error.
  1158. content:
  1159. application/json:
  1160. schema:
  1161. $ref: '#/components/schemas/Error500'
  1162. '/coordinators/{bidderAddr}':
  1163. get:
  1164. tags:
  1165. - Hermez status
  1166. summary: Get the information of a coordinator.
  1167. description: Get the information of a coordinator.
  1168. operationId: getCoordinator
  1169. parameters:
  1170. - name: bidderAddr
  1171. in: path
  1172. description: Coordinator identifier
  1173. required: true
  1174. schema:
  1175. $ref: '#/components/schemas/EthereumAddress'
  1176. responses:
  1177. '200':
  1178. description: Successful operation.
  1179. content:
  1180. application/json:
  1181. schema:
  1182. $ref: '#/components/schemas/Coordinator'
  1183. '400':
  1184. description: Bad request.
  1185. content:
  1186. application/json:
  1187. schema:
  1188. $ref: '#/components/schemas/Error400'
  1189. '404':
  1190. description: Not found.
  1191. content:
  1192. application/json:
  1193. schema:
  1194. $ref: '#/components/schemas/Error404'
  1195. '500':
  1196. description: Internal server error.
  1197. content:
  1198. application/json:
  1199. schema:
  1200. $ref: '#/components/schemas/Error500'
  1201. components:
  1202. schemas:
  1203. ItemId:
  1204. type: integer
  1205. description: Position of the item in the DB. This is useful for pagination, but has nothing to do with the protocol.
  1206. PostPoolL2Transaction:
  1207. type: object
  1208. description: L2 transaction to be posted.
  1209. properties:
  1210. id:
  1211. $ref: '#/components/schemas/TransactionId'
  1212. type:
  1213. $ref: '#/components/schemas/TransactionTypeL2'
  1214. tokenId:
  1215. $ref: '#/components/schemas/TokenId'
  1216. fromAccountIndex:
  1217. $ref: '#/components/schemas/AccountIndex'
  1218. toAccountIndex:
  1219. type: string
  1220. description: >-
  1221. Identifier of the destination account. It references the position where the account is inside the state Merkle tree.
  1222. The identifier is built using: `hez:` + `token symbol:` + `index`. If this is provided, toHezEthereumAddress and toBjj
  1223. must be null. To perform an exit the value hez:EXIT:1 must be used.
  1224. example: null
  1225. nullable: true
  1226. toHezEthereumAddress:
  1227. type: string
  1228. description: "Address of an Etherum account linked to the Hermez network. If this is provided, toAccountIndex and toBjj must be null."
  1229. pattern: "^hez:0x[a-fA-F0-9]{40}$"
  1230. example: "hez:0xaa942cfcd25ad4d90a62358b0dd84f33b398262a"
  1231. nullable: true
  1232. toBjj:
  1233. type: string
  1234. description: >-
  1235. 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.
  1236. If this is prvided, toAccountIndex must be null and toHezEthereumAddress must be hez:0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF.
  1237. pattern: "^hez:[A-Za-z0-9_-]{44}$"
  1238. example: null
  1239. nullable: true
  1240. amount:
  1241. allOf:
  1242. - $ref: '#/components/schemas/BigInt'
  1243. - description: Amount of tokens to be sent.
  1244. example: "6300000000000000000"
  1245. fee:
  1246. $ref: '#/components/schemas/FeeSelector'
  1247. nonce:
  1248. $ref: '#/components/schemas/Nonce'
  1249. signature:
  1250. allOf:
  1251. - $ref: '#/components/schemas/BJJSignature'
  1252. - description: Signature of the transaction. More info [here](https://idocs.hermez.io/#/spec/zkrollup/README?id=l2a-idl2).
  1253. - example: "72024a43f546b0e1d9d5d7c4c30c259102a9726363adcc4ec7b6aea686bcb5116f485c5542d27c4092ae0ceaf38e3bb44417639bd2070a58ba1aa1aab9d92c03"
  1254. requestFromAccountIndex:
  1255. type: string
  1256. description: References the `fromAccountIndex` of the requested transaction.
  1257. example: null
  1258. nullable: true
  1259. requestToAccountIndex:
  1260. type: string
  1261. description: References the `toAccountIndex` of the requested transaction.
  1262. example: null
  1263. nullable: true
  1264. requestToHezEthereumAddress:
  1265. type: string
  1266. description: References the `toHezEthereumAddress` of the requested transaction.
  1267. pattern: "^hez:0x[a-fA-F0-9]{40}$"
  1268. example: null
  1269. nullable: true
  1270. requestToBjj:
  1271. type: string
  1272. description: References the `toBjj` of the requested transaction.
  1273. pattern: "^hez:[A-Za-z0-9_-]{44}$"
  1274. example: null
  1275. nullable: true
  1276. requestTokenId:
  1277. type: integer
  1278. description: References the `tokenId` of the requested transaction.
  1279. example: null
  1280. nullable: true
  1281. requestAmount:
  1282. type: string
  1283. description: References the `amount` of the requested transaction.
  1284. example: null
  1285. nullable: true
  1286. requestFee:
  1287. type: integer
  1288. description: References the `fee` of the requested transaction.
  1289. example: null
  1290. nullable: true
  1291. requestNonce:
  1292. type: integer
  1293. description: References the `nonce` of the requested transaction.
  1294. example: null
  1295. nullable: true
  1296. required:
  1297. - id
  1298. - type
  1299. - tokenId
  1300. - fromAccountIndex
  1301. - amount
  1302. - fee
  1303. - nonce
  1304. - signature
  1305. PoolL2Transaction:
  1306. type: object
  1307. properties:
  1308. id:
  1309. $ref: '#/components/schemas/TransactionId'
  1310. type:
  1311. $ref: '#/components/schemas/TransactionTypeL2'
  1312. fromAccountIndex:
  1313. $ref: '#/components/schemas/AccountIndex'
  1314. fromHezEthereumAddress:
  1315. type: string
  1316. description: "Address of an Etherum account linked to the Hermez network."
  1317. pattern: "^hez:0x[a-fA-F0-9]{40}$"
  1318. example: "hez:0xaa942cfcd25ad4d90a62358b0dd84f33b398262a"
  1319. nullable: true
  1320. fromBJJ:
  1321. type: string
  1322. 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."
  1323. pattern: "^hez:[A-Za-z0-9_-]{44}$"
  1324. example: "hez:9CK9fjQdMUTGm8KDvGLy3MB-vnP0NCcGX7Uh7OO6KRJm"
  1325. nullable: true
  1326. toAccountIndex:
  1327. type: string
  1328. description: >-
  1329. Identifier of the destination account. It references the position where the account is inside the state Merkle tree.
  1330. The identifier is built using: `hez:` + `token symbol:` + `index`
  1331. example: "hez:DAI:309"
  1332. nullable: true
  1333. toHezEthereumAddress:
  1334. type: string
  1335. description: "Address of an Etherum account linked to the Hermez network."
  1336. pattern: "^hez:0x[a-fA-F0-9]{40}$"
  1337. example: null
  1338. nullable: true
  1339. toBjj:
  1340. type: string
  1341. 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."
  1342. pattern: "^hez:[A-Za-z0-9_-]{44}$"
  1343. example: null
  1344. nullable: true
  1345. amount:
  1346. allOf:
  1347. - $ref: '#/components/schemas/BigInt'
  1348. - description: Amount of tokens to be sent.
  1349. example: "6303020000000000000"
  1350. fee:
  1351. $ref: '#/components/schemas/FeeSelector'
  1352. nonce:
  1353. $ref: '#/components/schemas/Nonce'
  1354. state:
  1355. $ref: '#/components/schemas/PoolL2TransactionState'
  1356. signature:
  1357. allOf:
  1358. - $ref: '#/components/schemas/BJJSignature'
  1359. - description: Signature of the transaction. More info [here](https://idocs.hermez.io/#/spec/zkrollup/README?id=l2a-idl2).
  1360. - example: "72024a43f546b0e1d9d5d7c4c30c259102a9726363adcc4ec7b6aea686bcb5116f485c5542d27c4092ae0ceaf38e3bb44417639bd2070a58ba1aa1aab9d92c03"
  1361. timestamp:
  1362. type: string
  1363. description: Moment in which the transaction was added to the pool.
  1364. format: date-time
  1365. batchNum:
  1366. type: integer
  1367. description: Identifier of a batch. Every new forged batch increments by one the batchNum, starting at 0.
  1368. minimum: 0
  1369. maximum: 4294967295
  1370. nullable: true
  1371. example: null
  1372. requestFromAccountIndex:
  1373. type: string
  1374. description: >-
  1375. Identifier of an account. It references the position where the account is inside the state Merkle tree.
  1376. The identifier is built using: `hez:` + `token symbol:` + `index`
  1377. nullable: true
  1378. example: null
  1379. requestToAccountIndex:
  1380. type: string
  1381. description: >-
  1382. Identifier of an account. It references the position where the account is inside the state Merkle tree.
  1383. The identifier is built using: `hez:` + `token symbol:` + `index`
  1384. nullable: true
  1385. example: null
  1386. requestToHezEthereumAddress:
  1387. type: string
  1388. description: "Address of an Etherum account linked to the Hermez network."
  1389. pattern: "^hez:0x[a-fA-F0-9]{40}$"
  1390. nullable: true
  1391. example: null
  1392. requestToBJJ:
  1393. type: string
  1394. 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."
  1395. pattern: "^hez:[A-Za-z0-9_-]{44}$"
  1396. nullable: true
  1397. example: null
  1398. requestTokenId:
  1399. type: integer
  1400. description: References the `tokenId` of the requested transaction.
  1401. example: null
  1402. nullable: true
  1403. requestAmount:
  1404. type: string
  1405. description: BigInt is an integer encoded as a string for numbers that are very large.
  1406. nullable: true
  1407. example: null
  1408. requestFee:
  1409. type: integer
  1410. description: Index of the fee type to select, more info [here](https://idocs.hermez.io/#/spec/zkrollup/fee-table?id=transaction-fee-table).
  1411. minimum: 0
  1412. maximum: 256
  1413. nullable: true
  1414. example: null
  1415. requestNonce:
  1416. type: integer
  1417. description: Number that can only be used once per account. Increments by one with each transaction.
  1418. minimum: 0
  1419. maximum: 1.84467440737096e+19
  1420. nullable: true
  1421. example: null
  1422. token:
  1423. $ref: '#/components/schemas/Token'
  1424. required:
  1425. - id
  1426. - type
  1427. - fromAccountIndex
  1428. - fromHezEthereumAddress
  1429. - fromBJJ
  1430. - toAccountIndex
  1431. - toHezEthereumAddress
  1432. - toBjj
  1433. - amount
  1434. - fee
  1435. - nonce
  1436. - state
  1437. - signature
  1438. - timestamp
  1439. - batchNum
  1440. - requestFromAccountIndex
  1441. - requestToAccountIndex
  1442. - requestToHezEthereumAddress
  1443. - requestToBJJ
  1444. - requestTokenId
  1445. - requestAmount
  1446. - requestFee
  1447. - requestNonce
  1448. - token
  1449. TransactionId:
  1450. type: string
  1451. 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)
  1452. example: "0x00000000000001e240004700"
  1453. EthereumAddress:
  1454. type: string
  1455. description: "Address of an Etherum account."
  1456. pattern: "^0x[a-fA-F0-9]{40}$"
  1457. example: "0xaa942cfcd25ad4d90a62358b0dd84f33b398262a"
  1458. HezEthereumAddress:
  1459. type: string
  1460. description: "Address of an Etherum account linked to the Hermez network."
  1461. pattern: "^hez:0x[a-fA-F0-9]{40}$"
  1462. example: "hez:0xaa942cfcd25ad4d90a62358b0dd84f33b398262a"
  1463. BJJ:
  1464. type: string
  1465. 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."
  1466. pattern: "^hez:[A-Za-z0-9_-]{44}$"
  1467. example: "hez:rR7LXKal-av7I56Y0dEBCVmwc9zpoLY5ERhy5w7G-xwe"
  1468. AccountIndex:
  1469. type: string
  1470. description: >-
  1471. Identifier of an account. It references the position where the account is inside the state Merkle tree.
  1472. The identifier is built using: `hez:` + `token symbol:` + `index`
  1473. example: "hez:DAI:4444"
  1474. TransactionType:
  1475. type: string
  1476. description: Type of transaction.
  1477. enum:
  1478. - Exit
  1479. - Transfer
  1480. - Deposit
  1481. - CreateAccountDeposit
  1482. - CreateAccountDepositTransfer
  1483. - DepositTransfer
  1484. - ForceTransfer
  1485. - ForceExit
  1486. - TransferToEthAddr
  1487. - TransferToBJJ
  1488. TransactionTypeL2:
  1489. type: string
  1490. description: Type of transaction.
  1491. enum:
  1492. - Exit
  1493. - Transfer
  1494. - TransferToEthAddr
  1495. - TransferToBJJ
  1496. TokenId:
  1497. type: integer
  1498. description: Identifier of a token registered in the network.
  1499. minimum: 0
  1500. maximum: 4294967295
  1501. example: 98765
  1502. BigInt:
  1503. type: string
  1504. description: BigInt is an integer encoded as a string for numbers that are very large.
  1505. example: "8708856933496328593"
  1506. pattern: "^\\d+$"
  1507. FeeSelector:
  1508. type: integer
  1509. description: Index of the fee type to select, more info [here](https://idocs.hermez.io/#/spec/zkrollup/fee-table?id=transaction-fee-table).
  1510. minimum: 0
  1511. maximum: 256
  1512. example: 36
  1513. Nonce:
  1514. type: integer
  1515. description: Number that can only be used once per account, increments by one at each transaction.
  1516. minimum: 0
  1517. maximum: 1.84467440737096e+19
  1518. example: 121
  1519. PoolL2TransactionState:
  1520. type: string
  1521. description: >
  1522. State of a L2 transaction from the coordinator pool.
  1523. * pend: Pending
  1524. * fing: Forging
  1525. * fged: Forged
  1526. * invl: Invalid
  1527. enum:
  1528. - pend
  1529. - fing
  1530. - fged
  1531. - invl
  1532. ETHSignature:
  1533. type: string
  1534. description: Ethereum signature.
  1535. pattern: "^0x[a-fA-F0-9]{130}$"
  1536. example: "0xf9161cd688394772d93aa3e7b3f8f9553ca4f94f65b7cece93ed4a239d5c0b4677dca6d1d459e3a5c271a34de735d4664a43e5a8960a9a6e027d12c562dd448e1c"
  1537. BJJSignature:
  1538. type: string
  1539. description: BabyJubJub compressed signature.
  1540. pattern: "^[a-fA-F0-9]{128}$"
  1541. example: "72024a43f546b0e1d9d5d7c4c30c259102a9726363adcc4ec7b6aea686bcb5116f485c5542d27c4092ae0ceaf38e3bb44417639bd2070a58ba1aa1aab9d92c03"
  1542. BatchNum:
  1543. type: integer
  1544. description: Identifier of a batch. Every new forged batch increments by one the batchNum, starting at 0.
  1545. minimum: 0
  1546. maximum: 4294967295
  1547. example: 5432
  1548. AccountCreationAuthorizationPost:
  1549. type: object
  1550. properties:
  1551. hezEthereumAddress:
  1552. $ref: '#/components/schemas/HezEthereumAddress'
  1553. bjj:
  1554. $ref: '#/components/schemas/BJJ'
  1555. signature:
  1556. $ref: '#/components/schemas/ETHSignature'
  1557. required:
  1558. - hezEthereumAddress
  1559. - bjj
  1560. - signature
  1561. AccountCreationAuthorization:
  1562. type: object
  1563. properties:
  1564. timestamp:
  1565. type: string
  1566. format: date-time
  1567. hezEthereumAddress:
  1568. $ref: '#/components/schemas/HezEthereumAddress'
  1569. bjj:
  1570. $ref: '#/components/schemas/BJJ'
  1571. signature:
  1572. $ref: '#/components/schemas/ETHSignature'
  1573. required:
  1574. - timestamp
  1575. - hezEthereumAddress
  1576. - bjj
  1577. - signature
  1578. HistoryTransaction:
  1579. type: object
  1580. description: Transaction of the Hermez network
  1581. properties:
  1582. L1orL2:
  1583. type: string
  1584. enum:
  1585. - L1
  1586. - L2
  1587. id:
  1588. $ref: '#/components/schemas/TransactionId'
  1589. itemId:
  1590. $ref: '#/components/schemas/ItemId'
  1591. type:
  1592. $ref: '#/components/schemas/TransactionType'
  1593. position:
  1594. $ref: '#/components/schemas/TransactionPosition'
  1595. fromAccountIndex:
  1596. type: string
  1597. description: >-
  1598. Identifier of an account. It references the position where the account is inside the state Merkle tree.
  1599. The identifier is built using: `hez:` + `token symbol:` + `index`
  1600. example: "hez:DAI:4444"
  1601. nullable: true
  1602. fromHezEthereumAddress:
  1603. type: string
  1604. description: "Address of an Etherum account linked to the Hermez network."
  1605. pattern: "^hez:0x[a-fA-F0-9]{40}$"
  1606. example: "hez:0xaa942cfcd25ad4d90a62358b0dd84f33b398262a"
  1607. nullable: true
  1608. fromBJJ:
  1609. type: string
  1610. 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."
  1611. pattern: "^hez:[A-Za-z0-9_-]{44}$"
  1612. example: "hez:9CK9fjQdMUTGm8KDvGLy3MB-vnP0NCcGX7Uh7OO6KRJm"
  1613. nullable: true
  1614. toAccountIndex:
  1615. allOf:
  1616. - $ref: '#/components/schemas/AccountIndex'
  1617. - example: "hez:DAI:672"
  1618. toHezEthereumAddress:
  1619. type: string
  1620. description: "Address of an Etherum account linked to the Hermez network."
  1621. pattern: "^hez:0x[a-fA-F0-9]{40}$"
  1622. example: "hez:0xaa942cfcd25ad4d90a62358b0dd84f33b398262a"
  1623. nullable: true
  1624. toBJJ:
  1625. type: string
  1626. 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."
  1627. pattern: "^hez:[A-Za-z0-9_-]{44}$"
  1628. example: "hez:f1J78_6uqTyjX6jrVCqN4RFeRBnWQAGl477ZFtOnH6Sm"
  1629. nullable: true
  1630. amount:
  1631. allOf:
  1632. - $ref: '#/components/schemas/BigInt'
  1633. - description: Amount of tokens to be sent.
  1634. - example: "4903020000000000000"
  1635. batchNum:
  1636. type: integer
  1637. description: Batch in which the transaction was forged. Null indicates not forged yet.
  1638. minimum: 0
  1639. maximum: 4294967295
  1640. example: 5432
  1641. nullable: true
  1642. historicUSD:
  1643. type: number
  1644. description: Value in USD at the moment the transaction was forged.
  1645. example: 49.7
  1646. nullable: true
  1647. timestamp:
  1648. type: string
  1649. format: date-time
  1650. 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.
  1651. token:
  1652. $ref: '#/components/schemas/Token'
  1653. L1Info:
  1654. type: object
  1655. description: Additional information that only applies to L1 transactions.
  1656. nullable: true
  1657. properties:
  1658. toForgeL1TransactionsNum:
  1659. $ref: '#/components/schemas/ToForgeL1TransactionsNum'
  1660. userOrigin:
  1661. type: boolean
  1662. description: True if the transaction was sent by a user. False if it was sent by a coordinator.
  1663. loadAmount:
  1664. allOf:
  1665. - $ref: '#/components/schemas/BigInt'
  1666. - description: Tokens transfered from L1 to L2.
  1667. - example: "4900000000000000000"
  1668. historicLoadAmountUSD:
  1669. type: number
  1670. description: Load amount in USD, at the moment the transaction was made.
  1671. example: 3.897
  1672. nullable: true
  1673. ethereumBlockNum:
  1674. allOf:
  1675. - $ref: '#/components/schemas/EthBlockNum'
  1676. - description: Ethereum block in which the transaction was added to the smart contract forge queue.
  1677. - example: 258723049
  1678. required:
  1679. - toForgeL1TransactionsNum
  1680. - userOrigin
  1681. - loadAmount
  1682. - historicLoadAmountUSD
  1683. - ethereumBlockNum
  1684. additionalProperties: false
  1685. L2Info:
  1686. type: object
  1687. description: Additional information that only applies to L2 transactions.
  1688. nullable: true
  1689. properties:
  1690. fee:
  1691. $ref: '#/components/schemas/FeeSelector'
  1692. historicFeeUSD:
  1693. type: number
  1694. description: Fee in USD, at the moment the transaction was forged.
  1695. example: 263.89
  1696. nullable: true
  1697. nonce:
  1698. $ref: '#/components/schemas/Nonce'
  1699. example: null
  1700. required:
  1701. - fee
  1702. - historicFeeUSD
  1703. - nonce
  1704. additionalProperties: false
  1705. required:
  1706. - L1orL2
  1707. - id
  1708. - itemId
  1709. - type
  1710. - position
  1711. - fromAccountIndex
  1712. - fromHezEthereumAddress
  1713. - fromBJJ
  1714. - toAccountIndex
  1715. - toHezEthereumAddress
  1716. - toBJJ
  1717. - amount
  1718. - batchNum
  1719. - historicUSD
  1720. - timestamp
  1721. - token
  1722. - L1Info
  1723. - L2Info
  1724. additionalProperties: false
  1725. HistoryTransactions:
  1726. type: object
  1727. properties:
  1728. transactions:
  1729. type: array
  1730. description: List of history transactions.
  1731. items:
  1732. $ref: '#/components/schemas/HistoryTransaction'
  1733. pagination:
  1734. $ref: '#/components/schemas/PaginationInfo'
  1735. required:
  1736. - transactions
  1737. - pagination
  1738. additionalProperties: false
  1739. EthBlockNum:
  1740. type: integer
  1741. description: Ethereum block number
  1742. minimum: 0
  1743. maximum: 1.84467440737096e+19
  1744. example: 762375478
  1745. ToForgeL1TransactionsNum:
  1746. type: integer
  1747. description: Reference to know in which batch a L1 transaction was forged / will be forged.
  1748. minimum: 0
  1749. maximum: 4294967295
  1750. example: 784
  1751. nullable: true
  1752. TransactionPosition:
  1753. type: integer
  1754. description: Position that a transaction occupies in a batch.
  1755. minimum: 0
  1756. example: 5
  1757. URL:
  1758. type: string
  1759. description: HTTP URL
  1760. example: "https://hermez.io"
  1761. TokenSymbol:
  1762. type: string
  1763. description: Abreviation of the token name.
  1764. example: "DAI"
  1765. TokenName:
  1766. type: string
  1767. description: Token name.
  1768. example: "Dai"
  1769. CollectedFees:
  1770. type: object
  1771. 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.
  1772. additionalProperties:
  1773. type: string
  1774. example:
  1775. 1234: "425632785672345647"
  1776. 4321: "86538967235465432654352"
  1777. Batch:
  1778. type: object
  1779. description: Group of transactions forged in a coordinator and sent and validated in Ethereum.
  1780. properties:
  1781. itemId:
  1782. $ref: '#/components/schemas/ItemId'
  1783. batchNum:
  1784. $ref: '#/components/schemas/BatchNum'
  1785. ethereumBlockNum:
  1786. $ref: '#/components/schemas/EthBlockNum'
  1787. ethereumBlockHash:
  1788. type: string
  1789. description: hash of the Ethereum block in which the batch was forged
  1790. example: "0xfe88c94d860f01a17f961bf4bdfb6e0c6cd10d3fda5cc861e805ca1240c58553"
  1791. timestamp:
  1792. type: string
  1793. format: date-time
  1794. description: Time in which the batch was forged.
  1795. forgerAddr:
  1796. $ref: '#/components/schemas/EthereumAddress'
  1797. collectedFees:
  1798. $ref: '#/components/schemas/CollectedFees'
  1799. historicTotalCollectedFeesUSD:
  1800. type: number
  1801. description: Sum of the all the fees collected, in USD, at the moment the batch was forged.
  1802. example: 23.3
  1803. stateRoot:
  1804. allOf:
  1805. - $ref: '#/components/schemas/Hash'
  1806. - description: Root of the accounts Merkle Tree.
  1807. - example: "2734657026572a8708d883"
  1808. numAccounts:
  1809. type: integer
  1810. description: Number of registered accounts in this batch.
  1811. exitRoot:
  1812. allOf:
  1813. - $ref: '#/components/schemas/Hash'
  1814. - description: Root of the exit Merkle Tree associated to this batch.
  1815. - example: "2734657026572a8708d883"
  1816. forgeL1TransactionsNum:
  1817. type: integer
  1818. description: Identifier that corresponds to the group of L1 transactions forged in the current batch.
  1819. example: 5
  1820. nullable: true
  1821. slotNum:
  1822. $ref: '#/components/schemas/SlotNum'
  1823. additionalProperties: false
  1824. required:
  1825. - itemId
  1826. - batchNum
  1827. - ethereumBlockNum
  1828. - ethereumBlockHash
  1829. - timestamp
  1830. - forgerAddr
  1831. - collectedFees
  1832. - historicTotalCollectedFeesUSD
  1833. - stateRoot
  1834. - numAccounts
  1835. - exitRoot
  1836. - forgeL1TransactionsNum
  1837. - slotNum
  1838. FullBatch:
  1839. type: object
  1840. description: Group of transactions forged in a coordinator and sent and validated in Ethereum.
  1841. properties:
  1842. batch:
  1843. $ref: '#/components/schemas/Batch'
  1844. transactions:
  1845. type: array
  1846. description: List of forged transactions in the batch
  1847. items:
  1848. $ref: '#/components/schemas/HistoryTransaction'
  1849. additionalProperties: false
  1850. required:
  1851. - batch
  1852. - transactions
  1853. Hash:
  1854. type: string
  1855. description: hashed data
  1856. example: "2734657026572a8708d883"
  1857. SlotNum:
  1858. type: integer
  1859. description: Identifier of a slot.
  1860. minimum: 0
  1861. maximum: 4294967295
  1862. example: 784
  1863. Batches:
  1864. type: object
  1865. properties:
  1866. batches:
  1867. type: array
  1868. description: List of batches.
  1869. items:
  1870. $ref: '#/components/schemas/Batch'
  1871. pagination:
  1872. $ref: '#/components/schemas/PaginationInfo'
  1873. additionalProperties: false
  1874. required:
  1875. - batches
  1876. - pagination
  1877. Coordinator:
  1878. type: object
  1879. properties:
  1880. itemId:
  1881. $ref: '#/components/schemas/ItemId'
  1882. forgerAddr:
  1883. $ref: '#/components/schemas/EthereumAddress'
  1884. bidderAddr:
  1885. $ref: '#/components/schemas/EthereumAddress'
  1886. URL:
  1887. $ref: '#/components/schemas/URL'
  1888. ethereumBlock:
  1889. allOf:
  1890. - $ref: '#/components/schemas/EthBlockNum'
  1891. - description: Ethereum block in which the coordinator registered into the network.
  1892. - example: 5735943738
  1893. additionalProperties: false
  1894. required:
  1895. - itemId
  1896. - forgerAddr
  1897. - bidderAddr
  1898. - URL
  1899. - ethereumBlock
  1900. Coordinators:
  1901. type: object
  1902. properties:
  1903. coordinators:
  1904. type: array
  1905. description: List of coordinators.
  1906. items:
  1907. $ref: '#/components/schemas/Coordinator'
  1908. pagination:
  1909. $ref: '#/components/schemas/PaginationInfo'
  1910. additionalProperties: false
  1911. required:
  1912. - coordinators
  1913. - pagination
  1914. Bid:
  1915. type: object
  1916. description: Tokens placed in an auction by a coordinator to gain the right to forge batches during a specific slot.
  1917. properties:
  1918. itemId:
  1919. $ref: '#/components/schemas/ItemId'
  1920. bidderAddr:
  1921. $ref: '#/components/schemas/EthereumAddress'
  1922. forgerAddr:
  1923. $ref: '#/components/schemas/EthereumAddress'
  1924. slotNum:
  1925. $ref: '#/components/schemas/SlotNum'
  1926. URL:
  1927. $ref: '#/components/schemas/URL'
  1928. bidValue:
  1929. $ref: '#/components/schemas/BigInt'
  1930. ethereumBlockNum:
  1931. $ref: '#/components/schemas/EthBlockNum'
  1932. timestamp:
  1933. type: string
  1934. format: date-time
  1935. additionalProperties: false
  1936. require:
  1937. - bidderAddr
  1938. - forgerAddr
  1939. - slotNum
  1940. - URL
  1941. - bidValue
  1942. - ethereumBlockNum
  1943. - timestamp
  1944. Bids:
  1945. type: object
  1946. properties:
  1947. bids:
  1948. type: array
  1949. description: List of bids.
  1950. items:
  1951. $ref: '#/components/schemas/Bid'
  1952. pagination:
  1953. $ref: '#/components/schemas/PaginationInfo'
  1954. additionalProperties: false
  1955. require:
  1956. - bids
  1957. - pagination
  1958. RecommendedFee:
  1959. type: object
  1960. description: Fee that the coordinator recommends per transaction in USD.
  1961. properties:
  1962. existingAccount:
  1963. type: number
  1964. description: Recommended fee if the destination account of the transaction already exists.
  1965. minimum: 0
  1966. example: 0.1
  1967. createAccount:
  1968. type: number
  1969. 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.
  1970. minimum: 0
  1971. example: 1.3
  1972. createAccountInternal:
  1973. type: number
  1974. 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.
  1975. minimum: 0
  1976. example: 0.5
  1977. Token:
  1978. type: object
  1979. description: Hermez network compatible and registered token.
  1980. properties:
  1981. id:
  1982. $ref: '#/components/schemas/TokenId'
  1983. ethereumAddress:
  1984. allOf:
  1985. - $ref: '#/components/schemas/EthereumAddress'
  1986. - description: Ethereum address in which the token is deployed.
  1987. - example: "0xaa942cfcd25ad4d90a62358b0dd84f33b398262a"
  1988. itemId:
  1989. $ref: '#/components/schemas/ItemId'
  1990. name:
  1991. type: string
  1992. description: full name of the token
  1993. example: Maker Dai
  1994. symbol:
  1995. allOf:
  1996. - $ref: '#/components/schemas/TokenSymbol'
  1997. - example: DAI
  1998. decimals:
  1999. type: integer
  2000. description: Number of decimals of the token.
  2001. example: 18
  2002. ethereumBlockNum:
  2003. allOf:
  2004. - $ref: '#/components/schemas/EthBlockNum'
  2005. - description: Ethereum block number in which the token was added to the Hermez network.
  2006. - example: 539847538
  2007. USD:
  2008. type: number
  2009. description: Value of the token in USD.
  2010. example: 1.01
  2011. nullable: true
  2012. fiatUpdate:
  2013. type: string
  2014. format: date-time
  2015. description: Timestamp of the moment the `USD` value was updated.
  2016. nullable: true
  2017. required:
  2018. - id
  2019. - ethereumAddress
  2020. - itemId
  2021. - name
  2022. - symbol
  2023. - decimals
  2024. - ethereumBlockNum
  2025. - USD
  2026. - fiatUpdate
  2027. additionalProperties: false
  2028. Tokens:
  2029. type: object
  2030. properties:
  2031. tokens:
  2032. type: array
  2033. description: List of tokens.
  2034. items:
  2035. $ref: '#/components/schemas/Token'
  2036. pagination:
  2037. $ref: '#/components/schemas/PaginationInfo'
  2038. Exit:
  2039. type: object
  2040. description: Exit tree leaf. It Contains the necessary information to perform a withdrawal.
  2041. properties:
  2042. batchNum:
  2043. allOf:
  2044. - $ref: '#/components/schemas/BatchNum'
  2045. - description: Batch in which the exit was forged.
  2046. - example: 7394
  2047. accountIndex:
  2048. $ref: '#/components/schemas/AccountIndex'
  2049. itemId:
  2050. $ref: '#/components/schemas/ItemId'
  2051. merkleProof:
  2052. type: object
  2053. description: Existence proof of a leaf in a given Merkle Root. Encoded as hexadecimal string.
  2054. properties:
  2055. Root:
  2056. $ref: '#/components/schemas/BigInt'
  2057. Siblings:
  2058. type: array
  2059. items:
  2060. $ref: '#/components/schemas/BigInt'
  2061. OldKey:
  2062. $ref: '#/components/schemas/BigInt'
  2063. OldValue:
  2064. $ref: '#/components/schemas/BigInt'
  2065. IsOld0:
  2066. type: boolean
  2067. Key:
  2068. $ref: '#/components/schemas/BigInt'
  2069. Value:
  2070. $ref: '#/components/schemas/BigInt'
  2071. Fnc:
  2072. type: integer
  2073. maximum: 3
  2074. minimum: 0
  2075. required:
  2076. - Root
  2077. - Siblings
  2078. - OldKey
  2079. - OldValue
  2080. - IsOld0
  2081. - Key
  2082. - Value
  2083. - Fnc
  2084. additionalProperties: false
  2085. balance:
  2086. $ref: '#/components/schemas/BigInt'
  2087. instantWithdrawn:
  2088. type: integer
  2089. description: Block in which the exit balance was instantly withdrawn. Null indicates that an instant withdrawn hasn't been performed.
  2090. minimum: 0
  2091. maximum: 1.84467440737096e+19
  2092. example: 74747363
  2093. nullable: true
  2094. delayedWithdrawRequest:
  2095. type: integer
  2096. description: Block in which the exit balance was requested to delay withdraw. Null indicates that a delay withdraw hasn't been performed.
  2097. minimum: 0
  2098. maximum: 1.84467440737096e+19
  2099. example: null
  2100. nullable: true
  2101. delayedWithdrawn:
  2102. type: integer
  2103. 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.
  2104. minimum: 0
  2105. maximum: 1.84467440737096e+19
  2106. example: null
  2107. nullable: true
  2108. token:
  2109. $ref: '#/components/schemas/Token'
  2110. required:
  2111. - batchNum
  2112. - accountIndex
  2113. - itemId
  2114. - merkleProof
  2115. - balance
  2116. - instantWithdrawn
  2117. - delayedWithdrawRequest
  2118. - delayedWithdrawn
  2119. - token
  2120. additionalProperties: false
  2121. Exits:
  2122. type: object
  2123. properties:
  2124. exits:
  2125. type: array
  2126. description: List of exits.
  2127. items:
  2128. $ref: '#/components/schemas/Exit'
  2129. pagination:
  2130. $ref: '#/components/schemas/PaginationInfo'
  2131. required:
  2132. - exits
  2133. - pagination
  2134. additionalProperties: false
  2135. Account:
  2136. type: object
  2137. description: State tree leaf. It contains balance and nonce of an account.
  2138. properties:
  2139. accountIndex:
  2140. $ref: '#/components/schemas/AccountIndex'
  2141. nonce:
  2142. $ref: '#/components/schemas/Nonce'
  2143. balance:
  2144. $ref: '#/components/schemas/BigInt'
  2145. bjj:
  2146. $ref: '#/components/schemas/BJJ'
  2147. hezEthereumAddress:
  2148. $ref: '#/components/schemas/HezEthereumAddress'
  2149. token:
  2150. $ref: '#/components/schemas/Token'
  2151. Accounts:
  2152. type: object
  2153. properties:
  2154. accounts:
  2155. type: array
  2156. description: List of accounts.
  2157. items:
  2158. $ref: '#/components/schemas/Account'
  2159. pagination:
  2160. $ref: '#/components/schemas/PaginationInfo'
  2161. Slot:
  2162. type: object
  2163. description: Slot information.
  2164. properties:
  2165. slotNum:
  2166. $ref: '#/components/schemas/SlotNum'
  2167. firstBlock:
  2168. allOf:
  2169. - $ref: '#/components/schemas/EthBlockNum'
  2170. - description: Block in which the slot began or will begin
  2171. - example: 76238647846
  2172. lastBlock:
  2173. allOf:
  2174. - $ref: '#/components/schemas/EthBlockNum'
  2175. - description: Block in which the slot ended or will end
  2176. - example: 4475934
  2177. closedAuction:
  2178. type: boolean
  2179. description: Whether the auction of the slot has finished or not.
  2180. winner:
  2181. allOf:
  2182. - $ref: '#/components/schemas/Coordinator'
  2183. - description: Coordinator who won the auction. Only applicable if the auction is closed.
  2184. - nullable: true
  2185. - example: null
  2186. Slots:
  2187. type: object
  2188. properties:
  2189. nextForgers:
  2190. type: array
  2191. description: List of slots.
  2192. items:
  2193. $ref: '#/components/schemas/Slot'
  2194. pagination:
  2195. $ref: '#/components/schemas/PaginationInfo'
  2196. NextForger:
  2197. type: object
  2198. description: Coordinator information along with the scheduled forging period
  2199. properties:
  2200. coordinator:
  2201. $ref: '#/components/schemas/Coordinator'
  2202. period:
  2203. type: object
  2204. description: Time period in which the coordinator will have the ability to forge. Specified both in Ethereum blocks and timestamp
  2205. properties:
  2206. fromBlock:
  2207. $ref: '#/components/schemas/EthBlockNum'
  2208. toBlock:
  2209. $ref: '#/components/schemas/EthBlockNum'
  2210. fromTimestamp:
  2211. type: string
  2212. format: date-time
  2213. toTimestamp:
  2214. type: string
  2215. format: date-time
  2216. NextForgers:
  2217. type: object
  2218. properties:
  2219. nextForgers:
  2220. type: array
  2221. description: List of next coordinators to forge.
  2222. items:
  2223. $ref: '#/components/schemas/NextForger'
  2224. pagination:
  2225. $ref: '#/components/schemas/PaginationInfo'
  2226. State:
  2227. type: object
  2228. description: Gobal variables of the network
  2229. properties:
  2230. network:
  2231. type: object
  2232. description: Gobal statistics of the network
  2233. properties:
  2234. lastBlock:
  2235. allOf:
  2236. - $ref: '#/components/schemas/EthBlockNum'
  2237. - description: Last synchronized Etherum block.
  2238. - example: 3457437
  2239. lastBatch:
  2240. $ref: '#/components/schemas/Batch'
  2241. currentSlot:
  2242. allOf:
  2243. - $ref: '#/components/schemas/SlotNum'
  2244. - description: Slot where batches are currently being forged.
  2245. - example: 2334
  2246. nextForgers:
  2247. $ref: '#/components/schemas/NextForgers'
  2248. additionalProperties: false
  2249. require:
  2250. - lastBlock
  2251. - lastBatch
  2252. - currentSlot
  2253. - nextForgers
  2254. metrics:
  2255. type: object
  2256. description: Metrics of the network
  2257. properties:
  2258. transactionsPerBatch:
  2259. type: number
  2260. description: Average transactions per batch in the last 24 hours.
  2261. example: 2002.7
  2262. batchFrequency:
  2263. type: number
  2264. description: Average elapsed time between batches in the last 24 hours, in seconds.
  2265. example: 8.9
  2266. transactionsPerSecond:
  2267. type: number
  2268. description: Average transactions per second in the last 24 hours.
  2269. example: 302.3
  2270. totalAccounts:
  2271. type: integer
  2272. description: Number of created accounts.
  2273. example: 90473
  2274. totalBJJs:
  2275. type: integer
  2276. description: Number of different registered BJJs.
  2277. example: 23067
  2278. avgTransactionFee:
  2279. type: number
  2280. description: Average fee percentage paid for L2 transactions in the last 24 hours.
  2281. example: 1.54
  2282. additionalProperties: false
  2283. require:
  2284. - transactionsPerBatch
  2285. - batchFrequency
  2286. - transactionsPerSecond
  2287. - totalAccounts
  2288. - totalBJJs
  2289. - avgTransactionFee
  2290. rollup:
  2291. type: object
  2292. description: Rollup parameters
  2293. properties:
  2294. forgeL1L2BatchTimeout:
  2295. type: integer
  2296. description: Max ethereum blocks after the last L1-L2-batch, when exceeds the timeout only L1-L2-batch are allowed.
  2297. example: 5
  2298. feeAddToken:
  2299. type: integer
  2300. description: Fee to pay when registering tokens into the network.
  2301. example: 5698
  2302. withdrawalDelay:
  2303. type: integer
  2304. description: Withdraw delay in seconds
  2305. example: 432000
  2306. buckets:
  2307. type: array
  2308. description: List of buckets state
  2309. items:
  2310. type: object
  2311. properties:
  2312. ceilUSD:
  2313. type: integer
  2314. description: Max USD value
  2315. example: 1000
  2316. blockStamp:
  2317. type: integer
  2318. description: Last time a withdrawal was added ( or removed if the bucket was full)
  2319. example: 4475934
  2320. withdrawals:
  2321. type: integer
  2322. description: Available withdrawals of the bucket
  2323. example: 4
  2324. blockWithdrawalRate:
  2325. type: integer
  2326. description: Every `blockWithdrawalRate` blocks add 1 withdrawal
  2327. example: 8
  2328. maxWithdrawals:
  2329. type: integer
  2330. description: Max withdrawals the bucket can hold
  2331. example: 4
  2332. additionalProperties: false
  2333. require:
  2334. - ceilUSD
  2335. - blockStamp
  2336. - withdrawals
  2337. - blockWithdrawalRate
  2338. - maxWithdrawals
  2339. additionalProperties: false
  2340. require:
  2341. - forgeL1L2BatchTimeout
  2342. - feeAddToken
  2343. - withdrawalDelay
  2344. - buckets
  2345. auction:
  2346. type: object
  2347. description: Auction parameters.
  2348. properties:
  2349. bootCoordinator:
  2350. allOf:
  2351. - $ref: '#/components/schemas/EthereumAddress'
  2352. - description: Ethereum address of the boot coordinator.
  2353. - example: "0x997dc4262BCDbf85190C01c996b4C06a461d2430"
  2354. slotDeadline:
  2355. type: integer
  2356. 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.
  2357. example: 3
  2358. closedAuctionSlots:
  2359. type: integer
  2360. 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.
  2361. example: 2
  2362. openAuctionSlots:
  2363. type: integer
  2364. description: How many days in advance are auctions opened.
  2365. defaultSlotSetBid:
  2366. type: array
  2367. 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]`."
  2368. items:
  2369. type: integer
  2370. example: [32,0,68,21,55,99]
  2371. outbidding:
  2372. type: number
  2373. description: Minimum outbid over the previous one to consider it valid.
  2374. example: 3.64
  2375. donationAddress:
  2376. allOf:
  2377. - $ref: '#/components/schemas/EthereumAddress'
  2378. - description: Ethereum address where the donations will go to.
  2379. - example: "0x887dc4262BCDbf85190C01c996b4C06a461d2430"
  2380. allocationRatio:
  2381. type: array
  2382. description: Percentage in which fees will be splitted between donations, governance and burning. The sum of the tree values should be 100.
  2383. items:
  2384. type: integer
  2385. example: [80,10,10]
  2386. additionalProperties: false
  2387. require:
  2388. - bootCoordinator
  2389. - slotDeadline
  2390. - closedAuctionSlots
  2391. - openAuctionSlots
  2392. - defaultSlotSetBid
  2393. - outbidding
  2394. - donationAddress
  2395. - allocationRatio
  2396. withdrawalDelayer:
  2397. type: object
  2398. description: Withdrawal delayer parameters
  2399. properties:
  2400. hermezRollupAddress:
  2401. allOf:
  2402. - $ref: '#/components/schemas/EthereumAddress'
  2403. - description: Ethereum address of the rollup smart contract.
  2404. - example: "0x777dc4262BCDbf85190C01c996b4C06a461d2430"
  2405. hermezGovernanceDAOAddress:
  2406. allOf:
  2407. - $ref: '#/components/schemas/EthereumAddress'
  2408. - description: Ethereum address of the governance DAO.
  2409. - example: "0x667dc4262BCDbf85190C01c996b4C06a461d2430"
  2410. whiteHackGroupAddress:
  2411. allOf:
  2412. - $ref: '#/components/schemas/EthereumAddress'
  2413. - description: Ethereum Address that can claim the funds in an emergency when the maximum emergency mode time is exceeded.
  2414. - example: "0x557dc4262BCDbf85190C01c996b4C06a461d2430"
  2415. hermezKeeperAddress:
  2416. allOf:
  2417. - $ref: '#/components/schemas/EthereumAddress'
  2418. - description: Ethereum Address that can enable emergency mode and modify the delay to make a withdrawal.
  2419. - example: "0x557dc4262BCDbf85190C01c996b4C06a461d2430"
  2420. withdrawalDelay:
  2421. allOf:
  2422. - $ref: '#/components/schemas/EthBlockNum'
  2423. - description: The time that anyone needs to wait until a withdrawal of the funds is allowed, in Ethereum blocks.
  2424. - example: 539573849
  2425. emergencyModeStartingTime:
  2426. type: integer
  2427. description: Ethereum block in which the emergency mode will be activated.
  2428. example: 10
  2429. emergencyMode:
  2430. type: boolean
  2431. description: Indicates if emergency mode has been activated.
  2432. example: false
  2433. additionalProperties: false
  2434. require:
  2435. - hermezRollupAddress
  2436. - hermezGovernanceDAOAddress
  2437. - whiteHackGroupAddress
  2438. - hermezKeeperAddress
  2439. - withdrawalDelay
  2440. - emergencyModeStartingTime
  2441. - emergencyMode
  2442. recommendedFee:
  2443. $ref: '#/components/schemas/RecommendedFee'
  2444. additionalProperties: false
  2445. require:
  2446. - network
  2447. - metrics
  2448. - rollup
  2449. - auction
  2450. - withdrawalDelayer
  2451. - recomendedFee
  2452. PaginationInfo:
  2453. type: object
  2454. description: Give pagination information
  2455. properties:
  2456. totalItems:
  2457. type: integer
  2458. description: Amount of items that the endpoint can return given the filters and the current state of the database.
  2459. example: 2048
  2460. firstItem:
  2461. type: integer
  2462. description: The smallest itemId that the endpoint will return with the given filters.
  2463. example: 50
  2464. lastItem:
  2465. type: integer
  2466. description: The greatest itemId that the endpoint will return with the given filters.
  2467. example: 2130
  2468. Config:
  2469. type: object
  2470. description: Configuration parameters of the different smart contracts that power the Hermez network.
  2471. properties:
  2472. hermez:
  2473. type: object
  2474. description: Constant configuration of the Hermez smart contract.
  2475. properties:
  2476. publicConstants:
  2477. type: object
  2478. description: Public Hermez smart contract constants
  2479. properties:
  2480. tokenHEZ:
  2481. allOf:
  2482. - $ref: '#/components/schemas/EthereumAddress'
  2483. - description: Ethereum address of the HEZ token.
  2484. - example: "0x444dc4262BCDbf85190C01c996b4C06a461d2430"
  2485. absoluteMaxL1L2BatchTimeout:
  2486. type: integer
  2487. description: L1L2 Batch Timeout
  2488. example: 240
  2489. verifiers:
  2490. type: array
  2491. description: List of verifiers struct
  2492. items:
  2493. type: object
  2494. properties:
  2495. maxTx:
  2496. type: integer
  2497. description: Maximum rollup transactions in a batch
  2498. example: 512
  2499. nlevels:
  2500. type: integer
  2501. description: Number of levels of the circuit
  2502. example: 32
  2503. required:
  2504. - maxTx
  2505. - nlevels
  2506. additionalProperties: false
  2507. hermezAuctionContract:
  2508. allOf:
  2509. - $ref: '#/components/schemas/EthereumAddress'
  2510. - description: Ethereum address of the auction smart contract.
  2511. - example: "0x111dc4262BCDbf85190C01c996b4C06a461d2430"
  2512. hermezGovernanceDAOAddress:
  2513. allOf:
  2514. - $ref: '#/components/schemas/EthereumAddress'
  2515. - description: Ethereum address of the governanceDAO.
  2516. - example: "0x222dc4262BCDbf85190C01c996b4C06a461d2430"
  2517. safetyAddress:
  2518. allOf:
  2519. - $ref: '#/components/schemas/EthereumAddress'
  2520. - description: Ethereum address of the safety.
  2521. - example: "0x333dc4262BCDbf85190C01c996b4C06a461d2430"
  2522. withdrawDelayerContract:
  2523. allOf:
  2524. - $ref: '#/components/schemas/EthereumAddress'
  2525. - description: Ethereum address of the withdraw delayer contracts.
  2526. - example: "0x444dc4262BCDbf85190C01c996b4C06a461d2430"
  2527. required:
  2528. - tokenHEZ
  2529. - absoluteMaxL1L2BatchTimeout
  2530. - verifiers
  2531. - hermezAuctionContract
  2532. - hermezGovernanceDAOAddress
  2533. - safetyAddress
  2534. - withdrawDelayerContract
  2535. additionalProperties: false
  2536. maxFeeIdxCoordinator:
  2537. type: integer
  2538. description: is the maximum number of tokens the coordinator can use to collect fees.
  2539. example: 64
  2540. reservedIdx:
  2541. type: integer
  2542. description: First 256 indexes reserved, first user index will be the 256.
  2543. example: 255
  2544. exitIdx:
  2545. type: integer
  2546. description: Account index used to indicate that a transaction is an `exit` or `force exit`.
  2547. example: 1
  2548. limitLoadAmount:
  2549. type: integer
  2550. description: Maximum load amount (L1 to L2) allowed.
  2551. example: 321
  2552. limitL2TransferAmount:
  2553. type: integer
  2554. description: Maximum amount (L2 to L2) allowed.
  2555. example: 837
  2556. limitTokens:
  2557. type: integer
  2558. description: Maximum number of different tokens that can be registered in the network.
  2559. example: 4294967295
  2560. l1CoordinatorTotalBytes:
  2561. type: integer
  2562. description: Number of bytes that a L1 coordinator transaction has ([4 bytes] token + [32 bytes] babyjub + [65 bytes] compressedSignature).
  2563. example: 101
  2564. l1UserTotalBytes:
  2565. type: integer
  2566. 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).
  2567. example: 72
  2568. maxL1UserTx:
  2569. type: integer
  2570. description: Maximum L1-user transactions allowed to be queued in a batch.
  2571. example: 128
  2572. maxL1Tx:
  2573. type: integer
  2574. description: Maximum L1 transactions allowed to be queued in a batch.
  2575. example: 256
  2576. inputSHAConstantBytes:
  2577. type: integer
  2578. description: Input SHA constant bytes
  2579. example: 18542
  2580. numBuckets:
  2581. type: integer
  2582. description: Number of buckets
  2583. example: 5
  2584. maxWithdrawalDelay:
  2585. type: integer
  2586. description: Maximum delay to withdraw tokens. Time is measured in seconds.
  2587. example: 2 * 7 * 24 * 60 * 60
  2588. exchangeMultiplier:
  2589. type: integer
  2590. description: exchange multiplier
  2591. example: 1e14
  2592. required:
  2593. - publicConstants
  2594. - reservedIdx
  2595. - exitIdx
  2596. - limitLoadAmount
  2597. - limitL2TransferAmount
  2598. - limitTokens
  2599. - l1CoordinatorTotalBytes
  2600. - l1UserTotalBytes
  2601. - maxL1UserTx
  2602. - maxL1Tx
  2603. - inputSHAConstantBytes
  2604. - numBuckets
  2605. - maxWithdrawalDelay
  2606. - exchangeMultiplier
  2607. additionalProperties: false
  2608. auction:
  2609. type: object
  2610. description: Constant configuration of the auction smart contract.
  2611. properties:
  2612. blocksPerSlot:
  2613. type: integer
  2614. description: Blocks per slot.
  2615. initialMinimalBidding:
  2616. type: integer
  2617. description: Minimum bid when no one has bid yet.
  2618. genesisBlockNum:
  2619. allOf:
  2620. - $ref: '#/components/schemas/EthBlockNum'
  2621. - description: Ethereum block number in which the smart contract starts operating.
  2622. tokenHEZ:
  2623. allOf:
  2624. - $ref: '#/components/schemas/EthereumAddress'
  2625. - description: Ethereum address of the HEZ token.
  2626. - example: "0x333dc4262BCDbf85190C01c996b4C06a461d2430"
  2627. hermezRollup:
  2628. allOf:
  2629. - $ref: '#/components/schemas/EthereumAddress'
  2630. - description: Ethereum address of the rollup smart contract.
  2631. - example: "0x222dc4262BCDbf85190C01c996b4C06a461d2430"
  2632. governanceAddress:
  2633. allOf:
  2634. - $ref: '#/components/schemas/EthereumAddress'
  2635. - description: Ethereum address of the governance.
  2636. - example: "0x444dc4262BCDbf85190C01c996b4C06a461d2430"
  2637. required:
  2638. - blocksPerSlot
  2639. - initialMinimalBidding
  2640. - genesisBlockNum
  2641. - tokenHEZ
  2642. - hermezRollup
  2643. - governanceAddress
  2644. additionalProperties: false
  2645. withdrawalDelayer:
  2646. type: object
  2647. description: Constant configuration of the withdrawal delayer smart contract.
  2648. properties:
  2649. maxWithdrawalDelay:
  2650. type: integer
  2651. description: Maximum time delay in which the tokens can be locked in the contract. Time is measured in Ethereum blocks.
  2652. example: 200
  2653. maxEmergencyModeTime:
  2654. type: integer
  2655. description: Maximum amount of time in which the contract can be in emergency mode. Time is measured in Ethereum blocks.
  2656. example: 2000
  2657. hermezRollup:
  2658. allOf:
  2659. - $ref: '#/components/schemas/EthereumAddress'
  2660. - description: Ethereum address of the rollup smart contract.
  2661. - example: "0x222dc4262BCDbf85190C01c996b4C06a461d2430"
  2662. required:
  2663. - maxWithdrawalDelay
  2664. - maxEmergencyModeTime
  2665. - hermezRollup
  2666. additionalProperties: false
  2667. required:
  2668. - hermez
  2669. - auction
  2670. - withdrawalDelayer
  2671. additionalProperties: false
  2672. Error:
  2673. type: object
  2674. description: Error response.
  2675. properties:
  2676. message:
  2677. type: string
  2678. Error400:
  2679. allOf:
  2680. - $ref: '#/components/schemas/Error'
  2681. - example:
  2682. message: Invalid signature.
  2683. Error404:
  2684. allOf:
  2685. - $ref: '#/components/schemas/Error'
  2686. - example:
  2687. message: Item(s) not found.
  2688. Error500:
  2689. allOf:
  2690. - $ref: '#/components/schemas/Error'
  2691. - example:
  2692. message: Database error.