HIP-1334: Private Message Box Standard for Hiero Accounts

Abstract

This HIP proposes a standardized method for Hiero accounts to receive encrypted, asynchronous messages through dedicated “message boxes” implemented as Hiero Consensus Service (HCS) topics. The specification defines a protocol enabling any account to advertise a message box topic ID in their account memo, publish encryption keys to that topic, and receive end-to-end encrypted messages from other network participants. This creates a decentralized, censorship-resistant messaging layer for notifications, alerts, wallet communications, and general peer-to-peer messaging on any Hiero network.

A simplified interactive presentation of the message box flow is available.

A complete reference implementation is available at https://github.com/InternetOfPeers/hiero-message-box.

Motivation

Hiero currently lacks a standardized mechanism for accounts to receive asynchronous, private messages. There are numerous use cases requiring secure message delivery:

• Security Alerts: Wallet providers and custodians need to notify users about suspicious activities, security updates, or required actions on their accounts
• Service Notifications: dApps and services need to communicate with users about transaction confirmations, state changes, or other events without relying on centralized servers
• Peer-to-Peer Communication: Users may want to establish private communication channels without sharing off-chain contact information
• Business Communications: Enterprises need secure, auditable messaging between blockchain accounts for orders, invoices, or coordination
• Cross-Application Messaging: Different applications need a common protocol to send messages to users regardless of which wallet or interface they’re using

Current workarounds have significant limitations:

• Off-chain messaging: Requires centralized servers, introduces privacy and censorship concerns, and creates dependencies on third-party services
• On-chain transaction memos: Limited capacity (~100 bytes), unencrypted by default, and not designed for message delivery
• Smart contract events: Require polling, lack privacy, and are not suitable for direct account-to-account messaging
• Direct HCS usage: Requires coordination, lacks standardization, and provides no discovery mechanism

This proposal establishes a standard that:

1. Enables message box discovery through a standardized account memo format
2. Provides end-to-end encryption with support for multiple encryption schemes
3. Leverages existing Hiero services (HCS topics) for message delivery and consensus
4. Maintains backward compatibility with all existing Hiero functionality
5. Offers implementation flexibility through support for both RSA and ECIES encryption
6. Creates no additional network load beyond standard HCS topic operations

By standardizing this messaging pattern, the Hiero ecosystem can develop interoperable tools, wallets, and applications that seamlessly communicate with users’ message boxes regardless of implementation.

Rationale

Using HCS Topics as Message Boxes

Hiero Consensus Service provides ideal properties for a message box system:

• Immutable, ordered message delivery with consensus timestamps
• Pay-per-message model with low, predictable costs
• Built-in resistance to censorship and tampering
• Efficient retrieval through Mirror Node APIs
• No additional smart contract complexity or gas costs

Alternative approaches were considered but discarded:

• Token memos: Limited to token operations, insufficient for general messaging
• File service: Not designed for streaming messages, poor query performance
• Smart contracts: Higher costs, unnecessary complexity, potential for bugs

Account Memo for Discovery

The account memo field provides a natural, standardized location for advertising a message box:

• Already exists on every account with 100-byte capacity
• Easily queryable through Mirror Node REST API
• User-controlled and updateable
• No protocol changes required

The [HIP-1334:0.0.xxxxx] format was chosen to:

• Be clearly identifiable and parseable
• Allow future extensions with different HIP numbers
• Remain human-readable for transparency
• Coexist with other memo content

Dual Encryption Support

Supporting both RSA and ECIES provides flexibility for different use cases:

This dual approach allows:

• ED25519 accounts to use RSA with separate encryption keys
• secp256k1 accounts to reuse their Hiero key for encryption, or using an HD wallet to generate a dedicated key from the same seed phrase
• Users to choose based on their security and convenience preferences
• Future addition of other encryption schemes without breaking changes

Admin key for the topic

Users must remain in full control of their message boxes, so the client MUST include their public key as the topic admin key.

First Message Contains Public Key

Publishing the public key as the first topic message:

• Creates a single source of truth for the current public key
• Enables key rotation by creating a new message box
• Allows senders to verify encryption scheme before sending messages
• Maintains all key information on-chain for reliability

