XChain Platform SDK — Messaging Reference

This document covers the SDK’s messaging module: ECIES, ECDH, and AES encryption for MESSAGE actions, public key lookup, and high-level send/receive with automatic encryption and decryption.

Overview

The SDK provides a messaging module for encrypted and plaintext communication between addresses:

• sdk.messaging (MessagingUtils) — ECIES/ECDH/AES encryption, public key resolution, high-level send and receive.

Available on the SDK instance and as top-level convenience methods:

const sdk = new XChainSDK({
    network: 'bitcoin-mainnet',
    explorerUrl: 'localhost',
    encoderUrl: 'localhost'
});

// Namespaced access
sdk.messaging.eciesEncrypt('Hello', recipientPubkey);
sdk.messaging.send(params, sdk);

// Convenience access
sdk.sendMessage(params);
sdk.getPublicKey(address);
sdk.getMessagesForAddress(address, opts);

Encryption Methods

ECIES (Method 1) — Address Communication

ECIES encrypts directly to the recipient’s public key. No prior key exchange is needed. Any device with the recipient’s private key can decrypt.

Encrypt

const result = sdk.messaging.eciesEncrypt(plaintext, recipientPubkey);
// result.ciphertext — hex-encoded ciphertext

Parameters:

• plaintext (string) — Message to encrypt
• recipientPubkey (string|Buffer) — Recipient’s compressed public key (33 bytes hex)

The ciphertext contains: ephemeralPubkey(33) + iv(12) + authTag(16) + encryptedData

Decrypt

const result = sdk.messaging.eciesDecrypt(ciphertext, wif);
// result.plaintext — decrypted message string

Parameters:

• ciphertext (string|Buffer) — Hex-encoded ciphertext from eciesEncrypt
• wif (string) — Recipient’s WIF private key

ECDH (Method 2) — Session Communication

ECDH requires a key exchange handshake. Both parties exchange public keys via format 0/1 MESSAGE actions, then derive a shared secret.

Generate Session Key

const result = sdk.messaging.generateSessionKey(wif);
// result.publicKey — hex-encoded compressed public key for key exchange

Derive Shared Secret

const result = sdk.messaging.deriveSharedSecret(wif, theirPublicKey);
// result.sharedSecret — hex-encoded 32-byte shared secret

Both parties derive the same shared secret from myPrivateKey + theirPublicKey.

Encrypt / Decrypt

const encrypted = sdk.messaging.sessionEncrypt(plaintext, sharedSecret);
// encrypted.ciphertext — hex-encoded ciphertext

const decrypted = sdk.messaging.sessionDecrypt(ciphertext, sharedSecret);
// decrypted.plaintext — original message

AES (Method 3) — Shared Secret Communication

AES uses a pre-shared key. If the key is not exactly 32 bytes, it is hashed with SHA-256 to derive the encryption key.

Encrypt / Decrypt

const encrypted = sdk.messaging.aesEncrypt(plaintext, sharedKey);
// encrypted.ciphertext — hex-encoded ciphertext

const decrypted = sdk.messaging.aesDecrypt(ciphertext, sharedKey);
// decrypted.plaintext — original message

Parameters:

• sharedKey (string|Buffer) — Pre-shared key (hex string, Buffer, or passphrase)

Public Key Lookup

Look up the public key for any address that has sent at least one XChain transaction. The public key is extracted from the transaction’s scriptSig/witness data by the decoder and served via the explorer API.

// Via convenience method
const pubkey = await sdk.getPublicKey('1SomeAddress...');

// Via module directly
const pubkey = await sdk.messaging.getPublicKey(address, sdk.explorer);

Returns the hex-encoded compressed public key (66 characters), or null if not found.

High-Level Send

Send a message with automatic pubkey resolution, encryption, action creation, PSBT signing, and broadcasting.

const result = await sdk.sendMessage({
    wif: senderWIF,
    destination: recipientAddress,
    coin: 'BTC',                      // BTC, LTC, or DOGE — destination address network
    message: 'Hello!',
    method: 1,                        // 1=ECIES (default), 2=ECDH, 3=AES, null=plaintext
    sharedSecret: '...',              // Required for method 2
    sharedKey: '...',                 // Required for method 3
    encoder: { pubkey: senderPubkey } // Encoder options
});
// result.txid         — transaction ID
// result.actionString — the raw MESSAGE action string

Method Behavior

High-Level Receive / Read

Fetch and optionally decrypt messages for an address.

const messages = await sdk.getMessagesForAddress('1MyAddress...', {
    wif: myWIF,             // Optional: decrypt ECIES messages
    type: 'received',       // 'sent', 'received', or 'all' (default)
    limit: 10,
    page: 1,
    sortorder: 'DESC'
});

Each message object:

Auto-decryption only works for ECIES (method 1) when wif is provided. ECDH and AES messages require the application to supply the shared secret/key and decrypt manually using sessionDecrypt() or aesDecrypt().

Convenience Methods

Error Handling

The messaging module throws SDKMessagingError with the following codes:

Copyright © 2025–2026 Dankest, LLC

Based on XChain Platform by Dankest, LLC – https://dankest.llc

Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-or-later) with a commercial license available for proprietary use.

You may use, modify, and distribute this material under the terms of the License. See LICENSE and NOTICE for full terms. See the licensing overview.