clones-with-immutable-args

Enables creating clone contracts with immutable arguments.

The immutable arguments are stored in the code region of the created proxy contract, and whenever the proxy is called, it reads the arguments into memory, and then appends them to the calldata of the delegate call to the implementation contract. The implementation contract can thus read the arguments straight from calldata.

By doing so, the gas cost of creating parametrizable clones is reduced. An EIP-1167 clone shares its implementation's code, so its immutables are fixed when the implementation is deployed and cannot differ per clone: the only way to parametrize one is storage, which means paying to write the parameters at creation and to load them on every call. Here the parameters live in the clone's own code instead, so there is no storage write at creation, and reads are calldata reads.

Note the comparison is against a parametrized EIP-1167 clone, not against immutable variables on a regular contract. Solidity immutables are read from code and are already cheap, but they are the same for every clone of a given implementation, which is exactly what this library exists to work around.

In other word, if you know you are not gonna need parametrization and just want exact copies, then you can keep using EIP-1167, otherwise, clones-with-immutables is cheaper.

Status

This library is stable and maintained on demand: it is not under active feature development, but issues and security reports are addressed. The API is settled and in production use: no function signature has changed since 1.x, and none is planned to.

Note that the immutable args are appended to the calldata of every delegatecall, so an implementation inheriting Clone.sol reads them with a plain calldataload. This costs a small overhead on every call and makes arg reads very cheap. Other minimal-proxy libraries make different tradeoffs, including storing args in the runtime bytecode and reading them back with extcodecopy.

Compiler requirements

ClonesWithImmutableArgs.sol requires Solidity 0.8.13 or newer, because its inline assembly is annotated with the memory-safe dialect string, which lets the via-IR optimizer reason across those blocks.

Clone.sol still supports ^0.8.4. It is what a contract intended to be cloned inherits in order to read its immutable args, and it contains no assembly annotations, so implementations do not need a newer compiler than before. Only the factory side is affected.

If you are pinned below 0.8.13, use 1.2.0. It is the last release supporting ^0.8.4 throughout, and it contains the same fixes as 2.0.0.

Usage

Clone factory contracts should use the ClonesWithImmutableArgs library. ClonesWithImmutableArgs.clone() is the main function for creating clones.

Contracts intended to be cloned should inherit from Clone to get access to the helper functions for reading immutable args.

To see an example usage of the library, check out ExampleClone and ExampleCloneFactory.

Installation

To install with DappTools:

dapp install wighawag/clones-with-immutable-args

To install with Foundry:

forge install wighawag/clones-with-immutable-args

To install with Hardhat:

npm i -D clones-with-immutable-args

Local development

This project uses Foundry as the development framework.

Dependencies

make update

Compilation

make build

Testing

make test