implement block timestamp helper functions

- add blockTime helper to get a block's timestamp or estimated mining
date
- implement a boolean helper that allows for different language
depending on whether the block in question has been mined or not.

src/helpers/blockTime.js

@@ -0,0 +1,29 @@
+const MILLISECONDS_IN_A_SECOND = 1000
+
+export const blockTime = (eth) =>
+  async (blockNumber, showBlock = true, averageBlockTime = 13.965) => {
+    let timestamp
+    const currentBlock = await eth.getBlockNumber()
+
+    if (currentBlock >= blockNumber) {
+      timestamp = (await eth.getBlock(blockNumber)).timestamp * MILLISECONDS_IN_A_SECOND
+    } else {
+      const { timestamp: currentTimestamp } = await eth.getBlock(currentBlock)
+      const blockDuration = (blockNumber - currentBlock) * averageBlockTime
+      timestamp = (currentTimestamp + blockDuration) * MILLISECONDS_IN_A_SECOND
+    }
+
+    return {
+      type: 'string',
+      value: `${new Date(timestamp).toDateString()}${showBlock ? ` (block number: ${blockNumber})` : ''}`
+    }
+  }
+
+export const isBlockMined = (eth) =>
+  async (blockNumber) => {
+    const currentBlock = await eth.getBlockNumber()
+    return {
+      type: 'bool',
+      value: currentBlock >= blockNumber
+    }
+  }

src/helpers/index.js

@@ -6,6 +6,7 @@ import formatPct from './formatPct'
 import tokenAmount from './tokenAmount'
 import transformTime from './transformTime'
 import radspec from './radspec'
+import { blockTime, isBlockMined } from './blockTime'
 
 const defaultHelpers = {
   formatDate,
@@ -14,7 +15,9 @@ const defaultHelpers = {
   formatPct,
   fromHex,
   radspec,
-  echo
+  echo,
+  blockTime,
+  isBlockMined
 }
 
 export {
@@ -27,5 +30,7 @@ export {
   fromHex,
   radspec,
   transformTime,
-  tokenAmount
+  tokenAmount,
+  blockTime,
+  isBlockMined
 }

test/examples/examples.js

@@ -359,6 +359,18 @@ const cases = [
     source: "`_bool ? 'h' + _var + 'o' : 'bye'`",
     bindings: { _bool: bool(true), _var: string('ell') }
   }, 'hello'],
+  [{
+    source: 'get a past date: `@blockTime(block, showBlock)`',
+    bindings: { block: int('8765432'), showBlock: bool(false) }
+  }, 'get a past date: Fri Oct 18 2019'],
+  [{
+    source: 'get a future date: `@blockTime(block)`',
+    bindings: { block: int('20976543') }
+  }, 'get a future date: Wed Mar 19 2025 (block number: 20976543)'],
+  [{
+    source: 'see if block is mined: `@isBlockMined(block)`',
+    bindings: { block: int('98765430') }
+  }, 'see if block is mined: false'],
 
   // External calls with multiple return values
   [{