Skip to content

Latest commit

 

History

History
1115 lines (963 loc) · 65.3 KB

fip-0024.md

File metadata and controls

1115 lines (963 loc) · 65.3 KB
Raw
fip title status type author created updated
24
Secure message standard
draft
standard
w-canvas
2021-01-10
2021-01-19

Abstract

This Fip introduces a standard for private communication between wallets without broadcasting the transaction to the fio blockchain.

Terminology

  • Sender - user sending a message.
  • Recipient - user receiving a message.
  • Message - information or request the sender submits to the recipient.
  • Wallet - software following a user's instructions.
  • Location - address of the inbox used to reach the recipient's wallet. May be an ip address, url, onion address or other form of unique location identifier.
  • Fixed server - a system that is continuously running and connected to the internet with a fixed domain, ip address or tor address.
  • Public address - public address in a native blockchain.

Motivation

Currently, the fio protocol doesn't have a truly private communication system. Standardizing a direct messaging protocol that minimizes the use of the blockchain will increase privacy and reduce per user space consumption on the fio network.

Specification

A standard will be defined to interchange private encrypted information.

Methodology

To exchange information with the holder of a fio address, the sender's wallet will fetch an inbox location and the fio public key registered to that fio address using the /get_pub_address call (or an otherwise defined request call with that purpose). Then it will encrypt a signed message using a shared secret derived with the Diffie Hellman protocol (ECDH with AES-256-CBC) and submit it to the supplied location.

The recipient's wallet will respond using the same method.

Inbox location

As most wallets aren't regularly available on a managed uninterrupted network, a fixed server (personal, borrowed or rented) might be used as relay for local mobile and desktop wallets, the same way smartphones exchange emails using smtp servers.

Message construction

All messages will include an encrypted blob and information on how to interpret it.

In order to protect the user's privacy from third parties, all recognizable identification data in the message will be encrypted. The sender is, instead, identified by a token previously assigned by the recipient in a previous message.

Body parameters

Parameter Required Format Definition
protocol Yes String Marks the message as a fio standard direct message.
version Yes String Version of the standard used by the sender.
id_token Yes String - min 8 char max 64 char permitted: [a-Z] [0-9] . - _ + Token used by the receiver to identify the sender and decode the message with the correct shared secret. This token is assigned by the receiver on a previous message.
content Yes String Encrypted exchanged information. See below.

Content

Parameter Required Format Definition
Data Yes String Information to be sent to recipient.
Signature Yes String Sender's authentication signature of "data" field contents.

Data

Parameter Required Format Definition
action Yes String Description of the information being sent or requested.
message_id Yes String - min 1 char max 64 char permitted: [a-Z] [0-9] . - _ + Number used to identify and address the message. Must change for every message.
referenced_message_id When responding or updating a message String - min 1 char max 64 char permitted: [a-Z] [0-9] . - _ + message_number of the message being responded or referenced. Used to reference received messages. Same value may be used multiple times.
sender_fio_address Yes String Fio address of the sender.
recipient_fio_address Yes String Fio address of the recipient.
return_address No String Location of inbox to be used to respond the message.
return_address_type No String Type of address mentioned in return_address.
return_id_token When establishing communication for the first time String - min 8 char max 64 char permitted: [a-Z] [0-9] . - _ + Random string generated by the sender. The recipient will use it to identify himself on future messages. Must be different from id_token and tokens sent to other users.
payee_public_address When requesting funds or releasing public address String Blockchain native public address of the payee.
chain_code When requesting funds or public address String Code that identifies the blockchain (network) used to execute the payment.
token_code When requesting funds or public address String Code that identifies the token (currency) that will be used to pay.
amount When requesting funds String Amount to be paid. May be left empty for the recipient to choose an amount.
memo No String Textual description of the transaction. Freely chosen by the user.
message_status When responding a message String Status of a received message (success or error code).
hash No String Hash of the data not sent on the message.
offline_url No String Url of data that wasn't sent on the message.

Example

Message body
{
    "protocol": "fio_dm",
    "version": "1.0",
    "id_token": "P-cad58ccd38533479",
    "content": "53616c7465645f5f7634136af11def498242ffe9db2c55753d00efacaaad82f2b1d05990f1d8223deb95679e074c84c2b67161027762e8f91b3f989ec86c7c51716e027a551e091583efec77add534d6e344d439a3787dc227a5417b0a7741a0a0e46da9926b8640c8a400b7a37fbe19493dd82bb40e07507b3193baa92b17bf76a12473058d675b21ca0e24ae844fac4cca5c1438ee4273b0fc959bd09a6fa1a90051abd143b4ecb07b38605255f97e0990eeb52f11663b58e7d97ad7f0f80b2f461ea8949ecea5aa9057b8e9f0f6eb20c47446318b583fa7d444a755b79ea0de73d3859c564b4ce9e988c707ca80d26d9dfb37b55e14021f4717b88b975eff9fbc088525cb19009d2788e515eb54d2b5696ea2b21a1b18103c39c83f4cd2447662c3cc6645f3ddd992a798a8e4b75454ca49ca31943a7bc107785d60a1c726b8ed1682c0017d7efa3ee07a772adb934bfc2ff4595b4455803a7d93010b54fe735c51e5eef33b1b11a83dca100b14f098a4902930f19f892557a92fdc19bc84f767105dcd23eadd8f70c47821005429c2b3d174f339b5a4b8f484b922701e35042c16b3434f0d335f1a8d7e29d3c45385d08ad0ec821ab639466718623f2de6deb5a30fc1831500cee309dd69960a7e6f87d89938c091a49ce4acc5bf0343b02eaffc689cedf644b9ab8e7588c6f1e6e1b52b0fd91d673dd4cf4c527ca7877b"
}
Content (before encrypting)
{
    "data": {
        "action": "peer_new_funds_request",
        "message_id": "000521f",
        "sender_fio_address": "alice@wallet",
        "recipient_fio_address": "bob@wallet",
        "payee_public_address": "",
        "chain_code": "BTC",
        "token_code": "BTC",
        "amount": ".001",
        "memo": "Thank you for your payment."
    },
    "signature": "EsykzHzdXvdQkwS7j4zYvwgVvCMVLPEapwhL9UVeKgrQAMMrTvfhggKyrPLV7CNTpU8UrfMEoFJU3BTmCf4kHGfYXRrYpADXEnFRA"
}
Message emission

Message actions

To facilitate development, secure message actions will be defined in a similar way to fio api endpoints and actions proposed in fip-0008.

Action Description
peer_new_com_request Requests for a communication channel to be established by proving the sender's identity and assigning an identification token to the recipient.
peer_new_funds_request Requests for a payment to be deposited to a specific public address (sends an invoice).
peer_new_pub_address_request Requests the recipient for a public address to deposit funds to.
peer_return_message_status Confirms that a message was received. Informs if message was successfully read by the wallet; returns error code otherwise.
peer_accept_request Informs the recipient that a specific request was accepted and returns the required data.
peer_reject_request Informs the recipient that a specific request will not be executed.
peer_cancel_request Informs the recipient that the sender is no longer interested in the referenced petition.
peer_update_data_request Requests the receiver to change the communication data registered to the sender (e.g.location and id token)
peer_close_com_request Requests recipient to ignore data registered under that communication channel and treat any future contact as new.
peer_send_private_text Sends a private memo.

Opening a communication channel

Before any practical messages can be interchanged, secure communication between the wallets must be established.

Encryption

To establish a channel, sender's wallet must write an initiating message containing the sender's fio address and an identification token. The initiating message must be encrypted asymmetrically with an integrated encryption scheme (ECIES with AES-256-CBC) using the recipient's fio public key and sent to recipient's inbox location.

Having decoded the initiating message, the recipient will be able to use the /get_pub_address call to obtain the senders public key and use it to derive a shared secret for symmetric encryption. This will be used to encrypt all future communications between the two parties.

Generating identity token

After decoding the message, a random string will be generated to identify all messages sent by the same peer.

