evm-gauntlet-vrfv2plus

This package implements various commands for deploying and managing VRF V2+ contracts.

See here for supported operations and associated documentation.

Repository dependencies

• Chainlink repository with contracts: chainlink

Required tools

• yarn
• jq
• foundry
• nvm
• node.js
• [email protected]

Setup

# cd into gauntlet-evm repo
$ cd gauntlet-evm
$ nvm use
$ yarn # Installs node.js dependencies

Running Tests

From the root directory of gauntlet-evm run the following to trigger all tests:

yarn test --selectProjects evm-gauntlet-vrfv2plus

Or if you want to run a specific test only:

yarn test packages/evm-gauntlet-vrfv2plus/tests/batchblockhashstore.test.ts

Update Contract ABIs and Bytecode

Using the script

There is a script you can use to help you with generating all the metadata files (you can find it in the scripts folder). Prior to running the script, make sure that you have the correct foundry.toml and remappings.txt configuration set. If not, follow steps 1-4 in the manual steps guide below. Otherwise, the script will warn you about missing configuration. Also, don't forget to install Foundry prior to using the script!

This is how you can run the script that replaces all the manual steps explained below to generate all the necessary metadata for VRFCoordinatorV2_5.sol contract:

$ ./gen-vrf-contract-metadata.sh \
     -m /path/to/chainlink \
     -c /path/to/chainlink/contracts/src/v0.8/vrf/dev/VRFCoordinatorV2_5.sol \
     -g /path/to/gauntlet-evm
     -v /path/to/gauntlet-evm/packages/evm-gauntlet-vrfv2plus/artifacts/evm/v2
     -p vrfv2plus_coordinator

Flags are as following:

