@chainlink/evm-gauntlet-vrfv2plus v5.9.0

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
• pnpm@8.6.2

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

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)
• -p : Foundry profile to use (optional parameter, if not specified default profile will be used, set to vrf for using VRF default profile)
• -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 profile

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

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/contracts@4.9.3 code to local vendor directory

   $ nvm use
   $ npm install -g @openzeppelin/contracts@4.9.3
   # Update node.js version accordingly in the command below
   $ cp -r ~/.nvm/versions/node/v16.20.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 pnpm@8.6.2
   $ 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.

3. Release the new gauntlet-evm package:

   git checkout changeset-release/develop
   git pull origin changeset-release/develop --rebase
   git rebase --exec 'git commit --amend --no-edit -n -S' -i develop # The only commit present in the VIM editor when you do this should be the "Version Packages" commit.
   git push origin changeset-release/develop -f # You have to force push to apply your signature to the commits

Documentation

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

VRF Operational Use Cases

EngOps VRF Guide