DashPay Contact Requests

DashPay contact requests are contactRequest documents in the DashPay data contract. The document links the sender identity to toUserId and carries the sender's DIP-15 contact payment public key encrypted for the recipient.

The Evo SDK exposes the DIP-15 derivation primitive through wallet.deriveDashpayContactKey. Applications still need to encrypt the derived contact xpub before submitting the document.

Document fields

The contactRequest document requires these fields:

type DashpayContactRequestDocument = {
  $createdAt: number;
  $createdAtCoreBlockHeight: number;
  toUserId: Uint8Array;
  encryptedPublicKey: Uint8Array;
  senderKeyIndex: number;
  recipientKeyIndex: number;
  accountReference: number;
};

The current DashPay contract schema requires the system field $createdAtCoreBlockHeight. Older external references may use coreHeightCreatedAt; do not submit that name to the current contract.

encryptedPublicKey is exactly 96 bytes:

  • 16 bytes: AES-CBC initialization vector
  • 80 bytes: AES-CBC ciphertext for the sender's 69-byte compact contact xpub

The compact xpub is the parent fingerprint (4 bytes), chain code (32 bytes) and public key (33 bytes), without the version, depth and child number of a full 78-byte BIP32 serialization. Receivers, including the reference mobile wallets and the Rust, Swift and Kotlin SDKs, refuse any other plaintext length. Both 69 and 78 bytes pad to the same 80-byte ciphertext, so the contract cannot catch the mistake: a request that encrypts the full 78 bytes is stored on chain, and the recipient's wallet then drops it.

The sender derives the contact xpub from the sender identity, recipient identity, account, and address index. The sender then encrypts that xpub with an ECDH shared secret from the sender's identity encryption private key and the 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:

  • 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):

RuleDeclared asError
toUserId is not the senderdistinctFrom: "$ownerId" on toUserIdDocumentPropertyNotDistinctError (10419)
The recipient identity existsrefersTo of type identity on toUserIdReferencedEntityNotFoundError (40120)
encryptedPublicKey, encryptedAccountLabel and encryptedShieldedAddress are a 16-byte IV plus whole 16-byte blocksencryptedFor with scheme ecdh-secp256k1-aes256-cbcInvalidEncryptedPropertyShapeError (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 that the two key indexes name keys the identities hold, the purpose of those keys, or that the bytes decrypt. Wallets and SDKs can read the encryption recipe from the contract (encrypted_properties() in Rust).

Derive the contact payment xpub

import { wallet } from '@dashevo/evo-sdk';

const senderKeyIndex = 0;
const recipientKeyIndex = 0;
const addressIndex = 0;

const contactKey = await wallet.deriveDashpayContactKey({
  mnemonic: senderMnemonic,
  network: 'testnet',
  senderIdentityId,
  receiverIdentityId: recipientIdentityId,
  account: 0,
  addressIndex,
});

// contactKey.xpub is encrypted into contactRequest.encryptedPublicKey.

senderKeyIndex and recipientKeyIndex identify the identity public keys used for ECDH. addressIndex is the DIP-15 child index used for contact payment key derivation and is independent from those identity key indexes.

Build the encrypted public key

The following helper shows the byte-level encryption shape. It uses the same secp256k1 primitives exposed by @dashevo/dashcore-lib and Node.js crypto for AES-CBC.

import crypto from 'node:crypto';
import dashcore from '@dashevo/dashcore-lib';

function fixed32(value): Buffer {
  return Buffer.from(value.toArray('be', 32));
}

function deriveSharedKey({
  privateKeyWif,
  publicKeyBytes,
}: {
  privateKeyWif: string;
  publicKeyBytes: Uint8Array;
}): Buffer {
  const privateKey = dashcore.PrivateKey.fromWIF(privateKeyWif);
  const publicKey = dashcore.PublicKey.fromBuffer(Buffer.from(publicKeyBytes));
  const sharedPoint = publicKey.point.mul(privateKey.toBigNumber());

  if (sharedPoint.isInfinity()) {
    throw new Error('ECDH shared point is invalid');
  }

  const x = fixed32(sharedPoint.getX());
  const y = fixed32(sharedPoint.getY());
  const compressedPrefix = Buffer.from([2 | (y[31] & 1)]);

  return crypto.createHash('sha256').update(Buffer.concat([compressedPrefix, x])).digest();
}

function compactXpubPayload(xpub: string): Buffer {
  const payload = dashcore.encoding.Base58Check.decode(xpub);

  if (payload.length !== 78) {
    throw new Error(`Invalid DashPay contact xpub length: ${payload.length}`);
  }

  // BIP32 layout: version(4) depth(1) parentFingerprint(4) childNumber(4)
  // chainCode(32) publicKey(33). DIP-15 encrypts only the parent
  // fingerprint, chain code and public key: 69 bytes.
  return Buffer.concat([payload.subarray(5, 9), payload.subarray(13, 78)]);
}

function encryptContactXpub({
  contactXpub,
  senderEncryptionPrivateKeyWif,
  recipientDecryptionPublicKeyBytes,
}: {
  contactXpub: string;
  senderEncryptionPrivateKeyWif: string;
  recipientDecryptionPublicKeyBytes: Uint8Array;
}): Uint8Array {
  const aesKey = deriveSharedKey({
    privateKeyWif: senderEncryptionPrivateKeyWif,
    publicKeyBytes: recipientDecryptionPublicKeyBytes,
  });
  const payload = compactXpubPayload(contactXpub);
  const iv = crypto.randomBytes(16);
  const cipher = crypto.createCipheriv('aes-256-cbc', aesKey, iv);
  const encrypted = Buffer.concat([
    cipher.update(payload),
    cipher.final(),
  ]);

  const encryptedPublicKey = Buffer.concat([iv, encrypted]);

  if (encryptedPublicKey.length !== 96) {
    throw new Error(`DashPay encryptedPublicKey must be 96 bytes, got ${encryptedPublicKey.length}`);
  }

  return encryptedPublicKey;
}

Submit the document

const encryptedPublicKey = encryptContactXpub({
  contactXpub: contactKey.xpub,
  senderEncryptionPrivateKeyWif,
  recipientDecryptionPublicKeyBytes,
});

const accountReference = 0;

const document = {
  $createdAt: Date.now(),
  $createdAtCoreBlockHeight: platformCoreHeight,
  toUserId: recipientIdentityIdBytes,
  encryptedPublicKey,
  senderKeyIndex,
  recipientKeyIndex,
  accountReference,
};

accountReference above is a placeholder for the current Platform field accepted by the contactRequest schema. It is not a complete implementation of any ASK/HMAC-based account-reference obfuscation described in older DIP text.

When querying received requests through the JavaScript SDK, pass identity IDs in the representation expected by the SDK call being used. The contract stores toUserId as a 32-byte identifier, while some high-level JavaScript query helpers accept the base58 identity string and perform the conversion internally.

Current SDK boundary

wallet.deriveDashpayContactKey handles DIP-15 path derivation. It does not currently submit DashPay documents or encrypt/decrypt encryptedPublicKey. Applications need to combine the wallet helper with identity encryption keys until a higher-level DashPay contact request helper is added to the JavaScript SDK.

Treat the example as a byte-level reference. A production application should add contract validation, decrypt round-trip tests, and checks that the selected identity keys are active secp256k1 keys bounded for DashPay contact requests.