Skip to main content

Messaging

DePIN Messaging is a token-gated, end-to-end encrypted messaging system for the Neurai blockchain. Only holders of a specific asset can submit and decrypt messages in that token pool.

DePIN Payload Structure

Overview​

DePIN Messaging combines three elements:

  • Access control via token ownership (asset-gated pools).
  • Hybrid encryption using ECIES (secp256k1 ECDH) + AES-256-GCM.
  • Message integrity with ECDSA signatures (secp256k1).

Messages are encrypted client-side. Pools validate and store ciphertext, but they cannot know the content of the encrypted messages.

Architecture​

Core components​

  1. Local pool: in-memory message storage (CDepinMsgPool).
  2. Network server: JSON-RPC 2.0 on exclusive DePIN port 19002 for remote submission.
  3. Core RPC: standard node RPC on 19001 for message retrieval.
  4. Public key index: blockchain-based registry of revealed public keys.

Topology​

DePIN Payload Structure

Message format (technical)​

CDepinMessage (outer envelope)​

Fields:

  • token: asset name (string)
  • senderAddress: Neurai address
  • timestamp: UNIX time (int64)
  • signature: ECDSA signature over message hash
  • encryptedPayload: serialized ECIES message

Serialization (CompactSize / varint):

[varint token_len][token]
[varint addr_len][address]
[8 bytes timestamp LE]
[varint sig_len][signature]
[varint payload_len][encrypted_payload]

CECIESEncryptedMessage (inner payload)​

Fields:

  • ephemeralPubKey: 33 bytes (compressed secp256k1)
  • encryptedPayload: AES-256-GCM payload (nonce + ciphertext + tag)
  • recipientKeys: map of hash160(address) -> per-recipient wrapped AES key

encryptedPayload:

[12 bytes nonce][ciphertext][16 bytes GCM tag]

Per-recipient key package (60 bytes):

[12 bytes recipient_nonce][32 bytes encrypted_aes_key][16 bytes recipient_tag]

Cryptography​

ECIES hybrid encryption​

  1. Generate ephemeral keypair per message.
  2. Derive a message AES key using KDF-SHA256.
  3. Encrypt the plaintext using AES-256-GCM.
  4. For each recipient:
    • ECDH with recipient pubkey.
    • Derive a wrap key (KDF-SHA256).
    • Encrypt the AES key with AES-256-GCM.

ECDSA signing​

The sender signs:

hash = DSHA256(
  token || senderAddress || timestamp || encryptedPayload
)
signature = ECDSA_Sign(hash, sender_privkey)

Verification recovers the public key from the signature and checks the derived address against senderAddress.

End-to-end message flow​

Sending (remote client -> pool)​

  1. Discover token holders from chain.
  2. Resolve their public keys from the public key index.
  3. Encrypt the plaintext into an ECIES payload.
  4. Build and sign CDepinMessage.
  5. Submit via depinsubmitmsg to the pool (port 19002).

Receiving (client-side decryption)​

  1. Call depinreceivemsg(token, address, lastTimestamp) on a pool.
  2. Pool returns encrypted messages only (no server-side decryption).
  3. Client attempts decryption locally; non-matching recipient keys fail auth.

RPC reference​

depinsubmitmsg (pool server, port 19002)​

Submit a pre-encrypted, signed message:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "depinsubmitmsg",
  "params": ["<hex_serialized_message>"]
}

CLI:

neurai-cli depinsubmitmsg "<hex_serialized_message>"

depinreceivemsg (core RPC, port 8766)​

Fetch encrypted messages for client-side decryption:

{
  "jsonrpc": "1.0",
  "id": "1",
  "method": "depinreceivemsg",
  "params": ["TOKEN", "Nxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", 1730000000]
}

CLI:

neurai-cli depinreceivemsg "TOKEN" "Nxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" 1730000000

Configuration​

Enable DePIN messaging in neurai.conf:

# Mandatory
txindex=1                   # Required for Assets
assetindex=1                # Required for DePIN
depinmsg=1                  # Enable DePIN messaging
depinmsgtoken=MYTOKEN       # Token that controls access

# Message Limits
depinmsgmaxusers=30         # Max recipients (default: 20, max: 50)
depinmsgsize=2048           # Max size bytes (default: 1024, max: 10240)
depinmsgexpire=336          # Expiry hours (default: 168, max: 720)

# Pool Management
depinpoolsize=200           # Max pool MB (default: 100, max: 1000)
depinpoolpersist=1          # Persist pool on shutdown (default: 0)

Verify settings:

neurai-cli depingetmsginfo

Security considerations​

  • Integrity: messages are signed and verified before acceptance.
  • Access control: sender must hold the pool token.
  • Confidentiality: servers do not decrypt payloads; only recipients can.
  • DoS limits: message size, recipient count, expiry, and pool size are capped.
  • Metadata: sender, timestamp, and recipient count remain visible.

Implementation notes​

The client library @neuraiproject/neurai-depin-msg provides:

  • Builds serialized CDepinMessage payloads for depinsubmitmsg
  • Decrypts encrypted_payload_hex from depinreceivemsg

Resources​