diff --git a/docs/smart-contracts/data-types/crypto-data-types.md b/docs/smart-contracts/data-types/crypto-data-types.md index 652bb446b..788363bd0 100644 --- a/docs/smart-contracts/data-types/crypto-data-types.md +++ b/docs/smart-contracts/data-types/crypto-data-types.md @@ -2,7 +2,7 @@ title: Cryptographic data types authors: 'Mathias Hiron (Nomadic Labs), Sasha Aldrick (TriliTech), Tim McMackin (TriliTech)' last_update: - date: 5 October 2023 + date: 9 April 2024 --- Tezos provides hash functions for cryptographic purposes. @@ -37,65 +37,14 @@ It can also be used for identity-based cryptography, single-round multi-party ke - SmartPy: [Cryptography](https://smartpy.io/manual/scenarios/cryptography#cryptography) - Taquito: [Signing data](https://tezostaquito.io/docs/signing/) -## Timelocks +## Time-locks -A `timelock` is a cryptographic primitive that can be used as part of a **commit & reveal** scheme, to provide a guarantee that the information associated to the commit is eventually revealed. +A `timelock` is a cryptographic primitive that can be used as part of a commit-and-reveal scheme, to provide a guarantee that the information associated to the commit is eventually revealed. -### Classical commit & reveal scheme - -Commit & reveal is a scheme that consists of two steps, involving one or more participants: - -- Before a set deadline, each participant makes a decision and publishes a commitment, which is a proof that they have taken a decision that they won't be able to change. -The proof often takes the form of a hash of the data that corresponding to the decision. -- After the deadline, each participant reveals the data corresponding to their commitment. -Other participants can check that the hash of this data indeed corresponds to their previous commitment. - -This scheme makes it possible to prove that a certain decision was taken before some information was revealed. -This information may be the decision of other participants, or some external independent information. - -As an example, imagine that two players want to play the game [rock, paper, scissors](https://en.wikipedia.org/wiki/Rock_paper_scissors) via a smart contract. -As it is impossible to force and verify that the two players reveal their choice between rock, paper or scissors simultaneously, they can use a commit & reveal scheme to do so. - -During the first step, they pick their choice, identified by a number from 1 to 3, put it in a pair with some random data, compute a hash of the result. -This hash is the commitment that they can then send to the contract. - -After both players have sent their commitment, they can reveal by sending the actual data to the contract including the random data. -The contract can verify that the hash of this data matches the previous commitment. -When the two players have revealed their data, the smart contract determines the outcome of the game and distributes rewards accordingly. - -### Not revealing - -One issue with the classical commit & reveal scheme is that after the first step is closed and some information is revealed, one participant may find it advantageous to not reveal at all. -Why reveal if it will only make you lose? For some use cases, this can ruin the whole process. - -One way to address this problem is by setting a financial incentive, such as tokens that people deposit along with their commitments. -After they reveal, they get the tokens back, which encourages them to reveal. - -### Forcing the reveal with a time lock - -In some cases, a financial incentive is not enough by itself. -For example, the benefit of not revealing may outweigh the benefit of revealing, or multiple participants may collaborate and decide not to reveal. - -In this case, you can use a time lock to produce a commitment and force the reveal. - -In this case, instead of using a hash, the data is encrypted using an encryption method that can be cracked with a known algorithm. -The amount of time that it takes to crack the encryption is bounded, which provides a time limit. - -The algorithm used to crack it can't be parallelized, which means there is a limit to how much computing power can be applied to it. -You can estimate the time that it takes for an ordinary computer to crack it and for the fastest possible dedicated hardware to crack it. -Then you can set the time limit by setting the number of iterations in the data encryption. - -For example, assume that you encrypt data in a time lock that you know takes between 10 minutes and 10 hours to decrypt, depending on the hardware. -You can use a commit phase that takes less than 10 minutes, which is not enough time to crack the encryption, so no one can decrypt anyone's commitment. -Then you can use a reveal phase that gives the participants a few minutes to reveal their data. -If a participant doesn't reveal, you can provide a financial reward (funded by the non-revealed participants' deposits) to anyone else to crack the encryption and reveal the data. - -Because it's possible to reveal the data eventually, all participants have an incentive to reveal because they will eventually lose their deposit when someone else cracks and reveals the data. -In this way, time locks work as a deterrent; in practice, participants nearly always reveal rather than forcing someone else to crack the encryption. - -Some use cases involve collectively generating a random value or preventing [BPEV attacks](https://opentezos.com/smart-contracts/avoiding-flaws/#6-not-protecting-against-bots-bpev-attacks). +For information about using time-locks, see [Timelocks](../timelocks). ## Implementation details -- Michelson: [Operations on timelock](https://tezos.gitlab.io/active/michelson.html#operations-on-timelock) +- Michelson: [Time-lock](https://tezos.gitlab.io/active/timelock.html) - Archetype: [Timelock](https://archetype-lang.org/docs/language-basics/crypto#timelock) +- LIGO: [Timelock](https://ligolang.org/docs/reference/current-reference/?lang=jsligo#timelock) diff --git a/docs/smart-contracts/timelocks.md b/docs/smart-contracts/timelocks.md new file mode 100644 index 000000000..db73ce7a0 --- /dev/null +++ b/docs/smart-contracts/timelocks.md @@ -0,0 +1,103 @@ +--- +title: Timelocks +authors: 'Mathias Hiron (Nomadic Labs), Sasha Aldrick (TriliTech), Tim McMackin (TriliTech)' +last_update: + date: 9 May 2024 +--- + +Timelocks are a way to prevent exploits known as _front-running_, or more properly, _extractable value (EV) attacks_. +In general, these attacks happen when a client uses information about an upcoming transaction to make a profit at its expense. + +:::note + +Within decentralized finance, the term "front-running" can be misleading because it implies a relationship between clients and block producers where none may exist. + +In traditional finance, front-running often relies on malicious brokers profiting from advance, nonpublic information about their clients' trades. +For example, a malicious stockbroker may buy a security for themselves before they execute a client's large buy order, knowing that the client's buy order will drive the price of the security up. + +In decentralized finance, anyone can see incoming transactions, so front-running does not always mean that block producers are acting maliciously or sharing private information with clients. +EV attacks can come from bots that watch for incoming transactions and insert their own transactions before the incoming transaction runs. + +However, block producers may still be able to profit from advance information about transactions. +For example, they may craft blocks that include a client's transaction and one of their own in an order that guarantees a gain to the block producer. +This type of attack is called a block producer extractable value (BPEV) attack. + +::: + +For more information about this kind of attack, see [An analysis of Ethereum front-running and its defense solutions](https://medium.com/degate/an-analysis-of-ethereum-front-running-and-its-defense-solutions-34ef81ba8456). + +## Preventing EV attacks with timelocks + +Tezos developers can prevent EV attacks with timelock encryption, which encrypts a message so it can be decrypted in two ways: + +- The author of the encrypted message provides the unencrypted message and proof that it matches the encrypted message. +- Anyone else can decrypt the message with a certain number of operations. + +With timelocks, an author can encrypt a message in such a way that anyone else can reveal the message, but only after a certain amount of time. +This duration is based on the time it takes for a single computer to decrypt the commitments because the decryption algorithm can’t be parallelized. +That means that computers can’t easily work together to decrypt it and that adversaries cannot break it even with significant computing power. + +dApps that use timelocks to prevent EV attacks work in this general way: + +1. A user sends a timelock-encrypted transaction or operation to the dApp. +1. The dApp adds the transaction to its queue before anyone can see what the transaction is. +To everyone else, including bakers, bots, and the dApp itself, the transaction is encrypted and unreadable. +No one else can decrypt the transaction quickly, so they can’t take advantage of it in an EV attack. +1. In the background, the dApp begins decrypting the transaction. +1. One of two things happen: + + - The user submits the decrypted transaction and the proof that the decryption is accurate to the dApp before the dApp decrypts the transaction. + - The dApp decrypts the transaction before the user submits the decrypted transaction, such as if prices changed and the user doesn't want to execute the transaction anymore. + In this case, the dApp takes a penalty charge from the transaction for making it waste processing power on decrypting it. +1. The dApp fulfills the decrypted transactions in its queue in the order that they were submitted. + +In practice, DeFi users nearly always submit their decrypted transactions before anyone else decrypts them. +They don’t want to pay the penalty and they know how long it will take the dApp to break the transaction’s encryption. + +## Flow of timelocks in a typical commit-and-reveal scheme + +Timelocks are often used to ensure that a group of users each submit information while keeping their submissions secret for a certain amount of time. +Sometimes this process is called a _commit and reveal scheme_ because all users commit to their choice without seeing the others' choices. + +This is the typical usage pattern of a timelock: + +1. In the first time period, a contract collects timelock encrypted values from users along with some valuable deposit, such as tez. +2. In the second time period, after the values are collected, users submit a decryption of the value they submitted with a proof that the decryption is correct. +This prevents users from changing their values. +3. In the third time period, if any value isn't decrypted, anyone can claim some of the deposit by submitting a decryption of the value. +This prevents users from profiting by not revealing their decrypted values or blocking the process. +This period needs to be long enough so that people have enough time to perform the timelock decryption. +4. Finally, the contract runs some logic based on the decrypted data. +For example, it might distribute funds to a winner or run an operation that the majority of the users secretly voted for. + +Contracts can assess different penalties for not revealing, depending on whether the user merely failed to submit a decryption for their value or if they also intentionally encrypted invalid data. +They can also distribute different rewards for submitting a correct decryption. + +Because it's possible to reveal the data eventually, all participants have an incentive to reveal because they will eventually lose their deposit when someone else cracks and reveals the data. +In this way, timelocks work as a deterrent; in practice, participants nearly always reveal rather than forcing someone else to crack the encryption. +However, the second period needs to be long enough so that bakers cannot easily censor submission of the decryption in a bid to later claim the reward. + +Also, contracts should burn part of a deposit when another user submits a decryption of someone else's value. +Burning a part of the deposit limits attacks where a user gets back their whole deposit by providing the decryption, but in a way that delays everyone else. + +## Example + +Timelocks make it possible to prove that a certain decision was taken before some information was revealed. +This information may be the decision of other participants or some external independent information. + +As an example, imagine that two players want to play the game [rock, paper, scissors](https://en.wikipedia.org/wiki/Rock_paper_scissors) via a smart contract. +If one player can see another player's choice before they choose, they will win every time. +Because it is impossible to force and verify that the two players reveal their choice simultaneously, they can use a commit-and-reveal scheme. + +During the first step, they pick their choice and put it in a pair with some random data. +Then they compute a hash of the result to create a timelock and send this value to the contract as a commitment. + +After both players have sent their commitment, they can reveal by sending the actual data to the contract including the random data. +The contract can verify that the hash of this data matches the previous commitment. +When the two players have revealed their data, the smart contract determines the outcome of the game and distributes rewards accordingly. + +## References + +- [Timelock puzzles and timed release Crypto](http://www.hashcash.org/papers/timelock.pdf) +- [Not protecting against bots (BPEV attacks)](https://opentezos.com/smart-contracts/avoiding-flaws/#6-not-protecting-against-bots-bpev-attacks) +- [How Tezos timelocks help protect DeFi transactions](https://spotlight.tezos.com/timelocks-defi/) diff --git a/sidebars.js b/sidebars.js index 02793cc90..7c1e10074 100644 --- a/sidebars.js +++ b/sidebars.js @@ -161,6 +161,7 @@ const sidebars = { 'smart-contracts/events', 'smart-contracts/delegation', 'smart-contracts/multisig', + 'smart-contracts/timelocks', 'smart-contracts/oracles', ], },