2021-05-20 17:42:06 -07:00
|
|
|
//! Orchard shielded data for `V5` `Transaction`s.
|
|
|
|
|
2021-07-29 06:37:18 -07:00
|
|
|
use std::{
|
|
|
|
cmp::{Eq, PartialEq},
|
Refactor mempool spend conflict checks to increase performance (#2826)
* Add `HashSet`s to help spend conflict detection
Keep track of the spent transparent outpoints and the revealed
nullifiers.
Clippy complained that the `ActiveState` had variants with large size
differences, but that was expected, so I disabled that lint on that
`enum`.
* Clear the `HashSet`s when clearing the mempool
Clear them so that they remain consistent with the set of verified
transactions.
* Use `HashSet`s to check for spend conflicts
Store new outputs into its respective `HashSet`, and abort if a
duplicate output is found.
* Remove inserted outputs when aborting
Restore the `HashSet` to its previous state.
* Remove tracked outputs when removing a transaction
Keep the mempool storage in a consistent state when a transaction is
removed.
* Remove tracked outputs when evicting from mempool
Ensure eviction also keeps the tracked outputs consistent with the
verified transactions.
* Refactor to create a `VerifiedSet` helper type
Move the code to handle the output caches into the new type. Also move
the eviction code to make things a little simpler.
* Refactor to have a single `remove` method
Centralize the code that handles the removal of a transaction to avoid
mistakes.
* Move mempool size limiting back to `Storage`
Because the evicted transactions must be added to the rejected list.
* Remove leftover `dbg!` statement
Leftover from some temporary testing code.
Co-authored-by: teor <teor@riseup.net>
* Remove unnecessary `TODO`
It is more speculation than planning, so it doesn't add much value.
Co-authored-by: teor <teor@riseup.net>
* Fix typo in documentation
The verb should match the subject "transactions" which is plural.
Co-authored-by: teor <teor@riseup.net>
* Add a comment to warn about correctness
There's a subtle but important detail in the implementation that should
be made more visible to avoid mistakes in the future.
Co-authored-by: teor <teor@riseup.net>
* Remove outdated comment
Left-over from the attempt to move the eviction into the `VerifiedSet`.
* Improve comment explaining lint removal
Rewrite the comment explaining why the Clippy lint was ignored.
* Check for spend conflicts in `VerifiedSet`
Refactor to avoid API misuse.
* Test rejected transaction rollback
Using two transactions, perform the same test adding a conflict to both
of them to check if the second inserted transaction is properly
rejected. Then remove any conflicts from the second transaction and add
it again. That should work, because if it doesn't it means that when the
second transaction was rejected it left things it shouldn't in the
cache.
* Test removal of multiple transactions
When removing multiple transactions from the mempool storage, all of the
ones requested should be removed and any other transaction should be
still be there afterwards.
* Increase mempool size to 4, so that spend conflict tests work
If the mempool size is smaller than 4,
these tests don't fail on a trivial removal bug.
Because we need a minimum number of transactions in the mempool
to trigger the bug.
Also commit a proptest seed that fails on a trivial removal bug.
(This seed fails if we remove indexes in order,
because every index past the first removes the wrong transaction.)
* Summarise transaction data in proptest error output
* Summarise spend conflict field data in proptest error output
* Summarise multiple removal field data in proptest error output
And replace the very large proptest debug output with the new summary.
Co-authored-by: teor <teor@riseup.net>
2021-10-10 16:54:46 -07:00
|
|
|
fmt::{self, Debug},
|
2021-07-29 06:37:18 -07:00
|
|
|
io,
|
|
|
|
};
|
|
|
|
|
|
|
|
use byteorder::{ReadBytesExt, WriteBytesExt};
|
|
|
|
use halo2::pasta::pallas;
|
|
|
|
|
2021-05-20 17:42:06 -07:00
|
|
|
use crate::{
|
2021-07-28 20:49:36 -07:00
|
|
|
amount::{Amount, NegativeAllowed},
|
2021-05-20 17:42:06 -07:00
|
|
|
block::MAX_BLOCK_BYTES,
|
2021-08-16 12:16:25 -07:00
|
|
|
orchard::{tree, Action, Nullifier, ValueCommitment},
|
2021-05-20 17:42:06 -07:00
|
|
|
primitives::{
|
2021-08-16 12:16:25 -07:00
|
|
|
redpallas::{self, Binding, Signature, SpendAuth},
|
2021-05-20 17:42:06 -07:00
|
|
|
Halo2Proof,
|
|
|
|
},
|
|
|
|
serialization::{
|
|
|
|
AtLeastOne, SerializationError, TrustedPreallocate, ZcashDeserialize, ZcashSerialize,
|
|
|
|
},
|
|
|
|
};
|
|
|
|
|
|
|
|
/// A bundle of [`Action`] descriptions and signature data.
|
|
|
|
#[derive(Clone, Debug, PartialEq, Eq, Deserialize, Serialize)]
|
|
|
|
pub struct ShieldedData {
|
|
|
|
/// The orchard flags for this transaction.
|
2022-02-10 19:16:35 -08:00
|
|
|
/// Denoted as `flagsOrchard` in the spec.
|
2021-05-20 17:42:06 -07:00
|
|
|
pub flags: Flags,
|
|
|
|
/// The net value of Orchard spends minus outputs.
|
2022-02-10 19:16:35 -08:00
|
|
|
/// Denoted as `valueBalanceOrchard` in the spec.
|
2021-05-20 17:42:06 -07:00
|
|
|
pub value_balance: Amount,
|
|
|
|
/// The shared anchor for all `Spend`s in this transaction.
|
2022-02-10 19:16:35 -08:00
|
|
|
/// Denoted as `anchorOrchard` in the spec.
|
2021-05-20 17:42:06 -07:00
|
|
|
pub shared_anchor: tree::Root,
|
|
|
|
/// The aggregated zk-SNARK proof for all the actions in this transaction.
|
2022-02-10 19:16:35 -08:00
|
|
|
/// Denoted as `proofsOrchard` in the spec.
|
2021-05-20 17:42:06 -07:00
|
|
|
pub proof: Halo2Proof,
|
2021-07-29 06:37:18 -07:00
|
|
|
/// The Orchard Actions, in the order they appear in the transaction.
|
2022-02-10 19:16:35 -08:00
|
|
|
/// Denoted as `vActionsOrchard` and `vSpendAuthSigsOrchard` in the spec.
|
2021-05-20 17:42:06 -07:00
|
|
|
pub actions: AtLeastOne<AuthorizedAction>,
|
|
|
|
/// A signature on the transaction `sighash`.
|
2022-02-10 19:16:35 -08:00
|
|
|
/// Denoted as `bindingSigOrchard` in the spec.
|
2021-05-20 17:42:06 -07:00
|
|
|
pub binding_sig: Signature<Binding>,
|
|
|
|
}
|
|
|
|
|
Refactor mempool spend conflict checks to increase performance (#2826)
* Add `HashSet`s to help spend conflict detection
Keep track of the spent transparent outpoints and the revealed
nullifiers.
Clippy complained that the `ActiveState` had variants with large size
differences, but that was expected, so I disabled that lint on that
`enum`.
* Clear the `HashSet`s when clearing the mempool
Clear them so that they remain consistent with the set of verified
transactions.
* Use `HashSet`s to check for spend conflicts
Store new outputs into its respective `HashSet`, and abort if a
duplicate output is found.
* Remove inserted outputs when aborting
Restore the `HashSet` to its previous state.
* Remove tracked outputs when removing a transaction
Keep the mempool storage in a consistent state when a transaction is
removed.
* Remove tracked outputs when evicting from mempool
Ensure eviction also keeps the tracked outputs consistent with the
verified transactions.
* Refactor to create a `VerifiedSet` helper type
Move the code to handle the output caches into the new type. Also move
the eviction code to make things a little simpler.
* Refactor to have a single `remove` method
Centralize the code that handles the removal of a transaction to avoid
mistakes.
* Move mempool size limiting back to `Storage`
Because the evicted transactions must be added to the rejected list.
* Remove leftover `dbg!` statement
Leftover from some temporary testing code.
Co-authored-by: teor <teor@riseup.net>
* Remove unnecessary `TODO`
It is more speculation than planning, so it doesn't add much value.
Co-authored-by: teor <teor@riseup.net>
* Fix typo in documentation
The verb should match the subject "transactions" which is plural.
Co-authored-by: teor <teor@riseup.net>
* Add a comment to warn about correctness
There's a subtle but important detail in the implementation that should
be made more visible to avoid mistakes in the future.
Co-authored-by: teor <teor@riseup.net>
* Remove outdated comment
Left-over from the attempt to move the eviction into the `VerifiedSet`.
* Improve comment explaining lint removal
Rewrite the comment explaining why the Clippy lint was ignored.
* Check for spend conflicts in `VerifiedSet`
Refactor to avoid API misuse.
* Test rejected transaction rollback
Using two transactions, perform the same test adding a conflict to both
of them to check if the second inserted transaction is properly
rejected. Then remove any conflicts from the second transaction and add
it again. That should work, because if it doesn't it means that when the
second transaction was rejected it left things it shouldn't in the
cache.
* Test removal of multiple transactions
When removing multiple transactions from the mempool storage, all of the
ones requested should be removed and any other transaction should be
still be there afterwards.
* Increase mempool size to 4, so that spend conflict tests work
If the mempool size is smaller than 4,
these tests don't fail on a trivial removal bug.
Because we need a minimum number of transactions in the mempool
to trigger the bug.
Also commit a proptest seed that fails on a trivial removal bug.
(This seed fails if we remove indexes in order,
because every index past the first removes the wrong transaction.)
* Summarise transaction data in proptest error output
* Summarise spend conflict field data in proptest error output
* Summarise multiple removal field data in proptest error output
And replace the very large proptest debug output with the new summary.
Co-authored-by: teor <teor@riseup.net>
2021-10-10 16:54:46 -07:00
|
|
|
impl fmt::Display for ShieldedData {
|
|
|
|
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
|
|
|
|
let mut fmter = f.debug_struct("orchard::ShieldedData");
|
|
|
|
|
|
|
|
fmter.field("actions", &self.actions.len());
|
|
|
|
fmter.field("value_balance", &self.value_balance);
|
|
|
|
fmter.field("flags", &self.flags);
|
|
|
|
|
|
|
|
fmter.field("proof_len", &self.proof.zcash_serialized_size());
|
|
|
|
|
|
|
|
fmter.field("shared_anchor", &self.shared_anchor);
|
|
|
|
|
|
|
|
fmter.finish()
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2021-05-25 19:02:42 -07:00
|
|
|
impl ShieldedData {
|
2021-07-29 06:37:18 -07:00
|
|
|
/// Iterate over the [`Action`]s for the [`AuthorizedAction`]s in this
|
|
|
|
/// transaction, in the order they appear in it.
|
2021-05-25 19:02:42 -07:00
|
|
|
pub fn actions(&self) -> impl Iterator<Item = &Action> {
|
|
|
|
self.actions.actions()
|
|
|
|
}
|
|
|
|
|
2021-05-27 08:06:08 -07:00
|
|
|
/// Collect the [`Nullifier`]s for this transaction.
|
2021-05-25 19:02:42 -07:00
|
|
|
pub fn nullifiers(&self) -> impl Iterator<Item = &Nullifier> {
|
|
|
|
self.actions().map(|action| &action.nullifier)
|
|
|
|
}
|
2021-07-28 20:49:36 -07:00
|
|
|
|
2021-08-16 12:16:25 -07:00
|
|
|
/// Calculate the Action binding verification key.
|
|
|
|
///
|
|
|
|
/// Getting the binding signature validating key from the Action description
|
|
|
|
/// value commitments and the balancing value implicitly checks that the
|
|
|
|
/// balancing value is consistent with the value transferred in the
|
|
|
|
/// Action descriptions, but also proves that the signer knew the
|
|
|
|
/// randomness used for the Action value commitments, which
|
|
|
|
/// prevents replays of Action descriptions that perform an output.
|
|
|
|
/// In Orchard, all Action descriptions have a spend authorization signature,
|
|
|
|
/// therefore the proof of knowledge of the value commitment randomness
|
|
|
|
/// is less important, but stills provides defense in depth, and reduces the
|
|
|
|
/// differences between Orchard and Sapling.
|
|
|
|
///
|
|
|
|
/// The net value of Orchard spends minus outputs in a transaction
|
|
|
|
/// is called the balancing value, measured in zatoshi as a signed integer
|
|
|
|
/// cv_balance.
|
|
|
|
///
|
|
|
|
/// Consistency of cv_balance with the value commitments in Action
|
|
|
|
/// descriptions is enforced by the binding signature.
|
|
|
|
///
|
|
|
|
/// Instead of generating a key pair at random, we generate it as a function
|
|
|
|
/// of the value commitments in the Action descriptions of the transaction, and
|
|
|
|
/// the balancing value.
|
|
|
|
///
|
2022-05-30 13:12:11 -07:00
|
|
|
/// <https://zips.z.cash/protocol/protocol.pdf#orchardbalance>
|
2021-08-16 12:16:25 -07:00
|
|
|
pub fn binding_verification_key(&self) -> redpallas::VerificationKeyBytes<Binding> {
|
|
|
|
let cv: ValueCommitment = self.actions().map(|action| action.cv).sum();
|
|
|
|
let cv_balance: ValueCommitment =
|
|
|
|
ValueCommitment::new(pallas::Scalar::zero(), self.value_balance);
|
|
|
|
|
|
|
|
let key_bytes: [u8; 32] = (cv - cv_balance).into();
|
|
|
|
key_bytes.into()
|
|
|
|
}
|
|
|
|
|
2021-07-28 20:49:36 -07:00
|
|
|
/// Provide access to the `value_balance` field of the shielded data.
|
|
|
|
///
|
|
|
|
/// Needed to calculate the sapling value balance.
|
|
|
|
pub fn value_balance(&self) -> Amount<NegativeAllowed> {
|
|
|
|
self.value_balance
|
|
|
|
}
|
2021-07-29 06:37:18 -07:00
|
|
|
|
|
|
|
/// Collect the cm_x's for this transaction, if it contains [`Action`]s with
|
|
|
|
/// outputs, in the order they appear in the transaction.
|
|
|
|
pub fn note_commitments(&self) -> impl Iterator<Item = &pallas::Base> {
|
|
|
|
self.actions().map(|action| &action.cm_x)
|
|
|
|
}
|
2021-05-25 19:02:42 -07:00
|
|
|
}
|
|
|
|
|
|
|
|
impl AtLeastOne<AuthorizedAction> {
|
|
|
|
/// Iterate over the [`Action`]s of each [`AuthorizedAction`].
|
|
|
|
pub fn actions(&self) -> impl Iterator<Item = &Action> {
|
|
|
|
self.iter()
|
|
|
|
.map(|authorized_action| &authorized_action.action)
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2021-05-20 17:42:06 -07:00
|
|
|
/// An authorized action description.
|
|
|
|
///
|
|
|
|
/// Every authorized Orchard `Action` must have a corresponding `SpendAuth` signature.
|
|
|
|
#[derive(Clone, Debug, PartialEq, Eq, Deserialize, Serialize)]
|
|
|
|
pub struct AuthorizedAction {
|
|
|
|
/// The action description of this Action.
|
|
|
|
pub action: Action,
|
|
|
|
/// The spend signature.
|
|
|
|
pub spend_auth_sig: Signature<SpendAuth>,
|
|
|
|
}
|
|
|
|
|
|
|
|
impl AuthorizedAction {
|
|
|
|
/// Split out the action and the signature for V5 transaction
|
|
|
|
/// serialization.
|
|
|
|
pub fn into_parts(self) -> (Action, Signature<SpendAuth>) {
|
|
|
|
(self.action, self.spend_auth_sig)
|
|
|
|
}
|
|
|
|
|
|
|
|
// Combine the action and the spend auth sig from V5 transaction
|
|
|
|
/// deserialization.
|
|
|
|
pub fn from_parts(action: Action, spend_auth_sig: Signature<SpendAuth>) -> AuthorizedAction {
|
|
|
|
AuthorizedAction {
|
|
|
|
action,
|
|
|
|
spend_auth_sig,
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
/// The size of a single Action
|
|
|
|
///
|
|
|
|
/// Actions are 5 * 32 + 580 + 80 bytes so the total size of each Action is 820 bytes.
|
|
|
|
/// [7.5 Action Description Encoding and Consensus][ps]
|
|
|
|
///
|
2022-06-02 08:07:35 -07:00
|
|
|
/// [ps]: <https://zips.z.cash/protocol/nu5.pdf#actionencodingandconsensus>
|
2021-05-20 17:42:06 -07:00
|
|
|
pub const ACTION_SIZE: u64 = 5 * 32 + 580 + 80;
|
|
|
|
|
|
|
|
/// The size of a single Signature<SpendAuth>
|
|
|
|
///
|
|
|
|
/// Each Signature is 64 bytes.
|
|
|
|
/// [7.1 Transaction Encoding and Consensus][ps]
|
|
|
|
///
|
2022-06-02 08:07:35 -07:00
|
|
|
/// [ps]: <https://zips.z.cash/protocol/nu5.pdf#actionencodingandconsensus>
|
2021-05-20 17:42:06 -07:00
|
|
|
pub const SPEND_AUTH_SIG_SIZE: u64 = 64;
|
|
|
|
|
|
|
|
/// The size of a single AuthorizedAction
|
|
|
|
///
|
|
|
|
/// Each serialized `Action` has a corresponding `Signature<SpendAuth>`.
|
|
|
|
pub const AUTHORIZED_ACTION_SIZE: u64 = ACTION_SIZE + SPEND_AUTH_SIG_SIZE;
|
|
|
|
|
|
|
|
/// The maximum number of orchard actions in a valid Zcash on-chain transaction V5.
|
|
|
|
///
|
|
|
|
/// If a transaction contains more actions than can fit in maximally large block, it might be
|
|
|
|
/// valid on the network and in the mempool, but it can never be mined into a block. So
|
|
|
|
/// rejecting these large edge-case transactions can never break consensus.
|
|
|
|
impl TrustedPreallocate for Action {
|
|
|
|
fn max_allocation() -> u64 {
|
|
|
|
// Since a serialized Vec<AuthorizedAction> uses at least one byte for its length,
|
|
|
|
// and the signature is required,
|
|
|
|
// a valid max allocation can never exceed this size
|
2021-11-18 10:06:07 -08:00
|
|
|
const MAX: u64 = (MAX_BLOCK_BYTES - 1) / AUTHORIZED_ACTION_SIZE;
|
2022-02-08 12:28:40 -08:00
|
|
|
// # Consensus
|
|
|
|
//
|
2021-11-18 10:06:07 -08:00
|
|
|
// > [NU5 onward] nSpendsSapling, nOutputsSapling, and nActionsOrchard MUST all be less than 2^16.
|
2022-02-08 12:28:40 -08:00
|
|
|
//
|
|
|
|
// https://zips.z.cash/protocol/protocol.pdf#txnconsensus
|
|
|
|
//
|
2021-11-18 10:06:07 -08:00
|
|
|
// This acts as nActionsOrchard and is therefore subject to the rule.
|
|
|
|
// The maximum value is actually smaller due to the block size limit,
|
|
|
|
// but we ensure the 2^16 limit with a static assertion.
|
|
|
|
static_assertions::const_assert!(MAX < (1 << 16));
|
|
|
|
MAX
|
2021-05-20 17:42:06 -07:00
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
impl TrustedPreallocate for Signature<SpendAuth> {
|
|
|
|
fn max_allocation() -> u64 {
|
|
|
|
// Each signature must have a corresponding action.
|
|
|
|
Action::max_allocation()
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
bitflags! {
|
|
|
|
/// Per-Transaction flags for Orchard.
|
|
|
|
///
|
|
|
|
/// The spend and output flags are passed to the `Halo2Proof` verifier, which verifies
|
|
|
|
/// the relevant note spending and creation consensus rules.
|
2021-06-14 17:04:18 -07:00
|
|
|
///
|
2022-02-08 12:28:40 -08:00
|
|
|
/// # Consensus
|
|
|
|
///
|
|
|
|
/// > [NU5 onward] In a version 5 transaction, the reserved bits 2..7 of the flagsOrchard
|
|
|
|
/// > field MUST be zero.
|
|
|
|
///
|
|
|
|
/// <https://zips.z.cash/protocol/protocol.pdf#txnconsensus>
|
2021-06-14 17:04:18 -07:00
|
|
|
///
|
|
|
|
/// ([`bitflags`](https://docs.rs/bitflags/1.2.1/bitflags/index.html) restricts its values to the
|
|
|
|
/// set of valid flags)
|
2021-05-20 17:42:06 -07:00
|
|
|
#[derive(Deserialize, Serialize)]
|
|
|
|
pub struct Flags: u8 {
|
|
|
|
/// Enable spending non-zero valued Orchard notes.
|
|
|
|
///
|
|
|
|
/// "the `enableSpendsOrchard` flag, if present, MUST be 0 for coinbase transactions"
|
|
|
|
const ENABLE_SPENDS = 0b00000001;
|
|
|
|
/// Enable creating new non-zero valued Orchard notes.
|
|
|
|
const ENABLE_OUTPUTS = 0b00000010;
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
impl ZcashSerialize for Flags {
|
|
|
|
fn zcash_serialize<W: io::Write>(&self, mut writer: W) -> Result<(), io::Error> {
|
|
|
|
writer.write_u8(self.bits())?;
|
|
|
|
|
|
|
|
Ok(())
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
impl ZcashDeserialize for Flags {
|
|
|
|
fn zcash_deserialize<R: io::Read>(mut reader: R) -> Result<Self, SerializationError> {
|
2021-06-14 17:04:18 -07:00
|
|
|
// Consensus rule: "In a version 5 transaction,
|
|
|
|
// the reserved bits 2..7 of the flagsOrchard field MUST be zero."
|
|
|
|
// https://zips.z.cash/protocol/protocol.pdf#txnencodingandconsensus
|
2022-10-14 01:53:40 -07:00
|
|
|
//
|
|
|
|
// Clippy 1.64 is wrong here, this lazy evaluation is necessary, constructors are functions. This is fixed in 1.66.
|
|
|
|
#[allow(clippy::unnecessary_lazy_evaluations)]
|
2021-06-14 17:04:18 -07:00
|
|
|
Flags::from_bits(reader.read_u8()?)
|
2022-10-14 01:53:40 -07:00
|
|
|
.ok_or_else(|| SerializationError::Parse("invalid reserved orchard flags"))
|
2021-05-20 17:42:06 -07:00
|
|
|
}
|
|
|
|
}
|