Arbitrary Message System Operations

Decrypt From

Decrypt an AES-encrypted message.

Request:

• requestType is decryptFrom

• secretPhrase is the secret passphrase of the recipient

• account is the account ID of the recipient

• data is AES-encrypted data

• nonce is the unique nonce associated with the encrypted data

• decryptedMessageIsText is false if the decrypted message is a hex string, otherwise the decrypted message is text (optional)

• uncompressDecryptedMessage is false to prevent gzip uncompression after decryption (optional)

Response:

• decryptedMessage (S) is the decrypted message

• requestProcessingTime (N) is the API request processing time (in millisec)

Example: Refer to Decrypt From example.

Download Prunable Message

Downloadins a prunable message attachments directly as binary data. An optional secretPhrase parameter is supported, to allow decryption and downloading of the encrypted part of the message instead of the plain text part.

Request:

• requestType is downloadPrunableMessage

• transaction is the transaction ID

• secretPhrase is the secret passphrase used to decrypt the encrypted part of the message (optional)

• sharedKey is the shared key used to decrypt the message (optional) (see Get Shared Key)
• retrieve is true to retrieve the message from achival node if needed (optional)

• requireBlock is theblock ID of a block that must be present in the blockchain during execution (optional)

• requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response: The prunable data as a binary file.

Example: Refer to Download Prunable Message example.

Encrypt To

Encrypt a message using AES without sending it.

Request:

• requestType is encryptTo

• secretPhrase is the secret passphrase of the sender

• recipient is the account ID of the recipient

• messageToEncrypt is either UTF-8 text or a string of hex digits to be compressed and converted into a 1000 byte maximum bytecode then encrypted using AES

• messageToEncryptIsText is false if the message to encrypt is a hex string, otherwise the message to encrypt is text (optional)

• compressMessageToEncrypt is false to prevent gzip compression before encryption (optional)

Response:

• data (S) is the AES-encrypted data

• nonce (S) is a 32-byte pseudorandom nonce

• requestProcessingTime (N) is the API request processing time (in millisec)

Example: Refer to Encrypt To example.

Get All Prunable Messages

Get all available prunable messages in reverse block timestamp order.

Request:

• requestType is getAllPrunableMessages

• timestamp is the earliest message (in seconds since the genesis block) to retrieve (optional)

• firstIndex is a zero-based index to the first prunable message to retrieve (optional)

• lastIndex is a zero-based index to the last prunable message to retrieve (optional)

• requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)

• requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

• prunableMessages (A) is an array of prunable messages (refer to Get Prunable Message)
• lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)

• requestProcessingTime (N) is the API request processing time (in millsec)

Example: Refer to Get All Prunable Messages example.

Get Prunable Message

Get the prunable message given a transaction ID, optionally decrypting it if encrypted and if a secretPhrase is provided, if it is still available.

Request:

• requestType is getPrunableMessage

• transaction is the transaction ID

• secretPhrase is the secret phrase needed for decryption (optional)

• sharedKey is the shared key used to decrypt the message (optional) (see Get Shared Key)
• retrieve is true to retrieve pruned data from other nodes if not available (optional)

• requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)

• requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

• sender (S) is the sender account number

• senderRS (S) is the Reed-Solomon address of the sender account

• recipient (S) is the recipient account number

• recipientRS (S) is the Reed-Solomon address of the recipient account

• message (S) is the plain message text

• messageIsText (B) is true if the plain message is text, false if it is a hex string

• encryptedMessage (O) is the encrypted message object, containing data (S) and nonce (S) fields

• encryptedMessageIsText (B) is true if the encrypted message is text, false if it is a hex string

• decryptedMessage (S) is the decrypted and decompressed (if necessary) encrypted message, if applicable and if secretPhrase is provided

• isCompressed (B) is true if the encrypted message was compressed before encryption, if applicable

• transaction (S) is the transaction ID

• transactionTimestamp (N) is the transaction timestamp (in seconds since the genesis block)

• blockTimestamp (N) is the block timestamp (in seconds since the genesis block)

• lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)

• requestProcessingTime (N) is the API request processing time (in millsec)

Example: Refer to Get Prunable Message example.

Get Prunable Messages

Get all still-available prunable messages given an account id, optionally limiting to only those with another account as recipient or sender, in reverse chronological order.

Request:

• requestType is getPrunableMessages

• account is the account ID

• otherAccount is another account ID, either sender or recipient, to limit the response

• secretPhrase is the secret phrase needed for decryption (optional)

• timestamp is the earliest prunable message (in seconds since the genesis block) to retrieve (optional)

• firstIndex is a zero-based index to the first prunable message to retrieve (optional)

• lastIndex is a zero-based index to the last prunable message to retrieve (optional)

• requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)

• requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

• prunableMessages (A) is an array of prunable message objects (refer to Get Prunable Message for details)
• lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)

• requestProcessingTime (N) is the API request processing time (in millsec)

Example: Refer to Get Prunable Messages example.

Get Shared Key

Get the one-time shared key used for encryption of messages.

Request:

• requestType is getSharedKey

• account is the recipient account ID

• secretPhrase is the secret phrase of the sender

• nonce is the 32-byte pseudorandom nonce

Response:

• sharedKey (S) is shared key as a hexadecimal string

