|
| 1 | +# Pyth Entropy Solidity SDK |
| 2 | + |
| 3 | +The Pyth Entropy Solidity SDK allows you to generate secure random numbers on the blockchain by |
| 4 | +interacting with the Pyth Entropy protocol. |
| 5 | +The SDK can be used for any application that requires random numbers, such as NFT mints, gaming, and more. |
| 6 | + |
| 7 | +## Install |
| 8 | + |
| 9 | +```shell copy |
| 10 | +npm install @pythnetwork/entropy-sdk-solidity |
| 11 | +``` |
| 12 | + |
| 13 | +## Setup |
| 14 | + |
| 15 | +To use the SDK, you need the address of an Entropy contract on your blockchain and a randomness provider. |
| 16 | +You can find current deployments [here](evm.mdx). |
| 17 | + |
| 18 | +Choose one of the networks and instantiate an `IEntropy` contract in your solidity contract: |
| 19 | + |
| 20 | +```solidity copy |
| 21 | + IEntropy entropy = IEntropy(<address>); |
| 22 | +``` |
| 23 | + |
| 24 | +## Usage |
| 25 | + |
| 26 | +To generate a random number, follow these steps. |
| 27 | + |
| 28 | +### 1. Commit to a random number |
| 29 | + |
| 30 | +Generate a 32-byte random number on the client side, then hash it with keccak256 to create a commitment. |
| 31 | +You can do this with typescript and web3.js as follows: |
| 32 | + |
| 33 | +```typescript copy |
| 34 | +const randomNumber = web3.utils.randomHex(32); |
| 35 | +const commitment = web3.utils.keccak256(randomNumber); |
| 36 | +``` |
| 37 | + |
| 38 | +### 2. Request a number from Entropy |
| 39 | + |
| 40 | +Invoke the `request` method of the `IEntropy` contract. |
| 41 | +The `request` method requires paying a fee in native gas tokens which is configured per-provider. |
| 42 | +Each entropy contracts has a default provider, you can get the default provider by calling the method `getDefaultProvider`. |
| 43 | + |
| 44 | +```solidity copy |
| 45 | +address provider = entropy.getDefaultProvider(); |
| 46 | +``` |
| 47 | + |
| 48 | +Use the `getFee` method to calculate the fee and send it as the value of the `request` call: |
| 49 | + |
| 50 | +```solidity copy |
| 51 | +uint fee = entropy.getFee(provider); |
| 52 | +uint64 sequenceNumber = entropy.request{value: fee}(provider, commitment, true); |
| 53 | +``` |
| 54 | + |
| 55 | +This method returns a sequence number. Store this sequence number for use in later steps. |
| 56 | +If you are invoking this off-chain, the method also emits a `PythRandomEvents.Requested` event that contains the sequence number in it. |
| 57 | + |
| 58 | +### 3. Fetch the provider's number |
| 59 | + |
| 60 | +Providers store their uri, with some other metadata, on chain when registering and that can be fetched by calling the method `getProviderInfo`. |
| 61 | +You need the provider's uri to fetch the provider's random number. |
| 62 | + |
| 63 | +For the provider `0x6CC14824Ea2918f5De5C2f75A9Da968ad4BD6344` you can query the webservice at https://fortuna-staging.pyth.network : |
| 64 | + |
| 65 | +```typescript copy |
| 66 | +await axios.get( |
| 67 | + `https://fortuna-staging.pyth.network/v1/chains/${chainName}/revelations/${sequenceNumber}` |
| 68 | +); |
| 69 | +``` |
| 70 | + |
| 71 | +This method returns a JSON object containing the provider's random number. |
| 72 | + |
| 73 | +### 4. Reveal the number |
| 74 | + |
| 75 | +Invoke the `reveal` method on the `IEntropy` contract: |
| 76 | + |
| 77 | +```solidity copy |
| 78 | +bytes32 randomNumber = entropy.reveal( |
| 79 | + provider, |
| 80 | + sequenceNumber, |
| 81 | + randomNumber, |
| 82 | + providerRandomNumber |
| 83 | +) |
| 84 | +``` |
| 85 | + |
| 86 | +This method will combine the user and provider's random numbers, along with the blockhash, to construct the final secure random number. |
| 87 | + |
| 88 | +## Example Application |
| 89 | + |
| 90 | +The [Coin Flip](https://github.com/pyth-network/pyth-crosschain/tree/main/target_chains/ethereum/examples/coin_flip) example demonstrates how to build a smart contract that |
| 91 | +interacts with Pyth Entropy as well as a typescript client for that application. |
0 commit comments