Storing sender data

The message contents, the derived shared secret, and the id token will be stored unencrypted on a local database under a new communication channel assigned exclusively for that sender-recipient fio address pair.

Responding the message

Depending on the configuration, the wallet might reply with a "message received" status and wait for the user to decide whether to accept or reject the communication request or automatically send a full response.

If the decision to accept the request is taken, the wallet will reply with a confirmation message to communicate the success and send the identification token to be used on the following messages.

Fetching information

To safely communicate with the owner of a fio address, its necessary to acquire the wallet's inbox location and public key. The latter is registered by default as the public address for the fio token under the user's control, and may be obtained as such.

Adding new token

Inbox locations will have to be assigned under new token code standards. Alternatively, a new endpoint could be created for this purpose.

The standard for each type of address will be added to the fip-0015 specification. Address format might also be added to the endpoint error handler.

Example:
chain_code token_code multi_level_parameters name slip_44_index
FIB IPA Inbox IP address
FIB URL Inbox Url
FIB OA3 Inbox onion address V3 
{
  "fio_address": "alice@wallet",
  "public_addresses": [
    {
      "chain_code": "FIB",
      "token_code": "URL",
      "public_address": "172.102.105.111:3030",
    },
    {
      "chain_code": "FIB",
      "token_code": "OA3",
      "public_address": "pymmivd4krv2f07q87oz99kcvn4w4ongj9n70r6fjff75ht46uwnayid.onion:3031",
    }
  ],
  "max_fee": 0,
  "tpid": "dev@wallet",
  "actor": "yfmyo1t2i3fi"
}

Protocol calls

Open new communication channel request

Description:

Requests for a communication channel to be established by proving the sender's identity and assigning an identification token to the recipient.

Endpoint:

peer_new_com_request

Notes:
  • As the communication is being established and no identification tokens have been exchanged, the initiating message must be encrypted asymmetrically with an integrated encryption scheme (ECIES with AES-256-CBC) using the receivers fio public key.
  • The string "NEW" must be used in place of id. This instructs the recipient to decrypt the content with the correct algorithm.
  • If communication is relayed by an external server but the message not successfully decrypted, the sender's identity will not be established and no error codes will be returned to the sender.
  • See the "Opening a communication channel" section for more information on how the first message is constructed.
Body parameters
Parameter Required Format Definition
protocol Yes String Marks the message as a fio standard direct message.
version Yes String Version of the standard used by the sender.
id_token Yes String - min 8 char max 64 char permitted: [a-Z] [0-9] . - _ + Token used by the receiver to identify the sender and decode the message with the correct shared secret. This token is assigned by the receiver on a previous message.
content Yes String Encrypted exchanged information. See below.
Content
Parameter Required Format Definition
Data Yes String Information to be sent to recipient.
Signature Yes String Sender's authentication signature of "data" field contents.
Data
Parameter Required Format Definition
action Yes String Description of the information being sent or requested.
message_id Yes String - min 1 char max 64 char permitted: [a-Z] [0-9] . - _ + Number used to identify and address the message. Must change for every message.
sender_fio_address Yes String Fio address of the sender.
recipient_fio_address Yes String Fio address of the recipient.
return_address No String Location of inbox to be used to respond the message.
return_address_type No String Type of address mentioned in return_address.
return_id_token Yes String - min 8 char max 64 char permitted: [a-Z] [0-9] . - _ + Random string generated by the sender. The recipient will use it to identify himself on future messages. Must be different from id_token and tokens sent to other users.
memo No String Textual description of the transaction. Freely chosen by the user.
hash No String Hash of the data not sent on the message.
offline_url No String Url of data that wasn't sent on the message.

Example

Message body
{
  "protocol": "fio_dm",
  "version": "1.0",
  "id_token": "P-d2d84fe7acd6601c",
  "content": "53616c7465645f5fa97214774070c912868ea90907463a997b954ea2383996e9c469e26f085c1a29c6cd2b2da08601841dcfc16d9fea68d1d52a6eebbfbd52d86c8167a06203a313264de7587ef197db799a261b86ae1ea9810540a0ec7ae31a0407c2c7e7d1e281205f94dc09ce137699e7828d80cc0fcf84654911ab2ac7348552ddcaba99f0bc9ede87e141b93f1c62fa7461d0b70210c1ca8ce2583633c4bc4ad6f527f518d9e2d6f7f0d2af9177b548a2baf349b94388d3af3fad54d1975829407a53a2f76f5c403bcd1b52720ebbbe5cd2491d522da1ffcab49572768a9e4ebc4f191be863b2713e6ce918a28f519bb1c65ab77896446e12cd085cc88083bbade725aaad82410a2f44b01ad98de4a2e4c8238ead9a22952e869bb6d0f0d504e13361b7f428b3010114ae489e9776c2d7d349c16fd8ab71bb5e2fb0742f646d022807a227acca32df5d493c4f053bb55fa631454f16b0be8c3b4fbd8c60de977dcb82147a347a1c7f97b07986e9e14613c010d39d4d6509e94465f2dd20673b75e84d032cdf9cc24b25754e274c7c67b84e1ba0c1cd3b2424b499dd61ffb89b53e6599e435e04702d66199b0c1b2f0232ee59b1625e3319ed63eb2f7928ecf9436179619feaf5e1116e1684c70ac5a9304bd1ada3ac7582c62b2d78781eafefd52f5e5c1468b1d59c32be1dc7d93e10d1f267a7ee4f25348fe8d0890bb1b073f7108cf9199c401725035ea51ad151d6fff2011f1b376ed3798b1ed64084"
}
Content (before encrypting)
{
    "data": {
        "action": "peer_new_com_request",
        "message_id": "000001c",
        "return_id_token": "P-29564d9d26900c43",
        "sender_fio_address": "bob@wallet",
        "recipient_fio_address": "alice@wallet",
        "memo": "Hello! This is Bob, from accounting"
    },
    "signature": "AN1rKqPWr4XoPJMcLM2nWEsj2NBt5qUhG3Y5dWbsSoDxGf9JRuu43z8xg9t2SRFyo7vCkyt4erbyeWJLYGHVSskdArjoCUT16"
}
Processing
  • Message is received or fetched by wallet.
  • Raw message is validated per exception handling.
  • Content is decoded with ecies using recipient's private key.
  • Sender is identified by the field sender_fio_address.
  • Signature is verified using sender's public key.
  • Content is validated per exception handling.
  • Success reception message is transmitted.
  • Sender is added to the peer database.
  • Message is saved locally in plain text.
  • If programmed, an automated action may be executed.
  • Message call is added to the queue for the user to attend.

New funds request

Description:

Requests for a payment to be deposited to a specific public address (sends an invoice).

Endpoint:

peer_new_funds_request

Note:
  • Amount may be empty for the recipient to define.
