Skip to content

Commit

Permalink
docs: Node operator doc fixes (#1771)
Browse files Browse the repository at this point in the history
* fix(docs): Replace "a IOTA" with "an IOTA"

* fix(docs): Typos and incorrect URLs in full node config

* fix(docs): Update staking numbers and fix style

* fix(nre): Fix typos, style and urls in node operator guide

* fix(docs): Fix data management typos and content

* fix(docs): Typos and style fixes in snapshots

* feat(devx): poc import config READMEs in wiki while keeping the READMEs valid

* fix(docs): Proofread node tools

* fix(docs): Rename tasks section to operation

* fix(docs): Proofread node monitoring

* fix(docs): Comment out TODO URLs

* fix(docs): dprint fmt

* refactor(docs): Pull validator tool into wiki as well

---------

Co-authored-by: Lucas Tortora <[email protected]>
Co-authored-by: Thoralf-M <[email protected]>
  • Loading branch information
3 people authored and bingyanglin committed Aug 19, 2024
1 parent daf854c commit 84f528a
Show file tree
Hide file tree
Showing 23 changed files with 203 additions and 686 deletions.
6 changes: 3 additions & 3 deletions docs/content/_snippets/staking-pool-reqs.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,6 @@ There are minimum staking requirements a validator must satisfy to become active

More precisely:

- A validator candidate must accrue at least 30M IOTA of stake before they can request to join the validator set.
- If an active validator’s stake falls below 20M IOTA, they have seven epochs of grace period to gain back the stake before being removed from the validator set.
- If an active validator’s stake falls below 15M IOTA, they are removed from the validator set at the end of the current epoch boundary. IOTA uses 24-hour epochs.
- A validator candidate must accrue at least 2M IOTA of stake before they can request to join the validator set.
- If an active validator’s stake falls below 1.5M IOTA, they have seven epochs of grace period to gain back the stake before being removed from the validator set.
- If an active validator’s stake falls below 1M IOTA, they are removed from the validator set at the end of the current epoch boundary. IOTA uses 24-hour epochs.
2 changes: 1 addition & 1 deletion docs/content/operator/archives.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: IOTA Archives
description: The archive is a historical record of all transactions on IOTA. Enable archiving on your Full nodes as a best practice.
---

A IOTA archive is a history of all transaction data on IOTA, trailing behind the latest checkpoint by 10 minutes. As a IOTA node operator, you can write this history to an object store like S3, GCS, or similar for safe keeping. Saving this archive data is considered a best practice because IOTA prunes transactions on Full nodes to remove historical transactions and their effects. Peer nodes, for example, might not catch up with all transactions and effects through synchronization if they lag behind the current epoch by more than the latest few epochs. Instead of relying on synchronization, peer nodes can fallback to downloading this information from an archive.
An IOTA archive is a history of all transaction data on IOTA, trailing behind the latest checkpoint by 10 minutes. As an IOTA node operator, you can write this history to an object store like S3, GCS, or similar for safe keeping. Saving this archive data is considered a best practice because IOTA prunes transactions on Full nodes to remove historical transactions and their effects. Peer nodes, for example, might not catch up with all transactions and effects through synchronization if they lag behind the current epoch by more than the latest few epochs. Instead of relying on synchronization, peer nodes can fallback to downloading this information from an archive.

IOTA Archival nodes (Full nodes that write to an archive) don't store historical state on local storage and don't help query historical data. They serve the purpose of enabling peer nodes to catch up to the latest checkpoint and are useful for auditing and verifying the complete history of all transactions on the network.

Expand Down
20 changes: 10 additions & 10 deletions docs/content/operator/data-management.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -3,26 +3,26 @@ title: Data Management
description: A high-level description of data management on the IOTA network that you can use to optimize your IOTA Full node configuration.
---

Managing the data on your IOTA Full node is critical to ensuring a healthy IOTA network. This topic provides a high-level description of data management on IOTA Full nodes that you can use to optimize your Full node configuration. For more information about IOTA Full nodes, such as pruning policies and archival settings, see [Run a IOTA Full Node](iota-full-node.mdx).
Managing the data on your IOTA Full node is critical to ensuring a healthy IOTA network. This topic provides a high-level description of data management on IOTA Full nodes that you can use to optimize your Full node configuration. For more information about IOTA Full nodes, such as pruning policies and archival settings, see [Run an IOTA Full Node](iota-full-node.mdx).

## Basic IOTA Full node functionality

The minimal version of a IOTA Full node executes all of the transactions IOTA validators commit. IOTA Full nodes also orchestrate the submitting of new transactions to the system:
The minimal version of an IOTA Full node executes all of the transactions IOTA validators commit. IOTA Full nodes also orchestrate the submitting of new transactions to the system:

![Basic IOTA Full node functionality](images/fn-basic-functionality.png "A diagram that shows the operations of a basic IOTA Full node.")

The preceding image shows how data flows through a Full node:

1. **`State sync` protocol:** A IOTA Full node performs the following to achieve state synchronization:
1. **`State sync` protocol:** An IOTA Full node performs the following to achieve state synchronization:
- Retrieves the information about the committed checkpoints via the p2p gossip-like protocol
- Executes the transactions locally to verify that effects match the effects certified by the quorum of the validators
- Updates the local state with the latest object values accordingly.
2. **RPCs:** A IOTA Full node exposes IOTA RPC endpoints for querying the latest state of the system, including both the latest state metadata (such as, `iota_getProtocolConfig`), and the latest state object data (`iota_getObject)`.
2. **RPCs:** An IOTA Full node exposes IOTA RPC endpoints for querying the latest state of the system, including both the latest state metadata (such as, `iota_getProtocolConfig`), and the latest state object data (`iota_getObject)`.
3. **Transaction submission:** Each IOTA Full node orchestrates transaction submission to the quorum of the IOTA Validators, and, optionally if configured, locally executes the finalized transactions (called fast path execution), which circumvents the wait for checkpoint synchronization.

## IOTA Full node Data and RPC types

A IOTA Full Node stores multiple categories of data in its permanent store.
An IOTA Full Node stores multiple categories of data in its permanent store.

:::info

Expand All @@ -32,15 +32,15 @@ The per-epoch IOTA store is beyond the scope of this topic. IOTA uses the per-ep

IOTA Full nodes store the following types of data:

1. **Transactions with associated effects and events:** IOTA uses a unique transaction digest to retrieve information about a transaction, including its effects and emitted events. IOTA Full nodes don't require the historic transaction information for basic Full node operations. To conserve drive space, you can enable pruning to remove this historical data.
1. **Transactions with associated effects and events:** IOTA uses a unique transaction digest to retrieve information about a transaction, including its effects and emitted events. IOTA Full nodes don't require the historic transaction information for basic Full node operations. To conserve disk space, you can enable pruning to remove this historical data.
2. **Checkpoints:** IOTA groups committed transactions in checkpoints, and then uses those checkpoints to achieve state synchronization. Checkpoints keep transaction digests that contain additional integrity metadata.
IOTA Full nodes don't require data from checkpoints to execute and submit transactions, so you can configure pruning for this data as well.
3. **Objects:** Transactions that mutate objects create new object versions. Each object has a unique pair of `(objectId, version)` used to identify the object. IOTA Full nodes don't require historic object versions to execute and submit transactions, so you can configure your Full node to also prune this data.
4. **Indexing information:** A Full node default configuration is to post-process the committed transactions: it indexes the committed information to enable efficient aggregation and filtering queries. For example, the indexing can be useful for retrieving all the historic transactions of a given sender, or finding all the objects owned by an address.

IOTA Full nodes support more than 40 RPC types that includes the following categories:

* **General metadata**, such as `iota_getProtocolConfig` and `iota_getChainIdentier`. These requests don't depend on additional indexing and don't require historic data to process.
* **General metadata**, such as `iota_getProtocolConfig` and `iota_getChainIdentifier`. These requests don't depend on additional indexing and don't require historic data to process.
* **Direct lookups**, such as `iota_getObject`, `iota_getEvents`. These requests don't depend on additional indexing, but require historic data in some cases, such as `iota_tryGetPastObject` and `iota_getTransactionBlock`.
* **Accumulation and filtering queries**,such as `iotax_getOwnedObjects` and `iotax_getCoins`. These requests depend on additional indexing, and require historic data in some cases, such as `iotax_queryTransactionBlocks`.

Expand All @@ -52,19 +52,19 @@ IOTA plans to migrate the RPC endpoints that require additional indexing away fr

## IOTA Archival data

A IOTA archive instance stores the full IOTA transaction history since genesis in a database agnostic format. This includes information about transactions (with client authentication), effects, events, and checkpoints. As such, archival storage can be used for data auditing and for replaying historic transactions.
An IOTA archive instance stores the full IOTA transaction history since genesis in a database agnostic format. This includes information about transactions (with client authentication), effects, events, and checkpoints. As such, archival storage can be used for data auditing and for replaying historic transactions.

:::info

The current archival storage format doesn't include historic object versions.

:::

As a Full node operator, you can [enable archival fallback for your Full node](./archives.mdx#set-up-archival-fallback) by specifying the URL to upload archival data. Currently, the IOTA Foundation manages a IOTA archive and stores it in AWS S3. To ensure a healthy network, we encourage the IOTA community to set up additional archives to ensure archival data availability across the network. In a typical configuration, an archive trails behind the latest checkpoint by approximately 10 minutes.
As a Full node operator, you can [enable archival fallback for your Full node](./archives.mdx#set-up-archival-fallback) by specifying the URL to upload archival data. To ensure a healthy network, we encourage the IOTA community to set up additional archives to ensure archival data availability across the network. In a typical configuration, an archive trails behind the latest checkpoint by approximately 10 minutes.

A Full Node that starts from scratch can replay (and thus re-verify) transactions that occurred since IOTA genesis from the given archive via [configuring Archival Fallback](./archives.mdx#set-up-archival-fallback) in the `fullnode.yaml` configuration file to point to the S3 bucket that stores the archive.

A IOTA Full node that fails to retrieve checkpoints from its peers via state sync protocol falls back to downloading the missing checkpoints from its pre-configured archive. This fallback enables a Full node to catch up with the rest of the system regardless of the pruning policies of its peers.
An IOTA Full node that fails to retrieve checkpoints from its peers via state sync protocol falls back to downloading the missing checkpoints from its pre-configured archive. This fallback enables a Full node to catch up with the rest of the system regardless of the pruning policies of its peers.

## IOTA Full node pruning policies

Expand Down
Loading

0 comments on commit 84f528a

Please sign in to comment.