Resetting a Network
Creating a new chain or resetting a specific network can be tedious. The following guide should save you time.
Last updated
Creating a new chain or resetting a specific network can be tedious. The following guide should save you time.
Last updated
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.'
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