Body parameters
Parameter Required Format Definition
protocol Yes String Marks the message as a fio standard direct message.
version Yes String Version of the standard used by the sender.
id_token Yes String - min 8 char max 64 char permitted: [a-Z] [0-9] . - _ + Token used by the receiver to identify the sender and decode the message with the correct shared secret. This token is assigned by the receiver on a previous message.
content Yes String Encrypted exchanged information. See below.
Content
Parameter Required Format Definition
Data Yes String Information to be sent to recipient.
Signature Yes String Sender's authentication signature of "data" field contents.
Data
Parameter Required Format Definition
action Yes String Description of the information being sent or requested.
message_id Yes String - min 1 char max 64 char permitted: [a-Z] [0-9] . - _ + Number used to identify and address the message. Must change for every message.
sender_fio_address Yes String Fio address of the sender.
recipient_fio_address Yes String Fio address of the recipient.
return_address No String Location of inbox to be used to respond the message.
return_address_type No String Type of address mentioned in return_adress.
return_id_token No String - min 8 char max 64 char permitted: [a-Z] [0-9] . - _ + Random string generated by the sender. The recipient will use it to identify himself on future messages. Must be different from id_token and tokens sent to other users.
payee_public_address Yes String Blockchain native public address of the payee.
chain_code Yes String Code that identifies the blockchain (network) used to execute the payment.
token_code Yes String Code that identifies the token (currency) that will be used to pay.
amount Yes String Amount to be paid. May be left empty for the recipient to choose an amount.
memo No String Textual description of the transaction. Freely chosen by the user.
hash No String Hash of the data not sent on the message.
offline_url No String Url of data that wasn't sent on the message.
Example
Message body
{
    "protocol": "fio_dm",
    "version": "1.0",
    "id_token": "P-9d9701ceb58945a4",
    "content": "53616c7465645f5fa97214774070c912868ea90907463a997b954ea2383996e9c469e26f085c1a29c6cd2b2da08601841dcfc16d9fea68d1d52a6eebbfbd52d86c8167a06203a313264de7587ef197db799a261b86ae1ea9810540a0ec7ae31a0407c2c7e7d1e281205f94dc09ce137699e7828d80cc0fcf84654911ab2ac7348552ddcaba99f0bc9ede87e141b93f1c62fa7461d0b70210c1ca8ce2583633c4bc4ad6f527f518d9e2d6f7f0d2af9177b548a2baf349b94388d3af3fad54d1975829407a53a2f76f5c403bcd1b52720ebbbe5cd2491d522da1ffcab49572768a9e4ebc4f191be863b2713e6ce918a28f519bb1c65ab77896446e12cd085cc88083bbade725aaad82410a2f44b01ad98de4a2e4c8238ead9a22952e869bb6d0f0d504e13361b7f428b3010114ae489e9776c2d7d349c16fd8ab71bb5e2fb0742f646d022807a227acca32df5d493c4f053bb55fa631454f16b0be8c3b4fbd8c60de977dcb82147a347a1c7f97b07986e9e14613c010d39d4d6509e94465f2dd20673b75e84d032cdf9cc24b25754e274c7c67b84e1ba0c1cd3b2424b499dd61ffb89b53e6599e435e04702d66199b0c1b2f0232ee59b1625e3319ed63eb2f7928ecf9436179619feaf5e1116e1684c70ac5a9304bd1ada3ac7582c62b2d78781eafefd52f5e5c1468b1d59c32be1dc7d93e10d1f267a7ee4f25348fe8d0890bb1b073f7108cf9199c401725035ea51ad151d6fff2011f1b376ed3798b1ed64084"
}
Content (before encrypting)
{
    "data": {
        "action": "peer_new_funds_request",
        "message_id": "000521f",
        "sender_fio_address": "payments@restaurant",
        "recipient_fio_address": "bob@wallet",
        "payee_public_address": "bc1q96kdtk68aw7ew5fw2f33cpxsvzcvpxw7mmat7n",
        "chain_code": "BTC",
        "token_code": "BTC",
        "amount": ".000852",
        "memo": "dinner_bill"
    },
    "signature": "381yXYkZS6yAAqcVSsPDvtArHgE4GcBQQmoKpF3pQYzYcyo8ANWh3q7txuQX7fWov7LtNP5cdnbKkwNSSoL1nzAsoxYGNDqu"
}
Processing
  • Message is received or fetched by wallet.
  • Raw message is validated per exception handling.
  • Sender is identified using identification token.
  • Content is decoded using known shared secret.
  • Signature is verified using sender's public key.
  • Content is validated per exception handling.
  • Success reception message is transmitted.
  • Message is saved locally in plain text.
  • If programmed, an automated action may be executed.
  • Message call is added to the queue for the user to attend.

New public address request

Description:

Requests the recipient for a public address to deposit funds to.

Endpoint:

peer_new_pub_address_request

Body parameters
Parameter Required Format Definition
protocol Yes String Marks the message as a fio standard direct message.
version Yes String Version of the standard used by the sender.
id_token Yes String - min 8 char max 64 char permitted: [a-Z] [0-9] . - _ + Token used by the receiver to identify the sender and decode the message with the correct shared secret. This token is assigned by the receiver on a previous message.
content Yes String Encrypted exchanged information. See below.
Content
Parameter Required Format Definition
Data Yes String Information to be sent to recipient.
Signature Yes String Sender's authentication signature of "data" field contents.
Data
Parameter Required Format Definition
action Yes String Description of the information being sent or requested.
message_id Yes String - min 1 char max 64 char permitted: [a-Z] [0-9] . - _ + Number used to identify and address the message. Must change for every message.
sender_fio_address Yes String Fio address of the sender.
recipient_fio_address Yes String Fio address of the recipient.
return_address No String Location of inbox to be used to respond the message.
return_address_type No String Type of address mentioned in return_adress.
return_id_token No String - min 8 char max 64 char permitted: [a-Z] [0-9] . - _ + Random string generated by the sender. The recipient will use it to identify himself on future messages. Must be different from id_token and tokens sent to other users.
chain_code Yes String Code that identifies the blockchain (network) used to execute the payment.
token_code Yes String Code that identifies the token (currency) that will be used to pay.
amount No String Amount to be paid. May be left empty for the recipient to choose an amount.
memo No String Textual description of the transaction. Freely chosen by the user.
hash No String Hash of the data not sent on the message.
offline_url No String Url of data that wasn't sent on the message.
Example
Message body
{
    "protocol": "fio_dm",
    "version": "1.0",
    "id_token": "P-068573942c8133c8",
    "content": "53616c7465645f5fc82fc2818d843e0a31a061bdbd3379b2da65cbb754c19b3acb8c02864a69c8aaf41da0c54fb1c34458afef7edca711978b494c1358e9677562ba691c9544e3f407d45b01b4a9f03a182b568c739800cc37acc409fcbde97162892d31f3c5760a1b0e75be01a74f3d09c75678fadf37406da141aafdd1b566867d3ffc1109a5928217eb915f682be44df0c650259b19d103f51a30cc9b5b67f49dcc2b60ab0f610b9245ad9a35b2c13189d16e4385502d30fa7342b1fe642c09c926db790f11725f49d7910351cfa3871bb585c7cd45bfba3680cdf697166236d6c09f07cdd1f73c1ec6688da6335a7cfc6393d83b7a52de3368e93a2f7f7c755a333dbfba528fb584d04896493a305c8345a50e560a9582a0a888764b992c575e34a4396496fa7e6c14d74fd96bac341685d1522736d5b71a1b36365472f2808e1b14eecce7c662a4e49fdfe75774f0d61f2a147a7091d3c63aae4ff6b6aa0e496abd4ba7f691ac8f4395efd009286ee8f0d0712bb1667c5be79ea8a1067ca6b8e6a0227d5d510fe63f7b3a0fa528c9aec30f55322d25877dac26b9368d54bc11bfdb8236e6534fadf099aa2f1f26c682c819c0c351b486c4af72f3438299"
}
Content (before encrypting)
{
    "data": {
        "action": "peer_new_pub_address_request",
        "message_id": "000020p",
        "sender_fio_address": "alice@wallet",
        "recipient_fio_address": "bob@wallet",
        "chain_code": "ETH",
        "token_code": "ETH",
        "memo": "December Commissions"
    },
    "signature": "iKx1CJNQRiE7JGSQSbLh2epNK5T1tyR4ptgnxQgX6HNMhjdF91aG4QnKD4xVjATbTqnax2WyngnFV3HyYPSaeQoynH6NtdqxXK"
}
Processing
  • Message is received or fetched by wallet.
  • Raw message is validated per exception handling.
  • Sender is identified using identification token.
  • Content is decoded using known shared secret.
  • Signature is verified using sender's public key.
  • Content is validated per exception handling.
  • Success reception message is transmitted.
  • Message is saved locally in plain text.
  • If programmed, public address may be released automatically.
  • Message call is added to the queue for the user to attend.

Return message status

Description:

Confirms that a message was received. Informs if message was successfully read by the wallet; returns error code otherwise.

Endpoint:

peer_return_message_status

