Skip to content

Commit 4b15232

Browse files
aditya520aditya520
committed
chore(entropy) Refactor guide
1 parent e54da23 commit 4b15232

File tree

4 files changed

+128
-48
lines changed

4 files changed

+128
-48
lines changed

‎components/FeeTable.tsx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ const FeeTable = ({
3333
<thead>
3434
<tr>
3535
<th>Chain Id</th>
36-
<th>Fee</th>
36+
<th>Fee (ETH)</th>
3737
</tr>
3838
</thead>
3939
<tbody>

‎pages/entropy/contract-addresses.mdx

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ import EntropyDeploymentTable from "../../components/EntropyDeploymentTable";
1414
showReveal={true}
1515
/>
1616

17-
The default provider for above mainnet chains is `0x52DeaA1c84233F7bb8C8A45baeDE41091c616506`.
17+
**The default provider for above mainnet chains is `0x52DeaA1c84233F7bb8C8A45baeDE41091c616506`.**
1818

1919
The default provider on mainnet has a reveal delay to avoid changes on the outcome of the Entropy request because of block reorgs.
2020
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.
@@ -33,8 +33,8 @@ The default provider fulfills the request by sending a transaction with a gas li
3333
showReveal={false}
3434
/>
3535

36-
The default provider for above testnet chains is `0x6CC14824Ea2918f5De5C2f75A9Da968ad4BD6344`.
36+
**The default provider for above testnet chains is `0x6CC14824Ea2918f5De5C2f75A9Da968ad4BD6344`.**
3737

38-
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.
38+
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.
3939

4040
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: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,5 @@
1-
# Generate Random Numbers
1+
# How to Generate Random Numbers
22

3-
Integrations simply call an on-chain function to request a random number from Entropy.
4-
This function takes a random number that you have generated off-chain and returns a sequence number.
5-
Entropy will then callback your contract with the generated random number once the request is fullfilled by the provider.
3+
Integrating Pyth Entropy requires a simple call an onchain function to request a random number from Entropy. The function takes a random number that one can generate offchain and pass it to the onchain function which returns a sequence number. Pyth Entropy will then callback your contract with the generated random number once the request is fulfilled.
64

75
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: 122 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1,46 +1,68 @@
1+
import { Tabs, Callout } from "nextra/components";
2+
13
# How to Generate Random Numbers in EVM Contracts Using Pyth Entropy
24

3-
This guide explains how to integrate Pyth Entropy into an EVM Contract to generate on-chain random numbers.
5+
This guide explains how to integrate Pyth Entropy into EVM Contracts to generate on-chain random numbers.
46
The intended audience for this guide is developers of any application that needs on-chain randomness, such as NFT mints or games.
57

68
## Install the SDK
79

8-
Pyth Entropy has a Solidity SDK that lets your contract interact with the Entropy contract.
10+
Pyth Entropy has a [Solidity SDK](https://github.com/pyth-network/pyth-crosschain/tree/main/target_chains/ethereum/entropy_sdk/solidity) that lets your contract interact with the Entropy contract.
911
Install the SDK using your package manager:
1012

13+
<Tabs items={['hardhat', 'foundry']}>
14+
<Tabs.Tab>
15+
```shell copy
16+
npm install @pythnetwork/entropy-sdk-solidity
17+
```
18+
</Tabs.Tab>
19+
<Tabs.Tab>
1120
```shell copy
21+
npm init -y
1222
npm install @pythnetwork/entropy-sdk-solidity
1323
```
1424

25+
Then add the following line to your `remappings.txt` :
26+
27+
```text copy
28+
@pythnetwork/entropy-sdk-solidity/=node_modules/@pythnetwork/entropy-sdk-solidity
29+
```
30+
31+
</Tabs.Tab>
32+
</Tabs>
33+
1534
## Setup
1635

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.
36+
The Solidity SDK exports two interfaces:
1937

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.
22-
Consult the current [Entropy contract addresses](../contract-addresses) to find the address on your chain.
23-
Once you have a contract address, instantiate an `IEntropy` contract in your solidity contract:
38+
- [`IEntropyConsumer`](https://github.com/pyth-network/pyth-crosschain/blob/main/target_chains/ethereum/entropy_sdk/solidity/IEntropyConsumer.sol) - The interface that your contract should implement. It makes sure that your contract is compliant with the Entropy contract.
39+
- [`IEntropy`](https://github.com/pyth-network/pyth-crosschain/blob/main/target_chains/ethereum/entropy_sdk/solidity/IEntropy.sol) - The interface to interact with the Entropy contract.
40+
You will need the address of an Entropy contract on your blockchain.
41+
Consult the current [Entropy contract addresses](../contract-addresses) to find the address on your chain.
42+
Once you have a contract address, instantiate an `IEntropy` contract in your solidity contract:
2443

2544
```solidity copy
2645
import { IEntropyConsumer } from "@pythnetwork/entropy-sdk-solidity/IEntropyConsumer.sol";
2746
import { IEntropy } from "@pythnetwork/entropy-sdk-solidity/IEntropy.sol";
2847
29-
contract YourContract is IEntropyConsumer {
30-
IEntropy entropy = IEntropy(<address>);
48+
// @param entropyAddress The address of the entropy contract.
49+
contract YourContract(address entropyAddress) is IEntropyConsumer {
50+
IEntropy entropy = IEntropy(entropyAddress);
3151
}
32-
3352
```
3453

35-
Entropy also requires selecting a randomness provider. The randomness provider is a third-party
54+
<Callout type="info">
55+
Entropy also requires selecting a **randomness provider**. The randomness provider is a third-party
3656
who participates in the generation process. Each provider is identified by an address and hosts
3757
a keeper service for fullfilling requests.
3858

39-
The simplest way to choose a provider is to use the default provider.
59+
The simplest way to choose a provider is to use the default provider called [**Fortuna**](https://github.com/pyth-network/pyth-crosschain/tree/main/apps/fortuna).
4060
The default provider for each contract and their corresponding URI is also listed in the
4161
[Entropy contract addresses](../contract-addresses).
4262

43-
You can also get the default provider's address by calling the `getDefaultProvider` method:
63+
</Callout>
64+
65+
You can also get the default provider's address by calling the [`getDefaultProvider`](https://github.com/pyth-network/pyth-crosschain/blob/main/target_chains/ethereum/entropy_sdk/solidity/IEntropy.sol#L94) method:
4466

4567
```solidity copy
4668
address provider = entropy.getDefaultProvider();
@@ -53,49 +75,109 @@ To generate a random number, follow these steps.
5375
### 1. Generate a random number
5476

5577
Generate a 32-byte random number on the client side.
56-
You can do this with typescript and web3.js as follows:
5778

58-
```typescript copy
59-
const randomNumber = web3.utils.randomHex(32);
60-
```
79+
<Tabs items={["web3.js", "ethers.js"]}>
80+
<Tabs.Tab>
81+
```typescript copy const userRandomNumber = web3.utils.randomHex(32); ```
82+
</Tabs.Tab>
83+
<Tabs.Tab>
84+
```typescript copy const userRandomNumber = ethers.utils.randomBytes(32);
85+
```
86+
</Tabs.Tab>
87+
</Tabs>
6188

6289
### 2. Request a number from Entropy
6390

64-
Invoke the `requestWithCallback` method of the `IEntropy` contract.
91+
Invoke the [`requestWithCallback`](https://github.com/pyth-network/pyth-crosschain/blob/main/target_chains/ethereum/entropy_sdk/solidity/IEntropy.sol#L83) method of the `IEntropy` contract.
6592
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:
93+
94+
The fees differs for every chain and can be found at the [Current Fees](../current-fees) page. \
95+
You can use the onchain method [`getFee`](https://github.com/pyth-network/pyth-crosschain/blob/main/target_chains/ethereum/entropy_sdk/solidity/IEntropy.sol#L101) to calculate the fee for the default provider and send it as the value of the `requestWithCallback` call:
6796

6897
```solidity copy
69-
uint fee = entropy.getFee(provider);
70-
uint64 sequenceNumber = entropy.requestWithCallback{value: fee}(provider, randomNumber);
98+
function requestRandomNumber(bytes32 userRandomNumber) external payable {
99+
uint256 fee = entropy.getFee(entropyProvider);
100+
101+
uint64 sequenceNumber = entropy.requestWithCallback{ value: fee }(
102+
entropyProvider,
103+
userRandomNumber
104+
);
105+
}
106+
71107
```
72108

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.
109+
This method returns a sequence number and emits a [`RequestedWithCallback`](https://github.com/pyth-network/pyth-crosschain/blob/main/target_chains/ethereum/entropy_sdk/solidity/EntropyEvents.sol#L10) event. You can store this sequence number to identify the request in next step.
74110

75111
### 3. Implement callback for Entropy
76112

77-
```solidity copy
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-
}
113+
```solidity {28-37} copy
114+
pragma solidity ^0.8.0;
115+
116+
import { IEntropyConsumer } from "@pythnetwork/entropy-sdk-solidity/IEntropyConsumer.sol";
117+
import { IEntropy } from "@pythnetwork/entropy-sdk-solidity/IEntropy.sol";
83118
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.
119+
contract YourContract is IEntropyConsumer {
120+
IEntropy entropy;
121+
122+
// @param entropyAddress The address of the entropy contract.
123+
constructor(address entropyAddress) {
124+
entropy = IEntropy(entropyAddress);
125+
}
126+
127+
// @param userRandomNumber The random number generated by the user.
128+
function requestRandomNumber(bytes32 userRandomNumber) external payable {
129+
// Get the default provider and the fee for the request
130+
address entropyProvider = entropy.getDefaultProvider();
131+
uint256 fee = entropy.getFee(entropyProvider);
132+
133+
// Request the random number with the callback
134+
uint64 sequenceNumber = entropy.requestWithCallback{ value: fee }(
135+
entropyProvider,
136+
userRandomNumber
137+
);
138+
// Store the sequence number to identify the callback request
139+
}
140+
141+
// It is called by the entropy contract when a random number is generated.
142+
function entropyCallback(
143+
uint64 sequenceNumber,
144+
// If your app uses multiple providers, you can use this argument to
145+
// distinguish which one is calling the app back.
146+
address provider,
147+
bytes32 randomNumber
148+
) internal override {
149+
// Implement your callback logic here.
150+
}
151+
152+
// This method is required by the IEntropyConsumer interface.
153+
// It returns the address of the entropy contract which will call the callback.
154+
function getEntropy() internal view override returns (address) {
155+
return address(entropy);
156+
}
93157
}
94158
95159
```
96160

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.
161+
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.
162+
163+
**The entropyCallback function should be implemented in the same contract that is requesting the random number.**
98164

99165
## Additional Resources
100166

101-
If you are having trouble getting the callback to run, please see the guide on how to [Debug Callback Failures](/entropy/debug-callback-failures).
167+
You may find these additional resources helpful while integrating Pyth Entropy into your EVM contract.
168+
169+
### Debug Callback Failures
170+
171+
Check how to [Debug Callback Failures](/entropy/debug-callback-failures) if you are having trouble getting the callback to run.
172+
173+
### Pyth Entropy Contract Addresses
174+
175+
Consult the [Entropy contract addresses](../contract-addresses) to find the Entropy contract address on your chain.
176+
177+
### Current Fees
178+
179+
Check the [Current Fees](../current-fees) to find the current fee for each provider on your chain.
180+
181+
### Best Practices
182+
183+
Check out the [Best Practices](/entropy/best-practices) guide for tips to limit gas usage, or generate multiple random numbers in a single transaction.

0 commit comments

Comments
 (0)