IBC#033: Bitcoin Core Initialization, Step 12: Onion Services

Hello everyone and welcome to this new episode of Inside Bitcoin Code.

We concluded the previous episode with discussing about port bindings. Today, we continue our deep dive into step 12 of the initialization of Bitcoin Core, discussing about Tor services. [Code Link]

Let’s start!

---

Onion Service Target

First of all, the code defines a CService object — a combination of a network address and a port number — which will store the local address Bitcoin Core should use for its Tor hidden service.

CService onion_service_target;

Then, the program tries three different options to choose which local address will receive Tor traffic, by explicitly setting an onion bind address, using the first bind address provided by the user, or setting a default generated address.

First, it checks that the onion_binds vector in not empty().
If so, it takes the address at the front() of the vector — the first one.

if (!connOptions.onion_binds.empty()) {
    onion_service_target = connOptions.onion_binds.front();
}

Otherwise, it looks into the vBinds vector. In case it is not empty(), the variable onion_service_target is assigned the address value at the front() of the vector.

else if (!connOptions.vBinds.empty()) {
    onion_service_target = connOptions.vBinds.front();
}

Finally, if neither of the two previous options is available, the onion_service_target variable is assigned a default address generated by the DefaultOnionServiceTarget function.
The address is the added to the onion_binds vector.

else {
    onion_service_target = DefaultOnionServiceTarget(default_bind_port_onion);
    connOptions.onion_binds.push_back(onion_service_target);
}

---

Consider supporting this newsletter by using one of my affiliate links. These are not sponsorships, just products I use everyday. Thank you!

---

Launching Tor Control

Once the onion_service_target is filled with the Tor address, the code checks whether the -listenonion input argument has been set to 1 by the user.

if (args.GetBoolArg("-listenonion", DEFAULT_LISTEN_ONION))

Before creating the Tor onion service, the program checks that there is not more than one address provided.

if (connOptions.onion_binds.size() > 1)

If that is the case, a warning is sent to the user, stating that only the one provided by the onion_service_target variable will be used.

InitWarning(strprintf(_(
    "More than one onion bind address is provided. Using %s "
    "for the automatically created Tor onion service."),
    onion_service_target.ToStringAddrPort()
));

Finally, the StartTorControl() function is called.
This function launches the torcontrol thread, which instructs Tor to create a hidden service that points to the chosen onion_service_target address.
This allows external Tor users to connect to Bitcoin Core via an .onion address without knowing the node's IP.

StartTorControl(onion_service_target);

---

Affiliate Program

Ready to Lead the Change*? If you are looking to professionalize your journey in the Bitcoin ecosystem, the Plan B Network provides the ultimate educational framework. Whether you are aiming to build the next major startup or dive deep into the protocol's code, they have a Master track for you. Use my code* SS_Varese at checkout to receive 15% OFF on both the Business and Developers tracks!

---

Let’s keep in touch:

• Follow me on Nostr and X
• Check out my writings on btc++ insider edition
• Try my new app Sats Tracker, an expense tracker app for people living in the Bitcoin standard. Available on Zapstore!