Almonte at 09:40, 12 January 2021

2021-01-12T09:40:10Z

New page

<languages />
<translate>
{{#seo:
|title=Account Setup for Message-based Deposits
|titlemode=replace
|keywords=ardor learning hub, ardor documentation, blockchain, proof of stake, ardor, ignis, jelurida, development, ardor wiki, wiki, tutorials, advanced tutorials, how-to, message-based deposits, prevent users to send tokens without a message
|description=This guide explains how to prevent users from accidentally sending tokens without message setting up the property nrs_recipient_ui_options. It is covered with a step-by-step guide for both configuring the receiving account and to send tokens to the account.
}}
[[Category:Advanced_guides]]

==Introduction==

This guide explains how to configure the account property <code>nrs_recipient_ui_options</code>. 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_Properties|account property]] with name <code>nrs_recipient_ui_options</code>, set by the recipient on itself is used to configure the modal in the [[Introductory_tour_of_ardors_features|Ardor UI]] when sending funds to that account. It also allows control over the message encryption, such as disabling it. The value of the <code>nrs_recipient_ui_options</code> property is a JSON object containing the following fields:

* '''message_format''': [https://en.wikipedia.org/wiki/Regular_expression Regular expression] of the message format which is required when depositing to this address. For instance:
** The expression <code>[0-9]+</code> will only allow a numeric message.
*** For instance: <code>291</code>
** If the message should be of a particular length use the expression as follows: <code>[a-zA-Z0-9]{4,8}</code>.
*** 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 - <code>true</code> is valid value, <code>"true"</code> is not.
* '''encrypt_message_disabled''': if <code>true</code>, the encrypt message box is disabled. Set this to <code>true</code> if you can accept either only encrypted or only unencrypted messages. Must be boolean, not string. If <code>true</code>, the '''encrypt_message''' field must also be set to <code>true</code> or <code>false</code>. Or else the configuration is invalid.

Example of the <code>nrs_recipient_ui_options</code> property:

<syntaxhighlight lang="json">
{"message_format":"[a-zA-Z0-9]{4,8}","encrypt_message":true,"encrypt_message_disabled":true}
</syntaxhighlight>

==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 [[Accounts#Get_Account_Properties|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:

<btn size="sm">https://testardor.jelurida.com/test?requestType=getAccountProperties&property=nrs_recipient_ui_options&setter=ARDOR-S9Q3-GPL9-XLPB-EDW66&recipient=ARDOR-S9Q3-GPL9-XLPB-EDW66|<span class="glyphicon glyphicon-cog"></span> Test Get Account Properties|btn-primary</btn>

<syntaxhighlight lang="bash">
http://localhost:26876/nxt?
requestType=getAccountProperties&property=nrs_recipient_ui_options&
setter=ARDOR-S9Q3-GPL9-XLPB-EDW66&recipient=ARDOR-S9Q3-GPL9-XLPB-EDW66
</syntaxhighlight>

If the account ARDOR-S9Q3-GPL9-XLPB-EDW66 is properly configured for message-based deposits, the result will be something like
<syntaxhighlight lang="json">
{
"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}"
}
]
}
</syntaxhighlight>

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 <code>true</code>, this means that the destination account can accept either only encrypted or only unencrypted messaged. In this case check the '''encrypt_message''' field:
** If <code>true</code>, the account accepts only encrypted messages
** If <code>false</code>, 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 <code>ARDOR-GHKP-XWB5-XMZB-CTUE3</code> for this example. First [[Login_Page_Tutorial|login into the Ardor wallet]] with the account that will receive the funds.

Then click on 'Account Properties':

[[File:Account setup for Message-based deposits - 1.jpg|class=img-responsive|border|Account properties]]

Click on 'Set' as shows the following image:

[[File:Account setup for Message-based deposits - 2.jpg|class=img-responsive|border|Set property]]

Set the values of the account property:
* Recipient account (it must be the same account, in this case, <code>ARDOR-GHKP-XWB5-XMZB-CTUE3</code>
* Property: <code>nrs_recipient_ui_options</code>
* 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

[[File:Account_setup_for_Message-based_deposits_-_3.jpg|class=img-responsive|border|Set property values]]

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 <code>ARDOR-X8ZN-WUJ2-SXY3-FBUYC</code> to send funds to the previously created receiving account of the section above. First [[Login_Page_Tutorial|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 <code>ARDOR-GHKP-XWB5-XMZB-CTUE3</code> already configured.

Click on the "Send IGNIS" button:

[[File:Account setup for Message-based deposits - 4.jpg|class=img-responsive|border|Send IGNIS]]

Fill the recipient account (for this case: <code>ARDOR-GHKP-XWB5-XMZB-CTUE3</code>), 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:

[[File:Account setup for Message-based deposits - 5.jpg|class=img-responsive|border|Preventing users to send funds with a wrong message]]

===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:

[[File:Account setup for Message-based deposits - 6.jpg|class=img-responsive|border|Sending funds with a well-formatted message]]

</translate>

Account Setup for Message-based Deposits - Revision history

Almonte at 09:40, 12 January 2021