READ THE CODE

Inside Bitcoin

The code behind the network, with room to understand it.

Stable release v32.1bitcoin/bitcoin · f0de87f04062 ↗3,020 source files · 47.5 MB stored on the server440 file guides

Release published 2026-10-28 · Snapshot fetched 2026-11-01. Latest stable release at fetch time; development branches and Git history are excluded. Only the selected code window and visible folders load here.

24,296 bytes · SHA-256 e9765c13342a1715… · View upstream ↗

1#!/usr/bin/env python3
2# Copyright (c) 2015-present The Bitcoin Core developers
3# Distributed under the MIT software license, see the accompanying
4# file COPYING or http://www.opensource.org/licenses/mit-license.php.
5"""Test bitcoind with different proxy configuration.
6
7Test plan:
8- Start bitcoind's with different proxy configurations
9- Use addnode to initiate connections
10- Verify that proxies are connected to, and the right connection command is given
11- Proxy configurations to test on bitcoind side:
12    - `-proxy` (proxy everything)
13    - `-onion` (proxy just onions)
14    - `-proxyrandomize` Circuit randomization
15    - `-cjdnsreachable`
16- Proxy configurations to test on proxy side,
17    - support no authentication (other proxy)
18    - support no authentication + user/pass authentication (Tor)
19    - proxy on IPv6
20    - proxy over unix domain sockets
21
22- Create various proxies (as threads)
23- Create nodes that connect to them
24- Manipulate the peer connections using addnode (onetry) and observe effects
25- Test the getpeerinfo `network` field for the peer
26
27addnode connect to IPv4
28addnode connect to IPv6
29addnode connect to onion
30addnode connect to generic DNS name
31addnode connect to a CJDNS address
32
33- Test getnetworkinfo for each node
34
35- Test passing invalid -proxy
36- Test passing invalid -onion
37- Test passing invalid -i2psam
38- Test passing -onlynet=onion without -proxy or -onion
39- Test passing -onlynet=onion with -onion=0 and with -noonion
40- Test passing unknown -onlynet
41"""
42
43import os
44import socket
45import tempfile
46
47from test_framework.socks5 import Socks5Configuration, Socks5Command, Socks5Server, AddressType
48from test_framework.test_framework import BitcoinTestFramework
49from test_framework.util import assert_equal
50from test_framework.netutil import test_ipv6_local, test_unix_socket
51
52# Networks returned by RPC getpeerinfo.
53NET_UNROUTABLE = "not_publicly_routable"
54NET_IPV4 = "ipv4"
55NET_IPV6 = "ipv6"
56NET_ONION = "onion"
57NET_I2P = "i2p"
58NET_CJDNS = "cjdns"
59
60# Networks returned by RPC getnetworkinfo, defined in src/rpc/net.cpp::GetNetworksInfo()
61NETWORKS = frozenset({NET_IPV4, NET_IPV6, NET_ONION, NET_I2P, NET_CJDNS})
62
63# Use the shortest temp path possible since UNIX sockets may have as little as 92-char limit
64socket_path = tempfile.NamedTemporaryFile().name
65
66class ProxyTest(BitcoinTestFramework):
67    def set_test_params(self):
68        self.num_nodes = 7
69        self.setup_clean_chain = True
70
71    def setup_nodes(self):
72        self.have_ipv6 = test_ipv6_local()
73        self.have_unix_sockets = test_unix_socket()
74        # Create two proxies on different ports.
75        # Use port=0 to let the OS assign available ports, avoiding
76        # "address already in use" errors from concurrent tests.
77        # ... one unauthenticated
78        self.conf1 = Socks5Configuration()
79        self.conf1.addr = ('127.0.0.1', 0)
80        self.conf1.unauth = True
81        self.conf1.auth = False
82        # ... one supporting authenticated and unauthenticated (Tor)
83        self.conf2 = Socks5Configuration()
84        self.conf2.addr = ('127.0.0.1', 0)
85        self.conf2.unauth = True
86        self.conf2.auth = True
87        if self.have_ipv6:
88            # ... one on IPv6 with similar configuration
89            self.conf3 = Socks5Configuration()
90            self.conf3.af = socket.AF_INET6
91            self.conf3.addr = ('::1', 0)
92            self.conf3.unauth = True
93            self.conf3.auth = True
94        else:
95            self.log.warning("Testing without local IPv6 support")
96
97        if self.have_unix_sockets:
98            self.conf4 = Socks5Configuration()
99            self.conf4.af = socket.AF_UNIX
100            self.conf4.addr = socket_path
101            self.conf4.unauth = True
102            self.conf4.auth = True
103        else:
104            self.log.warning("Testing without local unix domain sockets support")
105
106        self.serv1 = Socks5Server(self.conf1)
107        self.serv1.start()
108        self.serv2 = Socks5Server(self.conf2)
109        self.serv2.start()
110        if self.have_ipv6:
111            self.serv3 = Socks5Server(self.conf3)
112            self.serv3.start()
113        if self.have_unix_sockets:
114            self.serv4 = Socks5Server(self.conf4)
115            self.serv4.start()
116
117        # We will not try to connect to this.
118        self.i2p_sam = ('127.0.0.1', 7656)
119
120        # Note: proxies are not used to connect to local nodes. This is because the proxy to
121        # use is based on CService.GetNetwork(), which returns NET_UNROUTABLE for localhost.
122        args = [
123            ['-listen', f'-proxy={self.conf1.addr[0]}:{self.conf1.addr[1]}','-proxyrandomize=1'],
124            ['-listen', f'-proxy={self.conf1.addr[0]}:{self.conf1.addr[1]}',f'-onion={self.conf2.addr[0]}:{self.conf2.addr[1]}',
125                f'-i2psam={self.i2p_sam[0]}:{self.i2p_sam[1]}', '-i2pacceptincoming=0', '-proxyrandomize=0'],
126            ['-listen', f'-proxy={self.conf2.addr[0]}:{self.conf2.addr[1]}','-proxyrandomize=1'],
127            [],
128            ['-listen', f'-proxy={self.conf1.addr[0]}:{self.conf1.addr[1]}','-proxyrandomize=1',
129                '-cjdnsreachable'],
130            [],
131            []
132        ]
133        if self.have_ipv6:
134            args[3] = ['-listen', f'-proxy=[{self.conf3.addr[0]}]:{self.conf3.addr[1]}','-proxyrandomize=0', '-noonion']
135        if self.have_unix_sockets:
136            args[5] = ['-listen', f'-proxy=unix:{socket_path}']
137            args[6] = ['-listen', f'-onion=unix:{socket_path}']
138        # This test launches many nodes; disable prevout prefetching so we don't spin up a
139        # thread pool for each one.
140        args = [a + ['-prevoutfetchthreads=0'] for a in args]
141        self.add_nodes(self.num_nodes, extra_args=args)
142        self.start_nodes()
143
144    def network_test(self, node, addr, network):
145        for peer in node.getpeerinfo():
146            if peer["addr"] == addr:
147                assert_equal(peer["network"], network)
148
149    def node_test(self, node, *, proxies, auth, test_onion, test_cjdns):
150        rv = []
151        addr = "15.61.23.23:1234"
152        self.log.debug(f"Test: outgoing IPv4 connection through node {node.index} for address {addr}")
153        # v2transport=False is used to avoid reconnections with v1 being scheduled. These could interfere with later checks.
154        node.addnode(addr, "onetry", v2transport=False)
155        cmd = proxies[0].queue.get()
156        assert isinstance(cmd, Socks5Command)
157        # Note: bitcoind's SOCKS5 implementation only sends atyp DOMAINNAME, even if connecting directly to IPv4/IPv6
158        assert_equal(cmd.atyp, AddressType.DOMAINNAME)
159        assert_equal(cmd.addr, b"15.61.23.23")
160        assert_equal(cmd.port, 1234)
161        if not auth:
162            assert_equal(cmd.username, None)
163            assert_equal(cmd.password, None)
164        rv.append(cmd)
165        self.network_test(node, addr, network=NET_IPV4)
166
167        if self.have_ipv6:
168            addr = "[1233:3432:2434:2343:3234:2345:6546:4534]:5443"
169            self.log.debug(f"Test: outgoing IPv6 connection through node {node.index} for address {addr}")
170            node.addnode(addr, "onetry", v2transport=False)
171            cmd = proxies[1].queue.get()
172            assert isinstance(cmd, Socks5Command)
173            # Note: bitcoind's SOCKS5 implementation only sends atyp DOMAINNAME, even if connecting directly to IPv4/IPv6
174            assert_equal(cmd.atyp, AddressType.DOMAINNAME)
175            assert_equal(cmd.addr, b"1233:3432:2434:2343:3234:2345:6546:4534")
176            assert_equal(cmd.port, 5443)
177            if not auth:
178                assert_equal(cmd.username, None)
179                assert_equal(cmd.password, None)
180            rv.append(cmd)
181            self.network_test(node, addr, network=NET_IPV6)
182
183        if test_onion:
184            addr = "pg6mmjiyjmcrsslvykfwnntlaru7p5svn6y2ymmju6nubxndf4pscryd.onion:8333"
185            self.log.debug(f"Test: outgoing onion connection through node {node.index} for address {addr}")
186            node.addnode(addr, "onetry", v2transport=False)
187            cmd = proxies[2].queue.get()
188            assert isinstance(cmd, Socks5Command)
189            assert_equal(cmd.atyp, AddressType.DOMAINNAME)
190            assert_equal(cmd.addr, b"pg6mmjiyjmcrsslvykfwnntlaru7p5svn6y2ymmju6nubxndf4pscryd.onion")
191            assert_equal(cmd.port, 8333)
192            if not auth:
193                assert_equal(cmd.username, None)
194                assert_equal(cmd.password, None)
195            rv.append(cmd)
196            self.network_test(node, addr, network=NET_ONION)
197
198        if test_cjdns:
199            addr = "[fc00:1:2:3:4:5:6:7]:8888"
200            self.log.debug(f"Test: outgoing CJDNS connection through node {node.index} for address {addr}")
201            node.addnode(addr, "onetry", v2transport=False)
202            cmd = proxies[1].queue.get()
203            assert isinstance(cmd, Socks5Command)
204            assert_equal(cmd.atyp, AddressType.DOMAINNAME)
205            assert_equal(cmd.addr, b"fc00:1:2:3:4:5:6:7")
206            assert_equal(cmd.port, 8888)
207            if not auth:
208                assert_equal(cmd.username, None)
209                assert_equal(cmd.password, None)
210            rv.append(cmd)
211            self.network_test(node, addr, network=NET_CJDNS)
212
213        addr = "node.noumenon:8333"
214        self.log.debug(f"Test: outgoing DNS name connection through node {node.index} for address {addr}")
215        node.addnode(addr, "onetry", v2transport=False)
216        cmd = proxies[3].queue.get()
217        assert isinstance(cmd, Socks5Command)
218        assert_equal(cmd.atyp, AddressType.DOMAINNAME)
219        assert_equal(cmd.addr, b"node.noumenon")
220        assert_equal(cmd.port, 8333)
221        if not auth:
222            assert_equal(cmd.username, None)
223            assert_equal(cmd.password, None)
224        rv.append(cmd)
225        self.network_test(node, addr, network=NET_UNROUTABLE)
226
227        return rv
228
229    def run_test(self):
230        # basic -proxy
231        self.node_test(self.nodes[0],
232            proxies=[self.serv1, self.serv1, self.serv1, self.serv1],
233            auth=False, test_onion=True, test_cjdns=False)
234
235        # -proxy plus -onion
236        self.node_test(self.nodes[1],
237            proxies=[self.serv1, self.serv1, self.serv2, self.serv1],
238            auth=False, test_onion=True, test_cjdns=False)
239
240        # -proxy plus -onion, -proxyrandomize
241        rv = self.node_test(self.nodes[2],
242            proxies=[self.serv2, self.serv2, self.serv2, self.serv2],
243            auth=True, test_onion=True, test_cjdns=False)
244        # Check that credentials as used for -proxyrandomize connections are unique
245        credentials = set((x.username,x.password) for x in rv)
246        assert_equal(len(credentials), len(rv))
247
248        if self.have_ipv6:
249            # proxy on IPv6 localhost
250            self.node_test(self.nodes[3],

src/wallet/receive.cpp

src/wallet/coinselection.cpp

src/consensus/validation.h

src/primitives/transaction.cpp

src/script/descriptor.cpp

src/bitcoin-cli.cpp

src/rpc/blockchain.cpp

src/rpc/rawtransaction.cpp

src/init.cpp

src/crypto/sha256.cpp

src/consensus/merkle.h

src/consensus/tx_check.h

src/consensus/tx_verify.h

src/policy/feerate.h

src/policy/feerate.cpp

src/primitives/transaction_identifier.h

src/chainparamsbase.h

src/chainparamsbase.cpp

src/util/moneystr.cpp

src/crypto/ripemd160.h

src/crypto/sha1.h

src/crypto/sha512.h

src/crypto/hmac_sha256.h

src/crypto/hmac_sha512.h

src/crypto/hmac_sha256.cpp

src/crypto/hmac_sha512.cpp

src/crypto/hkdf_sha256_32.h

src/crypto/hkdf_sha256_32.cpp

src/support/cleanse.h

src/support/cleanse.cpp

src/crypto/siphash.cpp

src/crypto/muhash.h

src/crypto/chacha20.h

src/crypto/poly1305.h

src/crypto/chacha20poly1305.h

src/crypto/chacha20poly1305.cpp

src/util/chaintype.cpp

src/util/obfuscation.h

src/util/byte_units.h

src/util/overflow.h

src/blockencodings.cpp

src/net_permissions.cpp

src/policy/packages.cpp

src/policy/rbf.cpp

src/policy/truc_policy.cpp

src/policy/ephemeral_policy.cpp

src/policy/settings.cpp

src/policy/policy.cpp

src/node/transaction.cpp

src/node/coin.cpp

src/rpc/client.cpp

src/rpc/external_signer.cpp

src/rpc/request.cpp

src/rpc/server_util.cpp

src/rpc/fees.cpp

src/rpc/output_script.cpp

src/rpc/rawtransaction_util.cpp

src/rpc/rawtransaction_util.h

src/rpc/register.h

src/rpc/request.h

src/rpc/server_util.h

src/rpc/protocol.h

src/rpc/server.h

src/rpc/signmessage.cpp

src/rpc/txoutproof.cpp

src/rpc/util.cpp

src/rpc/util.h

src/wallet/rpc/addresses.cpp

src/wallet/rpc/backup.cpp

src/wallet/rpc/coins.cpp

src/wallet/rpc/encrypt.cpp

src/wallet/rpc/signmessage.cpp

src/wallet/rpc/util.cpp

src/wallet/rpc/util.h

src/wallet/coincontrol.cpp

src/wallet/coincontrol.h

src/wallet/context.cpp

src/wallet/context.h

src/wallet/crypter.cpp

src/wallet/crypter.h

src/wallet/db.cpp

src/wallet/export.cpp

src/wallet/external_signer_scriptpubkeyman.cpp

src/wallet/rpc/spend.cpp

src/wallet/rpc/transactions.cpp

src/wallet/rpc/wallet.cpp

src/wallet/feebumper.cpp

src/wallet/feebumper.h

src/index/base.h

src/index/base.cpp

src/index/txindex.h

src/index/txindex.cpp

src/index/txindex_key.h

src/index/txospenderindex.h

src/index/txospenderindex.cpp

src/index/blockfilterindex.h

src/index/blockfilterindex.cpp

src/index/coinstatsindex.h

src/index/coinstatsindex.cpp

src/index/db_key.h

src/index/disktxpos.h

src/kernel/chain.cpp

src/kernel/chain.h

src/kernel/checks.cpp

src/kernel/checks.h

src/kernel/context.cpp

src/kernel/context.h

src/kernel/cs_main.cpp

src/kernel/cs_main.h

src/kernel/disconnected_transactions.cpp

src/kernel/disconnected_transactions.h

src/kernel/mempool_removal_reason.cpp

src/kernel/mempool_removal_reason.h

src/kernel/coinstats.cpp

src/kernel/coinstats.h

src/kernel/chainparams.cpp

src/kernel/chainparams.h

src/wallet/sqlite.cpp

src/wallet/sqlite.h

src/wallet/transaction.cpp

src/wallet/transaction.h

src/wallet/dump.cpp

src/wallet/dump.h

src/wallet/init.cpp

src/wallet/walletutil.cpp

src/wallet/walletutil.h

src/wallet/wallettool.cpp

src/wallet/wallettool.h

src/wallet/export.h

src/wallet/migrate.cpp

src/wallet/migrate.h

src/wallet/db.h

src/wallet/walletdb.cpp

src/wallet/interfaces.cpp

src/wallet/scriptpubkeyman.cpp

src/wallet/scriptpubkeyman.h

src/kernel/bitcoinkernel.cpp

src/kernel/bitcoinkernel.h

src/kernel/bitcoinkernel_wrapper.h

src/node/chainstate.cpp

src/node/chainstate.h

src/node/blockstorage.cpp

src/node/blockstorage.h

src/node/mempool_persist.cpp

src/node/mempool_persist.h

src/node/utxo_snapshot.cpp

src/node/utxo_snapshot.h

src/node/kernel_notifications.cpp

src/node/kernel_notifications.h

src/node/blockmanager_args.cpp

src/kernel/blockmanager_opts.h

src/util/expected.cpp

src/policy/settings.h

src/util/types.h

src/kernel/messagestartchars.h

src/kernel/warning.h

src/util/exception.h

src/common/license_info.h

src/node/coins_view_args.h

src/node/database_args.h

src/util/batchpriority.h

src/util/ui_change_type.h

src/node/coins_view_args.cpp

src/node/peerman_args.h

src/util/serfloat.h

src/node/blockmanager_args.h

src/node/database_args.cpp

src/util/overloaded.h

src/interfaces/types.h

src/node/chainstatemanager_args.h

src/node/minisketchwrapper.h

src/util/macros.h

src/util/syserror.h

src/common/run_command.h

src/util/bytevectorhash.cpp

src/node/mempool_persist_args.cpp

src/util/exec.h

src/util/rbf.h

src/crypto/hex_base.h

src/node/mempool_persist_args.h

src/interfaces/echo.h

src/util/any.h

src/util/batchpriority.cpp

src/util/threadnames.h

src/node/coin.h

src/node/mempool_args.h

src/util/asmap.h

src/util/bytevectorhash.h

src/node/context.cpp

src/util/insert.h

src/util/readwritefile.h

src/node/peerman_args.cpp

src/node/interface_ui.cpp

src/interfaces/handler.h

src/node/mining_args.h

src/util/hasher.cpp

src/common/init.h

src/kernel/mempool_limits.h

src/common/system.h

src/crypto/sha3.h

src/util/threadinterrupt.cpp

src/node/protocol_version.h

src/util/exception.cpp

src/common/messages.h

src/node/connection_types.cpp

src/util/bip32.h

src/common/license_info.cpp

src/util/stdmutex.h

src/common/run_command.cpp

src/util/check.cpp

src/util/golombrice.h

src/node/types.h

src/node/timeoffsets.h

src/util/readwritefile.cpp

src/util/fastrange.h

src/util/signalinterrupt.h

src/util/task_runner.h

src/util/syserror.cpp

src/common/interfaces.cpp

src/common/types.h

src/util/threadinterrupt.h

src/kernel/chainstatemanager_opts.h

src/node/psbt.h

src/policy/ephemeral_policy.h

src/util/trace.h

src/common/url.cpp

src/kernel/mempool_options.h

src/util/serfloat.cpp

src/kernel/notifications_interface.h

src/node/timeoffsets.cpp

src/node/warnings.cpp

src/util/hash_type.h

src/crypto/hex_base.cpp

src/node/eviction.h

src/util/tokenbucket.h

src/crypto/aes.h

src/common/pcp.h

src/util/feefrac.cpp

src/node/transaction.h

src/util/threadnames.cpp

src/common/signmessage.h

src/util/exec.cpp

src/util/signalinterrupt.cpp

src/clientversion.cpp

src/common/signmessage.cpp

src/compat/assumptions.h

src/compat/byteswap.h

src/deploymentinfo.cpp

src/deploymentinfo.h

src/deploymentstatus.cpp

src/deploymentstatus.h

src/dummywallet.cpp

src/external_signer.h

src/init/bitcoin-gui.cpp

src/init/bitcoin-node.cpp

src/init/bitcoin-qt.cpp

src/init/bitcoin-wallet.cpp

src/init/bitcoind.cpp

src/init/common.h

src/interfaces/init.h

src/interfaces/ipc.h

src/key_io.h

src/logging/categories.h

src/logging/timer.h

src/mapport.h

src/musig.h

src/net_permissions.h

src/netgroup.h

src/netmessagemaker.h

src/node/chainstatemanager_args.cpp

src/node/connection_types.h

src/node/context.h

src/node/interface_ui.h

src/node/mempool_args.cpp

src/node/mining_args.cpp

src/node/minisketchwrapper.cpp

src/node/txreconciliation.h

src/policy/fees/estimator_args.cpp

src/policy/fees/estimator_args.h

src/policy/fees/estimator_man.cpp

src/policy/fees/estimator_man.h

src/policy/packages.h

src/policy/rbf.h

src/policy/truc_policy.h

src/pow.h

src/primitives/block.cpp

src/randomenv.h

src/rest.h

src/script/keyorigin.h

src/script/parsing.cpp

src/script/parsing.h

src/script/script_error.h

src/script/sigcache.cpp

src/script/sigcache.h

src/script/solver.h

src/script/verify_flags.h

src/semaphore_grant.h

src/signet.h

src/span.h

src/support/allocators/secure.h

src/support/allocators/zeroafterfree.h

src/util/tokenpipe.cpp

src/util/translation.h

src/util/vector.h

src/versionbits.h

src/versionbits_impl.h

src/wallet/external_signer_scriptpubkeyman.h

src/wallet/fees.h

src/wallet/load.h

src/wallet/receive.h

src/wallet/rpc/wallet.h

src/wallet/types.h

src/walletinitinterface.h

src/zmq/zmqabstractnotifier.cpp

Independent explanations by MyBitcoinExplorer. Not affiliated with or endorsed by Bitcoin Core. Guides are educational and do not replace the source or its tests.

Bitcoin Core source © its contributors, distributed under the MIT license. Original notices and bundled third-party licenses are retained in the source tree.