Skip to content
Merged
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
113 changes: 111 additions & 2 deletions packages/rs-dpp/src/shielded/memo.rs
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
//! * bytes `[4..36]` β€” a 32-byte payload whose meaning depends on
//! `kind`.
//!
//! Two kinds are defined today; unknown kinds round-trip verbatim as
//! Three kinds are defined today; unknown kinds round-trip verbatim as
//! [`ShieldedMemo::Other`] so a future writer's memo is never
//! corrupted by an older reader.

Expand All @@ -28,6 +28,8 @@ pub const MEMO_PAYLOAD_SIZE: usize = MEMO_SIZE - 4;
const KIND_EMPTY: u32 = 0;
/// `kind` tag for a UTF-8 text memo (zero-padded payload).
const KIND_TEXT: u32 = 1;
/// `kind` tag for a payment reference (zero-padded payload).
const KIND_PAYMENT_REF: u32 = 2;

/// A decoded shielded note memo.
///
Expand All @@ -42,6 +44,13 @@ pub enum ShieldedMemo {
Empty,
/// A UTF-8 text memo whose byte length is at most [`MEMO_PAYLOAD_SIZE`].
Text(String),
/// A payment reference: what the payment is for, in a value the payee chose and
/// gave to the payer, such as an invoice or order number, padded on the right with
/// zero bytes. The payee matches all 32 bytes against its own records.
///
/// It never says who paid. Anyone who has seen a reference can attach it to a
/// payment, so the payee checks the amount it received against the request.
PaymentRef([u8; MEMO_PAYLOAD_SIZE]),
Comment on lines +47 to +53

@thepastaclaw thepastaclaw Nov 12, 2026 •

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

βœ… Resolved at 83901e22; see the replies below.

🟑 Suggestion: Document the enum additions as Rust source-compatibility changes

Both ShieldedMemo and platform_encryption::CryptoError are publicly exported enums without #[non_exhaustive]. Adding PaymentRef and the two error variants makes downstream exhaustive matches fail to compile when consumers update, even though existing workspace consumers still compile and the memo wire encoding remains compatible. Replace the PR's Breaking Changes claim of "None" with a migration note explaining that exhaustive matches need new arms or a fallback. Keep the ordinary feat: title: the book's "Commits, pull requests, and what to run before pushing" section reserves ! for consensus-breaking changes, which this is not.

source: gpt-6.1-sol (phase2-reviewer: general, architecture-layering, platform-versioning, rust-quality, security-auditor)

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in the description: Breaking Changes now says there is no consensus change (the title stays feat:) and gives the migration note, that ShieldedMemo and CryptoError gain variants and code matching either exhaustively needs a new arm or a fallback.

πŸ€– Addressed by Claude Code

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Resolved (re-reviewed at 83901e22): Your current Breaking Changes section explicitly documents the added ShieldedMemo and CryptoError variants and the exhaustive-match migration, while retaining the ordinary feat title and unchanged memo-wire compatibility.

/// Any memo whose `kind` this version does not interpret (or a
/// structurally-invalid known kind). Retained verbatim so it
/// round-trips unchanged.
Expand All @@ -67,6 +76,38 @@ impl ShieldedMemo {
Ok(ShieldedMemo::Text(s))
}

/// Build a payment reference memo from the reference the payee supplied, of 1 to
/// [`MEMO_PAYLOAD_SIZE`] bytes, padded on the right with zero bytes. A payee whose
/// own identifier is longer issues a 32-byte hash of it.
///
/// An empty or all-zero reference is refused: 32 zero bytes are no reference.
pub fn payment_ref(reference: &[u8]) -> Result<Self, ProtocolError> {
if reference.len() > MEMO_PAYLOAD_SIZE {
return Err(ProtocolError::Generic(format!(
"shielded payment reference is {} bytes, exceeds the {MEMO_PAYLOAD_SIZE}-byte limit",
reference.len()
)));
}
if reference.iter().all(|&byte| byte == 0) {
return Err(ProtocolError::Generic(
"shielded payment reference is empty or all zero bytes".to_string(),
));
}
let mut payload = [0u8; MEMO_PAYLOAD_SIZE];
payload[..reference.len()].copy_from_slice(reference);
Ok(ShieldedMemo::PaymentRef(payload))
}

/// A payment reference as text, when it is valid UTF-8 once its zero padding is
/// removed. `None` for a reference that is not, a hash for example: a caller that
/// shows such a reference renders its 32 bytes in hexadecimal.
pub fn payment_ref_text(reference: &[u8; MEMO_PAYLOAD_SIZE]) -> Option<&str> {
let end = reference.iter().rposition(|&b| b != 0).map_or(0, |i| i + 1);
std::str::from_utf8(&reference[..end])
.ok()
.filter(|text| !text.is_empty())
}

/// Encode to the on-chain 36-byte memo layout.
pub fn to_bytes(&self) -> [u8; MEMO_SIZE] {
let mut out = [0u8; MEMO_SIZE];
Expand All @@ -82,6 +123,7 @@ impl ShieldedMemo {
payload[..n].copy_from_slice(&bytes[..n]);
(KIND_TEXT, payload)
}
ShieldedMemo::PaymentRef(reference) => (KIND_PAYMENT_REF, *reference),
ShieldedMemo::Other { kind, payload } => (*kind, *payload),
};
out[0..4].copy_from_slice(&kind.to_le_bytes());
Expand All @@ -92,7 +134,8 @@ impl ShieldedMemo {
/// Decode from the on-chain 36-byte memo layout.
///
/// Decoding is total: a `KIND_TEXT` memo whose payload is not valid
/// UTF-8, or a `KIND_EMPTY` memo with a non-zero payload, falls back
/// UTF-8, a `KIND_EMPTY` memo with a non-zero payload, or a
/// `KIND_PAYMENT_REF` memo with an all-zero payload falls back
/// to [`Self::Other`] so the raw bytes are preserved rather than lost.
pub fn from_bytes(bytes: &[u8; MEMO_SIZE]) -> Self {
let kind = u32::from_le_bytes([bytes[0], bytes[1], bytes[2], bytes[3]]);
Expand All @@ -117,6 +160,10 @@ impl ShieldedMemo {
Err(_) => ShieldedMemo::Other { kind, payload },
}
}
// 32 zero bytes are no reference, so that memo is not read as one.
KIND_PAYMENT_REF if payload != [0u8; MEMO_PAYLOAD_SIZE] => {
ShieldedMemo::PaymentRef(payload)
}
_ => ShieldedMemo::Other { kind, payload },
}
}
Expand Down Expand Up @@ -199,6 +246,68 @@ mod tests {
);
}