Notes:
  • This response is sent directly from a wallet.
  • It may be sent automatically after receiving any message without a "return message status action".
  • It is used to confirm that a previous message arrived to the sender's wallet, and inform of any errors.
  • Does not carry information on the message status or response. Just confirmation on the arrival.
  • If the sender of a previous message is not correctly identified a response with this action is never invoked, and the previous request will remain unanswered.
  • This action does not require confirmation.
Body parameters
Parameter Required Format Definition
protocol Yes String Marks the message as a fio standard direct message.
version Yes String Version of the standard used by the sender.
id_token Yes String - min 8 char max 64 char permitted: [a-Z] [0-9] . - _ + Token used by the receiver to identify the sender and decode the message with the correct shared secret. This token is assigned by the receiver on a previous message.
content Yes String Encrypted exchanged information. See below.
Content
Parameter Required Format Definition
Data Yes String Information to be sent to recipient.
Signature Yes String Sender's authentication signature of "data" field contents.
Data
Parameter Required Format Definition
action Yes String Description of the information being sent or requested.
message_id Yes String - min 1 char max 64 char permitted: [a-Z] [0-9] . - _ + Number used to identify and address the message. Must change for every message.
referenced_message_id Yes String - min 1 char max 64 char permitted: [a-Z] [0-9] . - _ + message_number of the message being responded or referenced. Used to reference received messages. Same value may be used multiple times.
sender_fio_address Yes String Fio address of the sender.
recipient_fio_address Yes String Fio address of the recipient.
return_address No String Location of inbox to be used to respond the message.
return_address_type No String Type of address mentioned in return_adress.
return_id_token No String - min 8 char max 64 char permitted: [a-Z] [0-9] . - _ + Random string generated by the sender. The recipient will use it to identify himself on future messages. Must be different from id_token and tokens sent to other users.
message_status Yes String Status of a received message (success or error code).
Example
Message body
{
    "protocol": "fio_dm",
    "version": "1.0",
    "id_token": "P-cef782dc5b26556e",
    "content": "53616c7465645f5f1ce5494127e766956f207f66f0e7679b760ad720c28bb772e49ecfe21a4a98a2756f2cf4484121ab9d3a322a57fb7f283a1b597df6399ebb67a8e6e6b8c3b60b03dbfe31ce33ea9b93313018ed49567df16e4e0c2eb25a0ad1b9fdfea223dce0503298e3eb6c824b4be25858057223ef6c9461d3f40bd83c72633fdc69f3caef28df7024dc8e9b2dd7996952eb6812e5e776a9b7d574ae0a1929316ceaff7f66a6c65f0509b47167d76b03c017926409709d2a44f6ec1b5a4e305de4cd8b7eb8e4ccd4824784399a58888412a02b6007413045dec6502484fa16955a8c5f59ae6074e31adba1c65d368922411ee2ede677dd19c458da62357602f0d4504486bf016a0ce6156226b7d867a7702e2c78184ffc410ea90a238b87c4cdb3467c3ca4338f4edfbb1bbcd64b22aa6ec473a6d0de49ae54cfbfdb344202baf5932841d57ee4f99d5a0bef4af89848f8c7468012b4e648e0f1da2b640b78770b1141b984e4f863ebfdb77a63e9d65ee0fafeb606c5f793e7ad3e3267eae796c2e04ba774509c208823e8f77c2bdad3eaacef521b673238658132cab1"
}
Content (before encrypting)
{
    "data": {
        "action": "peer_return_message_status",
        "message_id": "000415s",
        "referenced_message_id": "000324f",
        "sender_fio_address": "alice@wallet",
        "recipient_fio_address": "bob@wallet",
        "message_status": "success",
    },
    "signature": "AN1rKvtdMiUZ3bmV1kqFVsdfPwdpd7yfZ9XiBwvte1AzFdQ95k9mVwzCqPK61wPC3952iCkKkCaj7gWr945cVcYKoZQd1NxCK"
}
Processing
  • Message is received or fetched by wallet.
  • Raw message is validated per exception handling.
  • Sender is identified using identification token.
  • Content is decoded using known shared secret.
  • Signature is verified using sender's public key.
  • Content is validated per exception handling.
  • Message is saved locally in plain text.
  • Status of previous message is updated.
  • Message call is added to the queue for the user to attend.

Accept request

Description:

Informs the recipient that a specific request was accepted and returns the required data.

Endpoint:

peer_accept_request

Notes:
  • Depending on the configuration this message might be sent automatically after receiving a new communication channel or public address request.
  • In the case of a new communication channel request, the messages completes creation of the requested communication channel by assigning the recipient and identification token.
  • In the case of a funds request, the message only informs the recipient that the invoice was paid.
  • In the case of a public address request, the message discloses the public address (for the specific token) that the recipient solicited.
  • After receiving a public address, recipient's wallet might automatically make a payment.
