-
Notifications
You must be signed in to change notification settings - Fork 0
Wallet Connection Guide
The goal of this guide is to help resolving the most common issues with connecting your cryptocurrency wallet to the respective network, i.e. to resolve syncing issues. This tutorial is an ongoing work-in-progress, additions or corrections are welcome.
We will consider the following root causes. If in doubt, please check them all one by one in order to eliminate all possible issues.
- No internet connection
- You are using an old version of the wallet
- Desktop firewall or antivirus blocking the connection
- Outgoing connections on non-standard ports are blocked by the network
- No known network nodes
- Incoming connections are blocked by the network
- Your chain has forked, or your configuration is broken in some other way
- The coin is dead
- Traffic is blocked by deep-packet-inspection / censorship
- Your node is misbehaving because of a programming error
If nothing else helps, try making a new data directory.
Obviously, you can only connect to other nodes if you have working internet access. Before doing anything else, please verify that the internet connection of your PC (or whatever device you are running your wallet on) works and is stable, i.e. it does not collapse frequently. If it is not stable, try running your wallet on a different device or network.
Make sure you are running the latest version of the wallet. You will usually find an up-to-date download link in the OP (the opening post of the ANN thread, which is the Announcement thread for your coin)), or on the website of your coin. Only download the wallet from an official source, not from some random dude sending you a binary file (it could contain a virus!).
-
Windows: Make sure that neither your antivirus, desktop firewall or Windows firewall are blocking your connection. (TODO: Add more details)
-
Linux: The default firewall rules on almost all Linux distributions are to allow everything; If you had created your own firewall rules, you'd probably know it. In that case, make sure that the connections on the required ports are allowed.
First, we want to check that outgoing connections on non-standard ports work for you in general. Please visit the following URL: http://portquiz.net:54321 If the site loads successfully, then chances are good that your outgoing connections are not blocked, so you can skip this step and move to the next section.
If the site does not load, there may be different reasons:
-
If you are on a public or corporate network, only standard ports may be allowed. Unless your wallet supports tunneling over common ports (most don't), this issue might not be easily resolvable. Try using a different network.
-
If you are on your home network, check that your router's settings do not restrict outgoing connections. For the typical home user, this does not provide any meaningful security advantage, so you can just allow all outgoing connections.
-
If you are using a VPN, that could be another reason because your VPN software may block traffic on non-standard ports for security reasons. In that case, try to whitelist the port or contact your VPN provider.
If you haven't powered up your wallet in a long time, it might happen that all hardcoded nodes (the "default" nodes) are offline by now, and newer ones have been added. This is especially the case if your wallet complains about "No connections". To solve this, you need to add the IP addresses of a few nodes in the network. This is the so called node list. There are multiple ways to get an up-to-date node list:
- Check the OP (opening post, the first post in the ANN thread (which is the Announcement thread for your coin)) for a node list.
- Ask other community members on a forum, Slack, chat etc.
- Many "blockchain explorers" also publish a node list. Look for the address of the block explorer in the OP or on CoinMarketCap. When you are on the explorer site, look for a "Network" section or something similar.
If you have the node list, you may notice that it has a strange syntax that looks like this:
addnode=1.2.3.4.5
addnode=23.14.11.1
addnode=5.33.53.4
...
This list is meant to be copied and pasted into the .conf file of your wallet. The .conf file is located in the data directory of your wallet.
- If you are on Windows, press WindowsKey+R and type %APPDATA% and press Enter. You should now somewhere see the name of your coin.
- Under Linux, the data directory will be a hidden file starting with a dot (.). Go to your home directory and press Ctrl-H. Look for a directory that sounds like your coin.
If you can't seem to find the data directory, ask someone who knows where it is.
Enter this directory and open the .conf file you see there, e.g. "Bitcoin.conf". Paste the node list at the end of the file, and save the file. Then restart your wallet.
If there is no .conf file, it might be because the code of your wallet is very old (like, stone age in terms of cryptocurrencies). In that case, or if you don't want to restart your wallet, you might want to add the nodes manually via the Debug console. Open the debug console, and type for each line in your node list:
addnode 23.14.11.1 add
and press Enter. Replace the IP addresses accordingly.
Wait a moment for the connection to be established. You should now see your number of connections increasing.
Incoming connections are, in general, not required for syncing, because your wallet will try to connect to known nodes (see the previous step) on its own, which only requires an outgoing connection. However, it is still a good idea to allow incoming connections on the ports of your wallet, to increase reliability and the number of your connections.
If you are on a public or corporate network, incoming connections will probably be blocked. There is no way for you to fix this. Try switching to a different network. But again, this is generally not required, it only improves your connection to other nodes.
If you are in your home network, there are two ways to make this work:
-
Enable UPnP. UPnP opens the required ports automatically when needed. This is the preferred option if you are not a computer professional. Maybe UPnP is already enabled on your router by default, so first check whether it already works (see further down). If it doesn't work, you'll have to find out how to enable UPnP on your router model.
-
Forward the ports manually. This is especially handy if you like to have some control over which applications on your network are reachable from the outside.
-
First, we need to find out the port number that your wallet uses. There are many ways to do so:
- look at the OP (opening post of the ANN, which is the Announcement thread of your coin))
- look at the website in the help section, FAQ etc.
- ask other community members on a forum (e.g. bitcointalk.org), chat, Slack etc.
- PM or mail the dev himself
- look into the source code (if you know what to look for)
- run your favorite network analysis tool while the wallet is running (e.g. 'netstat -tulpn' on Linux)
-
Create a new port forwarding rule on your router. You need to make a rule for the port you found out in the previous step, for the TCP protocol, and allow it in both directions (inbound and outbound). You'll have to find out how to do this on your router model, for example by looking into the manual.
-
After you have ensured that connection requests are forwarded from your router to your PC (either by UPnP or through manual port forwarding), you also have to make sure that your system firewall (especially on Windows operating systems) or your antivirus don't block incoming connections. See the section about firewalls.
Finally, verify that the port is open. Start the wallet, then go to this page and put in the port number your wallet uses: http://canyouseeme.org/ Click on "Check port". You should see a success message now.
If your syncing seems to be "stuck", even though you have added nodes and checked that your outgoing connections on non-standard ports work, it could be because your wallet is on a different chain than everybody else in the network. This is relatively rare, but can happen.
Similarly, sometimes you might have messed around with your configuration and everything is broken now.
To solve these problems, see making a new data directory.
If you can't find a node list and don't get any connections, it might be simply that there are no nodes in the network any more. Which means that the network is dead, nobody is using it any more. You could run the blockchain on your own, but that wouldn't make a lot of sense. You can make a post on bitcointalk or try to contact other people if you really want to revive the network.
If you are in China, then you probably know that all kinds of stuff are being blocked. Also, if your wallet is utilizing the Tor network, or if you are using a VPN, some corporate networks might try to detect and block it using a technique called deep packet inspection. That is serious censorship, and circumventing it is way past the scope of this guide.
There may be rare cases when you are doing everything right, but your wallet functions differently than anybody else on the network because of a bug (a programming error) that only happens on your system and those of a few other unlucky individuals. You can detect this if you look at the "debug.log" file in the data directory, and see a lot of clients disconnecting from you after a short amount of time.
The only time I saw this in reality was (coincidentally on my own system) when the code used non-checked floating-point arithmetic to produce fixed integer values, which were different on my system than most other people's because the compiler didn't enable SSE on my platform by default ... Programming errors like these can be very difficult to find. Head to the developer, or try to debug the problem on your own if you are a computer professional yourself.
If nothing else helps, you can try making a new data directory. That way, everything will be as if you were running the wallet for the first time, i.e. a new config file will be generated and the whole program will start syncing from scratch. Follow these steps:
-
Close the wallet.
-
Go to the data directory of your coin.
- If you are on Windows, press WindowsKey+R and type %APPDATA% and press Enter. You should now somewhere see the name of your coin.
- Under Linux, the data directory will be a hidden file starting with a dot (.). Go to your home directory and press Ctrl-H. Look for a directory that sounds like your coin.
If you can't seem to find the data directory, ask someone who knows where it is.
-
Rename the data directory. For example, if the old data directory in APPDATA is called "Bitcoin", rename it to "Bitcoin-old". By doing this, the wallet can't find it any more and will use the new data directory we'll be creating now:
-
Create a new, empty directory that has the same name as before, e.g. 'Bitcoin', without the '-old'. It needs to be exactly the same name as before, including capitalization.
-
Copy the file "wallet.dat" from Bitcoin-old to Bitcoin (replace with the actual name of your coin). Wallet.dat contains your private keys, so that you will have your funds again in the new wallet. If you don't have any funds yet because you have never received any coins, and never gave your address to anyone, you can skip this step.
-
Start the wallet again. You should now see that it starts syncing from scratch. This will hopefully continue until you are fully synced. If you see your balance being zero right now, don't panic, it will come back if you have copied the old wallet.dat. :)
-
After your wallet has synced completely and your balance is there, and you have verified that everything works, you can remove the old data directory which is called "Bitcoin-old" (or whatever you named it in step 3).