An Ephemeral BitDB for Dealing with Time

Jan 16, 2019 · 7 min read
Image for post
Image for post

Today I present Chronos, a new BitDB node that breaks all the rules of BitDB.

As a result, it gets its hands on what has been out of reach: Time.

Image for post
Image for post

Here’s how Chronos is different:

  1. A Timestamp for Every Transaction: Every transaction has a timestamp of when they were discovered (not when they were mined into a block)
  2. Even Mempool: Even Mempool transactions have a timestamp (This is not the case for other BitDB nodes)
  3. Ephemeral: 24 hour sliding window of transaction storage
  4. One collection: All transactions stored in a single chronological collection, regardless of confirmed or unconfirmed.
  5. Dynamic attribute: Has a dynamically computed virtual attribute named timeago

Chronos was designed for dealing with time, which used to be impossible with existing BitDBs.

To understand why this has been impossible, we must first understand how the existing system works. Let’s take a look at how the concept of “Time” works in Bitcoin land.

How Time Flows in Bitcoin Wonderland

Think of Bitcoin as a parallel universe. In this Bitcoin world, time flows differently than the outside world we live in. So if Alice wants to visit this Bitcoin wonderland, she’d better be very conscious about the rules. Otherwise she may face a totally unexpected reality when she comes back to her real world.

Image for post
Image for post

Here are the rules:

  1. A block is the minimal unit of time.
  2. Everything that happens within a single block should be considered to have happened SIMULTANEOUSLY.
  3. Until transactions get mined into a block, they didn’t happen.

For example, just because one transaction is sent to Bitcoin earlier than another transaction, doesn’t mean it will be mined earlier.

Also, just because a transaction appears later within the blockchain than another transaction, doesn’t mean that transaction was sent later. It could have just propagated slowly, or may have stayed in the mempool for a long time before finally getting mined.

So when thinking about time in Bitcoin:

  1. Think of Bitcoin as a clock, where every new block is a tick.
  2. Treat every transaction within the same block as simultaneous.
  3. Don’t try to determine which transaction was SENT earlier based on when a transaction was DISCOVERED, because it will vary across all nodes.

How Other BitDB Nodes Deal with Bitcoin’s Rules of Time

Before we discuss Chronos, let’s look at how other existing BitDB nodes deal with time, abiding by the rules mentioned above (This includes Genesis and Babel).

1. Block

Transactions mined into a block all have a blk attribute, which contains 3 child attributes:

  1. i: Block index (height)
  2. h: Block hash
  3. t: Block time (in unix timestamp)

One thing to remember is that EVERY transaction in the same block has EXACTLY the same blk attribute.

This means you can’t tell which transaction in a block was SENT earlier than another transaction in the same block. You can’t even tell which was DISCOVERED earlier through BitDB because they all have the same timestamp.

Image for post
Image for post

2. Mempool

In case of mempool, there is no such thing as a blk attribute.

As you can see below, there is no time related attribute. Mempool transactions are not yet mined into a block so there is no timestamp assigned by BitDB, following the “rules of time in Bitcoin” discussed above.

Image for post
Image for post


Now let’s look at Chronos. It is primarily designed for dealing with Time. As you can see below, there are two new attributes: timeago and timestamp.

Image for post
Image for post

Let’s walk through each notable feature:

1. A Unix Timestamp for Every Transaction

Image for post
Image for post

There’s a new attribute called timestamp. This is the Unix timestamp of when the transaction was discovered.

  1. Unlike the existing BitDB nodes that ONLY store the timestamp of its parent block, every Chronos transaction has its own timestamp, all different.
  2. Also, now even the mempool transactions have a timestamp.

2. Virtual Attribute

Image for post
Image for post

There’s another attribute called timeago.

This one is special because it’s not actually stored in the database (Otherwise it will become outdated every time you reload the page because “1 minute ago” will no longer be “1 minute ago”). Instead, it’s computed from the timestamp attribute in realtime when the query engine returns the result.

The caveat is, you can’t query using this attribute, this is just an attribute that’s computed in realtime and displayed to you. If you want to query by timestamps, use the timestamp attribute.

3. No distinction between block and mempool

This is another feature that breaks the rules of BitDB. Until now, all BitDB nodes have kept confirmed (block) and unconfirmed (mempool) transactions as two separate collections (c for confirmed and u for unconfirmed).

Chronos only has a single collection named t.

At first, incoming mempool transactions get inserted into the database. And when the same transaction gets added to a block, the entry gets updated to have the blk property (the block info).

So when you see a transaction without a blk attribute, you know it’s in the mempool.

Image for post
Image for post

4. Ephemeral

Chronos has a 24 hour sliding window policy.

All transactions get wiped out after 24 hours have passed.

Image for post
Image for post

This is a deliberate decision to reinforce the purpose of Chronos:

  1. Chronos is not meant to be used as a standalone (although you could if it fits your purpose), but as a complement to other BitDB nodes.
  2. Chronos by default is not meant to be used for mission critical applications, for the reasons discussed above (IF you want to use it for mission critical applications, you can use various second layer techniques such as cross referencing with other BitDB nodes, but this is out of scope of this article)

What is It For?

So when IS it useful? Let me give you a quick example.

Let’s look at Memo is a social network built on top of Bitcoin OP_RETURNs. Each post is a transaction that contains an OP_RETURN script output, which contains the human readable message. So each post you’re seeing below is a Bitcoin transaction.

Image for post
Image for post

But there’s a caveat. These timestamps in the red circles are NOT from the blockchain. These are the timestamps of when the node “discovered” each user post.

With existing BitDB nodes, something like this was impossible (because they were too “principled” at following Bitcoin’s rules).

But with Chronos, you can easily parse bitcoin OP_RETURN transactions and sort and display them by timestamp within your own application UI.


Chronos is still uses the same Bitquery just like Genesis BitDB and Babel BitDB.

Also, the schema is pretty much the same, except for the additions and the collection structure mentioned above. So not much has changed in terms of querying. You just get more data.

So if this is the first time learning about BitDB, you may want to first learn BitDB itself first:

And if you’re ready to try Chronos, head over to Chronos explorer and play with it.

The API endpoint is:

which means your queries will look like this:[BASE64_ENCODED_BITQUERY]


Chronos is a new type of BitDB node that makes an interesting tradeoff to provide a feature that can be helpful for many developers when used with care.

More specifically, it’s a Bitcoin database that lets you deal with Time, by attaching timestamps to every single transaction.

Some of you may think this is the most interesting BitDB released so far. Some of you may not get it yet (If you don’t get it yet, try thinking deeply about each feature and you may get where this is headed).

Regardless, being able to use real world timestamps is a really nifty feature and have been one of the most frequently requested features since the beginning of BitDB, so I’m sure many of you will get it.

And if you have questions or need help, join the slack channel:

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store