Body parameters
Parameter Required Format Definition
protocol Yes String Marks the message as a fio standard direct message.
version Yes String Version of the standard used by the sender.
id_token Yes String - min 8 char max 64 char permitted: [a-Z] [0-9] . - _ + Token used by the receiver to identify the sender and decode the message with the correct shared secret. This token is assigned by the receiver on a previous message.
content Yes String Encrypted exchanged information. See below.
Content
Parameter Required Format Definition
Data Yes String Information to be sent to recipient.
Signature Yes String Sender's authentication signature of "data" field contents.
Data
Parameter Required Format Definition
action Yes String Description of the information being sent or requested.
message_id Yes String - min 1 char max 64 char permitted: [a-Z] [0-9] . - _ + Number used to identify and address the message. Must change for every message.
referenced_message_id Yes String - min 1 char max 64 char permitted: [a-Z] [0-9] . - _ + message_number of the message being responded or referenced. Used to reference received messages. Same value may be used multiple times.
sender_fio_address Yes String Fio address of the sender.
recipient_fio_address Yes String Fio address of the recipient.
return_address No String Location of inbox to be used to respond the message.
return_address_type No String Type of address mentioned in return_adress.
return_id_token when accepting a new communication request String - min 8 char max 64 char permitted: [a-Z] [0-9] . - _ + Random string generated by the sender. The recipient will use it to identify himself on future messages. Must be different from id_token and tokens sent to other users.
payee_public_address When releasing public address String Blockchain native public address of the payee.
chain_code When releasing public address String Code that identifies the blockchain (network) used to execute the payment.
token_code When releasing public address String Code that identifies the token (currency) that will be used to pay.
amount No String Amount to be paid. May be left empty for the recipient to choose an amount.
memo No String Textual description of the transaction. Freely chosen by the user.
hash No String Hash of the data not sent on the message.
offline_url No String Url of data that wasn't sent on the message.
Example 1
Message body
{
    "protocol": "fio_dm",
    "version": "1.0",
    "id_token": "P-9cb7bf19df5d7f85",
    "content": "53616c7465645f5fc8092417ba0c7e25c98b0007a7724181eddcc3c6432e1c4ca84690fc7c2f292e2447aebf75f7bc800ad67820855797b9d9ad3f6c24475c230328c3044e84225cd8a34fd268606e84067b3162eca24fadf623a851150afef6140d9ba1b15e6f100398ca58ce55aff089154e93af6ec73b3de21282d230d484e09b076e10c000d9bd5ec80235686945ed70526b66bfe78d0acc9e696542c2533b8ec66ffea2e5df3d63077f0620f0d15d3044b20e7ad4a532ad2e9c09de4d97bd3dade947e06370b46bdaa410c86ce832c3552bddd16c19d0e2750893f881effee312325960bcc98632d73fcf14416c6b4c95063f61946dfed7d093b2beb2443747fb7e25e41542e66f4366947579fb357fbc84eb9fe6d196986cc704589baffd6beb694d77ca7791cdd69e01b24d5ad262d24cf466a6859a3396297ab442195572364ab130fd74da43294c457c36eccb63bd8fdd97f59bf52a55d25fbdd7a2cac88b67aa4713b39ea67ec1d307c3927f6b6df0aa4b0207ffebbdbbd1e7c5cfad91fdf80d1989da0be0177eea9e046c6ab093ffc6403f7a808a80b3d44826e1d897f2b47d044caffec64640f12fd3da16e96ac2036689cdd0853b597328746be163f1125ecb999212de75c2a8e1476d46de563ec11b58769ae7ef16648a442a"
}
Content (before encrypting)
{
    "data": {
        "action": "peer_accept_request",
        "message_id": "000002a",
        "referenced_message_id": "000001c",
        "return_id_token": "P-c08ce664c4dbfa08",
        "sender_fio_address": "alice@wallet",
        "recipient_fio_address": "bob@wallet",
        "memo": "Hi Bob! Thanks for adding me!"
    },
    "signature": "381yXZ1ob7QcRNq2UFHeyuWKFNbh5MQetL3BAsZcup9X1CQ2vtvwFWpVuCkh3Mg6dgRRBVkUn569pBaLbgrkCCytTovvm2AK"
}
Example 2
Message body
{
    "protocol": "fio_dm",
    "version": "1.0",
    "id_token": "P-d20fae1f68f9aade",
    "content": "53616c7465645f5fb31efc0d364d28872113a811a2a502d76576870314c0a7c30c18f22c13e7ae7d3c924e67b28a127e26639eb028838d2dd13a84d39dec72c321620204ef1bc45e728bdeb4f260d4c15c7fbaf9ee384905b7ba7f060407ea42a2d0153d2d6c5701ae2a10acad7d6fde082149ce1de288d5c16a248e715d3116b6796e967d4b299912b59465c223e4969f1654f1f324a5a863e5f84c5f2ee97026946fc9cd9b9b9d9e5ba1382ce6897d691eae0003149878c8f1c53b5ca96625266d991389d958a83c6793555ebf95f258c1834838bfb303479534b9bbdaaa0dfac784adbc392ed77a391a959f157fede44feae20681f1535ca86bcc8e287bf7265c2955999d8076def60c5de46eca9d0a1e031cc7f2675a70f1dc12244b52c91875ab28a37811e506e5028ec194a0db20b3b4edfb5eac0fdae11ee7cf1fa5f8bc4f7e8888e451b02116c23232adedf1ed89cff6201589e79009f8a1265552a6dbf26c3e10c79504b52e58e660e9c8b54391ea60786616bfaf24ede7f978913111e4de4c15872c1c02b77f493dcc2cb464344678d3844e518ce6ad188337602cad9b97a6896e02c17837f4e0a295f78bf90bf279fb151d493ea718242e0a7456341f5a79786181e01c0f4a4b3e5d26862cca7b508b6d689cf1ba77a9ef9dea4b2f0bf4667b9d8f0e077fdc679223e425acebebccc2e1921ab6639b0c82ef4823f8b026d10a654788045b2d7ba4fd41e61e16b0e32464f4a25f10b79efdf6702cf5f7fb05f1d136b3cfe24017682e13af"
}
Content (before encrypting)
{
    "data": {
        "action": "peer_accept_request",
        "message_id": "000032a",
        "referenced_message_id": "000028p",
        "sender_fio_address": "alice@wallet",
        "recipient_fio_address": "bob@wallet",
        "payee_public_address": "bc1q96kdtk68aw7ew5fw2f33cpxsvzcvpxw7mmat7n",
        "chain_code": "BTC",
        "token_code": "BTC",
        "memo": "Thank you for your payment"
    },
    "signature": "381yXZX6vA5pvi5dXUziDexHnfmchQaB4QJ97nXxE8c5Q9Zq8tFs4QKfQCDDLA42BCJNbq4PreUF9E92fLFs7HXnhwapTPF5"
}
Processing
  • Message is received or fetched by wallet.
  • Raw message is validated per exception handling.
  • Sender is identified using identification token.
  • Content is decoded using known shared secret.
  • Signature is verified using sender's public key.
  • Content is validated per exception handling.
  • Success reception message is transmitted.
  • Message is saved locally in plain text.
  • Status of the referenced request is updated.
  • If programmed, an automated action may be executed.
  • Message call is added to the queue for the user to attend.

Reject request

Description:

Informs the recipient that a specific request will not be executed.

Endpoint:

peer_reject_request

Body parameters
Parameter Required Format Definition
protocol Yes String Marks the message as a fio standard direct message.
version Yes String Version of the standard used by the sender.
id_token Yes String - min 8 char max 64 char permitted: [a-Z] [0-9] . - _ + Token used by the receiver to identify the sender and decode the message with the correct shared secret. This token is assigned by the receiver on a previous message.
content Yes String Encrypted exchanged information. See below.
Content
Parameter Required Format Definition
Data Yes String Information to be sent to recipient.
Signature Yes String Sender's authentication signature of "data" field contents.
Data
Parameter Required Format Definition
action Yes String Description of the information being sent or requested.
message_id Yes String - min 1 char max 64 char permitted: [a-Z] [0-9] . - _ + Number used to identify and address the message. Must change for every message.
referenced_message_id Yes String - min 1 char max 64 char permitted: [a-Z] [0-9] . - _ + message_number of the message being responded or referenced. Used to reference received messages. Same value may be used multiple times.
sender_fio_address Yes String Fio address of the sender.
recipient_fio_address Yes String Fio address of the recipient.
return_address No String Location of inbox to be used to respond the message.
return_address_type No String Type of address mentioned in return_adress.
return_id_token No String - min 8 char max 64 char permitted: [a-Z] [0-9] . - _ + Random string generated by the sender. The recipient will use it to identify himself on future messages. Must be different from id_token and tokens sent to other users.
memo No String Textual description of the transaction. Freely chosen by the user.
Example
Message body
{
    "protocol": "fio_dm",
    "version": "1.0",
    "id_token": "P-6fd497cbd389c9c1",
    "content": "53616c7465645f5f4b9857f78f90c0c0b96637e41f4818584d9c55f3c85b03150d262fb2e04eaa0771f6fddca9e36767a5ef47230696ad43933d77db06daee594d2b156878027f2fe3c2783e444ee19d8c5ce6738cabfe713ac4972c0eeb41b6050c8afe7e05d37c89f4e55521f356b933b46cd1d488557b9dab57e120821973e456b665d2bc4c00875b1d552b6430dfc436c4402bd7b3826fa8cb212e35d12ad3ce1c7cf23cc8f93fcb865b0afe2b2b11a1eda482cddbb9954d34aa77bc4e7b9ee6f0e404be597413283096a859ceccd19172a5290fd0c67a52c5c731d7861383e7528334955b5340840ff2a2041fa3f3f372c04a8ce0a8a5fe8b242d51f5788e46e1031635915890717ee78b7d86380950bc527a5253a078d976e0c5f243d812c8f5864fea8d6c4fca716b35fc18072e12a0ca7b536de3b7de0293e2cfd82a95aa4f4c7c214dcce646e589defc3f6250e8107b9b4f9102c90e7f856c60219745b7ad020a7bc4937c5ccb420537e77accd47302a4807b01e0e39631f1b3299536eadf38115d836138dab81fdccc2efcea674ab5aa10b2e52a54fc2e07ef6d0ba099d8090f06c22d04180eaee1c34939"
}
Content (before encrypting)
{
    "data": {
        "action": "peer_reject_request",
        "message_id": "000004r",
        "referenced_message_id": "000008f",
        "sender_fio_address": "alice@wallet",
        "recipient_fio_address": "bob@wallet",
        "memo": "Thank you, but that's too expensive for me."
    },
    "signature": "381yXZLxuDd4DQArPKEGK9ishyXL5vbfTBwSQHcEb9GqRgzGzG5DJ1uJm2aPKeahgEkZCzmhdkvaazX7FUrHesRLo7X7HTPV"
}
Processing
  • Message is received or fetched by wallet.
  • Raw message is validated per exception handling.
  • Sender is identified using identification token.
  • Content is decoded using known shared secret.
  • Signature is verified using sender's public key.
  • Content is validated per exception handling.
  • Success reception message is transmitted.
  • Message is saved locally in plain text.
  • Status of the referenced request is updated.
  • If programmed, an automated action may be executed.
  • Message call is added to the queue for the user to attend.

