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
17 changes: 16 additions & 1 deletion book/src/evo-sdk/dashpay-contact-requests.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,14 +48,29 @@ recipient's identity decryption public key.

## What consensus checks

From protocol version 15 a contact request may also carry the optional
`encryptedShieldedAddress`: the sender's shielded payment address for this
contact, encrypted with the same shared secret. Wallets write it in 64 bytes:

Comment on lines +51 to +54

@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 71ecfc28; see the replies below.

🟡 Suggestion: Describe 64 bytes as the wallet encoding, not the only valid length

This section says encryptedShieldedAddress is exactly 64 bytes, but the next paragraph and the schema accept both 64-byte and 80-byte ciphertexts. Readers implementing a wallet or SDK could therefore reject a consensus-valid 80-byte value. Describe 64 bytes as the current wallet encoding while retaining the subsequent explanation that consensus accepts 64 or 80 bytes.

Suggested change
From protocol version 15 a contact request may also carry the optional
`encryptedShieldedAddress`: the sender's shielded payment address for this
contact, encrypted with the same shared secret. It is exactly 64 bytes:
contact, encrypted with the same shared secret. Wallets currently write 64 bytes:

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

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 71ecfc28): Your change in 71ecfc2 resolves this: the book now distinguishes the current 64-byte wallet encoding from both accepted ciphertext lengths and tells readers to ignore an undecodable value rather than refuse the contact request.

- 16 bytes: AES-CBC initialization vector, drawn at random for this field
- 48 bytes: AES-CBC ciphertext of the 43-byte address (an 11-byte diversifier
followed by a 32-byte transmission key)

That is the current encoding, not the only length the contract accepts: it
takes 64 or 80 bytes, the two lengths in its range that are an IV plus whole
blocks, and wallets keep 80 for a later encoding. A reader that cannot decode
a value ignores it instead of refusing the contact request. A sender gives
each contact a different address, so a payment that arrives on one is
attributed to that contact.

From protocol version 15 the DashPay contract (v3) states these checks in its
schema, and a contact request that fails one is refused (and the fee charged):

| Rule | Declared as | Error |
| --- | --- | --- |
| `toUserId` is not the sender | `distinctFrom: "$ownerId"` on `toUserId` | `DocumentPropertyNotDistinctError` (10419) |
| The recipient identity exists | `refersTo` of type `identity` on `toUserId` | `ReferencedEntityNotFoundError` (40120) |
| `encryptedPublicKey` and `encryptedAccountLabel` are a 16-byte IV plus whole 16-byte blocks | `encryptedFor` with scheme `ecdh-secp256k1-aes256-cbc` | `InvalidEncryptedPropertyShapeError` (10420) |
| `encryptedPublicKey`, `encryptedAccountLabel` and `encryptedShieldedAddress` are a 16-byte IV plus whole 16-byte blocks | `encryptedFor` with scheme `ecdh-secp256k1-aes256-cbc` | `InvalidEncryptedPropertyShapeError` (10420) |

