Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 9 additions & 2 deletions packages/rs-dpp/src/shielded/builder/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,10 @@ mod token_shielded_transfer;
mod token_unshield;
mod unshield;

pub use self::shield::build_shield_transition;
pub use self::shield::{
build_shield_transition, build_shield_transition_from_proved_bundle, prove_shield_bundle,
ProvedShieldBundle,
};
pub use document_token_payment::build_document_shielded_token_payment;
pub use identity_create_from_shielded_pool::{
build_identity_create_from_shielded_pool_transition, IdentityCreateFromShieldedPoolBuildResult,
Expand All @@ -56,7 +59,11 @@ pub use identity_top_up_from_shielded_pool::build_identity_top_up_from_shielded_
pub use shield_from_asset_lock::build_shield_from_asset_lock_transition;
#[cfg(feature = "core_key_wallet")]
pub use shield_from_asset_lock::build_shield_from_asset_lock_transition_with_signer;
pub use shield_from_identity::build_shield_from_identity_transition;
pub use shield_from_identity::{
build_shield_from_identity_transition,
build_shield_from_identity_transition_from_proved_bundle, prove_shield_from_identity_bundle,
ProvedShieldFromIdentityBundle,
};
pub use shielded_transfer::build_shielded_transfer_transition;
pub use shielded_withdrawal::build_shielded_withdrawal_transition;
pub use token_burn_from_pool::build_token_burn_from_pool_transition;
Expand Down
237 changes: 218 additions & 19 deletions packages/rs-dpp/src/shielded/builder/shield.rs
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
use std::collections::BTreeMap;
use std::collections::{BTreeMap, BTreeSet};

use crate::address_funds::AddressFundsFeeStrategy;
use crate::address_funds::{OrchardAddress, PlatformAddress};
Expand All @@ -12,12 +12,132 @@ use crate::state_transition::StateTransition;
use crate::ProtocolError;
use platform_version::version::PlatformVersion;

use super::{build_output_only_bundle, serialize_authorized_bundle, OrchardProver};
use super::{
build_output_only_bundle, serialize_authorized_bundle, OrchardProver, SerializedBundle,
};

/// A Shield bundle that has been proved and bound to its funding addresses, but not yet wrapped
/// in a signed transition. Produced by [`prove_shield_bundle`], consumed by
/// [`build_shield_transition_from_proved_bundle`].
pub struct ProvedShieldBundle {
bundle: SerializedBundle,
/// The funding binding the bundle's sighash committed to (see
/// [`shield_extra_sighash_data`]); empty at protocol versions that bind nothing.
extra_sighash_data: Vec<u8>,
}

impl ProvedShieldBundle {
/// Whether this bundle binds exactly what consensus will re-derive for `inputs` at
/// `platform_version` — the same funding addresses under the same binding rules. A bundle
/// proved at a protocol version with a different binding (e.g. across the activation of
/// `credit_pool_bundle_binding`) must be proved again.
pub fn is_bound_for(
&self,
inputs: &BTreeMap<PlatformAddress, (AddressNonce, Credits)>,
platform_version: &PlatformVersion,
) -> Result<bool, ProtocolError> {
Ok(shield_extra_sighash_data(inputs, platform_version)? == self.extra_sighash_data)
}
}

/// Proves the output-only Orchard bundle of a Shield transition.
///
/// This is the CPU-heavy half of [`build_shield_transition`] (Halo 2 proof generation, seconds of
/// work) and does no I/O and no signing, so it can run on a blocking thread while the caller
/// fetches the input nonces.
///
/// The bundle's binding signature commits to the funding addresses — the SET of input addresses,
/// via [`shield_extra_sighash_data`] — and never to their nonces or contributed amounts. The
/// nonces and amounts are committed later by the input witnesses, which sign the whole
/// transition in [`build_shield_transition_from_proved_bundle`].
pub fn prove_shield_bundle<P: OrchardProver>(
recipient: &OrchardAddress,
shield_amount: u64,
input_addresses: BTreeSet<PlatformAddress>,
prover: &P,
memo: [u8; 36],
sender_ovk: Option<grovedb_commitment_tree::OutgoingViewingKey>,
platform_version: &PlatformVersion,
) -> Result<ProvedShieldBundle, ProtocolError> {
// `shield_extra_sighash_data` digests only the map's keys (in key order); the nonce and
// amount values are deliberately not part of the binding, so placeholders bind exactly the
// bytes the real inputs map binds (pinned by
// `test_proved_bundle_binding_ignores_nonces_and_amounts`).
let binding_inputs: BTreeMap<PlatformAddress, (AddressNonce, Credits)> = input_addresses
.iter()
.map(|address| (*address, (0, 0)))
.collect();
// Bound to the funding addresses, so nobody else can re-wrap the proved bundle; empty at
// protocol versions whose verifier predates the binding.
let extra_sighash_data = shield_extra_sighash_data(&binding_inputs, platform_version)?;

// Shield (Type 15) never pads with anonymity-set fillers — only the
// Type 18 ShieldFromAssetLock pool-seeding path does (`dummy_outputs`).
let bundle = build_output_only_bundle(
recipient,
shield_amount,
memo,
sender_ovk,
0,
&extra_sighash_data,
prover,
)?;
Ok(ProvedShieldBundle {
bundle: serialize_authorized_bundle(&bundle),
extra_sighash_data,
})
}

/// Wraps a [`ProvedShieldBundle`] into a signed Shield state transition: attaches the inputs with
/// their nonces and amounts and signs every input witness over the transition's signable bytes.
///
/// The binding consensus will re-derive from `inputs` at `platform_version` must equal the one
/// the bundle was proved with (see [`ProvedShieldBundle::is_bound_for`]); otherwise this errors
/// instead of producing a transition consensus would reject.
pub async fn build_shield_transition_from_proved_bundle<S: Signer<PlatformAddress>>(
proved: ProvedShieldBundle,
inputs: BTreeMap<PlatformAddress, (AddressNonce, Credits)>,
fee_strategy: AddressFundsFeeStrategy,
signer: &S,
user_fee_increase: UserFeeIncrease,
platform_version: &PlatformVersion,
) -> Result<StateTransition, ProtocolError> {
if fee_strategy.is_empty() {
return Err(ProtocolError::ShieldedBuildError(
"fee_strategy must have at least one step".to_string(),
));
}
if !proved.is_bound_for(&inputs, platform_version)? {
return Err(ProtocolError::ShieldedBuildError(
"shield inputs do not match the binding the bundle was proved with (different \
funding addresses or protocol version)"
.to_string(),
));
}
let sb = proved.bundle;

ShieldTransition::try_from_bundle_with_signer(
inputs,
sb.actions,
sb.value_balance.unsigned_abs(),
sb.anchor,
sb.proof,
sb.binding_signature,
fee_strategy,
signer,
user_fee_increase,
platform_version,
)
.await
}

/// Builds a Shield state transition (transparent platform addresses -> shielded pool).
///
/// Constructs an output-only Orchard bundle (no spends), proves it, signs the
/// transparent input witnesses, and returns a ready-to-broadcast `StateTransition`.
/// Equivalent to [`prove_shield_bundle`] followed by
/// [`build_shield_transition_from_proved_bundle`]; use those two directly to prove while the
/// input nonces are still being fetched.
///
/// # Parameters
/// - `recipient` - Orchard address to receive the shielded note
Expand Down Expand Up @@ -47,36 +167,26 @@ pub async fn build_shield_transition<S: Signer<PlatformAddress>, P: OrchardProve
sender_ovk: Option<grovedb_commitment_tree::OutgoingViewingKey>,
platform_version: &PlatformVersion,
) -> Result<StateTransition, ProtocolError> {
// Checked before proving so a malformed request fails without paying for the proof.
if fee_strategy.is_empty() {
return Err(ProtocolError::ShieldedBuildError(
"fee_strategy must have at least one step".to_string(),
));
}

// Bound to the funding addresses, so nobody else can re-wrap the proved bundle; empty at
// protocol versions whose verifier predates the binding.
let extra_sighash_data = shield_extra_sighash_data(&inputs, platform_version)?;

// Shield (Type 15) never pads with anonymity-set fillers — only the
// Type 18 ShieldFromAssetLock pool-seeding path does (`dummy_outputs`).
let bundle = build_output_only_bundle(
let proved = prove_shield_bundle(
recipient,
shield_amount,
inputs.keys().copied().collect(),
prover,
memo,
sender_ovk,
0,
&extra_sighash_data,
prover,
platform_version,
)?;
let sb = serialize_authorized_bundle(&bundle);

ShieldTransition::try_from_bundle_with_signer(
build_shield_transition_from_proved_bundle(
proved,
inputs,
sb.actions,
sb.value_balance.unsigned_abs(),
sb.anchor,
sb.proof,
sb.binding_signature,
fee_strategy,
signer,
user_fee_increase,
Expand Down Expand Up @@ -287,4 +397,93 @@ mod tests {
result.err()
);
}

#[test]
fn test_proved_bundle_binding_ignores_nonces_and_amounts() {
// `prove_shield_bundle` binds placeholder nonces/amounts; that is only sound because the
// Shield binding digests the input address set alone. Pin it at every version that binds.
let mut real = BTreeMap::new();
real.insert(PlatformAddress::P2pkh([1u8; 20]), (17u32, 100_000u64));
real.insert(PlatformAddress::P2sh([2u8; 20]), (u32::MAX, 1u64));
let placeholders: BTreeMap<PlatformAddress, (AddressNonce, Credits)> =
real.keys().map(|address| (*address, (0, 0))).collect();
for platform_version in [PlatformVersion::first(), PlatformVersion::latest()] {
assert_eq!(
shield_extra_sighash_data(&real, platform_version).unwrap(),
shield_extra_sighash_data(&placeholders, platform_version).unwrap(),
);
}
// And at the latest version the binding is not vacuous: it depends on the address set.
let latest = PlatformVersion::latest();
assert!(!shield_extra_sighash_data(&real, latest).unwrap().is_empty());
let mut other = real.clone();
other.insert(PlatformAddress::P2pkh([3u8; 20]), (0, 0));
assert_ne!(
shield_extra_sighash_data(&real, latest).unwrap(),
shield_extra_sighash_data(&other, latest).unwrap(),
);
}

#[tokio::test]
async fn test_proved_bundle_split_path_and_binding_mismatch() {
let recipient = test_orchard_address();
let latest = PlatformVersion::latest();
let a = PlatformAddress::P2pkh([1u8; 20]);
let b = PlatformAddress::P2pkh([2u8; 20]);
let fee_strategy = vec![AddressFundsFeeStrategyStep::DeductFromInput(0)];
let inputs_for = |addrs: &[PlatformAddress]| -> BTreeMap<_, _> {
addrs
.iter()
.map(|addr| (*addr, (7u32, 100_000u64)))
.collect()
};
let prove = |platform_version| {
prove_shield_bundle(
&recipient,
50_000,
[a].into_iter().collect(),
&TestProver,
[0u8; 36],
None,
platform_version,
)
.expect("prove")
};

// Proved for {a} at the latest version: bound for exactly those inputs at that version.
let proved = prove(latest);
assert!(proved.is_bound_for(&inputs_for(&[a]), latest).unwrap());
assert!(!proved.is_bound_for(&inputs_for(&[a, b]), latest).unwrap());
assert!(!proved.is_bound_for(&inputs_for(&[b]), latest).unwrap());
// A version whose binding rules differ (the first version binds nothing) must re-prove.
assert!(!proved
.is_bound_for(&inputs_for(&[a]), PlatformVersion::first())
.unwrap());

// Wrapping it around other inputs is refused rather than built.
let err = build_shield_transition_from_proved_bundle(
proved,
inputs_for(&[a, b]),
fee_strategy.clone(),
&DummySigner,
0,
latest,
)
.await
.expect_err("mismatched inputs must be rejected");
assert!(err.to_string().contains("do not match"), "{err}");

// Prove first, attach nonces afterwards (the wallet's overlap path).
let st = build_shield_transition_from_proved_bundle(
prove(latest),
inputs_for(&[a]),
fee_strategy,
&DummySigner,
0,
latest,
)
.await
.expect("assemble");
assert!(matches!(st, StateTransition::Shield(_)));
}
}
Loading
Loading