Statuses for Messages and Transfers

[adamant-al]

See also:

• In-Chat and Direct Crypto Transfers in ADAMANT https://github.com/orgs/Adamant-im/discussions/31

Message Statuses

• ✅ Delivered
• ⏳ [Internal status] Generating transaction, sending to node (~Pending)
• ⏳ Sending / Checking (Pending)
• ⏳ Registered on node (~Pending)
• ❌ Not sent
• ⚠️ Inconsistent (mismatch detected)
• ⚭ In blockchain (additional to Delivered)

👉 In ADAMANT, there is no "read" status for messages, and it will never be implemented — to preserve user privacy.

Messages (without sockets)

• Incoming messages are always delivered since they are taken directly from the blockchain. Therefore, they never have any other status. We don’t display statuses for incoming messages.
• Outgoing messages:
  1. Start with ⏳ Sending
  2. Then ✅ Delivered (when the node accepts the transaction)
  3. Finally ⚭ In blockchain (additional to Delivered)
• Transition from ⏳ Sending → ✅ Delivered to node must happen quickly for a smooth UI experience
• Statuses are updated both in the chat list and inside each chat

Messages (with sockets)

Incoming messages

• Sockets return unconfirmed transactions as soon as they reach the node. At this point, transaction fields like block_timestamp, height, blockId, and confirmations are null.
• Sockets duplicate REST API responses. Messages arrive instantly via sockets, while REST provides updates every ~10 seconds (SOCKET_ENABLED_TIMEOUT) for reliability.
• Via socket we get status:
  • ✅ Delivered to node (always, immediately).
• We do not use “Delivered to recipient” — it contradicts ADAMANT’s privacy philosophy and is technically unreliable (recipient may be offline)
• Via REST we get information about the block that includes the transaction. First we show ✅ Delivered to node, then ⚭ In blockchain.
• In the future, we’ll add socket subscriptions to transaction-in-block events

Outgoing messages

• Outgoing messages flow:
  1. ⏳ Sending
  2. ✅ Delivered to node
  3. ⚭ In blockchain (as soon as the block is known, via socket or REST).
• Transition from ⏳ Sending → ✅ Delivered to node must happen quickly for a smooth UI experience
• ❌ Not sent appears if delivery to the node fails or the blockchain rejects the transaction
• Statuses update in both chat list and chat view

Cryptocurrency Transfers and Status Checks

• For all crypto transfers, ADAMANT displays the transaction status in the token’s own blockchain
  • Example: for DOGE transfer, we show the DOGE transaction status
  • Applies to both incoming and outgoing transfers
• Initial status: ⏳ Pending (sending/checking)
• Once node confirms the transaction exists: ⏳ Registered
• Then we keep checking until final status: ✅ Success or ❌ Failed

Reference: AIP-12

Transaction check rules per coin are defined in adamant-wallets (txFetchInfo).

Final Statuses

• ✅ Success — confirmed in the network
• ❌ Failed — rejected by network (cancelled, out of gas, etc.)
• ⚠️ Inconsistent — mismatch in transaction details

Transaction details view/screen

• ⏳ Generating transaction / Sending to node (~Pending) — shown as a "clock" icon briefly, then switches
• ⏳ Pending — transaction sent or detected in chat
• ⏳ Registered — seen on the node but not confirmed
• ✅ Success — final state
• ❌ Failed — final state
• ⚠️ Inconsistent — final state

Workflow: Pending → Registered → Success / Failed / Inconsistent.

Special Notes for ADM Transactions

• ADM status comes directly with the transaction:
  • If confirmations > 0 → ✅ Success
  • If confirmations = 0 → ⏳ Pending or Registered

Reliability and Edge Cases

• For other blockchains, status checks require additional node/API requests
• Issues that may occur:
  • Unconfirmed transactions appear with delays on some nodes
  • Nodes may temporarily not return old transactions, responding only after repeated requests
• To handle this, ADAMANT uses a background status check mechanism:
  • Only checks statuses of transactions visible to the user
  • Stops once a final status is received
  • Check frequency depends on transaction age (New vs Old)
  • Limited attempts for ⏳ Pending; unlimited for ⏳ Registered
  • Checks only when a network connection and coin nodes are available (to avoid “wasting” attempts offline)

Determining Transaction State (New/Old)

This classification is only relevant for Pending transactions, as it helps decide:

• The appropriate check interval
• How many attempts should be made to verify the transaction

Rules

1. Any transaction just broadcast from your app is automatically considered New
2. Other transactions (incoming/outgoing):
   • Check the transaction’s timestamp:
     • In chats: the timestamp comes from the ADM message containing the transaction ID
     • In transaction lists: the timestamp is provided by the indexer along with other transaction data
   • Old transaction: if the timestamp is older than X minutes compared to the current time
   • New transaction: if the timestamp is within the last X minutes (e.g., a freshly received BTC transfer in a chat)

Choosing X interval

• X may be a static constant (e.g., 5 minutes)
• Preferably, it should be calculated for each coin separately, for example:

const isNew = (admTransferTimestamp) =>
  Date.now() - admTransferTimestamp < newPendingTxFetchAttempts * newPendingTxFetchInterval;

Why This Matters

This distinction ensures efficient polling behavior:

• Newer transactions require more frequent checks
• Older transactions can be verified less aggressively

Example: Bitcoin Transfer

Constants from adamant-wallets:

