Resetting a Network
Creating a new chain or resetting a specific network can be tedious. The following guide should save you time.
The instructions in this guide are only for developers and the Lynx Code Development Team. There is no situation where a user should execute these instructions to 'fix a bug.'
A video at the bottom of this article complements this writing.
This guide is being created as a reference for developers looking to reset the Testnet network. Consensus parameters must be changed to create a new Mainnet blockchain, but this guide does not cover those changes.
Step 1: Preparing the target network
Shut down all peers that operate on the target network.
If you execute the following steps without shutting down all daemons on the network, your effort will be futile. You must be able to stop all daemons on the network to reset it. This is a feature of blockchain, not a bug. This design disallows a bad actor from executing these steps on the Mainnet network for a blockchain project since detected peers will have a longer chain length backed by a network of PoW or PoS hashing power.
Don't forget that with blockchain, the longest chain wins. If you don't shut down all nodes and your newly created node discovers a peer with a longer chain, the two will sync, and your short chain history will be reset and 'overwritten' by the longer peer chain history.
For your safety, after you shut down all the neighbor peers on the network, delete the chain history for those neighbor peers, too. The reason is that if a node is accidentally turned on later and still has the old chain history intact, it will disrupt your effort and force you to start over again. Save time by turning off all neighbor peers and deleting each node's blockchain data files. All blockchain history will be lost, including coins possessed, transaction history, and data stored. Be sure this is exactly your intention. Practice on a Testnet. There is no undo or rollback. The following command is a suggestion.
Step 2: Prepare the primary creation daemon
Determine which VPS will initialize the network with the first 1500 blocks.
As of 2024, Lynx is a Proof of Stake project, but the initialization of the first 1500 blocks of the network is completed with Proof of Work. The process requires a single node to start the process. Keep all other nodes off or disconnected from the network. Again, if any of them are enabled, you will lose your work as the peer will have a longer chain. Your primary daemon will have its blockchain history reset to the peer's longer chain history.
Not turning off all peer nodes or enabling a peer node without deleting its chain history is the primary reason this process fails. There is no harm in starting over again, but go slow and stay disciplined in your process.
Step 3: Set your startup parameters
Configure two temporary upstart arguments.
When Lynx starts, the daemon discovers no peers and assumes the chain state is stale because no blockchain history is known. The daemon will find itself 'stuck,' and nothing will happen. To prevent this, force the two following start-up parameters on the daemon.
Fundamentally, you are telling the daemon to ignore the fact that the stale state of the network can be ignored and to ignore the PoW or PoS mining status of any other peer (during this sensitive period) discovered. You will remove these two parameters later.
Step 4: Start one daemon and create reward addresses
Create addresses to capture the new block rewards.
Start the daemon and review the debug log. Be sure to review the debug log for the respective network you are working on; the testnet has its own debug log here.
This guide does not cover the intricacies of updating your genesis block consensus parameters. This documentation assumes you have set 'testnet=1' in your lynx.conf file.
To start creating blocks, you must have addresses known to the daemon to collect the coinbase reward. Be sure to configure your lynx.conf file with the network parameter to indicate which network you are operating. Execute the following command five times to create unique addresses on the node.
Save these addresses; you will need them in the next step.
Step 5: Create Proof of Work blocks
Capture the coinbase rewards from the first blocks created.
Using the RPC command 'generatetoaddress', you will force the creation of blocks in sets. The following example creates five blocks and assigns the coinbase reward to the respective address. This is one of the addresses generated in the previous step. Execute this step repeatedly for each address you create. A shell script or crontab is recommended to automate this process.
The trick is not to create the blocks too fast. Later, the Proof of Stake algorithm will use the time stamps of the created blocks to impact the target block time. If you create these new blocks too fast or in too large amounts, the PoS algorithm may become stuck later. An example of a crontab script is below.
Step 6: Forcibly turn off staking
Prevent simultaneous PoS and PoW block creation errors.
After a while, you will see 'incorrect proof of work' entries in the debug log. This happens because the Lynx daemon starts the staking thread automatically. This is a feature, not a bug. During this block creation period, the debug log will generate a long list of these messages. You can avoid these by turning off staking using the following command.
Once block 1500 is reached, you can stop this process and proceed to the next step of using Proof of Stake to create blocks.
Step 7: Allow your target block time to stabilize
Be patient and allow the difficulty adjustment algorithm to work.
Once your maximum PoW block has been reached, you can restart your primary Lynx daemon. You will know when no more PoW blocks get created. You should only restart this daemon, no others yet. You'll need to be patient at this step. If you are impatient and send Lynx coins to other nodes, you risk creating a stuck network, and then you would have to start the process over again.
You can turn off your crontab of 'generatetoaddress' commands now. If you don't, you will notice that PoS blocks won't get created and the chain will appear stuck.
When you restart your daemon, you need to kickstart the staking for this sole daemon (remember, it has no peers). Use the following command to start your daemon node.
The goal of this step is to let the node stake and wait for the block time to settle around the intended target time. Since Lynx has a 5-minute block time, you are waiting for the daemon to report this block time in the debug log consistently. The debug log contains a 'Block Statistics' report every 25 blocks. Wait for this report to appear in the debug log, and pay close attention to the 'last hour' section. In the case of Lynx, we are looking for a 300-second block time. Ideally, we should see several reports of this target block time. This process might take several hours - sometimes even a full 24 hours. Their is no rush, so waiting 24 hours is fine.
You can provision other daemons during this time and let them sync to your primary node. However, ensure you have deleted the blockchain history before you start the daemon. Sometimes, it's best to double-check for safety. If you don't, the nodes will sync, and the primary node will lose its history - overwritten by the longer blockchain history on the peer node. You will have to restart the process completely if this occurs.
Don't send any coins to other peers yet. You need to ensure the network block time has settled.
Step 8: Cleanup and Peer Staking
Send coins to peers so they can stake and stabilize the network.
By this time, you have provisioned other nodes, they have synced with your primary node, and your block time has settled to a relatively stable 300-second period. Those other nodes don't have any coins yet; this is good. Now, remove the startup parameters (-maxtipage=9999999999 -stakethreadignorepeers=1) on the primary node and restart Lynx. This will allow other nodes to start staking gracefully after they receive coins.
After a while, sending a small number of coins to peer nodes will be safe. The maturity time is 30 blocks, so keep this in mind when sending coins. You must start small so the primary staking node doesn't get stuck.
Sending too many coins too early will cause the node to get stuck. The reason the primary staking node would get stuck is complicated but understandable. When you created the primary staking node, you only created a limited number of addresses for staking. The coinbase reward requires 30 blocks to maturity before sending the coins to another address. If you generate a send transaction with immature coins, the daemon will hold the transaction in the mempool and remain in that state for up to 24 hours. This could lock up coins in a state that will disallow them to be used for staking - thus, the node will 'get stuck.' With staking enabled, this is a known issue when using a hot wallet on a Lynx node. The recommendation is to keep two nodes. One has no send transactions while staking is enabled, and another hot wallet node has staking disabled.
Step 9: Monitor your network
After you are able to see peer nodes win staking rewards and the distribution of staking effort becomes flattened across the network of nodes, you can consider your task complete.
Video Tutorial
The video below is long, but for our visual learners, it can illustrate the 8 steps for a deeper understanding of how to execute the process.
Last updated
