Add binary encoding for unified spending keys.

This encoding is wallet-internal-only and is currently
guarded under the `unstable` feature flag.

components/zcash_address/CHANGELOG.md

@@ -11,6 +11,7 @@ and this library adheres to Rust's notion of
 - `zcash_address::TryFromAddress`
 - `zcash_address::TryFromRawAddress`
 - `zcash_address::ZcashAddress::convert_if_network`
+- A `TryFrom<Typecode>` implementation for `usize`.
 
 ### Changed
 - MSRV is now 1.52

components/zcash_address/src/convert.rs

@@ -104,7 +104,7 @@ impl<E: Error + 'static> Error for ConversionError<E> {
 /// ```
 pub trait TryFromRawAddress: Sized {
     /// Conversion errors for the user type (e.g. failing to parse the data passed to
-    /// [`Self::try_from_sapling`] as a valid Sapling address).
+    /// [`Self::try_from_raw_sapling`] as a valid Sapling address).
     type Error;
 
     fn try_from_raw_sprout(data: sprout::Data) -> Result<Self, ConversionError<Self::Error>> {

components/zcash_address/src/kind/unified.rs

@@ -1,8 +1,9 @@
 use bech32::{self, FromBase32, ToBase32, Variant};
 use std::cmp;
-use std::convert::TryFrom;
+use std::convert::{TryFrom, TryInto};
 use std::error::Error;
 use std::fmt;
+use std::num::TryFromIntError;
 
 use crate::Network;
 
@@ -88,6 +89,13 @@ impl From<Typecode> for u32 {
     }
 }
 
+impl TryFrom<Typecode> for usize {
+    type Error = TryFromIntError;
+    fn try_from(t: Typecode) -> Result<Self, Self::Error> {
+        u32::from(t).try_into()
+    }
+}
+
 impl Typecode {
     fn is_transparent(&self) -> bool {
         // Unknown typecodes are treated as not transparent for the purpose of disallowing

zcash_client_backend/CHANGELOG.md

@@ -45,7 +45,7 @@ and this library adheres to Rust's notion of
   likely to be modified and/or moved to a different module in a future
   release:
   - `zcash_client_backend::address::UnifiedAddress`
-  - `zcash_client_backend::keys::{UnifiedSpendingKey`, `UnifiedFullViewingKey`}
+  - `zcash_client_backend::keys::{UnifiedSpendingKey`, `UnifiedFullViewingKey`, `Era`, `DecodingError`}
   - `zcash_client_backend::encoding::AddressCodec`
   - `zcash_client_backend::encoding::encode_payment_address`
   - `zcash_client_backend::encoding::encode_transparent_address`

zcash_client_backend/Cargo.toml

@@ -18,6 +18,7 @@ base64 = "0.13"
 bech32 = "0.8"
 bls12_381 = "0.7"
 bs58 = { version = "0.4", features = ["check"] }
+byteorder = { version = "1", optional = true }
 crossbeam-channel = "0.5"
 ff = "0.12"
 group = "0.12"
@@ -39,6 +40,7 @@ subtle = "2.2.3"
 time = "0.2"
 tracing = "0.1"
 zcash_address = { version = "0.1", path = "../components/zcash_address" }
+zcash_encoding = { version = "0.1", path = "../components/zcash_encoding" }
 zcash_note_encryption = { version = "0.1", path = "../components/zcash_note_encryption" }
 zcash_primitives = { version = "0.7", path = "../zcash_primitives" }
 
@@ -47,6 +49,7 @@ protobuf-codegen-pure = "~2.27.1" # MSRV 1.52.1
 
 [dev-dependencies]
 gumdrop = "0.8"
+proptest = "1.0.0"
 rand_xorshift = "0.3"
 tempfile = "3.1.0"
 zcash_proofs = { version = "0.7", path = "../zcash_proofs" }
@@ -58,7 +61,7 @@ test-dependencies = [
     "orchard/test-dependencies",
     "zcash_primitives/test-dependencies",
 ]
-unstable = []
+unstable = ["byteorder"]
 
 [lib]
 bench = false

zcash_client_backend/src/keys.rs

@@ -1,19 +1,35 @@
 //! Helper functions for managing light client key material.
+use orchard;
 use zcash_address::unified::{self, Container, Encoding};
 use zcash_primitives::{
     consensus,
-    sapling::keys as sapling_keys,
     zip32::{AccountId, DiversifierIndex},
 };
 
 use crate::address::UnifiedAddress;
 
 #[cfg(feature = "transparent-inputs")]
-use zcash_primitives::legacy::keys::{self as legacy, IncomingViewingKey};
+use {
+    std::convert::TryInto,
+    zcash_primitives::legacy::keys::{self as legacy, IncomingViewingKey},
+};
+
+#[cfg(feature = "unstable")]
+use {
+    byteorder::{LittleEndian, ReadBytesExt, WriteBytesExt},
+    std::convert::TryFrom,
+    std::io::{Read, Write},
+    zcash_address::unified::Typecode,
+    zcash_encoding::CompactSize,
+    zcash_primitives::consensus::BranchId,
+};
 
 pub mod sapling {
     use zcash_primitives::zip32::{AccountId, ChildIndex};
-    pub use zcash_primitives::zip32::{ExtendedFullViewingKey, ExtendedSpendingKey};
+    pub use zcash_primitives::{
+        sapling::keys::DiversifiableFullViewingKey,
+        zip32::{ExtendedFullViewingKey, ExtendedSpendingKey},
+    };
 
     /// Derives the ZIP 32 [`ExtendedSpendingKey`] for a given coin type and account from the
     /// given seed.
@@ -71,12 +87,58 @@ pub enum DerivationError {
     Transparent(hdwallet::error::Error),
 }
 
+/// A version identifier for the encoding of unified spending keys.
+///
+/// Each era corresponds to a range of block heights. During an era, the unified spending key
+/// parsed from an encoded form tagged with that era's identifier is expected to provide
+/// sufficient spending authority to spend any non-Sprout shielded note created in a transaction
+/// within the era's block range.
+#[cfg(feature = "unstable")]
+#[derive(Debug, PartialEq, Eq)]
+pub enum Era {
+    /// The Orchard era begins at Orchard activation, and will end if a new pool that requires a
+    /// change to unified spending keys is introduced.
+    Orchard,
+}
+
+/// A type for errors that can occur when decoding keys from their serialized representations.
+#[cfg(feature = "unstable")]
+#[derive(Debug, PartialEq, Eq)]
+pub enum DecodingError {
+    ReadError(&'static str),
+    EraInvalid,
+    EraMismatch(Era),
+    TypecodeInvalid,
+    LengthInvalid,
+    LengthMismatch(Typecode, u32),
+    InsufficientData(Typecode),
+    KeyDataInvalid(Typecode),
+}
+
+#[cfg(feature = "unstable")]
+impl Era {
+    /// Returns the unique identifier for the era.
+    fn id(&self) -> u32 {
+        // We use the consensus branch id of the network upgrade that introduced a
+        // new USK format as the identifier for the era.
+        match self {
+            Era::Orchard => u32::from(BranchId::Nu5),
+        }
+    }
+
+    fn try_from_id(id: u32) -> Option<Self> {
+        BranchId::try_from(id).ok().and_then(|b| match b {
+            BranchId::Nu5 => Some(Era::Orchard),
+            _ => None,
+        })
+    }
+}
+
 /// A set of viewing keys that are all associated with a single
 /// ZIP-0032 account identifier.
 #[derive(Clone, Debug)]
 #[doc(hidden)]
 pub struct UnifiedSpendingKey {
-    account: AccountId,
     #[cfg(feature = "transparent-inputs")]
     transparent: legacy::AccountPrivKey,
     sapling: sapling::ExtendedSpendingKey,
@@ -103,7 +165,6 @@ impl UnifiedSpendingKey {
             .map_err(DerivationError::Transparent)?;
 
         Ok(UnifiedSpendingKey {
-            account,
             #[cfg(feature = "transparent-inputs")]
             transparent,
             sapling: sapling::spending_key(seed, params.coin_type(), account),
@@ -121,10 +182,6 @@ impl UnifiedSpendingKey {
         }
     }
 
-    pub fn account(&self) -> AccountId {
-        self.account
-    }
-
     /// Returns the transparent component of the unified key at the
     /// BIP44 path `m/44'/<coin_type>'/<account>'`.
     #[cfg(feature = "transparent-inputs")]
@@ -141,16 +198,154 @@ impl UnifiedSpendingKey {
     pub fn orchard(&self) -> &orchard::keys::SpendingKey {
         &self.orchard
     }
+
+    /// Returns a binary encoding of this key suitable for decoding with [`decode`].
+    ///
+    /// The encoded form of a unified spending key is only intended for use
+    /// within wallets when required for storage and/or crossing FFI boundaries;
+    /// unified spending keys should not be exposed to users, and consequently
+    /// no string-based encoding is defined. This encoding does not include any
+    /// internal validation metadata (such as checksums) as keys decoded from
+    /// this form will necessarily be validated when the attempt is made to
+    /// spend a note that they have authority for.
+    #[cfg(feature = "unstable")]
+    pub fn to_bytes(&self, era: Era) -> Vec<u8> {
+        let mut result = vec![];
+        result.write_u32::<LittleEndian>(era.id()).unwrap();
+
+        // orchard
+        let orchard_key = self.orchard();
+        CompactSize::write(&mut result, usize::try_from(Typecode::Orchard).unwrap()).unwrap();
+
+        let orchard_key_bytes = orchard_key.to_bytes();
+        CompactSize::write(&mut result, orchard_key_bytes.len()).unwrap();
+        result.write_all(orchard_key_bytes).unwrap();
+
+        // sapling
+        let sapling_key = self.sapling();
+        CompactSize::write(&mut result, usize::try_from(Typecode::Sapling).unwrap()).unwrap();
+
+        let sapling_key_bytes = sapling_key.to_bytes();
+        CompactSize::write(&mut result, sapling_key_bytes.len()).unwrap();
+        result.write_all(&sapling_key_bytes).unwrap();
+
+        // transparent
+        #[cfg(feature = "transparent-inputs")]
+        {
+            let account_tkey = self.transparent();
+            CompactSize::write(&mut result, usize::try_from(Typecode::P2pkh).unwrap()).unwrap();
+
+            let account_tkey_bytes = account_tkey.to_bytes();
+            CompactSize::write(&mut result, account_tkey_bytes.len()).unwrap();
+            result.write_all(&account_tkey_bytes).unwrap();
+        }
+
+        result
+    }
+
+    /// Decodes a [`UnifiedSpendingKey`] value from its serialized representation.
+    ///
+    /// See [`to_bytes`] for additional detail about the encoded form.
+    #[allow(clippy::unnecessary_unwrap)]
+    #[cfg(feature = "unstable")]
+    pub fn from_bytes(era: Era, encoded: &[u8]) -> Result<Self, DecodingError> {
+        let mut source = std::io::Cursor::new(encoded);
+        let decoded_era = source
+            .read_u32::<LittleEndian>()
+            .map_err(|_| DecodingError::ReadError("era"))
+            .and_then(|id| Era::try_from_id(id).ok_or(DecodingError::EraInvalid))?;
+
+        if decoded_era != era {
+            return Err(DecodingError::EraMismatch(decoded_era));
+        }
+
+        let mut orchard = None;
+        let mut sapling = None;
+        #[cfg(feature = "transparent-inputs")]
+        let mut transparent = None;
+        loop {
+            let tc = CompactSize::read_t::<_, u32>(&mut source)
+                .map_err(|_| DecodingError::ReadError("typecode"))
+                .and_then(|v| Typecode::try_from(v).map_err(|_| DecodingError::TypecodeInvalid))?;
+
+            let len = CompactSize::read_t::<_, u32>(&mut source)
+                .map_err(|_| DecodingError::ReadError("key length"))?;
+
+            match tc {
+                Typecode::Orchard => {
+                    if len != 32 {
+                        return Err(DecodingError::LengthMismatch(Typecode::Orchard, len));
+                    }
+
+                    let mut key = [0u8; 32];
+                    source
+                        .read_exact(&mut key)
+                        .map_err(|_| DecodingError::InsufficientData(Typecode::Orchard))?;
+                    orchard = Some(
+                        Option::<orchard::keys::SpendingKey>::from(
+                            orchard::keys::SpendingKey::from_bytes(key),
+                        )
+                        .ok_or(DecodingError::KeyDataInvalid(Typecode::Orchard))?,
+                    );
+                }
+                Typecode::Sapling => {
+                    if len != 169 {
+                        return Err(DecodingError::LengthMismatch(Typecode::Sapling, len));
+                    }
+
+                    let mut key = [0u8; 169];
+                    source
+                        .read_exact(&mut key)
+                        .map_err(|_| DecodingError::InsufficientData(Typecode::Sapling))?;
+                    sapling = Some(
+                        sapling::ExtendedSpendingKey::from_bytes(&key)
+                            .map_err(|_| DecodingError::KeyDataInvalid(Typecode::Sapling))?,
+                    );
+                }
+                #[cfg(feature = "transparent-inputs")]
+                Typecode::P2pkh => {
+                    if len != 64 {
+                        return Err(DecodingError::LengthMismatch(Typecode::P2pkh, len));
+                    }
+
+                    let mut key = [0u8; 64];
+                    source
+                        .read_exact(&mut key)
+                        .map_err(|_| DecodingError::InsufficientData(Typecode::P2pkh))?;
+                    transparent = Some(
+                        legacy::AccountPrivKey::from_bytes(&key)
+                            .ok_or(DecodingError::KeyDataInvalid(Typecode::P2pkh))?,
+                    );
+                }
+                _ => {
+                    return Err(DecodingError::TypecodeInvalid);
+                }
+            }
+
+            #[cfg(feature = "transparent-inputs")]
+            let has_transparent = transparent.is_some();
+            #[cfg(not(feature = "transparent-inputs"))]
+            let has_transparent = true;
+
+            if orchard.is_some() && sapling.is_some() && has_transparent {
+                return Ok(UnifiedSpendingKey {
+                    orchard: orchard.unwrap(),
+                    sapling: sapling.unwrap(),
+                    #[cfg(feature = "transparent-inputs")]
+                    transparent: transparent.unwrap(),
+                });
+            }
+        }
+    }
 }
 
-/// A set of viewing keys that are all associated with a single
-/// ZIP-0032 account identifier.
+/// A [ZIP 316](https://zips.z.cash/zip-0316) unified full viewing key.
 #[derive(Clone, Debug)]
 #[doc(hidden)]
 pub struct UnifiedFullViewingKey {
     #[cfg(feature = "transparent-inputs")]
     transparent: Option<legacy::AccountPubKey>,
-    sapling: Option<sapling_keys::DiversifiableFullViewingKey>,
+    sapling: Option<sapling::DiversifiableFullViewingKey>,
     orchard: Option<orchard::keys::FullViewingKey>,
     unknown: Vec<(u32, Vec<u8>)>,
 }
@@ -160,7 +355,7 @@ impl UnifiedFullViewingKey {
     /// Construct a new unified full viewing key, if the required components are present.
     pub fn new(
         #[cfg(feature = "transparent-inputs")] transparent: Option<legacy::AccountPubKey>,
-        sapling: Option<sapling_keys::DiversifiableFullViewingKey>,
+        sapling: Option<sapling::DiversifiableFullViewingKey>,
         orchard: Option<orchard::keys::FullViewingKey>,
     ) -> Option<UnifiedFullViewingKey> {
         if sapling.is_none() {
@@ -210,7 +405,7 @@ impl UnifiedFullViewingKey {
                     })
                     .transpose(),
                 unified::Fvk::Sapling(data) => {
-                    sapling_keys::DiversifiableFullViewingKey::from_bytes(data)
+                    sapling::DiversifiableFullViewingKey::from_bytes(data)
                         .ok_or("Invalid Sapling FVK in Unified FVK")
                         .map(|pa| {
                             sapling = Some(pa);
@@ -287,7 +482,7 @@ impl UnifiedFullViewingKey {
     }
 
     /// Returns the Sapling diversifiable full viewing key component of this unified key.
-    pub fn sapling(&self) -> Option<&sapling_keys::DiversifiableFullViewingKey> {
+    pub fn sapling(&self) -> Option<&sapling::DiversifiableFullViewingKey> {
         self.sapling.as_ref()
     }
 
@@ -366,8 +561,29 @@ impl UnifiedFullViewingKey {
     }
 }
 
+#[cfg(any(test, feature = "test-dependencies"))]
+pub mod testing {
+    use proptest::prelude::*;
+
+    use super::UnifiedSpendingKey;
+    use zcash_primitives::{consensus::Network, zip32::AccountId};
+
+    pub fn arb_unified_spending_key(params: Network) -> impl Strategy<Value = UnifiedSpendingKey> {
+        prop::array::uniform32(prop::num::u8::ANY).prop_flat_map(move |seed| {
+            prop::num::u32::ANY
+                .prop_map(move |account| {
+                    UnifiedSpendingKey::from_seed(&params, &seed, AccountId::from(account))
+                })
+                .prop_filter("seeds must generate valid USKs", |v| v.is_ok())
+                .prop_map(|v| v.unwrap())
+        })
+    }
+}
+
 #[cfg(test)]
 mod tests {
+    use proptest::prelude::proptest;
+
     use super::{sapling, UnifiedFullViewingKey};
     use zcash_primitives::{
         consensus::MAIN_NETWORK,
@@ -383,6 +599,13 @@ mod tests {
         },
     };
 
+    #[cfg(feature = "unstable")]
+    use {
+        super::{testing::arb_unified_spending_key, Era, UnifiedSpendingKey},
+        subtle::ConstantTimeEq,
+        zcash_primitives::consensus::Network,
+    };
+
     #[cfg(feature = "transparent-inputs")]
     fn seed() -> Vec<u8> {
         let seed_hex = "6ef5f84def6f4b9d38f466586a8380a38593bd47c8cda77f091856176da47f26b5bd1c8d097486e5635df5a66e820d28e1d73346f499801c86228d43f390304f";
@@ -476,4 +699,22 @@ mod tests {
         #[cfg(not(feature = "transparent-inputs"))]
         assert_eq!(decoded_with_t.unknown.len(), 1);
     }
+
+    proptest! {
+        #[test]
+        #[cfg(feature = "unstable")]
+        fn prop_usk_roundtrip(usk in arb_unified_spending_key(Network::MainNetwork)) {
+            let encoded = usk.to_bytes(Era::Orchard);
+            #[cfg(not(feature = "transparent-inputs"))]
+            assert_eq!(encoded.len(), 4 + 2 + 32 + 2 + 169);
+            #[cfg(feature = "transparent-inputs")]
+            assert_eq!(encoded.len(), 4 + 2 + 32 + 2 + 169 + 2 + 64);
+            let decoded = UnifiedSpendingKey::from_bytes(Era::Orchard, &encoded);
+            let decoded = decoded.unwrap_or_else(|e| panic!("Error decoding USK: {:?}", e));
+            assert!(bool::from(decoded.orchard().ct_eq(usk.orchard())));
+            assert_eq!(decoded.sapling(), usk.sapling());
+            #[cfg(feature = "transparent-inputs")]
+            assert_eq!(decoded.transparent().to_bytes(), usk.transparent().to_bytes());
+        }
+    }
 }