mirror of https://github.com/zcash/zips.git
106 lines
4.6 KiB
ReStructuredText
106 lines
4.6 KiB
ReStructuredText
::
|
|
|
|
ZIP: 302
|
|
Title: Standardized Memo Field Format
|
|
Owners: Jack Grigg <jack@electriccoin.co>
|
|
Original-Authors: Jay Graber
|
|
Status: Draft
|
|
Category: Standards / RPC / Wallet
|
|
Created: 2017-02-08
|
|
Discussions-To: <https://github.com/zcash/zips/issues/366>
|
|
Pull-Request: <https://github.com/zcash/zips/pull/105>
|
|
|
|
Abstract
|
|
========
|
|
|
|
This ZIP describes a proposed specification for a standardized format for clients who wish
|
|
to transmit or receive content within the encrypted memo field of shielded transactions.
|
|
|
|
Motivation
|
|
==========
|
|
|
|
A well-defined standard for formatting content within the encrypted memo field will help
|
|
expand its use within the Zcash ecosystem by providing a commonly recognized format for
|
|
memo values carrying different types of data. Users and third-party services benefit from
|
|
standardized formatting rules that define the type and length of the data contained within.
|
|
|
|
Specification
|
|
=============
|
|
|
|
Section 5.5 of the Zcash protocol specification [#protocol]_ defines three cases
|
|
for the encoding of a memo field:
|
|
|
|
* a UTF-8 human-readable string [#UTF-8]_, padded by appending zero bytes; or
|
|
* the byte ``0xF6`` followed by 511 ``0x00`` bytes, indicating "no memo"; or
|
|
* any other sequence of 512 bytes starting with a byte value ``0xF5`` or greater (which is
|
|
therefore not a valid UTF-8 string), as specified in ZIP 302.
|
|
|
|
This ZIP refines the specification of the third case.
|
|
|
|
The following specification constrains a party, called the "reader", that interprets the
|
|
contents of a memo. It does not define consensus requirements.
|
|
|
|
+ If the first byte (byte 0) has a value of ``0xF4`` or smaller, then the reader MUST:
|
|
|
|
+ strip any trailing zero bytes
|
|
+ decode it as a UTF-8 string (if decoding fails then report an error).
|
|
|
|
+ If the first byte has a value of ``0xF6``, and the remaining 511 bytes are ``0x00``,
|
|
then the user supplied no memo, and the encrypted memo field is to be treated as empty.
|
|
|
|
+ If the memo matches any of these patterns, then this memo is from the future, because
|
|
these ranges are reserved for future updates to this specification:
|
|
|
|
+ The first byte has a value of ``0xF6``, and the remaining 511 bytes are not all
|
|
``0x00``.
|
|
+ The first byte has a value between ``0xF7`` and ``0xFE`` inclusive.
|
|
|
|
+ If the first byte has a value of ``0xFF`` then the reader should not make any other
|
|
assumption about the memo. In order to put arbitrary data into a memo field (that
|
|
might have some private non-standard structure), the value of the first byte SHOULD
|
|
be set to 0xFF; the remaining 511 bytes are then unconstrained.
|
|
|
|
+ If the first byte has a value of ``0xF5``, then the reader should not make any other
|
|
assumption about the memo. This value was used ambiguously in the past by private
|
|
agreement; applications SHOULD prefer ``0xFF`` which is unambiguously for this purpose.
|
|
|
|
Rationale
|
|
=========
|
|
|
|
The new protocol specification is an improvement over the current memo field content
|
|
specification that was in the protocol spec up to version 2020.1.0, which stated:
|
|
|
|
The usage of the memo field is by agreement between the sender and recipient of the
|
|
note. The memo field SHOULD be encoded either as:
|
|
|
|
+ a UTF-8 human-readable string [Unicode], padded by appending zero bytes; or
|
|
+ an arbitrary sequence of 512 bytes starting with a byte value of ``0xF5`` or
|
|
greater, which is therefore not a valid UTF-8 string.
|
|
|
|
In the former case, wallet software is expected to strip any trailing zero bytes and
|
|
then display the resulting UTF-8 string to the recipient user, where applicable.
|
|
Incorrect UTF-8-encoded byte sequences should be displayed as replacement characters
|
|
(``U+FFFD``).
|
|
|
|
In the latter case, the contents of the memo field SHOULD NOT be displayed. A start
|
|
byte of ``0xF5`` is reserved for use by automated software by private agreement. A
|
|
start byte of ``0xF6`` or greater is reserved for use in future Zcash protocol
|
|
extensions.
|
|
|
|
See issue `#1849`_ for further discussion.
|
|
|
|
.. _`#1849`: https://github.com/zcash/zcash/issues/1849
|
|
|
|
Backwards Compatibility
|
|
=======================
|
|
|
|
Encrypted memo field contents sent without the standardized format proposed here will be
|
|
interpreted according to the specification set out in older versions of the protocol spec.
|
|
|
|
References
|
|
==========
|
|
|
|
.. [#protocol] `Zcash Protocol Specification, Version 2021.1.19 <protocol/protocol.pdf>`_
|
|
.. [#UTF-8] `UTF-8, a transformation format of ISO 10646 <https://www.rfc-editor.org/rfc/rfc3629.html>`_
|
|
.. [#Bitcoin-CompactSize] `Variable length integer. Bitcoin Wiki <https://en.bitcoin.it/wiki/Protocol_documentation#Variable_length_integer>`_
|