vrf-solidity is an open source fast and effective implementation of Verifiable Random Functions (VRFs) written in Solidity. More precisely, this library implements verification functions for VRF proofs based on the Elliptic Curve (EC) Secp256k1.
DISCLAIMER: This is experimental software. Use it at your own risk!
The solidity library has been designed aiming at decreasing gas consumption and its complexity due to EC operations.
It provides two main pure functions for verifying VRF proofs:
- verify:
- Description: VRF full verification (requires heavy EC computation)
- Inputs:
- _publicKey: The public key as an array composed of
[pubKey-x, pubKey-y] - _proof: The VRF proof as an array composed of
[gamma-x, gamma-y, c, s] - _message: The message (in bytes) used for computing the VRF
- _publicKey: The public key as an array composed of
- Output:
- true, if VRF proof is valid
- fastVerify:
- Description: VRF fast verification by providing additional EC points. It uses the
ecrecoverprecompiled function to verify EC multiplications (lower gas consumption). - Inputs:
- _publicKey: The public key as an array composed of
[pubKey-x, pubKey-y] - _proof: The VRF proof as an array composed of
[gamma-x, gamma-y, c, s] - _message: The message (in bytes) used for computing the VRF
- _uPoint: The
uEC point defined asU = s*B - c*Y - _vComponents: The components required to compute
vasV = s*H - c*Gamma
- _publicKey: The public key as an array composed of
- Output:
- true, if VRF proof is valid
- Description: VRF fast verification by providing additional EC points. It uses the
Additionally, the library provides some auxiliary pure functions to facilitate computing the aforementioned input parameters:
- decodeProof:
- Description: Decode from bytes to VRF proof
- Input:
- _proof: The VRF proof as bytes
- Output:
- The VRF proof as an array composed of
[gamma-x, gamma-y, c, s]
- The VRF proof as an array composed of
- decodePoint:
- Description: Decode from bytes to EC point
- Input:
- _point: The EC point as bytes
- Output:
- The point as
[point-x, point-y]
- The point as
- computeFastVerifyParams:
- Description: Compute the parameters (EC points) required for the VRF fast verification function
- Inputs:
- _publicKey: The public key as an array composed of
[pubKey-x, pubKey-y] - _proof: The VRF proof as an array composed of
[gamma-x, gamma-y, c, s] - _message: The message (in bytes) used for computing the VRF
- _publicKey: The public key as an array composed of
- Output:
- The fast verify required parameters as the tuple
([uPointX, uPointY], [sHX, sHY, cGammaX, cGammaY])
- The fast verify required parameters as the tuple
- gammaToHash:
- Description: Computes the VRF hash output as result of the digest of a ciphersuite-dependent prefix concatenated with the gamma point. This hash can be used for deterministically generating verifiable pseudorandom numbers.
- Inputs:
- _gammaX: The x-coordinate of the gamma EC point
- _gammaY: The y-coordinate of the gamma EC point
- Output:
- The VRF hash ouput as shas256 digest
This library follows the algorithms described in VRF-draft-04 in order to provide the VRF verification capability.
The supported cipher suite is SECP256K1_SHA256_TAI, i.e. the aforementioned algorithms using SHA256 as digest function and the secp256k1 curve. For the VRF algorithms the cipher suite code used is 0xFE.
For elliptic curve arithmetic operations vrf-solidity uses the elliptic-curve-solidity library.
VRF.sol library can be used directly by importing it.
Similarly to the VRFTestHelper.sol from the test project folder, a contract may use the library by instantiation as follows:
pragma solidity 0.6.12;
import "vrf-solidity/contracts/VRF.sol";
contract VRFTestHelper {
function functionUsingVRF(
uint256[2] memory public _publicKey,
uint256[4] memory public _proof,
bytes memory _message)
public returns (bool)
{
return VRF.verify(_publicKey, _proof, _message);
}
}The tests under the test folder can be seen as additional examples for interacting with the contract using Solidity and Javascript.
Gas consumption analysis was conducted in order to understand the associated costs to the usage of the vrf-solidity library. Only public functions were object of study as they are the only functions meant to be called by other parties.
The three auxiliary public functions (decodeProof, decodePoint and computeFastVerifyParams) are recommended to be used (if possible) as off-chain operations.
- solc version: 0.6.12+commit.27d51765
- optimizer enabled: true (runs 200)
$ nvm use 12
$ ganache-cli -b 5$ nvm use 12
$ truffle test --network local ./benchmark/VRFGasHelper.sol ./benchmark/gas.js
Contract: VRFGasHelper - Gas consumption analysis
VRF verification functions:
✓ should verify a VRF proof (1) (1615119 gas)
✓ should verify a VRF proof (2) (1706587 gas)
...·--------------------------------------------|---------------------------|-------------|----------------------------·
| Solc version: 0.6.12+commit.27d51765 · Optimizer enabled: true · Runs: 200 · Block limit: 6718946 gas │
·············································|···························|·············|·····························
| Methods │
·················|···························|·············|·············|·············|··············|··············
| Contract · Method · Min · Max · Avg · # calls · usd (avg) │
·················|···························|·············|·············|·············|··············|··············
| VRFGasHelper · computeFastVerifyParams · 1513058 · 1831274 · 1611989 · 91 · - │
·················|···························|·············|·············|·············|··············|··············
| VRFGasHelper · decodePoint · 55844 · 55877 · 55867 · 10 · - │
·················|···························|·············|·············|·············|··············|··············
| VRFGasHelper · decodeProof · 56839 · 56860 · 56851 · 10 · - │
·················|···························|·············|·············|·············|··············|··············
| VRFGasHelper · fastVerify · 106360 · 352838 · 150715 · 94 · - │
·················|···························|·············|·············|·············|··············|··············
| VRFGasHelper · gammaToHash · 24189 · 24201 · 24198 · 91 · - │
·················|···························|·············|·············|·············|··············|··············
| VRFGasHelper · verify · 1543493 · 1862450 · 1643712 · 92 · - │
·················|···························|·············|·············|·············|··············|··············
| Deployments · · % of limit · │
·············································|·············|·············|·············|··············|··············
| VRFGasHelper · - · - · 1598637 · 23.8 % · - │
·--------------------------------------------|-------------|-------------|-------------|--------------|-------------·
195 passing (20m)
In Ethereum, gas consumption derived from Etherscan Average. USD price estimation derived from CoinMarketCap.
- 14 gwei/gas
- 1412.49 usd/eth
·----------------|---------------------------|-------------|-------------|-------------|--------------|-------------·
| Contract · Method · Min · Max · Avg · # calls · usd (avg) │
·----------------|---------------------------|-------------|-------------|-------------|--------------|-------------·
| VRF · verify · 1543493 · 1862450 · 1643712 · 92 · 32.50 │
·················|···························|·············|·············|·············|··············|··············
| VRF · fastVerify · 106360 · 352838 · 150715 · 94 · 2.98 │
·----------------|---------------------------|-------------|-------------|-------------|--------------|-------------·
·----------------|---------------------------|-------------|-------------|-------------|--------------|-------------·
| Contract · Method · Min · Max · Avg · # calls · usd (avg) │
·----------------|---------------------------|-------------|-------------|-------------|--------------|-------------·
| VRF · decodeProof · 56839 · 56860 · 56851 · 10 · 1.12 │
·················|···························|·············|·············|·············|··············|··············
| VRF · decodePoint · 55844 · 55877 · 55867 · 10 · 1.10 │
·················|···························|·············|·············|·············|··············|··············
| VRF · computeFastVerifyParams · 1513058 · 1831274 · 1611989 · 91 · 31.88 │
·----------------|---------------------------|-------------|-------------|-------------|--------------|-------------·
In Polygon, gas consumption derived from Polygonscan Average. USD price estimation derived from CoinMarketCap.
- 51.6 gwei/gas
- 0.91 usd/matic
·----------------|---------------------------|-------------|-------------|-------------|--------------|-------------·
| Contract · Method · Min · Max · Avg · # calls · usd (avg) │
·----------------|---------------------------|-------------|-------------|-------------|--------------|-------------·
| VRF · verify · 1543493 · 1862450 · 1643712 · 92 · 0.0772 │
·················|···························|·············|·············|·············|··············|··············
| VRF · fastVerify · 106360 · 352838 · 150715 · 94 · 0.0071 │
·················|···························|·············|·············|·············|··············|··············
| VRF · decodeProof · 56839 · 56860 · 56851 · 10 · 0.0027 │
·················|···························|·············|·············|·············|··············|··············
| VRF · decodePoint · 55844 · 55877 · 55867 · 10 · 0.0026 │
·················|···························|·············|·············|·············|··············|··············
| VRF · computeFastVerifyParams · 1513058 · 1831274 · 1611989 · 91 · 0.0757 │
·----------------|---------------------------|-------------|-------------|-------------|--------------|-------------·
The following resources have been used for test vectors:
Secp256k1: Chuck Batson- VRF with ciphersuite
SECP256K1_SHA256_TAI: vrf-rs
Some EC arithmetic operations have been opmitized thanks to the impressive work of the following resources:
- Post by Vitalik Buterin in Ethresearch
- SolCrypto library
vrf-solidity is published under the MIT license.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent