Configure your NKN node

From NKN Community Wiki

📌 This guide will help you to understand the different possible customisation of your NKN node using its configuration file.

⚠️ If you are not sure what you want to do or have any doubts about your configuration, do not change the default values!

The config.json file is available at different location regarding your installation method

 /home/nkn/nkn-commercial/services/nkn-node/config.json (All in one) 
/home/nknx/nkn-commercial/services/nkn-node/config.json (nknx)

config.json default

  Version                    int
  SeedList                   []string
  SyncMode                   string
  RPCCert                    string
  RPCKey                     string
  HttpWsPort                 uint16
  HttpJsonPort               uint16
  NodePort                   uint16
  LogLevel                   int
  MaxLogFileSize             uint32
  IsTLS                      bool
  GenesisBlockProposer       string
  NumLowFeeTxnPerBlock       uint32
  LowFeeTxnSizePerBlock      uint32
  MinTxnFee                  int64
  RegisterIDRegFee           int64
  RegisterIDTxnFee           int64
  Hostname                   string
  Transport                  string
  NAT                        bool
  Mining                     bool
  MiningDebug                bool
  BeneficiaryAddr            string
  SyncBatchWindowSize        uint32
  SyncBlockHeadersBatchSize  uint32
  SyncBlocksBatchSize        uint32
  NumTxnPerBlock             uint32
  TxPoolPerAccountTxCap      uint32
  TxPoolTotalTxCap           uint32
  TxPoolMaxMemorySize        uint32
  RPCReadTimeout             time.Duration
  RPCWriteTimeout            time.Duration
  KeepAliveTimeout           time.Duration
  LogPath                    string
  ChainDBPath                string
  WalletFile                 string
  MaxGetIDSeeds              uint32
  DBFilesCacheCapacity       uint32

Configuration options


Before a new node can join NKN network, it needs to acquire neighbor information from any of the existing live nodes in NKN network. When nknd is initiated, it will randomly pick a seed node, and send request to that seed node to get its neighbor list. Any live node can become seed node for others. NKN project team provide 8 seed nodes that can run stably for long period of time.


Version 2.17 introduced two new sync mode: fast sync and light sync. Fast sync node will sync the same full block history as before, but much faster by syncing the state directly. Think of it as a decentralized replacement of the ChainDB snapshot that many people are using. Light sync node will only sync headers of old blocks without transactions. The local ledger size will be much smaller than before (ChainDB size is about 4GB at the time of the release), but node will not be able to respond to getblock and gettransaction RPC requests for old blocks/transactions. We recommend using light sync only when node disk space is not enough.

Parameters are : "SyncMode": "fast" or "SyncMode": "light"


If HttpJson RPC service is using TLS for connection


NKN’s designated port for HttpJson service, and its default value is 30003.


When HttpJson is using TLS connection, RPCCert is the certificate while RPCKey is the private key.


NKN’s designated port for WebSocket service, and its default value is 30002. If the last 3 digits of port is 440 (for example 30443), then it is TLS connection.


nkn network overlay port,and its default value is 30001


Level of logging: [0:Debug, 1:Info, 2:Warning, 3:Error]


The maximum log file size before a new log file is created.

unit in MB,and its default value is 20MB


Public key of the designated generis block proposer, default value is the public key of NKN developer team.


The number of low fee transactions that miners are willing to include within each block. 0 means there is no limit, and the default value is 0.


The max allowed size (in Bytes) per block for all the low fee transactions. 0 means there is no limit. Default value is 4096.


The minimum acceptable fee (in NKN) per transaction for this node. If the fees included in the transaction is lower than this, this transaction will not be included in the block. Default value is 0.1.


The amount registration fee this node is willing to pay for GenerateID. The default value is 0.


The amount transaction fee this node is willing to accept for including this GenerateID into the block. The default value is 0.


Designated public IP address of this node. Upon bootup, the node will use external service to find out own public IP address. Default value is empty. If you want to run a local testnet with a single machine, Hostname should be set to “”


Whether automatic port forwarding is enabled (requires home router to support UPnP and PMP functionality). Default value is True.


On/Off switch for enabling/disabling mining. Default value is True.


Whether use tcp or udp for socket connection. Default value is “tcp”.


Whether to display node’s current timestamp and proposalSubmitted in getnodestate API. It will help debug Mining issues. Default value is True.


Configure the wallet address that will receive mining rewards. This will enable the decoupling of miner wallet and asset holding wallet, thus improving security. If this configuration is not empty, all mining reward will go to BeneficiaryAddr wallet address. Otherwise the mining reward will go to local mining wallet. Default value is empty.


During initial synchronization of blockchain data, the number of concurrent job threads. default value is 1024. The higher the window size, the faster the initial synchronization speed. However on smaller devices built with less RAM, smaller window size is recommended to avoid out of memory errors during initial synchronization.


During blockchain data synchronization, the number of BlockHeaders each job thread will fetch. Default value is 256.


During blockchain data synchronization, the number of Blocks each job thread will fetch. Default value is 8.


Maximum amount of transactions per block. Default value is 4096.


Maximum amount of transactions per account in the transaction pool. Default value is 32.


Maximum amount of total transactions from all accounts in the transaction pool. 0 means there is no limit. Default value is 0.


Maximum size (in Mega Bytes or MB) of total transactions from all accounts in the transaction pool. 0 means there is no limit. Default value is 32 (MB).


Timeout intervals for Read, Write and KeepAlive of HttpJson service