tlock-go

Time-lock encryption library for Go 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
• Same as Capytime APP: Uses identical algorithm for interoperability

Installation

go get github.com/capytime/tlock

Quick Start

Encrypt Text

package main

import (
    "context"
    "fmt"
    "time"

    tlock "github.com/capytime/tlock"
)

func main() {
    // Encrypt a message that unlocks in 1 hour
    unlockTime := time.Now().Add(1 * time.Hour)
    encrypted, err := tlock.EncryptText("Hello, Future!", unlockTime, nil)
    if err != nil {
        panic(err)
    }

    fmt.Println(encrypted)
    // Output: TLOCK://v1/eyJyb3VuZCI6MTIzNDU2Ny...
}

Check Status

status, err := tlock.CheckUnlockStatusFromString(encrypted, nil)
if err != nil {
    panic(err)
}

fmt.Printf("Can unlock: %v\n", status.CanUnlock)
fmt.Printf("Target round: %d\n", status.TargetRound)
fmt.Printf("Current round: %d\n", status.CurrentRound)
fmt.Printf("Remaining: %ds\n", status.RemainingSeconds)
fmt.Printf("Unlock time: %v\n", status.UnlockTime)

Decrypt (After Unlock Time)

ctx := context.Background()

// This will return an error if called before unlock time
decrypted, err := tlock.DecryptText(ctx, encrypted, nil)
if err != nil {
    panic(err)
}

fmt.Println(decrypted) // "Hello, Future!"

API Reference

Core Functions

EncryptText(message, unlockTime, opts) (string, error)

Encrypts a text message with time-lock.

• message: String to encrypt
• unlockTime: time.Time when decryption becomes possible
• opts: Optional EncryptOptions
• Returns: TLOCK:// formatted ciphertext string

DecryptText(ctx, tlockString, opts) (string, error)

Decrypts a time-locked message. Returns error if called before unlock time.

• ctx: Context for cancellation
• tlockString: TLOCK:// formatted ciphertext
• opts: Optional DecryptOptions
• Returns: Decrypted message

Encrypt(data, unlockTime, opts) (*TimelockCiphertext, error)

Encrypts binary data with time-lock.

• data: []byte to encrypt
• unlockTime: time.Time when decryption becomes possible
• Returns: TimelockCiphertext struct

Decrypt(ctx, ciphertext, opts) ([]byte, error)

Decrypts binary time-locked data.

• ciphertext: TimelockCiphertext struct
• Returns: Decrypted bytes

Network Configuration

import tlock "github.com/capytime/tlock"

// Quicknet (default): 3 seconds per round, for development
// Mainnet: 30 seconds per round, for production

encrypted, err := tlock.EncryptText("message", unlockTime, &tlock.EncryptOptions{
    Network: &tlock.Mainnet,
})

Time Utilities

import tlock "github.com/capytime/tlock"

// Convert Unix timestamp to drand round
round := tlock.TimeToRound(1735689599, tlock.Quicknet)

// Convert round back to timestamp
timestamp := tlock.RoundToTime(round, tlock.Quicknet)

// Get current drand round
current := tlock.GetCurrentRound(tlock.Quicknet)

// Calculate remaining seconds
remaining := tlock.GetRemainingSeconds(round, tlock.Quicknet)

// Format remaining time
formatted := tlock.FormatRemainingTime(remaining, "en") // "1h 30m 45s"

String Encoding

// Check if string is TLOCK format
if tlock.IsTlockString(encrypted) {
    // Parse TLOCK string
    ct, err := tlock.DecodeTlockString(encrypted)
    if err != nil {
        panic(err)
    }

    // Encode back to TLOCK string
    encoded, err := tlock.EncodeTlockString(ct)
}

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)
• @capytime/tlock (JavaScript/TypeScript)
• Other implementations using the same drand Quicknet + IBE scheme

Dependencies

• github.com/kilic/bls12-381 - BLS12-381 curve operations
• golang.org/x/crypto - Cryptographic utilities

Security

• No Early Decryption: Mathematically impossible before time arrives
• Decentralized: drand network is operated by Cloudflare, Protocol Labs, and others
• Audited Curve Implementation: Uses well-tested BLS12-381 library

License

MIT © Capytime Team

Links

• Capytime Website
• drand Network
• BLS12-381 Curve