Support for Message Formats

Both JSON and CBOR encoding are supported:

• JSON: Human-readable, easy debugging, wide tool support
• CBOR: Binary format, ~3-5% size reduction, better for high-volume scenarios

Automatic format detection ensures backward compatibility and user choice.

Clients SHOULD provide users with options to display or filter out messages that are unencrypted or do not conform to the supported formats.

Message Chunking

Messages larger than 1KB MUST be split into chunks and transparently reassembled for the users by the client. This:

• Eliminates size limitations for applications
• Leverages existing HCS infrastructure
• Maintains message ordering guarantees

The Hiero SDKs manage the split of the messages into multiple chunks, but clients MUST implement the correct reassembly procedure before proceeding with the decryption.

Future Enhancements

The following enhancements are intentionally excluded from this initial specification but may be addressed in future HIPs:

• Authenticated messaging with digital signatures
• Group messaging and broadcast capabilities
• Spam prevention and message filtering standards
• Post-quantum cryptography support
• Rich message metadata and attachments

User Stories

1. As a wallet user, I would like to receive security alerts about suspicious activity on my account, without having to share my email address or phone number. This would allow me to maintain my privacy while staying informed about critical security events.

2. As a user, I want to opt in to a private messaging system and choose whether or not to advertise a dedicated inbox for private messages.

3. As a service provider, I want to be able to notify users of important changes to the status of my application, ensuring they receive timely and secure updates without having to rely on centralised services (social networks) or unreliable, hard-to-verify sources.

4. As a security researcher, I want to alert token holders to discovered vulnerabilities or phishing attempts targeting their assets, so that the community can be protected through decentralised warnings, independent of centralised communication channels.

5. As an enterprise user, I want to establish secure communication channels with business partners using only their Hiero account IDs. This would allow me to coordinate transactions without sharing off-chain contact information or relying on third-party services.

6. As a DApp developer, I want my applications to include the ability for users to send messages to any Hiero account with a configured message box, regardless of the wallet or implementation used, so they can communicate freely across the ecosystem.

Specification

Overview

The message box system consists of three components:

1. Account Memo Convention: Standardized format for advertising a message box ID
2. Topic Structure: First message in the topic contains a public key, subsequent messages are encrypted with that
3. Message Format: Structured envelope supporting multiple encryption schemes and encodings

Account Memo Convention

An account advertises its message box by including the following format in its account memo:

[HIP-1334:<topic-id>]

Requirements:

• <topic-id> MUST be a valid Hiero topic ID (format: shard.realm.num)
• The bracket notation [HIP-1334:...] MUST be present
• The memo MAY contain additional text before or after the bracketed section
• The topic ID SHOULD be the only HIP-1334 reference in the memo
• If multiple HIP-1334 references exist, implementations SHOULD use the first one

Examples:

[HIP-1334:0.0.123456] is my message box. Send me private messages there.

すべての通信を暗号化してください [HIP-1334:0.0.456789]

صندوق رسائلي هو [HIP-1334:0.0.456789]. سيتم تجاهل النص العادي.

Discovery Process:

1. Query the account’s memo via Mirror Node REST API: GET /api/v1/accounts/{accountId}
2. Parse the memo field for the pattern \[HIP-1334:(0\.0\.\d+)\]
3. Extract the topic ID
4. Retrieve the first message from the topic to get the public key

Topic Setup

Topic Memo

The topic memo SHOULD display the owner’s details in plain text. Although it uses the HIP-1334 format, it uses the account ID rather than the message box ID used by the account memo:

[HIP-1334:<account-id>]

Example:

[HIP-1334:0.0.1234] listens here for HIP-1334 encrypted messages.

First message

The first message in a message box topic MUST contain the public key, encryption metadata, and a cryptographic signature proving ownership. This message MUST use JSON encoding and follow a two-part structure with payload and proof sections.

RSA Format:

{
  "payload": {
    "encryptionType": "RSA",
    "publicKey": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhki...",
    "type": "HIP-1334_PUBLIC_KEY"
  },
  "proof": {
    "accountId": "0.0.12345",
    "signerPublicKey": "a1b2c3d4...",
    "signerKeyType": "ED25519",
    "signature": "d5e6f7g8..."
  }
}

