Morley.Tezos.Crypto.Timelock

Timelock puzzle algorithms implementation.

This module follows the reference implementation for the most part, which you can find in the [tezos repository](https:/gitlab.comtezostezos-blobb1a2ff0334405cafd7465bfa991d23844f0b4e70srclib_crypto/timelock.ml).

For a more high-level overview of the concepts, refer to the timelock documentation page.

The general idea is built upon Rivest, Shamir, Wagner "Time-lock puzzles and timed-release Crypto", there are however some differences from the paper:

• The paper suggests using RC5 cipher, which Tezos implementation eschews in favor of NaCl's "secret box".
• The paper suggest generating the symmetric secret key \(K\) directly, then encrypting it with a randomly chosen value \(a\) as \(C_K = K + a^{2^t} \pmod n\). Tezos implementation instead randomly generates only \(a\), and then produces the secret key using BLAKE2b KDF with a fixed key from \(a^{2^t} \pmod n\).
• Since the secret key is determined only by the "unlocked" value, the time-locked value representation also differs. In the paper it's represented as ((n,a,t,C_K,C_M)), i.e. the tuple of modulus, "locked" value, time, encrypted key and encrypted message. In Tezos implementation it's instead ((a,n,C_M)), and \(t\) is treated as a separate argument.
• Likely to guard the protocol from guessing attacks, additional "proof" verification is added, described in [Boneh, Bünz, Fisch "A Survey of Two Verifiable Delay Functions"](https:/eprint.iacr.org2018/712.pdf)

Documentation

newtype TLTime

Number of steps a timelock needs to be opened without knowing a "secret", i.e. modulo factorization.

The reference implementation uses OCaml int, and it can only be positive, so on 64-bit architecture it's actually a 62-bit natural. We use Word62 to represent it.

The constructor is marked Unsafe since GHC does not warn on overflowing literals (exceeding custom Word62 type bounds), thus the resultant TLTime value may get truncated silently.

>>> UnsafeTLTime 4611686018427387906
UnsafeTLTime {unTLTime = 2}

Constructors

UnsafeTLTime

Fields

• unTLTime :: Word62

Bundled Patterns

pattern TLTime :: Word62 -> TLTime

Instances

Bounded TLTime

Defined in Morley.Tezos.Crypto.Timelock

Methods

minBound :: TLTime

maxBound :: TLTime

Eq TLTime

Defined in Morley.Tezos.Crypto.Timelock

Methods

(==) :: TLTime -> TLTime -> Bool

(/=) :: TLTime -> TLTime -> Bool

Show TLTime

Defined in Morley.Tezos.Crypto.Timelock

Methods

showsPrec :: Int -> TLTime -> ShowS

show :: TLTime -> String

showList :: [TLTime] -> ShowS

Buildable TLTime

Defined in Morley.Tezos.Crypto.Timelock

Methods

build :: TLTime -> Builder

HasCLReader TLTime

Defined in Morley.Tezos.Crypto.Timelock

Methods

getReader :: ReadM TLTime

getMetavar :: String

data Chest

A locked chest

Constructors

Chest

Fields

• chestLockedVal :: Locked
• chestPublicModulus :: PublicModulus
• chestCiphertext :: Ciphertext

Instances

Eq Chest

Defined in Morley.Tezos.Crypto.Timelock

Methods

(==) :: Chest -> Chest -> Bool

(/=) :: Chest -> Chest -> Bool

Show Chest

Defined in Morley.Tezos.Crypto.Timelock

Methods

showsPrec :: Int -> Chest -> ShowS

show :: Chest -> String

showList :: [Chest] -> ShowS

Generic Chest

Defined in Morley.Tezos.Crypto.Timelock

Associated Types

type Rep Chest :: Type -> Type

Methods

from :: Chest -> Rep Chest x

to :: Rep Chest x -> Chest

NFData Chest

Defined in Morley.Tezos.Crypto.Timelock

Methods

rnf :: Chest -> ()

Binary Chest

Defined in Morley.Tezos.Crypto.Timelock

Methods

put :: Chest -> Put

get :: Get Chest

putList :: [Chest] -> Put

IsoValue Chest