Up to protocol version 14 a data trigger made only the first two checks and
reported both as a `DataTriggerConditionError` (40500). Neither version checks
Expand Down
14 changes: 14 additions & 0 deletions packages/dashpay-contract/schema/v3/dashpay.schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -285,6 +285,20 @@
"minItems": 38,
"maxItems": 102,
"position": 6
},
"encryptedShieldedAddress": {
"type": "array",
"byteArray": true,
"minItems": 64,
"maxItems": 80,
"encryptedFor": {
"recipient": "toUserId",
"recipientKey": "recipientKeyIndex",
"senderKey": "senderKeyIndex",
"scheme": "ecdh-secp256k1-aes256-cbc"
},
"position": 7,
"description": "Sender's per-contact shielded payment address (43 bytes), encrypted to the contact with the DIP-15 shared key"
}
},
"required": [
Expand Down
9 changes: 9 additions & 0 deletions packages/dashpay-contract/src/v3/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,15 @@ use serde_json::Value;
// check the profile data trigger made up to protocol version 14. Their descriptions say
// so in place of v2's mention of the data trigger.
//
// It adds one property:
//
// - `contactRequest.encryptedShieldedAddress`, optional and last in position: the
// sender's shielded payment address for this contact (43 bytes), encrypted as
// `encryptedPublicKey` is (`encryptedFor`). That is 64 bytes, an IV and three AES
// blocks. The contract also accepts 80 bytes, an IV and four blocks, which wallets
// keep for a later encoding. A contact request stored before the property existed
// ends before it and reads back without it.
//
// And it adds one type:
//
// - `privateContactRequest`, a private type of 589-byte entries: a contact request
Expand Down
120 changes: 115 additions & 5 deletions packages/rs-dpp/src/system_data_contracts.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1481,11 +1481,12 @@ mod dashpay_v3_tests {
ConstraintExpression, PropertyConstraint,
};
use crate::data_contract::document_type::{
DistinctFrom, DocumentPropertyReferenceTarget, DocumentPropertyType, DocumentTypeRef,
EncryptedFor, EncryptedForRecipient, EncryptionScheme,
ByteArrayPropertySizes, DistinctFrom, DocumentPropertyReferenceTarget,
DocumentPropertyType, DocumentTypeRef, EncryptedFor, EncryptedForRecipient,
EncryptionScheme,
};
use crate::document::serialization_traits::DocumentPlatformConversionMethodsV0;
use crate::document::DocumentV0;
use crate::document::{Document, DocumentV0, DocumentV0Getters};
use platform_value::{Identifier, Value};
use std::collections::BTreeMap;

Expand Down Expand Up @@ -1625,7 +1626,7 @@ mod dashpay_v3_tests {
}

/// The two checks of the contact request data trigger, as declarations: the
/// recipient is an identity, and not the writer. The two ECDH fields name their
/// recipient is an identity, and not the writer. The three ECDH fields name their
/// encryption, so their lengths must be an IV plus whole AES blocks.
#[test]
fn should_declare_the_contact_request_checks_and_encryption() {
Expand Down Expand Up @@ -1660,11 +1661,120 @@ mod dashpay_v3_tests {
encrypted,
vec![
("encryptedAccountLabel", recipe.clone()),
("encryptedPublicKey", recipe),
("encryptedPublicKey", recipe.clone()),
("encryptedShieldedAddress", recipe),
]
);
}

/// A contact request may carry the sender's shielded payment address for this
/// contact: 43 bytes encrypted as `encryptedPublicKey` is, so an IV and three AES
/// blocks (64 bytes), with the 80-byte length kept for a later encoding. The
/// property is optional and the last in position.
#[test]
fn should_let_a_contact_request_carry_an_encrypted_shielded_address() {
let contract = dashpay();
let contact_request = document_type(&contract, "contactRequest");

let (last_name, last_property) = contact_request
.properties()
.last()
.expect("contactRequest has properties");
assert_eq!(last_name, "encryptedShieldedAddress");
assert!(!last_property.required);
assert_eq!(
last_property.property_type,
DocumentPropertyType::ByteArray(ByteArrayPropertySizes {
min_size: Some(64),
max_size: Some(80),
})
);

// The private request carries the same address in the clear, inside its
// encrypted entry, so it has no encrypted form of it.
assert!(document_type(&contract, "privateContactRequest")
.flattened_properties()
.get("encryptedShieldedAddress")
.is_none());
}

/// A contact request stored under DashPay v2 ends before the property v3 adds.
/// Read under v3 it is the same document, without a shielded address.
#[test]
fn should_read_a_contact_request_stored_before_the_shielded_address_existed() {
let v3 = dashpay();
let protocol_version_14 = PlatformVersion::get(14).expect("protocol version 14");
let v2 = load_system_data_contract(SystemDataContract::Dashpay, protocol_version_14)
.expect("DashPay v2");
assert!(document_type(&v2, "contactRequest")
.flattened_properties()
.get("encryptedShieldedAddress")
.is_none());

let stored_under_v2 = DocumentV0 {
id: Identifier::from([4; 32]),
owner_id: Identifier::from([5; 32]),
properties: BTreeMap::from([
("toUserId".to_string(), Value::Identifier([6; 32])),
("encryptedPublicKey".to_string(), Value::Bytes(vec![7; 96])),
("senderKeyIndex".to_string(), Value::I64(2)),
("recipientKeyIndex".to_string(), Value::I64(3)),
("accountReference".to_string(), Value::I64(0x0123_4567)),
(
"encryptedAccountLabel".to_string(),
Value::Bytes(vec![8; 48]),
),
("autoAcceptProof".to_string(), Value::Bytes(vec![9; 38])),
]),
created_at: Some(1_700_000_000_000),
created_at_core_block_height: Some(2_000_000),
..Default::default()
};
let bytes = stored_under_v2
.serialize(
document_type(&v2, "contactRequest"),
&v2,
protocol_version_14,
)
.expect("the contact request serializes under v2");

let read = Document::from_bytes(
&bytes,
document_type(&v3, "contactRequest"),
PlatformVersion::latest(),
)
.expect("a v2 contact request reads under v3");
assert_eq!(read.properties(), &stored_under_v2.properties);
assert_eq!(read.id(), stored_under_v2.id);
assert_eq!(read.owner_id(), stored_under_v2.owner_id);
assert_eq!(read.created_at(), stored_under_v2.created_at);
assert_eq!(
read.created_at_core_block_height(),
stored_under_v2.created_at_core_block_height
);

// With the address, the stored form grows by the property and nothing else moves.
let mut with_address = stored_under_v2.clone();
with_address.properties.insert(
"encryptedShieldedAddress".to_string(),
Value::Bytes(vec![10; 64]),
);
let bytes = with_address
.serialize(
document_type(&v3, "contactRequest"),
&v3,
PlatformVersion::latest(),
)
.expect("the contact request serializes under v3");
let read = Document::from_bytes(
&bytes,
document_type(&v3, "contactRequest"),
PlatformVersion::latest(),
)
.expect("a v3 contact request reads back");
assert_eq!(read.properties(), &with_address.properties);
}

/// The check of the profile data trigger, as two rules: each DIP-33 payment
/// address starts with its type byte, 0x00 (P2PKH) or 0x01 (P2SH). A profile
/// without the address reads its first byte as 0, so the rule holds, as the
Expand Down
Loading
Loading