Cancel request

Description:

Informs the recipient that the sender no longer interested in the referenced petition.

Endpoint:

peer_cancel_request

Body parameters
Parameter Required Format Definition
protocol Yes String Marks the message as a fio standard direct message.
version Yes String Version of the standard used by the sender.
id_token Yes String - min 8 char max 64 char permitted: [a-Z] [0-9] . - _ + Token used by the receiver to identify the sender and decode the message with the correct shared secret. This token is assigned by the receiver on a previous message.
content Yes String Encrypted exchanged information. See below.
Content
Parameter Required Format Definition
Data Yes String Information to be sent to recipient.
Signature Yes String Sender's authentication signature of "data" field contents.
Data
Parameter Required Format Definition
action Yes String Description of the information being sent or requested.
message_id Yes String - min 1 char max 64 char permitted: [a-Z] [0-9] . - _ + Number used to identify and address the message. Must change for every message.
referenced_message_id Yes String - min 1 char max 64 char permitted: [a-Z] [0-9] . - _ + message_number of the message being responded or referenced. Used to reference received messages. Same value may be used multiple times.
sender_fio_address Yes String Fio address of the sender.
recipient_fio_address Yes String Fio address of the recipient.
return_address No String Location of inbox to be used to respond the message.
return_address_type No String Type of address mentioned in return_adress.
return_id_token No String - min 8 char max 64 char permitted: [a-Z] [0-9] . - _ + Random string generated by the sender. The recipient will use it to identify himself on future messages. Must be different from id_token and tokens sent to other users.
memo No String Textual description of the transaction. Freely chosen by the user.
Example
Message body
{
    "protocol": "fio_dm",
    "version": "1.0",
    "id_token": "P-f0fb7a448876f18a",
    "content": "53616c7465645f5fd0752ed9eaa33b1612d39e7c40e5d6c016885eea62e03530493c09a2234fb87a304b275ca77316d7fe71c9c589f6cef58c019bd5233f91e3c5cfe5075229d919e492638711d2bb6a8cf40c92cebe67e1529170fba87a379ea80e322249584084c25cae15cd5f80098a022f792a1de0e50f44738f4d5d7ce66e05eeec08b6c36f847911579f1a10d8c87059cf2698c388e736e6e3668cde4ee31e96912bf2bd6aaf9755b81aaf2e26b942cc3c43b35d881810ce19a2302d250ef59c571d38e7f357a4f0c967e0f5e9ed514b3357248249bf8b5cfa77573ac9d5c00c464eb17b353d7c0d6b2b0918e943c75f8c44dd50f128453054183964b9ae5672dff60eb1c198a4a4909eee34a633441e2a94094822eced211d0dfc63b4bfbe87ddb070cfcb43ba6afcf4fb7627a6f9208c8e0e8d939da4413afcd4c8deddb68795dd7705c332745d30131ec2237f6058c5120910e8e03e8c5b16586768020b0ca375060e0a5e0b99d3f47b3a3be8d27a75b693ca0f0695130f1e018213227006e9b5b42746d4c2f5a9486c7a80ca5f1266985a963a88ab5b014adc8c0d2cf44f00f619f862906988e3283b30d0"
}
Content (before encrypting)
{
    "data": {
        "action": "peer_cancel_request",
        "message_id": "000036c",
        "referenced_message_id": "000035f",
        "sender_fio_address": "alice@wallet",
        "recipient_fio_address": "bob@wallet",
        "memo": "Sorry, sent invoice by mistake."
    },
    "signature": "AN1rKvt8wPCyGsjJCE6CdUtLqZxzvfXUc3jBTTm1MQZN3mSpqV1Bkh1uututrDn82PZ31RzPhfgJ8eCoxrHbrZB6QFLHR3XEE"
}
Processing
  • Message is received or fetched by wallet.
  • Raw message is validated per exception handling.
  • Sender is identified using identification token.
  • Content is decoded using known shared secret.
  • Signature is verified using sender's public key.
  • Content is validated per exception handling.
  • Success reception message is transmitted.
  • Message is saved locally in plain text.
  • Status of the referenced request is updated.
  • If still active, request is removed from queue.

Update data request

Description:

Requests the receiver to change the communication data registered to the sender (location and id token)

Endpoint:

peer_update_com_data_request

Body parameters
Parameter Required Format Definition
protocol Yes String Marks the message as a fio standard direct message.
version Yes String Version of the standard used by the sender.
id_token Yes String - min 8 char max 64 char permitted: [a-Z] [0-9] . - _ + Token used by the receiver to identify the sender and decode the message with the correct shared secret. This token is assigned by the receiver on a previous message.
content Yes String Encrypted exchanged information. See below.
Content
Parameter Required Format Definition
Data Yes String Information to be sent to recipient.
Signature Yes String Sender's authentication signature of "data" field contents.
Data
Parameter Required Format Definition
action Yes String Description of the information being sent or requested.
message_id Yes String - min 1 char max 64 char permitted: [a-Z] [0-9] . - _ + Number used to identify and address the message. Must change for every message.
sender_fio_address Yes String Fio address of the sender.
recipient_fio_address Yes String Fio address of the recipient.
return_address No String Location of inbox to be used to respond the message.
return_address_type No String Type of address mentioned in return_address.
return_id_token No String - min 8 char max 64 char permitted: [a-Z] [0-9] . - _ + Random string generated by the sender. The recipient will use it to identify himself on future messages. Must be different from id_token and tokens sent to other users.
Example
Message body
{
    "protocol": "fio_dm",
    "version": "1.0",
    "id_token": "P-b554fb20227e91c5",
    "content": "53616c7465645f5fba5ceead8fb02f370f21861e5c73f4eb0f399823f06cfebd9944a9224cdda2189bbfe3b92c202b43aa14d1af983fa817a0776d9ca041cec4b196533caafa7b99779e62e3d8c09c033b3219f8ff37741ec804f83e5a7238abafbeb3ca96981f95fed16fdf98cfd6841c66820d58ecb28c7eeb71644cb72b014a551b9c28e383337d70f2bdf33bb39f4881835fe7621de40c9304bd9fbf9417a2b0f18c64ab19561f17dcd19389e7d759120c6608f2ebda5cd175b7150743c6e23d80c910e1b9d2ab57bdcdf419e19888fb21720f985e712108cc3012b4bd0d4515a7a7663a2ea2c71b2af4ac5dc81932e6dc29565844b66ae9f6c863ea4aa334a1784a2dfe631889fd1e26fe28816b3bb2df198a5e314bd172b00bd5c2db08caa0fef2eb444bd6377c984e8242c5f6ed518cca29559e80a8dd1c8d3d0b7167ab9290563b7c7bea2b20d5c64dd14968d3a6416d39c3da6fd34f8d7ae5b35f70267e2142776788fa5099d7402de86ebd67d09ef169c0208c077891241e945d53fe8ba372b5f8becdd89e5c8fd53bf99dbb0217df466d228003f60a059c66c6c6d7bc93b6df5dd0c06cfd72995e246507fe60c9c52e971886292ab6dc1b580027f88c30f51c56e332922eb397036a12d0661368a2fff5e52942b32842fd469d1c4824d9bf5b14a0bb2830409e3de88b61"
}
Content (before encrypting)
{
    "data": {
        "action": "peer_update_com_data_request",
        "message_id": "000123u",
        "sender_fio_address": "alice@wallet",
        "recipient_fio_address": "bob@wallet",
        "return_address": "alice.mywalletinbox.crypto:3030",
        "return_address_type": "URL",
        "return_id_token": "P-677b73bfd188ba87",
    },
    "signature": "AN1rKpnb9GjcapGzkJw9rdBEuXLkdS9cGxd8fUAr5hLHAMBG3qGsZfZmPNjjDMRb9sU2zS9P56KCZb9QxJrfLnFpByLNPeRoV"
}
Processing
  • Message is received or fetched by wallet.
  • Raw message is validated per exception handling.
  • Sender is identified using identification token.
  • Content is decoded using known shared secret.
  • Signature is verified using sender's public key.
  • Content is validated per exception handling.
  • Success reception message is transmitted.
  • Message is saved locally in plain text.
  • Database is updated with the latest sender's information.

