REST API

Accepts a new SHA-256 hash to be witnessed in the timechain and returns a crum as reciept. (A crum is a tuple consisting of a 32-byte hash, and an 8-byte UTC witness time). The returned crum may be later used to retrieve a crumtrail via the "update" method. The HTTP response is 202.

This method is idempotent over the duration of a [timechain] block. (The no. of blocks this idempotency is in effect can be configured in the timechain settings, but there's no reason to, since increasing it negatively impacts scalability, but does not offer any tangible user benefit.)

In rare cases (a race between clients), this method may return a 200 response with a fully constructed crumtrail (see update). To cover such corner cases, the optional query string parameters the update method takes, may also be supplied.

Retrieves the crumtrail for the given crum (previously received via the witness method), if the crum's block no. has been committed to the timechain; otherwise, if the crum is valid (is scheduled to be committed to the timechain), then the crum is returned as-is. Finally, if the crum is not valid (is expired, or made up), then this method defaults to the witness method.

Returns a block proof asserting the hash of a block at some no. is derived from the hash of blocks at lower no.s. If no arguments are provided, a block proof linking the genesis to the latest block is returned.

Returns the chain paramaters and notary policy settings. These are constant, static values over a typical session. The chain parameters (inception UTC, time-bin resolution) are in fact immutable, but other policy settings may be adjusted over the life of a timechain. While the JSON response is meant to be parsed by software, it's somewhat human readable:

• incept_utc - Starting UTC of genesis block, in milliseconds.
• bin_exp - Block durations (in milliseconds) and block time boundaries are modeled by powers of 2. This value, called the "bin exponent" defines which power of 2 is used for the time binning. Examples:
  • 10: 2¹⁰ = 1024 (millis) ~ 1 second
  • 16: 2¹⁶ ~ 1 minute, 6 seconds

The bin exponent also delineates block time boundaries. For a given block, the minimum (big endian) UTC value has its rightmost bin_exp-bits set to 0 (zero), while all eligible UTC values in the block share the same remaining leftmost bits; and the maximum UTC value in the block has its rightmost bin_exp-bits set to 1 (one).

• block_commit_lag - No. of (wall time) milliseconds post a time block before it becomes eligible to be committed. This, in turn, defines the minimum time that must elapse before a witnessed hash can be updated to become a crumtrail.
• blocks_searched - When witnessing a new hash, a service may guarantee it hasn't seen that same hash within a certain window of blocks. In most cases, this "feature" is unnecessary and may even be set to zero.
• blocks_retained - Crumtrails are kept around for this many blocks after their hashes are committed to the chain: after that they are purged.

Verifies the given URL-encoded crumtrail is committed to the timechain. The response (in JSON) is the same crumtrail, but with its block proof patched to the most recent state of the chain. A human readable summary precedes the crumtrail's JSON.

This method primarily exists so that a crumtrail may be archived as a bookmark. See the crum CLI tool for archiving crumtrails from multiple timechains.

Hash encoding translator. Converts hex to b64, and viceversa. The Base64 encoding is non-standard The response is plain text.

About b64

This is slightly non-standard Base64 encoding. It uses the URL / filename-friendly character-set specified in §5 of RFC 4648 but takes liberties (discussed tho not condoned in §3.2) for specifying boundary conditions in a way that does not require padding for our use case. Unlike in some other variants, padding bits must be set to '0', so as to preserve one-to-one-ness, and are pre-pended (two '0' bits), not post-pended.