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