Close communication channel request

Description:

Requests recipient to ignore registered to sender and treat any future contact as new.

Endpoint:

peer_close_com_request

Notes:
  • If a comunication channel is closed, recipient's wallets will stop comparing messages with sender's identification tokens. Sender's data might also be deleted from recipients database.
  • Might be used for wallet migration.
Body parameters
Parameter Required Format Definition
protocol Yes String Marks the message as a fio standard direct message.
version Yes String Version of the standard used by the sender.
id_token Yes String - min 8 char max 64 char permitted: [a-Z] [0-9] . - _ + Token used by the receiver to identify the sender and decode the message with the correct shared secret. This token is assigned by the receiver on a previous message.
content Yes String Encrypted exchanged information. See below.
Content
Parameter Required Format Definition
Data Yes String Information to be sent to recipient.
Signature Yes String Sender's authentication signature of "data" field contents.
Data
Parameter Required Format Definition
action Yes String Description of the information being sent or requested.
message_id Yes String - min 1 char max 64 char permitted: [a-Z] [0-9] . - _ + Number used to identify and address the message. Must change for every message.
sender_fio_address Yes String Fio address of the sender.
recipient_fio_address Yes String Fio address of the recipient.
memo No String Textual description of the transaction. Freely chosen by the user.
Example
Message body
{
    "protocol": "fio_dm",
    "version": "1.0",
    "id_token": "P-3b04d9af8a3e7146",
    "content": "53616c7465645f5f72ccd43db18e9461e19dfac0b980df787b52f5ff1e9d2409597fa3ca28321ba2c2abc2e3cc3c19a7f3eec16e7f4e00d55ebeb1b51754cc7a46cfa2131636c9e1b3f28761377934df1d5406f215b8fe55a1a0a4684d59565985d84617d08d98bd1751e125d93ccc81f8f84718daf7faf9a003f439d6d07260f2855604edc3a2ba4b1f24d748b982baae777cc63378bfa249776c92afade2d5870518fb001d3123f0aea67bcf0366618e19667d5ab721d95f45743d4bf371e5026954da3d1f52163c8508d17211f2f5729129ba1d2e721a8e199c76834b3c5db4ec21e7e069cb4658f7a7450666ab3999ec01eac23d8374cb6184bf297c75899d0111dc86e03726ca411f4fdcd05201955eeed3e57ea5aeb36faf8a06e3fa7c1a3b0420679c59a03b2937a839b5fb58dfec39ff9eca10fe8d6a56153bcaf01edb4acf5b8a66b8770a5738997826399c"
}
Content (before encrypting)
{
    "data": {
        "action": "peer_close_com_request",
        "message_id": "000871l",
        "sender_fio_address": "alice@wallet",
        "recipient_fio_address": "bob@wallet",
    },
    "signature": "381yXZ7Z6ku1eWmcHSYS5YFdA5jrVteXJ5XBVJP8SyYZyWJ2jgTc2tSQ79YsSmdBR3L7T2q8YSTkzXrUwzjzm6oSnUz5Tshx"
}
Processing
  • Message is received or fetched by wallet.
  • Raw message is validated per exception handling.
  • Sender is identified using identification token.
  • Content is decoded using known shared secret.
  • Signature is verified using sender's public key.
  • Content is validated per exception handling.
  • Success reception message is transmitted.
  • Message is saved locally in plain text.
  • If programmed, communication channel might be closed automatically.
  • Message call is added to the queue for the user to attend.

Send private text

Description:

Sends a private memo

Endpoint:

peer_send_private_text

Body parameters
Parameter Required Format Definition
protocol Yes String Marks the message as a fio standard direct message.
version Yes String Version of the standard used by the sender.
id_token Yes String - min 8 char max 64 char permitted: [a-Z] [0-9] . - _ + Token used by the receiver to identify the sender and decode the message with the correct shared secret. This token is assigned by the receiver on a previous message.
content Yes String Encrypted exchanged information. See below.
Content
Parameter Required Format Definition
Data Yes String Information to be sent to recipient.
Signature Yes String Sender's authentication signature of "data" field contents.
Data
Parameter Required Format Definition
action Yes String Description of the information being sent or requested.
message_id Yes String - min 1 char max 64 char permitted: [a-Z] [0-9] . - _ + Number used to identify and address the message. Must change for every message.
referenced_message_id No String - min 1 char max 64 char permitted: [a-Z] [0-9] . - _ + message_number of the message being responded or referenced. Used to reference received messages. Same value may be used multiple times.
sender_fio_address Yes String Fio address of the sender.
recipient_fio_address Yes String Fio address of the recipient.
memo yes String Textual description of the transaction. Freely chosen by the user.
Example
Message body
{
    "protocol": "fio_dm",
    "version": "1.0",
    "id_token": "P-5b5ea6a3917d4b62",
    "content": "53616c7465645f5fab2f15b41473292c607864f103ed9a58902a5126e1246d1fa8a424cfd52e0c0f8ae9ab6fbcf4b526484c756f2894382f451a70fbb8b4c175bd28022cc5b4d507741d1a868f38c4dbffb56b000be799ab591d53c85efa011057922ee54fe6e1b0760c03089fa77a055b5b296369bbf6bdcf392f1efd2a45a2eb6ef4f70d8dafd5e7990bf5a44598f86f991d6c9ac4fd8590e69052c17b5e602a5a042a51c35b1068df3f4553491ab919de65349113556a9296d05e7bd5c69d272535608459177e39658e530b19dff139655c6af5a631a5ec631e201a2a6c51b64aa027327d60d2c1daab299857092accad90c009edee39c73f205f48abc0df74b271c166a55fd99b1e8a3f5c61c09e312391e654334382e199c971dd794e54c854102d2ae433820f6cc0bb52d46f3f1ddd925080f4266fdf257cec0190230994d66b3bf79ba84c039548d8477c46bf11f4360c1640f3ae47db454c4ccfbf5b78502e27c6b990a220b589542885c0aaaedc82f4acc8512e651df1d97c8ce5152315d91fe0c3c4791a5247535e143fb2bb698abd90860eccb9217738f80df4c2cc53abe64ed6f0ebbdd29f19ac15b2343d87c6a34b7d4df67d39267ebd98a323"
}
Content (before encrypting)
{
    "data": {
        "action": "peer_send_private_text",
        "message_id": "000012m",
        "sender_fio_address": "mike@wallet",
        "recipient_fio_address": "bob@wallet",
        "memo": "Hi! It's me, Mike! I want to buy more of that stuff. Do you accept payments in Monero?"
    },
    "signature": "iKx1CJMnCjprZkNMawCH6yXxJnaX5jzdHc5PmfUoME38WXuPkj2D5BPwSKefh5EUqvTXRJVsCL9Trnn5N1fKrBzMt6bZbFUhfX"
}
Processing
  • Message is received or fetched by wallet.
  • Raw message is validated per exception handling.
  • Sender is identified using identification token.
  • Content is decoded using known shared secret.
  • Signature is verified using sender's public key.
  • Content is validated per exception handling.
  • Success reception message is transmitted.
  • Message is saved locally in plain text.
  • Message call is added to the queue for the user to attend.

Exception handling