ECIES Format:

{
  "payload": {
    "encryptionType": "ECIES",
    "publicKey": {
      "curve": "secp256k1",
      "key": "03a1b2c3d4e5f6...",
      "type": "ECIES"
    },
    "type": "HIP-1334_PUBLIC_KEY"
  },
  "proof": {
    "accountId": "0.0.12345",
    "signerPublicKey": "02a1b2c3d4...",
    "signerKeyType": "ECDSA_SECP256K1",
    "signature": "d5e6f7g8..."
  }
}

Payload Fields:

• encryptionType: MUST be either "RSA" or "ECIES"
• publicKey:
  • For RSA: PEM-encoded RSA-2048 public key string
  • For ECIES: Object containing:
    • curve: MUST be "secp256k1" (only supported curve)
    • key: Hex-encoded public key (33 bytes for compressed secp256k1)
    • type: MUST be "ECIES"
• type: MUST be the string "HIP-1334_PUBLIC_KEY"

Proof Fields:

• accountId: The Hiero account ID that owns this message box (format: “shard.realm.num”)
• signerPublicKey: Hex-encoded public key of the account (from Hiero account key)
• signerKeyType: MUST be either "ED25519" or "ECDSA_SECP256K1"
• signature: Hex-encoded signature of the canonical JSON representation of the payload

Signature Generation:

1. Serialize the payload object using canonical JSON (keys sorted alphabetically)
2. Sign the canonical JSON string with the message box owner’s Hiero private key
3. Encode the signature in hexadecimal format
4. Include the signature and signer’s public key in the proof section

Signature Verification:

Senders MUST verify the signature before sending messages:

1. Retrieve the message box owner’s public key from Mirror Node API
2. Verify that proof.signerPublicKey matches the account’s public key
3. Verify that proof.accountId matches the intended recipient
4. Canonicalize the payload object (sort keys alphabetically)
5. Verify the signature using the canonical JSON and the account’s public key
6. If verification fails: warn user and refuse to send message

Message Format

All messages after the first MUST be encrypted using the published public key. Messages MAY use either JSON or CBOR encoding. The CBOR format uses the same structure as JSON but encoded in Concise Binary Object Representation (RFC 8949) for size efficiency.

RSA encrypted message format:

{
  "type": "HIP-1334_ENCRYPTED_MESSAGE",
  "format": "json",
  "data": {
    "type": "RSA",
    "encryptedKey": "base64-encoded-encrypted-AES-key",
    "iv": "base64-encoded-initialization-vector",
    "encryptedData": "base64-encoded-ciphertext"
  }
}

ECIES encrypted message format::

{
  "type": "HIP-1334_ENCRYPTED_MESSAGE",
  "format": "json",
  "data": {
    "type": "ECIES",
    "ephemeralPublicKey": "hex-encoded-ephemeral-public-key",
    "iv": "base64-encoded-initialization-vector",
    "encryptedData": "base64-encoded-ciphertext",
    "authTag": "base64-encoded-auth-tag",
    "curve": "secp256k1"
  }
}

Top-level Fields:

• type: MUST be the string "HIP-1334_ENCRYPTED_MESSAGE"
• format: MUST be either "json" or "cbor"
• data: Object containing encryption-specific fields

RSA Data Fields:

• type: MUST be "RSA"
• encryptedKey: Base64-encoded encrypted AES-256 key (encrypted with RSA-OAEP)
• iv: Base64-encoded initialization vector (16 bytes)
• encryptedData: Base64-encoded ciphertext (encrypted with AES-256-CBC)

ECIES Data Fields:

• type: MUST be "ECIES"
• ephemeralPublicKey: Hex-encoded ephemeral public key (33 bytes compressed)
• iv: Base64-encoded initialization vector (16 bytes)
• encryptedData: Base64-encoded ciphertext (encrypted with AES-256-GCM)
• authTag: Base64-encoded authentication tag (16 bytes)
• curve: MUST be "secp256k1"

Encryption Specifications

RSA-2048 Hybrid Encryption

Key Generation

