ERC-5202: Blueprint contract format

Define a bytecode container format for indexing and utilizing blueprint contracts


Metadata
Status: FinalStandards Track: ERCCreated: 2022-06-23
Authors
Charles Cooper (@charles-cooper), Edward Amor (@skellet0r)
Requires

Abstract


Define a standard for "blueprint" contracts, or contracts which represent initcode that is stored on-chain.

Motivation


To decrease deployer contract size, a useful pattern is to store initcode on chain as a "blueprint" contract, and then use EXTCODECOPY to copy the initcode into memory, followed by a call to CREATE or CREATE2. However, this comes with the following problems:

  • It is hard for external tools and indexers to detect if a contract is a "regular" runtime contract or a "blueprint" contract. Heuristically searching for patterns in bytecode to determine if it is initcode poses maintenance and correctness problems.
  • Storing initcode byte-for-byte on-chain is a correctness and security problem. Since the EVM does not have a native way to distinguish between executable code and other types of code, unless the initcode explicitly implements ACL rules, anybody can call such a "blueprint" contract and execute the initcode directly as ordinary runtime code. This is particularly problematic if the initcode stored by the blueprint contract has side effects such as writing to storage or calling external contracts. If the initcode stored by the blueprint contract executes a SELFDESTRUCT opcode, the blueprint contract could even be removed, preventing the correct operation of downstream deployer contracts that rely on the blueprint existing. For this reason, it would be good to prefix blueprint contracts with a special preamble to prevent execution.

Specification


The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

A blueprint contract MUST use the preamble 0xFE71<version bits><length encoding bits>. 6 bits are allocated to the version, and 2 bits to the length encoding. The first version begins at 0 (0b000000), and versions increment by 1. The value 0b11 for <length encoding bits> is reserved. In the case that the length bits are 0b11, the third byte is considered a continuation byte (that is, the version requires multiple bytes to encode). The exact encoding of a multi-byte version is left to a future ERC.

A blueprint contract MUST contain at least one byte of initcode.

A blueprint contract MAY insert any bytes (data or code) between the version byte(s) and the initcode. If such variable length data is used, the preamble must be 0xFE71<version bits><length encoding bits><length bytes><data>. The <length encoding bits> represent a number between 0 and 2 (inclusive) describing how many bytes <length bytes> takes, and <length bytes> is the big-endian encoding of the number of bytes that <data> takes.

Rationale


  • To save gas and storage space, the preamble should be as minimal as possible.

  • It is considered "bad" behavior to try to CALL a blueprint contract directly, therefore the preamble starts with INVALID (0xfe) to end execution with an exceptional halting condition (rather than a "gentler" opcode like STOP (0x00)).

  • To help distinguish a blueprint contract from other contracts that may start with 0xFE, a "magic" byte is used. The value 0x71 was arbitrarily chosen by taking the last byte of the keccak256 hash of the bytestring "blueprint" (i.e.: keccak256(b"blueprint")[-1]).

  • An empty initcode is disallowed by the spec to prevent what might be a common mistake.

  • Users may want to include arbitrary data or code in their preamble. To allow indexers to ignore these bytes, a variable length encoding is proposed. To allow the length to be only zero or one bytes (in the presumably common case that len(data bytes) is smaller than 256), two bits of the third byte are reserved to specify how many bytes the encoded length takes.

  • In case we need an upgrade path, version bits are included. While we do not expect to exhaust the version bits, in case we do, a continuation sequence is reserved. Since only two bytes are required for <length bytes> (as EIP-170 restricts contract length to 24KB), a <length encoding bits> value of 3 would never be required to describe <length bytes>. For that reason, the special <length encoding bits> value of 0b11 is reserved as a continuation sequence marker.

  • The length of the initcode itself is not included by default in the preamble because it takes space, and it can be trivially determined using EXTCODESIZE.

  • The Ethereum Object Format (EOF) could provide another way of specifying blueprint contracts, by adding another section kind (3 - initcode). However, it is not yet in the EVM, and we would like to be able to standardize blueprint contracts today, without relying on EVM changes. If, at some future point, section kind 3 becomes part of the EOF spec, and the EOF becomes part of the EVM, this ERC will be considered to be obsolesced since the EOF validation spec provides much stronger guarantees than this ERC.

Backwards Compatibility


No known issues

Test Cases


  • An example (and trivial!) blueprint contract with no data section, whose initcode is just the STOP instruction:

  • An example blueprint contract whose initcode is the trivial STOP instruction and whose data section contains the byte 0xFF repeated seven times:

Here, 0xFE71 is the magic header, 0x01 means version 0 + 1 length bit, 0x07 encodes the length in bytes of the data section. These are followed by the data section, and then the initcode. For illustration, the above code with delimiters would be 0xFE71|01|07|FFFFFFFFFFFFFF|00.

  • An example blueprint whose initcode is the trivial STOP instruction and whose data section contains the byte 0xFF repeated 256 times:

Delimited, that would be 0xFE71|02|0100|FF...FF|00.

Reference Implementation



The following reference function takes the desired initcode for a blueprint as a parameter, and returns EVM code which will deploy a corresponding blueprint contract (with no data section):


Security Considerations


There could be contracts on-chain already which happen to start with the same prefix as proposed in this ERC. However, this is not considered a serious risk, because the way it is envisioned that indexers will use this is to verify source code by compiling it and prepending the preamble.

As of 2022-07-08, no contracts deployed on the Ethereum mainnet have a bytecode starting with 0xFE71.

Copyright


Copyright and related rights waived via CC0.