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/{hezEthereumAddress}':
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: hezEthereumAddress
109 in: path
110 description: Ethereum address.
111 required: true
112 schema:
113 $ref: '#/components/schemas/HezEthereumAddress'
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: hezEthereumAddress
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/HezEthereumAddress'
153 - name: BJJ
154 in: query
155 description: Only get accounts associated to a BabyJubJub public key. Incompatible with the query `hezEthereumAddress`.
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: hezEthereumAddress
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/HezEthereumAddress'
267 - name: BJJ
268 in: query
269 description: Get exits associated to a BabyJubJub public key. Incompatible with query `hezEthereumAddress` 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 `hezEthereumAddress` 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/PostPoolL2Transaction'
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: hezEthereumAddress
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/HezEthereumAddress'
477 - name: BJJ
478 in: query
479 description: Only get transactions associated to a BabyJubJub public key. Incompatible with the queries `hezEthereumAddress` 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`, `hezEthereumAddress` 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 PostPoolL2Transaction:
1232 type: object
1233 properties:
1234 id:
1235 $ref: '#/components/schemas/TransactionId'
1236 type:
1237 $ref: '#/components/schemas/TransactionType'
1238 tokenId:
1239 $ref: '#/components/schemas/TokenId'
1240 fromAccountIndex:
1241 $ref: '#/components/schemas/AccountIndex'
1242 toAccountIndex:
1243 type: string
1244 description: >-
1245 Identifier of the destination account. It references the position where the account is inside the state Merkle tree.
1246 The identifier is built using: `hez:` + `token symbol:` + `index`
1247 example: null
1248 nullable: true
1249 toHezEthereumAddress:
1250 type: string
1251 description: "Address of an Etherum account linked to the Hermez network."
1252 pattern: "^hez:0x[a-fA-F0-9]{40}$"
1253 example: "hez:0xaa942cfcd25ad4d90a62358b0dd84f33b398262a"
1254 nullable: true
1255 toBjj:
1256 type: string
1257 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."
1258 pattern: "^hez:[A-Za-z0-9_-]{44}$"
1259 example: null
1260 nullable: true
1261 amount:
1262 allOf:
1263 - $ref: '#/components/schemas/BigInt'
1264 - description: Amount of tokens to be sent.
1265 example: "63"
1266 fee:
1267 $ref: '#/components/schemas/FeeSelector'
1268 nonce:
1269 $ref: '#/components/schemas/Nonce'
1270 signature:
1271 allOf:
1272 - $ref: '#/components/schemas/Signature'
1273 - description: Signature of the transaction. More info [here](https://idocs.hermez.io/#/spec/zkrollup/README?id=l2a-idl2).
1274 - example: "72024a43f546b0e1d9d5d7c4c30c259102a9726363adcc4ec7b6aea686bcb5116f485c5542d27c4092ae0ceaf38e3bb44417639bd2070a58ba1aa1aab9d92c03"
1275 requestFromAccountIndex:
1276 type: string
1277 description: References the `fromAccountIndex` of the requested transaction.
1278 example: null
1279 nullable: true
1280 requestToAccountIndex:
1281 type: string
1282 description: References the `toAccountIndex` of the requested transaction.
1283 example: null
1284 nullable: true
1285 requestToHezEthereumAddress:
1286 type: string
1287 description: References the `toHezEthereumAddress` of the requested transaction.
1288 pattern: "^hez:0x[a-fA-F0-9]{40}$"
1289 example: null
1290 nullable: true
1291 requestToBJJ:
1292 type: string
1293 description: References the `toBJJ` of the requested transaction.
1294 pattern: "^hez:[A-Za-z0-9_-]{44}$"
1295 example: null
1296 nullable: true
1297 requestTokenId:
1298 type: integer
1299 description: References the `tokenId` of the requested transaction.
1300 example: null
1301 nullable: true
1302 requestAmount:
1303 type: string
1304 description: References the `amount` of the requested transaction.
1305 example: null
1306 nullable: true
1307 requestFee:
1308 type: integer
1309 description: References the `fee` of the requested transaction.
1310 example: null
1311 nullable: true
1312 requestNonce:
1313 type: integer
1314 description: References the `nonce` of the requested transaction.
1315 example: null
1316 nullable: true
1317 required:
1318 - id
1319 - type
1320 - tokenId
1321 - fromAccountIndex
1322 - toAccountIndex
1323 - toHezAccountIndex
1324 - toHezEthereumAddress
1325 - toBjj
1326 - amount
1327 - fee
1328 - nonce
1329 - signature
1330 - requestFromAccountIndex
1331 - requestToAccountIndex
1332 - requestToHezEthereumAddress
1333 - requestToBJJ
1334 - requestTokenId
1335 - requestAmount
1336 - requestFee
1337 - requestNonce
1338 PoolL2Transaction:
1339 type: object
1340 properties:
1341 id:
1342 $ref: '#/components/schemas/TransactionId'
1343 type:
1344 $ref: '#/components/schemas/TransactionType'
1345 fromAccountIndex:
1346 $ref: '#/components/schemas/AccountIndex'
1347 toAccountIndex:
1348 type: string
1349 description: >-
1350 Identifier of the destination account. It references the position where the account is inside the state Merkle tree.
1351 The identifier is built using: `hez:` + `token symbol:` + `index`
1352 example: "hez:DAI:309"
1353 nullable: true
1354 toHezEthereumAddress:
1355 type: string
1356 description: "Address of an Etherum account linked to the Hermez network."
1357 pattern: "^hez:0x[a-fA-F0-9]{40}$"
1358 example: null
1359 nullable: true
1360 toBjj:
1361 type: string
1362 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."
1363 pattern: "^hez:[A-Za-z0-9_-]{44}$"
1364 example: null
1365 nullable: true
1366 amount:
1367 allOf:
1368 - $ref: '#/components/schemas/BigInt'
1369 - description: Amount of tokens to be sent.
1370 example: "63"
1371 fee:
1372 $ref: '#/components/schemas/FeeSelector'
1373 nonce:
1374 $ref: '#/components/schemas/Nonce'
1375 state:
1376 $ref: '#/components/schemas/PoolL2TransactionState'
1377 signature:
1378 allOf:
1379 - $ref: '#/components/schemas/Signature'
1380 - description: Signature of the transaction. More info [here](https://idocs.hermez.io/#/spec/zkrollup/README?id=l2a-idl2).
1381 - example: "72024a43f546b0e1d9d5d7c4c30c259102a9726363adcc4ec7b6aea686bcb5116f485c5542d27c4092ae0ceaf38e3bb44417639bd2070a58ba1aa1aab9d92c03"
1382 timestamp:
1383 type: string
1384 description: Moment in which the transaction was added to the pool.
1385 format: date-time
1386 batchNum:
1387 allOf:
1388 - $ref: '#/components/schemas/BatchNum'
1389 - nullable: true
1390 - example: 5432
1391 requestFromAccountIndex:
1392 allOf:
1393 - $ref: '#/components/schemas/AccountIndex'
1394 - nullable: true
1395 - example: "hez:0xaa942cfcd25ad4d90a62358b0dd84f33b398262a"
1396 requestToAccountIndex:
1397 allOf:
1398 - $ref: '#/components/schemas/AccountIndex'
1399 - nullable: true
1400 - example: "hez:DAI:33"
1401 requestToHezEthereumAddress:
1402 allOf:
1403 - $ref: '#/components/schemas/HezEthereumAddress'
1404 - nullable: true
1405 - example: "hez:0xbb942cfcd25ad4d90a62358b0dd84f33b3982699"
1406 requestToBJJ:
1407 allOf:
1408 - $ref: '#/components/schemas/BJJ'
1409 - nullable: true
1410 - example: "hez:HVrB8xQHAYt9QTpPUsj3RGOzDmrCI4IgrYslTeTqo6Ix"
1411 requestTokenId:
1412 allOf:
1413 - $ref: '#/components/schemas/TokenId'
1414 - nullable: true
1415 - example: 4444
1416 requestAmount:
1417 allOf:
1418 - $ref: '#/components/schemas/BigInt'
1419 - description: Amount of tokens to be sent.
1420 - example: "7"
1421 - nullable: true
1422 requestFee:
1423 allOf:
1424 - $ref: '#/components/schemas/FeeSelector'
1425 - nullable: true
1426 - example: 8
1427 requestNonce:
1428 allOf:
1429 - $ref: '#/components/schemas/Nonce'
1430 - nullable: true
1431 - example: 6
1432 token:
1433 $ref: '#/components/schemas/Token'
1434 required:
1435 - fromAccountIndex
1436 - toHezAccountIndex
1437 - toHezEthereumAddress
1438 - toBjj
1439 - tokenId
1440 - amount
1441 - fee
1442 - nonce
1443 - signature
1444 TransactionId:
1445 type: string
1446 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)
1447 example: "0x00000000000001e240004700"
1448 EthereumAddress:
1449 type: string
1450 description: "Address of an Etherum account."
1451 pattern: "^0x[a-fA-F0-9]{40}$"
1452 example: "0xaa942cfcd25ad4d90a62358b0dd84f33b398262a"
1453 HezEthereumAddress:
1454 type: string
1455 description: "Address of an Etherum account linked to the Hermez network."
1456 pattern: "^hez:0x[a-fA-F0-9]{40}$"
1457 example: "hez:0xaa942cfcd25ad4d90a62358b0dd84f33b398262a"
1458 BJJ:
1459 type: string
1460 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."
1461 pattern: "^hez:[A-Za-z0-9_-]{44}$"
1462 example: "hez:rR7LXKal-av7I56Y0dEBCVmwc9zpoLY5ERhy5w7G-xwe"
1463 AccountIndex:
1464 type: string
1465 description: >-
1466 Identifier of an account. It references the position where the account is inside the state Merkle tree.
1467 The identifier is built using: `hez:` + `token symbol:` + `index`
1468 example: "hez:DAI:4444"
1469 TransactionType:
1470 type: string
1471 description: Type of transaction.
1472 enum:
1473 - Exit
1474 - Transfer
1475 - Deposit
1476 - CreateAccountDeposit
1477 - CreateAccountDepositTransfer
1478 - DepositTransfer
1479 - ForceTransfer
1480 - ForceExit
1481 - TransferToEthAddr
1482 - TransferToBJJ
1483 TokenId:
1484 type: integer
1485 description: Identifier of a token registered in the network.
1486 minimum: 0
1487 maximum: 4294967295
1488 example: 4444
1489 BigInt:
1490 type: string
1491 description: BigInt is an integer encoded as a string for numbers that are very large.
1492 example: "8708856933496328593"
1493 FeeSelector:
1494 type: integer
1495 description: Index of the fee type to select, more info [here](https://idocs.hermez.io/#/spec/zkrollup/fee-table?id=transaction-fee-table).
1496 minimum: 0
1497 maximum: 256
1498 example: 36
1499 Nonce:
1500 type: integer
1501 description: Number that can only be used once per account, increments by one at each transaction.
1502 minimum: 0
1503 maximum: 1.84467440737096e+19
1504 example: 121
1505 PoolL2TransactionState:
1506 type: string
1507 description: >
1508 State of a L2 transaction from the coordinator pool.
1509 * pend: Pending
1510 * fing: Forging
1511 * fged: Forged
1512 * invl: Invalid
1513 enum:
1514 - pend
1515 - fing
1516 - fged
1517 - invl
1518 Signature:
1519 type: string
1520 description: BabyJubJub compressed signature.
1521 pattern: "^[a-fA-F0-9]{128}$"
1522 example: "72024a43f546b0e1d9d5d7c4c30c259102a9726363adcc4ec7b6aea686bcb5116f485c5542d27c4092ae0ceaf38e3bb44417639bd2070a58ba1aa1aab9d92c03"
1523 BatchNum:
1524 type: integer
1525 description: Identifier of a batch. Every new forged batch increments by one the batchNum, starting at 0.
1526 minimum: 0
1527 maximum: 4294967295
1528 example: 5432
1529 AccountCreationAuthorization:
1530 type: object
1531 properties:
1532 timestamp:
1533 type: string
1534 format: date-time
1535 hezEthereumAddress:
1536 $ref: '#/components/schemas/HezEthereumAddress'
1537 bjj:
1538 $ref: '#/components/schemas/BJJ'
1539 signature:
1540 allOf:
1541 - $ref: '#/components/schemas/Signature'
1542 - description: Signature of the auth message. More info [here](https://idocs.hermez.io/#/spec/zkrollup/README?id=regular-rollup-account).
1543 - example: "72024a43f546b0e1d9d5d7c4c30c259102a9726363adcc4ec7b6aea686bcb5116f485c5542d27c4092ae0ceaf38e3bb44417639bd2070a58ba1aa1aab9d92c03"
1544 required:
1545 - ethereumAddress
1546 - bjj
1547 - signature
1548 HistoryTransaction:
1549 type: object
1550 description: Transaction of the Hermez network
1551 properties:
1552 L1orL2:
1553 type: string
1554 enum:
1555 - L1
1556 - L2
1557 id:
1558 $ref: '#/components/schemas/TransactionId'
1559 type:
1560 $ref: '#/components/schemas/TransactionType'
1561 position:
1562 $ref: '#/components/schemas/TransactionPosition'
1563 fromAccountIndex:
1564 type: string
1565 description: >-
1566 Identifier of an account. It references the position where the account is inside the state Merkle tree.
1567 The identifier is built using: `hez:` + `token symbol:` + `index`
1568 example: "hez:DAI:4444"
1569 nullable: true
1570 toAccountIndex:
1571 allOf:
1572 - $ref: '#/components/schemas/AccountIndex'
1573 - example: "hez:DAI:672"
1574 amount:
1575 allOf:
1576 - $ref: '#/components/schemas/BigInt'
1577 - description: Amount of tokens to be sent.
1578 - example: "49"
1579 batchNum:
1580 type: integer
1581 description: Batch in which the transaction was forged. Null indicates not forged yet.
1582 minimum: 0
1583 maximum: 4294967295
1584 example: 5432
1585 nullable: true
1586 historicUSD:
1587 type: number
1588 description: Value in USD at the moment the transaction was forged.
1589 example: 49.7
1590 nullable: true
1591 timestamp:
1592 type: string
1593 format: date-time
1594 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.
1595 token:
1596 $ref: '#/components/schemas/Token'
1597 L1Info:
1598 type: object
1599 description: Additional information that only applies to L1 transactions.
1600 nullable: true
1601 properties:
1602 toForgeL1TransactionsNum:
1603 $ref: '#/components/schemas/ToForgeL1TransactionsNum'
1604 userOrigin:
1605 type: boolean
1606 description: True if the transaction was sent by a user. False if it was sent by a coordinator.
1607 fromHezEthereumAddress:
1608 $ref: '#/components/schemas/HezEthereumAddress'
1609 fromBJJ:
1610 $ref: '#/components/schemas/BJJ'
1611 loadAmount:
1612 allOf:
1613 - $ref: '#/components/schemas/BigInt'
1614 - description: Tokens transfered from L1 to L2.
1615 - example: "49"
1616 historicLoadAmountUSD:
1617 type: number
1618 description: Load amount in USD, at the moment the transaction was made.
1619 example: 3.897
1620 nullable: true
1621 ethereumBlockNum:
1622 allOf:
1623 - $ref: '#/components/schemas/EthBlockNum'
1624 - description: Ethereum block in which the transaction was added to the smart contract forge queue.
1625 - example: 258723049
1626 required:
1627 - toForgeL1TransactionsNum
1628 - userOrigin
1629 - fromHezEthereumAddress
1630 - fromBJJ
1631 - loadAmount
1632 - historicLoadAmountUSD
1633 - ethereumBlockNum
1634 additionalProperties: false
1635 L2Info:
1636 type: object
1637 description: Additional information that only applies to L2 transactions.
1638 nullable: true
1639 properties:
1640 fee:
1641 $ref: '#/components/schemas/FeeSelector'
1642 historicFeeUSD:
1643 type: number
1644 description: Fee in USD, at the moment the transaction was forged.
1645 example: 263.89
1646 nullable: true
1647 nonce:
1648 $ref: '#/components/schemas/Nonce'
1649 example: null
1650 required:
1651 - fee
1652 - historicFeeUSD
1653 - nonce
1654 additionalProperties: false
1655 required:
1656 - L1orL2
1657 - id
1658 - type
1659 - position
1660 - fromAccountIndex
1661 - toAccountIndex
1662 - amount
1663 - batchNum
1664 - historicUSD
1665 - timestamp
1666 - token
1667 - L1Info
1668 - L2Info
1669 additionalProperties: false
1670 HistoryTransactions:
1671 type: object
1672 properties:
1673 transactions:
1674 type: array
1675 description: List of history transactions.
1676 items:
1677 $ref: '#/components/schemas/HistoryTransaction'
1678 pagination:
1679 $ref: '#/components/schemas/PaginationInfo'
1680 required:
1681 - transactions
1682 - pagination
1683 additionalProperties: false
1684 EthBlockNum:
1685 type: integer
1686 description: Ethereum block number
1687 minimum: 0
1688 maximum: 1.84467440737096e+19
1689 example: 762375478
1690 ToForgeL1TransactionsNum:
1691 type: integer
1692 description: Reference to know in which batch a L1 transaction was forged / will be forged.
1693 minimum: 0
1694 maximum: 4294967295
1695 example: 784
1696 nullable: true
1697 TransactionPosition:
1698 type: integer
1699 description: Position that a transaction occupies in a batch.
1700 minimum: 0
1701 example: 5
1702 URL:
1703 type: string
1704 description: HTTP URL
1705 example: "https://hermez.io"
1706 TokenSymbol:
1707 type: string
1708 description: Abreviation of the token name.
1709 example: "DAI"
1710 TokenName:
1711 type: string
1712 description: Token name.
1713 example: "Dai"
1714 CollectedFees:
1715 type: array
1716 description: Collected fees by the forger of the batch. A maximum of 64 different tokens can be used.
1717 items:
1718 type: object
1719 properties:
1720 tokenId:
1721 $ref: '#/components/schemas/TokenId'
1722 amount:
1723 allOf:
1724 - $ref: '#/components/schemas/BigInt'
1725 - description: Ammount of collected tokens
1726 - example: "53"
1727 Batch:
1728 type: object
1729 description: Group of transactions forged in a coordinator and sent and validated in Ethereum.
1730 properties:
1731 batchNum:
1732 $ref: '#/components/schemas/BatchNum'
1733 ethereumBlockNum:
1734 $ref: '#/components/schemas/EthBlockNum'
1735 ethereumBlockHash:
1736 type: string
1737 description: hash of the Ethereum block in which the batch was forged
1738 example: "0xfe88c94d860f01a17f961bf4bdfb6e0c6cd10d3fda5cc861e805ca1240c58553"
1739 timestamp:
1740 type: string
1741 format: date-time
1742 description: Time in which the batch was forged.
1743 forgerAddr:
1744 $ref: '#/components/schemas/EthereumAddress'
1745 collectedFees:
1746 $ref: '#/components/schemas/CollectedFees'
1747 totalCollectedFeesUSD:
1748 type: number
1749 description: Value in USD of the collected tokens by the forger in concept of fees. This is calculated at the moment the batch is forged, with the conversion rates at that time.
1750 historicTotalCollectedFeesUSD:
1751 type: number
1752 description: Sum of the all the fees collected, in USD, at the moment the batch was forged.
1753 example: 23.3
1754 stateRoot:
1755 allOf:
1756 - $ref: '#/components/schemas/Hash'
1757 - description: Root of the accounts Merkle Tree.
1758 - example: "2734657026572a8708d883"
1759 numAccounts:
1760 type: integer
1761 description: Number of registered accounts in this batch.
1762 exitRoot:
1763 allOf:
1764 - $ref: '#/components/schemas/Hash'
1765 - description: Root of the exit Merkle Tree associated to this batch.
1766 - example: "2734657026572a8708d883"
1767 forgeL1TransactionsNum:
1768 allOf:
1769 - $ref: '#/components/schemas/ToForgeL1TransactionsNum'
1770 - description: Identifier that corresponds to the group of L1 transactions forged in the current batch.
1771 - example: 5
1772 slotNum:
1773 $ref: '#/components/schemas/SlotNum'
1774 FullBatch:
1775 type: object
1776 description: Group of transactions forged in a coordinator and sent and validated in Ethereum.
1777 properties:
1778 batch:
1779 $ref: '#/components/schemas/Batch'
1780 transactions:
1781 type: array
1782 description: List of forged transactions in the batch
1783 items:
1784 $ref: '#/components/schemas/HistoryTransaction'
1785 Hash:
1786 type: string
1787 description: hashed data
1788 example: "2734657026572a8708d883"
1789 SlotNum:
1790 type: integer
1791 description: Identifier of a slot.
1792 minimum: 0
1793 maximum: 4294967295
1794 example: 784
1795 Batches:
1796 type: object
1797 properties:
1798 batches:
1799 type: array
1800 description: List of batches.
1801 items:
1802 $ref: '#/components/schemas/Batch'
1803 pagination:
1804 $ref: '#/components/schemas/PaginationInfo'
1805 Coordinator:
1806 type: object
1807 properties:
1808 forgerAddr:
1809 $ref: '#/components/schemas/EthereumAddress'
1810 withdrawAddr:
1811 $ref: '#/components/schemas/EthereumAddress'
1812 URL:
1813 $ref: '#/components/schemas/URL'
1814 ethereumBlock:
1815 allOf:
1816 - $ref: '#/components/schemas/EthBlockNum'
1817 - description: Ethereum block in which the coordinator registered into the network.
1818 - example: 5735943738
1819 Coordinators:
1820 type: object
1821 properties:
1822 coordinators:
1823 type: array
1824 description: List of coordinators.
1825 items:
1826 $ref: '#/components/schemas/Coordinator'
1827 pagination:
1828 $ref: '#/components/schemas/PaginationInfo'
1829 Bid:
1830 type: object
1831 description: Tokens placed in an auction by a coordinator to gain the right to forge batches during a specific slot.
1832 properties:
1833 forgerAddr:
1834 $ref: '#/components/schemas/EthereumAddress'
1835 slotNum:
1836 $ref: '#/components/schemas/SlotNum'
1837 withdrawAddr:
1838 $ref: '#/components/schemas/EthereumAddress'
1839 URL:
1840 $ref: '#/components/schemas/URL'
1841 bidValue:
1842 $ref: '#/components/schemas/BigInt'
1843 ethereumBlockNum:
1844 $ref: '#/components/schemas/EthBlockNum'
1845 timestamp:
1846 type: string
1847 format: date-time
1848 Bids:
1849 type: object
1850 properties:
1851 bids:
1852 type: array
1853 description: List of bids.
1854 items:
1855 $ref: '#/components/schemas/Bid'
1856 pagination:
1857 $ref: '#/components/schemas/PaginationInfo'
1858 RecommendedFee:
1859 type: object
1860 description: Fee that the coordinator recommends per transaction in USD.
1861 properties:
1862 existingAccount:
1863 type: number
1864 description: Recommended fee if the destination account of the transaction already exists.
1865 minimum: 0
1866 example: 0.1
1867 createAccount:
1868 type: number
1869 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.
1870 minimum: 0
1871 example: 1.3
1872 createAccountInternal:
1873 type: number
1874 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.
1875 minimum: 0
1876 example: 0.5
1877 Token:
1878 type: object
1879 description: Hermez network compatible and registered token.
1880 properties:
1881 id:
1882 $ref: '#/components/schemas/TokenId'
1883 ethereumAddress:
1884 allOf:
1885 - $ref: '#/components/schemas/EthereumAddress'
1886 - description: Ethereum address in which the token is deployed.
1887 - example: "0xaa942cfcd25ad4d90a62358b0dd84f33b398262a"
1888 name:
1889 type: string
1890 description: full name of the token
1891 example: Maker Dai
1892 symbol:
1893 allOf:
1894 - $ref: '#/components/schemas/TokenSymbol'
1895 - example: DAI
1896 decimals:
1897 type: integer
1898 description: Number of decimals of the token.
1899 example: 18
1900 ethereumBlockNum:
1901 allOf:
1902 - $ref: '#/components/schemas/EthBlockNum'
1903 - description: Ethereum block number in which the token was added to the Hermez network.
1904 - example: 539847538
1905 USD:
1906 type: number
1907 description: Value of the token in USD.
1908 example: 1.01
1909 nullable: true
1910 fiatUpdate:
1911 type: string
1912 format: date-time
1913 description: Timestamp of the moment the `USD` value was updated.
1914 nullable: true
1915 required:
1916 - id
1917 - ethereumAddress
1918 - name
1919 - symbol
1920 - decimals
1921 - ethereumBlockNum
1922 - USD
1923 - fiatUpdate
1924 additionalProperties: false
1925 Tokens:
1926 type: object
1927 properties:
1928 tokens:
1929 type: array
1930 description: List of tokens.
1931 items:
1932 $ref: '#/components/schemas/Token'
1933 pagination:
1934 $ref: '#/components/schemas/PaginationInfo'
1935 Exit:
1936 type: object
1937 description: Exit tree leaf. It Contains the necessary information to perform a withdrawal.
1938 properties:
1939 batchNum:
1940 allOf:
1941 - $ref: '#/components/schemas/BatchNum'
1942 - description: Batch in which the exit was forged.
1943 - example: 7394
1944 accountIndex:
1945 $ref: '#/components/schemas/AccountIndex'
1946 merkleProof:
1947 type: string
1948 description: Existence proof of a leaf in a given Merkle Root. Encoded as hexadecimal string.
1949 example: "0x347089321de8971320489793a823470918fffeab"
1950 balance:
1951 $ref: '#/components/schemas/BigInt'
1952 instantWithdrawn:
1953 allOf:
1954 - $ref: '#/components/schemas/EthBlockNum'
1955 - description: Block in which the exit balance was instantly withdrawn. Null indicates that an instant withdrawn hasn't been performed.
1956 - example: 74747363
1957 delayedWithdrawRequest:
1958 allOf:
1959 - $ref: '#/components/schemas/EthBlockNum'
1960 - description: Block in which the exit balance was requested to delay withdraw. Null indicates that a delay withdraw hasn't been performed.
1961 - example: null
1962 delayedWithdrawn:
1963 allOf:
1964 - $ref: '#/components/schemas/EthBlockNum'
1965 - 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.
1966 - example: null
1967 token:
1968 $ref: '#/components/schemas/Token'
1969 Exits:
1970 type: object
1971 properties:
1972 exits:
1973 type: array
1974 description: List of exits.
1975 items:
1976 $ref: '#/components/schemas/Exit'
1977 pagination:
1978 $ref: '#/components/schemas/PaginationInfo'
1979 Account:
1980 type: object
1981 description: State tree leaf. It contains balance and nonce of an account.
1982 properties:
1983 accountIndex:
1984 $ref: '#/components/schemas/AccountIndex'
1985 nonce:
1986 $ref: '#/components/schemas/Nonce'
1987 balance:
1988 $ref: '#/components/schemas/BigInt'
1989 bjj:
1990 $ref: '#/components/schemas/BJJ'
1991 hezEthereumAddress:
1992 $ref: '#/components/schemas/HezEthereumAddress'
1993 token:
1994 $ref: '#/components/schemas/Token'
1995 Accounts:
1996 type: object
1997 properties:
1998 accounts:
1999 type: array
2000 description: List of accounts.
2001 items:
2002 $ref: '#/components/schemas/Account'
2003 pagination:
2004 $ref: '#/components/schemas/PaginationInfo'
2005 Slot:
2006 type: object
2007 description: Slot information.
2008 properties:
2009 slotNum:
2010 $ref: '#/components/schemas/SlotNum'
2011 firstBlock:
2012 allOf:
2013 - $ref: '#/components/schemas/EthBlockNum'
2014 - description: Block in which the slot began or will begin
2015 - example: 76238647846
2016 lastBlock:
2017 allOf:
2018 - $ref: '#/components/schemas/EthBlockNum'
2019 - description: Block in which the slot ended or will end
2020 - example: 4475934
2021 closedAuction:
2022 type: boolean
2023 description: Whether the auction of the slot has finished or not.
2024 winner:
2025 allOf:
2026 - $ref: '#/components/schemas/Coordinator'
2027 - description: Coordinator who won the auction. Only applicable if the auction is closed.
2028 - nullable: true
2029 - example: null
2030 batchNums:
2031 type: array
2032 description: List of batch numbers that were forged during the slot
2033 items:
2034 $ref: '#/components/schemas/BatchNum'
2035 Slots:
2036 type: object
2037 properties:
2038 nextForgers:
2039 type: array
2040 description: List of slots.
2041 items:
2042 $ref: '#/components/schemas/Slot'
2043 pagination:
2044 $ref: '#/components/schemas/PaginationInfo'
2045 NextForger:
2046 type: object
2047 description: Coordinator information along with the scheduled forging period
2048 properties:
2049 coordinator:
2050 $ref: '#/components/schemas/Coordinator'
2051 period:
2052 type: object
2053 description: Time period in which the coordinator will have the ability to forge. Specified both in Ethereum blocks and timestamp
2054 properties:
2055 fromBlock:
2056 $ref: '#/components/schemas/EthBlockNum'
2057 toBlock:
2058 $ref: '#/components/schemas/EthBlockNum'
2059 fromTimestamp:
2060 type: string
2061 format: date-time
2062 toTimestamp:
2063 type: string
2064 format: date-time
2065 NextForgers:
2066 type: object
2067 properties:
2068 nextForgers:
2069 type: array
2070 description: List of next coordinators to forge.
2071 items:
2072 $ref: '#/components/schemas/NextForger'
2073 pagination:
2074 $ref: '#/components/schemas/PaginationInfo'
2075 State:
2076 type: object
2077 description: Gobal statistics of the network.
2078 properties:
2079 lastBlock:
2080 allOf:
2081 - $ref: '#/components/schemas/EthBlockNum'
2082 - description: Last synchronized Etherum block.
2083 - example: 3457437
2084 lastBatch:
2085 allOf:
2086 - $ref: '#/components/schemas/BatchNum'
2087 - description: Last batch that has been forged.
2088 - example: 76523
2089 currentSlot:
2090 allOf:
2091 - $ref: '#/components/schemas/SlotNum'
2092 - description: Slot where batches are currently being forged.
2093 - example: 2334
2094 transactionsPerBatch:
2095 type: number
2096 description: Average transactions per batch in the last 24 hours.
2097 example: 2002.7
2098 batchFrequency:
2099 type: number
2100 description: Average elapsed time between batches in the last 24 hours, in seconds.
2101 example: 8.9
2102 transactionsPerSecond:
2103 type: number
2104 description: Average transactions per second in the last 24 hours.
2105 example: 302.3
2106 totalAccounts:
2107 type: integer
2108 description: Number of created accounts.
2109 example: 90473
2110 totalBJJs:
2111 type: integer
2112 description: Number of different registered BJJs.
2113 example: 23067
2114 avgTransactionFee:
2115 type: number
2116 description: Average fee percentage paid for L2 transactions in the last 24 hours.
2117 example: 1.54
2118 governance:
2119 type: object
2120 description: Network setings that are updatable by the governance.
2121 properties:
2122 rollup:
2123 type: object
2124 description: Rollup parameters.
2125 properties:
2126 forgeTimeout:
2127 type: integer
2128 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.
2129 example: 5
2130 feeAddToken:
2131 type: integer
2132 description: fee to pay when registering tokens into the network.
2133 example: 5698
2134 auction:
2135 type: object
2136 description: Auction parameters.
2137 properties:
2138 bootCoordinator:
2139 allOf:
2140 - $ref: '#/components/schemas/EthereumAddress'
2141 - description: Ethereum address of the boot coordinator.
2142 - example: "0x997dc4262BCDbf85190C01c996b4C06a461d2430"
2143 slotDeadline:
2144 type: integer
2145 description: Number of blocks at the end of a slot in which any coordinator can forge if the winner has not forged one before.
2146 example: 3
2147 closedAuctionSlots:
2148 type: integer
2149 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.
2150 example: 2
2151 openAuctionSlots:
2152 type: integer
2153 description: How many days in advance are auctions opened.
2154 defaultSlotSetBid:
2155 type: array
2156 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]`."
2157 items:
2158 type: integer
2159 example: [32,0,68,21,55,99]
2160 outbidding:
2161 type: number
2162 description: Minimum outbid over the previous one to consider it valid.
2163 example: 3.64
2164 donationAddress:
2165 allOf:
2166 - $ref: '#/components/schemas/EthereumAddress'
2167 - description: Ethereum address where the donations will go to.
2168 - example: "0x887dc4262BCDbf85190C01c996b4C06a461d2430"
2169 allocationRatio:
2170 type: array
2171 description: Percentage in which fees will be splitted between donations, governance and burning. The sum of the tree values should be 100.
2172 items:
2173 type: integer
2174 example: [80,10,10]
2175 withdrawalDelayer:
2176 type: object
2177 description: Withdrawal delayer parameters.
2178 properties:
2179 rollupAddress:
2180 allOf:
2181 - $ref: '#/components/schemas/EthereumAddress'
2182 - description: Ethereum address of the rollup smart contract.
2183 - example: "0x777dc4262BCDbf85190C01c996b4C06a461d2430"
2184 governanceAddress:
2185 allOf:
2186 - $ref: '#/components/schemas/EthereumAddress'
2187 - description: Ethereum address of the governance mechanism.
2188 - example: "0x667dc4262BCDbf85190C01c996b4C06a461d2430"
2189 whitheHackerGroupAddress:
2190 allOf:
2191 - $ref: '#/components/schemas/EthereumAddress'
2192 - description: Ethereum Address that can claim the funds in an emergency when the maximum emergency mode time is exceeded.
2193 - example: "0x557dc4262BCDbf85190C01c996b4C06a461d2430"
2194 keeperAddress:
2195 allOf:
2196 - $ref: '#/components/schemas/EthereumAddress'
2197 - description: Ethereum Address that can enable emergency mode and modify the delay to make a withdrawal.
2198 - example: "0x557dc4262BCDbf85190C01c996b4C06a461d2430"
2199 withdrawalDelay:
2200 allOf:
2201 - $ref: '#/components/schemas/EthBlockNum'
2202 - description: The time that anyone needs to wait until a withdrawal of the funds is allowed, in Ethereum blocks.
2203 - example: 539573849
2204 emergencyModeStartingTime:
2205 type: integer
2206 description: Ethereum block in which the emergency mode will be activated.
2207 example: 10
2208 emergencyMode:
2209 type: boolean
2210 description: Indicates if emergency mode has been activated.
2211
2212 PaginationInfo:
2213 type: object
2214 description: Give pagination information
2215 properties:
2216 totalItems:
2217 type: integer
2218 description: Amount of items that the endpoint can return given the filters and the current state of the database.
2219 example: 2048
2220 lastReturnedItem:
2221 type: integer
2222 description: Index of the last returned item. Useful to query next items.
2223 example: 439
2224 Config:
2225 type: object
2226 description: Configuration parameters of the different smart contracts that power the Hermez network.
2227 properties:
2228 hermez:
2229 type: object
2230 description: Constant configuration of the Hermez smart contract.
2231 properties:
2232 HEZTokenAddress:
2233 allOf:
2234 - $ref: '#/components/schemas/EthereumAddress'
2235 - description: Ethereum address of the HEZ token.
2236 - example: "0x444dc4262BCDbf85190C01c996b4C06a461d2430"
2237 maxTxVerifiers:
2238 type: integer
2239 description: Maximum transactions of the verifiers.
2240 example: 100
2241 maxLoadAmount:
2242 type: integer
2243 description: Maximum load amount (L1 to L2) allowed.
2244 example: 321
2245 maxAmount:
2246 type: integer
2247 description: Maximum amount (L2 to L2) allowed.
2248 example: 837
2249 maxTokens:
2250 type: integer
2251 description: Maximum number of different tokens that can be registered in the network.
2252 example: 4294967295
2253 reservedAccountIndex:
2254 type: integer
2255 description: First user index. Bellow this number the indexes are reserved for the protocol.
2256 example: 256
2257 lastAccountIndex:
2258 type: integer
2259 description: Biggest account index that can be registered.
2260 example: 4294967295
2261 exitAccountIndex:
2262 type: integer
2263 description: Account index used to indicate that a transaction is an `exit` or `force exit`.
2264 example: 1
2265 L1CoordinatorBytes:
2266 type: integer
2267 description: Number of bytes that a L1 coordinator transaction has ([4 bytes] token + [32 bytes] babyjub + [65 bytes] compressedSignature).
2268 example: 23
2269 L1UserBytes:
2270 type: integer
2271 description: Number of bytes that a L2 transaction has ([4 bytes] fromIdx + [4 bytes] toIdx + [2 bytes] amountFloat16 + [1 bytes] fee).
2272 example: 32
2273 L2Bytes:
2274 type: integer
2275 description: Number of bytes that a L2 transaction has ([4 bytes] fromIdx + [4 bytes] toIdx + [2 bytes] amountFloat16 + [1 bytes] fee).
2276 example: 33
2277 maxL1Transactions:
2278 type: integer
2279 description: Maximum L1 transactions allowed to be queued in a batch.
2280 example: 128
2281 maxL1UserTransactions:
2282 type: integer
2283 description: Maximum L1 transactions allowed to be queued in a batch by users (anyone who is not a coordinator).
2284 example: 32
2285 RField:
2286 allOf:
2287 - $ref: '#/components/schemas/BigInt'
2288 - description: Modulus zkSNARK.
2289 withdrawManager:
2290 type: object
2291 description: Constant configuration of the withdraw manager smart contract.
2292 properties:
2293 noLimit:
2294 type: integer
2295 description: Reserved bucket index when the token value is 0 USD.
2296 example: 0
2297 amountOfBuckets:
2298 type: integer
2299 description: Number of buckets
2300 maxWithdrawalDelay:
2301 type: integer
2302 description: Maximum delay to withdraw tokens. Time is measured in Ethereum blocks.
2303 auction:
2304 type: object
2305 description: Constant configuration of the auction smart contract.
2306 properties:
2307 HEZTokenAddress:
2308 allOf:
2309 - $ref: '#/components/schemas/EthereumAddress'
2310 - description: Ethereum address of the HEZ token.
2311 - example: "0x333dc4262BCDbf85190C01c996b4C06a461d2430"
2312 rollupAddress:
2313 allOf:
2314 - $ref: '#/components/schemas/EthereumAddress'
2315 - description: Ethereum address of the rollup smart contract.
2316 - example: "0x222dc4262BCDbf85190C01c996b4C06a461d2430"
2317 genesisBlockNum:
2318 allOf:
2319 - $ref: '#/components/schemas/EthBlockNum'
2320 - description: Ethereum block number in which the smart contract starts operating.
2321 delayGenesis:
2322 type: integer
2323 description: Time delay between `genesisBlockNum` and the beginning of the first block. Time is measured in Ethereum blocks.
2324 blocksPerSlot:
2325 type: integer
2326 description: Blocks per slot.
2327 initialMinimalBidding:
2328 type: integer
2329 description: Minimum bid when no one has bid yet.
2330 withdrawalDelayer:
2331 type: object
2332 description: Constant configuration of the withdrawal delayer smart contract.
2333 properties:
2334 maxWithdrawalDelay:
2335 type: integer
2336 description: Maximum time delay in which the tokens can be locked in the contract. Time is measured in Ethereum blocks.
2337 example: 200
2338 maxEmergencyModeTime:
2339 type: integer
2340 description: Maximum amount of time in which the contract can be in emergency mode. Time is measured in Ethereum blocks.
2341 example: 2000
2342 Error:
2343 type: object
2344 description: Error response.
2345 properties:
2346 message:
2347 type: string
2348 Error400:
2349 allOf:
2350 - $ref: '#/components/schemas/Error'
2351 - example:
2352 message: Invalid signature.
2353 Error404:
2354 allOf:
2355 - $ref: '#/components/schemas/Error'
2356 - example:
2357 message: Item(s) not found.
2358 Error500:
2359 allOf:
2360 - $ref: '#/components/schemas/Error'
2361 - example:
2362 message: Database error.