diff --git a/docs/build/apis/sidebars.js b/docs/build/apis/sidebars.js index f2eb2b5a0c0..4d133d52e71 100644 --- a/docs/build/apis/sidebars.js +++ b/docs/build/apis/sidebars.js @@ -48,6 +48,12 @@ const categories = [ collapsed: true, items: './docs/core/v2/sidebar', }, + { + type: 'category', + label: 'V3', + collapsed: true, + items: './docs/core/v3/sidebar', + }, ], }, { diff --git a/docs/maintain/iota-core/2.0/docs/getting_started/getting_started.md b/docs/maintain/iota-core/2.0/docs/getting_started/getting_started.md new file mode 100644 index 00000000000..f7eb4895f9c --- /dev/null +++ b/docs/maintain/iota-core/2.0/docs/getting_started/getting_started.md @@ -0,0 +1,56 @@ +--- +description: Getting started with the recommended requirements and installation links. +image: /img/icons/iota/iota_core.png +tags: + - IOTA Node + - IOTA-Core Node + - Linux + - macOS + - Windows + - Docker + - reference + - Requirements +--- + +# Getting Started + +Running a node is an efficient way to use IOTA. By doing so, you have direct access to the Tangle instead of connecting +to and trusting someone else's node. Additionally, you help the network to become more distributed and resilient. + +## Recommended Requirements + +To handle a potentially high rate of blocks per second, nodes need enough computational power to run reliably and +should have the following minimum specs: + +- 4 cores or 4 vCPU. +- 8 GB RAM. +- SSD storage. +- A public IP address. + +The amount of storage you will need will depend on whether and how often you plan on _pruning_ old data from your local +database. + +IOTA-Core exposes different functionality on different ports: + +- `15600 TCP` - Gossip protocol port. +- `14626 UDP` - Autopeering port (optional). +- `14265 TCP` - REST HTTP API port (optional). + +These ports are essential for flawless node operation. The REST HTTP API port is optional and is only needed if +you want to offer access to your node's API. You can customize all ports using +the [`config.json`](../how_tos/post_installation.md) file. + +## Operating System + +The IOTA-Core software is written in Go and can be deployed on all major platforms. +The [recommended setup](../how_tos/using_docker.md) uses Docker to run IOTA-Core together with some INX extensions +secured behind a [Traefik](https://traefik.io) SSL reverse proxy. + +## Configuration + +IOTA-Core uses two JSON configuration files that you can tweak based on your deployment requirements: + +- `config.json` - Includes all core configuration parameters. +- `peering.json` - Includes connection details to node neighbors (peers). + +You can read more about the configuration in the [post installation](../how_tos/post_installation.md) article. diff --git a/docs/maintain/iota-core/2.0/docs/how_tos/post_installation.md b/docs/maintain/iota-core/2.0/docs/how_tos/post_installation.md new file mode 100644 index 00000000000..54bdb0d5fc4 --- /dev/null +++ b/docs/maintain/iota-core/2.0/docs/how_tos/post_installation.md @@ -0,0 +1,81 @@ +--- +description: Introducing the IOTA-Core node configuration files and their settings. +image: /img/icons/iota/iota_core.png +tags: + - IOTA Node + - IOTA-Core Node + - Configuration + - REST API + - Dashboard + - how to +--- + +# Post-installation + +Once you have deployed IOTA-core, you can set all the parameters using configuration files. + +## Configuration Files + +The most important configuration files are: + +- `config.json` - Includes all configuration flags and their values. +- `peering.json` - Includes all connection details to your static peers (neighbors). + +## Default Configuration + +There are default configuration files available that you can use: + +- `config_testnet.json` - Includes the default values required to join the Testnet. +- `config_defaults.json` - Includes all default parameters used by IOTA-core. You can use this file as a reference when customizing your `config.json` + +You can pick one of these files and use it as your `config.json` to join the configured network. + +Please see the [`config.json`](../references/configuration.md) and `peering.json` articles for more information about the contents of the configuration files. + +## Configuring HTTP REST API + +One of the tasks the node is responsible for is exposing [API](../references/api_reference.md) to clients that would like to interact with the IOTA network, such as crypto wallets, exchanges, IoT devices, etc. + +By default, IOTA-Core will expose the [Core REST API v3](../references/api_reference.md) on port `14265`. +If you use the [recommended setup](using_docker.md) the API will be exposed on the default HTTPS port (`443`) and secured using an SSL certificate. + +Since offering the HTTP REST API to the public can consume your node's resources, there are options to restrict which routes can be called and other request limitations: + +### Routes + +- `restAPI.publicRoutes` defines which routes can be called without JWT authorization. +- `restAPI.protectedRoutes` defines which routes require JWT authorization. +- All other routes will not be exposed. + +### JWT Auth + +To generate a JWT-token to be used with the protected routes you can run: + +```sh +./iota-core tool jwt-api --databasePath --salt +``` + +If you are running our [recommended setup](using_docker.md) then see [here](using_docker.md#tools). + +### Proof-of-Work + +If you are concerned with resource consumption, consider turning off `restAPI.pow.enabled`. +This way, the clients must perform proof of work locally before submitting a block for broadcast. +If you would like to offer proof of work to clients, consider increasing the `restAPI.pow.workerCount` to provide a faster block submission experience. + +### Reverse Proxy + +We recommend that you provide your HTTP REST API behind a reverse proxy, such as [HAProxy](http://www.haproxy.org/), [Traefik](https://traefik.io/), [Nginx](https://www.nginx.com/), or [Apache](https://www.apache.org/) configured with TLS. +When using our [recommended setup](using_docker.md) this is done for you automatically. + +### Other + +You can find all the HTTP REST API related options in the [`config.json` reference](../references/configuration.md#restapi) + +## Update + +You can update IOTA-Core to the latest stable version with no breaking updates by running the following command: + +```sh +docker compose down && docker compose pull && docker compose up -d +``` diff --git a/docs/maintain/iota-core/2.0/docs/how_tos/using_docker.md b/docs/maintain/iota-core/2.0/docs/how_tos/using_docker.md new file mode 100644 index 00000000000..3b49bd6e7a0 --- /dev/null +++ b/docs/maintain/iota-core/2.0/docs/how_tos/using_docker.md @@ -0,0 +1,215 @@ +--- +description: Learn how to install and run a iota-CORE node using Docker. +image: /img/icons/iota/iota_core.png +tags: + - IOTA Node + - IOTA-Core Node + - Docker + - Install + - Run + - macOS + - Windows + - Linux + - how to +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import LinuxCommands from '@site/docs/_admonitions/_linux-commands.md'; + +# Install IOTA-Core using Docker + +This article guides the recommended setup to run an IOTA-Core node. +It includes everything required to set up a public node accessible by wallets and applications: + +- [IOTA-core](https://github.com/iotaledger/iota-core) +- [Traefik](https://traefik.io) - Reverse proxy using SSL certificates to secure access to the node API and dashboard. +- [Prometheus](https://prometheus.io) - Metrics scraper configured to collect all metrics from IOTA-Core and INX extensions. +- [Grafana](https://grafana.com) - Data visualizer that can be used to display the metrics collected by Prometheus. +- [inx-dashboard](https://github.com/iotaledger/inx-dashboard) - Node dashboard. +- [inx-indexer](https://github.com/iotaledger/inx-indexer) - Indexer extension for wallets and applications. +- [inx-mqtt](https://github.com/iotaledger/inx-mqtt) - MQTT extension providing the Event API. + +## Requirements + +1. A recent release of Docker enterprise or community edition. Avoid using the Docker version shipped with your OS since these are mostly out of date. You can find installation instructions in the [official Docker documentation](https://docs.docker.com/engine/install/). +2. [Docker Compose CLI plugin](https://docs.docker.com/compose/install/linux/). +3. A registered domain name pointing to the public IP address of your server. _(optional if not using HTTPS)_ +4. Opening up the following ports in your server's firewall: + +- `15600 TCP` - Used for IOTA-Core gossip. +- `80 TCP` - Used for HTTP. _(can be changed, see below)_ +- `443 TCP` - Used for HTTPS. _(optional if not using HTTPS)_ + +5. [curl](https://curl.se/). + +## Download the latest release + + + +Once you have completed all the installation [requirements](#requirements), you can download one of the latest releases, depending on the network you want to join, by running the following command: + +```sh +mkdir node-docker-setup && cd node-docker-setup && curl -L https://node-docker-setup.iota.org/iota2-testnet | tar -zx +``` + +## Prepare + + + +### 1. Generate dashboard credentials + +To access your IOTA-Core dashboard, you need to configure credentials. +Run the following command to generate a password hash and salt for the dashboard: + +```sh +docker compose run iota-core tools pwd-hash +``` + +Copy the output of the command for the next step. + +### 2. Setup your Environment + +Copy the `env_template` file to `.env` using the following command: + +```sh +cp env_template .env +``` + +Modify the `.env` file to fit your needs with the editor of your choice. +We are using `nano` in the following example: + +```sh +nano .env +``` + +Follow the instructions provided in the file. +With `nano`, you can save your changes and exit the editor using `CTRL+O` and `CTRL+X`. + +:::note + +You can configure your node to either use HTTP or HTTPS. For publicly exposed nodes, we heavily recommend using HTTPS. + +::: + +```sh reference +https://github.com/iotaledger/node-docker-setup/blob/feat/iota-core/testnet_iota-2.0/env_template +``` + +### 3. Setup neighbors + +Add your IOTA-Core neighbor addresses to the `peering.json` file. + +:::note + +This step is recommended but optional if you are using autopeering. + +::: + +### 4. Create the `data` folder + +All files used by IOTA-Core, the INX extensions, Traefik & co will be stored in a directory called `data`. +Docker image runs under user with user id `65532` and group id `65532`, so this directory needs to have the correct permissions to be accessed by the containers. +To create this directory with correct permissions, run the contained script: + +```sh +./prepare_docker.sh +``` + +## Run + +### Starting the node + +You can start IOTA-Core node and INX extensions by running: + +```sh +docker compose up -d +``` + +- `-d` Instructs Docker to start the containers in the background. + +#### HTTPS + +After starting the node, you will be able to access your services at the following endpoints: + +- API: `https://node.your-domain.com/api/routes` +- IOTA-Core Dashboard: `https://node.your-domain.com/dashboard` +- Grafana: `https://node.your-domain.com/grafana` _(optional if using "monitoring" profile)_ + +:::warning + +After starting your node for the first time, please change the default grafana credentials. +**User**: `admin` +**Password**: `admin` + +::: + +You can configure your wallet software to use `https://node.your-domain.com`. + +#### HTTP + +After starting the node, you will be able to access your services at the following endpoints: + +- API: `http://localhost/api/routes` +- IOTA-Core Dashboard: `http://localhost/dashboard` +- Grafana: `http://localhost/grafana` _(optional if using "monitoring" profile)_ + +:::note + +If you changed the default `HTTP_PORT` value, you must add the port to the URLs. + +::: + +You can configure your wallet software to use `http://localhost`. + +### Displaying Log Output + +You can display IOTA-Core logs by running: + +```sh +docker compose logs -f iota-core +``` + +- `-f` + Instructs Docker to continue displaying the log to `stdout` until CTRL+C is pressed. + +### Stopping the node + +You can stop the IOTA-Core node and INX extensions by running: + +```sh +docker compose down +``` + +### Tools + +To access IOTA-Core tools, you can use the following command: + +```sh +docker compose run iota-core tool +``` + +To see the list of tools included run the following: + +```sh +docker compose run iota-core tool -h +``` + +## JWT Auth + +To generate a JWT token to be used to access protected routes, you can run the following: + +```sh +docker compose run iota-core tool jwt-api --databasePath data/p2pstore +``` + +- If you changed the `restAPI.jwtAuth.salt` value in the `config.json`, then you need to pass that value as a parameter as `--salt `. + +## INX + +This setup includes the INX extensions listed at the beginning of this guide. +If you want to disable certain extensions, you can comment out the different services in the `docker-compose.yml` file and restart the node. + +# More Information + +You can find more information in the [GitHub repository](https://github.com/iotaledger/node-docker-setup) diff --git a/docs/maintain/iota-core/2.0/docs/how_tos/validator_setup.md b/docs/maintain/iota-core/2.0/docs/how_tos/validator_setup.md new file mode 100644 index 00000000000..2aa71a1c8f1 --- /dev/null +++ b/docs/maintain/iota-core/2.0/docs/how_tos/validator_setup.md @@ -0,0 +1,359 @@ +--- +description: Learn how to become a validator. +image: /img/icons/iota/iota_core.png +tags: + - IOTA Node + - IOTA-Core Node + - Docker + - Install + - Run + - Validator + - Staking + - macOS + - Windows + - Linux + - how to +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import LinuxCommands from '@site/docs/_admonitions/_linux-commands.md'; + +# Validator Setup Guide + +Validators secure the network by issuing validation blocks and receive Mana as a reward. To become a validator, you need +to create an account that can issue blocks, and the account needs to stake tokens. This guide explains how to create the +account and configure the validator plugin of the docker setup. +The validator plugin will then try to make the account a validator by issuing a candidacy announcement to the network. +The validator plugin will start issuing validation blocks if selected for the committee. + +:::info + +Running a validator implies [running a full-node setup](using_docker.md). + +::: + +Throughout the guide, we will use the CLI wallet from the iota-SDK and the [node docker setup](./using_docker.md). + +:::tip notation + +This guide uses the following notation. If `Public Key` has a value of `0xff`, then running the +command `echo {Public Key}` means replacing the variable `{Public Key}` with its value, i.e., running the +command `echo 0xff`. + +::: + +## Set Up the CLI Wallet + +### 1a. Downlaod the latest Version + +You can download the latest release of the CLI Wallet from the following link: +https://github.com/iotaledger/iota-sdk/releases/tag/cli-wallet-v2.0.0-beta.2 + +After downloading, copy the binary to your current directory. + +### 1b. Build From Source + +:::info Pre-build Release + +If you already downloaded the pre-build release version, you can skip this section and continue with [Connect to a Node](#2-connect-to-a-node) + +::: + +Please follow the instructions to build the CLI Wallet from source: + +#### 1. Clone the Repository + +You can clone the repository by running the following command: + +```bash +git clone -b 2.0 https://github.com/iotaledger/iota-sdk +``` + +#### 2. Build + +After you have downloaded the source code, you can build it by changing the current directory to `iota-sdk/cli` and +running the following command: + +```bash +cargo build --release +``` + +#### 3. (optional) Copy the Wallet + +For ease of access, you can copy the Wallet that you built into your current directory or even add it to your $PATH: + +```bash +cp ../target/release/wallet wallet +``` + +### 2. Connect to a Node + +You can use the following command to connect your wallet to a Testnet node — alternatively, your node’s URL: + +```bash +./wallet init --node-url "https://api.nova-testnet.iotaledger.net" +``` + +### 3. Configure Your Wallet + +Once you’ve connected your wallet to a node, you must answer the following setup questions: + +:::info Not Mentioned Questions + +The setup questions that aren't asked here you can configure however you prefer, there config doesn't matter for this how-to. + +::: + +#### Select secret manager. + +Unless you have a ledger, select Stronghold. + +#### Do you want to set the address of the new wallet? + +No. + +#### Select BIP path + +Select `Custom` as the BIP path and type `1/0/0/0`. + +#### Do you want to set an alias for the new wallet? + +Yes. + +Then, enter a wallet alias of your choice. + +## Create an Account + +:::tip Connect to a Node + +The following sections assume you have already set up your [CLI Wallet](#set-up-the-cli-wallet), +and [connected it to a node](#2-connect-to-a-node). + +::: + +### 1. Create an Implicit Account + +You can create an implicit account by running the following command: + +``` +implicit-account-creation-address +``` + +Please copy the implicit address returned by the command. + +### 2. Fund Your Account + +You can enter the address at the [Testnet Faucet](https://faucet.nova-testnet.iotaledger.net/) to fund your account or run the +following command + +```bash +faucet {implicit-address} --url https://faucet.nova-testnet.iotaledger.net/api/enqueue +``` + +### 3. Sync With the Node + +After creating and funding your implicit account, you should use the `sync` and `implicit-accounts` functionalities to +retrieve the implicit account creation output. + +```bash +sync +implicit-accounts +``` + +You should run this until the BIC changes from `None` to `Some(0)`, then copy the `Output Id`. + +### 4. Transition the Account + +You can transition your account by running the following command: + +```bash +implicit-account-transition {Output Id} +``` + +### 5. Sync With the Node + +You can now `sync` with the node and run the `accounts` command to ensure an account is displayed with Block Issuance +Credit of `0`, which is the case if it displays `Some(0)` instead of `None`. + +```bash +sync +accounts +``` + +You now have a block issuer account and can send transactions as you wish if you have enough Mana available. + +## Adding a Block Issuer Key + +### 1. Generate an Ed25519 Keypair + +In the directory of the [node docker setup](./using_docker.md), you can run the following command to generate an +Ed25519 keypair: + +```bash +docker compose run iota-core tools ed25519-key +``` + +Please take note of the `ed25519 public key` and `ed25519 private key` and add a `0x` at the beginning of the public +key. + +### 2. Select a Validator Account + +You can now return to the wallet and `sync` it. Afterward, you should run the `accounts` command to retrieve the list of +available accounts and choose an account you want to use as a validator to issue validation block. Please take note of +its `Account ID` and `Account Address`. + +```bash +sync +accounts +``` + +### 3. Add the Account as a Block Issuer + +You can add the account as a block issuer using the following command: + +:::note + +The public key needs to have the `0x` prefix. + +::: + +```bash +add-block-issuer-key {Account ID} {ed25519 public key} +``` + +### 4. Verify + +You can verify you successfully added the key by running the `sync` and `accounts` commands. You should then copy +the `Output ID` of the account and run the `output {Output ID}` command. + +```bash +sync +account +output {Output ID} +``` + +You can find the `block_issuer_keys` list in the `features` section of the retrieved output. It should show two entries +that look like these but with different values: + +```plaintext +block_issuer_keys: BlockIssuerKeys( + [ + 0x16cbbea33ebcf2e17528737ee64b7b8290fe5c5b0d3c60a05a05bff3d2517b10, + 0x1a6709248bd6f06b103e0b3173c16c69d9a457d447409a6efc9612ffb64da964, + ], +``` + +## Start Staking + +### 1. Sync With the Node + +To start staking, you first need to run the `sync` and `accounts` commands and take note of the `Account ID` of the +account you want to use as a validator. + +```bash +sync +account +``` + +### 2. Decide Your Stake Amount + +Next, you should run the `output {Output ID}` command and take note of the `amount`. This is the highest possible amount +you can stake. Decide how much you want to stake. The `Stake Amount` can be anything between `1` and the +displayed `amount`. + +```bash +output {Output ID} +``` + +:::tip + +The higher your `Stake Amount`, the more likely you will be selected for the validator committee, so +setting `Stake Amount = amount` is preferred. + +::: + +### 3. Decide on a `Fixed Cost` + +This value is not particularly important for the Testnet. A recommended value is anywhere between 1 and 10. + +### 4. Begin Staking + +You can use the following command to start staking: + +```sh +begin-staking {Account ID} {Stake Amount} {Fixed Cost} +``` + +You can verify you successfully started staking by running the `sync` and `accounts` commands, copying the `Output ID` of the account, and then running `output {Output ID}`. You should be able to find the `StakingFeature` within the `features` section. It should show the `Stake Amount` and `Fixed Cost` you just entered. It should look like this, but with the values you entered: + +``` + +StakingFeature { +staked_amount: 1000000000, +fixed_cost: 1, +... + +``` + +The account is now registered as a validator. Next, you must set up the infrastructure to issue validation blocks to secure the network. + +## Prepare the Validator Plugin + +Running a validator requires running a full IOTA-Core node. You can follow the steps outlined in the [how to install using Docker guide](./using_docker.md) to setup the node. + +Follow the next steps after successfully setting up the node or while setting it up at your choice. + +### 1. Update the `.env` File + +You must modify the `.env` file in the following ways: + +1. Uncomment the `COMPOSE_PROFILES` line below the validator service. +2. Set the `Account Address` from earlier as the `VALIDATOR_ACCOUNT_ADDR`. +3. Set the `ed25519 private key` from earlier as the `VALIDATOR_PRV_KEY` (**with no** 0x prefix). + +### 2. Allot Mana to the Account + +The selected account needs Mana to issue candidacy announcements to the network. The Mana must be _allotted_ to the account. You can do this using the `allot-mana` command in the CLI wallet or the developer tools in Firefly. In the CLI Wallet, first check how much Mana can be allotted using `sync`, which shows you a `ManaBalance`: + +``` +ManaBalance { + total: DecayedMana { + stored: 1861687, + potential: 19380254, + }, + available: DecayedMana { + stored: 1861687, + potential: 19380254, + }, + rewards: 0, +}, +``` + +Set `Mana` as `stored + potential` from the `available` section. + +Now we allot the Mana to our account. If you happen to have multiple accounts, you also need to specify the ID of the account that will be used as the validator account. + +```bash +allot-mana {Mana} +``` + +### 3. Verify the `inx-validator` + +When you start the docker containers, an `inx-validator` container should also start. You can check the logs to see if +everything is working with the following command: + +```bash +docker logs -f inx-validator +``` + +If the logs don't show any errors, you should be good to go. The network will select you as a validator if your stake is +high enough. You can check the stake requirements as follows: The total pool stake, which consists of +your `Stake Amount` and all the stake that is delegated to your account, must be greater than the _Pool Stake_ of the +last entry in the [validator list](https://explorer.iota.org/iota2-testnet/validators/). Note that this list +might change every epoch, so the stake requirements might also change. + +You can check your _Total pool stake_ by taking the `Account Address`, opening the following URL, and checking +the `Validation` tab: + +`https://explorer.iota.org/iota2-testnet/addr/{Account Address}` diff --git a/docs/maintain/iota-core/2.0/docs/references/api_reference.md b/docs/maintain/iota-core/2.0/docs/references/api_reference.md new file mode 100644 index 00000000000..24c8f7b90e2 --- /dev/null +++ b/docs/maintain/iota-core/2.0/docs/references/api_reference.md @@ -0,0 +1,16 @@ +--- +description: Links to the REST API reference and the Node event API reference. +image: /img/icons/iota/iota_core.png +tags: + - IOTA Node + - IOTA-Core Node + - REST API + - API + - Reference +--- + +# API Reference + +You can find specifications of the APIs exposed by in the links below: + +- [Core REST API v3](/apis/core/v3/iota-core-rest-api) diff --git a/docs/maintain/iota-core/2.0/docs/references/configuration.md b/docs/maintain/iota-core/2.0/docs/references/configuration.md new file mode 100755 index 00000000000..490cc9a3725 --- /dev/null +++ b/docs/maintain/iota-core/2.0/docs/references/configuration.md @@ -0,0 +1,460 @@ +--- +# !!! DO NOT MODIFY !!! +# This file is auto-generated by the gendoc tool based on the source code of the app. +description: This section describes the configuration parameters and their types for your IOTA core node. +keywords: + - IOTA Node + - Configuration + - JSON + - Customize + - Config + - reference +--- +# Configuration + +The IOTA core node uses a JSON standard format as a config file. If you are unsure about JSON syntax, you can find more information in the [official JSON specs](https://www.json.org). + +You can change the path of the config file by using the `-c` or `--config` argument while executing `iota-core` executable. + +For example: +```bash +iota-core -c config_example.json +``` + +You can always get the most up-to-date description of the config parameters by running: + +```bash +iota-core -h --full +``` + +## 1. Application + +| Name | Description | Type | Default value | +| ------------------------- | ------------------------------------------------------ | ------- | ------------- | +| checkForUpdates | Whether to check for updates of the application or not | boolean | true | +| [shutdown](#app_shutdown) | Configuration for shutdown | object | | + +### Shutdown + +| Name | Description | Type | Default value | +| ------------------------ | ------------------------------------------------------------------------------------------------------ | ------ | ------------- | +| stopGracePeriod | The maximum time to wait for background processes to finish during shutdown before terminating the app | string | "5m" | +| [log](#app_shutdown_log) | Configuration for log | object | | + +### Log + +| Name | Description | Type | Default value | +| -------- | --------------------------------------------------- | ------- | -------------- | +| enabled | Whether to store self-shutdown events to a log file | boolean | true | +| filePath | The file path to the self-shutdown log | string | "shutdown.log" | + +Example: + +```json + { + "app": { + "checkForUpdates": true, + "shutdown": { + "stopGracePeriod": "5m", + "log": { + "enabled": true, + "filePath": "shutdown.log" + } + } + } + } +``` + +## 2. Logger + +| Name | Description | Type | Default value | +| ----------- | -------------------------------------------------------------------------------------------------------------- | ------ | ------------- | +| name | The optional name of the logger instance. All log messages are prefixed with that name. | string | "" | +| level | The minimum enabled logging level | string | "info" | +| timeFormat | Sets the logger's timestamp format. (options: "rfc3339", "rfc3339nano", "datetime", "timeonly", and "iso8601") | string | "rfc3339" | +| outputPaths | A list of file paths or stdout/stderr to write logging output to | array | stdout | + +Example: + +```json + { + "logger": { + "name": "", + "level": "info", + "timeFormat": "rfc3339", + "outputPaths": [ + "stdout" + ] + } + } +``` + +## 3. Peer to Peer + +| Name | Description | Type | Default value | +| ------------------------------------------- | ----------------------------------------------------------------- | ------ | -------------------------------------------- | +| bindMultiAddresses | The bind multi addresses for p2p connections | array | /ip4/0.0.0.0/tcp/15600
/ip6/::/tcp/15600 | +| [connectionManager](#p2p_connectionmanager) | Configuration for connectionManager | object | | +| identityPrivateKey | Private key used to derive the node identity (optional) | string | "" | +| identityPrivateKeyFilePath | The file path to the private key used to derive the node identity | string | "testnet/p2p/identity.key" | +| [autopeering](#p2p_autopeering) | Configuration for autopeering | object | | + +### ConnectionManager + +| Name | Description | Type | Default value | +| ------------- | ---------------------------------------------------------------------------- | ---- | ------------- | +| highWatermark | The threshold up on which connections count truncates to the lower watermark | int | 10 | +| lowWatermark | The minimum connections count to hold after the high watermark was reached | int | 5 | + +### Autopeering + +| Name | Description | Type | Default value | +| ---------------------- | -------------------------------------------------------------------------- | ------- | ------------- | +| maxPeers | The max number of auto-peer connections. Set to 0 to disable auto-peering. | int | 5 | +| bootstrapPeers | Peers to be used as discovery for other peers | array | | +| allowLocalIPs | Allow local IPs to be used for autopeering | boolean | false | +| externalMultiAddresses | External reacheable multi addresses advertised to the network | array | | + +Example: + +```json + { + "p2p": { + "bindMultiAddresses": [ + "/ip4/0.0.0.0/tcp/15600", + "/ip6/::/tcp/15600" + ], + "connectionManager": { + "highWatermark": 10, + "lowWatermark": 5 + }, + "identityPrivateKey": "", + "identityPrivateKeyFilePath": "testnet/p2p/identity.key", + "autopeering": { + "maxPeers": 5, + "bootstrapPeers": [], + "allowLocalIPs": false, + "externalMultiAddresses": [] + } + } + } +``` + +## 4. Profiling + +| Name | Description | Type | Default value | +| ----------- | ------------------------------------------------- | ------- | ---------------- | +| enabled | Whether the profiling component is enabled | boolean | false | +| bindAddress | The bind address on which the profiler listens on | string | "localhost:6060" | + +Example: + +```json + { + "profiling": { + "enabled": false, + "bindAddress": "localhost:6060" + } + } +``` + +## 5. RestAPI + +| Name | Description | Type | Default value | +| --------------------------- | ---------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| bindAddress | The bind address on which the REST API listens on | string | "0.0.0.0:14265" | +| publicRoutes | The HTTP REST routes which can be called without authorization. Wildcards using \* are allowed | array | /health
/api/routes
/api/core/v3/info
/api/core/v3/network\*
/api/core/v3/blocks\*
/api/core/v3/transactions\*
/api/core/v3/commitments\*
/api/core/v3/outputs\*
/api/core/v3/accounts\*
/api/core/v3/validators\*
/api/core/v3/rewards\*
/api/core/v3/committee\*
/api/debug/v2/\*
/api/indexer/v2/\*
/api/mqtt/v2
/api/blockissuer/v1/\* | +| protectedRoutes | The HTTP REST routes which need to be called with authorization. Wildcards using \* are allowed | array | /api/\* | +| debugRequestLoggerEnabled | Whether the debug logging for requests should be enabled | boolean | false | +| maxPageSize | The maximum number of results per page | uint | 100 | +| maxCacheSize | The maximum size of cache for results | string | "50MB" | +| [jwtAuth](#restapi_jwtauth) | Configuration for JWT Auth | object | | +| [limits](#restapi_limits) | Configuration for limits | object | | + +### JWT Auth + +| Name | Description | Type | Default value | +| ---- | --------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------------- | +| salt | Salt used inside the JWT tokens for the REST API. Change this to a different value to invalidate JWT tokens not matching this new value | string | "IOTA" | + +### Limits + +| Name | Description | Type | Default value | +| ------------- | ------------------------------------------------------------------------- | ------ | ------------- | +| maxBodyLength | The maximum number of characters that the body of an API call may contain | string | "1M" | +| maxResults | The maximum number of results that may be returned by an endpoint | int | 1000 | + +Example: + +```json + { + "restAPI": { + "bindAddress": "0.0.0.0:14265", + "publicRoutes": [ + "/health", + "/api/routes", + "/api/core/v3/info", + "/api/core/v3/network*", + "/api/core/v3/blocks*", + "/api/core/v3/transactions*", + "/api/core/v3/commitments*", + "/api/core/v3/outputs*", + "/api/core/v3/accounts*", + "/api/core/v3/validators*", + "/api/core/v3/rewards*", + "/api/core/v3/committee*", + "/api/debug/v2/*", + "/api/indexer/v2/*", + "/api/mqtt/v2", + "/api/blockissuer/v1/*" + ], + "protectedRoutes": [ + "/api/*" + ], + "debugRequestLoggerEnabled": false, + "maxPageSize": 100, + "maxCacheSize": "50MB", + "jwtAuth": { + "salt": "IOTA" + }, + "limits": { + "maxBodyLength": "1M", + "maxResults": 1000 + } + } + } +``` + +## 6. DebugAPI + +| Name | Description | Type | Default value | +| ------------------ | ----------------------------------------- | ------- | ------------- | +| enabled | Whether the DebugAPI component is enabled | boolean | false | +| [db](#debugapi_db) | Configuration for Database | object | | + +### Database + +| Name | Description | Type | Default value | +| ------------------------------- | ---------------------------------------------------------- | ------ | --------------- | +| path | The path to the database folder | string | "testnet/debug" | +| maxOpenDBs | Maximum number of open database instances | int | 2 | +| granularity | How many slots should be contained in a single DB instance | int | 100 | +| [pruning](#debugapi_db_pruning) | Configuration for pruning | object | | + +### Pruning + +| Name | Description | Type | Default value | +| --------- | ---------------------------------- | ---- | ------------- | +| threshold | How many epochs should be retained | uint | 1 | + +Example: + +```json + { + "debugAPI": { + "enabled": false, + "db": { + "path": "testnet/debug", + "maxOpenDBs": 2, + "granularity": 100, + "pruning": { + "threshold": 1 + } + } + } + } +``` + +## 7. MetricsTracker + +| Name | Description | Type | Default value | +| ------- | --------------------------------------------- | ------- | ------------- | +| enabled | Whether the Metrics Tracker plugin is enabled | boolean | true | + +Example: + +```json + { + "metricsTracker": { + "enabled": true + } + } +``` + +## 8. Database + +| Name | Description | Type | Default value | +| ---------------------- | ----------------------------------------- | ------ | ------------------ | +| engine | The used database engine (rocksdb/mapdb) | string | "rocksdb" | +| path | The path to the database folder | string | "testnet/database" | +| maxOpenDBs | Maximum number of open database instances | int | 5 | +| [pruning](#db_pruning) | Configuration for pruning | object | | + +### Pruning + +| Name | Description | Type | Default value | +| ------------------------ | -------------------------------------------- | ------ | ------------- | +| threshold | How many finalized epochs should be retained | uint | 30 | +| [size](#db_pruning_size) | Configuration for size | object | | + +### Size + +| Name | Description | Type | Default value | +| ------------------- | --------------------------------------------------------------------------------- | ------- | ------------- | +| enabled | Whether to delete old block data from the database based on maximum database size | boolean | true | +| targetSize | Target size of the database | string | "30GB" | +| reductionPercentage | The percentage the database size gets reduced if the target size is reached | float | 10.0 | +| cooldownTime | Cooldown time between two pruning by database size events | string | "5m" | + +Example: + +```json + { + "db": { + "engine": "rocksdb", + "path": "testnet/database", + "maxOpenDBs": 5, + "pruning": { + "threshold": 30, + "size": { + "enabled": true, + "targetSize": "30GB", + "reductionPercentage": 10, + "cooldownTime": "5m" + } + } + } + } +``` + +## 9. Protocol + +| Name | Description | Type | Default value | +| -------------------------------- | ---------------------------------------------------------------- | ------- | ---------------------------------- | +| [snapshot](#protocol_snapshot) | Configuration for snapshot | object | | +| commitmentCheck | Specifies whether commitment and ledger checks should be enabled | boolean | true | +| [filter](#protocol_filter) | Configuration for filter | object | | +| protocolParametersPath | The path of the protocol parameters file | string | "testnet/protocol_parameters.json" | +| [baseToken](#protocol_basetoken) | Configuration for baseToken | object | | + +### Snapshot + +| Name | Description | Type | Default value | +| ----- | ------------------------------------------------------------------------------------------ | ------ | ---------------------- | +| path | The path of the snapshot file | string | "testnet/snapshot.bin" | +| depth | Defines how many slot diffs are stored in the snapshot, starting from the full ledgerstate | int | 5 | + +### Filter + +| Name | Description | Type | Default value | +| -------------------- | ------------------------------------------------------------------------------------------ | ------ | ------------- | +| maxAllowedClockDrift | The maximum drift our wall clock can have to future blocks being received from the network | string | "5s" | + +### BaseToken + +| Name | Description | Type | Default value | +| ------------ | --------------------------------- | ------ | ------------- | +| name | The base token name | string | "Shimmer" | +| tickerSymbol | The base token ticker symbol | string | "SMR" | +| unit | The base token unit | string | "SMR" | +| subunit | The base token subunit | string | "glow" | +| decimals | The base token amount of decimals | uint | 6 | + +Example: + +```json + { + "protocol": { + "snapshot": { + "path": "testnet/snapshot.bin", + "depth": 5 + }, + "commitmentCheck": true, + "filter": { + "maxAllowedClockDrift": "5s" + }, + "protocolParametersPath": "testnet/protocol_parameters.json", + "baseToken": { + "name": "Shimmer", + "tickerSymbol": "SMR", + "unit": "SMR", + "subunit": "glow", + "decimals": 6 + } + } + } +``` + +## 10. Retainer + +| Name | Description | Type | Default value | +| ----------------------- | ----------------------------------------------------- | ------- | ------------- | +| debugStoreErrorMessages | Whether to store debug error messages in the database | boolean | false | + +Example: + +```json + { + "retainer": { + "debugStoreErrorMessages": false + } + } +``` + +## 11. Node + +| Name | Description | Type | Default value | +| ----- | ------------------------------- | ------ | ---------------- | +| alias | Set an alias to identify a node | string | "IOTA-Core node" | + +Example: + +```json + { + "node": { + "alias": "IOTA-Core node" + } + } +``` + +## 12. Prometheus + +| Name | Description | Type | Default value | +| --------------- | ---------------------------------------------------- | ------- | -------------- | +| enabled | Whether the Metrics component is enabled | boolean | true | +| bindAddress | Bind address on which the Prometheus exporter server | string | "0.0.0.0:9311" | +| goMetrics | Include go metrics | boolean | false | +| processMetrics | Include process metrics | boolean | false | +| promhttpMetrics | Include promhttp metrics | boolean | false | + +Example: + +```json + { + "prometheus": { + "enabled": true, + "bindAddress": "0.0.0.0:9311", + "goMetrics": false, + "processMetrics": false, + "promhttpMetrics": false + } + } +``` + +## 13. INX + +| Name | Description | Type | Default value | +| ----------- | ------------------------------------------------------ | ------- | ---------------- | +| enabled | Whether the INX plugin is enabled | boolean | false | +| bindAddress | The bind address on which the INX can be accessed from | string | "localhost:9029" | + +Example: + +```json + { + "inx": { + "enabled": false, + "bindAddress": "localhost:9029" + } +} +``` diff --git a/docs/maintain/iota-core/2.0/docs/welcome.md b/docs/maintain/iota-core/2.0/docs/welcome.md new file mode 100644 index 00000000000..1accc8395d2 --- /dev/null +++ b/docs/maintain/iota-core/2.0/docs/welcome.md @@ -0,0 +1,27 @@ +--- +description: The IOTA-Core is a powerful, easy to install node software written in Go. It provides the full node capabilities including full support of the latest network updates. +image: /img/icons/iota/iota_core.png +tags: + - IOTA Node + - IOTA-Core Node + - IOTA-Core + - IOTA + - Node Software + - Welcome + - explanation +--- + +# Welcome to IOTA-Core + +The IOTA-Core is a powerful, easy-to-install node software written in Go. +It provides full-node capabilities, including full support for the latest network updates. + +By running your own node, you have the following benefits: + +- You have direct access to the IOTA network instead of having to connect to and trust someone else's node. +- You help the network to become more distributed and resilient by validating blocks and _value transactions_. + +## Source Code + +The project's source code is available on [GitHub](https://github.com/iotaledger/iota-core). + diff --git a/docs/maintain/iota-core/2.0/sidebars.js b/docs/maintain/iota-core/2.0/sidebars.js new file mode 100644 index 00000000000..1716dce275c --- /dev/null +++ b/docs/maintain/iota-core/2.0/sidebars.js @@ -0,0 +1,315 @@ +/** + * * Creating a sidebar enables you to: + - create an ordered group of docs + - render a sidebar for each doc of that group + - provide next/previous navigation + + The sidebars can be generated from the filesystem, or explicitly defined here. + + Create as many sidebars as you want. + */ + +module.exports = { + docs: [ + { + type: 'category', + label: 'IOTA-Core', + collapsed: false, + items: [ + { + type: 'doc', + id: 'welcome', + }, + { + type: 'doc', + id: 'getting_started/getting_started', + }, + { + type: 'category', + label: 'How to', + items: [ + { + type: 'doc', + id: 'how_tos/using_docker', + label: 'Install using Docker', + }, + { + type: 'doc', + id: 'how_tos/validator_setup', + label: 'Become a validator', + }, + { + type: 'doc', + id: 'how_tos/post_installation', + label: 'Post Installation', + }, + ], + } /* + { + type: 'category', + label: 'INX-Plugins', + link: { + type: 'generated-index', + title: 'INX-Plugins', + description: + 'Use custom plugins to extend the functionality of your node.', + slug: '/inx-plugins', + keywords: ['inx', 'plugins'], + }, + items: [ + { + type: 'category', + label: 'API Core v0', + collapsed: true, + items: [ + { + type: 'doc', + label: 'Welcome', + id: 'inx-plugins/api-core-v0/welcome', + }, + { + type: 'doc', + label: 'Configuration', + id: 'inx-plugins/api-core-v0/configuration', + }, + ], + }, + { + type: 'category', + label: 'API Core v1', + collapsed: true, + items: [ + { + type: 'doc', + label: 'Welcome', + id: 'inx-plugins/api-core-v1/welcome', + }, + { + type: 'doc', + label: 'Configuration', + id: 'inx-plugins/api-core-v1/configuration', + }, + ], + }, + { + type: 'category', + label: 'Coordinator', + collapsed: true, + items: [ + { + type: 'doc', + label: 'Welcome', + id: 'inx-plugins/coordinator/welcome', + }, + { + type: 'doc', + label: 'Configuration', + id: 'inx-plugins/coordinator/configuration', + }, + ], + }, + { + type: 'category', + label: 'Dashboard', + collapsed: true, + items: [ + { + type: 'doc', + label: 'Welcome', + id: 'inx-plugins/dashboard/welcome', + }, + { + type: 'doc', + label: 'Configuration', + id: 'inx-plugins/dashboard/configuration', + }, + ], + }, + { + type: 'category', + label: 'Faucet', + collapsed: true, + items: [ + { + type: 'doc', + label: 'Welcome', + id: 'inx-plugins/faucet/welcome', + }, + { + type: 'doc', + label: 'Configuration', + id: 'inx-plugins/faucet/configuration', + }, + ], + }, + { + type: 'category', + label: 'Indexer', + collapsed: true, + items: [ + { + type: 'doc', + label: 'Welcome', + id: 'inx-plugins/indexer/welcome', + }, + { + type: 'doc', + label: 'Configuration', + id: 'inx-plugins/indexer/configuration', + }, + { + type: 'doc', + label: 'API Reference', + id: 'inx-plugins/indexer/api_reference', + }, + { + type: 'doc', + label: 'How To Query Outputs', + id: 'inx-plugins/indexer/how_to/query_outputs', + }, + ], + }, + { + type: 'category', + label: 'IRC Metadata', + collapsed: true, + items: [ + { + type: 'doc', + label: 'Welcome', + id: 'inx-plugins/irc-metadata/welcome', + }, + { + type: 'doc', + label: 'Configuration', + id: 'inx-plugins/irc-metadata/configuration', + }, + { + type: 'doc', + label: 'API Reference', + id: 'inx-plugins/irc-metadata/api_reference', + }, + ], + }, + { + type: 'category', + label: 'MQTT', + collapsed: true, + items: [ + { + type: 'doc', + label: 'Welcome', + id: 'inx-plugins/mqtt/welcome', + }, + { + type: 'doc', + label: 'Configuration', + id: 'inx-plugins/mqtt/configuration', + }, + { + type: 'doc', + label: 'API Reference', + id: 'inx-plugins/mqtt/api_reference', + }, + ], + }, + { + type: 'category', + label: 'Participation', + collapsed: true, + items: [ + { + type: 'doc', + label: 'Welcome', + id: 'inx-plugins/participation/welcome', + }, + { + type: 'doc', + label: 'Configuration', + id: 'inx-plugins/participation/configuration', + }, + { + type: 'doc', + label: 'API Reference', + id: 'inx-plugins/participation/api_reference', + }, + ], + }, + { + type: 'category', + label: 'POI', + collapsed: true, + items: [ + { + type: 'doc', + label: 'Welcome', + id: 'inx-plugins/poi/welcome', + }, + { + type: 'doc', + label: 'Configuration', + id: 'inx-plugins/poi/configuration', + }, + { + type: 'doc', + label: 'API Reference', + id: 'inx-plugins/poi/api_reference', + }, + ], + }, + { + type: 'category', + label: 'Spammer', + collapsed: true, + items: [ + { + type: 'doc', + label: 'Welcome', + id: 'inx-plugins/spammer/welcome', + }, + { + type: 'doc', + label: 'Configuration', + id: 'inx-plugins/spammer/configuration', + }, + ], + }, + { + type: 'category', + label: 'Community INX Plugins', + collapsed: true, + items: [ + { + label: 'INX Collector', + type: 'link', + href: 'https://github.com/teleconsys/inx-collector', + }, + ], + }, + ], + },*/, + { + type: 'category', + label: 'References', + items: [ + { + type: 'doc', + id: 'references/configuration', + label: 'Configuration', + } /* + { + type: 'doc', + id: 'references/peering', + label: 'Peering', + },*/, + { + type: 'doc', + id: 'references/api_reference', + label: 'API Reference', + }, + ], + }, + ], + }, + ], +}; diff --git a/docusaurus.config.js b/docusaurus.config.js index 54475f71726..24a4aa77a8f 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -249,7 +249,7 @@ module.exports = async () => { id: 'openapi', docsPluginId: 'apis', // e.g. "classic" or the plugin-content-docs id config: { - coreApiShimmer: { + coreApiV2: { specPath: 'https://raw.githubusercontent.com/iotaledger/tips/main/tips/TIP-0025/core-rest-api.yaml', outputDir: path.resolve( @@ -260,6 +260,17 @@ module.exports = async () => { groupPathsBy: 'tag', }, }, + coreApiV3: { + specPath: + 'https://raw.githubusercontent.com/iotaledger/tips/tip48/tips/TIP-0048/openapi3-core.yaml', + outputDir: path.resolve( + __dirname, + 'docs/build/apis/docs/core/v3', + ), + sidebarOptions: { + groupPathsBy: 'tag', + }, + }, waspApi: { specPath: 'https://raw.githubusercontent.com/iotaledger/wasp/develop/clients/apiclient/api/openapi.yaml', diff --git a/versionedConfig.js b/versionedConfig.js index 58b8fbb2d32..5f0d04f79b8 100644 --- a/versionedConfig.js +++ b/versionedConfig.js @@ -124,6 +124,19 @@ exports.maintainPluginsConfig = [ }, ], }, + { + id: 'iota-core', + label: 'IOTA-Core', + description: "IOTA's latest node software.", + icon: 'Iota20', + subsection: 'maintain-layer-1', + versions: [ + { + label: '2.0', + badges: ['Testnet'], + }, + ], + }, { id: 'wasp', label: 'Wasp',