-
Notifications
You must be signed in to change notification settings - Fork 23
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Update with changes from Edmund's review (#2510)
* Update with changes from Edmund's review * Fix typo * Split up misc endpoints into three sections * rename files * Update config and file name * update the config and fix build * Fix key in config * Add redirect * Add redirect --------- Co-authored-by: Steven Straatemans <[email protected]>
- Loading branch information
1 parent
2d6573b
commit 0ce02c0
Showing
10 changed files
with
428 additions
and
368 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
90 changes: 90 additions & 0 deletions
90
packages/apps/docs/src/docs/reference/chainweb/chainweb-block-updates.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,90 @@ | ||
| --- | ||
| title: Block updates endpoint | ||
| description: | ||
| Provides reference information for endpoint you can use to monitor a node for new blocks. | ||
| menu: Chainweb API | ||
| label: Block updates endpoint | ||
| order: 2 | ||
| layout: full | ||
| tags: ['chainweb', 'node api', 'chainweb api', 'api reference'] | ||
| --- | ||
|
|
||
| # Block updates endpoint | ||
|
|
||
| The block updates endpoint enables you to connect to a server-side event stream to be notified when new blocks are added to the blockchain. | ||
|
|
||
| ## Monitor events for new blocks | ||
|
|
||
| Use `GET http://{baseURL}/header/updates` to connect to a source of server events that emits a BlockHeader event for each new block header that is added to the chain database of the remote node. | ||
|
|
||
| The stream can contain blocks that might later become orphaned. | ||
| To address this potential issue, you should buffer events on the client side for the most recent block heights to allow for a desired confirmation depth to be reached. | ||
|
|
||
| You should note that the server might terminate this event stream from time to time. | ||
| It is up to the client to restart event streaming with a new request. | ||
|
|
||
| ### Responses | ||
|
|
||
| - **200 OK** indicates a successful requests and results in a stream of BlockHeader events. | ||
| Each event consists of an event property and a data property and are separated by empty lines. | ||
|
|
||
| #### Response header | ||
|
|
||
| The response header parameters are the same for all successful and unsuccessful Chainweb node requests. | ||
|
|
||
| | Parameter | Type | Description | ||
| | --------- | ---- | ----------- | ||
| | x-peer-addr | string | Specifies the host address and port number of the client as observed by the remote Chainweb node. The host address can be a domain name or an IP address in IPv4 or IPv6 format. For example: `"10.36.1.3:42988"`. | ||
| | x-server‑timestamp | integer >= 0 | Specifies the clock time of the remote Chainweb node using the UNIX epoch timestamp. For example: `1618597601`. | ||
| | x‑chainweb‑node‑version | string | Specifies the version of the remote Chainweb node. For example: `"2.23"`. | ||
|
|
||
| #### Response schema | ||
|
|
||
| If the request is successful, the response returns `text/event-stream` content with the following: | ||
|
|
||
| | Parameter | Type | Description | | ||
| | --------- | ---- | ----------- | ||
| | event | string | Specifies the type of event with the event property value of "BlockHeader". | ||
| | data | object | Specifies the data properties for the event. | ||
|
|
||
| ### Examples | ||
|
|
||
| You can send a request for block header updates from the Kadena main network like this: | ||
|
|
||
|
|
||
| ```Postman | ||
| GET http://api.chainweb.com/chainweb/0.0/mainnet01/header/updates | ||
| ``` | ||
|
|
||
| This request returns a stream of events with the BlockHeader event property and a data property: | ||
|
|
||
|  | ||
|
|
||
| If you expand the data property for an event, the event includes details similar to the folloiwng: | ||
|
|
||
| ```json | ||
| { | ||
| "header": { | ||
| "adjacents": { | ||
| "12": "_RU_P5XpRIFJK7-xhClDzBIwRD3LCkNzhNTi4M05uPY", | ||
| "14": "tzNb2_b_nWkGM9Qh3u4Pxna-NU2RYBYEuZE3cwu2m1k", | ||
| "3": "6auRG8JDj4S4IYMF8G-d47dkwVAfX8XmOOg6isofr_M" | ||
| }, | ||
| "chainId": 13, | ||
| "chainwebVersion": "mainnet01", | ||
| "creationTime": 1722966936274259, | ||
| "epochStart": 1722966541117672, | ||
| "featureFlags": 0, | ||
| "hash": "mb-Tn9AyDYuP5TgqaAlBu9VgR6eSZdWgKz9qtAGbrDA", | ||
| "height": 5016971, | ||
| "nonce": "5486220440094445593", | ||
| "parent": "ItXSuFMmiQ1tcbXHPD0YoVR-2oip8RAn0m20v09vsTc", | ||
| "payloadHash": "9v4k_U0IjxES-AwUSw_0PsqVBZ65msUKgZcGZO2cbY8", | ||
| "target": "mGwbbeZtKT0EAHYYZTgreADt6mLkayeBEQAAAAAAAAA", | ||
| "weight": "LJy-RUh3OhJ8VwEAAAAAAAAAAAAAAAAAAAAAAAAAAAA" | ||
| }, | ||
| "powHash": "0000000000000009d25e6c0bfe4f0c07b87af281929d275412c8be921fd9334b", | ||
| "target": "000000000000001181276be462eaed00782b3865187600043d296de66d1b6c98", | ||
| "txCount": 0 | ||
| } | ||
| ``` |
126 changes: 126 additions & 0 deletions
126
packages/apps/docs/src/docs/reference/chainweb/chainweb-db-backups.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,126 @@ | ||
| --- | ||
| title: Backup endpoints | ||
| description: | ||
| Provides reference information for the endpoints you can use to start or query the status of database backups for a node. | ||
| menu: Chainweb API | ||
| label: Backup endpoints | ||
| order: 2 | ||
| layout: full | ||
| tags: ['chainweb', 'node api', 'chainweb api', 'api reference'] | ||
| --- | ||
|
|
||
| # Backup endpoints | ||
|
|
||
| You can configure a Chainweb node to support database backup jobs. | ||
| If you enable the backup API for a node, you can use the backup endpoints to a start backup job and check the status of a previously started backup job. | ||
|
|
||
| ## Enable backups | ||
|
|
||
| The `/make-backup` and `/check-backup` endpoints are only valid if you enable the backup API for a node. | ||
| You can enable the backup API by starting the node with the `--enable-backup-api` and `--backup-directory` command-line options or by specifying the following configuration settings in the node configuration file: | ||
|
|
||
| ```yaml | ||
| backup: | ||
| api: | ||
| enabled: true | ||
| directory: path-to-backups-directory | ||
| ``` | ||
| ### Select a backup directory | ||
| If you enable the backup API, sending a request the `POST http://{baseURL}/make-backup` endpoint always backs up the RocksDB portion of the Chainweb database. | ||
|
|
||
| In most cases, you should locate the backup directory in the same partition as the active RocksDB database. | ||
| Storing RocksDB backups in the same partition as the active RocksDB database minimizes the space required and the time it takes to complete backups initially. | ||
| Over time—as the active database diverges from the backup copy—the space required will increase. | ||
| If you store the backup on another partition, the backup operation takes longer and the backup copy requires as much disk space as the active RocksDB database. | ||
|
|
||
| ### Back up the Pact database | ||
|
|
||
| Chainweb nodes have two separate databases. | ||
| One database—the RocksDB database—stores information about blocks and chains. | ||
| A second database—the Pact Sqlite database—stores information about smart contracts and state. | ||
|
|
||
| While backup jobs always back up the RocksDB database, backing up the Pact Sqlite database is optional. | ||
| If you include the `backupPact` parameter in your request, the backup job backs up both databases. | ||
| Backing up both databases takes much longer than only backing up the RockDB database. | ||
| In addition, Pact database backups always require as much space as the active Pact database. | ||
|
|
||
| ### Define a retention policy | ||
|
|
||
| Database backup jobs don't provide any type of automatic backup retention policy. | ||
| You should define your own policy and delete old backup copies, as appropriate. | ||
|
|
||
| ## Start a backup job | ||
|
|
||
| Use `POST http://{baseURL}/make-backup` to start a backup job for a Chainweb node. | ||
| Starting a backup job creates a UNIX timestamp identifier for the job. | ||
| You can then use the identifier to check the status of the job to determine if the job is still in progress or the backup has been completed. | ||
|
|
||
| If a backup job is already in progress, this endpoint returns the UNIX timestamp job identifier instead of starting a new backup job. | ||
|
|
||
|
|
||
| ### Query parameters | ||
|
|
||
| | Parameter | Description | ||
| | --------- | ----------- | ||
| | backupPact | Indicates that you want to back up both the RockDB database and the Pact database. This option requires additional disk space and increases the time required to complete the backup. | ||
|
|
||
| ### Responses | ||
|
|
||
| Requests to the `POST http://{baseURL}/make-backup` endpoint return the following response code: | ||
|
|
||
| - **200 OK** indicates that a backup job has been created. | ||
|
|
||
| #### Response header | ||
|
|
||
| The response header parameters are the same for all successful and unsuccessful Chainweb node requests. | ||
|
|
||
| | Parameter | Type | Description | ||
| | --------- | ---- | ----------- | ||
| | x-peer-addr | string | Specifies the host address and port number of the client as observed by the remote Chainweb node. The host address can be a domain name or an IP address in IPv4 or IPv6 format. For example: `"10.36.1.3:42988"`. | ||
| | x-server‑timestamp | integer >= 0 | Specifies the clock time of the remote Chainweb node using the UNIX epoch timestamp. For example: `1618597601`. | ||
| | x‑chainweb‑node‑version | string | Specifies the version of the remote Chainweb node. For example: `"2.23"`. | ||
|
|
||
| #### Response schema | ||
|
|
||
| The response returns `text/plain` content with the following information: | ||
|
|
||
| | Parameter | Type | Description | ||
| | --------- | ---- | ----------- | ||
| | backupId | string | Specifies the backup job identifier with a UNIX timestamp from the `a-zA-Z0-9_-` character set. | ||
|
|
||
| ## Check the status of a backup job | ||
|
|
||
| Use `GET http://{baseURL}/check-backup/{backupId}` to check the status of a backup job. | ||
|
|
||
| ### Path parameters | ||
|
|
||
| | Parameter | Type | Description | ||
| | --------- | ---- | ----------- | ||
| | backupId (required) | string | Specifies the backup job identifier with a UNIX timestamp from the `a-zA-Z0-9_-` character set. For example: 1648665437000 | ||
|
|
||
| ### Responses | ||
|
|
||
| Requests to the `GET http://{baseURL}/check-backup` endpoint can return the following response codes: | ||
|
|
||
| - **200 OK** indicates that a backup job with the specified identifier exists and returns its current status. | ||
| - **404 Not Found** indicates that there were no backup jobs matching the specified identifier. | ||
|
|
||
| #### Response header | ||
|
|
||
| The response header parameters are the same for all successful and unsuccessful Chainweb node requests. | ||
|
|
||
| | Parameter | Type | Description | ||
| | --------- | ---- | ----------- | ||
| | x-peer-addr | string | Specifies the host address and port number of the client as observed by the remote Chainweb node. The host address can be a domain name or an IP address in IPv4 or IPv6 format. For example: `"10.36.1.3:42988"`. | ||
| | x-server‑timestamp | integer >= 0 | Specifies the clock time of the remote Chainweb node using the UNIX epoch timestamp. For example: `1618597601`. | ||
| | x‑chainweb‑node‑version | string | Specifies the version of the remote Chainweb node. For example: `"2.23"`. | ||
|
|
||
| #### Response schema | ||
|
|
||
| The response returns `text/plain` content with the following information: | ||
|
|
||
| | Parameter | Type | Description | ||
| | --------- | ---- | ----------- | ||
| | status | string | Specifies the status of the backup job with the specified identifier. There are three possible status messages: `backup-done`, `backup-in-progress`, and `backup-failed`. |
8 changes: 4 additions & 4 deletions
8
...erence/chainweb/chainweb-service-block.md → ...reference/chainweb/chainweb-full-block.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.