"txFetchInfo": {
    // Interval between fetching Tx in ms when its current status is
    "newPendingInterval": 10000, // "Pending" for new transactions
    "oldPendingInterval": 3000, // "Pending" for old transactions
    "registeredInterval": 40000, // "Registered"

    // Attempts to fetch Tx when its current status is `Pending`
    "newPendingAttempts": 20, // for new transactions
    "oldPendingAttempts": 3 // for old transactions
  },

Transaction Statuses (once again)

• Pending — After signing and broadcasting to a node, but not yet seen in the mempool/network
• Registered — Detected by a node (even with 0 confirmations)
• Confirmed — Included in a block (≥1 confirmation)
• Failed — Not accepted by the network (e.g., dropped from mempool, invalid, or not found after repeated checks)

Checking Logic for Pending Transactions

New Pending TX (just sent):

• Check interval: every 10 seconds (newPendingInterval)
• Max attempts: 20 (newPendingAttempts)
• Total time window: ~200 seconds (~3.3 minutes)
• If detected by a node (even with 0 confirmations) → mark as Registered
• If still not seen by a node after all attempts → mark as Failed

Registered Transactions

• Check interval: every 40 seconds (registeredInterval)
• Attempts: Unlimited (until Confirmed or Failed)
• Success: when ≥1 confirmation → Confirmed
• Failure: if node returns an error for this transaction

Re-checking Statuses (UI/UX)

• On user action (clicking the ❌, ✅, or ⚠️ icons in chat), the transaction is reset to Pending and re-checked again
• This applies to transfers of all cryptocurrencies

Storage Notes

• Transaction statuses are not stored when logging in with password, PIN, or fingerprint
• On login with password, statuses are re-checked from scratch

Inconsistency

We mark a transfer as Inconsistent when there’s a mismatch between the transfer data recorded in the ADAMANT message and the data retrieved from the token’s blockchain. A transfer is considered inconsistent if any of the following holds:

1. Amount differs by more than a small tolerance (≈ 0.1–0.5%)
2. Sender address differs
3. Recipient address differs
4. Timestamp mismatch: the message time and the blockchain transaction time differ by more than 3 hours

Special “non-standard” statuses

5. Unsupported coin

The coin is not supported by the app, so we cannot verify the transfer (e.g., xrp_transaction).

Behavior: tapping such a transaction does not open details; show a snackbar/popup: Cryptocurrency is not supported yet.

6. Duplicate transaction hash

A critical case. Example: you send 1 BTC and post the corresponding ADM transaction in chat → it’s valid and becomes Success. Immediately after, another ADM message is sent with the same TX hash for 1 BTC. All checks (1–4) pass again, so it would also become Success—making it look like 1 + 1 = 2 BTC were sent.

Mitigation:

• Perform a duplicate-hash check against already loaded transactions (that’s sufficient because the vulnerability exists only within a short time window)
• If the duplicate-hash check fails, mark the transaction as ⚠️ Inconsistent

Status updates propagate both in the chat list and inside the chat.

Inconsistency Reasons (Table)

Priority	English	Русский
1	Incorrect transaction hash. Be aware of fraud.	Неверный хэш транзакции. Остерегайтесь мошенников.
2	Duplicated transaction. This {crypto} transfer appeared in chat earlier. Be aware of fraud.	Транзакция повторяется. Этот перевод {crypto} уже встречался в чате ранее. Остерегайтесь мошенников.
3	The sender’s {crypto} address differs. Be aware of fraud.	{crypto}-адрес отправителя не сходится. Остерегайтесь мошенников.
4	The recipient’s {crypto} address differs. Be aware of fraud.	{crypto}-адрес получателя не сходится. Остерегайтесь мошенников.
5	Wrong {crypto} amount. Be aware of fraud.	Неверное количество {crypto}. Остерегайтесь мошенников.
6	Unable to retrieve the sender’s {crypto} address.	Нет {crypto}-адреса отправителя.
7	Unable to retrieve the recipient’s {crypto} address.	Нет {crypto}-адреса получателя.
8	The message and {crypto} transaction timestamps differ significantly. A few seconds is typical; this gap is unusually large. Please double-check.	Сообщение и {crypto}-транзакция имеют заметную разницу во времени. Небольшая задержка возможна, но эта слишком велика — перепроверьте.
9	Failed to check the transaction. Something went wrong.	Не удалось проверить транзакцию. Что-то пошло не так.

{crypto} is a placeholder for the asset ticker (e.g., BTC, ETH).

UI demo for Transfer statuses

DASH In-Chat PWA-dev v4.9.0 3G — 2025-03-04

After tap on “Confirm transfer”, Status is Unknown/ ⏳ ~10 sec	Tx is shown in chat as Pending	Tap on Tx details → Status is Pending ~2 min
Status is Confirmed with no details ~5 sec	Status is Confirmed with details — Final

DASH In-Chat iOS v3.11.0 (3) TestFlight — 2025-03-04

After tap on “Send” (confirm), Status is Unknown/ ⏳ ~3 sec	Tx is shown in chat as Pending ~0 sec	Automatically go to Tx details ⟶ Status is Pending ~2 min
Status is Confirmed with no details ~0 sec	Status is Confirmed with details — Final
(I wasn’t so fast to take a screenshot)

[metalisk]

Amazing contribution,
Thanks for the detailed description and screenshots.

[metalisk]

My contribution to this topic:
In-Chat and Direct Crypto Transfers in ADAMANT https://github.com/orgs/Adamant-im/discussions/31