[ZIP 230, ZIP 246] v6 transaction format and sighash by str4d · Pull Request #987 · zcash/zips

str4d · 2025-02-26T23:13:32Z

Incomplete todo list:

Specify sighash versioning process (it is currently just a rough summary).

It can always be derived, and would need to be re-derived for verification purposes anyway.

This performs various improvements to the naming of the branches of the TxID and Signature Digests, and the Authorizing Data Commitment, as initially suggested in the review of QED-it/zcash-test-vectors#24. (adapted from commit QED-it/zips@8662fd6)

Rationale: these are long enough as it is, and ZSAs are an augmentation to the existing Orchard pool, not a new pool of funds.

Signed-off-by: Daira-Emma Hopwood <daira@jacaranda.org>

clean up some formatting. Signed-off-by: Daira-Emma Hopwood <daira@jacaranda.org>

vivek-arte

One of the changes relevant for the sighash and transaction format is the move of the burn field information into the action groups.

Note that this is independent of any subsequent versioning etc for Swaps specific changes, it is natural to have the burn information a part of each Action Group.

I've made those changes as suggestions in this review, along with a few smaller suggestions.

Co-authored-by: Vivek Arte <46618816+vivek-arte@users.noreply.github.com>

…n Group

str4d · 2025-03-11T22:26:09Z

+- Sighash versions are numbered starting from 0 for each tx version.
+- v0 is by convention the "commit to everything" sighash digest. Other versions can commit to whatever makes sense for desired functionality within that tx version.
+- Have a single byte encoded alongside the signature (not appended the way transparent does) that permits the signer to specify which sighash version they are using.
+- Consensus rules choose the digest algorithm for each signer based on that byte.


We should clarify that the consensus rules choose from the available digest algorithms for the (consensus_branch_id, transaction_version) tuple under question (both of which are committed to by the transaction, and can therefore be checked non-contextually). For the NU7 consensus branch ID, there will only be one available digest version for v6 transactions (the v0 digests).

str4d · 2025-03-11T23:13:11Z

+
+- Sighash versions are numbered starting from 0 for each tx version.
+- v0 is by convention the "commit to everything" sighash digest. Other versions can commit to whatever makes sense for desired functionality within that tx version.
+- Have a single byte encoded alongside the signature (not appended the way transparent does) that permits the signer to specify which sighash version they are using.


In ZIP Sync, we discussed how this should be represented. We identified that one of the issues we have with how transparent sighash types are handled is that they are considered authorizing data (they are appended to signatures and are thus part of the signature, chosen at signing time by the signer). We decided that for sighash versioning, we'd prefer them to be effecting data. This means:

For Sapling spendAuthSig, this would be an extra byte on the Spend Description.

For Orchard spendAuthSig, this would be an extra byte on the Action Description.

For bindingSigs, we place an extra byte in the corresponding bundles.

For transparent, due to the lack of a 1:1 between inputs and signatures (as an arbitrary number of signatures can exist within a scriptSig), this would be an extra byte on the CTxIn that is used for every signature authorizing the input.

@daira doesn't think we need it at the per-input level for transparent (Ya Ain't Gonna Need It), while @str4d says this is useful for symmetry (the effecting data is then consistently at the per-input level) and that we are trying to create a design that doesn't restrict what kinds of sighash digest algorithms we might want to create in future. @nuttycom is happy to have it at the per-input level for now, and we can adjust if we discover difficulties.

