Some notes about Transaction publishing, normalization, verification, and broadcast on ADM node

[adamant-al]

Functions

• Transaction.prototype.verify — checks a transaction retrieved from other blocks; may include old transactions.
• Transactions.prototype.publish — checks incoming transactions from users, verifying "fresh" unconfirmed transactions.

verify is also called after receiving a new transaction from the API, following the publish and objectNormalize methods. publish is only called when pushing transactions via the public API.

Transaction processing

Receiving a new tx from a client app via API (it's the first node that sees the tx):

1. Logic->Transaction.prototype.publish creates a new transaction from the received data, validates the client's transaction properties (including timestampMs), and adds a transaction ID.
2. Processes the unconfirmed transaction (see the flow below) as usual.

Receiving a new tx from another peer at the current height:

1. Validates the transaction (see below). If it's invalid, removes the peer.
2. Processes the unconfirmed transaction as usual (see the flow below).

Fetching a tx from another peer when arising/verifying the blockchain from height 0:

1. Validates the transaction (see below). If it's invalid, removes the peer.
2. Processes the unconfirmed transaction as usual (see the flow below) but verifies multiple transactions at a time.

Validating transaction:

1. A node only calls objectNormalize() for schema validation of a received transaction.

Processing an unconfirmed transaction flow:

1. First, logic.transaction.process() is called. It verifies the transaction ID and normalizes the sender ID.
2. Then, the transaction is normalized. The logic.transaction.objectNormalize() method validates the transaction object against a schema and removes unnecessary properties, including timestampMs before spaceship activation.
3. Finally, logic.transaction.verify() is called, verifying all properties such as timestamp, timestampMs, signature, etc.

Notes and Q/A:

• Removing the peer means removing a peer from the peer list until it rediscovers the peer again. Nodes do not ban peers (BANNED status is never applied).
• When does a node broadcast a tx to other nodes? After the "Processes the unconfirmed transaction as usual" step.
• Besides objectNormalize(), node has normalize(). The normalize() method is only used for POST /transactions/normalize endpoint that should be deprecated.
• Why does node have both apply() and applyUnconfirmed()? "apply" methods change balances of the sender and recipient accounts. applyUnconfirmed() changes unconfirmed balance. Same goes for "undo" methods.
• When a node generates a new block, the transactions are taken from an already verified list
• Currently we have these checks in publish():
  • Transaction timestamp is in the future
  • Transaction timestamp is more than ${constants.maxTransactionAgeSec} seconds in the past
• There is no point in adding the same checks in the publish method as in verify because the latter MUST be called after publish. Also, we can't include publish's checks in the verify method because they depend on the current time. It's impossible to verify whether an old transaction is no more than 5 seconds old.
• Will a client app receive an error text The difference between timestamp and timestampMs is greater than ${maxTimestampMsDelta}ms. or Invalid transaction timestamp. Timestamp is not in the int32 range if it's not in publish() but in verify()? Yes.

Timestamp notes

• Transaction timestamp is ADAMANT epoch time in seconds, not Unix time.
• Transaction timestampMs should be ADAMANT epoch time in milliseconds, not Unix time. Unix milliseconds can be derived as constants.epochTime.getTime() + timestampMs.
• timestampMs is not part of transaction bytes, signatures, transaction IDs, or hashes, including after the spaceship activation.
• After spaceship, consensus-sensitive validation should require timestampMs to be in the same ADAMANT epoch second as timestamp: 0 <= timestampMs - timestamp * 1000 < 1000.
• The stricter same-second rule is intentional. timestampMs must refine the exact same ADAMANT epoch second stored in timestamp; clients should compute timestamp = Math.floor(timestampMs / 1000). Using Math.round() or Math.ceil() near a second boundary creates an inconsistent pair and should be rejected.
• Current client/source review: adamant-api-jsclient uses getEpochTime() with Math.floor; PWA uses adamant.epochTime()/transaction signing with Math.floor; adamant-console delegates transaction creation to adamant-api@2.4.0, whose getEpochTime() also uses Math.floor; iOS builds outgoing NormalizedTransaction.timestamp by converting the positive ADAMANT epoch interval to UInt64, which truncates fractional seconds and is equivalent to floor for current transactions; docs examples use Math.floor; schema contains no client-side timestamp generation logic. No outgoing ADM transaction timestamp generation path using round or ceil was found.
• Before spaceship, consensus-sensitive normalization should remove timestampMs so pre-activation behavior stays compatible with older nodes.
• Multiple transactions from the same sender within one second are allowed as long as they are distinct transactions. timestampMs helps clients sort fast chat messages but must not become a transaction nonce or signature input.

Admission-time checks

• publish() contains public API admission checks for freshly submitted transactions. These checks may depend on the node's current clock.
• If a transaction passes publish(), it is still processed by verify(). verify() intentionally has no current-time check and should keep only deterministic checks: schema, id, signatures, balances, and the timestampMs same-second rule.
• Current-time checks from publish() must not be moved into verify() because verify() is used for replay, synchronization, and historical transactions.
• The existing future check is slot-based. With 5-second slots, a client clock ahead by about 400 ms only causes Transaction timestamp is in the future when the rounded seconds timestamp crosses into the next slot.
• maxTransactionFutureMs is a non-consensus public API admission tolerance. It should be applied only in publish(), not in replay, peer/block verification, or consensus activation logic.
• The intended condition is to preserve the old slot-based admission policy while softening the boundary case: reject only when transactionSlotNumber > currentSlotNumber and the transaction time is more than maxTransactionFutureMs ahead of the node's current time.
• For that calculation, use timestampMs when the client provided it; otherwise fall back to timestamp * 1000.
• A small non-consensus grace in publish() (for example, 500 ms for the next slot) can improve UX for slightly fast client clocks without changing replay validation. Client apps should still keep a small timestamp reserve for compatibility with older nodes.
• A transaction whose timestamp is one second ahead of the current block can still be included in that block. This does not break the blockchain: transaction timestamp is signed transaction metadata, not the source of slot or block validity, and consensus does not require tx.timestamp <= block.timestamp.
• During replay, nodes do not compare transaction timestamps with local wall-clock time, so the admission-time grace cannot create replay divergence.

Status endpoint

• /api/node/status may return additional clock fields such as nodeTimestampMs (ADAMANT epoch milliseconds) and unixTimestampMs without consensus impact.
• nodeTimestamp remains ADAMANT epoch seconds.

Activation heights

• Consensus activation heights should be configurable for testnet and ADAMANT-based chains while preserving mainnet defaults in code/config.
• The historical fairSystemActivateBlock: 4359464 check used height > fairSystemActivateBlock, so the equivalent first active height for a named fairSystem activation is 4,359,465.
• The spaceship activation should gate only consensus-sensitive behavior such as accepting, normalizing, storing, and validating timestampMs during block/peer/replay processing. Clock-relative publish() checks are admission policy and should remain outside consensus activation.

[adamant-al]

Further reading

• Add draft AIP for timestampMs transactions Add draft AIP for timestampMs transactions AIPs#62
• Fix: Complete timestampMs response and activation handling Fix: Complete timestampMs response and activation handling adamant#210