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