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 server340 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.

23,481 bytes · SHA-256 689755678f69d31a… · View upstream ↗

1// Copyright (c) 2009-2010 Satoshi Nakamoto
2// Copyright (c) 2009-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
6#ifndef BITCOIN_STREAMS_H
7#define BITCOIN_STREAMS_H
8
9#include <serialize.h>
10#include <span.h>
11#include <support/allocators/zeroafterfree.h>
12#include <util/check.h>
13#include <util/log.h>
14#include <util/obfuscation.h>
15#include <util/overflow.h>
16#include <util/syserror.h>
17
18#include <algorithm>
19#include <cassert>
20#include <cstddef>
21#include <cstdint>
22#include <cstdio>
23#include <cstring>
24#include <ios>
25#include <limits>
26#include <optional>
27#include <string>
28#include <vector>
29
30/* Minimal stream for overwriting and/or appending to an existing byte vector
31 *
32 * The referenced vector will grow as necessary
33 */
34class VectorWriter
35{
36public:
37/*
38 * @param[in]  vchDataIn  Referenced byte vector to overwrite/append
39 * @param[in]  nPosIn Starting position. Vector index where writes should start. The vector will initially
40 *                    grow as necessary to max(nPosIn, vec.size()). So to append, use vec.size().
41*/
42    VectorWriter(std::vector<unsigned char>& vchDataIn, size_t nPosIn) : vchData{vchDataIn}, nPos{nPosIn}
43    {
44        if(nPos > vchData.size())
45            vchData.resize(nPos);
46    }
47/*
48 * (other params same as above)
49 * @param[in]  args  A list of items to serialize starting at nPosIn.
50*/
51    template <typename... Args>
52    VectorWriter(std::vector<unsigned char>& vchDataIn, size_t nPosIn, Args&&... args) : VectorWriter{vchDataIn, nPosIn}
53    {
54        ::SerializeMany(*this, std::forward<Args>(args)...);
55    }
56    void write(std::span<const std::byte> src)
57    {
58        assert(nPos <= vchData.size());
59        size_t nOverwrite = std::min(src.size(), vchData.size() - nPos);
60        if (nOverwrite) {
61            memcpy(vchData.data() + nPos, src.data(), nOverwrite);
62        }
63        if (nOverwrite < src.size()) {
64            vchData.insert(vchData.end(), UCharCast(src.data()) + nOverwrite, UCharCast(src.data() + src.size()));
65        }
66        nPos += src.size();
67    }
68    template <typename T>
69    VectorWriter& operator<<(const T& obj)
70    {
71        ::Serialize(*this, obj);
72        return (*this);
73    }
74
75private:
76    std::vector<unsigned char>& vchData;
77    size_t nPos;
78};
79
80/** Minimal stream for reading from an existing byte array by std::span.
81 */
82class SpanReader
83{
84private:
85    std::span<const std::byte> m_data;
86
87public:
88    /**
89     * @param[in]  data Referenced byte vector to overwrite/append
90     */
91    explicit SpanReader(std::span<const unsigned char> data) : m_data{std::as_bytes(data)} {}
92    explicit SpanReader(std::span<const std::byte> data) : m_data{data} {}
93
94    template<typename T>
95    SpanReader& operator>>(T&& obj)
96    {
97        ::Unserialize(*this, obj);
98        return (*this);
99    }
100
101    size_t size() const { return m_data.size(); }
102    bool empty() const { return m_data.empty(); }
103
104    void read(std::span<std::byte> dst)
105    {
106        if (dst.size() == 0) {
107            return;
108        }
109
110        // Read from the beginning of the buffer
111        if (dst.size() > m_data.size()) {
112            throw std::ios_base::failure("SpanReader::read(): end of data");
113        }
114        memcpy(dst.data(), m_data.data(), dst.size());
115        m_data = m_data.subspan(dst.size());
116    }
117
118    void ignore(size_t n)
119    {
120        if (n > m_data.size()) {
121            throw std::ios_base::failure("SpanReader::ignore(): end of data");
122        }
123        m_data = m_data.subspan(n);
124    }
125};
126
127/** Minimal stream for writing to an existing span of bytes.
128 */
129class SpanWriter
130{
131private:
132    std::span<std::byte> m_dest;
133
134public:
135    explicit SpanWriter(std::span<std::byte> dest) : m_dest{dest} {}
136    template <typename... Args>
137    SpanWriter(std::span<std::byte> dest, Args&&... args) : SpanWriter{dest}
138    {
139        ::SerializeMany(*this, std::forward<Args>(args)...);
140    }
141
142    void write(std::span<const std::byte> src)
143    {
144        if (src.size() > m_dest.size()) {
145            throw std::ios_base::failure("SpanWriter::write(): exceeded buffer size");
146        }
147        memcpy(m_dest.data(), src.data(), src.size());
148        m_dest = m_dest.subspan(src.size());
149    }
150
151    template<typename T>
152    SpanWriter& operator<<(const T& obj)
153    {
154        ::Serialize(*this, obj);
155        return *this;
156    }
157};
158
159/** Double ended buffer combining vector and stream-like interfaces.
160 *
161 * >> and << read and write unformatted data using the above serialization templates.
162 * Fills with data in linear time; some stringstream implementations take N^2 time.
163 */
164class DataStream
165{
166protected:
167    using vector_type = SerializeData;
168    vector_type vch;
169    vector_type::size_type m_read_pos{0};
170
171public:
172    typedef vector_type::allocator_type   allocator_type;
173    typedef vector_type::size_type        size_type;
174    typedef vector_type::difference_type  difference_type;
175    typedef vector_type::reference        reference;
176    typedef vector_type::const_reference  const_reference;
177    typedef vector_type::value_type       value_type;
178    typedef vector_type::iterator         iterator;
179    typedef vector_type::const_iterator   const_iterator;
180    typedef vector_type::reverse_iterator reverse_iterator;
181
182    explicit DataStream() = default;
183    explicit DataStream(std::span<const uint8_t> sp) : DataStream{std::as_bytes(sp)} {}
184    explicit DataStream(std::span<const value_type> sp) : vch(sp.data(), sp.data() + sp.size()) {}
185
186    std::string str() const
187    {
188        return std::string{UCharCast(data()), UCharCast(data() + size())};
189    }
190
191    //
192    // Vector subset
193    //
194    const_iterator begin() const                     { return vch.begin() + m_read_pos; }
195    iterator begin()                                 { return vch.begin() + m_read_pos; }
196    const_iterator end() const                       { return vch.end(); }
197    iterator end()                                   { return vch.end(); }
198    size_type size() const                           { return vch.size() - m_read_pos; }
199    bool empty() const                               { return vch.size() == m_read_pos; }
200    void resize(size_type n, value_type c = value_type{}) { vch.resize(n + m_read_pos, c); }
201    void reserve(size_type n)                        { vch.reserve(n + m_read_pos); }
202    const_reference operator[](size_type pos) const  { return vch[pos + m_read_pos]; }
203    reference operator[](size_type pos)              { return vch[pos + m_read_pos]; }
204    void clear()                                     { vch.clear(); m_read_pos = 0; }
205    value_type* data()                               { return vch.data() + m_read_pos; }
206    const value_type* data() const                   { return vch.data() + m_read_pos; }
207
208    //
209    // Stream subset
210    //
211    void read(std::span<value_type> dst)
212    {
213        if (dst.size() == 0) return;
214
215        // Read from the beginning of the buffer
216        auto next_read_pos{CheckedAdd(m_read_pos, dst.size())};
217        if (!next_read_pos.has_value() || next_read_pos.value() > vch.size()) {
218            throw std::ios_base::failure("DataStream::read(): end of data");
219        }
220        memcpy(dst.data(), &vch[m_read_pos], dst.size());
221        if (next_read_pos.value() == vch.size()) {
222            // If fully consumed, reset to empty state.
223            clear();
224            return;
225        }
226        m_read_pos = next_read_pos.value();
227    }
228
229    void ignore(size_t num_ignore)
230    {
231        // Ignore from the beginning of the buffer
232        auto next_read_pos{CheckedAdd(m_read_pos, num_ignore)};
233        if (!next_read_pos.has_value() || next_read_pos.value() > vch.size()) {
234            throw std::ios_base::failure("DataStream::ignore(): end of data");
235        }
236        if (next_read_pos.value() == vch.size()) {
237            // If all bytes are ignored, reset to empty state.
238            clear();
239            return;
240        }
241        m_read_pos = next_read_pos.value();
242    }
243
244    void write(std::span<const value_type> src)
245    {
246        // Write to the end of the buffer
247        vch.insert(vch.end(), src.begin(), src.end());
248    }
249
250    template<typename T>

FILE GUIDE · KEY SECTIONS

Byte streams used by serialization

These stream adapters move serialized bytes between vectors, spans and files. The underlying object serializer determines their meaning.

Line 82 ↗

Read within a fixed region

SpanReader checks the remaining size before copying or ignoring bytes. Reading beyond the supplied region throws, which helps reject truncated serialized objects when callers handle failure correctly.

Line 129 ↗

Write within a fixed destination

SpanWriter refuses a write larger than the remaining destination. Its serialization operator delegates to the object serializer; it does not silently grow a caller-owned span.

Line 164 ↗

An owned read/write buffer

DataStream combines a vector with a read position and serialization operators. size refers to unread data. File-oriented classes later in the header provide different ownership, buffering and lifetime rules.

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.