#[test]
fn should_encode_a_payment_reference_padded_to_32_bytes() {
// The vector of the DashPay shielded payment addresses DIP.
let memo = ShieldedMemo::payment_ref(b"INV-2026-0042").expect("a 13-byte reference");
let bytes = memo.to_bytes();
let mut expected = [0u8; MEMO_SIZE];
expected[0] = 2;
expected[4..17].copy_from_slice(b"INV-2026-0042");
assert_eq!(bytes, expected);
assert_eq!(ShieldedMemo::from_bytes(&bytes), memo);

let ShieldedMemo::PaymentRef(reference) = memo else {
panic!("expected a payment reference");
};
assert_eq!(
ShieldedMemo::payment_ref_text(&reference),
Some("INV-2026-0042")
);
}

#[test]
fn should_round_trip_a_32_byte_payment_reference_that_is_not_text() {
// A hash: every byte used, not UTF-8, ending in a zero byte that is part of it.
let mut reference = [0xF5u8; MEMO_PAYLOAD_SIZE];
reference[31] = 0;
let memo = ShieldedMemo::payment_ref(&reference).expect("a 32-byte reference");
assert_eq!(memo, ShieldedMemo::PaymentRef(reference));
assert_eq!(ShieldedMemo::from_bytes(&memo.to_bytes()), memo);
assert_eq!(ShieldedMemo::payment_ref_text(&reference), None);
}

