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.

13,461 bytes · SHA-256 0ba6bfc9495623bd… · View upstream ↗

1#!/usr/bin/env python3
2# Copyright (c) 2022-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"""Class for v2 P2P protocol (see BIP 324)"""
6
7import random
8
9from .crypto.bip324_cipher import FSChaCha20Poly1305
10from .crypto.chacha20 import FSChaCha20
11from .crypto.ellswift import ellswift_create, ellswift_ecdh_xonly
12from .crypto.hkdf import hkdf_sha256
13from .key import TaggedHash
14from .messages import MAGIC_BYTES
15from .util import assert_equal
16
17
18CHACHA20POLY1305_EXPANSION = 16
19HEADER_LEN = 1
20IGNORE_BIT_POS = 7
21LENGTH_FIELD_LEN = 3
22MAX_GARBAGE_LEN = 4095
23
24SHORTID = {
25    1: b"addr",
26    2: b"block",
27    3: b"blocktxn",
28    4: b"cmpctblock",
29    5: b"feefilter",
30    6: b"filteradd",
31    7: b"filterclear",
32    8: b"filterload",
33    9: b"getblocks",
34    10: b"getblocktxn",
35    11: b"getdata",
36    12: b"getheaders",
37    13: b"headers",
38    14: b"inv",
39    15: b"mempool",
40    16: b"merkleblock",
41    17: b"notfound",
42    18: b"ping",
43    19: b"pong",
44    20: b"sendcmpct",
45    21: b"tx",
46    22: b"getcfilters",
47    23: b"cfilter",
48    24: b"getcfheaders",
49    25: b"cfheaders",
50    26: b"getcfcheckpt",
51    27: b"cfcheckpt",
52    28: b"addrv2",
53    37: b"feature",
54}
55
56# Dictionary which contains short message type ID for the P2P message
57MSGTYPE_TO_SHORTID = {msgtype: shortid for shortid, msgtype in SHORTID.items()}
58
59
60class EncryptedP2PState:
61    """A class for managing the state when v2 P2P protocol is used. Performs initial v2 handshake and encrypts/decrypts
62    P2P messages. P2PConnection uses an object of this class.
63
64
65    Args:
66        initiating (bool): defines whether the P2PConnection is an initiator or responder.
67            - initiating = True for inbound connections in the test framework   [TestNode <------- P2PConnection]
68            - initiating = False for outbound connections in the test framework [TestNode -------> P2PConnection]
69
70        net (string): chain used (regtest, signet etc..)
71
72    Methods:
73        perform an advanced form of diffie-hellman handshake to instantiate the encrypted transport. before exchanging
74        any P2P messages, 2 nodes perform this handshake in order to determine a shared secret that is unique to both
75        of them and use it to derive keys to encrypt/decrypt P2P messages.
76            - initial v2 handshakes is performed by: (see BIP324 section #overall-handshake-pseudocode)
77                1. initiator using initiate_v2_handshake(), complete_handshake() and authenticate_handshake()
78                2. responder using respond_v2_handshake(), complete_handshake() and authenticate_handshake()
79            - initialize_v2_transport() sets various BIP324 derived keys and ciphers.
80
81        encrypt/decrypt v2 P2P messages using v2_enc_packet() and v2_receive_packet().
82    """
83    def __init__(self, *, initiating, net):
84        self.initiating = initiating  # True if initiator
85        self.net = net
86        self.peer = {}  # object with various BIP324 derived keys and ciphers
87        self.privkey_ours = None
88        self.ellswift_ours = None
89        self.sent_garbage = b""
90        self.received_garbage = b""
91        self.received_prefix = b""  # received ellswift bytes till the first mismatch from 16 bytes v1_prefix
92        self.tried_v2_handshake = False  # True when the initial handshake is over
93        # stores length of packet contents to detect whether first 3 bytes (which contains length of packet contents)
94        # has been decrypted. set to -1 if decryption hasn't been done yet.
95        self.contents_len = -1
96        self.found_garbage_terminator = False
97        self.transport_version = b''
98
99    @staticmethod
100    def v2_ecdh(priv, ellswift_theirs, ellswift_ours, initiating):
101        """Compute BIP324 shared secret.
102
103        Returns:
104        bytes - BIP324 shared secret
105        """
106        ecdh_point_x32 = ellswift_ecdh_xonly(ellswift_theirs, priv)
107        if initiating:
108            # Initiating, place our public key encoding first.
109            return TaggedHash("bip324_ellswift_xonly_ecdh", ellswift_ours + ellswift_theirs + ecdh_point_x32)
110        else:
111            # Responding, place their public key encoding first.
112            return TaggedHash("bip324_ellswift_xonly_ecdh", ellswift_theirs + ellswift_ours + ecdh_point_x32)
113
114    def generate_keypair_and_garbage(self, garbage_len=None):
115        """Generates ellswift keypair and 4095 bytes garbage at max"""
116        self.privkey_ours, self.ellswift_ours = ellswift_create()
117        if garbage_len is None:
118            garbage_len = random.randrange(MAX_GARBAGE_LEN + 1)
119        self.sent_garbage = random.randbytes(garbage_len)
120        return self.ellswift_ours + self.sent_garbage
121
122    def initiate_v2_handshake(self):
123        """Initiator begins the v2 handshake by sending its ellswift bytes and garbage
124
125        Returns:
126        bytes - bytes to be sent to the peer when starting the v2 handshake as an initiator
127        """
128        return self.generate_keypair_and_garbage()
129
130    def respond_v2_handshake(self, response):
131        """Responder begins the v2 handshake by sending its ellswift bytes and garbage. However, the responder
132        sends this after having received at least one byte that mismatches 16-byte v1_prefix.
133
134        Returns:
135        1. int - length of bytes that were consumed so that recvbuf can be updated
136        2. bytes - bytes to be sent to the peer when starting the v2 handshake as a responder.
137                 - returns b"" if more bytes need to be received before we can respond and start the v2 handshake.
138                 - returns -1 to downgrade the connection to v1 P2P.
139        """
140        v1_prefix = MAGIC_BYTES[self.net] + b'version\x00\x00\x00\x00\x00'
141        while len(self.received_prefix) < 16:
142            byte = response.read(1)
143            # return b"" if we need to receive more bytes
144            if not byte:
145                return len(self.received_prefix), b""
146            self.received_prefix += byte
147            if self.received_prefix[-1] != v1_prefix[len(self.received_prefix) - 1]:
148                return len(self.received_prefix), self.generate_keypair_and_garbage()
149        # return -1 to decide v1 only after all 16 bytes processed
150        return len(self.received_prefix), -1
151
152    def complete_handshake(self, response):
153        """ Instantiates the encrypted transport and
154        sends garbage terminator + optional decoy packets + transport version packet.
155        Done by both initiator and responder.
156
157        Returns:
158        1. int - length of bytes that were consumed. returns 0 if all 64 bytes from ellswift haven't been received yet.
159        2. bytes - bytes to be sent to the peer when completing the v2 handshake
160        """
161        ellswift_theirs = self.received_prefix + response.read(64 - len(self.received_prefix))
162        # return b"" if we need to receive more bytes
163        if len(ellswift_theirs) != 64:
164            return 0, b""
165        ecdh_secret = self.v2_ecdh(self.privkey_ours, ellswift_theirs, self.ellswift_ours, self.initiating)
166        self.initialize_v2_transport(ecdh_secret)
167        # Send garbage terminator
168        msg_to_send = self.peer['send_garbage_terminator']
169        # Optionally send decoy packets after garbage terminator.
170        aad = self.sent_garbage
171        for decoy_content_len in [random.randint(1, 100) for _ in range(random.randint(0, 10))]:
172            msg_to_send += self.v2_enc_packet(decoy_content_len * b'\x00', aad=aad, ignore=True)
173            aad = b''
174        # Send version packet.
175        msg_to_send += self.v2_enc_packet(self.transport_version, aad=aad)
176        return 64 - len(self.received_prefix), msg_to_send
177
178    def authenticate_handshake(self, response):
179        """ Ensures that the received optional decoy packets and transport version packet are authenticated.
180        Marks the v2 handshake as complete. Done by both initiator and responder.
181
182        Returns:
183        1. int - length of bytes that were processed so that recvbuf can be updated
184        2. bool - True if the authentication was successful/more bytes need to be received and False otherwise
185        """
186        processed_length = 0
187
188        # Detect garbage terminator in the received bytes
189        if not self.found_garbage_terminator:
190            received_garbage = response[:16]
191            response = response[16:]
192            processed_length = len(received_garbage)
193            for i in range(MAX_GARBAGE_LEN + 1):
194                if received_garbage[-16:] == self.peer['recv_garbage_terminator']:
195                    # Receive, decode, and ignore version packet.
196                    # This includes skipping decoys and authenticating the received garbage.
197                    self.found_garbage_terminator = True
198                    self.received_garbage = received_garbage[:-16]
199                    break
200                else:
201                    # don't update recvbuf since more bytes need to be received
202                    if len(response) == 0:
203                        return 0, True
204                    received_garbage += response[:1]
205                    processed_length += 1
206                    response = response[1:]
207            else:
208                # disconnect since garbage terminator was not seen after 4 KiB of garbage.
209                return processed_length, False
210
211        # Process optional decoy packets and transport version packet
212        while not self.tried_v2_handshake:
213            length, contents = self.v2_receive_packet(response, aad=self.received_garbage)
214            if length == -1:
215                return processed_length, False
216            elif length == 0:
217                return processed_length, True
218            processed_length += length
219            self.received_garbage = b""
220            # decoy packets have contents = None. v2 handshake is complete only when version packet
221            # (can be empty with contents = b"") with contents != None is received.
222            if contents is not None:
223                assert_equal(contents, b"")  # currently TestNode sends an empty version packet
224                self.tried_v2_handshake = True
225                return processed_length, True
226            response = response[length:]
227
228    def initialize_v2_transport(self, ecdh_secret):
229        """Sets the peer object with various BIP324 derived keys and ciphers."""
230        peer = {}
231        salt = b'bitcoin_v2_shared_secret' + MAGIC_BYTES[self.net]
232        for name in ('initiator_L', 'initiator_P', 'responder_L', 'responder_P', 'garbage_terminators', 'session_id'):
233            peer[name] = hkdf_sha256(salt=salt, ikm=ecdh_secret, info=name.encode('utf-8'), length=32)
234        if self.initiating:
235            self.peer['send_L'] = FSChaCha20(peer['initiator_L'])
236            self.peer['send_P'] = FSChaCha20Poly1305(peer['initiator_P'])
237            self.peer['send_garbage_terminator'] = peer['garbage_terminators'][:16]
238            self.peer['recv_L'] = FSChaCha20(peer['responder_L'])
239            self.peer['recv_P'] = FSChaCha20Poly1305(peer['responder_P'])
240            self.peer['recv_garbage_terminator'] = peer['garbage_terminators'][16:]
241        else:
242            self.peer['send_L'] = FSChaCha20(peer['responder_L'])
243            self.peer['send_P'] = FSChaCha20Poly1305(peer['responder_P'])
244            self.peer['send_garbage_terminator'] = peer['garbage_terminators'][16:]
245            self.peer['recv_L'] = FSChaCha20(peer['initiator_L'])
246            self.peer['recv_P'] = FSChaCha20Poly1305(peer['initiator_P'])
247            self.peer['recv_garbage_terminator'] = peer['garbage_terminators'][:16]
248        self.peer['session_id'] = peer['session_id']
249
250    def v2_enc_packet(self, contents, aad=b'', ignore=False):

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.