Note that there is no requirement for future sighash digest algorithms to pay any attention to the sighash_type appended to each signature. It is entirely fine for us to treat that as a v0-specific behaviour (or even decide to phase it out in future transaction versions, though we are explicitly choosing to keep it for the v6 transaction's v0 digest algorithm).

I rather strongly don't want very much if any additional complexity or work associated with transparent features.

nuttycom · 2025-04-29T21:54:26Z

+| 1                           |``flagsOrchard``              |``byte``                                        |As defined in Section 7.1 of the Protocol Specification              |
+|                             |                              |                                                |[#protocol-txnencoding]_.                                            |


These should reference ZIP 225, or a more precise reference within the protocol spec, instead of section 7.1.

daira · 2025-04-29T21:55:29Z

@@ -222,86 +203,111 @@ Transaction Format



At line 191, change SpendDescriptionV6 to SpendDescriptionV5, and add an extra bullet point:

* There is no ``SpendDescriptionV6`` because the format of Sapling Spend descriptions has not changed from ``SpendDescriptionV5`` [#zip-0225]_.

nuttycom · 2025-04-29T22:02:37Z

@@ -315,31 +321,39 @@ We introduce the ``nAGExpiryHeight`` field in this transaction format in order t
 For the OrchardZSA protocol, which does not make use of an additional expiry height for transactions, we set the value of ``nAGExpiryHeight`` to be ``0`` by consensus.


We need to ensure that a conformance requirement exists within the specification that requires nAGExpiryHeight to be zero as of NU7.

However, the consistency between nAGExpiryHeight and the overall transaction expiry height should be specified here (though not in the rationale section.)

@str4d

Reviewed with @str4d, @arya, @SamHSmith Co-authored-by: Vivek Arte <46618816+vivek-arte@users.noreply.github.com>

str4d · 2025-05-13T23:10:48Z

Force-pushed to undo the render, and fix my review comments.

arya2 · 2025-05-16T02:53:23Z

  ``vSpendAuthSigsOrchard``, each have a 1:1 correspondence to the elements of
  ``vActionsOrchard`` and MUST be ordered such that the proof or signature at a given
  index corresponds to the ``OrchardZSAAction`` at the same index.
+* If thee value of ``nAGExpiryHeight`` is nonzero, it MUST be consistent with


Suggested change

* If thee value of ``nAGExpiryHeight`` is nonzero, it MUST be consistent with

* If the value of ``nAGExpiryHeight`` is nonzero, it MUST be consistent with

daira · 2025-05-20T19:27:49Z

Please also regenerate README.rst.

I don't think that the .rst generation should be a blocker for PRs merging; having CI do the publishing ensures that the zips.z.cash render is up to date, and regenerating the .rst can be done opportunistically, out-of-band. We will not expect third-party contributors to do this regeneration, in any case.

nuttycom

ACK for interim merge; there will be follow-up PRs for ZIP 246 regardless.

nuttycom · 2025-05-20T20:43:48Z

+-----------------------------+------------------------------+------------------------------------------------+---------------------------------------------------------------------+
+| 8                           |``fee``                       |``uint64``                                      |The fee to be paid by this transaction, in zatoshis.                 |
+-----------------------------+------------------------------+------------------------------------------------+---------------------------------------------------------------------+
+| 8                           |``burnAmount``                |``uint64``                                      |The value to be burned in this transaction, in zatoshis.             |


nit: Is this field name changing, or are we still calling it "burning"?

nuttycom · 2025-05-20T20:48:36Z

+| 32                          |``AssetBase``                 |``byte[32]``                                    |For the OrchardZSA protocol, this is the encoding of the Asset Base  |
+|                             |                              |                                                |:math:`\mathsf{AssetBase^{Orchard}}\!`.                              |
+-----------------------------+------------------------------+------------------------------------------------+---------------------------------------------------------------------+
+| 8                           |``valueBurn``                 |``uint64``                                      |The amount being burnt. The value is checked by consensus to be      |


Given that this is a burn, in contrast to the ZSF deposit, I think it's important to have different naming.

nuttycom · 2025-05-20T20:54:54Z

+    T.4a.i   : orchard_actions_compact_digest      (32-byte hash output)
+    T.4a.ii  : orchard_actions_noncompact_digest   (32-byte hash output)


TODO: all that we need here is the noncompact digest.

nuttycom · 2025-05-20T20:55:19Z

+   T.3b.i:  sapling_outputs_compact_digest    (32-byte hash)
+   T.3b.ii: sapling_outputs_noncompact_digest (32-byte hash)


TODO: all we need is the noncompact digest.

nuttycom · 2025-05-20T21:07:56Z

+-----------------------------+------------------------------+------------------------------------------------+---------------------------------------------------------------------+
+| 8                           |``fee``                       |``uint64``                                      |The fee to be paid by this transaction, in zatoshis.                 |
+-----------------------------+------------------------------+------------------------------------------------+---------------------------------------------------------------------+
+| 8                           |``burnAmount``                |``uint64``                                      |The value to be burned in this transaction, in zatoshis.             |


This change can be made in a future PR, to avoid foramtting issues.

The merge of zcash#987 happened to delete the table entry for the Asset Base in the Issue Note. We are adding it back here.

This PR performs the change from zcash/zips#987 to remove the asset base from the issue note description. It also makes the follow-on reorderings suggested in zcash/zips#1086 and zcash/zips#1088. The test vectors are updated in QED-it/zcash-test-vectors#36 and copied in from there. --------- Co-authored-by: Constance Beguier <constance@qed-it.com>

str4d and others added 15 commits February 26, 2025 00:46

ZIP 230: Reorganise ActionGroupDescription to group effecting data

8862ae2

ZIP 230: Constrain parser for nAGExpiryHeight and clarify 0

cdf76fb

ZIP 230: Remove AssetBase from issuance bundle encoding

80ac162

It can always be derived, and would need to be re-derived for verification purposes anyway.

ZIP 246: Initial empty ZIP structure for v6 transaction digests

c0c20fb

Updating digest names (#95)

7a112c7

This performs various improvements to the naming of the branches of the TxID and Signature Digests, and the Authorizing Data Commitment, as initially suggested in the review of QED-it/zcash-test-vectors#24. (adapted from commit QED-it/zips@8662fd6)

Move-only: Move sighash content from ZIP 226 to ZIP 246

a34a5eb

Move-only: Move sighash content from ZIP 227 to ZIP 246

5ab748a

Replace moved content in ZIPs 226 and 227 with a reference

457a04c

ZIP 246: Refer to ZIP 230 for field encodings

f44713e

ZIP 246: Fix heading levels and a bug from #975

8df0c17

ZIP 246: Remove _zsa internal suffix from digest names

dba350f

Rationale: these are long enough as it is, and ZSAs are an augmentation to the existing Orchard pool, not a new pool of funds.

Integrate ZIP 231 changes into ZIPs 230 and 246

5ec91f9

Integrate ZIPs 233 and 2002 into ZIPs 230 and 246

07fa7c3

Clear out some trailing whitespace

2220b35

ZIP 317: Fix rendering of conventional fee formula

aa7436e

str4d marked this pull request as draft February 26, 2025 23:13

str4d added 2 commits February 26, 2025 23:15

ZIP 317: Integrate fee changes from ZIP 227

39d74ed

ZIP 317: Integrate fee changes from ZIP 231

b0d8fbd

str4d force-pushed the v6-tx-format-and-sighash branch from b15642a to b0d8fbd Compare February 26, 2025 23:15

str4d mentioned this pull request Feb 26, 2025

ZIPs 226, 227, and 230: ZSA Transfer, Issuance and Burn #976

Closed

daira added 2 commits February 27, 2025 00:57

Improve formatting of ZIP 317.

edba0a0

Signed-off-by: Daira-Emma Hopwood <daira@jacaranda.org>

ZIP 230: make all the table columns the same width in the source, and

001cdd8

clean up some formatting. Signed-off-by: Daira-Emma Hopwood <daira@jacaranda.org>

vivek-arte reviewed Feb 27, 2025

View reviewed changes

Comment thread zips/zip-0227.rst Outdated

Comment thread zips/zip-0230.rst Outdated

Comment thread zips/zip-0230.rst

Comment thread zips/zip-0230.rst Outdated

Comment thread zips/zip-0246.rst Outdated

Comment thread zips/zip-0246.rst

Comment thread zips/zip-0246.rst Outdated

daira reviewed Feb 27, 2025

View reviewed changes

Comment thread zips/zip-0226.rst Outdated

Apply minor editorial suggestions

3d6f118

Co-authored-by: Vivek Arte <46618816+vivek-arte@users.noreply.github.com>

daira reviewed Feb 28, 2025

View reviewed changes

Comment thread zips/zip-0227.rst Outdated

adding the rst changes for the addition of burn fields into the Actio…

e9369af

…n Group

vivek-arte mentioned this pull request Mar 11, 2025

[ZIP 227, ZIP 230, ZIP 246] Addition of burn fields into the Action Group #991

Merged

str4d commented Mar 11, 2025

View reviewed changes

nuttycom reviewed Apr 29, 2025

View reviewed changes

daira reviewed Apr 29, 2025

View reviewed changes

nuttycom reviewed Apr 29, 2025

View reviewed changes

Comment thread zips/zip-0230.rst Outdated

nuttycom force-pushed the v6-tx-format-and-sighash branch from 2755ae9 to a5b5756 Compare April 30, 2025 00:02

nuttycom marked this pull request as ready for review April 30, 2025 00:02

vivek-arte mentioned this pull request May 5, 2025

Local reference of upstream PR#991 QED-it/zips#102

Closed

str4d commented May 6, 2025

View reviewed changes

Comment thread zips/zip-0246.rst Outdated

str4d commented May 6, 2025

View reviewed changes

Comment thread zips/zip-0246.rst Outdated

str4d commented May 6, 2025

View reviewed changes

Comment thread zips/zip-0246.rst Outdated

arya2 self-requested a review May 6, 2025 22:35

Apply suggestions from code review

2225f87

Reviewed with @str4d, @arya, @SamHSmith Co-authored-by: Vivek Arte <46618816+vivek-arte@users.noreply.github.com>

str4d force-pushed the v6-tx-format-and-sighash branch from a5b5756 to 2225f87 Compare May 13, 2025 23:10

str4d added 2 commits May 13, 2025 23:25

Merge branch 'main' into v6-tx-format-and-sighash

86ffb0f

Merge branch 'main' into v6-tx-format-and-sighash

936571a

arya2 approved these changes May 16, 2025

View reviewed changes

daira reviewed May 20, 2025

View reviewed changes

nuttycom approved these changes May 20, 2025

View reviewed changes

nuttycom reviewed May 20, 2025

View reviewed changes

nuttycom merged commit 9e647aa into main May 20, 2025
1 check passed

nuttycom deleted the v6-tx-format-and-sighash branch May 20, 2025 21:11

daira mentioned this pull request May 20, 2025

[ZIP 248] Resolve comments on from #987 #1030

Open

This was referenced Jun 3, 2025

Add zsf_deposit field to Tx V6 format (ZIP-230) pull request #745

Closed

Add zsf_deposit to transaction id and signature digest in ZIP-244 #748

Closed

vivek-arte mentioned this pull request Sep 2, 2025

Adding back the assetBase field to the IssueNote structure QED-it/zips#120

Merged

vivek-arte added a commit to QED-it/zips that referenced this pull request Sep 2, 2025

Adding back the assetBase field to the IssueNote structure (#120)

21b2673

The merge of zcash#987 happened to delete the table entry for the Asset Base in the Issue Note. We are adding it back here.

vivek-arte mentioned this pull request Sep 2, 2025

[ZIP 230] Adding back the assetBase field to the IssueNote structure #1081

Closed

vivek-arte mentioned this pull request Sep 15, 2025

Removing the Asset Base from the issue note description QED-it/librustzcash#141

Merged

		\| 1 \|``flagsOrchard`` \|``byte`` \|As defined in Section 7.1 of the Protocol Specification \|
		\| \| \| \|[#protocol-txnencoding]_. \|

		@@ -315,31 +321,39 @@ We introduce the ``nAGExpiryHeight`` field in this transaction format in order t
		For the OrchardZSA protocol, which does not make use of an additional expiry height for transactions, we set the value of ``nAGExpiryHeight`` to be ``0`` by consensus.

	* If thee value of ``nAGExpiryHeight`` is nonzero, it MUST be consistent with
	* If the value of ``nAGExpiryHeight`` is nonzero, it MUST be consistent with

		T.4a.i : orchard_actions_compact_digest (32-byte hash output)
		T.4a.ii : orchard_actions_noncompact_digest (32-byte hash output)

		T.3b.i: sapling_outputs_compact_digest (32-byte hash)
		T.3b.ii: sapling_outputs_noncompact_digest (32-byte hash)

	\| 8 \|``burnAmount`` \|``uint64`` \|The value to be burned in this transaction, in zatoshis. \|
	\| 8 \|``zip233Amount`` \|``uint64`` \|The value to be removed from circulation in this transaction, in \|
	\| \| \| \|zatoshis. \|

Conversation

str4d commented Feb 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vivek-arte left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

str4d Mar 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

daira Apr 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nuttycom Apr 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

str4d commented May 13, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nuttycom left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nuttycom May 20, 2025 • edited by daira Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

str4d commented Feb 26, 2025 •

edited

Loading

vivek-arte left a comment •

edited

Loading

str4d Mar 11, 2025 •

edited

Loading

daira Apr 29, 2025 •

edited

Loading

nuttycom Apr 29, 2025 •

edited

Loading

nuttycom May 20, 2025 •

edited by daira

Loading