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