@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

``bash
npm install @capytime/tlock


or

yarn add @capytime/tlock

or

pnpm add @capytime/tlock
`

Quick Start

$3

`typescript
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...
`

$3

`typescript
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});
`

$3

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

$3

`typescript
// 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

$3

#### 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 - 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 - Decrypted message

#### encrypt(data, unlockTime, options?)

Encrypts binary data with time-lock.

- data: Uint8Array to encrypt
- unlockTime: Unix timestamp (seconds)
- Returns: Promise

#### decrypt(ciphertext, options?)

Decrypts binary time-locked data.

- ciphertext: TimelockCiphertext object
- Returns: Promise

#### checkUnlockStatus(tlockStringOrCiphertext, network?)

Checks if a ciphertext can be decrypted.

- Returns: UnlockStatus object

$3

`typescript
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
});
`

$3

`typescript
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);
`

$3

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

`typescript
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 |

$3

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