logo
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
//! Converting Zcash consensus-critical data structures into bytes.

use std::{io, net::Ipv6Addr};

use super::{AtLeastOne, CompactSizeMessage};

/// The maximum length of a Zcash message, in bytes.
///
/// This value is used to calculate safe preallocation limits for some types
pub const MAX_PROTOCOL_MESSAGE_LEN: usize = 2 * 1024 * 1024;

/// Consensus-critical serialization for Zcash.
///
/// This trait provides a generic serialization for consensus-critical
/// formats, such as network messages, transactions, blocks, etc.
///
/// It is intended for use only for consensus-critical formats.
/// Internal serialization can freely use `serde`, or any other format.
pub trait ZcashSerialize: Sized {
    /// Write `self` to the given `writer` using the canonical format.
    ///
    /// This function has a `zcash_` prefix to alert the reader that the
    /// serialization in use is consensus-critical serialization, rather than
    /// some other kind of serialization.
    ///
    /// Notice that the error type is [`std::io::Error`]; this indicates that
    /// serialization MUST be infallible up to errors in the underlying writer.
    /// In other words, any type implementing `ZcashSerialize` must make illegal
    /// states unrepresentable.
    fn zcash_serialize<W: io::Write>(&self, writer: W) -> Result<(), io::Error>;

    /// Helper function to construct a vec to serialize the current struct into
    fn zcash_serialize_to_vec(&self) -> Result<Vec<u8>, io::Error> {
        let mut data = Vec::new();
        self.zcash_serialize(&mut data)?;
        Ok(data)
    }

    /// Get the size of `self` by using a fake writer.
    fn zcash_serialized_size(&self) -> Result<usize, io::Error> {
        let mut writer = FakeWriter(0);
        self.zcash_serialize(&mut writer)
            .expect("writer should never fail");
        Ok(writer.0)
    }
}

/// A fake writer helper used to get object lengths without allocating RAM.
pub struct FakeWriter(pub usize);

impl std::io::Write for FakeWriter {
    fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
        self.0 += buf.len();

        Ok(buf.len())
    }

    fn flush(&mut self) -> std::io::Result<()> {
        Ok(())
    }
}

/// Serialize a `Vec` as a CompactSize number of items, then the items. This is
/// the most common format in Zcash.
///
/// See `zcash_serialize_external_count` for more details, and usage information.
impl<T: ZcashSerialize> ZcashSerialize for Vec<T> {
    #[allow(clippy::unwrap_in_result)]
    fn zcash_serialize<W: io::Write>(&self, mut writer: W) -> Result<(), io::Error> {
        let len: CompactSizeMessage = self
            .len()
            .try_into()
            .expect("len fits in MAX_PROTOCOL_MESSAGE_LEN");
        len.zcash_serialize(&mut writer)?;

        zcash_serialize_external_count(self, writer)
    }
}

/// Serialize an `AtLeastOne` vector as a CompactSize number of items, then the
/// items. This is the most common format in Zcash.
impl<T: ZcashSerialize> ZcashSerialize for AtLeastOne<T> {
    fn zcash_serialize<W: io::Write>(&self, mut writer: W) -> Result<(), io::Error> {
        self.as_vec().zcash_serialize(&mut writer)
    }
}

/// Serialize a byte vector as a CompactSize number of items, then the items.
///
/// # Correctness
///
/// Most Zcash types have specific rules about serialization of `Vec<u8>`s.
/// Check the spec and consensus rules before using this function.
///
/// See `zcash_serialize_bytes_external_count` for more details, and usage information.
//
// we specifically want to serialize `Vec`s here, rather than generic slices
#[allow(clippy::ptr_arg)]
pub fn zcash_serialize_bytes<W: io::Write>(vec: &Vec<u8>, mut writer: W) -> Result<(), io::Error> {
    let len: CompactSizeMessage = vec
        .len()
        .try_into()
        .expect("len fits in MAX_PROTOCOL_MESSAGE_LEN");
    len.zcash_serialize(&mut writer)?;

    zcash_serialize_bytes_external_count(vec, writer)
}

/// Serialize an empty list of items, by writing a zero CompactSize length.
/// (And no items.)
pub fn zcash_serialize_empty_list<W: io::Write>(writer: W) -> Result<(), io::Error> {
    let len: CompactSizeMessage = 0.try_into().expect("zero fits in MAX_PROTOCOL_MESSAGE_LEN");
    len.zcash_serialize(writer)
}

/// Serialize a typed `Vec` **without** writing the number of items as a
/// CompactSize.
///
/// In Zcash, most arrays are stored as a CompactSize, followed by that number
/// of items of type `T`. But in `Transaction::V5`, some types are serialized as
/// multiple arrays in different locations, with a single CompactSize before the
/// first array.
///
/// ## Usage
///
/// Use `zcash_serialize_external_count` when the array count is determined by
/// other data, or a consensus rule.
///
/// Use `Vec::zcash_serialize` for data that contains CompactSize count,
/// followed by the data array.
///
/// For example, when a single count applies to multiple arrays:
/// 1. Use `Vec::zcash_serialize` for the array that has a data count.
/// 2. Use `zcash_serialize_external_count` for the arrays with no count in the
///    data, passing the length of the first array.
///
/// This function has a `zcash_` prefix to alert the reader that the
/// serialization in use is consensus-critical serialization, rather than
/// some other kind of serialization.
//
// we specifically want to serialize `Vec`s here, rather than generic slices
#[allow(clippy::ptr_arg)]
pub fn zcash_serialize_external_count<W: io::Write, T: ZcashSerialize>(
    vec: &Vec<T>,
    mut writer: W,
) -> Result<(), io::Error> {
    for x in vec {
        x.zcash_serialize(&mut writer)?;
    }
    Ok(())
}

/// Serialize a raw byte `Vec` **without** writing the number of items as a
/// CompactSize.
///
/// This is a convenience alias for `writer.write_all(&vec)`.
//
// we specifically want to serialize `Vec`s here, rather than generic slices
#[allow(clippy::ptr_arg)]
pub fn zcash_serialize_bytes_external_count<W: io::Write>(
    vec: &Vec<u8>,
    mut writer: W,
) -> Result<(), io::Error> {
    writer.write_all(vec)
}

/// Write a Bitcoin-encoded UTF-8 `&str`.
impl ZcashSerialize for &str {
    fn zcash_serialize<W: io::Write>(&self, writer: W) -> Result<(), io::Error> {
        let str_bytes = self.as_bytes().to_vec();
        zcash_serialize_bytes(&str_bytes, writer)
    }
}

/// Write a Bitcoin-encoded UTF-8 `String`.
impl ZcashSerialize for String {
    fn zcash_serialize<W: io::Write>(&self, mut writer: W) -> Result<(), io::Error> {
        self.as_str().zcash_serialize(&mut writer)
    }
}

// We don't impl ZcashSerialize for Ipv4Addr or SocketAddrs,
// because the IPv4 and port formats are different in addr (v1) and addrv2 messages.

/// Write a Bitcoin-encoded IPv6 address.
impl ZcashSerialize for Ipv6Addr {
    fn zcash_serialize<W: io::Write>(&self, mut writer: W) -> Result<(), std::io::Error> {
        writer.write_all(&self.octets())
    }
}