This page is the Simplified Technical English version of ZIP 216. The source ZIP is the normative text. Read the writing rules to understand the marked words.
ZIP 216: Require Canonical Jubjub Point Encodings
ZIP: 216
Title: Require Canonical Jubjub Point Encodings
Owners: Jack Grigg <thestr4d@gmail.com>
Daira-Emma Hopwood <daira@jacaranda.org>
Status: Final
Category: Consensus
Created: 2021-02-11
License: MIT
Discussions-To: <https://github.com/zcash/zips/issues/400>
Terminology
On this page, STE words are in the place of the BCP 14 key words of the source. Refer to the key word table.
The term "network upgrade" has the definition in ZIP 200 [zip-0200].
The terms "settled" and "full validator" have the definitions in [protocol-blockchain].
The terms "Mainnet" and "Testnet" have the definitions in [protocol-networks].
Abstract
This ZIP contains a fix for an oversight in the implementation of the Sapling consensus rules. The fix is the rejection of all non-canonical representations of Jubjub points.
Motivation
The Sapling specification was originally written with this intent: all values, including Jubjub points, are strongly typed with canonical representations [protocol-jubjub]. This has significant advantages for security analysis, because the protocol can be modeled with only the abstract types.
The intent of the Jubjub implementation was to make sure that the decoding logic accepts only canonical point encodings. This applies to the jubjub crate [jubjub-crate] and to its previous implementations. But because of an oversight in the implementation, there is an edge case. For each point on the curve where the \(u\)-coordinate is zero, the decoding logic accepts two encodings:
// Fix the sign of `u` if necessary let flip_sign = Choice::from((u.to_bytes()[0] ^ sign) & 1); let u_negated = -u; let final_u = Fq::conditional_select(&u, &u_negated, flip_sign);
This code accepts either sign bit, because u_negated == u.
There are two points on the Jubjub curve with \(u\)-coordinate zero:
- \((0, 1)\) is the identity.
- \((0, -1)\) is a point of order two.
Each of these has a single non-canonical encoding. In this encoding, the value of the sign bit is \(1\).
The result is a consensus issue, because either of the above encodings can be decoded and then re-encoded to a different encoding. (Other non-canonical point encodings are rejected.)
For example, some node implementations can store points internally as abstract curve points and use these points to derive transaction IDs. If a non-canonical encoding appears in a transaction field, these implementations derive different IDs than nodes that store transactions as bytes (such as zcashd).
No security vulnerability from this issue is known, beyond the risk of consensus incompatibility. In fact, for some of the fields that the issue can have an effect on, the issue does not occur. The reason is that small-order points are already prohibited in these fields by consensus rules. Thus non-canonical encodings are incidentally prohibited also.
Adjustments to the protocol specification were made in these versions to match the zcashd implementation:
- 2020.1.8
- 2020.1.9
- 2020.1.15
- 2021.1.17
- 2023.4.0.
Further changes were also made in version 2025.6.0. Six specification revisions were necessary to get this right. This fact is a conclusive demonstration of the problem.
Specification
Let \(\mathsf{abst}_{\mathbb{J}}\), \(\mathsf{repr}_{\mathbb{J}}\), and \(q_{\mathbb{J}}\) be as defined in [protocol-jubjub].
In this ZIP, a non-canonical compressed encoding of a Jubjub point is a sequence of \(256\) bits, \(b\), such that \(\mathsf{abst}_{\mathbb{J}}(b) \neq \bot\) and \(\mathsf{repr_{\mathbb{J}}}\big(\mathsf{abst}_{\mathbb{J}}(b)\big) \neq b\).
Non-normative note: There are two such bit sequences, \(\mathsf{I2LEOSP}_{\ell_{\mathbb{J}}}(2^{255} + 1)\) and \(\mathsf{I2LEOSP}_{\ell_{\mathbb{J}}}(2^{255} + q_{\mathbb{J}} - 1)\). In the Sapling protocol, the ordering for conversion between bit sequences and byte sequences is little-endian. Thus the first of these sequences corresponds to a \(\mathtt{0x01}\) byte, then \(30\) zero bytes, and then a \(\mathtt{0x80}\) byte.
After this ZIP activates, non-canonical Jubjub point encodings must be rejected in the following places within the Sapling consensus protocol where Jubjub points occur.
In Sapling Spend descriptions [protocol-spenddesc]:
- The \(\underline{R}\) component (that is, the first \(32\) bytes) of the \(\mathtt{spendAuthSig}\) RedDSA signature.
In transactions [protocol-txnencoding]:
- The \(\underline{R}\) component (that is, the first \(32\) bytes) of the \(\mathtt{bindingSigSapling}\) RedDSA signature.
In the plaintext that results from the decryption of the \(\mathsf{C^{out}}\) field of a Sapling transmitted note ciphertext (the encryption is in [protocol-saplingandorchardencrypt], and the decryption is in [protocol-decryptovk]):
- \(\mathsf{pk\star_d}\).
Also, \(\mathsf{pk\star_d}\) must be considered invalid if it encodes the zero point \(\mathcal{O}_{\mathbb{J}}\).
These requirements on \(\mathsf{pk\star_d}\) have an effect on the decryption of \(\mathsf{C^{out}}\) in all cases. But they are consensus-critical only for the decryption of \(\mathsf{C^{out}}\) for a Sapling shielded coinbase output [protocol-txnconsensus] [zip-0213].
Note: When an implementation decrypts a Sapling transmitted note ciphertext with an incoming viewing key [protocol-decryptivk], it calculates \(\mathsf{pk_d}\) as \(\mathsf{KA^{Sapling}.DerivePublic}(\mathsf{ivk}, \mathsf{g_d}) =\) \([\mathsf{ivk}]\,\mathsf{g_d}\). Because \(\mathsf{g_d}\) is an output of \(\mathsf{DiversifyHash^{Sapling}} \;{\small ⦂}\; \mathbb{B}^{[\ell_d]} \rightarrow \mathbb{J}^{(r)*} \cup \{\bot\}\), it cannot be \(\mathcal{O}_{\mathbb{J}}\). The value \(\mathsf{ivk}\) cannot be \(0\) for a validly constructed Sapling incoming viewing key [protocol-saplingkeycomponents]. Thus the calculated value of \(\mathsf{pk_d}\) cannot be \(\mathcal{O}_{\mathbb{J}}\). An implementation can redundantly enforce that the calculated value of \(\mathsf{pk_d}\) is not \(\mathcal{O}_{\mathbb{J}}\).
There are some additional fields in the consensus protocol that encode Jubjub points. But in these fields, non-canonical encodings must already be rejected as a side effect of existing consensus rules.
In Sapling Spend descriptions:
- \(\mathtt{cv}\)
- \(\mathtt{rk}\).
In Sapling Output descriptions [protocol-outputdesc]:
- \(\mathtt{cv}\)
- \(\mathtt{ephemeralKey}\).
By consensus, these fields cannot contain small-order points. All of the points with non-canonical encodings are small-order.
Implementations can reject non-canonical encodings of the above four fields early in the decoding of a transaction. A risk is thus removed. The risk is that parts of the transaction can be re-serialized from their internal representation to a different byte sequence than in the original transaction. For example, this can occur during the calculation of transaction IDs.
In addition, a Sapling address or full viewing key must be considered invalid when imported if it contains one of these items:
- A non-canonical Jubjub point encoding.
- An encoding of a point that is not in the prime-order subgroup \(\mathbb{J}^{(r)}\).
These requirements can be enforced before NU5 activation. These requirements have an effect on the fields in the lists below.
In Sapling payment addresses [protocol-saplingpaymentaddrencoding]:
- The encoding of \(\mathsf{pk_d}\).
In Sapling full viewing keys [protocol-saplingfullviewingkeyencoding] and extended full viewing keys [zip-0032-extfvk]:
- The encoding of \(\mathsf{ak}\)
- The encoding of \(\mathsf{nk}\).
Also, \(\mathsf{pk_d}\) and \(\mathsf{ak}\) must be considered invalid if they encode the zero point \(\mathcal{O}_{\mathbb{J}}\).
The fields in this Specification section are intended to be a complete list. The list has each place where compressed encodings of Jubjub points occur in these items:
- The Zcash consensus protocol.
- Plaintext formats.
- Address formats.
- Key formats.
Note: In some versions of the Zcash protocol specification, it was possible by mistake for \(\mathsf{pk_d}\) in a Sapling payment address to encode the zero point. This was also possible for \(\mathsf{pk\star_d}\) in a decrypted \(\mathsf{C^{out}}\). The history is in a note that was added in version 2023.4.0 of the protocol specification [protocol-2023.4.0]:
A previous version of this specification did not have this requirement: the decoded point \(\mathsf{pk_d}\) of a Sapling note is in the set of prime-order points \(\mathbb{J}^{(r)*}\) (that is, "if ... \(\mathsf{pk_d} \not\in \mathbb{J}^{(r)*}\), return \(\bot\!\)"). This did not match the implementation in
zcashd. In fact, the history is a little more complicated.The current specification matches the implementation in
librustzcashas of [librustzcash-pr109]. Since v2.1.2,zcashduses this implementation.But
zcashdalso had another implementation of Sapling note decryption. It used this implementation for consensus checks, specifically the check that the decryption of a shielded coinbase output with the zero \(\mathsf{ovk}\) succeeds.This was corrected in
zcashdv5.5.0, to enforce the same restriction on the decrypted \(\mathsf{pk_d}\). This correction was originally set to activate in a soft fork at block height 2121200 on both Mainnet and Testnet [zcashd-pr6459]. (On Testnet, this height was in the past at the release ofzcashdv5.5.0. Thus the change was enforced immediately on upgrade.)The soft fork was observed to be retrospectively valid after that height. Thus the implementation was simplified in [zcashd-pr6725] to use the
librustzcashimplementation in all cases. This reflects the specification above.zebraalways used thelibrustzcashimplementation.
The protocol specification was updated again in version 2025.6.0 [protocol-2025.6.0]. In this update, the type of \(\mathsf{ivk}\) in Sapling was tightened to \(\{ 1\,..\, 2^{\ell^{\mathsf{Sapling}}_{\mathsf{ivk}}}\!-1 \}\). The type of \(\mathsf{pk_d}\) in both Sapling and Orchard was tightened to \(\mathsf{KA^{protocol}.PublicPrimeOrder}\). The purpose was to make the exclusion of the zero point more obvious [zips-issue664].
This update also has this effect. A Sapling incoming viewing key [protocol-saplinginviewingkeyencoding] that encodes the zero \(\mathsf{ivk}\) must be considered invalid when imported. A Sapling IVK Encoding in a Unified Incoming Viewing Key [zip-0316] that encodes the zero \(\mathsf{ivk}\) also must be considered invalid when imported.
Another note was also added. This note is explicitly about the encoding of \(\mathsf{pk_d}\) in Sapling payment addresses [protocol-saplingpaymentaddrencoding]:
The restriction on \(\mathsf{pk_d}\) reflects its current type \(\mathsf{KA^{Sapling}.PublicPrimeOrder} = \mathbb{J}^{(r)*}\). In versions of this specification before 2025.6.0, \(\mathsf{pk_d}\) had the type \(\mathsf{KA^{Sapling}.PublicPrimeSubgroup} = \mathbb{J}^{(r)}\), that is, including \(\mathcal{O}_{\mathbb{J}}\).
An update to exclude \(\mathcal{O}_{\mathbb{J}}\) can be necessary for implementations of consumers for this encoding. We recommend that these implementations are checked for consistency with the current version of [ZIP-216].
Retroactive applicability
As originally specified in this ZIP, it was necessary to apply the new validity rules only after NU5 activation. This was necessary because it was possible for any block before NU5 activation to include a transaction that contains a non-canonical Jubjub point encoding.
But NU5 is now a settled network upgrade on the Zcash Mainnet and Testnet chains [protocol-blockchain] [protocol-networks]. Thus it can be observed that there were no such non-canonical encodings in publicly visible transaction fields before the Mainnet and Testnet NU5 activations. Thus a full validator can enforce the above specification retroactively.
It is still possible that there are non-canonical \(\mathsf{pk\star_d}\) encodings in some plaintexts. These are plaintexts that result from the decryption of the \(\mathsf{C^{out}}\) field of a Sapling transmitted note ciphertext. Such encodings must be rejected by the decryption procedure in [protocol-decryptovk] as it is specified at this time.
In version 2025.6.0 of the protocol specification [protocol-2025.6.0], this procedure was changed to reject them unconditionally, not only after NU5 activation. (This change has no effect on consensus relative to the previous version. The reason is that only small-order Jubjub curve points have non-canonical encodings. Thus the check that returns \(\bot\) if \(\mathsf{pk_d} ∉ \mathbb{J}^{(r)*}\) catches all such cases.)
The rejection of non-canonical \(\mathsf{pk\star_d}\) encodings cannot be the cause of a loss of funds that are sent to a correctly generated Sapling address. (This is an address that is generated as specified in [protocol-saplingkeycomponents].) The reason is that such an address cannot have \(\mathsf{ivk} = 0\). This is the only case where \(\mathsf{pk\star_d}\) can be non-canonical.
Current zcashd and light wallets that are based on librustzcash reject these encodings during wallet rescanning.
Note: There are no such non-canonical \(\mathsf{pk\star_d}\) encodings in the \(\mathsf{C^{out}}\) components of shielded coinbase outputs. (By consensus, it is necessary that they are decryptable by an all-zero \(\mathsf{ovk}\) [protocol-txnconsensus].)
Rationale
Zcash had a similar issue before, with non-canonical representations of points in Ed25519 public keys and signatures. Ed25519 signatures are common in the wider ecosystem. Thus, in that case, the decision in ZIP 215 [zip-0215] was to accept non-canonical representations of points. (ZIP 215 activated with the Canopy network upgrade [zip-0251].)
In Sapling, we have the motivation to reject these non-canonical points instead, for these reasons:
- The chance that the identity occurs anywhere in the Sapling components of transactions from implementations that follow the standard protocol is cryptographically negligible.
- With this choice, the simpler security analysis of the Sapling protocol, as described above, is possible again.
- The Jubjub curve has a vastly smaller scope of usage in the general cryptographic ecosystem than Curve25519 and Ed25519.
The necessary checks are very simple. No cryptographic operations are necessary for these checks. Thus the effect on performance is negligible.
There is no effect on the public inputs of Jubjub points to the Spend circuit (\(\!\mathsf{rk}\) and \(\mathsf{cv^{old}}\)) and the Output circuit (\(\!\mathsf{cv^{new}}\) and \(\mathsf{epk}\)). The reason is that these inputs are represented in affine coordinates as elements of the correct field (\(\!\mathbb{F}_{r_\mathbb{S}} = \mathbb{F}_{q_\mathbb{J}}\)). Thus no issue of encoding canonicity arises.
There is no effect on encodings of elliptic curve points on the following:
- Curve25519
- BN-254 \(\mathbb{G}_1\)
- BN-254 \(\mathbb{G}_2\)
- BLS12-381 \(\mathbb{G}_1\)
- BLS12-381 \(\mathbb{G}_2\).
There is also no effect on encodings of elliptic curve points on the Pallas and Vesta curves [protocol-pallasandvesta]. These curves are used by the Orchard shielded protocol.
Security and Privacy Considerations
With this ZIP, a potential source of consensus divergence between different full node implementations is eliminated. From February 2023 onward, no divergence of this type is known for any production implementation of Zcash. But an early alpha version of the zebrad node implementation was susceptible to this issue.
Deployment
This ZIP activated with Network Upgrade 5. Requirements on points that are encoded in payment addresses and full viewing keys can be enforced before NU5 activation.
zcashd retroactively enforces canonical encoding of Jubjub points for the entire chain history, as described in the Retroactive applicability section. This enforcement is in these zcashd pull requests:
- #6000 [zcashd-pr6000]
- #6399 [zcashd-pr6399]
- #6459 [zcashd-pr6459]
- #6725 [zcashd-pr6725].
References
- [BCP14]
- Information on BCP 14 — "RFC 2119: Key words for use in RFCs to Indicate Requirement Levels" and "RFC 8174: Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words"
- [protocol]
- Zcash Protocol Specification, Version 2025.6.1 [NU6.1] or later
- [protocol-blockchain]
- Zcash Protocol Specification, Version 2025.6.1 [NU6.1]. Section 3.3: The Block Chain
- [protocol-networks]
- Zcash Protocol Specification, Version 2025.6.1 [NU6.1]. Section 3.12: Mainnet and Testnet
- [protocol-saplingkeycomponents]
- Zcash Protocol Specification, Version 2025.6.1 [NU6.1]. Section 4.2.2: Sapling Key Components
- [protocol-spenddesc]
- Zcash Protocol Specification, Version 2025.6.1 [NU6.1]. Section 4.4: Spend Descriptions
- [protocol-outputdesc]
- Zcash Protocol Specification, Version 2025.6.1 [NU6.1]. Section 4.5: Output Descriptions
- [protocol-saplingandorchardencrypt]
- Zcash Protocol Specification, Version 2025.6.1 [NU6.1]. Section 4.20.1: Encryption (Sapling and Orchard)
- [protocol-decryptivk]
- Zcash Protocol Specification, Version 2025.6.1 [NU6.1]. Section 4.20.2: Decryption using an Incoming Viewing Key (Sapling and Orchard)
- [protocol-decryptovk]
- Zcash Protocol Specification, Version 2025.6.1 [NU6.1]. Section 4.20.3: Decryption using an Outgoing Viewing Key (Sapling and Orchard)
- [protocol-jubjub]
- Zcash Protocol Specification, Version 2025.6.1 [NU6.1]. Section 5.4.9.3: Jubjub
- [protocol-pallasandvesta]
- Zcash Protocol Specification, Version 2025.6.1 [NU6.1]. Section 5.4.9.6: Pallas and Vesta
- [protocol-saplingpaymentaddrencoding]
- Zcash Protocol Specification, Version 2025.6.1 [NU6.1]. Section 5.6.3.1: Sapling Payment Addresses
- [protocol-saplinginviewingkeyencoding]
- Zcash Protocol Specification, Version 2025.6.1 [NU6.1]. Section 5.6.3.2: Sapling Incoming Viewing Keys
- [protocol-saplingfullviewingkeyencoding]
- Zcash Protocol Specification, Version 2025.6.1 [NU6.1]. Section 5.6.3.3: Sapling Full Viewing Keys
- [protocol-txnencoding]
- Zcash Protocol Specification, Version 2025.6.1 [NU6.1]. Section 7.1: Transaction Encoding and Consensus
- [protocol-txnconsensus]
- Zcash Protocol Specification, Version 2025.6.1 [NU6.1]. Section 7.1.2: Transaction Consensus Rules
- [protocol-2023.4.0]
- Zcash Protocol Specification, Version 2023.4.0. Section 10: Change History — 2023.4.0
- [protocol-2025.6.0]
- Zcash Protocol Specification, Version 2025.6.1 [NU6.1]. Section 10: Change History — 2025.6.0
- [zip-0032-extfvk]
- ZIP 32: Shielded Hierarchical Deterministic Wallets. Sapling extended full viewing keys
- [zip-0200]
- ZIP 200: Network Upgrade Mechanism
- [zip-0213]
- ZIP 213: Shielded Coinbase
- [zip-0215]
- ZIP 215: Explicitly Defining and Modifying Ed25519 Validation Rules
- [zip-0251]
- ZIP 251: Deployment of the Canopy Network Upgrade
- [zip-0316]
- ZIP 316: Unified Addresses and Unified Viewing Keys
- [jubjub-crate]
- jubjub Rust crate
- [zcashd-pr6000]
- zcash/zcash PR 6000: Enable ZIP 216 for blocks prior to NU5 activation
- [zcashd-pr6399]
- zcash/zcash PR 6399: Retroactively enable ZIP 216 before NU5 activation
- [zcashd-pr6459]
- zcash/zcash PR 6459: Migrate to zcash_primitives 0.10
- [zcashd-pr6725]
- zcash/zcash PR 6725: Retroactively use Rust to decrypt shielded coinbase before soft fork
- [librustzcash-pr109]
- zcash/librustzcash PR 109: PaymentAddress encapsulation
- [zips-issue664]
- zcash/zips issue 664: Sapling pk_d should not allow the zero point