Diff time and timereceived in gettransaction, bitcoin core JSON API?

[Cryptowatch.com]

TL;DR: What's the difference between 'time' and 'timereceived in a bitcoin transaction and which one to use when the aim is to get the time of the transaction when it was broadcast to the network?


After searching a bit online I was still unable to find a good answer.

Software: Bitcoin-0.10.1

When doing bitcoin-cli gettransaction TXID I get a json result set which contains 'time' and 'timereceived'.

When doing bitcoin-cli help gettransaction I get:

Code:

 "time" : ttt,            (numeric) The transaction time in seconds since epoch (1 Jan 1970 GMT)
 "timereceived" : ttt,    (numeric) The time received in seconds since epoch (1 Jan 1970 GMT)

Looking at listtransactions 'time' and 'timereceived' is always the same.

I thought that 'time' and 'timereceived' might be different and one represented the time when the transaction was received (ie. user initiates the transaction with sendtoaddress), and the other one representing when the transaction is actually done.

I ran testnet with 0 connections and issued a transaction, then shut it down, waited a little, and restarted the daemon. When the transaction was finally broadcast, the 'time' and 'timereceived' was still identical.

The question then becomes: What are the difference between 'time' and 'timereceived'? What I'm looking at it is to get the time when the transaction was broadcast to the network. The help text did not enlighten me. Instead of me spending a lot of time pouring through the source code to figure this out, perhaps someone smarter than me is able to enlighten me?

Also, if those values are always identical (could not be?), then we would not need both? As there's many bright minds looking at the code, I doubt this is an oversight.

[tspacepilot]

This is just a guess, but if I'm wrong then perhaps it will help spur discussion.  First, I note that I don't find any reference to "timereceived" looking quickly through bitcoin-core/src/primitives/transaction.h and transaction.cpp.  So, perhaps timereceived is a property that each client computes for itself.  Then, perhaps for for the majority of transactions, a client receives them when it downloads the blockchain so it simply uses the transaction's "time" as a standin for "timereceived".  If this hypothesis is correct, perhaps on new transaction that you didn't download in your initial sync you'd see a difference.

Here's another guess: perhaps once a transaction is included in the blockchain then timereceived is set to = time but before then they are unequal.  This would allow you to find unincluded transactions by looking for ones in which timereceived wasn't equal to time.

So, perhaps my guesses will get someone with more knowledge to appear and correct me

[shorena]

Im actually surprised that this was included as AFAIK transactions never had any timestamps in the past. I had to wait till Im home to test this as my server is not yet updated to 0.10.1.

this is what I got when requesting the latest TX

Code:

-snip-
"time" : 1430280730,
"timereceived" : 1430285648,
-snip-

These correspond to today 04:12:10 and today 05:34:08

Since Im in CEST (+2) the later time would be when I started the wallet this morning for syncing. The first value fits the timestamp from the block the TX is in[1]. Thus my assumption is:

"time" is the timestamp from the block
"timereceived" is when the wallet learned about the transaction

[1] https://www.blocktrail.com/btc/block/00000000000000000d738b104eec646bef5755a16cc189a2781417bc3985fd01

[DannyHamilton]

- snip -
AFAIK transactions never had any timestamps in the past.
- snip -

They still don't.

There are no timestamps in the actual transactions.  However, a wallet can choose to keep track of when it sends a transaction, when it first hears of a transaction from a peer, and when it first a block that contains the transaction, and what the timestamp is on the block that contains the transaction.  What the wallet does with this information is implementation dependent.  It is also important to understand that the only timestamp that you can count on being consistent between multiple wallets will be the timestamp in the block that contains the transaction.

[Cryptowatch.com]

Ok, I found the answer in the documentation.

https://bitcoin.org/en/developer-reference#gettransaction

As prev. mentioned:

When doing bitcoin-cli help gettransaction I get:

Code:

"time" : ttt,            (numeric) The transaction time in seconds since epoch (1 Jan 1970 GMT)
 "timereceived" : ttt,    (numeric) The time received in seconds since epoch (1 Jan 1970 GMT)

However, the docs says:

Name: time    
Type: number (int)    
Presence: Required (exactly 1)    
Description: A Unix epoch time when the transaction was added to the wallet

Name: timerecived [sic]
Type: number (int)
Presence: Required (exactly 1)
Description: A Unix epoch time when the transaction was detected by the local node, or the time of the block on the local best block chain that included the transaction

So for all intents and purposes when sending bitcoins from the local node, 'time' should be sufficient to determine when the user sent the coins, as a send transaction, to my understanding is immediately deducted from the wallet-balance when sendtoaddress is used. Just tested this, so it can be confirmed such is the case.

Perhaps the help text in bitcoin-cli should be updated to be more in line with the 'developer-reference'?

Also, for 'time',  A Unix epoch time when the transaction was added to the wallet. Is this the same for both 'send' and 'receive' transactions? What is the definition of 'added' in this context? I'm not sure but I think bitcoin core needs 1 confirmation to make funds available (ie. showing in the balance). However, when I sent a small amount of testnetcoins to one of my nodes from a remote node, the 'time' and 'timereceived' is still the same, so I assume 'added to wallet' means that the transaction was added to the wallet the moment it was received, even if it sat at 0 confirmations.


But A Unix epoch time when the transaction was added to the wallet and  A Unix epoch time when the transaction was detected by the local node seems to me to be equal statements?

In which scenarios would 'time' and 'timereceived' differ? I checked 'listtransactions' for a couple of test-nodes of mine (on different subnets), and 'time' and 'timereceived' always was equal, both for 'send' and 'receive' transactions.

It seems then that the only way 'time' and 'timereceived' could be non-equal was if the time of the block on the local best block chain that included the transaction determined the unix epoch time of the latter.