Skip to content

Commit a4f51d4

Browse files
author
Dev Kalra
authored
[entropy]: update docs for entropy-v2 (#251)
* update how to guide for evm * minor updates * update generate random numbers page * add gas limit * add a disclaimer * precommit fix * remove link * minor * precommit fix * address feedback * precommit fix
1 parent fda82c5 commit a4f51d4

File tree

4 files changed

+81
-78
lines changed

4 files changed

+81
-78
lines changed

‎pages/entropy/best-practices.mdx

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@ Developers integrating Entropy into their applications should consider using som
44

55
## Incomplete Requests
66

7+
Note: The following best practices are only applicable for the manual reveal without automatic callback.
8+
79
Users of Entropy-powered protocols can choose not to complete the protocol.
810
They can compute the random number after it is fully determined, but before revealing it to the contract.
911
Hence, they can choose to stop the protocol at this point if they do not like the chosen random number.

‎pages/entropy/contract-addresses.mdx

Lines changed: 33 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -2,43 +2,45 @@
22

33
## Mainnets
44

5-
| Chain Id | Entropy Contract Address | Reveal Delay |
6-
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------ |
7-
| lightlink-phoenix | [`0x98046Bd286715D3B0BC227Dd7a956b83D8978603`](https://phoenix.lightlink.io/address/0x98046Bd286715D3B0BC227Dd7a956b83D8978603) | 1 block |
8-
| chiliz | [`0x0708325268dF9F66270F1401206434524814508b`](https://scan.chiliz.com/address/0x0708325268dF9F66270F1401206434524814508b) | 12 blocks |
9-
| arbitrum | [`0x7698E925FfC29655576D0b361D75Af579e20AdAc`](https://arbiscan.io/address/0x7698E925FfC29655576D0b361D75Af579e20AdAc) | 6 blocks |
10-
| optimism | [`0xdF21D137Aadc95588205586636710ca2890538d5`](https://optimistic.etherscan.io/address/0xdF21D137Aadc95588205586636710ca2890538d5) | Until `safe` |
11-
| mode | [`0x8D254a21b3C86D32F7179855531CE99164721933`](https://explorer.mode.network/address/0x8D254a21b3C86D32F7179855531CE99164721933) | Until `safe` |
12-
| blast | [`0x5744Cbf430D99456a0A8771208b674F27f8EF0Fb`](https://blastscan.io/address/0x5744Cbf430D99456a0A8771208b674F27f8EF0Fb) | 1 block |
13-
| zetachain | [`0x36825bf3Fbdf5a29E2d5148bfe7Dcf7B5639e320`](https://zetachain.blockscout.com/address/0x36825bf3Fbdf5a29E2d5148bfe7Dcf7B5639e320) | 0 block |
14-
| base | [`0x6E7D74FA7d5c90FEF9F0512987605a6d546181Bb`](https://basescan.org/address/0x6E7D74FA7d5c90FEF9F0512987605a6d546181Bb) | 1 block |
15-
16-
The default provider for above mainnet chains is `0x52DeaA1c84233F7bb8C8A45baeDE41091c616506`. The Fortuna URL for the default provider is `https://fortuna.dourolabs.app/v1/chains/<chain>`,
17-
where `<chain>` is the chain id from the leftmost column.
5+
| Chain Id | Entropy Contract Address | Reveal Delay | Gas Limit |
6+
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------ | --------- |
7+
| lightlink-phoenix | [`0x98046Bd286715D3B0BC227Dd7a956b83D8978603`](https://phoenix.lightlink.io/address/0x98046Bd286715D3B0BC227Dd7a956b83D8978603) | 1 block | 500K |
8+
| chiliz | [`0x0708325268dF9F66270F1401206434524814508b`](https://scan.chiliz.com/address/0x0708325268dF9F66270F1401206434524814508b) | 12 blocks | 500K |
9+
| arbitrum | [`0x7698E925FfC29655576D0b361D75Af579e20AdAc`](https://arbiscan.io/address/0x7698E925FfC29655576D0b361D75Af579e20AdAc) | 6 blocks | 500K |
10+
| optimism | [`0xdF21D137Aadc95588205586636710ca2890538d5`](https://optimistic.etherscan.io/address/0xdF21D137Aadc95588205586636710ca2890538d5) | Until `safe` | 500K |
11+
| mode | [`0x8D254a21b3C86D32F7179855531CE99164721933`](https://explorer.mode.network/address/0x8D254a21b3C86D32F7179855531CE99164721933) | Until `safe` | 500K |
12+
| blast | [`0x5744Cbf430D99456a0A8771208b674F27f8EF0Fb`](https://blastscan.io/address/0x5744Cbf430D99456a0A8771208b674F27f8EF0Fb) | 1 block | 500K |
13+
| zetachain | [`0x36825bf3Fbdf5a29E2d5148bfe7Dcf7B5639e320`](https://zetachain.blockscout.com/address/0x36825bf3Fbdf5a29E2d5148bfe7Dcf7B5639e320) | 0 block | 500K |
14+
| base | [`0x6E7D74FA7d5c90FEF9F0512987605a6d546181Bb`](https://basescan.org/address/0x6E7D74FA7d5c90FEF9F0512987605a6d546181Bb) | 1 block | 500K |
15+
16+
The default provider for above mainnet chains is `0x52DeaA1c84233F7bb8C8A45baeDE41091c616506`.
1817

1918
The default provider on mainnet has a reveal delay to avoid changes on the outcome of the Entropy request because of block reorgs.
2019
The reveal delay can be a number of blocks (measured from the `latest` block) or `safe` which means the reveal will be delayed until the request transaction is included in a block with `safe` tag.
2120
Read [here](https://www.alchemy.com/overviews/ethereum-commitment-levels) for more information on commitment levels.
2221

22+
The default provider fulfills the request by sending a transaction with a gas limit as mentioned in above table. Entropy callbacks the consumer as part of this transaction.
23+
2324
## Testnets
2425

25-
| Chain Id | Entropy Contract Address |
26-
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
27-
| lightlink-pegasus | [`0x8250f4aF4B972684F7b336503E2D6dFeDeB1487a`](https://pegasus.lightlink.io/address/0x8250f4aF4B972684F7b336503E2D6dFeDeB1487a) |
28-
| chiliz-spicy | [`0xD458261E832415CFd3BAE5E416FdF3230ce6F134`](https://spicy-explorer.chiliz.com/address/0xD458261E832415CFd3BAE5E416FdF3230ce6F134) |
29-
| conflux-espace-testnet | [`0xdF21D137Aadc95588205586636710ca2890538d5`](https://evmtestnet.confluxscan.io/address/0xdF21D137Aadc95588205586636710ca2890538d5) |
30-
| mode-sepolia | [`0x98046Bd286715D3B0BC227Dd7a956b83D8978603`](https://sepolia.explorer.mode.network/address/0x98046Bd286715D3B0BC227Dd7a956b83D8978603) |
31-
| sei-evm-devnet | [`0x6E3A2a644eeDCf6007d3c7d85F0094Cc1B25B2AE`](https://seitrace.com/address/0x6E3A2a644eeDCf6007d3c7d85F0094Cc1B25B2AE) |
32-
| arbitrum-sepolia | [`0x549Ebba8036Ab746611B4fFA1423eb0A4Df61440`](https://sepolia.arbiscan.io/address/0x549Ebba8036Ab746611B4fFA1423eb0A4Df61440) |
33-
| fantom-sonic | [`0xb27e5ca259702f209a29225d0eDdC131039C9933`](https://public-sonic.fantom.network/address/0xb27e5ca259702f209a29225d0eddc131039c9933) |
34-
| blast-testnet | [`0x98046Bd286715D3B0BC227Dd7a956b83D8978603`](https://testnet.blastscan.io/address/0x98046Bd286715D3B0BC227Dd7a956b83D8978603) |
35-
| optimism-sepolia | [`0x4821932D0CDd71225A6d914706A621e0389D7061`](https://optimism-sepolia.blockscout.com/address/0x4821932D0CDd71225A6d914706A621e0389D7061) |
36-
| base-sepolia | [`0x41c9e39574F40Ad34c79f1C99B66A45eFB830d4c`](https://base-sepolia.blockscout.com/address/0x41c9e39574F40Ad34c79f1C99B66A45eFB830d4c) |
37-
| berachain-testnet | [`0x26DD80569a8B23768A1d80869Ed7339e07595E85`](https://artio.beratrail.io/address/0x26DD80569a8B23768A1d80869Ed7339e07595E85) |
38-
| coredao-testnet | [`0xf0a1b566B55e0A0CB5BeF52Eb2a57142617Bee67`](https://scan.test.btcs.network/address/0xf0a1b566B55e0A0CB5BeF52Eb2a57142617Bee67) |
39-
| zetachain-testnet | [`0x4374e5a8b9C22271E9EB878A2AA31DE97DF15DAF`](https://explorer.zetachain.com/address/0x4374e5a8b9C22271E9EB878A2AA31DE97DF15DAF) |
40-
41-
The default provider for above testnet chains is `0x6CC14824Ea2918f5De5C2f75A9Da968ad4BD6344`. The Fortuna URL for the default provider is `https://fortuna-staging.dourolabs.app/v1/chains/<chain>`,
42-
where `<chain>` is the chain id from the leftmost column.
26+
| Chain Id | Entropy Contract Address | Gas Limit |
27+
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | --------- |
28+
| lightlink-pegasus | [`0x8250f4aF4B972684F7b336503E2D6dFeDeB1487a`](https://pegasus.lightlink.io/address/0x8250f4aF4B972684F7b336503E2D6dFeDeB1487a) | 500K |
29+
| chiliz-spicy | [`0xD458261E832415CFd3BAE5E416FdF3230ce6F134`](https://spicy-explorer.chiliz.com/address/0xD458261E832415CFd3BAE5E416FdF3230ce6F134) | 500K |
30+
| conflux-espace-testnet | [`0xdF21D137Aadc95588205586636710ca2890538d5`](https://evmtestnet.confluxscan.io/address/0xdF21D137Aadc95588205586636710ca2890538d5) | 500K |
31+
| mode-sepolia | [`0x98046Bd286715D3B0BC227Dd7a956b83D8978603`](https://sepolia.explorer.mode.network/address/0x98046Bd286715D3B0BC227Dd7a956b83D8978603) | 500K |
32+
| sei-evm-devnet | [`0x6E3A2a644eeDCf6007d3c7d85F0094Cc1B25B2AE`](https://seitrace.com/address/0x6E3A2a644eeDCf6007d3c7d85F0094Cc1B25B2AE) | 500K |
33+
| arbitrum-sepolia | [`0x549Ebba8036Ab746611B4fFA1423eb0A4Df61440`](https://sepolia.arbiscan.io/address/0x549Ebba8036Ab746611B4fFA1423eb0A4Df61440) | 500K |
34+
| fantom-sonic | [`0xb27e5ca259702f209a29225d0eDdC131039C9933`](https://public-sonic.fantom.network/address/0xb27e5ca259702f209a29225d0eddc131039c9933) | 500K |
35+
| blast-testnet | [`0x98046Bd286715D3B0BC227Dd7a956b83D8978603`](https://testnet.blastscan.io/address/0x98046Bd286715D3B0BC227Dd7a956b83D8978603) | 500K |
36+
| optimism-sepolia | [`0x4821932D0CDd71225A6d914706A621e0389D7061`](https://optimism-sepolia.blockscout.com/address/0x4821932D0CDd71225A6d914706A621e0389D7061) | 500K |
37+
| base-sepolia | [`0x41c9e39574F40Ad34c79f1C99B66A45eFB830d4c`](https://base-sepolia.blockscout.com/address/0x41c9e39574F40Ad34c79f1C99B66A45eFB830d4c) | 500K |
38+
| berachain-testnet | [`0x26DD80569a8B23768A1d80869Ed7339e07595E85`](https://artio.beratrail.io/address/0x26DD80569a8B23768A1d80869Ed7339e07595E85) | 500K |
39+
| coredao-testnet | [`0xf0a1b566B55e0A0CB5BeF52Eb2a57142617Bee67`](https://scan.test.btcs.network/address/0xf0a1b566B55e0A0CB5BeF52Eb2a57142617Bee67) | 500K |
40+
| zetachain-testnet | [`0x4374e5a8b9C22271E9EB878A2AA31DE97DF15DAF`](https://explorer.zetachain.com/address/0x4374e5a8b9C22271E9EB878A2AA31DE97DF15DAF) | 500K |
41+
42+
The default provider for above testnet chains is `0x6CC14824Ea2918f5De5C2f75A9Da968ad4BD6344`.
4343

4444
The default provider on testnet doesn't have a reveal delay. It reveals the commitment as soon as the request transaction is included in a block.
45+
46+
The default provider fulfills the request by sending a transaction with a gas limit as mentioned in above table. Entropy callbacks the consumer as part of this transaction.

‎pages/entropy/generate-random-numbers.mdx

Lines changed: 4 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,9 @@
11
# Generate Random Numbers
22

3-
Integrations use a simple four-step process, with two off-chain steps and two-on chain steps:
3+
Integrations use a simple one-step on-chain process:
44

5-
1. **Commit** to a random number. Generate a random value off-chain and hash it to create a commitment.
6-
1. **Request** a random number. Send a transaction with the commitment to the Entropy contract and receive a sequence number.
7-
1. **Retrieve** part of the random number. Submit the sequence number from (2) to a webservice to receive a random payload.
8-
1. **Reveal** the random number. Send a transaction with the sequence number from (2) , random value from (1), and the
9-
payload from (3) to the Entropy contract and receive the secure random number.
5+
1. **Request** a random number. Send a transaction with a random number that you have generated off-chain and receive a sequence number.
106

11-
See [How to Generate Random numbers in EVM dApps](generate-random-numbers/evm.mdx) to integrate your application with Pyth Entropy.
7+
Entropy will callback your contract with the generated random number once the request is fullfilled by the provider.
128

13-
Developers building on Entropy should also consult the [Best Practices](best-practices.mdx) section to learn how to avoid common security mistakes.
9+
See [How to Generate Random numbers in EVM dApps](generate-random-numbers/evm.mdx) to integrate your application with Pyth Entropy.

‎pages/entropy/generate-random-numbers/evm.mdx

Lines changed: 42 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -14,81 +14,84 @@ npm install @pythnetwork/entropy-sdk-solidity
1414

1515
## Setup
1616

17-
To use the SDK, you need the address of an Entropy contract on your blockchain.
17+
The SDK exports a `IEntropyConsumer` interface that your contract should implement. The interface
18+
makes sure that your contract is compliant with the Entropy contract.
19+
20+
The SDK also export `IEntropy` interface which you can use to interact with the Entropy contract.
21+
You will need the address of an Entropy contract on your blockchain.
1822
Consult the current [Entropy contract addresses](../contract-addresses) to find the address on your chain.
1923
Once you have a contract address, instantiate an `IEntropy` contract in your solidity contract:
2024

2125
```solidity copy
22-
IEntropy entropy = IEntropy(<address>);
26+
import { IEntropyConsumer } from "@pythnetwork/entropy-sdk-solidity/contracts/IEntropyConsumer.sol";
27+
import { IEntropy } from "@pythnetwork/entropy-sdk-solidity/contracts/IEntropy.sol";
28+
29+
contract YourContract is IEntropyConsumer {
30+
IEntropy entropy = IEntropy(<address>);
31+
}
32+
2333
```
2434

25-
Entropy also requires selecting a randomness provider.
26-
The randomness provider is a third-party who participates in the generation process.
27-
Each provider is identified by an address and hosts the Fortuna webservice at a URI.
28-
You will need both the provider address and the URL for the integration.
35+
Entropy also requires selecting a randomness provider. The randomness provider is a third-party
36+
who participates in the generation process. Each provider is identified by an address and hosts
37+
a keeper service for fullfilling requests.
2938

3039
The simplest way to choose a provider is to use the default provider.
3140
The default provider for each contract and their corresponding URI is also listed in the
3241
[Entropy contract addresses](../contract-addresses).
3342

34-
You can also get the default provider's address by calling the `getDefaultProvider` method, then
35-
get the provider's Fortuna URI by calling `getProviderInfo`:
43+
You can also get the default provider's address by calling the `getDefaultProvider` method:
3644

3745
```solidity copy
3846
address provider = entropy.getDefaultProvider();
39-
bytes providerUri = entropy.getProviderInfo().uri;
4047
```
4148

4249
## Usage
4350

4451
To generate a random number, follow these steps.
4552

46-
### 1. Commit to a random number
53+
### 1. Generate a random number
4754

48-
Generate a 32-byte random number on the client side, then hash it with keccak256 to create a commitment.
55+
Generate a 32-byte random number on the client side.
4956
You can do this with typescript and web3.js as follows:
5057

5158
```typescript copy
5259
const randomNumber = web3.utils.randomHex(32);
53-
const commitment = web3.utils.keccak256(randomNumber);
5460
```
5561

5662
### 2. Request a number from Entropy
5763

58-
Invoke the `request` method of the `IEntropy` contract.
59-
The `request` method requires paying a fee in native gas tokens which is configured per-provider.
60-
Use the `getFee` method to calculate the fee and send it as the value of the `request` call:
64+
Invoke the `requestWithCallback` method of the `IEntropy` contract.
65+
The `requestWithCallback` method requires paying a fee in native gas tokens which is configured per-provider.
66+
Use the `getFee` method to calculate the fee and send it as the value of the `requestWithCallback` call:
6167

6268
```solidity copy
6369
uint fee = entropy.getFee(provider);
64-
uint64 sequenceNumber = entropy.request{value: fee}(provider, commitment, true);
70+
uint64 sequenceNumber = entropy.requestWithCallback{value: fee}(provider, randomNumber);
6571
```
6672

67-
This method returns a sequence number. Store this sequence number for use in later steps.
68-
If you are invoking this off-chain, the method also emits a `PythRandomEvents.Requested` event that contains the sequence number in it.
73+
This method returns a sequence number and emits a `RequestedWithCallback` event. You can store this sequence number to identify the request in next step.
6974

70-
### 3. Fetch the provider's number
71-
72-
Submit a query to the `/revelations/` endpoint of the provider's Fortuna webservice.
73-
This endpoint takes a single path parameter, which is the sequence number of the request.
74-
75-
```typescript copy
76-
await axios.get(`${providerUri}/revelations/${sequenceNumber}`);
77-
```
78-
79-
This method returns a JSON object containing the provider's random number.
80-
81-
### 4. Reveal the number
82-
83-
Invoke the `reveal` method on the `IEntropy` contract:
75+
### 3. Implement callback for Entropy
8476

8577
```solidity copy
86-
bytes32 randomNumber = entropy.reveal(
87-
provider,
88-
sequenceNumber,
89-
randomNumber,
90-
providerRandomNumber
91-
)
78+
// This method is required by the IEntropyConsumer interface.
79+
// It returns the address of the entropy contract which will call the callback.
80+
function getEntropy() internal view override returns (address) {
81+
return address(entropy);
82+
}
83+
84+
// It is called by the entropy contract when a random number is generated.
85+
function entropyCallback(
86+
uint64 sequenceNumber,
87+
// If your app uses multiple providers, you can use this argument to
88+
// distinguish which one is calling the app back.
89+
address provider,
90+
bytes32 randomNumber
91+
) internal override {
92+
// Implement your callback logic here.
93+
}
94+
9295
```
9396

94-
This method will combine the user and provider's random numbers, along with the blockhash, to construct the final secure random number.
97+
When the final random number is ready to use, the entropyCallback function will be called by the Entropy contract. This will happen in a separate transaction submitted by the requested provider. The entropyCallback function should be implemented in the same contract that is requesting the random number.

0 commit comments

Comments
 (0)