Introduce libzcash::RawAddress type

Currently, `libzcash::PaymentAddress` serves two purposes: it represents
the result of parsing a string encoding provided by a user, and it holds
the possible shielded protocol addresses that can be used in transaction
outputs. In order to add support for Unified Addresses, we split these
purposes across two separate types.

We also add two new visitors to enable converting between these types:

- `RecipientForPaymentAddress` returns the "preferred protocol address"
  that should be used in transaction outputs, or `std::nullopt` if the
  payment address encoding was invalid.

- `GetRawAddresses` returns all protocol addresses contained within the
  given payment address, or an empty set if the payment address encoding
  was invalid.

For the existing address encodings, the implementations of these are
trivial.

src/zcash/Address.cpp

@@ -35,3 +35,39 @@ bool IsValidViewingKey(const libzcash::ViewingKey& vk) {
 bool IsValidSpendingKey(const libzcash::SpendingKey& zkey) {
     return !std::holds_alternative<libzcash::InvalidEncoding>(zkey);
 }
+
+std::optional<libzcash::RawAddress> RecipientForPaymentAddress::operator()(
+    const libzcash::InvalidEncoding& no) const
+{
+    return std::nullopt;
+}
+
+std::optional<libzcash::RawAddress> RecipientForPaymentAddress::operator()(
+    const libzcash::SproutPaymentAddress &zaddr) const
+{
+    return zaddr;
+}
+
+std::optional<libzcash::RawAddress> RecipientForPaymentAddress::operator()(
+    const libzcash::SaplingPaymentAddress &zaddr) const
+{
+    return zaddr;
+}
+
+std::set<libzcash::RawAddress> GetRawAddresses::operator()(
+    const libzcash::InvalidEncoding& no) const
+{
+    return {};
+}
+
+std::set<libzcash::RawAddress> GetRawAddresses::operator()(
+    const libzcash::SproutPaymentAddress &zaddr) const
+{
+    return {zaddr};
+}
+
+std::set<libzcash::RawAddress> GetRawAddresses::operator()(
+    const libzcash::SaplingPaymentAddress &zaddr) const
+{
+    return {zaddr};
+}

src/zcash/Address.hpp

@@ -8,12 +8,16 @@
 #include <variant>
 
 namespace libzcash {
+/** Protocol addresses that can receive funds in a transaction. */
+typedef std::variant<SproutPaymentAddress, SaplingPaymentAddress> RawAddress;
+
 class InvalidEncoding {
 public:
     friend bool operator==(const InvalidEncoding &a, const InvalidEncoding &b) { return true; }
     friend bool operator<(const InvalidEncoding &a, const InvalidEncoding &b) { return true; }
 };
 
+/** Addresses that can appear in a string encoding. */
 typedef std::variant<InvalidEncoding, SproutPaymentAddress, SaplingPaymentAddress> PaymentAddress;
 typedef std::variant<InvalidEncoding, SproutViewingKey, SaplingExtendedFullViewingKey> ViewingKey;
 typedef std::variant<InvalidEncoding, SproutSpendingKey, SaplingExtendedSpendingKey> SpendingKey;
@@ -43,4 +47,28 @@ bool IsValidViewingKey(const libzcash::ViewingKey& vk);
 /** Check whether a SpendingKey is not an InvalidEncoding. */
 bool IsValidSpendingKey(const libzcash::SpendingKey& zkey);
 
+/**
+ * Returns the protocol address that should be used in transaction outputs.
+ */
+class RecipientForPaymentAddress {
+public:
+    RecipientForPaymentAddress() {}
+
+    std::optional<libzcash::RawAddress> operator()(const libzcash::InvalidEncoding& no) const;
+    std::optional<libzcash::RawAddress> operator()(const libzcash::SproutPaymentAddress &zaddr) const;
+    std::optional<libzcash::RawAddress> operator()(const libzcash::SaplingPaymentAddress &zaddr) const;
+};
+
+/**
+ * Returns all protocol addresses contained within the given payment address.
+ */
+class GetRawAddresses {
+public:
+    GetRawAddresses() {}
+
+    std::set<libzcash::RawAddress> operator()(const libzcash::InvalidEncoding& no) const;
+    std::set<libzcash::RawAddress> operator()(const libzcash::SproutPaymentAddress &zaddr) const;
+    std::set<libzcash::RawAddress> operator()(const libzcash::SaplingPaymentAddress &zaddr) const;
+};
+
 #endif // ZC_ADDRESS_H_