This response will give a non-technical overview of Chia's light wallet syncing process. For technical info, see our docs site, as well as the FlyClient White Paper, which details the process from which Chia's light client is based.
First, a bit about addresses in Chia. A single Chia wallet can use up to four billion (2^32) addresses. Hopefully, you won't need more than that! Using multiple addresses can help provide anonymity. Rather than having to sign up for a new account each time you want to receive money, you can simply click "NEW ADDRESS" and presto -- a new address appears. Additionally, each time you receive change from sending money, a new address is automatically generated. Your wallet keeps track of each of the addresses that have been used. As long as your wallet is synced, it always knows how much money you have.
One important thing to remember is that your wallet addresses will always be generated in the same order. When you generate a "new" address, you're actually calculating the next address in the sequence. Your wallet doesn't know what the next address will be until it's generated, but the sequence will always be the same. For example, if you generate 50 new addresses (and write them down), and then install Chia on a new computer and import the same wallet, the first 50 addresses you generate will exactly match those from your original computer.
Next, we'll introduce a setting called
initial_num_public_keys. This setting is part of
config.yaml, located in
~/.chia/mainnet/config on Linux and MacOS, and
C:\Users\<username>\.chia\mainnet\config on Windows. The default value of this setting is 100. The majority of users should not change it.
You can think of
initial_num_public_keys as the number of future addresses to examine. It's a window that expands with time (and never contracts). Here's how it works:
The first time you run Chia's software, your wallet will attempt to sync. It does this by checking the first address in the sequence. If that address has ever received money, your wallet will account for that transaction history and examine the next address, and so on. It would take a very long time to examine all four billion addresses, so your wallet will stop looking at some point. This is where
initial_num_public_keys comes in.
By default, your wallet will stop after it has examined 100 straight addresses that have never received money. If it examines 50 empty addresses and then finds a transaction on the 51st address, the number left to examine is reset back to 100. Because the addresses always appear in the same sequence, it will be rare to have even a single address without any transaction history. But there is one exception: if you click "NEW ADDRESS" twice, then one address will remain unused. If you click "NEW ADDRESS" 101 times without receiving money at any of those addresses, then you'll have 100 consecutive unused addresses in the sequence. Let's say you receive money at the 101st address. When your wallet attempts to sync, it will stop looking after the 100th blank address. Transactions from subsequent addresses will remain undiscovered, and your balance will be incorrect.
The default setting for
initial_num_public_keys is quite conservative -- it should be rare for anyone to click "NEW ADDRESS" more than 100 times without actually using any of those addresses. That said, you might have a legitimate reason to do this, for example if you're running an exchange. In that case, feel free to set
initial_num_public_keys to a higher number, stop your wallet, delete your wallet database, and start your wallet again to begin a fresh sync.
Why not set
initial_num_public_keys to a higher number by default? Because it would take longer for your wallet to sync. Why not set it lower? If the default setting were 2, most wallets would likely still show the correct balance and the sync time would be faster. However, we set the default to 100 to prioritize showing the correct balance over syncing as fast as possible.
How does your wallet know it has the correct info for each address? It polls one or more of its peers. These peers can be either trusted or untrusted, as explained in the previous question. By default, your own node is the only one you trust. If your node is fully synced, then your wallet only needs to query your node to determine your transaction history for each address. If your node is not fully synced, then your wallet will query a number of peers about this info. If any of them lie, omit info, or disconnect in the middle of a query, your wallet will know because the responses won't all match.
If you believe your balance is incorrect, changing
initial_num_public_keys is unlikely to fix the problem. If at all possible, you should sync a full node, stop Chia, delete your wallet database, and start Chia again. This time, Chia will sync based on your own node alone. If this is not an option, then resyncing from untrustred nodes might fix the problem as well.