Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

CHIP-0036: keccak256 CLVM operator #131

Merged
merged 7 commits into from
Dec 19, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
139 changes: 139 additions & 0 deletions CHIPs/chip-0036.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,139 @@
CHIP Number | 0036
:-------------|:----
Title | keccak256 CLVM operator
Description | Add a CLVM operator to support Ethereum addresses
Author | [Arvid Norberg](https://github.com/arvidn), [Rigidity](https://github.com/Rigidity)
Editor | [Dan Perry](https://github.com/danieljperry)
Comments-URI | [CHIPs repo, PR #131](https://github.com/Chia-Network/chips/pull/131)
Status | Final
Category | Standards Track
Sub-Category | Chialisp
Created | 2024-10-25
Requires | None
Replaces | None
Superseded-By | None

## Abstract
This CHIP will add a new `keccak256` operator to the CLVM in order to enable the support of Ethereum addresses. This operator will be made accessible from behind the `softfork` guard, which requires a soft fork of Chia's consensus.

## Definitions

Throughout this document, we'll use the following terms:
* **Chialisp** - The high-level [programming language](https://chialisp.com/) from which Chia coins are constructed
* **CLVM** - [Chialisp Virtual Machine](https://chialisp.com/clvm), where the bytecode from compiled Chialisp is executed. Also commonly refers to the compiled bytecode itself
* **Keccak-256** - The same hashing standard Ethereum uses. A few notes on this standard:
* The Keccak-256 standard referred to in this CHIP is specifically version 3 of the [winning submission](https://keccak.team/files/Keccak-submission-3.pdf) to the NIST SHA-3 contest by Bertoni, Daemen, Peeters, and Van Assche in 2011
* This standard is _not_ the same as the final [SHA-3 standard](https://en.wikipedia.org/wiki/SHA-3), which NIST released in 2015
* The EVM uses an opcode called `SHA3`, and Solidity has an instruction called `sha3`. However, these _do not_ refer to the final SHA-3 standard. They _do_ refer to the same `Keccak-256` standard used in this CHIP
* In order to avoid confusion, we will not use the terms `SHA3`, `sha3`, or `SHA-3` further in this CHIP. Instead, the terms `Keccak-256` and `keccak256` will be used to denote the cryptographic standard used in Ethereum

## Motivation

CLVM currently includes an atomic operator called [`sha256`](https://chialisp.com/operators/#atoms). This operator calculates and returns the SHA-256 hash of the input atom(s).

This CHIP will add an atomic operator to the CLVM called `keccak256`, which will calculate and return the Keccak-256 hash of the input atom(s). The primary reason to add this operator is to support Ethereum addresses, which also rely on Keccak-256.

## Backwards Compatibility

If this CHIP is accepted, the `keccak256` operator will be added to the CLVM. If the operator could be called directly, it would break compatibility, and therefore would require a hard fork of Chia's blockchain. However, CLVM includes a [softfork operator](https://chialisp.com/operators/#softfork) specifically to define new CLVM operators without requiring a hard fork.

This CHIP will therefore use the `softfork` operator, which itself requires a soft fork of Chia's blockchain. After the fork's activation, the operator will need to be called from inside the `softfork` guard. This process is detailed in the [softfork usage](#softfork-usage) section.

As with all forks, there will be a risk of a chain split. The soft fork could also fail to be adopted. This might happen if an insufficient number of nodes have upgraded to include the changes introduced by this CHIP prior to the fork's block height.

The operator will be introduced in multiple phases:
* **Pre-CHIP**: Prior to block `6 800 000` (six million, eight hundred thousand), the new operator will be undefined. Any attempt to call it will return `NIL`.
* **Soft fork**: A soft fork will activate at block `6 800 000`. From that block forward, the new operator will exhibit the functionality laid out in this CHIP. It will need to be called from inside the `softfork` guard.
* **Hard fork** (hypothetical): In the event that a hard fork is enacted after the code from this CHIP has been added to the codebase, this hypothetical hard fork could include adding the operator from this CHIP to the core CLVM operator set. If this were to happen, the operator could be also be called from outside the `softfork` guard. (Note that the operator would still be callable from inside the `softfork` guard if desired.)

## Rationale

This CHIP's design was primarily chosen to support Ethereum addresses. It was implemented in a manner consistent with the Keccak-256 standard.

The new operator will incur a CLVM cost, as detailed below. If this CHIP is adopted, the new operator will be optional when designing Chia coins.

## Specification

### `keccak256`

Opcode: 64

Functionality: Calculate and return the Keccak-256 hash of the input atom(s)

Arguments:
* If zero arguments, the Keccak-256 hash of an empty string will be returned
* If one or more arguments:
1. Each argument (if more than one) will be concatenated
2. The Keccak-256 hash of the resulting string will be returned

Usage: `(keccak256 A B …)`

CLVM Cost: `50` base, `160` per argument, `2` per byte

### `softfork` usage

As explained in the [Backwards Compatibility](#backwards-compatibility) section, starting with block `6 800 000`, the operators introduced in this CHIP will be available from inside the `softfork` guard.

The following rules apply when calling the `keccak256` operator by using the `softfork` operator:
* The `softfork` operator works like `apply` (`a`) but takes two additional parameters, `cost` and `extension`
* The syntax is therefore `softfork (<cost> <extension> <quoted-program> <arguments>)`
* The `cost` parameter is the CLVM cost of executing the `quoted-program` with the specified `arguments`. If this cost mismatches the actual cost of executing the program, the `softfork` operator will raise an exception
* The `extension` parameter is an integer indicating the set of extensions available in the `softfork` guard.
* `extension 0` referred to the `Coin ID`, `BLS`, etc operators described in [CHIP-11](https://github.com/Chia-Network/chips/blob/main/CHIPs/chip-0011.md).
* `extension 1` will refer to the operator from this CHIP, _as well as_ those from `extension 0`.
* Just like the `a` operator, the `quoted-program` parameter is quoted and executed from inside the `softfork` guard.
* A client that does not recognize the `extension` specifier must:
* In consensus mode, ignore the whole `softfork`, return `null` and charge the specified `cost`
* In mempool mode, fail the program immediately

Since `softfork` guards always return null, the only useful outcome of executing one is terminating (i.e. failing) the program or not.

The cost of executing the `softfork` operator is 140. This counts against the cost specified in its arguments.

An example of using the `softfork` operator to call the `keccak256` operator is as follows:

```
(softfork
(q . 842) ; expected cost (including cost of softfork itself)
(q . 1) ; extension 1
(q a ; defer execution of if-branches
(i
(=
(keccak256
(q . f)
(q . oobar)
)
(q . 0x38d18acb67d25c8bb9942764b62f18e17054f66a817bd4295423adf9ed98873e)
)
(q . 0) ; if encoding matches, return 0
(q x) ; if encoding mismatches, raise
)
(q . ())) ; environment to apply
(q . ())) ; environment to softfork
```

## Test Cases

Test cases for the `keccak256` operator are located in the [clvm_rs](https://github.com/Chia-Network/clvm_rs/blob/0e12fd49da962365e409a4d889c618b854ee34b3/op-tests/test-keccak256.txt) repository.

Additional tests were added as part of [PR #18988](https://github.com/Chia-Network/chia-blockchain/pull/18988) of the `chia-blockchain` repository.

## Reference Implementation

* [keccak256 and softfork implementation](https://github.com/Chia-Network/clvm_rs/pull/489/files) in Rust
* [softfork implementation](https://github.com/Chia-Network/chia-blockchain/pull/18988/files) in the `chia-blockchain` repository

## Security

Chia Network, Inc. has conducted an internal review of the code involved with this CHIP.

## Additional Assets

None

## Copyright
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).




Loading