• requestProcessingTime (N) is the API request processing time (in millisec)

Example: Refer to Get Shared Key example.

Read Message

Get a message given a transaction ID.

Request:

• requestType is readMessage

• transaction is the transaction ID of the message

• secretPhrase is the secret passphrase of the account that received the message (optional)

• sharedKey is the shared key used to decrypt the message (optional) (see Get Shared Key)
• retrieve is true to retrieve pruned data from archival nodes (optional)

• requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)

• requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

• messageIsPrunable (B) is true if there is a plain message and it is prunable, false if it is not prunable

• message (S) is the plain message, if applicable

• encryptedMessageIsPrunable (B) is true if there is an encrypted message and it is prunable, false if it is not prunable

• decryptedMessage (S) is the decrypted message, if applicable and only if the provided secretPhrase belongs to either the sender or receiver of the transaction

• decryptedMessageToSelf (S) is the decrypted message sent to self, if applicable and only if the provided secretPhrase belongs to the sender of transaction

• lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)

• requestProcessingTime (N) is the API request processing time (in millisec)

Example: Refer to Read Message example.

Send Message

Create an Arbitrary Message transaction. POST only.

Request: Refer to Create Transaction Request for common parameters.

• requestType is sendMessage

• recipient is the account ID of the recipient (optional)

• recipientPublicKey is the public key of the receiving account (optional, enhances security of a new account)

• message is either UTF-8 text or a string of hex digits (perhaps previously encoded using an arbitrary algorithm) to be converted into a bytecode with a maximum length of one kilobyte, 42 kilobytes if prunable (optional)

• messageIsText is false if the message is a hex string, otherwise the message is text (optional)

• messageIsPrunable is true if the message is prunable (optional)

• messageToEncrypt is either UTF-8 text or a string of hex digits to be compressed (unless compressMessageToEncrypt is false) and converted into a bytecode with a maximum length of one kilobyte, 42 kilobytes if prunable, then encrypted using AES (optional)

• messageToEncryptIsText is false if the message to encrypt is a hex string, otherwise the message to encrypt is text (optional)

• encryptedMessageData is already encrypted data which overrides messageToEncrypt if provided (optional)

• encryptedMessageNonce is a unique 32-byte number which cannot be reused (optional unless encryptedMessageData is provided)

• encryptedMessageIsPrunable is true if the encrypted message is prunable (optional)

• compressMessageToEncrypt is false to prevent gzip compression before encryption (optional)

• messageToEncryptToSelf is either UTF-8 text or a string of hex digits to be compressed (unless compressMessageToEncryptToSelf is false) and converted into a one kilobyte maximum bytecode then encrypted with AES, then sent to the sending account (optional)

• messageToEncryptToSelfIsText is false if the message to self-encrypt is a hex string, otherwise the message to encrypt is text (optional)

• encryptToSelfMessageData is already encrypted data which overrides messageToEncryptToSelf if provided (optional)

• encryptToSelfMessageNonce is a unique 32-byte number which cannot be reused (optional unless encryptToSelfMessageData is provided)

• compressMessageToEncryptToSelf is false to prevent gzip compression before encryption (optional)

Note: Any combination (including none or all) of the three options plain message, messageToEncrypt, and messageToEncryptToSelf will be included in the transaction. However, one and only one prunable message may be included in a single transaction if there is not already a message of the same type (either plain or encrypted).

Note: The encryptedMessageData-encryptedMessageNonce pair or the encryptToSelfMessageData-encryptToSelfMessageNonce pair can be the output of Encrypt To

Response: Refer to Create Transaction Response.

Example: Refer to Send Message example.

Verify Prunable Message

Verify that a prunable message obtained from any source, when hashed, matches the hash of the original prunable message.

Request: Refer to Send Message for more details about the following request parameters.

• requestType is verifyPrunableMessage

• message is the plain message, if applicable (optional)

• messageIsText is false if the provided plain message is a hex string (optional)

• encryptedMessageData is the data part of the encrypted data-nonce pair (optional if message provided)

• encryptedMessageNonce is the nonce part of the encrypted data-nonce pair (required if encryptedMessageData provided)

• messageToEncryptIsText is false if the encrypted message was a hex string before encryption (optional)

• compressMessageToEncrypt is false if the encrypted message was not compressed before encryption (optional)

• requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)

• requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Note: The hash is computed from the message itself plus its associated flag(s) isText and isCompressed (encrypted only); therefore the flag(s) must be provided for verification if different from the default(s). The original encryptedMessageData-encryptedMessageNonce pair used to compute the original hash must be provided again to recompute the hash for verification of a prunable encrypted message.

Response:

• version.PrunablePlainMessage or version.PrunableEncryptedMessage (N) is 1, the version number

• verify (B) is true if the original hash matches the hash computed from the provided values

• message (S) or encryptedMessage (O) is the prunable plain message or the prunable encrypted message object containing the fields:

  • data (S)

  • nonce (B)

  • isText (B)

  • isCompressed (B)

• messageIsText (B) is true if the plain message is text, false if it is a hex string, if applicable

• messageHash or encryptedMessageHash (S) is the hash

• lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)

• requestProcessingTime (N) is the API request processing time (in millsec)

Example: Refer to Verify Prunable Message example.