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