Skip to content

Commit 332c3ea

Browse files
aditya520aditya520
authored
chore(dev-hub) Move Entropy pages (#3016)
1 parent faad438 commit 332c3ea

21 files changed

+726
-74
lines changed

‎apps/developer-hub/content/docs/entropy/best-practices.mdx

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
---
2+
title: Best Practices
3+
description: Best practices for using Pyth Entropy in your applications
4+
---
5+
6+
# Best Practices
7+
8+
## Limit gas usage on the callback
9+
10+
Keeping the callback function simple is crucial because the entropy providers limit gas usage.
11+
This ensures gas usage is predictable and consistent, avoiding potential issues with the callback.
12+
13+
For example, if you want to use entropy to generate a random number for each player in a round of game,
14+
you need to make sure that the callback function works for the maximum number of players that can be in each round.
15+
Otherwise, the callbacks will work for some rounds with fewer players, but will fail for rounds with more players.
16+
17+
Multiple solutions are possible to address this problem. You can store the random number received from the callback and
18+
either ask users to submit more transactions after the callback to continue the flow or run a background crank service
19+
to submit the necessary transactions.
20+
21+
The gas limit for each chain is listed on the [contract addresses](contract-addresses) page.
22+
23+
## Handling callback failures
24+
25+
While the default entropy provider is highly reliable, in rare cases a callback might not be received. This typically happens when there's an issue with your contract's callback implementation rather than with the provider itself. The most common causes are:
26+
27+
1. The callback function is using more gas than the allowed limit
28+
2. The callback function contains logic that throws an error
29+
30+
If you're not receiving a callback, you can manually invoke it to identify the specific issue. This allows you to:
31+
32+
- See if the transaction fails and why
33+
- Check the gas usage against the chain's callback gas limit
34+
- Debug your callback implementation
35+
36+
For detailed instructions on how to manually invoke and debug callbacks, refer to the [Debug Callback Failures](debug-callback-failures) guide.
37+
38+
## Generating random values within a specific range
39+
40+
You can map the random number provided by Entropy into a smaller range using the solidity [modulo operator](https://docs.soliditylang.org/en/latest/types.html#modulo).
41+
Here is a simple example of how to map a random number provided by Entropy into a range between `minRange` and `maxRange` (inclusive).
42+
43+
```solidity
44+
// Maps a random number into a range between minRange and maxRange (inclusive)
45+
function mapRandomNumber(
46+
bytes32 randomNumber,
47+
int256 minRange,
48+
int256 maxRange
49+
) internal pure returns (int256) {
50+
require(minRange <= maxRange, "Invalid range");
51+
52+
uint256 range = uint256(maxRange - minRange + 1);
53+
uint256 randomUint = uint256(randomNumber);
54+
55+
return minRange + int256(randomUint % range);
56+
}
57+
```

‎apps/developer-hub/content/docs/entropy/contract-addresses.mdx

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
title: Contract Addresses
3+
description: Entropy contract addresses on different networks
4+
---
5+
6+
# Entropy Contract Addresses on EVM
7+
8+
## Mainnets
9+
10+
The Entropy contract is deployed on the following mainnet chains:
11+
12+
| Network | Contract Address | Gas Limit | Provider |
13+
| --------- | -------------------------------------------- | --------- | -------------------------------------------- |
14+
| Ethereum | `0x98046Bd286715D3B0BC227Dd7a956b83D8978603` | 100,000 | `0x52DeaA1c84233F7bb8C8A45baeDE41091c616506` |
15+
| Arbitrum | `0x23f0e8FAeE7bbb405E7A7C3d60138FCfd43d7509` | 100,000 | `0x52DeaA1c84233F7bb8C8A45baeDE41091c616506` |
16+
| Avalanche | `0x36825bf3Fbdf5a29E2d5148bfe7Dcf7B5639e320` | 100,000 | `0x52DeaA1c84233F7bb8C8A45baeDE41091c616506` |
17+
| Base | `0x98046Bd286715D3B0BC227Dd7a956b83D8978603` | 100,000 | `0x52DeaA1c84233F7bb8C8A45baeDE41091c616506` |
18+
| BNB Chain | `0x98046Bd286715D3B0BC227Dd7a956b83D8978603` | 100,000 | `0x52DeaA1c84233F7bb8C8A45baeDE41091c616506` |
19+
| Optimism | `0x98046Bd286715D3B0BC227Dd7a956b83D8978603` | 100,000 | `0x52DeaA1c84233F7bb8C8A45baeDE41091c616506` |
20+
| Polygon | `0x98046Bd286715D3B0BC227Dd7a956b83D8978603` | 100,000 | `0x52DeaA1c84233F7bb8C8A45baeDE41091c616506` |
21+
22+
**The default provider for above mainnet chains is `0x52DeaA1c84233F7bb8C8A45baeDE41091c616506`.**
23+
24+
The default provider on mainnet has a reveal delay to avoid changes on the outcome of the Entropy request because of block reorgs.
25+
The reveal delay shows how many blocks should be produced after the block including the request transaction in order to reveal and submit a callback transaction.
26+
27+
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.
28+
29+
## Testnets
30+
31+
The Entropy contract is deployed on the following testnet chains:
32+
33+
| Network | Contract Address | Gas Limit | Provider |
34+
| ---------------- | -------------------------------------------- | --------- | -------------------------------------------- |
35+
| Ethereum Sepolia | `0x41c9e39574F40Ad34c79f1C99B66A45eFB830d4c` | 100,000 | `0x6CC14824Ea2918f5De5C2f75A9Da968ad4BD6344` |
36+
| Arbitrum Sepolia | `0x36825bf3Fbdf5a29E2d5148bfe7Dcf7B5639e320` | 100,000 | `0x6CC14824Ea2918f5De5C2f75A9Da968ad4BD6344` |
37+
| Avalanche Fuji | `0x36825bf3Fbdf5a29E2d5148bfe7Dcf7B5639e320` | 100,000 | `0x6CC14824Ea2918f5De5C2f75A9Da968ad4BD6344` |
38+
| Base Sepolia | `0x41c9e39574F40Ad34c79f1C99B66A45eFB830d4c` | 100,000 | `0x6CC14824Ea2918f5De5C2f75A9Da968ad4BD6344` |
39+
| BNB Testnet | `0x41c9e39574F40Ad34c79f1C99B66A45eFB830d4c` | 100,000 | `0x6CC14824Ea2918f5De5C2f75A9Da968ad4BD6344` |
40+
| Optimism Sepolia | `0x41c9e39574F40Ad34c79f1C99B66A45eFB830d4c` | 100,000 | `0x6CC14824Ea2918f5De5C2f75A9Da968ad4BD6344` |
41+
| Polygon Amoy | `0x41c9e39574F40Ad34c79f1C99B66A45eFB830d4c` | 100,000 | `0x6CC14824Ea2918f5De5C2f75A9Da968ad4BD6344` |
42+
43+
**The default provider for above testnet chains is `0x6CC14824Ea2918f5De5C2f75A9Da968ad4BD6344`.**
44+
45+
The default provider on testnet has reveal delays identical to the corresponding mainnet chains to ensure consistent environment.
46+
47+
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.

‎apps/developer-hub/content/docs/entropy/create-your-first-entropy-app.mdx

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
---
2+
title: Create your first Entropy app on EVM
3+
description: Build a coin flip application using Pyth Entropy
4+
---
5+
6+
# Create your first Entropy app on EVM
7+
8+
In this tutorial we will implement and deploy a coin flip contract which will use entropy to generate a random output.
9+
10+
## Preliminaries
11+
12+
Before we start, please make sure you have the following tools installed:
13+
14+
- [Foundry](https://book.getfoundry.sh/getting-started/installation)
15+
- [Node.js](https://nodejs.org/en/download) (version >= v18.0.0)
16+
17+
## Getting Started
18+
19+
Create a directory named `coin-flip` and initialize a new Foundry project:
20+
21+
```bash
22+
mkdir coin-flip
23+
cd coin-flip
24+
forge init contracts
25+
```
26+
27+
Install the Pyth Entropy SDK:
28+
29+
```bash
30+
cd contracts
31+
npm init -y
32+
npm install @pythnetwork/entropy-sdk-solidity
33+
```
34+
35+
Add a `remappings.txt` file to the `contracts` directory:
36+
37+
```text
38+
@pythnetwork/entropy-sdk-solidity/=node_modules/@pythnetwork/entropy-sdk-solidity
39+
```
40+
41+
## Smart Contract Implementation
42+
43+
Replace the content of `contracts/src/Counter.sol` with the following coin flip contract:
44+
45+
```solidity
46+
// SPDX-License-Identifier: MIT
47+
pragma solidity ^0.8.0;
48+
49+
import "@pythnetwork/entropy-sdk-solidity/IEntropy.sol";
50+
import "@pythnetwork/entropy-sdk-solidity/IEntropyConsumer.sol";
51+
52+
contract CoinFlip is IEntropyConsumer {
53+
IEntropy entropy;
54+
55+
struct FlipRequest {
56+
address player;
57+
bool isHeads;
58+
}
59+
60+
mapping(uint64 => FlipRequest) public requests;
61+
mapping(address => uint256) public results; // 0 = not played, 1 = won, 2 = lost
62+
63+
constructor(address entropyAddress) {
64+
entropy = IEntropy(entropyAddress);
65+
}
66+
67+
function flipCoin(bool isHeads) external payable {
68+
uint256 fee = entropy.getFee(entropy.getDefaultProvider());
69+
require(msg.value >= fee, "Insufficient fee");
70+
71+
bytes32 userRandomNumber = keccak256(abi.encode(block.timestamp, msg.sender));
72+
uint64 sequenceNumber = entropy.requestWithCallback{value: fee}(
73+
entropy.getDefaultProvider(),
74+
userRandomNumber
75+
);
76+
77+
requests[sequenceNumber] = FlipRequest(msg.sender, isHeads);
78+
}
79+
80+
function entropyCallback(
81+
uint64 sequenceNumber,
82+
address,
83+
bytes32 randomNumber
84+
) internal override {
85+
FlipRequest memory request = requests[sequenceNumber];
86+
bool coinIsHeads = uint256(randomNumber) % 2 == 0;
87+
88+
if (coinIsHeads == request.isHeads) {
89+
results[request.player] = 1; // won
90+
} else {
91+
results[request.player] = 2; // lost
92+
}
93+
}
94+
}
95+
```
96+
97+
## Deployment
98+
99+
Create a deployment script and deploy to Optimism Sepolia testnet. Check the [contract addresses](contract-addresses) page for the Entropy contract address on your chosen network.
100+
101+
## Next Steps
102+
103+
- Add more complex game logic
104+
- Implement proper error handling
105+
- Add events for better tracking
106+
- Consider gas optimization techniques
107+
108+
For a complete example with deployment scripts and frontend integration, see the [Coin Flip example](https://github.com/pyth-network/pyth-examples/tree/main/entropy/coin_flip) in the Pyth examples repository.

‎apps/developer-hub/content/docs/entropy/current-fees.mdx

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
---
2+
title: Current Fees
3+
description: Current fees for using Pyth Entropy
4+
---
5+
6+
# Current Fees
7+
8+
The following tables shows the total fees payable when using the **default provider**.
9+
Note that the fees shown below will vary over time with prevailing gas prices on each chain.
10+
11+
## Mainnet
12+
13+
> ⚠️ **Warning**
14+
> The fees for mainnet are dynamically set. Always use the on-chain method `entropy.getFeeV2()` to get the current fee.
15+
16+
| Network | Fee (Native Token) |
17+
| --------- | ------------------ |
18+
| Ethereum | Dynamic |
19+
| Arbitrum | Dynamic |
20+
| Avalanche | Dynamic |
21+
| Base | Dynamic |
22+
| BNB Chain | Dynamic |
23+
| Optimism | Dynamic |
24+
| Polygon | Dynamic |
25+
26+
## Testnet
27+
28+
> ℹ️ **Note**
29+
> The fees for testnets kept deliberately low and different from the mainnet fees.
30+
31+
| Network | Fee (Native Token) |
32+
| ---------------- | ------------------ |
33+
| Ethereum Sepolia | 0.0001 ETH |
34+
| Arbitrum Sepolia | 0.0001 ETH |
35+
| Avalanche Fuji | 0.01 AVAX |
36+
| Base Sepolia | 0.0001 ETH |
37+
| BNB Testnet | 0.001 BNB |
38+
| Optimism Sepolia | 0.0001 ETH |
39+
| Polygon Amoy | 0.01 MATIC |

‎apps/developer-hub/content/docs/entropy/debug-callback-failures.mdx

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
---
2+
title: Debug Callback Failures
3+
description: How to identify and resolve issues with Entropy callbacks
4+
---
5+
6+
# Debug Callback Failures
7+
8+
> 🔍 **Quick Debug Tool**
9+
> Use the [Entropy Explorer](https://entropy-debugger.pyth.network/) to quickly diagnose and resolve callback issues.
10+
11+
This guide explains how to identify and resolve issues with the Entropy callback.
12+
The intended audience for this guide is developers who have made an Entropy random number request, but their application hasn't received a callback.
13+
14+
## Dependencies
15+
16+
This guide uses [Foundry](https://book.getfoundry.sh/getting-started/installation) to submit transactions to the blockchain.
17+
Please install Foundry before continuing.
18+
19+
## Run the Callback
20+
21+
Developers can run the Entropy callback themselves to see the reason for the failure.
22+
To run the callback, invoke the `revealWithCallback` function on the Entropy contract on your blockchain.
23+
The function has the following signature:
24+
25+
```solidity
26+
function revealWithCallback(
27+
address provider,
28+
uint64 sequenceNumber,
29+
bytes32 userRandomNumber,
30+
bytes32 providerRevelation
31+
)
32+
```
33+
34+
This call requires the chain ID, contract address, and four arguments.
35+
The chain ID and contract address can be retrieved from [Contract Addresses](contract-addresses).
36+
Export these values as environment variables for later use:
37+
38+
```bash
39+
export CHAIN_ID=blast
40+
export ENTROPY_ADDRESS=0x5744Cbf430D99456a0A8771208b674F27f8EF0Fb
41+
```
42+
43+
Three of the arguments can be retrieved from the request transaction's event logs.
44+
Look at the event logs of the request transaction in a block explorer.
45+
You should see a `RequestedWithCallback` event emitted from the Entropy contract.
46+
47+
Copy the following values from the event into environment variables:
48+
49+
```bash
50+
export PROVIDER=0x52DeaA1c84233F7bb8C8A45baeDE41091c616506
51+
export SEQUENCE_NUMBER=12345
52+
export USER_RANDOM_NUMBER=0x1234...
53+
```
54+
55+
The fourth argument (provider revelation) must be retrieved from the provider's API.
56+
This value becomes available after the reveal delay has passed.
57+
58+
## Common Issues
59+
60+
### Gas Limit Exceeded
61+
62+
If your callback function uses too much gas, the transaction will fail. Check the gas limit for your chain on the [contract addresses](contract-addresses) page and ensure your callback function uses less gas.
63+
64+
### Callback Function Errors
65+
66+
Your callback function might contain logic that throws an error. Review your callback implementation for:
67+
68+
- Division by zero
69+
- Array out of bounds access
70+
- Failed require statements
71+
- Insufficient contract balance for operations
72+
73+
### Transaction Timing
74+
75+
Make sure you're attempting the callback after the reveal delay has passed. The reveal delay varies by network and helps prevent MEV attacks.

‎apps/developer-hub/content/docs/entropy/error-codes.mdx

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
title: Error Codes
3+
description: Error codes and their meanings for Pyth Entropy
4+
---
5+
6+
# Error Codes
7+
8+
The following table contains the errors used in the Pyth Network's Entropy [EVM contracts](https://github.com/pyth-network/pyth-crosschain/blob/d290f4ec47a73636cf77711f5f68c3455bb8a8ca/target_chains/ethereum/contracts/contracts/entropy/Entropy.sol).
9+
This information is derived from [EntropyErrors.sol](https://github.com/pyth-network/pyth-crosschain/blob/d290f4ec47a73636cf77711f5f68c3455bb8a8ca/target_chains/ethereum/entropy_sdk/solidity/EntropyErrors.sol)
10+
in the Pyth EntropySDK and can be used to decode error codes programmatically.
11+
12+
| Error Codes | Error | Error Description |
13+
| ----------- | --------------------------- | --------------------------------------------------------- |
14+
| 0xd82dd966 | AssertionFailure() | Contract invariant failed. |
15+
| 0xda041bdf | ProviderAlreadyRegistered() | Provider already registered. |
16+
| 0xdf51c431 | NoSuchProvider() | Requested Provider does not exist. |
17+
| 0xc4237352 | NoSuchRequest() | Request does not exist or the request has been fulfilled. |
18+
| 0x3e515085 | OutOfRandomness() | Provider is out of committed random numbers. |
19+
| 0x025dbdd4 | InsufficientFee() | Request fee is insufficient. |
20+
| 0xb8be1a8d | IncorrectRevelation() | Revelation does not match commitment. |
21+
| 0x2763cc69 | RequestAlreadyRevealed() | Request has already been revealed. |
22+
| 0xdb8b95b8 | RevealTooEarly() | Reveal delay has not passed. |
23+
| 0x8f4eb604 | RandomnessNotRevealed() | Random number has not been revealed. |

‎apps/developer-hub/content/docs/entropy/examples.mdx

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
title: Example Applications
3+
description: Example applications using Pyth Entropy
4+
---
5+
6+
# Example Applications
7+
8+
The [Coin Flip](https://github.com/pyth-network/pyth-examples/tree/main/entropy/coin_flip) example demonstrates how to build a smart contract that
9+
interacts with Pyth Entropy as well as a typescript client for that application.
10+
11+
## Other Examples
12+
13+
You can find more examples and tutorials in the [Pyth Examples repository](https://github.com/pyth-network/pyth-examples/tree/main/entropy).

‎apps/developer-hub/content/docs/entropy/fees.mdx

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
title: Fees
3+
description: Understanding Pyth Entropy fee structure
4+
---
5+
6+
# Fees
7+
8+
The Entropy protocol has been designed to charge fees on a per-request basis. The total fee is
9+
the sum of the provider fee, which is determined by the individual provider on a per-blockchain
10+
basis, and the protocol fee, which is subject to Pyth governance decisions also on a per-chain
11+
basis. These are accessible via the smart contract functions.
12+
13+
Providers can withdraw their fees from the contract whenever they want. The allocation of the fees collected by the Entropy protocol
14+
is governed by the collective decisions of its governance body. All fees are denominated in the native token
15+
of the respective blockchain, ensuring a seamless and integrated operation.
16+
17+
Note that protocols integrating with Entropy can pass these fees along to their users. Whenever a user
18+
submits a transaction that requests a random number, the user can directly pay the entropy fees required
19+
with the native blockchain token. There are no fees for revealing the random numbers.
20+
21+
You can check the [current fees](current-fees) page to see the latest fees for each blockchain.

0 commit comments

Comments
 (0)