@capytime/tlock

Time-lock encryption library based on drand distributed randomness beacon. Lock messages until a specific time using cryptography - the key literally doesn't exist until time arrives.

Features

• True Time-Lock: Messages can only be decrypted after a specified time
• Cryptographic Guarantee: Uses drand network - even we can't decrypt early
• No Server Required: Decryption uses public drand network data
• Browser & Node.js: Works in both environments
• Same as Capytime APP: Uses identical algorithm for interoperability

Installation

npm install @capytime/tlock
# or
yarn add @capytime/tlock
# or
pnpm add @capytime/tlock

Quick Start

Encrypt Text

import { encryptText, decryptText, checkUnlockStatus } from '@capytime/tlock';

// Encrypt a message that unlocks in 1 hour
const unlockTime = Math.floor(Date.now() / 1000) + 3600;
const encrypted = await encryptText('Hello, Future!', unlockTime);

console.log(encrypted);
// Output: TLOCK://v1/eyJyb3VuZCI6MTIzNDU2Ny...

Check Status

const status = checkUnlockStatus(encrypted);

console.log(`Can unlock: ${status.canUnlock}`);
console.log(`Target round: ${status.targetRound}`);
console.log(`Current round: ${status.currentRound}`);
console.log(`Remaining: ${status.remainingSeconds}s`);
console.log(`Unlock time: ${status.unlockTime}`);

Decrypt (After Unlock Time)

// This will throw an error if called before unlock time
const decrypted = await decryptText(encrypted);
console.log(decrypted); // "Hello, Future!"

Using Date Objects

// Unlock at a specific date/time
const unlockDate = new Date('2025-12-31T23:59:59Z');
const encrypted = await encryptText('Happy New Year!', unlockDate);

API Reference

Core Functions

encryptText(message, unlockTime, options?)

Encrypts a text message with time-lock.

• message: String to encrypt
• unlockTime: Unix timestamp (seconds) or Date object
• options.network: DrandNetwork config (default: QUICKNET)
• Returns: Promise<string> - TLOCK:// formatted ciphertext

decryptText(tlockString, options?)

Decrypts a time-locked message. Throws if called before unlock time.

• tlockString: TLOCK:// formatted ciphertext
• options.network: DrandNetwork config
• Returns: Promise<string> - Decrypted message

encrypt(data, unlockTime, options?)

Encrypts binary data with time-lock.

• data: Uint8Array to encrypt
• unlockTime: Unix timestamp (seconds)
• Returns: Promise<TimelockCiphertext>

decrypt(ciphertext, options?)

Decrypts binary time-locked data.

• ciphertext: TimelockCiphertext object
• Returns: Promise<Uint8Array>

checkUnlockStatus(tlockStringOrCiphertext, network?)

Checks if a ciphertext can be decrypted.

• Returns: UnlockStatus object

Network Configuration

import { QUICKNET, MAINNET } from '@capytime/tlock';

// QUICKNET (default): 3 seconds per round, for development
// MAINNET: 30 seconds per round, for production

const encrypted = await encryptText('message', unlockTime, {
  network: MAINNET
});

Time Utilities

import {
  timeToRound,
  roundToTime,
  getCurrentRound,
  getRemainingSeconds
} from '@capytime/tlock';

// Convert Unix timestamp to drand round
const round = timeToRound(1735689599);

// Convert round back to timestamp
const timestamp = roundToTime(round);

// Get current drand round
const current = getCurrentRound();

// Calculate remaining seconds
const remaining = getRemainingSeconds(round);

Low-Level API

For advanced use cases, you can access the underlying cryptographic primitives:

import {
  ibeEncrypt,
  ibeDecrypt,
  aesGcmEncrypt,
  aesGcmDecrypt,
  fetchBeacon,
  parseG2PublicKey,
} from '@capytime/tlock';

Algorithm

This library implements time-lock encryption using:

| Component | Implementation | |-----------|---------------| | Elliptic Curve | BLS12-381 | | Identity Encryption | Boneh-Franklin IBE | | Symmetric Encryption | AES-256-GCM | | Time Beacon | drand Quicknet |

How It Works

1. Encrypt: Convert unlock time to drand round number, use IBE to encrypt a symmetric key to that round, then encrypt data with AES-GCM
2. Time Passes: Wait for drand network to reach target round
3. Decrypt: Fetch drand signature for the round, recover symmetric key via IBE, decrypt data

The key insight: drand produces BLS signatures on round numbers. Before the round arrives, no one (not even drand operators) knows the signature. This signature becomes the private key for IBE decryption.

Interoperability

Ciphertexts produced by this library are compatible with:

• Capytime APP (iOS/Android)
• Capytime Web (capytime.com/encrypt)
• Other implementations using the same drand Quicknet + IBE scheme

Security

• No Early Decryption: Mathematically impossible before time arrives
• Decentralized: drand network is operated by Cloudflare, Protocol Labs, and others
• Audited Cryptography: Uses @noble/curves library

License

MIT © Capytime Team

Links

• Capytime Website
• drand Network
• BLS12-381 Curve