Defined in Morley.Michelson.Typed.Haskell.Value

Associated Types

type ToT Chest :: T

Methods

toVal :: Chest -> Value (ToT Chest)

fromVal :: Value (ToT Chest) -> Chest

TypeHasDoc Chest

Defined in Morley.Michelson.Typed.Haskell.Doc

Associated Types

type TypeDocFieldDescriptions Chest :: FieldDescriptions

Methods

typeDocName :: Proxy Chest -> Text

typeDocMdDescription :: Markdown

typeDocMdReference :: Proxy Chest -> WithinParens -> Markdown

typeDocDependencies :: Proxy Chest -> [SomeDocDefinitionItem]

typeDocHaskellRep :: TypeDocHaskellRep Chest

typeDocMichelsonRep :: TypeDocMichelsonRep Chest

HasRPCRepr Chest

Defined in Morley.AsRPC

Associated Types

type AsRPC Chest

type Rep Chest

Defined in Morley.Tezos.Crypto.Timelock

type Rep Chest

type ToT Chest

Defined in Morley.Michelson.Typed.Haskell.Value

type ToT Chest = 'TChest

type TypeDocFieldDescriptions Chest

Defined in Morley.Michelson.Typed.Haskell.Doc

type TypeDocFieldDescriptions Chest = '[] :: [(Symbol, (Maybe Symbol, [(Symbol, Symbol)]))]

type AsRPC Chest

Defined in Morley.AsRPC

type AsRPC Chest = Chest

data ChestKey

A chest "key" with proof that it was indeed opened fairly.

Constructors

ChestKey

Fields

• ckUnlockedVal :: Unlocked
• ckProof :: Proof

Instances

Eq ChestKey

Defined in Morley.Tezos.Crypto.Timelock

Methods

(==) :: ChestKey -> ChestKey -> Bool

(/=) :: ChestKey -> ChestKey -> Bool

Show ChestKey

Defined in Morley.Tezos.Crypto.Timelock

Methods

showsPrec :: Int -> ChestKey -> ShowS

show :: ChestKey -> String

showList :: [ChestKey] -> ShowS

Generic ChestKey

Defined in Morley.Tezos.Crypto.Timelock

Associated Types

type Rep ChestKey :: Type -> Type

Methods

from :: ChestKey -> Rep ChestKey x

to :: Rep ChestKey x -> ChestKey

NFData ChestKey

Defined in Morley.Tezos.Crypto.Timelock

Methods

rnf :: ChestKey -> ()

Binary ChestKey

Defined in Morley.Tezos.Crypto.Timelock

Methods

put :: ChestKey -> Put

get :: Get ChestKey

putList :: [ChestKey] -> Put

IsoValue ChestKey

Defined in Morley.Michelson.Typed.Haskell.Value

Associated Types

type ToT ChestKey :: T

Methods

toVal :: ChestKey -> Value (ToT ChestKey)

fromVal :: Value (ToT ChestKey) -> ChestKey

TypeHasDoc ChestKey

Defined in Morley.Michelson.Typed.Haskell.Doc

Associated Types

type TypeDocFieldDescriptions ChestKey :: FieldDescriptions

Methods

typeDocName :: Proxy ChestKey -> Text

typeDocMdDescription :: Markdown

typeDocMdReference :: Proxy ChestKey -> WithinParens -> Markdown

typeDocDependencies :: Proxy ChestKey -> [SomeDocDefinitionItem]

typeDocHaskellRep :: TypeDocHaskellRep ChestKey

typeDocMichelsonRep :: TypeDocMichelsonRep ChestKey

HasRPCRepr ChestKey

Defined in Morley.AsRPC

Associated Types

type AsRPC ChestKey

type Rep ChestKey

Defined in Morley.Tezos.Crypto.Timelock

type Rep ChestKey

type ToT ChestKey

Defined in Morley.Michelson.Typed.Haskell.Value

type ToT ChestKey = 'TChestKey

type TypeDocFieldDescriptions ChestKey

Defined in Morley.Michelson.Typed.Haskell.Doc

type TypeDocFieldDescriptions ChestKey = '[] :: [(Symbol, (Maybe Symbol, [(Symbol, Symbol)]))]

type AsRPC ChestKey

Defined in Morley.AsRPC

type AsRPC ChestKey = ChestKey

data Ciphertext

Ciphertext with nonce.

Constructors

Ciphertext

Fields

• ctNonce :: Nonce
• ctPayload :: ByteString

Instances

Eq Ciphertext

Defined in Morley.Tezos.Crypto.Timelock

Methods

(==) :: Ciphertext -> Ciphertext -> Bool

(/=) :: Ciphertext -> Ciphertext -> Bool

Show Ciphertext

Defined in Morley.Tezos.Crypto.Timelock

Methods

showsPrec :: Int -> Ciphertext -> ShowS

show :: Ciphertext -> String

showList :: [Ciphertext] -> ShowS

Generic Ciphertext

Defined in Morley.Tezos.Crypto.Timelock

Associated Types

type Rep Ciphertext :: Type -> Type

Methods

from :: Ciphertext -> Rep Ciphertext x

to :: Rep Ciphertext x -> Ciphertext

NFData Ciphertext

Defined in Morley.Tezos.Crypto.Timelock

Methods

rnf :: Ciphertext -> ()

Binary Ciphertext

Defined in Morley.Tezos.Crypto.Timelock

Methods

put :: Ciphertext -> Put

get :: Get Ciphertext

putList :: [Ciphertext] -> Put

type Rep Ciphertext

Defined in Morley.Tezos.Crypto.Timelock

type Rep Ciphertext

data OpeningResult

The result of opening the chest.

Constructors

Correct ByteString

The chest was opened correctly.

BogusCipher

The chest was opened correctly, but the contents do not decode with the given symmetric key.

BogusOpening

The chest was not opened correctly, i.e. proof verification failed.

Instances

Eq OpeningResult

Defined in Morley.Tezos.Crypto.Timelock

Methods

(==) :: OpeningResult -> OpeningResult -> Bool

(/=) :: OpeningResult -> OpeningResult -> Bool

Show OpeningResult

Defined in Morley.Tezos.Crypto.Timelock

Methods

showsPrec :: Int -> OpeningResult -> ShowS

show :: OpeningResult -> String

showList :: [OpeningResult] -> ShowS

createChestAndChestKey

Arguments

:: ByteString

Chest content

-> TLTime

Time (in elementary actions) to open without key.

-> IO (Chest, ChestKey)

Create a timelock puzzle and a key.

createChestKey :: Chest -> TLTime -> ChestKey

Forge a chest key the hard way.

chestBytes :: Chest -> ByteString

Convert a Chest to binary representation, used by Tezos

chestKeyBytes :: ChestKey -> ByteString

Convert a ChestKey to binary representation, used by Tezos

chestFromBytes :: ByteString -> Either Text Chest

Read a Chest from binary representation, used by Tezos

chestKeyFromBytes :: ByteString -> Either Text ChestKey

Read a ChestKey from binary representation, used by Tezos

openChest :: Chest -> ChestKey -> TLTime -> OpeningResult

Try to (quickly) open a chest with the given key, verifying the proof.

mkTLTime :: Integral i => i -> Either Text TLTime

Safely creates TLTime checking for overflow and underflow. Accepts a number of any type.

toTLTime :: (Integral a, CheckIntSubType a Word62) => a -> TLTime

Safely creates TLTime.

This is the recommended way to create TLTime values.

When constructing literals, you'll need to specify the type of the literal. Bear in mind that GHC will check for literal overflow on builtin types like Word16 and Word32, but not on Word62, so be aware that toTLTime from Word62 will overflow silently. Prefer using builtin types when possible.

>>> unTLTime $ toTLTime (4611686018427387903 :: Word62)
4611686018427387903
>>> unTLTime $ toTLTime (4611686018427387904 :: Word62)
0

Internal, not safe for cryptography

createChestAndChestKeyFromSeed

Arguments

:: Int

Pseudo-random seed

-> ByteString

Chest content

-> TLTime

TLTime (in elementary actions) to open without key.

-> (Chest, ChestKey)

Construct a chest purely based on a seed for pseudorandom generator. This is not suitable for cryptography, used in tests.