AIP 14: Chatrooms API

Simple Summary

To simplify access to chats and offer one common endpoint for chats and group chats in the future, current node’s API need to be extended.

Abstract

Current API for retrieving chats are the same as for general transactions. It leads to ineffective work of messaging applications. To get full list of contacts, apps have to download all of transactions for a user. This behavior is very slow for users with multiple chats.

Effective solution is to create new chatroom endpoint that offers fetching contacts, chats and paginating through chatrooms.

Motivation

Chatrooms will make messenger apps faster and consume less memory.

Specification

New endpoint /api/chatrooms should be added to ADAMANT node. It uses REST notation.

Let user address is U000000000000 and he communicate with U000000000001. To get user’s U000000000000 chats, GET request to /api/chatrooms/U000000000000 should be sent. To get chat messages between U000000000000 and U000000000001, GET request to /api/chatrooms/U000000000000/U000000000001 should be sent.

API endpoint for /api/chatrooms/U000000000000 returns list of general chats structure:

"chats": [{
  "lastTransaction": {
    "id": TX_ID,
    "type": TX_TYPE,
    "height": TX_HEIGHT,
    "timestamp": ADAMANT_TIMESTAMP,
    "senderPublicKey": PUBLIC_KEY,
    "senderId": ADAMANT_ID, 
    "recipientId": ADAMANT_ID,
    "recipientPublicKey": PUBLIC_KEY,
    "amount": AMOUNT,
    "fee": AMOUNT,
    "signatures": [array of SIGNATURE],
      "confirmations": UNSIGNED INTEGER,
    "asset": JSON_OBJECT,
  },
  "participants": [ 
    {
      "address": "ADAMANT_ID",
      "publicKey": "PUBLIC_KEY"
    }, {
      "address": "ADAMANT_ID",
      "publicKey": "PUBLIC_KEY"
    }, {...}
  ]
}, {...}
]

Format types and fields described in AIP-10: General transaction structure for API calls. Array participants includes both sender’s and recipient’s addresses and public keys for chat dialog. Object lastTransaction contains information about last transaction with specific participant, including asset data.

List of all transactions in chat with specific recipient /api/chatrooms/U000000000000/U000000000001 is returned in messages response field.

Along with chats array, endpoint returns count of chats or messages integer value. count is independent from limit argument, always returning total count.

Available arguments:

• orderBy — order by field, same as in transaction list API, default is timestamp:desc
• offset — offset, same as in transaction list API, default is 0
• limit — limit field, same as in transaction list API, default 25
• withoutDirectTransfers — if direct ADM transfers (transactions of type 0) should not be returned, default false

Examples

Result of api/chatrooms/U7972131227889954319 request:

{
  "success": true,
  "nodeTimestamp": 46531132,
  "chats": [{
    "id": "7452709338464950789",
    "type": 8,
    "timestamp": 25726425,
    "senderPublicKey": "ce67b26e33391dd88ea2bc0173256b9c68a038888fc3de5b8b9887581ddd3239",
    "senderId": "U10879844458425463425",
    "recipientId": "U7972131227889954319",
    "recipientPublicKey": "d2885bc8d4aa68f0f4c919077c1edcb9c9020a715f20cb6db7578cd6f68055bb",
    "amount": 0,
    "fee": 100000,
    "signatures": [],
    "confirmations": null,
    "stored_value": null,
    "stored_key": null,
    "asset": {
      "chat": {
        "message": "7b1e6e21f1f8e4be646133d5814b2ca5c60c0a9bac",
        "own_message": "2a6b950be00ac83d289853251491486d0d403c81e5ce1213",
        "type": 1
      }
    },
    "participants": [{
      "address": "U10879844458425463425",
      "publicKey": "ce67b26e33391dd88ea2bc0173256b9c68a038888fc3de5b8b9887581ddd3239"
    }, {
      "address": "U7972131227889954319",
      "publicKey": "d2885bc8d4aa68f0f4c919077c1edcb9c9020a715f20cb6db7578cd6f68055bb"
    }]
  }, {...}
  ],
  "count": "63"
}

Result of api/chatrooms/U7972131227889954319/U15677078342684640219 request:

{
  "success": true,
  "nodeTimestamp": 46534772,
  "messages": [{
    "id": "10194689778297980241",
    "height": 840833,
    "blockId": "18442279251222439707",
    "type": 8,
    "timestamp": 11049579,
    "senderPublicKey": "d2885bc8d4aa68f0f4c919077c1edcb9c9020a715f20cb6db7578cd6f68055bb",
    "requesterPublicKey": null,
    "senderId": "U7972131227889954319",
    "recipientId": "U15677078342684640219",
    "recipientPublicKey": "e16e624fd0a5123294b448c21f30a07a0435533c693b146b14e66830e4e20404",
    "amount": 0,
    "fee": 500000,
    "signature": "0e5651909e77adb0bef384884e1f09c006b9403c1c9abeb36832df5c1fedeca6b5f2771bf84b273d27580e440acd823e6fbb3d2a55bf033512adc25711832501",
    "signSignature": null,
    "signatures": [],
    "confirmations": null,
    "stored_value": null,
    "stored_key": null,
    "asset": {
      "chat": {
        "message": "579636a8943c5f766e3bbbfaf75528d8a9e9b89878c0551c7f887f35c51034f32ba8bad35495e3f2c95af977c9b08d7b86c160c97456d1e426",
        "own_message": "a13976c2635255df4d96ad412f60630478e146b9d6fe82db",
        "type": 0
      }
    }
  }, {...}
  ],
  "participants": [{
    "address": "U7972131227889954319",
    "publicKey": "d2885bc8d4aa68f0f4c919077c1edcb9c9020a715f20cb6db7578cd6f68055bb"
  }, {
    "address": "U15677078342684640219",
    "publicKey": "e16e624fd0a5123294b448c21f30a07a0435533c693b146b14e66830e4e20404"
  }],
  "count": "341"
}  

Rationale

Messenger clients need to get chats faster. As clients need to know public keys of all chats participants, it is rational to return them in requests. Direct ADM token transfers may be hidden in some clients, so withoutDirectTransfers parameter added. offset and limit parameters allows to fetch data by parts and make client apps even faster.

Backwards Compatibility

This improvement adds new API endpoint, and won’t change backward compatibility for any previous clients.

Copyright

Copyright and related rights waived via CC0.