• -m : absolute path to your local chainlink repository copy (root)
• -c : absolute path to the contract file in your local chainlink repository
• -g : absolute path to your local gauntlet-evm repository copy (root)
• -v : version folder where to store all generated files (e.g. v1, v2)
• -p : Foundry profile to use (optional parameter, if not specified default profile will be used, set to vrfv2plus for using VRF v2.5 default profile or set to vrfv2plus_coordinator to use the profile for VRFCoordinatorV2_5 contract)
• -o : number of optimizer runs (optional parameter, default value is the one from the Foundry VRF profile in `foundry.toml`` file)

Known script issues

Script failures may be possible due to missing modules or lock file already being used. If you experience these issues, this is due to simultaneous use of different dependency managers resulting in collisions. In that case, go to your chainlink local repository run inside contracts folder and run some of the following to clean up:

$ npm run clean # should be sufficient, you could also try yarn clean
$ rm -rf node_modules # in case nothing else works

Manual steps

These steps will guide you how to (re)build contracts.

1. Go to chainlink core repo setup locally

   $ cd chainlink/contracts
   

2. Update foundry.toml file in contracts directory with following profiles (unless these profiles already exist, then don't update anything!)

   [profile.vrfv2plus_coordinator]
   optimizer_runs = 500
   src = 'src/v0.8/vrf'
   solc_version = '0.8.19'
   
   [profile.vrfv2plus]
   optimizer_runs = 1_000_000
   src = 'src/v0.8/vrf'
   solc_version = '0.8.19'
   

3. Update remappings.txt file in contracts directory to have openzeppelin point to a vendor directory rather than node_modules (if needed, adjust OpenZeppelin version to the one used in contracts)

   @openzeppelin/=src/v0.8/vendor/openzeppelin-solidity/v4.9.3
   

4. Download and copy @openzeppelin/[email protected] code to local vendor directory

   $ nvm use
   $ npm install -g @openzeppelin/[email protected]
   # Update node.js version accordingly in the command below
   $ cp -r ~/.nvm/versions/node/18.12.0/lib/node_modules/@openzeppelin/contracts/ ./src/v0.8/vendor/openzeppelin-solidity/v4.9.3/contracts/
   

5. Install Foundry and run forge build for VRFCoordinatorV2_5, BlockhashStore and VRFV2PlusWrapper (change FOUNDRY_PROFILE to profile name from foundry.toml file or omit if you want to use the default profile)

   $ FOUNDRY_PROFILE=<profile_name> forge build --contracts src/v0.8/vrf/dev/VRFCoordinatorV2_5.sol --force --build-info-path=./build --build-info --skip test --skip scripts
   $ mv build/1d042417803331c5f14babf40ad6faee.json build/VRFCoordinatorV2_5.build.json
   

   In case you are using Apple Clang with you Solidity compiler, make sure to remove "Darwin.appleclang" tag from the solcLongVersion parameter in the generated build file (otherwise verification might be rejected by EtherScan or some other blockchain explorer, check supported Solidity versions on EtherScan). You can do it like this:

   sed 's/.Darwin.appleclang//g' build/BatchVRFCoordinatorV2Plus.json > build/BatchVRFCoordinatorV2Plus_fixed.json
   mv build/BatchVRFCoordinatorV2Plus_fixed.json build/BatchVRFCoordinatorV2Plus.json 
   

   Few more finishing touches:

   # now remove all whitespaces and make the build file more compact
   $ cat ./build/VRFCoordinatorV2_5.build.json | jq -c . > ./build/VRFCoordinatorV2_5_compact.build.json
   # copy the file to gauntlet-evm inside artifacts folder
   $ cp /path/to/chainlink/build/VRFCoordinatorV2_5_compact.build.json /path/to/gauntlet-evm/packages/evm-gauntlet-vrfv2plus/artifacts/evm/VRFCoordinatorV2_5.build.json
   

   Repeat this process for BlockhashStore and VRFV2PlusWrapper contracts (or any other contracts).

6. Run hardhat compile to generate metadata (example for VRFCoordinatorV2_5.sol)

   # Make sure you are in the contrats folder (chainlink repo)
   $ cd ./contracts
   # The following command will use the settings for VRFCoordinatorV2_5 in hardhat.config.js
   # overrides section and the defaults (1 million optimizations) for wrapper and BHS
   
   $ nvm use
   # If specific node.js version not installed, install it using nvm install v16.16.0
   $ npm install -g [email protected]
   $ pnpm i
   $ pnpm hardhat compile
   
   # After running the above command, you should see the appropriate output in:
   # artifacts/src/v0.8/vrf/dev/<ContractName>.sol/<ContractName>.json
   
   # Example: artifacts/src/v0.8/vrf/dev/VRFCoordinatorV2_5.sol/VRFCoordinatorV2_5.json
   
   # copy the metadata file to a correct location in the gauntlet-evm repo
   $ cp ./artifacts/src/v0.8/vrf/dev/VRFCoordinatorV2_5.sol/VRFCoordinatorV2_5.json /path/to/gauntlet-evm/packages/evm-gauntlet-vrfv2plus/artifacts/evm
   

Add commands for new contracts

1. To add a new contract, create a separate subfolder under commands folder and add one file per command plus don't forget to add the index.ts file.

2. Add new contract category in packages/evm-gauntlet-vrfv2plus/src/lib/categories.ts, contract loader in packages/evm-gauntlet-vrfv2plus/src/lib/contracts.ts and new contract types (if necessary) in packages/evm-gauntlet-vrfv2plus/src/lib/types.ts.

3. Update commands root index in packages/evm-gauntlet-vrfv2plus/src/commands/index.ts by extending it with new commands.

4. You should be able to see new commands when you run yarn gauntlet help.

Package release

1. Create a PR in gauntlet-evm repo.

2. Add a changeset in the same PR yarn changeset add, edit the changeset file from major to minor and get the PR accepted and merged.

3. Release the new gauntlet-evm package: once changeset is detected on develop branch, CI will automatically create a new PR to release the package, approve this PR and merge it (merge will initiate package creation and then you can find it on the Releases page)

4. If you want this change to be available for the Gauntlet tool, then you have to make sure Gauntlet is updated with the new gauntlet-evm-vrfv2plus package version

5. Create a PR on the Gauntlet repository by upgrading the gauntlet-evm-vrfv2plus package version in the packages/gauntlet-evm by running the following command:

   yarn add @chainlink/[email protected] # replace X.Y.Z with the correct version
   

6. Add changeset in the same PR yarn changeset add, edit the changeset file from major to minor and get the PR accepted and merged.

7. Release the new gauntlet package: once changeset is detected on develop branch, CI will automatically create a new PR to release the package, approve this PR and merge it (merge will initiate package creation and then you can find it on the Releases page)

Documentation

When everything is finished, make sure to update the following docs:

VRF Operational Use Cases

EngOps VRF Guide