Error condition Trigger Type fields:name fields:value Error message
Invalid protocol The protocol used is not supported by the receiving wallet. 400 "protocol" Value sent, e.g. "fio_https" "Protocol not supported"
Invalid id Id doesn't match token assigned to any user. 400 "id_token" Value sent, e.g. "P-0000" "Unrecognized id"
Invalid action Action is not recognized by wallet. 400 "action" Value sent, e.g. "new_funds_request" "Unknown action"
Invalid message id Message id format is not valid or message id collides with a previous message. 400 "message_id" Value sent, e.g. "-1" "Invalid or reused message number"
Invalid responded message id Responded message id is in invalid format or does not match a recorded message. 400 "referenced_message_id" Value sent, e.g. "-1" "Invalid responded message Id"
Invalid sender fio address Sender fio address does not match address registered in channel database. 400 "sender_fio_address" Value sent, e.g. "noone@wallet" "Invalid fio address"
Invalid recipient fio address Recipient fio address does not match address registered in channel database. 400 "recipient_fio_address" Value sent, e.g. "noone@wallet" "Invalid fio address"
Invalid return address Wallet does not support the specified return address. 400 "return_address" Value sent, e.g. "domain.name.com_0123" "Invalid return address"
Invalid return address type Wallet does not support the specified return address type. 400 "return_address_type" Value sent, e.g. "onion" "Unsupported return address type"
Invalid return id token format Return id token is not in a valid format. 400 "return_id_token" Value sent, e.g. "%01234%" "Invalid return id token"
Invalid public address Payee public address does not match the expected format. 400 "payee_public_address" Value sent, e.g. "bc0..." "invalid public address"
Invalid chain format Supplied chain code is not supported or not in a valid format. 400 "chain_code" Value sent, e.g. "BTC%" "Invalid Chain Code"
Invalid token format Supplied token code is not supported or not in a valid format. 400 "token_code" Value sent, e.g. "BTC%" "Invalid Token Code"
Invalid amount format Supplied amount is not in a valid format. 400 "amount" Value sent, e.g. "-100" "Invalid amount"
Decryption failure Wallet was unable to Decript the content of the message. 400 "Unable to decrypt message"
Unrecognized signature The signature does not match sender's public key. 403 "signature" Value sent, e.g. "000000" "Invalid signature"
Not owner of fio address The presented fio address is not controlled by the user signing the message. 403 "Invalid id"
Payload to large Message size exceeds 8KB. 413 "Message to large"

Notes

Features

The proposed method offers an alternative solution against communicating exclusively through fio blockchain request.

Advantages:

  • High privacy
  • Less fees
  • Easier management for the user
  • Higher scalability for the network
  • Decreased per interaction write calls and space consumption in the fio blockchain
  • Ability to add interwallet actions without modification to the fio protocol code
  • Less limitation on messages length
  • May (theoretically) be implemented through any communication protocol

Disadvantages:

  • Requirement of a static location address
  • Requirement of a fixed server for the inbox (may belong to a third party)

Privacy level

The method requires a location to be publicly assigned to a fio address; and at least two requests to the fio blockchain to get the inbox location and public key of each new peer. This might leave small traces of information on some private servers (not an issue for most people).

If a user wishes to use the protocol with absolute privacy (outside of sharing his fio address with his peers) he may achieve this by using obfuscated addresses (via vpn or the tor Network) and run a private fio node.

Inbox server

Message processing

Note that even though the messages might be sent to a shared fixed server, the server will (sometimes) act only as an inbox to relay the message to the wallet and will not (necessarily) hold any keys, verify signatures decrypt information or handle message specific exceptions. Those tasks belong to the wallet.

For this reason, getting a "202" (accepted) http status code doesn't necessarily imply the message was successfully received and processed by the recipient.

Shared server addresses

For servers being accessed by multiple clients, a unique inbox identifier might be needed so that the server may know which user to relay the message to. Such identifiers must be included on the inbox location registered on the blockchain.

Rationale

Encryption

As most communications are naturally encrypted, additional encryption on the message content may seem redundant. However, as the end user is not likely to control the relaying server, an extra layer of protection will shield the user's privacy from third parties.

Initiating message

Encrypting the sender's fio address with an asymmetric algorithm aids in the protection of the user's privacy by obfuscating the relation between the two parties to any actor observing their communications.

An alternative method for this purpose, would be for both users to manually input each other's fio address (or click an invitation link) before starting communication. This would reduce significantly the complexity of the communication protocol, but would also reduce user friendliness.

Encrypting all content

As the message data is stored on the wallet instead of a public database, the content of the message can be decrypted and stored as plain text as to facilitate filtering of information. This means there is no inconvenience in hiding important fields behind a cipher for transfer.

Per address pair channel opening

Creating one channel per fio address pair will, in some cases, result in multiple channels per peer, as some users might control more than one fio address/key. Nevertheless, managing multiple keys or fio addresses per channel would make peer management excessively complex. This could open each wallet to strange errors and vulnerabilities which should be avoided.

Included content

Fio addresses

Even though the fio addresses of the sender and the recipient should be implicit and could be deduced by the recipient wallet in most messages, they have been purposely required to simplify wallet implementation, avoid multiple identity conflicts, and protect the user against security exploits (e.g. surreptitious forwarding attacks).

Future considerations

Spam prevention

As communication require sender's private key signature and a registered fio address, abused address lists may be used to filter communication from spamming addresses.

Derived id token

An alternative method to reusing id tokens or sending new ones for every new message would be to specify a standard to use the hash of a seed and a counter. This would generate predictable single use identification tokens that change automatically for each message and only known by the communicating parties.

additional actions

Other actions may be added in the future to extend the functionality and ease of use of the communication mechanism. For example:

  • Request for signature
  • Request to return accepted payment forms (token codes)
  • Request for amount to be paid (ask for an invoice)
  • Send message prove to verify recipient's reachability
  • Confirm the arrival of a previous message

additional data fields

More data fields might be added to allow better communication. These might include fields like:

  • Date and time
  • Application specific arbitrary data
  • Contact information
  • Hyperlinks

Possible upgrades

On future iterations of the protocol, more advanced features might be invoked by adding new actions or modifying existing ones. These might include systems to:

  • Automate recurring payments
  • Pre-authorize automatic charges
  • Generate complexly formatted invoices
  • Distribute invoices amongst groups
  • Transmit complex wallet instructions through messages
  • Collect microtransactions on a time based system
  • Redirect messages to other wallets
  • Continuous conversation (chat)
  • File and multimedia content transfer

Interactive requests

Funds requests may be modified to allow the users to specify data through the wallet instead of using an external interface. A user could, for example, choose a payment method interactively inside his wallet, instead of receiving a public address on a specific token.

Server business model

Just like the are companies that charge small (or no) fees for a simple email account, there could be a business model around fio peer messages. And, even though, server centralization could, potentially, lead to privacy and censorship concerns, any usable service would inheritably expand the protocol functionality and augment it's privacy (even if a particular provider is ill intentioned), and no user would be obligated to acquire any specific service.

A standard could also be specified, as part of the protocol, for the wallet to automatically setup and manage server accounts.

Fio blockchain integration

The fio software could, theoretically, be upgraded to support the secure message system natively, and have private interactions between the users without the need for external servers.

For this purpose, 2 new endpoints would need to be added to the protocol.

  1. A request to record an encrypted message in the blockchain.
  2. A request to fetch all messages containing a specific id token.

Of course as blockchain space is limited, messages would have to be optimized in size, and fees would probably have to be calculated in function of space and time.

For this modification to work, the user recipient would have to manually add the sender's fio address to his peer list before communicating for the first time or click an invitation link.

To implement the use of a private initiator message avoiding the requirement for invitation links or other kinds of external communication (which is not user friendly) Several different solutions could be implemented; for example:

  • Prepaid deposit inboxes
  • Preassigned limited storage inboxes
  • Side stealth fio key pairs
  • Join transactions
  • Anonymous transaction fee payment methods
  • Specially designed smart contracts
  • Trusted relaying third parties
  • Ring signatures
  • Message starting groups

Needless to say, most of the options could complicate the implementation extensively or create further problems to solve (like invitation spam).

Discussion link

https://discord.gg/6EUjzmHChY