Messages
From ArdorDocs
Decrypt From
Decrypt an AES-encrypted message. It can be used either with a secretPhrase or a privateKey (using the HD wallet).
Request:
- requestType is decryptFrom
- secretPhrase (S) is the secret passphrase of the recipient
- privateKey (S) is the privateKey (hex) of the derived account (HD wallet, refer to: Getting the private key from the derived account)
- account is the account ID of the message sender (the account which encrypted the message)
- 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)
Decrypt From Example
http://localhost:27876/nxt?
requestType=decryptFrom&
secretPhrase=IWontTellYou&
account=ARDOR-L6FM-89WK-VK8P-FCRBB&
data=c9ba8713c422e98867137f6166ed39d1758e18bb70492be4777899554dcca7082e5c25d1072f4bcc031add28292e32d097b1f243375c4d3d73e94cb93d37a980&
nonce=940ccec805655c59e69d545f369474a803ee6051fe16f1931b2b03eb1ef2313b
{
"decryptedMessage": "test message",
"requestProcessingTime": 2
}
Download Prunable Message
Downloading 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
- chain is the chain related to the message
- transaction is the transaction ID
- secretPhrase is the secret passphrase used to decrypt the encrypted part of the message (optional)
- privateKey (S) is the privateKey (hex) of the derived account (HD wallet, refer to: Getting the private key from the derived account)
- 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.
Download Prunable Message Example
http://localhost:27876/nxt?
requestType=downloadPrunableMessage&
chain=2&
transaction=264609232955144528&
retrieve=true
Response: The file in binary format.
Encrypt To
Encrypt a message using AES without sending it.
Request:
- requestType is encryptTo
- secretPhrase is the secret passphrase of the sender
- privateKey (S) is the privateKey (hex) of the derived account (HD wallet, refer to: Getting the private key from the derived account)
- 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)
Encrypt To Example
http://localhost:27876/nxt?
requestType=encryptTo&
secretPhrase=IWontTellYou&
recipient=ARDOR-L6FM-89WK-VK8P-FCRBB&
messageToEncrypt=test message
{
"data": "c9ba8713c422e98867137f6166ed39d1758e18bb70492be4777899554dcca7082e5c25d1072f4bcc031add28292e32d097b1f243375c4d3d73e94cb93d37a980",
"requestProcessingTime": 48,
"nonce": "940ccec805655c59e69d545f369474a803ee6051fe16f1931b2b03eb1ef2313b"
}
Get All Prunable Messages
Get all available prunable messages in reverse block timestamp order.
Request:
- requestType is getAllPrunableMessages
- chain is the chain related to the messages
- 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)
Get All Prunable Messages Example
http://localhost:27876/nxt?
requestType=getAllPrunableMessages&
chain=2&
lastIndex=0
{
"prunableMessages": [
{
"senderRS": "ARDOR-4VDY-LNVT-LMAY-FMCKA",
"sender": "15295723609781267838",
"recipientRS": "ARDOR-BMUV-8QQR-47VK-CR7F3",
"recipient": "11580081983047651163",
"blockTimestamp": 46382992,
"message": "This is a test prunable plain message.",
"transaction": "4628485271017409467",
"isText": true,
"transactionTimestamp": 46382948
}
],
"requestProcessingTime": 0
}
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
- chain is the chain related to the message
- transactionFullHash is the transaction Full Hash
- secretPhrase is the secret phrase needed for decryption (optional)
- privateKey (S) is the privateKey (hex) of the derived account (HD wallet, refer to: Getting the private key from the derived account)
- 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)
Get Prunable Message Example
http://localhost:27876/nxt?
requestType=getPrunableMessage&
chain=2&
transaction=16832262845403902696&
secretPhrase=secretPhrase
{
"senderRS": "ARDOR-4VDY-LNVT-LMAY-FMCKA",
"encryptedMessage": {
"data": "ba6baa8361ac5bdb9cb591cee616dc5801a32ddf05b66a4ee527cd8d57b0...",
"nonce": "41f93e32997c70937a005e5b0b42546a1efa9ea9eb012f98d7a92d0c5a8855a4"
},
"sender": "15295723609781267838",
"decryptedMessage": "test prunable encrypted message",
"recipientRS": "ARDOR-BMUV-8QQR-47VK-CR7F3",
"recipient": "11580081983047651163",
"blockTimestamp": 46117919,
"requestProcessingTime": 3,
"transaction": "16832262845403902696",
"encryptedMessageIsText": true,
"transactionTimestamp": 46117594,
"isCompressed": true
}
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
- chain is the chain related to the messages
- 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)
- privateKey (S) is the privateKey (hex) of the derived account (HD wallet, refer to: Getting the private key from the derived account) (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)
Get Prunable Messages Example
http://localhost:27876/nxt?
requestType=getPrunableMessages&
chain=2&
account=ARDOR-4VDY-LNVT-LMAY-FMCKA&
lastIndex=0
{
"prunableMessages": [
{
"senderRS": "ARDOR-4VDY-LNVT-LMAY-FMCKA",
"encryptedMessage": {
"data": "ba6baa8361ac5bdb9cb591cee616dc5801a32ddf05b66a4ee527cd8d57b0a...",
"nonce": "41f93e32997c70937a005e5b0b42546a1efa9ea9eb012f98d7a92d0c5a8855a4"
},
"sender": "15295723609781267838",
"recipientRS": "ARDOR-BMUV-8QQR-47VK-CR7F3",
"recipient": "11580081983047651163",
"blockTimestamp": 46117919,
"transaction": "16832262845403902696",
"isText": true,
"transactionTimestamp": 46117594,
"isCompressed": true
}
],
"requestProcessingTime": 1
}
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
- privateKey (S) is the privateKey (hex) of the derived account (HD wallet, refer to: Getting the private key from the derived account)
- 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)
http://localhost:27876/nxt?
requestType=getSharedKey&
account=ARDOR-5MYN-AP7M-NKMH-CRQJZ&
secretPhrase=IWontTellYou&
nonce=0102030405060708091011121314151617181920212223242526272829303132
{
"sharedKey": "927118faa4850afa7fb3ced7b17eb4968ec4f1c0a405b0890552bb54a67d0eba",
"requestProcessingTime": 1
}
Read Message
Get a message given a transaction ID.
Request:
- requestType is readMessage
- chain is the chain related to the message
- transaction is the transaction ID of the message
- secretPhrase is the secret passphrase of the account that received the message (optional)
- privateKey (S) is the privateKey (hex) of the derived account (HD wallet, refer to: Getting the private key from the derived account)
- 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)
Read Message Example
http://localhost:27876/nxt?
requestType=readMessage&
chain=2&
transaction=9908575668289607167&
secretPhrase=IWontTellYou
{
"requestProcessingTime": 1,
"message": "Test message.",
"decryptedMessage": "Test message (encrypted).",
"decryptedMessageToSelf": "abc123"
}
Send Message
Create an Arbitrary Message transaction. POST only.
Request: Refer to Create Transaction Request for common parameters.
- requestType is sendMessage
- chain is the chain for the message to be sent
- 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.
Send Message Example
http://localhost:27876/nxt?
requestType=sendMessage&
chain=2&
secretPhrase=IWontTellYou&
recipient=ARDOR-4VNQ-RWZC-4WWQ-GVM8S&
message=Test Message.&
deadline=60
{
"signatureHash": "795c58938a50d691f3f2b88bfaf03267236e972e1c068e0a5e11aeb606597f17",
"unsignedTransactionBytes": "01100593ce013c0057fb6f3a958e320bb49c4e81b4c2cf28b9f25d086c14...",
"transactionJSON": {
"senderPublicKey": "57fb6f3a958e320bb49c4e81b4c2cf28b9f25d086c143b473beec228f79ff93c",
"chain": 2,
"signature": "e916dbbfec51ca97ae76b1b190d1c74328f74c3c43ed3a06f1ca0ea250116...",
"feeNQT": "100000000",
"type": 1,
"fullHash": "ff157b8a125582898b5c50d32a62f725602d5197af236fabcd6ec978b6861528",
"version": 1,
"ecBlockId": "6060075251340574063",
"signatureHash": "795c58938a50d691f3f2b88bfaf03267236e972e1c068e0a5e11aeb606597f17",
"attachment": {
"version.Message": 1,
"messageIsText": true,
"message": "Test message."
},
"senderRS": "ARDOR-L6FM-89WK-VK8P-FCRBB",
"subtype": 0,
"amountNQT": "0",
"sender": "15323192282528158131",
"recipientRS": "ARDOR-4VNQ-RWZC-4WWQ-GVM8S",
"recipient": "17013046603665206934",
"ecBlockHeight": 280756,
"deadline": 60,
"transaction": "9908575668289607167",
"timestamp": 30315269,
"height": 2147483647
},
"broadcasted": true,
"requestProcessingTime": 11379,
"transactionBytes": "01100593ce013c0057fb6f3a958e320bb49c4e81b4c2cf28b9f25d086c143b...",
"fullHash": "ff157b8a125582898b5c50d32a62f725602d5197af236fabcd6ec978b6861528",
"transaction": "9908575668289607167"
}
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
- chain is the chain for the message to be verified
- 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)
Verify Prunable Message Example
http://localhost:27876/nxt?
requestType=verifyPrunableMessage&
chain=2&
message=This is a test prunable plain message.
{
"version.PrunablePlainMessage": 1,
"verify": true,
"messageIsText": true,
"messageHash": "da99da8026e30d971340ef54803543af3aa48ea215f80bd9375457bad8effb3f",
"requestProcessingTime": 1,
"message": "This is a test prunable plain message."
}