#[test]
fn should_read_references_that_differ_only_in_trailing_zero_bytes_as_one() {
assert_eq!(
ShieldedMemo::payment_ref(&[1]).expect("a reference"),
ShieldedMemo::payment_ref(&[1, 0]).expect("a reference")
);
}

#[test]
fn should_refuse_a_payment_reference_that_is_empty_all_zero_or_too_long() {
assert!(ShieldedMemo::payment_ref(&[]).is_err());
assert!(ShieldedMemo::payment_ref(&[0; 5]).is_err());
assert!(ShieldedMemo::payment_ref(&[0; MEMO_PAYLOAD_SIZE]).is_err());
assert!(ShieldedMemo::payment_ref(&[1; MEMO_PAYLOAD_SIZE + 1]).is_err());
}

#[test]
fn should_not_read_an_all_zero_payload_as_a_payment_reference() {
let mut bytes = [0u8; MEMO_SIZE];
bytes[0..4].copy_from_slice(&KIND_PAYMENT_REF.to_le_bytes());
assert_eq!(
ShieldedMemo::from_bytes(&bytes),
ShieldedMemo::Other {
kind: KIND_PAYMENT_REF,
payload: [0u8; MEMO_PAYLOAD_SIZE],
}
);
// The bytes survive the round trip.
assert_eq!(ShieldedMemo::from_bytes(&bytes).to_bytes(), bytes);
}

#[test]
fn unknown_kind_round_trips() {
let payload = [7u8; MEMO_PAYLOAD_SIZE];
Expand Down
6 changes: 6 additions & 0 deletions packages/rs-platform-encryption/src/error.rs
Original file line number Diff line number Diff line change
Expand Up @@ -14,4 +14,10 @@ pub enum CryptoError {

#[error("Invalid compact xpub length (DIP-15 requires exactly 69 bytes, got {0})")]
InvalidCompactXpubLength(usize),

#[error("Invalid encrypted shielded address length (expected 64 bytes, got {0})")]
InvalidEncryptedShieldedAddressLength(usize),

#[error("Invalid shielded address length (expected 43 bytes, got {0})")]
InvalidShieldedAddressLength(usize),
}
7 changes: 7 additions & 0 deletions packages/rs-platform-encryption/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@
//! - [`contact_info`] β€” `contactInfo` (`encToUserId` + `privateData`).
//! - [`account_reference`] β€” the masked `accountReference`.
//! - [`private_document_envelope`] β€” the standard private document envelope (version 1).
//! - [`shielded_address`]: `encryptedShieldedAddress` and the per-contact index rule.
//! - [`error`] β€” the shared [`CryptoError`].
//!
//! Every public item is re-exported at the crate root, so the API is flat
Expand All @@ -24,6 +25,7 @@ mod contact_info;
mod ecdh;
mod error;
mod private_document_envelope;
mod shielded_address;

pub use account_label::{decrypt_account_label, encrypt_account_label};
pub use account_reference::{
Expand All @@ -50,3 +52,8 @@ pub use private_document_envelope::{
PRIVATE_DOCUMENT_ENVELOPE_OVERHEAD_LEN, PRIVATE_DOCUMENT_ENVELOPE_VERSION,
PRIVATE_DOCUMENT_ENVELOPE_WRAPPER_LEN,
};
pub use shielded_address::{
decrypt_shielded_address, encrypt_shielded_address, is_shielded_contact_index,
shielded_contact_index, shielded_contact_index_key, ENCRYPTED_SHIELDED_ADDRESS_LEN,
SHIELDED_ADDRESS_LEN, SHIELDED_DIVERSIFIER_INDEX_LEN, SHIELDED_FULL_VIEWING_KEY_LEN,
};
Loading
Loading