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 paginated 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 is 2049.
19
20 Responses for those endpoints will always include a `pendingItems` property. This property includes the amount of items that are not fetched yet. This 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 requires 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 is 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 nullable: true
1861 additionalProperties: false
1862 required:
1863 - batch
1864 - transactions
1865 Hash:
1866 type: string
1867 description: hashed data
1868 example: "2734657026572a8708d883"
1869 SlotNum:
1870 type: integer
1871 description: Identifier of a slot.
1872 minimum: 0
1873 maximum: 4294967295
1874 example: 784
1875 Batches:
1876 type: object
1877 properties:
1878 batches:
1879 type: array
1880 description: List of batches.
1881 items:
1882 $ref: '#/components/schemas/Batch'
1883 pendingItems:
1884 $ref: '#/components/schemas/PendingItems'
1885 additionalProperties: false
1886 required:
1887 - batches
1888 - pendingItems
1889 Coordinator:
1890 type: object
1891 properties:
1892 itemId:
1893 $ref: '#/components/schemas/ItemId'
1894 forgerAddr:
1895 $ref: '#/components/schemas/EthereumAddress'
1896 bidderAddr:
1897 $ref: '#/components/schemas/EthereumAddress'
1898 URL:
1899 $ref: '#/components/schemas/URL'
1900 ethereumBlock:
1901 allOf:
1902 - $ref: '#/components/schemas/EthBlockNum'
1903 - description: Ethereum block in which the coordinator registered into the network.
1904 - example: 5735943738
1905 additionalProperties: false
1906 required:
1907 - itemId
1908 - forgerAddr
1909 - bidderAddr
1910 - URL
1911 - ethereumBlock
1912 Coordinators:
1913 type: object
1914 properties:
1915 coordinators:
1916 type: array
1917 description: List of coordinators.
1918 items:
1919 $ref: '#/components/schemas/Coordinator'
1920 pendingItems:
1921 $ref: '#/components/schemas/PendingItems'
1922 additionalProperties: false
1923 required:
1924 - coordinators
1925 - pendingItems
1926 Bid:
1927 type: object
1928 description: Tokens placed in an auction by a coordinator to gain the right to forge batches during a specific slot.
1929 properties:
1930 itemId:
1931 $ref: '#/components/schemas/ItemId'
1932 bidderAddr:
1933 $ref: '#/components/schemas/EthereumAddress'
1934 forgerAddr:
1935 $ref: '#/components/schemas/EthereumAddress'
1936 slotNum:
1937 $ref: '#/components/schemas/SlotNum'
1938 URL:
1939 $ref: '#/components/schemas/URL'
1940 bidValue:
1941 $ref: '#/components/schemas/BigInt'
1942 ethereumBlockNum:
1943 $ref: '#/components/schemas/EthBlockNum'
1944 timestamp:
1945 type: string
1946 format: date-time
1947 additionalProperties: false
1948 required:
1949 - bidderAddr
1950 - forgerAddr
1951 - slotNum
1952 - URL
1953 - bidValue
1954 - ethereumBlockNum
1955 - timestamp
1956 Bids:
1957 type: object
1958 properties:
1959 bids:
1960 type: array
1961 description: List of bids.
1962 items:
1963 $ref: '#/components/schemas/Bid'
1964 pendingItems:
1965 $ref: '#/components/schemas/PendingItems'
1966 additionalProperties: false
1967 required:
1968 - bids
1969 - pendingItems
1970 RecommendedFee:
1971 type: object
1972 description: Fee that the coordinator recommends per transaction in USD.
1973 properties:
1974 existingAccount:
1975 type: number
1976 description: Recommended fee if the destination account of the transaction already exists.
1977 minimum: 0
1978 example: 0.1
1979 createAccount:
1980 type: number
1981 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.
1982 minimum: 0
1983 example: 1.3
1984 createAccountInternal:
1985 type: number
1986 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.
1987 minimum: 0
1988 example: 0.5
1989 Token:
1990 type: object
1991 description: Hermez network compatible and registered token.
1992 properties:
1993 id:
1994 $ref: '#/components/schemas/TokenId'
1995 ethereumAddress:
1996 allOf:
1997 - $ref: '#/components/schemas/EthereumAddress'
1998 - description: Ethereum address in which the token is deployed.
1999 - example: "0xaa942cfcd25ad4d90a62358b0dd84f33b398262a"
2000 itemId:
2001 $ref: '#/components/schemas/ItemId'
2002 name:
2003 type: string
2004 description: full name of the token
2005 example: Maker Dai
2006 symbol:
2007 allOf:
2008 - $ref: '#/components/schemas/TokenSymbol'
2009 - example: DAI
2010 decimals:
2011 type: integer
2012 description: Number of decimals of the token.
2013 example: 18
2014 ethereumBlockNum:
2015 allOf:
2016 - $ref: '#/components/schemas/EthBlockNum'
2017 - description: Ethereum block number in which the token was added to the Hermez network.
2018 - example: 539847538
2019 USD:
2020 type: number
2021 description: Value of the token in USD.
2022 example: 1.01
2023 nullable: true
2024 fiatUpdate:
2025 type: string
2026 format: date-time
2027 description: Timestamp of the moment the `USD` value was updated.
2028 nullable: true
2029 required:
2030 - id
2031 - ethereumAddress
2032 - itemId
2033 - name
2034 - symbol
2035 - decimals
2036 - ethereumBlockNum
2037 - USD
2038 - fiatUpdate
2039 additionalProperties: false
2040 Tokens:
2041 type: object
2042 properties:
2043 tokens:
2044 type: array
2045 description: List of tokens.
2046 items:
2047 $ref: '#/components/schemas/Token'
2048 pendingItems:
2049 $ref: '#/components/schemas/PendingItems'
2050 Exit:
2051 type: object
2052 description: Exit tree leaf. It Contains the necessary information to perform a withdrawal.
2053 properties:
2054 batchNum:
2055 allOf:
2056 - $ref: '#/components/schemas/BatchNum'
2057 - description: Batch in which the exit was forged.
2058 - example: 7394
2059 accountIndex:
2060 $ref: '#/components/schemas/AccountIndex'
2061 itemId:
2062 $ref: '#/components/schemas/ItemId'
2063 merkleProof:
2064 type: object
2065 description: Existence proof of a leaf in a given Merkle Root. Encoded as hexadecimal string.
2066 properties:
2067 Root:
2068 $ref: '#/components/schemas/BigInt'
2069 Siblings:
2070 type: array
2071 items:
2072 $ref: '#/components/schemas/BigInt'
2073 OldKey:
2074 $ref: '#/components/schemas/BigInt'
2075 OldValue:
2076 $ref: '#/components/schemas/BigInt'
2077 IsOld0:
2078 type: boolean
2079 Key:
2080 $ref: '#/components/schemas/BigInt'
2081 Value:
2082 $ref: '#/components/schemas/BigInt'
2083 Fnc:
2084 type: integer
2085 maximum: 3
2086 minimum: 0
2087 required:
2088 - Root
2089 - Siblings
2090 - OldKey
2091 - OldValue
2092 - IsOld0
2093 - Key
2094 - Value
2095 - Fnc
2096 additionalProperties: false
2097 balance:
2098 $ref: '#/components/schemas/BigInt'
2099 instantWithdrawn:
2100 type: integer
2101 description: Block in which the exit balance was instantly withdrawn. Null indicates that an instant withdrawn hasn't been performed.
2102 minimum: 0
2103 maximum: 1.84467440737096e+19
2104 example: 74747363
2105 nullable: true
2106 delayedWithdrawRequest:
2107 type: integer
2108 description: Block in which the exit balance was requested to delay withdraw. Null indicates that a delay withdraw hasn't been performed.
2109 minimum: 0
2110 maximum: 1.84467440737096e+19
2111 example: null
2112 nullable: true
2113 delayedWithdrawn:
2114 type: integer
2115 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.
2116 minimum: 0
2117 maximum: 1.84467440737096e+19
2118 example: null
2119 nullable: true
2120 token:
2121 $ref: '#/components/schemas/Token'
2122 required:
2123 - batchNum
2124 - accountIndex
2125 - itemId
2126 - merkleProof
2127 - balance
2128 - instantWithdrawn
2129 - delayedWithdrawRequest
2130 - delayedWithdrawn
2131 - token
2132 additionalProperties: false
2133 Exits:
2134 type: object
2135 properties:
2136 exits:
2137 type: array
2138 description: List of exits.
2139 items:
2140 $ref: '#/components/schemas/Exit'
2141 pendingItems:
2142 $ref: '#/components/schemas/PendingItems'
2143 required:
2144 - exits
2145 - pendingItems
2146 additionalProperties: false
2147 Account:
2148 type: object
2149 description: State tree leaf. It contains balance and nonce of an account.
2150 properties:
2151 itemId:
2152 $ref: '#/components/schemas/ItemId'
2153 accountIndex:
2154 $ref: '#/components/schemas/AccountIndex'
2155 nonce:
2156 $ref: '#/components/schemas/Nonce'
2157 balance:
2158 $ref: '#/components/schemas/BigInt'
2159 bjj:
2160 $ref: '#/components/schemas/BJJ'
2161 hezEthereumAddress:
2162 $ref: '#/components/schemas/HezEthereumAddress'
2163 token:
2164 $ref: '#/components/schemas/Token'
2165 additionalProperties: false
2166 required:
2167 - itemId
2168 - accountIndex
2169 - nonce
2170 - balance
2171 - bjj
2172 - hezEthereumAddress
2173 - token
2174 Accounts:
2175 type: object
2176 properties:
2177 accounts:
2178 type: array
2179 description: List of accounts.
2180 items:
2181 $ref: '#/components/schemas/Account'
2182 pendingItems:
2183 $ref: '#/components/schemas/PendingItems'
2184 additionalProperties: false
2185 required:
2186 - accounts
2187 - pendingItems
2188 Slot:
2189 type: object
2190 description: Slot information.
2191 properties:
2192 itemId:
2193 $ref: '#/components/schemas/ItemId'
2194 slotNum:
2195 $ref: '#/components/schemas/SlotNum'
2196 firstBlock:
2197 allOf:
2198 - $ref: '#/components/schemas/EthBlockNum'
2199 - description: Block in which the slot began or will begin
2200 - example: 76238647846
2201 lastBlock:
2202 allOf:
2203 - $ref: '#/components/schemas/EthBlockNum'
2204 - description: Block in which the slot ended or will end
2205 - example: 4475934
2206 openAuction:
2207 type: boolean
2208 description: Whether the auction of the slot is open or not.
2209 bestBid:
2210 type: object
2211 description: The best bid of the auction. If the bestBid is null, it is because no coordinator has bid for that slot.
2212 nullable: true
2213 properties:
2214 itemId:
2215 $ref: '#/components/schemas/ItemId'
2216 bidderAddr:
2217 $ref: '#/components/schemas/EthereumAddress'
2218 forgerAddr:
2219 $ref: '#/components/schemas/EthereumAddress'
2220 slotNum:
2221 $ref: '#/components/schemas/SlotNum'
2222 URL:
2223 $ref: '#/components/schemas/URL'
2224 bidValue:
2225 type: string
2226 description: BigInt is an integer encoded as a string for numbers that are very large.
2227 example: "8708856933496328593"
2228 pattern: "^\\d+$"
2229 ethereumBlockNum:
2230 $ref: '#/components/schemas/EthBlockNum'
2231 timestamp:
2232 type: string
2233 format: date-time
2234 additionalProperties: false
2235 required:
2236 - bidderAddr
2237 - forgerAddr
2238 - slotNum
2239 - URL
2240 - bidValue
2241 - ethereumBlockNum
2242 - timestamp
2243 additionalProperties: false
2244 required:
2245 - slotNum
2246 - firstBlock
2247 - lastBlock
2248 - openAuction
2249 - bestBid
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 required:
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 slotNum:
2277 $ref: '#/components/schemas/SlotNum'
2278 fromBlock:
2279 $ref: '#/components/schemas/EthBlockNum'
2280 toBlock:
2281 $ref: '#/components/schemas/EthBlockNum'
2282 fromTimestamp:
2283 type: string
2284 format: date-time
2285 toTimestamp:
2286 type: string
2287 format: date-time
2288 required:
2289 - slotNum
2290 - fromBlock
2291 - toBlock
2292 - fromTimestamp
2293 - toTimestamp
2294 additionalProperties: false
2295 required:
2296 - coordinator
2297 - period
2298 additionalProperties: false
2299 NextForgers:
2300 type: array
2301 description: List of next coordinators to forge.
2302 items:
2303 $ref: '#/components/schemas/NextForger'
2304 State:
2305 type: object
2306 description: Gobal variables of the network
2307 properties:
2308 network:
2309 $ref: '#/components/schemas/StateNetwork'
2310 metrics:
2311 $ref: '#/components/schemas/StateMetrics'
2312 rollup:
2313 $ref: '#/components/schemas/StateRollup'
2314 auction:
2315 $ref: '#/components/schemas/StateAuction'
2316 withdrawalDelayer:
2317 $ref: '#/components/schemas/StateWithdrawDelayer'
2318 recommendedFee:
2319 $ref: '#/components/schemas/RecommendedFee'
2320 additionalProperties: false
2321 required:
2322 - network
2323 - metrics
2324 - rollup
2325 - auction
2326 - withdrawalDelayer
2327 - recommendedFee
2328 StateNetwork:
2329 type: object
2330 description: Gobal statistics of the network
2331 properties:
2332 lastEthereumBlock:
2333 allOf:
2334 - $ref: '#/components/schemas/EthBlockNum'
2335 - description: Current Etherum block. Note that this is the actual last block of Ethereum, not the last synchronized block by the node.
2336 - example: 3457437
2337 lastSynchedBlock:
2338 allOf:
2339 - $ref: '#/components/schemas/EthBlockNum'
2340 - description: Last synchronized Etherum block. Compare with lastEthereumBlock to check the synchronization status of the node.
2341 - example: 3457437
2342 lastBatch:
2343 $ref: '#/components/schemas/Batch'
2344 currentSlot:
2345 allOf:
2346 - $ref: '#/components/schemas/SlotNum'
2347 - description: Slot where batches are currently being forged.
2348 - example: 2334
2349 nextForgers:
2350 $ref: '#/components/schemas/NextForgers'
2351 additionalProperties: false
2352 required:
2353 - lastEthereumBlock
2354 - lastSynchedBlock
2355 - lastBatch
2356 - currentSlot
2357 - nextForgers
2358 StateAuction:
2359 type: object
2360 description: Auction parameters.
2361 properties:
2362 ethereumBlockNum:
2363 $ref: '#/components/schemas/EthBlockNum'
2364 bootCoordinator:
2365 allOf:
2366 - $ref: '#/components/schemas/EthereumAddress'
2367 - description: Ethereum address of the boot coordinator.
2368 - example: "0x997dc4262BCDbf85190C01c996b4C06a461d2430"
2369 slotDeadline:
2370 type: integer
2371 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.
2372 example: 3
2373 closedAuctionSlots:
2374 type: integer
2375 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.
2376 example: 2
2377 openAuctionSlots:
2378 type: integer
2379 description: How many days in advance are auctions opened.
2380 defaultSlotSetBid:
2381 type: array
2382 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]`."
2383 items:
2384 type: integer
2385 example: [32,0,68,21,55,99]
2386 outbidding:
2387 type: number
2388 description: Minimum outbid over the previous one to consider it valid.
2389 example: 3.64
2390 donationAddress:
2391 allOf:
2392 - $ref: '#/components/schemas/EthereumAddress'
2393 - description: Ethereum address where the donations will go to.
2394 - example: "0x887dc4262BCDbf85190C01c996b4C06a461d2430"
2395 allocationRatio:
2396 type: array
2397 description: Percentage in which fees will be splitted between donations, governance and burning. The sum of the tree values should be 100.
2398 items:
2399 type: integer
2400 example: [80,10,10]
2401 additionalProperties: false
2402 required:
2403 - ethereumBlockNum
2404 - bootCoordinator
2405 - slotDeadline
2406 - closedAuctionSlots
2407 - openAuctionSlots
2408 - defaultSlotSetBid
2409 - outbidding
2410 - donationAddress
2411 - allocationRatio
2412 StateRollup:
2413 type: object
2414 description: Rollup parameters
2415 properties:
2416 ethereumBlockNum:
2417 $ref: '#/components/schemas/EthBlockNum'
2418 forgeL1L2BatchTimeout:
2419 type: integer
2420 description: Max ethereum blocks after the last L1-L2-batch, when exceeds the timeout only L1-L2-batch are allowed.
2421 example: 5
2422 feeAddToken:
2423 type: integer
2424 description: Fee to pay when registering tokens into the network.
2425 example: 5698
2426 withdrawalDelay:
2427 type: integer
2428 description: Withdraw delay in seconds
2429 example: 432000
2430 buckets:
2431 type: array
2432 description: List of buckets state
2433 items:
2434 type: object
2435 properties:
2436 ceilUSD:
2437 type: integer
2438 description: Max USD value
2439 example: 1000
2440 blockStamp:
2441 type: integer
2442 description: Last time a withdrawal was added ( or removed if the bucket was full)
2443 example: 4475934
2444 withdrawals:
2445 type: integer
2446 description: Available withdrawals of the bucket
2447 example: 4
2448 blockWithdrawalRate:
2449 type: integer
2450 description: Every `blockWithdrawalRate` blocks add 1 withdrawal
2451 example: 8
2452 maxWithdrawals:
2453 type: integer
2454 description: Max withdrawals the bucket can hold
2455 example: 4
2456 additionalProperties: false
2457 required:
2458 - ceilUSD
2459 - blockStamp
2460 - withdrawals
2461 - blockWithdrawalRate
2462 - maxWithdrawals
2463 additionalProperties: false
2464 required:
2465 - ethereumBlockNum
2466 - forgeL1L2BatchTimeout
2467 - feeAddToken
2468 - withdrawalDelay
2469 - buckets
2470 StateWithdrawDelayer:
2471 type: object
2472 description: Withdrawal delayer parameters
2473 properties:
2474 ethereumBlockNum:
2475 $ref: '#/components/schemas/EthBlockNum'
2476 hermezGovernanceDAOAddress:
2477 allOf:
2478 - $ref: '#/components/schemas/EthereumAddress'
2479 - description: Ethereum address of the governance DAO.
2480 - example: "0x667dc4262BCDbf85190C01c996b4C06a461d2430"
2481 whiteHackGroupAddress:
2482 allOf:
2483 - $ref: '#/components/schemas/EthereumAddress'
2484 - description: Ethereum Address that can claim the funds in an emergency when the maximum emergency mode time is exceeded.
2485 - example: "0x557dc4262BCDbf85190C01c996b4C06a461d2430"
2486 hermezKeeperAddress:
2487 allOf:
2488 - $ref: '#/components/schemas/EthereumAddress'
2489 - description: Ethereum Address that can enable emergency mode and modify the delay to make a withdrawal.
2490 - example: "0x557dc4262BCDbf85190C01c996b4C06a461d2430"
2491 withdrawalDelay:
2492 allOf:
2493 - $ref: '#/components/schemas/EthBlockNum'
2494 - description: The time that anyone needs to wait until a withdrawal of the funds is allowed, in seconds.
2495 - example: 539573849
2496 emergencyModeStartingTime:
2497 type: integer
2498 description: Second (since unix epoch) in which the emergency mode has been activated.
2499 example: 10
2500 emergencyMode:
2501 type: boolean
2502 description: Indicates if emergency mode has been activated.
2503 example: false
2504 additionalProperties: false
2505 required:
2506 - ethereumBlockNum
2507 - hermezGovernanceDAOAddress
2508 - whiteHackGroupAddress
2509 - hermezKeeperAddress
2510 - withdrawalDelay
2511 - emergencyModeStartingTime
2512 - emergencyMode
2513 StateMetrics:
2514 type: object
2515 description: Metrics of the network
2516 properties:
2517 transactionsPerBatch:
2518 type: number
2519 description: Average transactions per batch in the last 24 hours.
2520 example: 2002.7
2521 batchFrequency:
2522 type: number
2523 description: Average elapsed time between batches in the last 24 hours, in seconds.
2524 example: 8.9
2525 transactionsPerSecond:
2526 type: number
2527 description: Average transactions per second in the last 24 hours.
2528 example: 302.3
2529 totalAccounts:
2530 type: integer
2531 description: Number of created accounts.
2532 example: 90473
2533 totalBJJs:
2534 type: integer
2535 description: Number of different registered BJJs.
2536 example: 23067
2537 avgTransactionFee:
2538 type: number
2539 description: Average fee percentage paid for L2 transactions in the last 24 hours.
2540 example: 1.54
2541 additionalProperties: false
2542 required:
2543 - transactionsPerBatch
2544 - batchFrequency
2545 - transactionsPerSecond
2546 - totalAccounts
2547 - totalBJJs
2548 - avgTransactionFee
2549 PendingItems:
2550 type: integer
2551 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.
2552 example: 15
2553 Config:
2554 type: object
2555 description: Configuration parameters of the different smart contracts that power the Hermez network.
2556 properties:
2557 hermez:
2558 type: object
2559 description: Constant configuration of the Hermez smart contract.
2560 properties:
2561 publicConstants:
2562 type: object
2563 description: Public Hermez smart contract constants
2564 properties:
2565 tokenHEZ:
2566 allOf:
2567 - $ref: '#/components/schemas/EthereumAddress'
2568 - description: Ethereum address of the HEZ token.
2569 - example: "0x444dc4262BCDbf85190C01c996b4C06a461d2430"
2570 absoluteMaxL1L2BatchTimeout:
2571 type: integer
2572 description: L1L2 Batch Timeout
2573 example: 240
2574 verifiers:
2575 type: array
2576 description: List of verifiers struct
2577 items:
2578 type: object
2579 properties:
2580 maxTx:
2581 type: integer
2582 description: Maximum rollup transactions in a batch
2583 example: 512
2584 nlevels:
2585 type: integer
2586 description: Number of levels of the circuit
2587 example: 32
2588 required:
2589 - maxTx
2590 - nlevels
2591 additionalProperties: false
2592 hermezAuctionContract:
2593 allOf:
2594 - $ref: '#/components/schemas/EthereumAddress'
2595 - description: Ethereum address of the auction smart contract.
2596 - example: "0x111dc4262BCDbf85190C01c996b4C06a461d2430"
2597 hermezGovernanceDAOAddress:
2598 allOf:
2599 - $ref: '#/components/schemas/EthereumAddress'
2600 - description: Ethereum address of the governanceDAO.
2601 - example: "0x222dc4262BCDbf85190C01c996b4C06a461d2430"
2602 safetyAddress:
2603 allOf:
2604 - $ref: '#/components/schemas/EthereumAddress'
2605 - description: Ethereum address of the safety.
2606 - example: "0x333dc4262BCDbf85190C01c996b4C06a461d2430"
2607 withdrawDelayerContract:
2608 allOf:
2609 - $ref: '#/components/schemas/EthereumAddress'
2610 - description: Ethereum address of the withdraw delayer contracts.
2611 - example: "0x444dc4262BCDbf85190C01c996b4C06a461d2430"
2612 required:
2613 - tokenHEZ
2614 - absoluteMaxL1L2BatchTimeout
2615 - verifiers
2616 - hermezAuctionContract
2617 - hermezGovernanceDAOAddress
2618 - safetyAddress
2619 - withdrawDelayerContract
2620 additionalProperties: false
2621 maxFeeIdxCoordinator:
2622 type: integer
2623 description: is the maximum number of tokens the coordinator can use to collect fees.
2624 example: 64
2625 reservedIdx:
2626 type: integer
2627 description: First 256 indexes reserved, first user index will be the 256.
2628 example: 255
2629 exitIdx:
2630 type: integer
2631 description: Account index used to indicate that a transaction is an `exit` or `force exit`.
2632 example: 1
2633 limitLoadAmount:
2634 type: integer
2635 description: Maximum load amount (L1 to L2) allowed.
2636 example: 321
2637 limitL2TransferAmount:
2638 type: integer
2639 description: Maximum amount (L2 to L2) allowed.
2640 example: 837
2641 limitTokens:
2642 type: integer
2643 description: Maximum number of different tokens that can be registered in the network.
2644 example: 4294967295
2645 l1CoordinatorTotalBytes:
2646 type: integer
2647 description: Number of bytes that a L1 coordinator transaction has ([4 bytes] token + [32 bytes] babyjub + [65 bytes] compressedSignature).
2648 example: 101
2649 l1UserTotalBytes:
2650 type: integer
2651 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).
2652 example: 72
2653 maxL1UserTx:
2654 type: integer
2655 description: Maximum L1-user transactions allowed to be queued in a batch.
2656 example: 128
2657 maxL1Tx:
2658 type: integer
2659 description: Maximum L1 transactions allowed to be queued in a batch.
2660 example: 256
2661 inputSHAConstantBytes:
2662 type: integer
2663 description: Input SHA constant bytes
2664 example: 18542
2665 numBuckets:
2666 type: integer
2667 description: Number of buckets
2668 example: 5
2669 maxWithdrawalDelay:
2670 type: integer
2671 description: Maximum delay to withdraw tokens. Time is measured in seconds.
2672 example: 2 * 7 * 24 * 60 * 60
2673 exchangeMultiplier:
2674 type: integer
2675 description: exchange multiplier
2676 example: 1e14
2677 required:
2678 - publicConstants
2679 - reservedIdx
2680 - exitIdx
2681 - limitLoadAmount
2682 - limitL2TransferAmount
2683 - limitTokens
2684 - l1CoordinatorTotalBytes
2685 - l1UserTotalBytes
2686 - maxL1UserTx
2687 - maxL1Tx
2688 - inputSHAConstantBytes
2689 - numBuckets
2690 - maxWithdrawalDelay
2691 - exchangeMultiplier
2692 additionalProperties: false
2693 auction:
2694 type: object
2695 description: Constant configuration of the auction smart contract.
2696 properties:
2697 blocksPerSlot:
2698 type: integer
2699 description: Blocks per slot.
2700 initialMinimalBidding:
2701 type: integer
2702 description: Minimum bid when no one has bid yet.
2703 genesisBlockNum:
2704 allOf:
2705 - $ref: '#/components/schemas/EthBlockNum'
2706 - description: Ethereum block number in which the smart contract starts operating.
2707 tokenHEZ:
2708 allOf:
2709 - $ref: '#/components/schemas/EthereumAddress'
2710 - description: Ethereum address of the HEZ token.
2711 - example: "0x333dc4262BCDbf85190C01c996b4C06a461d2430"
2712 hermezRollup:
2713 allOf:
2714 - $ref: '#/components/schemas/EthereumAddress'
2715 - description: Ethereum address of the rollup smart contract.
2716 - example: "0x222dc4262BCDbf85190C01c996b4C06a461d2430"
2717 governanceAddress:
2718 allOf:
2719 - $ref: '#/components/schemas/EthereumAddress'
2720 - description: Ethereum address of the governance.
2721 - example: "0x444dc4262BCDbf85190C01c996b4C06a461d2430"
2722 required:
2723 - blocksPerSlot
2724 - initialMinimalBidding
2725 - genesisBlockNum
2726 - tokenHEZ
2727 - hermezRollup
2728 - governanceAddress
2729 additionalProperties: false
2730 withdrawalDelayer:
2731 type: object
2732 description: Constant configuration of the withdrawal delayer smart contract.
2733 properties:
2734 maxWithdrawalDelay:
2735 type: integer
2736 description: Maximum time delay in which the tokens can be locked in the contract. Time is measured in seconds.
2737 example: 200
2738 maxEmergencyModeTime:
2739 type: integer
2740 description: Maximum amount of time in which the contract can be in emergency mode. Time is measured in seconds.
2741 example: 2000
2742 hermezRollup:
2743 allOf:
2744 - $ref: '#/components/schemas/EthereumAddress'
2745 - description: Ethereum address of the rollup smart contract.
2746 - example: "0x222dc4262BCDbf85190C01c996b4C06a461d2430"
2747 required:
2748 - maxWithdrawalDelay
2749 - maxEmergencyModeTime
2750 - hermezRollup
2751 additionalProperties: false
2752 required:
2753 - hermez
2754 - auction
2755 - withdrawalDelayer
2756 additionalProperties: false
2757 Error:
2758 type: object
2759 description: Error response.
2760 properties:
2761 message:
2762 type: string
2763 Error400:
2764 allOf:
2765 - $ref: '#/components/schemas/Error'
2766 - example:
2767 message: Invalid signature.
2768 Error404:
2769 allOf:
2770 - $ref: '#/components/schemas/Error'
2771 - example:
2772 message: Item(s) not found.
2773 Error500:
2774 allOf:
2775 - $ref: '#/components/schemas/Error'
2776 - example:
2777 message: Database error.