Account Setup for Message-based Deposits

This page contains changes which are not marked for translation.

Introduction

This guide explains how to configure the account property nrs_recipient_ui_options. It prevents users from accidentally sending tokens without a message to the account that has the property set up.

Decentralized applications that require a message to process the funds received, or any other use case that accepts message-based deposits should enable this functionality to prevent errors.

The guide explains the configuration of the account that will require the message-based deposit as well as the end-user steps to send funds.

nrs_recipient_ui_options property configuration

The account property with name nrs_recipient_ui_options, set by the recipient on itself is used to configure the modal in the Ardor UI when sending funds to that account. It also allows control over the message encryption, such as disabling it. The value of the nrs_recipient_ui_options property is a JSON object containing the following fields:

message_format: Regular expression of the message format which is required when depositing to this address. For instance:
- The expression [0-9]+ will only allow a numeric message.
  - For instance: 291
- If the message should be of a particular length use the expression as follows: [a-zA-Z0-9]{4,8}.
  - This format will only allow alphanumeric messages with length 4 to 8 characters.
- Note that the regular expression is case sensitive.
encrypt_message: default value for the encrypt message box. Must be boolean, not string - true is valid value, "true" is not.
encrypt_message_disabled: if true, the encrypt message box is disabled. Set this to true if you can accept either only encrypted or only unencrypted messages. Must be boolean, not string. If true, the encrypt_message field must also be set to true or false. Or else the configuration is invalid.

Example of the nrs_recipient_ui_options property:

{"message_format":"[a-zA-Z0-9]{4,8}","encrypt_message":true,"encrypt_message_disabled":true}

Checking the nrs_recipient_ui_options property

Applications that implement withdrawal of funds to user's account (like exchanges) should respect the nrs_recipient_ui_options property similarly to the Ardor UI - in order to protect the user from withdrawing funds to account owned by some other service which requires a message.

To get the property, use the Get Account Properties API with parameters

setter: the account to which the user wants to withdraw funds
recipient: again the account to which the user wants to withdraw funds. This parameter should be equal to the setter parameter because the nrs_recipient_ui_options property must be set by the account on itself.
property: the string "nrs_recipient_ui_options"

Example:

Test Get Account Properties

http://localhost:26876/nxt?
   requestType=getAccountProperties&property=nrs_recipient_ui_options&
   setter=ARDOR-S9Q3-GPL9-XLPB-EDW66&recipient=ARDOR-S9Q3-GPL9-XLPB-EDW66

If the account ARDOR-S9Q3-GPL9-XLPB-EDW66 is properly configured for message-based deposits, the result will be something like

{
  "setterRS": "ARDOR-S9Q3-GPL9-XLPB-EDW66",
  "recipientRS": "ARDOR-S9Q3-GPL9-XLPB-EDW66",
  "recipient": "13984674604228812481",
  "requestProcessingTime": 0,
  "setter": "13984674604228812481",
  "properties": [
    {
      "property": "nrs_recipient_ui_options",
      "value": "{\"message_format\":\"[0-9]+\",\"encrypt_message\":true,\"encrypt_message_disabled\":true}"
    }
  ]
}

If it is a regular account, not configured for message-based deposits, the properties array will be empty.

The properties array cannot contain more than 1 element for this request. If not empty, get the only element and then get the value field. It should be a string. Parse it as JSON object. If the parsing failed, consider this a regular account. If the parsing succeeded:

Get the message_format field of the parsed object:
- If not present, consider this a regular account.
- If message_format is present in the object, check if the message which the user entered is matched by this regular expression. If your UI doesn't allow the user to enter message, block the withdrawal and show an explanatory error message to the user.

Get the encrypt_message_disabled field. If true, this means that the destination account can accept either only encrypted or only unencrypted messaged. In this case check the encrypt_message field:
- If true, the account accepts only encrypted messages
- If false, the account accepts only unencrypted messages
- Anything else: the account is not properly configured - consider that it is a regular account

Step-by-step configuration of the receiving account

It will be used the Ardor account ARDOR-GHKP-XWB5-XMZB-CTUE3 for this example. First login into the Ardor wallet with the account that will receive the funds.

Then click on 'Account Properties':

Click on 'Set' as shows the following image:

Set the values of the account property:

Recipient account (it must be the same account, in this case, ARDOR-GHKP-XWB5-XMZB-CTUE3
Property: nrs_recipient_ui_options
Value: The JSON message. In this case the values of the fields are
- message_format: [a-zA-Z0-9]{4,8}
- encrypt_message: true
- encrypt_message_disabled: false

Once the transaction is bundled, the account property will appear in the "Incoming" properties. It can be updated or deleted if needed.

The receiving account is now already configured. When sending funds it will check the correctness of the message format and will automatically enable the message encryption. Refer to the next section to see how to send funds to the receiving account.

Sending funds to the receiving account

It will be used the Ardor account ARDOR-X8ZN-WUJ2-SXY3-FBUYC to send funds to the previously created receiving account of the section above. First login into the Ardor wallet with the account that will send the funds.

It is possible to send any token, in this guide we will send IGNIS tokens to the ARDOR-GHKP-XWB5-XMZB-CTUE3 already configured.

Click on the "Send IGNIS" button:

Fill the recipient account (for this case: ARDOR-GHKP-XWB5-XMZB-CTUE3), the amount, and the message.

Error when sending funds due to bad-formatted message

When the message does not fit the regular expression set up in the recipient account, it will disable the "Submit" button and will be prompted a message as follows:

Sending funds with well-formatted message

When the message is well-formatted it will allow sending funds to the recipient account as the following image shows:

Navigation menu