• Algorithm: RSA
• Modulus length: 2048 bits minimum (SHOULD use 2048 or 4096)
• Public exponent: 65537 (standard)
• Encoding: PKCS#8 for private key, SPKI for public key
• Format: PEM

RSA Encryption Process

1. Generate random 256-bit AES key
2. Generate random 128-bit initialization vector (IV)
3. Encrypt message with AES-256-CBC using the key and IV
4. Encrypt the AES key with recipient’s RSA public key using RSA-OAEP padding (SHA-256 hash)
5. Base64-encode encrypted key, IV, and ciphertext
6. Construct message envelope as specified above

RSA Decryption Process

1. Base64-decode encrypted key, IV, and ciphertext
2. Decrypt AES key using RSA private key with RSA-OAEP padding
3. Decrypt ciphertext using AES-256-CBC with the decrypted key and IV
4. Return plaintext message

RSA Security Properties

• RSA-OAEP provides IND-CCA2 security for key encapsulation
• AES-256-CBC provides confidentiality for message content

ECIES (secp256k1)

Key Requirements

• Curve: secp256k1
• Format: Compressed public keys (33 bytes) SHOULD be used
• Private keys: 32 bytes
• Note: ED25519 keys cannot be used for ECIES (no ECDH support)

ECIES Encryption Process

1. Generate ephemeral secp256k1 key pair
2. Perform ECDH key exchange with recipient’s public key to derive shared secret
3. Derive 256-bit encryption key: encryptionKey = SHA256(sharedSecret)
4. Generate random 128-bit initialization vector (IV)
5. Encrypt message with AES-256-GCM using encryption key and IV
6. Extract authentication tag from AES-GCM
7. Encode ephemeral public key (compressed), IV, ciphertext, and auth tag
8. Construct message envelope as specified above

ECIES Decryption Process

1. Decode ephemeral public key, IV, ciphertext, and auth tag
2. Perform ECDH key exchange with ephemeral public key using recipient’s private key
3. Derive encryption key: encryptionKey = SHA256(sharedSecret)
4. Decrypt ciphertext using AES-256-GCM with encryption key, IV, and verify auth tag
5. Return plaintext message

ECIES Security Properties

• ECDH provides key agreement with computational Diffie-Hellman security
• AES-256-GCM provides authenticated encryption (confidentiality + integrity)
• Authentication tag prevents ciphertext tampering

Implementation Requirements

Message Box Setup

1. Generate or load encryption key pair (RSA or ECIES)
2. If ECIES and account uses ED25519: MUST fallback to RSA or fail with clear error
3. Create new HCS topic with memo referencing the account
4. Set the topic admin key to the message box owner’s public key
5. Prepare the payload containing public key and encryption type
6. Sign the canonical JSON representation of the payload with the owner’s private key
7. Construct first message with both payload and proof sections
8. Submit signed public key message as first message to the topic
9. Update account memo with message box topic ID in HIP-1334 format

Sending Messages

1. Query recipient account memo via Mirror Node
2. Extract message box topic ID
3. Retrieve first message from topic via Mirror Node
4. Parse the first message as JSON with payload and proof structure
5. MUST verify ownership signature:
   • Retrieve recipient’s public key from Mirror Node API
   • Verify proof.signerPublicKey matches the account’s public key
   • Verify proof.accountId matches the intended recipient
   • Canonicalize the payload object (alphabetically sort all keys)
   • Verify signature using canonical JSON and account’s public key
   • If verification fails: warn user and refuse to send message
6. Extract public key and encryption type from verified payload
7. Validate encryption type is supported
8. Encrypt message using appropriate algorithm
9. Submit encrypted message to topic via HCS

Receiving Messages

1. Extract message box topic ID from own account memo
2. Query topic for new messages via Mirror Node (poll or subscribe)
3. For each message:
   • Detect format (JSON or CBOR) by examining first byte
   • Parse message structure
   • If type is HIP-1334_ENCRYPTED_MESSAGE: decrypt using private key
   • If type is HIP-1334_PUBLIC_KEY: ignore or use for verification
4. Handle chunked messages transparently (reassembled by Mirror Node)

Mirror Node Integration

Implementations SHOULD use the Mirror Node REST API for all read operations:

