waves_logo Docs
  • Node Owner Guide
    Node Owner Guide
  • Install Waves Node
    • Deploy Node in Docker
      Deploy Node in Docker
    • Install Node on Ubuntu
      Install Node on Ubuntu
    • Install Node on macOS
      Install Node on macOS
    • Install Node on Windows
      Install Node on Windows
    • Install from Source (Building SBT)
      Install from Source (Building SBT)
    Install Waves Node
  • Synchronize Waves Blockchain
    • Import/Export Blockchain
      Import/Export Blockchain
    • Download the Latest Blockchain
      Download the Latest Blockchain
    • Rollback Waves Node
      Rollback Waves Node
    Synchronize Waves Blockchain
  • Generate Blocks
    Generate Blocks
  • Upgrade Waves Node
    Upgrade Waves Node
  • Node Configuration
    Node Configuration
  • Logging Configuration
    Logging Configuration
  • Node Wallet
    Node Wallet
  • Features
    • Activation protocol
      Activation protocol
    Features
  • Custom Blockchain
    Custom Blockchain
  • Node REST API
    • API Key
      API Key
    • Working with Transactions
      Working with Transactions
    • Numeric Fields Format
      Numeric Fields Format
    • Pagination
      Pagination
    • CORS
      CORS
    • API Limitations of Pool of Public Nodes
      API Limitations of Pool of Public Nodes
    • Slow Requests
      Slow Requests
    • Response Codes and Errors
      Response Codes and Errors
    Node REST API
  • Extensions
    • gRPC Server
      gRPC Server
    • Blockchain Updates
      Blockchain Updates
    Extensions
  • Troubleshooting
    • Block Generation FAQ
      Block Generation FAQ
    Troubleshooting
  • Node Go
    Node Go
      • English
      • Русский
      On this page
        • Required Parameters
        • Changing Node Parameters
        • Sections of the Configuration File
          • Waves Configuration Section
          • DB Settings
          • Network Settings
          • Wallet Settings
          • Blockchain Settings
          • Miner Settings
          • REST API Settings
          • Synchronization Settings
          • UTX Pool Settings
          • Features Settings
          • Rewards Settings
      waves_logo Docs

          # Node Configuration

          Waves node parameters are stored in the node configuration file (*.conf). The system uses HOCON (Human-Optimized Config Object Notation) format that provides simple syntax and ability to use comments. Read more about HOCON .

          For a node installed from the APT repository or from a DEB package, the configuration file is embedded into the package, see the Install Node on Ubuntu article. For a node installed from a JAR file, download the sample configuration file waves-sample.conf .

          # Required Parameters

          In most cases, such as running a node from scratch, it is sufficient to set the following required parameters specific for your node:

          • waves.wallet.seed if you want the node to generate blocks or sign transactions on behalf of a particular account;
          • waves.wallet.password;
          • waves.rest-api.api-key-hash to use node API;
          • waves.blockchain.type.

          For the rest of the parameters, we recommend to leave the default values.

          # Changing Node Parameters

          After editing the configuration file, restart the node.

          For the node installed from a JAR file, specify the path to the edited configuration file in the start command (replace {*} with the actual file name):

          java -jar {*}.jar {*}.conf
          

          # Sections of the Configuration File

          Node configuration file contains parameters grouped into the following sections:

          Section Description
          waves Essential node parameters and other configuration subsections
          db Blockchain database parameters
          network Peer to peer network parameters
          wallet Built in node wallet parameters
          blockchain Blockchain parameters
          miner Blocks generator parameters
          rest-api Node API parameters
          synchronization Node synchronization parameters
          utx Unconfirmed transactions pool parameters
          features Features parameters
          rewards Rewards parameters
                extensions Extensions parameters
          kamon Performance metrics parameters
          metrics Blocks, transactions and other info metrics parameters

          # Waves Configuration Section

          Root configuration section waves holds essential application parameters and other configuration subsections.

          Using the enable-light-mode parameter, you can enable and disable the light mode. In the light mode, the node applies ready-made state snapshots without performing transaction validation, and thus significantly speeds up block processing. The default value is no. Light mode is enabled by feature #22 “Light Node”.

          With the directory parameter, you can set a path to the base application directory. It is possible to use environment variables to set configuration parameters. For example, by default, the base directory constructed relative to the user’s HOME environment variable. Please, do not enclose environment variables references in quotes, in this case, they will be handled as strings and won’t be resolved.

          Make sure the defined directory has a correct owner set: waves, waves-testnet or waves-stagenet for mainnet, testnet or stagenet.

          # Default Application Directory

          The paths listed below are used by default if the directory parameter is not specified in the configuration file.

          For nodes installed from DEB package:

          *nix
          Mainnet /var/lib/waves
          Testnet /var/lib/waves-testnet
          Stagenet /var/lib/waves-stagenet

          The following default application directories, depending on the operating system and the type of blockchain, are used for jar nodes if the directory parameter is not set in the node configuration .conf file:

          *nix macOS Windows
          Mainnet $XDG_DATA_HOME/waves-mainnet or $HOME/.local/share/waves-mainnet $HOME/Library/Application Support/waves-mainnet %LOCALAPPDATA%/waves-mainnet
          Testnet $XDG_DATA_HOME/waves-testnet or $HOME/.local/share/waves-testnet $HOME/Library/Application Support/waves-testnet %LOCALAPPDATA%/waves-testnet
          Stagenet $XDG_DATA_HOME/waves-stagenet or $HOME/.local/share/waves-stagenet $HOME/Library/Application Support/waves-stagenet %LOCALAPPDATA%/waves-stagenet
          Custom $XDG_DATA_HOME/waves-custom-<character>* or $HOME/.local/share/waves-custom-<character>* $HOME/Library/Application Support/waves-custom-<character>* %LOCALAPPDATA%/waves-custom-<character>*

          * See address-scheme-character parameter description.

          Note: The cache size parameters are set in bytes, but you can use size units:

          • K - for kilobyte
          • M - for megabytes
          • G - for gigabytes

          # DB Settings

          In DB section you can set blockchain database parameters.

          Name Description Default value
          directory Sets the location of database file. ${waves.directory}"/data" The path is resolved with regard to directory parameter from waves section.
          store-transactions-by-address This parameter allows to store transactions by address in database. If disabled, you will not be able to get information from the node. true
          store-invoke-script-results This parameter allows to store state changes in database. If disabled, you will not be able to get the state changes on your node. true
          max-cache-size Limits the size of caches which are used during block validation. Lower values slightly decrease memory consumption, while higher values might increase node performance. Setting this value to 0 disables caching. 100000
          max-rollback-depth By default a node can process rollback to up to 2000 blocks without rebuilding blockchain database. The default limit can be changed with this. 2000
          use-bloom-filter Enabling bloom filter allows to speed up blockchain import. Should be disabled in normal node operation. false
          store-state-hashes This setting enables /debug/stateHash/{height} api method false

          # Network Settings

          In network section you can set P2P network parameters.

          Name Description Default value
          file Sets the location of database file where the node stores lists of known and blacklisted peers. ${waves.directory}"/peers.dat By default, the path is resolved with regard to directory parameter from waves section.
          declared-address Sets the IP address and port (address:port) that is sent as external address during handshake.
          • Can be set automatically if UPnP is enabled. If the declared-address is not set and UPnP is enabled, the node will attempt to connect to an IGD (Internet Gateway Device), retrieve its external IP address and configure the gateway to allow traffic through. If the node succeeds, the IGD's external IP address becomes the node's declared-address.
          • If the declared-address is set and the UPnP is disabled, the node will listen to incoming connections on bind-address:port and broadcast specified declared-address to peers.
          • If the declared-address is not set and UPnP is disabled, the node will not listen to incoming connections at all.
          • In some cases, however, this setup is not recommended, you can set declared-address and enable UPnP (e.g. when IGD can't reliably determine its external IP address), so that the node attempts to configure an IGD to pass traffic from external port to bind-address:port.
          bind-address Sets the IP address of local network interface on which Waves Node will accept incoming connections. By default, node binds to 0.0.0.0 that means that it will listen on all available network adapters.
          port Sets the network port number to which other Waves nodes will connect. Check that the port is reachable from outside, otherwise your node will connect to P2P network using only outgoing connections. If this the port is used by other application, your node won’t start. 6868 for Mainnet
          6863 for Testnet
          6862 for Stagenet
          node-name Sets the name of your node visible to other participants of the P2P network. The name is transmitted during initial handshake. Generated randomly as Node-${random-nonce}
          nonce This value is sent during handshake. The value is used to distinguish nodes connected from one IP address. Generated randomly
          known-peers This parameter stores the list of bootstrap nodes to which your node will establish outgoing connections while initializing. no value
          peers-data-residence-time Period of time during which the node stores information about external peer since last communication session with it. 1d
          black-list-residence-time Period of time for which the information about external peer stays in the blacklist. 15m
          break-idle-connections-timeout Break a connection if there is no message from the peer during this timeout 5m
          max-inbound-connections Sets the maximum number of simultaneous inbound connections handled by the node. 100
          max-outbound-connections Number of maximum outgoing network connections. 100
          max-single-host-connections Allowed number of network connections made from single IP address. 3
          connection-timeout Network communication timeout. 30s
          max-unverified-peers Maximum size of the buffer to store information about peers during handshake process. 100
          enable-peers-exchange Enables or disables requesting and sending the information about peers. yes
          enable-blacklisting Enables or disables blacklisting of peers. yes
          peers-broadcast-interval Period of time between broadcasts of known peers list to other nodes. 2m
          handshake-timeout Time period to wait for reply during handshake. In case of no reply the peer will be blacklisted. 30s
          upnp This section allows to set the UPnP settings. The settings are useful if your node is running in the network where the node can ask your router (Internet Gateway Device) to establish a tunnel. By default, this functionality is disabled. To enable set the enable parameter to yes.
          traffic-logger This section allows to enable or disable logging of some of the incoming or outgoing network messages. Network messages are logged at TRACE level.

          Note: The time span parameters are set in milliseconds, but you can use duration units to shorten the value. Supported units are:

          • s - second, seconds
          • m - minute, minutes
          • h - hour, hours
          • d - day, days

          For usage examples see the list of default settings (do not copy this file and do not use it as the configuration file for your node).

          # Wallet Settings

          In wallet section you can configure parameters of the wallet built in Waves node.

          Name Description Default value
          file Sets the path to the wallet file. By default, the path to the file is calculated relative to the base application directory.
          password Sets the password string to protect the wallet file. "password string"
          seed This parameter is used to recreate an existing wallet on a new node. Provide the seed base58-encoded. If you don’t have any existing wallet, comment out this parameter and start the node. During the first run, the application will create a new wallet with a random seed for you. In this case, the seed will be displayed in the application log. If you miss it or if you don’t want to check the log files, it will also be available in REST API using the wallet/seed method. "seed in BASE58"

          Warning: Wallet is a critical part of your node. It is better to create its file in a safe and protected location. Don’t forget to backup your wallet’s file. It’s recommended to remove the seed from the configuration file immediately after the start of the node. If an attacker gains access to the seed string, he will have access to your funds on all your addresses!

          # Blockchain Settings

          In blockchain section you can select the blockchain type or create your own blockchain.

          Name Description Default value
          type Blockchain type: MAINNET, TESTNET, STAGENET, or CUSTOM. For MAINNET or TESTNET or STAGENET types, parameters of blockchain are built in the application so you don’t have to configure the parameters. See standard parameters for different types of blockchain . But if you select CUSTOM blockchain type, you have to provide parameters in the custom configuration section. TESTNET

          # Configuring Custom Blockchain

          The custom section allows to set parameters of your custom blockchain.

          Name Description Default value
          address-scheme-character This parameter in custom section to set the address feature character. This character used while building an address and also passed over a network during a handshake. The latter allow nodes not to connect to the nodes with other blockchains.
          functionality Section of blockchain functionality settings. The main settings are given below, for the others we don't recommend changing the defaults
          genesis Section of genesis block parameters, see the description below
          rewards Section containing the initial block reward and voting settings for changing it (see the Community-Driven Monetary Policy article)
          # Functionality settings
          Name Description Default value
          feature-check-blocks-period Number of blocks in the voting period for a new feature and in the period from feature approval to activation (see the Activation Protocol) article 10000
          blocks-for-feature-activation The number of blocks with feature support required for its approval 9000
          max-transaction-time-back-offset Allowable time a transaction's timestamp can lag behind the block's timestamp 120m
          max-transaction-time-forward-offset Allowable time a transaction's timestamp can be ahead of the block's timestamp 90m
          pre-activated-features List of pre-activated features and their activation heights (see the Features article)
          dao-address,
          xtn-buyback-address
          Addresses receiving a share of block reward (for more information on block reward distribution, see the Community Driven Monetary Policy article). If the address (or both) is not specified, the corresponding share of block reward goes to the block generator
          # Genesis block parameters
          Name Description Default value
          block-timestamp Sets the date of creation of genesis block.
          timestamp Sets time of creation for genesis transactions.
          signature Sets the signature of genesis block.
          initial-balance This parameter allows to set the total amount of coins. This value should be given in the atomic units of token.
          average-block-delay Sets the speed of block generation in your blockchain. This is a target period of time between blocks. In reality the delays between blocks may vary.
          transactions This parameter allows to provide the list of first transactions. Each transaction is described by recipient’s address (as BASE58 string) and amount. You have to distribute all initial balance to one or more addresses in genesis block. If you failed to do so, the genesis block will be considered as incorrect and the application won’t start.

          # Miner Settings

          In miner section it is possible to configure parameters of the new blocks generator.

          Name Description Default value
          enable This parameter enables or disables block generation on the node. By default, it’s enabled, but if you disable it your node won’t try to generate new blocks (won’t mine).
          quorum Sets the minimum required number of connected peers to enable and start mining of new blocks. By default it is set to 1, so your node will start mining as soon as it connects to the first peer in the P2P network. Setting this parameter to 0 will enable off-line generation.
          interval-after-last-block-then-generation-is-allowed This parameter allows to tune your node’s blocks download and generation behavior. By default, it set to 1 day, which means that your node won’t start block generation until it has the last block in the local blockchain not older than 1 day. So, using this parameter you tell your node to actualize the blockchain before starting to generate new blocks. Actually, it works only after long node shutdowns.
          no-quorum-mining-delay Sets mining attempts delay, if no quorum is available 5s
          micro-block-interval Sets the interval between microblocks 2s starting from node version 1.4.7
          5s up to and including node version 1.4.6
          max-transactions-in-micro-block Sets max amount of transactions in micro block 255
          min-micro-block-age Miner references the best microblock which is at least this age 2s
          minimal-block-generation-offset Sets minimal block generation offset 0
          private-keys Private keys used for generating blocks insteads of the main account from the node's wallet

          # REST API Settings

          The rest-api section in the node configuration file contains settings of Node REST API.

          Name Description Default value
          enable Activates REST API.
          If you want to deactivate REST API, change the default value to no
          yes
          bind-address Network address where the REST API accepts incoming connections.
          Note. It's not recommended to change the default value. Use Nginx’s proxy pass module or SSH port forwarding for external access
          "127.0.0.1"
          port Port number where the REST API accepts incoming connections 6869
          api-key-hash Hash of the API key to access private endpoints. For details see the API Key article ""
          cors-headers Section of CORS settings. See the How to Configure CORS: Support For Cross Domain Requests article for details. For a description of the settings, see below If the section is omitted, web apps of any domains are allowed to make requests to the node API
          transactions-by-address-limit • Maximum limit value in a request to /transactions/address/{address}/limit/{limit}
          • Maximum number of transaction IDs in request to /transactions/status and /transactions/merkleProof
          1000
          distribution-address-limit Maximum limit value in a request to /assets/{assetId}/distribution/{height}/limit/{limit} 1000
          data-keys-request-limit Maximum number of keys in a request to  /addresses/data/{address} 1000
          asset-details-limit Maximum number of token IDs in a request to /assets/details and /assets/balance/{address} 100
          blocks-request-limit • Maximum range {from}-{to} in a request to /blocks/address/{address}/{from}/{to}, /blocks/seq/{start}/{end}, and /blocks/headers/seq/{start}/{end} 100
          evaluate-script-complexity-limit Maximum complexity of the input expression in /utils/script/evaluate/{address} 52 000
          limited-pool-threads Maximum number of threads that process requests to /utils/script/compile*, /utils/script/decompile, /utils/script/estimate (the processing time for each request is limited) 2
          minimum-peers Minimum required number of connected peers to accept transactions via gRPC or REST API (broadcast). If the number of connected peers is less than the specified number, the node rejects transactions received via the API 1

          # CORS Settings

          Name Description Default value
          access-control-allow-headers HTTP headers that can be used during the external request [ "Authorization", "Content-Type", "X-Requested-With", "Timestamp", "Signature" ]
          access-control-allow-origin Origin that can access the response from requesting code "origin-from-request", which means that the Access-control-allow-origin HTTP header of the node API response contains the domain specified in the Origin header of the request. That way, any domain is allowed by default
          access-control-allow-methods Allowed HTTP methods when accessing a resource ["OPTIONS", "POST", "PUT", "GET", "DELETE"]
          access-control-allow-credentials Enable/disable exposing the response to the frontend JS code when the request's credentials mode is include yes

          # Synchronization Settings

          In synchronization section it is possible to tune different aspects of node synchronization process.

          Name Description Default value
          max-rollback This parameter allows to change the length of blockchain that can be discarded in case of fork detection. If your node is on a fork with a lower score, it will try to switch to another fork, to do so the node will rollback few blocks. If the detected fork is longer than the given number, node prefers not to switch to another fork even if its score is bigger. 100
          synchronization-timeout Sets the timeout on block download operation. 60s
          score-ttl Sets the time-to-live interval of broadcasted score packets. 90s
          history-replier In this subsection you can configure the number of last blocks and micro-blocks cached in memory.
          micro-block-synchronizer In this subsection you could tune various parameters of Waves-NG protocol. 2s

          # UTX Pool Settings

          The utx section allows to set unconfirmed transactions pool parameters.

          Name Description Default value
          max-size Sets the size of unconfirmed transactions pool (both scripted and non-scripted). 100000
          max-scripted-size Sets the size of unconfirmed transactions pool for scripted transactions. Prior to node version 1.1.6, the invoke script transactions were not counted (the counted were the transactions for the validation of which it is required to execute a smart contract). 5000
          max-transaction-age Sets the maximum age of transactions allowed to UTX.

          # Features Settings

          The features section allows to set features parameters

          Name Description Default Value
          auto-shutdown-on-unsupported-feature If this parameter is turned on, the node will be shut down on activation of a feature that is not implemented by node’s codebase. yes
          supported This parameter contains the list of features IDs, supported by the node owner. By default, the list is empty.

          Example:

          waves {
            ...
            features {
              auto-shutdown-on-unsupported-feature = yes
              supported = [20]
            }
          }
          

          # Rewards Settings

          In this section, you can set the desired reward size using desired parameter. The setting value is specified in WAVELETs.

          If the value is greater than the current reward size, then miner votes for the current reward size increase; if the value is smaller — for the decrease.

          Example of the setting that has the desired value of 7 WAVES:

          waves {
            ...
            rewards {
              desired = 700000000
            }
          }  
          

          The value can be any integer in the range from 0 to 9,223,372,036,854,775,807 inclusive. Negative value will be ignored.

          See Community-Driven Monetary Policy for more information.

          Upgrade Waves Node
          Logging Configuration
          Upgrade Waves Node
          Logging Configuration