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.

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