Account Memo Query:

GET /api/v1/accounts/{accountId}

Topic Messages Query:

GET /api/v1/topics/{topicId}/messages

Filtering Messages:

GET /api/v1/topics/{topicId}/messages?sequencenumber=gte:{startSeq}&sequencenumber=lte:{endSeq}

Polling for New Messages:

GET /api/v1/topics/{topicId}/messages?sequencenumber=gt:{lastSeenSeq}&limit=100

Impact on Mirror Node

This HIP has minimal impact on Mirror Node infrastructure:

No Changes Required:

• Existing REST API endpoints fully support this specification
• Topic message queries and account queries already handle all required operations
• Message chunking and reassembly is already implemented

Performance Considerations:

• Message box polling may increase query load
• Mirror Node operators may want to monitor for excessive polling patterns and implement caching strategies for frequently-accessed message boxes

Future Enhancements:

• Optional filtering to identify message box accounts
• WebSocket subscriptions for push notifications
• These are not required for initial implementation

Impact on SDK

This HIP does not require any change to the SDKs.

Error Handling

Implementations MUST handle the following error cases:

Invalid Account:

• Account does not exist
• Account memo does not contain HIP-1334 format
• Action: Return error indicating no message box configured

Invalid Topic:

• Topic does not exist
• Topic has no messages
• First message is not a valid HIP-1334_PUBLIC_KEY message
• First message signature does not match recipient admin key**
• Action: Return error indicating invalid message box configuration

Encryption Errors:

• Unsupported encryption type
• ED25519 key used with ECIES
• Malformed public key
• Action: Return error indicating incompatible encryption configuration

Decryption Errors:

• Invalid ciphertext
• Wrong private key
• Corrupted message
• Action: Log error, skip message, continue processing

Security Considerations

Front Running the First Message:

Although unlikely, considering that the topic is permissionless, a malicious user can technically send the first message before the correct owner of the message box has the possibility to do it, especially if the client is implemented incorrectly or there are unexpected issues between the creation of the topic and the sending of the first message. This can cause problems if the owner of the message box does not immediately notice the issue, so the risk is users starts sending private messages to malicious users.

To solve this problem, the message box owner MUST sign the first message payload, and the sender MUST verify that the first message payload’s signature correspond with the message box owner admnin key.

Deterministic Signature Serialization:

For cryptographic signature verification to work reliably, implementations MUST use canonical JSON serialization when signing and verifying the first message payload. This is critical because:

• Standard JSON.stringify() does not guarantee property order across different JavaScript engines or implementations
• Property order differences between signing and verification would cause signature verification to fail
• Canonical JSON ensures the exact same string is generated for signing and verification

Canonical JSON Requirements:

1. All object keys MUST be sorted alphabetically
2. Nested objects and arrays MUST be recursively canonicalized
3. No whitespace between elements (compact representation)
4. The same object MUST always produce the identical string representation

Example Implementation Pattern:

function canonicalJSON(obj) {
  if (obj === null || typeof obj !== 'object') {
    return JSON.stringify(obj);
  }
  if (Array.isArray(obj)) {
    return '[' + obj.map(item => canonicalJSON(item)).join(',') + ']';
  }
  const sortedKeys = Object.keys(obj).sort();
  const pairs = sortedKeys.map(key => {
    return JSON.stringify(key) + ':' + canonicalJSON(obj[key]);
  });
  return '{' + pairs.join(',') + '}';
}

Implementations in other languages MUST follow the same canonicalization rules to ensure interoperability.

Message Privacy:

• All message content MUST be encrypted before submission to HCS
• Public keys are intentionally public for sender discovery
• Message metadata (sender account ID, timestamp, size) is visible on-chain
• Implementations SHOULD warn users about metadata visibility

Key Management:

• Private keys MUST be stored securely (encrypted at rest recommended for RSA keys)
• Key rotation requires creating a new message box; old boxes remain accessible with original keys

ED25519 Limitation:

• ED25519 accounts cannot use ECIES (no ECDH support)
• Implementations MUST fallback to RSA or fail with clear error message

Backwards Compatibility

This HIP is fully backward compatible:

• Uses existing HCS functionality with no protocol changes
• Account memo is optional and does not affect non-participating accounts
• Applications without message box support simply ignore the memo format
• Existing tools and wallets continue to function normally
• No changes required to Hiero nodes, Mirror Nodes, or core services

Accounts without a message box in their memo are unaffected and can continue using their memo field for any purpose.

Security Implications

Positive Security Impacts

1. Decentralized Communication: Removes reliance on centralized message servers that can censored
2. End-to-End Encryption: Messages are encrypted client-side before touching the network
3. Immutable Audit Trail: All messages are recorded on-chain with consensus timestamps
4. No Private Key Exposure: Private keys never leave the user’s device

Potential Security Risks

1. Metadata Leakage: Message sender, timestamp, and size are public (inherent to HCS)
   • Mitigation: User awareness; applications can add timing obfuscation and clearly labelled fake payloads for sensitive use cases
2. Spam/DOS: Anyone can send messages to a published message box
   • Mitigation: HCS fees provide economic barrier; client-side filtering (blocklists, allowlists, rate limiting); HIP-991 topics.
3. Key Compromise: Stolen private keys can decrypt messages
   • Mitigation: Secure key storage;

Best Practices

• Store private keys encrypted at rest
• Implement client-side sender filtering
• Warn users that metadata (sender, timing, size) is public

How to Teach This

For End Users

Concept Introduction: “A message box is like a mailbox for your Hiero account. Just like a physical mailbox, you can tell people your mailbox address (your message box topic ID), and they can send you messages there. The messages are encrypted so only you can read them.”

Key Points:

1. Message boxes are optional - you choose to set one up
2. Your message box address goes in your account memo
3. Anyone can send you encrypted messages if they know your message box address
4. You need your private key to read messages

For Developers

Quick Start Guide:

1. Setting Up a Message Box:
   • Generate RSA or ECIES key pair
   • Create HCS topic
   • Publish public key as first message
   • Update account memo with topic ID [HIP-1334:]
2. Sending Messages:
   • Query account memo to find the topic ID
   • Fetch public key from the first message of the topic
   • Encrypt message following the recipeint’s specifications
   • Submit to HCS
3. Receiving Messages:
   • Poll Mirror Node for new messages
   • Decrypt with private key
   • Display to user

Integration Patterns:

• Wallet Integration: Built-in message viewing in wallet UI
• dApp Notifications: Send transaction confirmations to user message boxes
• Service Alerts: Notify users of security events or updates
• P2P Messaging: Enable encrypted communication between accounts

For Wallet Developers

Implementation Checklist:

• Add message box setup flow in wallet UI
• Generate a new private key with HD wallet for the message box
• Store encryption key securely
• Display message box address in account details
• Add “Messages” tab with inbox view
• Implement background polling for new messages
• Show message notifications to users
• Allow users to send messages to other accounts
• Support both RSA and ECIES encryption

Documentation Structure

1. Overview: What is a message box and why use it?
2. Quick Start: Get your first message box running in 5 minutes
3. User Guide: How to send and receive messages
4. Developer Guide: Integrate message boxes into your application
5. Security Guide: Best practices for key management and privacy
6. API Reference: Complete specification of message formats
7. Examples: Sample code in multiple languages

Reference Implementation

A complete reference implementation is available at https://github.com/InternetOfPeers/hiero-message-box.

The implementation fully demonstrates all aspects of this specification and serves as a working example for developers.

Key Components

1. Message Box Library (src/lib/message-box.js):
   • Complete message box setup and removal functionality
   • Two-key system support (payer and owner separation)
   • Cryptographic signature generation for ownership proof
   • Signature verification before sending messages
   • Encrypted message sending with format selection (JSON/CBOR)
   • Real-time message polling and historical retrieval
   • Key pair management for both RSA and ECIES modes
   • Automatic encryption type detection and routing
   • Canonical JSON serialization for deterministic signatures
