Home

Awesome

tlock-js

A typescript library for encrypting data which can only be decrypted at a set time in the future using drand.
tlock-js uses AGE to symmetrically encrypt a payload, and encrypts the symmetric key using pairing-based cryptography ensuring that it can only be decrypted when the drand's threshold network has generated randomness at a future point.

Prerequisites

Quickstart

Using it as a library

Note: early versions of node may need to pull in a fetch polyfill; versions 17+ have fetch already, but it may be behind the --experimental-modules flag.

Test our Web demo

We have a live web-demo relying on this library to allow you to test Timelock encryption/decryption directly in your browser now by visiting Timevault. Everything is done locally in your browser and it only fetches the drand beacons it needs to decrypt your ciphertexts, nothing else, no logging, no nothing.

API

timelockEncrypt

This encrypts a payload that can only be decrypted when the roundNumber has been reached.
The time of this roundNumber depends on the genesis and round frequency of the network you connect to. By default, the drand testnet HTTP client will be used, but you can implement your own and pass it in here. The output ciphertext should be compatible with any of the drand tlock implementations

timelockDecrypt

This takes a payload that has been encrypted with any of the drand tlock implementations, reads the roundNumber from it and attempts to decrypt it. If the round number has not yet been reached by the network, an error will be thrown. It accepts both armored and unarmored payloads.

roundForTime

Given a NetworkInfo object, it calculates what the latest-emitted round will have been at that time

timeForRound

Given a NetworkInfo object, it calculates the approximate time the given round will be emitted at (approximate because the network must work together to create the randomness).

Possible issues

export default {
   build: { target: "es2020" },
   optimizeDeps: {
       esbuildOptions: { target: "es2020", supported: { bigint: true } },
   },
};

npm packaging

The github actions create a dist folder and move the package.json and some other bits in order to do some packaging, thus running npm pack in the root dir will not give the expected results. Similarly, the main, module and types keys in the package.json are relative to the dist dir.


Get in touch


License

This project is licensed using the Permissive License Stack which means that all contributions are available under the most permissive commonly-used licenses, and dependent projects can pick the license that best suits them.

Therefore, the project is dual-licensed under Apache 2.0 and MIT terms: