2021-04-07 02:12:11 -07:00
|
|
|
|
::
|
|
|
|
|
|
|
|
|
|
ZIP: 316
|
|
|
|
|
Title: Unified Addresses
|
|
|
|
|
Owners: Daira Hopwood <daira@electriccoin.co>
|
2021-04-08 15:59:30 -07:00
|
|
|
|
Nathan Wilcox <nathan@electriccoin.co>
|
|
|
|
|
Taylor Hornby <taylor@electriccoin.co>
|
2021-04-07 02:12:11 -07:00
|
|
|
|
Jack Grigg <jack@electriccoin.co>
|
|
|
|
|
Sean Bowe <sean@electriccoin.co>
|
|
|
|
|
Kris Nuttycombe <kris@electriccoin.co>
|
|
|
|
|
Ying Tong Lai <yingtong@electriccoin.co>
|
2021-04-08 15:59:30 -07:00
|
|
|
|
Status: Proposed
|
2021-04-07 02:12:11 -07:00
|
|
|
|
Category: Standards / RPC / Wallet
|
2021-04-08 15:59:30 -07:00
|
|
|
|
Created: 2021-04-07
|
|
|
|
|
License: MIT
|
2021-04-07 02:12:11 -07:00
|
|
|
|
Discussions-To: <https://github.com/zcash/zips/issues/482>
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Terminology
|
|
|
|
|
===========
|
|
|
|
|
|
|
|
|
|
The key words "MUST", "MUST NOT", and "SHOULD" in this document are to
|
|
|
|
|
be interpreted as described in RFC 2119. [#RFC2119]_
|
|
|
|
|
|
|
|
|
|
The terms below are to be interpreted as follows:
|
|
|
|
|
|
|
|
|
|
Recipient
|
|
|
|
|
A wallet or other software that can receive transfers of assets (such
|
|
|
|
|
as ZEC) or in the future potentially other transaction-based state changes.
|
2021-04-22 14:00:33 -07:00
|
|
|
|
Producer
|
|
|
|
|
A wallet or other software that can create an Address (normally also a
|
|
|
|
|
Recipient).
|
2021-04-08 15:59:30 -07:00
|
|
|
|
Sender
|
|
|
|
|
A wallet or other software that can send transfers of assets, or other
|
2021-04-22 14:00:33 -07:00
|
|
|
|
consensus state side-effects defined in future.
|
2021-04-08 15:59:30 -07:00
|
|
|
|
Receiver
|
|
|
|
|
The necessary information to transfer an asset to a Recipient that generated
|
|
|
|
|
that Receiver using a specific Transfer Protocol. Each Receiver is associated
|
2021-04-20 16:11:55 -07:00
|
|
|
|
unambiguously with a specific Receiver Type, identified by an integer Typecode.
|
2021-04-22 14:00:33 -07:00
|
|
|
|
Receiver Encoding
|
|
|
|
|
An encoding of a Receiver as a byte sequence.
|
2021-04-08 15:59:30 -07:00
|
|
|
|
Legacy Address (or LA)
|
2021-04-22 14:00:33 -07:00
|
|
|
|
A Transparent, Sprout, or Sapling Address.
|
2021-04-08 15:59:30 -07:00
|
|
|
|
Unified Address (or UA)
|
|
|
|
|
A Unified Address combines multiple Receivers.
|
2021-04-22 14:00:33 -07:00
|
|
|
|
Unified Full Viewing Key (or UFVK)
|
|
|
|
|
A Unified Full Viewing Key combines multiple Full Viewing Keys.
|
|
|
|
|
Unified Incoming Viewing Key (or UIVK)
|
|
|
|
|
A Unified Incoming Viewing Key combines multiple Incoming Viewing Keys.
|
2021-04-08 15:59:30 -07:00
|
|
|
|
Address
|
|
|
|
|
Either a Legacy Address or a Unified Address.
|
|
|
|
|
Transfer Protocol
|
|
|
|
|
A specification of how a Sender can transfer assets to a Recipient.
|
|
|
|
|
For example, the Transfer Protocol for a Sapling Receiver is the subset
|
|
|
|
|
of the Zcash protocol required to successfully transfer ZEC using Sapling
|
|
|
|
|
Spend/Output Transfers as specified in the Zcash Protocol Specification.
|
|
|
|
|
(A single Zcash transaction can contain transfers of multiple
|
|
|
|
|
Transfer Protocols. For example a t→z transaction that shields to the
|
|
|
|
|
Sapling pool requires both Transparent and Sapling Transfer Protocols.)
|
|
|
|
|
Address Encoding
|
|
|
|
|
The externally visible encoding of an Address (e.g. as a string of
|
|
|
|
|
characters or a QR code).
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Abstract
|
|
|
|
|
========
|
|
|
|
|
|
2021-04-22 14:00:33 -07:00
|
|
|
|
This proposal defines Unified Addresses, which bundle together Zcash Addresses
|
2021-04-20 16:11:55 -07:00
|
|
|
|
of different types in a way that can be presented as a single Address Encoding.
|
|
|
|
|
It also defines Unified Viewing Keys, which perform a similar function for
|
|
|
|
|
Zcash viewing keys.
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Motivation
|
|
|
|
|
==========
|
|
|
|
|
|
|
|
|
|
Up to and including the Canopy network upgrade, Zcash supported the following
|
2021-04-22 14:00:33 -07:00
|
|
|
|
Payment Address types:
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
|
|
|
|
* Transparent Addresses (P2PKH and P2SH)
|
|
|
|
|
* Sprout Addresses
|
|
|
|
|
* Sapling Addresses
|
|
|
|
|
|
|
|
|
|
Each of these has its own Address Encodings, as a string and as a QR code.
|
|
|
|
|
(Since the QR code is derivable from the string encoding, for many purposes
|
|
|
|
|
it suffices to consider the string encoding.)
|
|
|
|
|
|
2021-04-22 14:00:33 -07:00
|
|
|
|
The Orchard proposal [#zip-0224]_ adds a new Address type, Orchard Addresses.
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
2021-04-22 14:00:33 -07:00
|
|
|
|
The difficulty with defining new Address Encodings for each Address type, is
|
2021-04-08 15:59:30 -07:00
|
|
|
|
that end-users are forced to be aware of the various types, and in particular
|
|
|
|
|
which types are supported by a given Sender or Recipient. In order to make
|
|
|
|
|
sure that transfers are completed successfully, users may be forced to
|
2021-04-22 14:00:33 -07:00
|
|
|
|
explicitly generate Addresses of different types and re-distribute encodings
|
2021-04-08 15:59:30 -07:00
|
|
|
|
of them, which adds significant friction and cognitive overhead to
|
|
|
|
|
understanding and using Zcash.
|
|
|
|
|
|
|
|
|
|
The goals for a Unified Address standard are as follows:
|
|
|
|
|
|
2021-04-20 16:11:55 -07:00
|
|
|
|
- Simplify coordination between Recipients and Senders by removing complexity
|
2021-04-22 14:00:33 -07:00
|
|
|
|
from negotiating Address types.
|
2021-04-08 15:59:30 -07:00
|
|
|
|
- Provide a “bridging mechanism” to allow shielded wallets to successfully
|
|
|
|
|
interact with conformant Transparent-Only wallets.
|
|
|
|
|
- Allow older conformant wallets to interact seamlessly with newer wallets.
|
|
|
|
|
- Enable users of newer wallets to upgrade to newer transaction technologies
|
|
|
|
|
and/or pools while maintaining seamless interactions with counterparties
|
|
|
|
|
using older wallets.
|
2021-04-20 16:11:55 -07:00
|
|
|
|
- Facilitate wallets to assume more sophisticated responsibilities for
|
|
|
|
|
shielding and/or migrating user funds.
|
2021-04-08 15:59:30 -07:00
|
|
|
|
- Allow wallets to potentially develop new transfer mechanisms without
|
|
|
|
|
underlying protocol changes.
|
2021-04-22 14:00:33 -07:00
|
|
|
|
- Support abstractions corresponding to a Unified Address that provide the
|
|
|
|
|
functionality of Full Viewing Keys and Incoming Viewing Keys.
|
2021-04-08 15:59:30 -07:00
|
|
|
|
- Provide forward compatibility that is standard for all wallets across a
|
|
|
|
|
range of potential future features. Some examples might include Layer 2
|
|
|
|
|
features, cross-chain interoperability and bridging, and decentralized
|
|
|
|
|
exchange.
|
|
|
|
|
- The standard should work well for Zcash today and upcoming potential
|
|
|
|
|
upgrades, and also anticipate even broader use cases down the road such
|
|
|
|
|
as cross-chain functionality.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Requirements
|
|
|
|
|
============
|
|
|
|
|
|
|
|
|
|
Overview
|
|
|
|
|
--------
|
|
|
|
|
|
|
|
|
|
Unified Addresses specify multiple methods for payment to a Recipient's Wallet.
|
|
|
|
|
The Sender's Wallet can then non-interactively select the method of payment.
|
|
|
|
|
|
|
|
|
|
Importantly, any wallet can support Unified Addresses, even when that wallet
|
|
|
|
|
only supports a subset of payment methods for receiving and/or sending.
|
|
|
|
|
|
|
|
|
|
Despite having some similar characteristics, the Unified Address standard is
|
|
|
|
|
orthogonal to Payment Request URIs [#zip-0321]_ and similar schemes, and the
|
|
|
|
|
Unified Address format is likely to be incorporated into such schemes as a new
|
2021-04-22 14:00:33 -07:00
|
|
|
|
Address type.
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
|
|
|
|
Concepts
|
|
|
|
|
--------
|
|
|
|
|
|
|
|
|
|
Wallets follow a model *Interaction Flow* as follows:
|
|
|
|
|
|
2021-04-22 14:00:33 -07:00
|
|
|
|
1. A Producer *generates* an Address.
|
|
|
|
|
2. The Producer *encodes* the Address.
|
|
|
|
|
3. The Producer wallet or human user *distributes* this Address Encoding,
|
2021-04-20 16:11:55 -07:00
|
|
|
|
This ZIP leaves distribution mechanisms out of scope.
|
|
|
|
|
4. A Sender wallet or user *imports* the Address Encoding through any of
|
2021-04-08 15:59:30 -07:00
|
|
|
|
a variety of mechanisms (QR Code scanning, Payment URIs, cut-and-paste,
|
2021-04-20 16:11:55 -07:00
|
|
|
|
or “in-band” protocols like ``Reply-To`` memos).
|
|
|
|
|
5. A Sender wallet *decodes* the Address Encoding and performs validity
|
|
|
|
|
checks.
|
|
|
|
|
6. (Perhaps later in time) the Sender wallet executes a transfer of ZEC
|
2021-04-22 14:00:33 -07:00
|
|
|
|
(or other assets or protocol state changes) to the Address.
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
2021-04-20 16:11:55 -07:00
|
|
|
|
Encodings of the same Address may be distributed zero or more times through
|
2021-04-22 14:00:33 -07:00
|
|
|
|
different means. Zero or more Senders may import Addresses. Zero or more of
|
2021-04-20 16:11:55 -07:00
|
|
|
|
those may execute a Transfer. A single Sender may execute multiple Transfers
|
|
|
|
|
over time from a single import.
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
2021-04-22 14:00:33 -07:00
|
|
|
|
Steps 1 to 5 inclusive also apply to Interaction Flows for Unified Full Viewing
|
|
|
|
|
Keys and Unified Incoming Viewing Keys.
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
|
|
|
|
Addresses
|
|
|
|
|
---------
|
|
|
|
|
|
|
|
|
|
A Unified Address (or UA for short) combines one or more Receivers.
|
|
|
|
|
|
|
|
|
|
When new Transport Protocols are introduced to the Zcash protocol after
|
|
|
|
|
Unified Addresses are standardized, those should introduce new Receiver Types
|
2021-04-22 14:00:33 -07:00
|
|
|
|
but *not* different Address types outside of the UA standard. There needs
|
2021-04-08 15:59:30 -07:00
|
|
|
|
to be a compelling reason to deviate from the standard, since the benefits
|
|
|
|
|
of UA come precisely from their applicability across all new protocol
|
|
|
|
|
upgrades.
|
|
|
|
|
|
|
|
|
|
Receivers
|
|
|
|
|
---------
|
|
|
|
|
|
2021-04-20 16:11:55 -07:00
|
|
|
|
Every Wallet must properly *parse* a Unified Address containing unrecognized
|
2021-04-22 14:00:33 -07:00
|
|
|
|
Receiver Types; and similarly for Unified Full Viewing Keys and Unified
|
|
|
|
|
Incoming Viewing Keys.
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
2021-04-20 16:11:55 -07:00
|
|
|
|
A Wallet may process unrecognized Receiver Types by indicating to the user
|
2021-04-08 15:59:30 -07:00
|
|
|
|
their presence or similar information for usability or diagnostic purposes.
|
|
|
|
|
|
|
|
|
|
Transport Encoding
|
|
|
|
|
------------------
|
|
|
|
|
|
|
|
|
|
The string encoding is “opaque” to human readers: it does *not* allow
|
|
|
|
|
visual identification of which Receivers or Receiver Types are present.
|
|
|
|
|
|
|
|
|
|
The string encoding is resilient against typos, transcription errors,
|
|
|
|
|
cut-and-paste errors, unanticipated truncation, or other anticipated
|
|
|
|
|
UX hazards.
|
|
|
|
|
|
2021-04-22 14:00:33 -07:00
|
|
|
|
There is a well-defined encoding of a Unified Address (or UFVK or UIVK)
|
|
|
|
|
as a QR Code, which produces QR codes that are reasonably compact and
|
|
|
|
|
robust.
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
|
|
|
|
There is a well-defined transformation between the QR Code and string
|
|
|
|
|
encodings in either direction.
|
|
|
|
|
|
|
|
|
|
The string encoding fits into ZIP-321 Payment URIs [#zip-0321]_ and
|
|
|
|
|
general URIs without introducing parse ambiguities.
|
|
|
|
|
|
|
|
|
|
The encoding must support sufficiently many Recipient Types to allow
|
|
|
|
|
for reasonable future expansion.
|
|
|
|
|
|
|
|
|
|
The encoding must allow all wallets to safely and correctly parse out
|
2021-04-20 16:11:55 -07:00
|
|
|
|
unrecognized Receiver Types well enough to ignore them.
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
|
|
|
|
Transfers
|
|
|
|
|
---------
|
|
|
|
|
|
2021-04-22 14:00:33 -07:00
|
|
|
|
When executing a Transfer the Sender selects a Receiver via a Selection
|
|
|
|
|
process.
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
|
|
|
|
Given a valid UA, Selection must treat any unrecognized Receiver as
|
|
|
|
|
though it were absent.
|
|
|
|
|
|
|
|
|
|
- This property is crucial for forward compatibility to ensure users
|
|
|
|
|
who upgrade to newer protocols / UAs don't lose the ability to smoothly
|
|
|
|
|
interact with older wallets.
|
|
|
|
|
|
|
|
|
|
- This property is crucial for allowing Transparent-Only UA-Conformant
|
|
|
|
|
wallets to interact with newer shielded wallets, removing a
|
|
|
|
|
disincentive for adopting newer shielded wallets.
|
|
|
|
|
|
|
|
|
|
- This property also allows Transparent-Only wallets to upgrade to
|
2021-04-20 16:11:55 -07:00
|
|
|
|
shielded support without re-acquiring counterparty UAs. If they are
|
|
|
|
|
re-acquired, the user flow and usability will be minimally disrupted.
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
2021-04-22 14:00:33 -07:00
|
|
|
|
Viewing Keys
|
|
|
|
|
------------
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
2021-04-22 14:00:33 -07:00
|
|
|
|
A Unified Full Viewing Key (resp. Unified Incoming Viewing Key) can be
|
|
|
|
|
used in a similar way to a Full Viewing Key (resp. Incoming Viewing Key)
|
|
|
|
|
as described in the Zcash Protocol Specification [#protocol-nu5]_.
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
2021-04-22 14:00:33 -07:00
|
|
|
|
Transparent Addresses do not have separate corresponding viewing keys,
|
|
|
|
|
but the address itself can effectively be used as a viewing key.
|
|
|
|
|
Therefore, a UFVK or UIVK should be able to include a Transparent Address.
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
2021-04-22 14:00:33 -07:00
|
|
|
|
A wallet should support deriving a Unified Address from a UFVK, by
|
|
|
|
|
deriving a Receiver from each Full Viewing Key in the UFVK. Any
|
|
|
|
|
Transparent Address in the UFVK is left as-is.
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
2021-04-22 14:00:33 -07:00
|
|
|
|
It is not possible to derive a Unified Address from a Unified Incoming
|
|
|
|
|
Viewing Key.
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
|
|
|
|
|
2021-04-22 14:00:33 -07:00
|
|
|
|
Open Issues and Known Concerns
|
|
|
|
|
------------------------------
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
2021-04-22 14:00:33 -07:00
|
|
|
|
TODO: We have a few of these that will be added in future edits.
|
|
|
|
|
This is especially true of privacy impacts of transparent or cross-pool
|
|
|
|
|
transactions and the associated UX issues.
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
|
|
|
|
|
2021-04-22 14:00:33 -07:00
|
|
|
|
Specification
|
|
|
|
|
=============
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
2021-04-22 14:00:33 -07:00
|
|
|
|
Encoding of Unified Addresses
|
|
|
|
|
-----------------------------
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
2021-04-22 14:00:33 -07:00
|
|
|
|
Rather than defining a Bech32 string encoding of Orchard Shielded
|
|
|
|
|
Payment Addresses, we instead define a Unified Address format that
|
2021-04-20 16:11:55 -07:00
|
|
|
|
is able to encode a set of Receivers of different types. This enables
|
|
|
|
|
the consumer of a Unified Address (i.e. the Sender) to choose the
|
|
|
|
|
Receiver of the best type it supports, providing a better user
|
|
|
|
|
experience as new Receiver Types are added in the future.
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
2021-04-22 14:00:33 -07:00
|
|
|
|
Assume that we are given a set of one or more Receiver Encodings
|
|
|
|
|
for distinct types. That is, the set may optionally contain one
|
|
|
|
|
Receiver of each of the Receiver Types in the following fixed
|
|
|
|
|
Priority List:
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
2021-04-20 16:11:55 -07:00
|
|
|
|
* Typecode :math:`\mathtt{0x03}` — an Orchard raw address as defined
|
2021-04-08 15:59:30 -07:00
|
|
|
|
in [#protocol-orchardpaymentaddrencoding]_;
|
|
|
|
|
|
2021-04-20 16:11:55 -07:00
|
|
|
|
* Typecode :math:`\mathtt{0x02}` — a Sapling raw address as defined
|
2021-04-08 15:59:30 -07:00
|
|
|
|
in [#protocol-saplingpaymentaddrencoding]_;
|
|
|
|
|
|
2021-04-22 14:00:33 -07:00
|
|
|
|
* Typecode :math:`\mathtt{0x01}` — a Transparent P2SH address, *or*
|
|
|
|
|
Typecode :math:`\mathtt{0x00}` — a Transparent P2PKH address.
|
2021-04-20 16:11:55 -07:00
|
|
|
|
|
2021-04-22 14:00:33 -07:00
|
|
|
|
We say that a Receiver Type is “preferred” over another when it appears
|
2021-04-20 16:11:55 -07:00
|
|
|
|
earlier in this Priority List.
|
|
|
|
|
|
|
|
|
|
A Unified Address MUST contain at least one shielded Receiver
|
|
|
|
|
(Typecodes :math:`\geq \mathtt{0x02}`).
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
2021-04-20 16:11:55 -07:00
|
|
|
|
The Sender of a payment to a Unified Address MUST use the Receiver
|
2021-04-22 14:00:33 -07:00
|
|
|
|
of the most preferred Receiver Type that it supports from the set.
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
2021-04-20 16:11:55 -07:00
|
|
|
|
For example, consider a wallet that supports sending funds to Orchard
|
2021-04-22 14:00:33 -07:00
|
|
|
|
Receivers, and does not support sending to any Receiver Type that is
|
|
|
|
|
preferred over Orchard. If that wallet is given a UA that includes an
|
|
|
|
|
Orchard Receiver and possibly other Receivers, it MUST send to the
|
|
|
|
|
Orchard Receiver.
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
2021-04-20 16:11:55 -07:00
|
|
|
|
The raw encoding of a Unified Address is a concatenation of
|
2021-04-08 15:59:30 -07:00
|
|
|
|
:math:`(\mathtt{typecode}, \mathtt{length}, \mathtt{addr})` encodings
|
2021-04-20 16:11:55 -07:00
|
|
|
|
of the consituent Receivers:
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
2021-04-20 16:11:55 -07:00
|
|
|
|
* :math:`\mathtt{typecode} : \mathtt{byte}` — the Typecode from the
|
2021-04-22 14:00:33 -07:00
|
|
|
|
above Priority List;
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
|
|
|
|
* :math:`\mathtt{length} : \mathtt{byte}` — the length in bytes of
|
|
|
|
|
:math:`\mathtt{addr}`;
|
|
|
|
|
|
2021-04-22 14:00:33 -07:00
|
|
|
|
* :math:`\mathtt{addr} : \mathtt{byte[length]}` — the Receiver Encoding.
|
|
|
|
|
|
|
|
|
|
A Receiver Encoding is the raw encoding of a Shielded Payment Address,
|
|
|
|
|
or the :math:`160`-bit script hash of a P2SH address [#P2SH]_, or the
|
|
|
|
|
:math:`160`-bit validating key hash of a P2PKH address [#P2PKH]_.
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
2021-04-22 14:00:33 -07:00
|
|
|
|
We append 16 zero bytes to the concatenated encodings, and then apply
|
|
|
|
|
the :math:`\mathsf{F4Jumble}` algorithm as described in `Address Hardening`_.
|
|
|
|
|
The output is then encoded with Bech32m [#bip-0350]_, ignoring any
|
|
|
|
|
length restrictions. This is chosen over Bech32 in order to better
|
|
|
|
|
handle variable-length inputs.
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
2021-04-22 14:00:33 -07:00
|
|
|
|
To decode a Unified Address Encoding, a Sender MUST use the following
|
|
|
|
|
procedure:
|
|
|
|
|
|
|
|
|
|
* Decode using Bech32m, rejecting any address with an incorrect checksum.
|
|
|
|
|
* Apply :math:`\mathsf{F4Jumble}^{-1}` (this can also reject if the input
|
|
|
|
|
is not in the correct range of lengths).
|
|
|
|
|
* If the result ends in 16 zero bytes, remove them; otherwise reject.
|
2021-04-22 14:10:41 -07:00
|
|
|
|
* Parse the result as a raw encoding as described above, rejecting the
|
|
|
|
|
entire Unified Address if it does not parse correctly.
|
2021-04-22 14:00:33 -07:00
|
|
|
|
|
|
|
|
|
For Unified Addresses on Mainnet, the Human-Readable Part (as defined
|
|
|
|
|
in [#bip-0350]_) is “``u``”. For Unified Addresses on Testnet, the
|
|
|
|
|
Human-Readable Part is “``utest``”.
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
|
|
|
|
Notes:
|
|
|
|
|
|
|
|
|
|
* The :math:`\mathtt{length}` field is always encoded as a single
|
|
|
|
|
byte, *not* as a :math:`\mathtt{compactSize}`.
|
|
|
|
|
|
2021-04-22 14:00:33 -07:00
|
|
|
|
* For Transparent Addresses, the Receiver Encoding does not include
|
|
|
|
|
the first two bytes of a raw encoding.
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
2021-04-22 14:00:33 -07:00
|
|
|
|
* There is intentionally no Typecode defined for a Sprout Shielded
|
|
|
|
|
Payment Address. Since it is no longer possible (since activation
|
2021-04-08 15:59:30 -07:00
|
|
|
|
of ZIP 211 in the Canopy network upgrade [#zip-0211]_) to send
|
|
|
|
|
funds into the Sprout chain value pool, this would not be generally
|
|
|
|
|
useful.
|
|
|
|
|
|
2021-04-22 14:00:33 -07:00
|
|
|
|
* Senders MUST ignore constituent Addresses with Typecodes they do
|
2021-04-08 15:59:30 -07:00
|
|
|
|
not recognize.
|
|
|
|
|
|
2021-04-22 14:00:33 -07:00
|
|
|
|
* Senders MUST reject Unified Addresses in which the same Typecode
|
|
|
|
|
appears more than once, or that include both P2SH and P2PKH
|
|
|
|
|
Transparent Addresses, or that contain only a Transparent Address.
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
2021-04-22 14:10:41 -07:00
|
|
|
|
* Senders MUST reject Unified Addresses in which *any* constituent
|
|
|
|
|
address does not meet the validation requirements of its
|
|
|
|
|
Receiver Encoding, as specified in the Zcash Protocol Specification
|
|
|
|
|
[#protocol-nu5]_.
|
|
|
|
|
|
2021-04-22 14:00:33 -07:00
|
|
|
|
* Producers SHOULD order the constituent Addresses in the same order
|
|
|
|
|
as in the Priority List above. However, Senders MUST NOT assume
|
|
|
|
|
this ordering, and it does not affect which Address should be used
|
|
|
|
|
by a Sender.
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
2021-04-20 16:11:55 -07:00
|
|
|
|
* There MUST NOT be additional bytes at the end of the raw encoding
|
|
|
|
|
that cannot be interpreted as specified above.
|
|
|
|
|
|
|
|
|
|
* A wallet MAY allow its user(s) to configure which Receiver Types
|
|
|
|
|
it can send to. It MUST NOT allow the user(s) to change the order
|
|
|
|
|
of the Priority List used to choose the Receiver Type.
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
|
|
|
|
|
2021-04-22 14:00:33 -07:00
|
|
|
|
Encoding of Unified Full/Incoming Viewing Keys
|
|
|
|
|
----------------------------------------------
|
|
|
|
|
|
|
|
|
|
Unified Full or Incoming Viewing Keys are encoded analogously to
|
|
|
|
|
Unified Addresses. The same Priority List and the same Typecodes are
|
|
|
|
|
used. For Shielded Addresses, the encoding used in place of the
|
|
|
|
|
:math:`\mathtt{addr}` field is the raw encoding of the Full Viewing
|
|
|
|
|
Key or Incoming Viewing Key.
|
|
|
|
|
|
|
|
|
|
Transparent Addresses do not have separate corresponding viewing keys,
|
|
|
|
|
but the address itself can effectively be used as a viewing key.
|
|
|
|
|
Therefore, a UFVK or UIVK MAY include a Transparent Address, which
|
|
|
|
|
is encoded using the same Typecode and Receiver Encoding as in a
|
|
|
|
|
Unified Address.
|
|
|
|
|
|
|
|
|
|
|
2021-04-08 15:59:30 -07:00
|
|
|
|
Address hardening
|
|
|
|
|
-----------------
|
|
|
|
|
|
|
|
|
|
Security goal (**near second preimage resistance**):
|
|
|
|
|
|
|
|
|
|
* An adversary is given :math:`q` Unified Addresses, generated honestly.
|
|
|
|
|
* The attack goal is to produce a “partially colliding” valid Unified
|
|
|
|
|
Address that:
|
|
|
|
|
|
|
|
|
|
a) has a string encoding matching that of *one of* the input
|
2021-04-22 14:00:33 -07:00
|
|
|
|
Addresses on some subset of characters (for concreteness, consider
|
2021-04-08 15:59:30 -07:00
|
|
|
|
the first :math:`n` and last :math:`m` characters, up to some bound
|
|
|
|
|
on :math:`n+m`);
|
|
|
|
|
b) is controlled by the adversary (for concreteness, the adversary
|
|
|
|
|
knows *at least one* of the private keys of the constituent
|
2021-04-22 14:00:33 -07:00
|
|
|
|
Addresses).
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
|
|
|
|
Security goal (**nonmalleability**):
|
|
|
|
|
|
2021-04-20 16:11:55 -07:00
|
|
|
|
* In this variant, part b) above is replaced by the meaning of the new
|
2021-04-22 14:00:33 -07:00
|
|
|
|
Address being “usefully” different than the Address it is based on, even
|
2021-04-20 16:11:55 -07:00
|
|
|
|
though the adversary does not know any of the private keys. For example,
|
2021-04-22 14:00:33 -07:00
|
|
|
|
if it were possible to delete a shielded constituent Address from a UA
|
|
|
|
|
leaving only a Transparent Address, that would be a significant malleability
|
2021-04-20 16:11:55 -07:00
|
|
|
|
attack.
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
|
|
|
|
Discussion
|
|
|
|
|
''''''''''
|
|
|
|
|
|
|
|
|
|
There is a generic brute force attack against near second preimage
|
|
|
|
|
resistance. The adversary generates UAs at random with known keys, until
|
|
|
|
|
one has an encoding that partially collides with one of the :math:`q` target
|
2021-04-22 14:00:33 -07:00
|
|
|
|
Addresses. It may be possible to improve on this attack by making use of
|
2021-04-08 15:59:30 -07:00
|
|
|
|
properties of checksums, etc.
|
|
|
|
|
|
|
|
|
|
The generic attack puts an upper bound on the achievable security: if it
|
|
|
|
|
takes work :math:`w` to produce and verify a UA, and the size of the character
|
|
|
|
|
set is :math:`c`, then the generic attack costs :math:`\sim \frac{w \cdot
|
|
|
|
|
c^{n+m}}{q}`.
|
|
|
|
|
|
2021-04-20 16:11:55 -07:00
|
|
|
|
There is also a generic brute force attack against nonmalleability. The
|
2021-04-22 14:00:33 -07:00
|
|
|
|
adversary modifies the target Address slightly and computes the corresponding
|
2021-04-20 16:11:55 -07:00
|
|
|
|
decoding, then repeats until the decoding is valid and also useful to the
|
2021-04-22 14:00:33 -07:00
|
|
|
|
adversary (e.g. it would lead to the Sender using a Transparent Address).
|
2021-04-20 16:11:55 -07:00
|
|
|
|
With :math:`w` defined as above, the cost is :math:`w/p` where :math:`p` is
|
|
|
|
|
the probability that a random decoding is of the required form.
|
|
|
|
|
|
2021-04-22 14:00:33 -07:00
|
|
|
|
Solution
|
|
|
|
|
''''''''
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
|
|
|
|
We use an unkeyed 4-round Feistel construction to approximate a random
|
|
|
|
|
permutation. (As explained below, 3 rounds would not be sufficient.)
|
|
|
|
|
|
|
|
|
|
Let :math:`H_i` be a hash personalized by :math:`i`, with maximum output
|
|
|
|
|
length :math:`\ell_H` bytes. Let :math:`G_i` be a XOF (a hash function with
|
|
|
|
|
extendable output length) based on :math:`H`, personalized by :math:`i`.
|
|
|
|
|
|
|
|
|
|
Given input :math:`M` of length :math:`\ell_M` bytes such that
|
2021-04-22 14:23:41 -07:00
|
|
|
|
:math:`48 \leq \ell_M \leq 16448`, define :math:`\mathsf{F4Jumble}(M)`
|
2021-04-08 15:59:30 -07:00
|
|
|
|
by:
|
|
|
|
|
|
|
|
|
|
* let :math:`\ell_L = \mathsf{min}(\ell_H, \mathsf{floor}(\ell_M/2))`
|
|
|
|
|
* let :math:`\ell_R = \ell_M - \ell_L`
|
|
|
|
|
* split :math:`M` into :math:`a` of length :math:`\ell_L` and :math:`b` of length :math:`\ell_R`
|
|
|
|
|
* let :math:`x = b \oplus G_0(a)`
|
|
|
|
|
* let :math:`y = a \oplus H_0(x)`
|
|
|
|
|
* let :math:`d = x \oplus G_1(y)`
|
|
|
|
|
* let :math:`c = y \oplus H_1(d)`
|
|
|
|
|
* return :math:`c \,||\, d`.
|
2021-05-12 02:29:11 -07:00
|
|
|
|
|
|
|
|
|
The inverse function :math:`\mathsf{F4Jumble}^{-1}` is obtained in the usual
|
|
|
|
|
way for a Feistel construction, by observing that :math:`r = p \oplus q` implies :math:`p = r \oplus q`.
|
|
|
|
|
|
2021-04-08 15:59:30 -07:00
|
|
|
|
The first argument to BLAKE2b below is the personalization.
|
|
|
|
|
|
|
|
|
|
We instantiate :math:`H_i(u)` by
|
2021-05-12 02:28:34 -07:00
|
|
|
|
:math:`\mathsf{BLAKE2b‐}(8\ell_L)(\texttt{“UA_F4Jumble_H_”} \,||\,`
|
2021-04-08 15:59:30 -07:00
|
|
|
|
:math:`[i, 0], u)`.
|
|
|
|
|
|
|
|
|
|
We instantiate :math:`G_i(u)` as the first :math:`\ell_R` bytes of the
|
|
|
|
|
concatenation of
|
2021-05-12 02:28:34 -07:00
|
|
|
|
:math:`[\mathsf{BLAKE2b‐}512(\texttt{“UA_F4Jumble_G_”} \,||\,`
|
2021-04-08 15:59:30 -07:00
|
|
|
|
:math:`[i, j], u) \text{ for } j \text{ from } 0 \text{ up to}`
|
|
|
|
|
:math:`\mathsf{ceiling}(\ell_R/\ell_H)-1]`.
|
|
|
|
|
|
|
|
|
|
.. figure:: zip-0316-f4.png
|
2021-05-12 07:26:08 -07:00
|
|
|
|
:width: 372px
|
2021-04-08 15:59:30 -07:00
|
|
|
|
:align: center
|
|
|
|
|
:figclass: align-center
|
|
|
|
|
|
|
|
|
|
Diagram of 4-round unkeyed Feistel construction
|
|
|
|
|
|
|
|
|
|
(In practice the lengths :math:`\ell_L` and :math:`\ell_R` will be roughly
|
|
|
|
|
the same until :math:`\ell_M` is larger than :math:`128` bytes.)
|
|
|
|
|
|
2021-04-22 14:23:41 -07:00
|
|
|
|
Usage for Unified Addresses, UFVKs, and UIVKs
|
|
|
|
|
'''''''''''''''''''''''''''''''''''''''''''''
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
2021-04-22 14:00:33 -07:00
|
|
|
|
In order to prevent the generic attack against nonmalleability, there
|
|
|
|
|
needs to be some redundancy in the encoding. Therefore, the Producer of
|
2021-04-22 14:23:41 -07:00
|
|
|
|
a Unified Address, UFVK, or UIVK appends 16 zero bytes to the raw encoding,
|
|
|
|
|
then applies :math:`\mathsf{F4Jumble}` before encoding the result with
|
|
|
|
|
Bech32m.
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
2021-04-22 14:00:33 -07:00
|
|
|
|
The Sender rejects any Bech32m-decoded byte sequence that is less than
|
2021-04-22 14:23:41 -07:00
|
|
|
|
48 bytes or greater than 16448 bytes; otherwise it applies
|
2021-04-20 16:11:55 -07:00
|
|
|
|
:math:`\mathsf{F4Jumble}^{-1}`. It rejects any result that does not end
|
|
|
|
|
in 16 zero bytes, before stripping these 16 bytes and parsing the result.
|
|
|
|
|
|
2021-04-22 14:23:41 -07:00
|
|
|
|
(48 bytes is the minimum size of a valid UA, UFVK, or UIVK raw encoding
|
|
|
|
|
plus 16 zero bytes, corresponding to a single Sapling Incoming Viewing Key.
|
|
|
|
|
16448 bytes is the largest input/output size supported by :math:`\mathsf{F4Jumble}`.)
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
|
|
|
|
Heuristic analysis
|
|
|
|
|
''''''''''''''''''
|
|
|
|
|
|
|
|
|
|
A 3-round unkeyed Feistel, as shown, is not sufficient:
|
|
|
|
|
|
|
|
|
|
.. figure:: zip-0316-f3.png
|
2021-05-12 07:26:08 -07:00
|
|
|
|
:width: 372px
|
2021-04-08 15:59:30 -07:00
|
|
|
|
:align: center
|
|
|
|
|
:figclass: align-center
|
|
|
|
|
|
|
|
|
|
Diagram of 3-round unkeyed Feistel construction
|
|
|
|
|
|
|
|
|
|
Suppose that an adversary has a target input/output pair
|
|
|
|
|
:math:`(a \,||\, b, c \,||\, d)`, and that the input to :math:`G_0` is
|
|
|
|
|
:math:`x`. By fixing :math:`x`, we can obtain another pair
|
|
|
|
|
:math:`((a \oplus t) \,||\, b', (c \oplus t) \,||\, d')` such that
|
|
|
|
|
:math:`a \oplus t` is close to :math:`a` and :math:`c \oplus t` is close
|
|
|
|
|
to :math:`c`.
|
|
|
|
|
(:math:`b'` and :math:`d'` will not be close to :math:`b` and :math:`d`,
|
|
|
|
|
but that isn't necessarily required for a valid attack.)
|
|
|
|
|
|
|
|
|
|
A 4-round Feistel thwarts this and similar attacks. Defining :math:`x` and
|
|
|
|
|
:math:`y` as the intermediate values in the first diagram above:
|
|
|
|
|
|
|
|
|
|
* if :math:`(x', y')` are fixed to the same values as :math:`(x, y)`, then
|
|
|
|
|
:math:`(a', b', c', d') = (a, b, c, d)`;
|
|
|
|
|
|
|
|
|
|
* if :math:`x' = x` but :math:`y' \neq y`, then the adversary is able to
|
|
|
|
|
introduce a controlled :math:`\oplus`-difference
|
|
|
|
|
:math:`a \oplus a' = y \oplus y'`, but the other three pieces
|
|
|
|
|
:math:`(b, c, d)` are all randomized, which is sufficient;
|
|
|
|
|
|
|
|
|
|
* if :math:`y' = y` but :math:`x' \neq x`, then the adversary is able to
|
|
|
|
|
introduce a controlled :math:`\oplus`-difference
|
|
|
|
|
:math:`d \oplus d' = x \oplus x'`, but the other three pieces
|
|
|
|
|
:math:`(a, b, c)` are all randomized, which is sufficient;
|
|
|
|
|
|
|
|
|
|
* if :math:`x' \neq x` and :math:`y' \neq y`, all four pieces are
|
|
|
|
|
randomized.
|
|
|
|
|
|
2021-04-22 15:18:34 -07:00
|
|
|
|
Note that the size of each piece is at least 24 bytes.
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
|
|
|
|
It would be possible to make an attack more expensive by making the work
|
2021-04-22 14:00:33 -07:00
|
|
|
|
done by a Producer more expensive. (This wouldn't necessarily have to
|
|
|
|
|
increase the work done by the Sender.) However, given that Unified Addresses
|
|
|
|
|
may need to be produced on constrained computing platforms, this was not
|
|
|
|
|
considered to be beneficial overall.
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
|
|
|
|
Efficiency
|
|
|
|
|
''''''''''
|
|
|
|
|
|
|
|
|
|
The cost is dominated by 4 BLAKE2b compressions for :math:`\ell_M \leq 128`
|
2021-04-22 14:00:33 -07:00
|
|
|
|
bytes. A UA containing a Transparent Address, a Sapling Address, and an
|
2021-04-22 15:18:34 -07:00
|
|
|
|
Orchard Address, would have :math:`\ell_M = 128` bytes. The restriction
|
2021-04-22 14:00:33 -07:00
|
|
|
|
to a single Address with a given Typecode (and at most one Transparent
|
|
|
|
|
Address) means that this is also the maximum length as of NU5 activation.
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
2021-04-20 16:11:55 -07:00
|
|
|
|
For longer UAs (when other Typecodes are added), the cost increases to 6
|
2021-04-08 15:59:30 -07:00
|
|
|
|
BLAKE2b compressions for :math:`128 < \ell_M \leq 192`, and 10 BLAKE2b
|
|
|
|
|
compressions for :math:`192 < \ell_M \leq 256`, for example. The maximum
|
|
|
|
|
cost for which the algorithm is defined would be 768 BLAKE2b compressions
|
|
|
|
|
at :math:`\ell_M = 16448` bytes. We will almost certainly never add enough
|
2021-04-20 16:11:55 -07:00
|
|
|
|
Typecodes to reach that, and we might want to define a smaller limit.
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
|
|
|
|
The memory usage, for a memory-optimized implementation, is roughly
|
|
|
|
|
:math:`\ell_M` bytes plus the size of a BLAKE2b hash state.
|
|
|
|
|
|
|
|
|
|
Dependencies
|
|
|
|
|
''''''''''''
|
|
|
|
|
|
|
|
|
|
BLAKE2b, with personalization and variable output length, is the only
|
|
|
|
|
external dependency. TODO: would it be useful to remove the requirement
|
|
|
|
|
for variable output length?
|
|
|
|
|
|
|
|
|
|
Related work
|
|
|
|
|
''''''''''''
|
|
|
|
|
|
2021-04-22 15:23:27 -07:00
|
|
|
|
`Eliminating Random Permutation Oracles in the Even–Mansour Cipher <https://www.iacr.org/cryptodb/data/paper.php?pubkey=218>`_
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
|
|
|
|
* This paper argues that a 4-round unkeyed Feistel is sufficient to
|
|
|
|
|
replace a random permutation in the Even–Mansour cipher construction.
|
|
|
|
|
|
2021-04-22 15:23:27 -07:00
|
|
|
|
`On the Round Security of Symmetric-Key Cryptographic Primitives <https://www.iacr.org/archive/crypto2000/18800377/18800377.pdf>`_
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
2021-04-22 15:23:27 -07:00
|
|
|
|
`LIONESS <https://www.cl.cam.ac.uk/~rja14/Papers/bear-lion.pdf>`_ is a similarly structured 4-round unbalanced Feistel cipher.
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Reference implementation
|
|
|
|
|
========================
|
|
|
|
|
|
2021-04-22 14:00:33 -07:00
|
|
|
|
TODO.
|
|
|
|
|
|
2021-04-08 15:59:30 -07:00
|
|
|
|
|
|
|
|
|
Acknowledgements
|
|
|
|
|
================
|
|
|
|
|
|
|
|
|
|
The authors would like to thank Benjamin Winston, Zooko Wilcox, Francisco Gindre,
|
2021-04-20 16:11:55 -07:00
|
|
|
|
Marshall Gaucher, Joseph Van Geffen, Brad Miller, Deirdre Connolly, and Teor for
|
2021-04-08 15:59:30 -07:00
|
|
|
|
discussions on the subject of Unified Addresses.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
References
|
|
|
|
|
==========
|
|
|
|
|
|
|
|
|
|
.. [#RFC2119] `RFC 2119: Key words for use in RFCs to Indicate Requirement Levels <https://www.rfc-editor.org/rfc/rfc2119.html>`_
|
2021-04-22 14:43:34 -07:00
|
|
|
|
.. [#protocol-nu5] `Zcash Protocol Specification, Version 2020.1.24 or later [NU5 proposal] <protocol/nu5.pdf>`_
|
|
|
|
|
.. [#protocol-saplingpaymentaddrencoding] `Zcash Protocol Specification, Version 2020.1.24 [NU5 proposal]. Section 5.6.3.1: Sapling Payment Addresses <protocol/nu5.pdf#saplingpaymentaddrencoding>`_
|
|
|
|
|
.. [#protocol-orchardpaymentaddrencoding] `Zcash Protocol Specification, Version 2020.1.24 [NU5 proposal]. Section 5.6.4.2: Orchard Raw Payment Addresses <protocol/nu5.pdf#orchardpaymentaddrencoding>`_
|
2021-04-08 15:59:30 -07:00
|
|
|
|
.. [#zip-0211] `ZIP 211: Disabling Addition of New Value to the Sprout Chain Value Pool <zip-0211.rst>`_
|
|
|
|
|
.. [#zip-0224] `ZIP 224: Orchard Shielded Protocol <zip-0224.rst>`_
|
|
|
|
|
.. [#zip-0321] `ZIP 321: Payment Request URIs <zip-0321.rst>`_
|
|
|
|
|
.. [#bip-0350] `BIP 350: Bech32m format for v1+ witness addresses <https://github.com/bitcoin/bips/blob/master/bip-0350.mediawiki>`_
|
|
|
|
|
.. [#P2PKH] `Transactions: P2PKH Script Validation — Bitcoin Developer Guide <https://developer.bitcoin.org/devguide/transactions.html#p2pkh-script-validation>`_
|
|
|
|
|
.. [#P2SH] `Transactions: P2SH Scripts — Bitcoin Developer Guide <https://developer.bitcoin.org/devguide/transactions.html#pay-to-script-hash-p2sh>`_
|