2. Encryption Library (src/lib/crypto.js):
   • RSA-2048 hybrid encryption/decryption (AES-256-CBC + RSA-OAEP)
   • ECIES encryption/decryption (ECDH + AES-256-GCM)
   • Custom CBOR encoder/decoder (RFC 8949 compliant)
   • Automatic format detection (JSON/CBOR/plaintext)
   • Encryption type detection and validation
   • Message signing and signature verification (ED25519, ECDSA_SECP256K1)
   • DER encoding helpers for cryptographic keys
3. Hedera Integration (src/lib/hedera.js):
   • Client initialization for testnet and mainnet
   • Account memo read via Mirror Node and update via HCS
   • Account public key retrieval from Mirror Node API
   • Topic creation and message submission
   • Complete Mirror Node API integration with message chunking support
   • Hiero key parsing and public key derivation (secp256k1, ED25519)
   • Transaction execution and signing helpers
4. Command-Line Tools:
   • setup-message-box.js: Complete setup flow with key generation/verification
   • send-message.js: Send encrypted messages with JSON/CBOR format selection
   • check-messages.js: Historical message retrieval with sequence range support
   • listen-for-new-messages.js: Real-time message listener with 3-second polling
   • remove-message-box.js: Message box removal

Test Coverage

The reference implementation has been extensively tested on Hedera testnet with:

• Encryption modes: Both RSA and ECIES successfully tested
• Message formats: JSON and CBOR encoding verified
• Key types: ED25519 and secp256k1 account keys tested
• Message sizes: Small messages and large messages requiring HCS chunking
• Error handling: Invalid keys, missing message boxes, corrupted messages

Technical Requirements

• SDK: Hashgraph SDK v2.76.0 or higher
• Runtime: Node.js v14+ (v18+ recommended for optimal compatibility)
• Crypto: Native Node.js crypto module only (no external dependencies)
• Network: Compatible with Hedera testnet and mainnet
• Mirror Node: Works with all standard Hiero Mirror Node implementations

Code Quality

• Modular architecture with clear separation of concerns
• Comprehensive error handling and user-friendly error messages
• Extensive inline documentation
• Minimal external dependencies (only Hashgraph SDK)

Documentation

The repository includes:

• Complete README with setup instructions
• Interactive HTML presentation visualizing the message box flow
• Code examples for all operations
• Environment configuration templates

Rejected Ideas

Standardized Sender Authentication

The current specification does not include sender authentication and consider the transaction payer as the message sender. Future HIPs can define a standard for:

• Message signing with sender’s Hiero key
• Verification process for recipients
• Optional vs. mandatory authentication

In the meanwhile, sender authentication is left to application-specific implementations embedded in the encrypted message.

Spam Prevention Mechanisms

Rejection Reason: While message boxes are permissionless by design, spam prevention is left to client-side implementation. HCS fees provide basic economic barriers. Applications can implement filtering (blocklists, allowlists, rate limiting) without protocol changes. Blocking at the protocol level would undermine the decentralized nature of this specification.

Note: This specification does not require use of permissionless, revenue-generating Topic IDs as described in HIP-991, but users may choose this option if desired.

Multiple Encryption Schemes per Message Box

Idea: Allow a single message box to accept messages encrypted with different schemes simultaneously.

Rejection Reason: This complicates the specification and increases implementation complexity. Users who need multiple encryption schemes can create separate message boxes for each use case.

Support for ED25519 in ECIES

Rejection Reason: ED25519 is a signature algorithm based on twisted Edwards curves and does not support ECDH (Elliptic Curve Diffie-Hellman) key exchange, which is fundamental to ECIES. This is a cryptographic incompatibility, not a design choice. The RSA encryption option fully supports ED25519 accounts.

Open Issues

No open issue.

References

• Hedera Consensus Service (HCS) Documentation
• Hedera Mirror Node REST API
• Hedera Account Service
• RSA-OAEP Encryption Standard (RFC 8017)
• Elliptic Curve Integrated Encryption Scheme (ECIES)
• AES-256 Encryption Standard (FIPS 197)
• secp256k1 Elliptic Curve Parameters
• CBOR Specification (RFC 8949)
• Node.js Crypto Module Documentation
• Hashgraph SDK Documentation

Copyright/License

This document is licensed under the Apache License, Version 2.0 — see LICENSE or https://www.apache.org/licenses/LICENSE-2.0.

Citation

Please cite this document as: