chore(dev-hub) Move Entropy pages

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

@@ -0,0 +1,57 @@
+---
+title: Best Practices
+description: Best practices for using Pyth Entropy in your applications
+---
+
+# Best Practices
+
+## Limit gas usage on the callback
+
+Keeping the callback function simple is crucial because the entropy providers limit gas usage.
+This ensures gas usage is predictable and consistent, avoiding potential issues with the callback.
+
+For example, if you want to use entropy to generate a random number for each player in a round of game,
+you need to make sure that the callback function works for the maximum number of players that can be in each round.
+Otherwise, the callbacks will work for some rounds with fewer players, but will fail for rounds with more players.
+
+Multiple solutions are possible to address this problem. You can store the random number received from the callback and
+either ask users to submit more transactions after the callback to continue the flow or run a background crank service
+to submit the necessary transactions.
+
+The gas limit for each chain is listed on the [contract addresses](contract-addresses) page.
+
+## Handling callback failures
+
+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:
+
+1. The callback function is using more gas than the allowed limit
+2. The callback function contains logic that throws an error
+
+If you're not receiving a callback, you can manually invoke it to identify the specific issue. This allows you to:
+
+- See if the transaction fails and why
+- Check the gas usage against the chain's callback gas limit
+- Debug your callback implementation
+
+For detailed instructions on how to manually invoke and debug callbacks, refer to the [Debug Callback Failures](debug-callback-failures) guide.
+
+## Generating random values within a specific range
+
+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).
+Here is a simple example of how to map a random number provided by Entropy into a range between `minRange` and `maxRange` (inclusive).
+
+```solidity
+// Maps a random number into a range between minRange and maxRange (inclusive)
+function mapRandomNumber(
+    bytes32 randomNumber,
+    int256 minRange,
+    int256 maxRange
+) internal pure returns (int256) {
+    require(minRange <= maxRange, "Invalid range");
+
+    uint256 range = uint256(maxRange - minRange + 1);
+    uint256 randomUint = uint256(randomNumber);
+
+    return minRange + int256(randomUint % range);
+}
+```

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

@@ -0,0 +1,47 @@
+---
+title: Contract Addresses
+description: Entropy contract addresses on different networks
+---
+
+# Entropy Contract Addresses on EVM
+
+## Mainnets
+
+The Entropy contract is deployed on the following mainnet chains:
+
+| Network   | Contract Address                             | Gas Limit | Provider                                     |
+| --------- | -------------------------------------------- | --------- | -------------------------------------------- |
+| Ethereum  | `0x98046Bd286715D3B0BC227Dd7a956b83D8978603` | 100,000   | `0x52DeaA1c84233F7bb8C8A45baeDE41091c616506` |
+| Arbitrum  | `0x23f0e8FAeE7bbb405E7A7C3d60138FCfd43d7509` | 100,000   | `0x52DeaA1c84233F7bb8C8A45baeDE41091c616506` |
+| Avalanche | `0x36825bf3Fbdf5a29E2d5148bfe7Dcf7B5639e320` | 100,000   | `0x52DeaA1c84233F7bb8C8A45baeDE41091c616506` |
+| Base      | `0x98046Bd286715D3B0BC227Dd7a956b83D8978603` | 100,000   | `0x52DeaA1c84233F7bb8C8A45baeDE41091c616506` |
+| BNB Chain | `0x98046Bd286715D3B0BC227Dd7a956b83D8978603` | 100,000   | `0x52DeaA1c84233F7bb8C8A45baeDE41091c616506` |
+| Optimism  | `0x98046Bd286715D3B0BC227Dd7a956b83D8978603` | 100,000   | `0x52DeaA1c84233F7bb8C8A45baeDE41091c616506` |
+| Polygon   | `0x98046Bd286715D3B0BC227Dd7a956b83D8978603` | 100,000   | `0x52DeaA1c84233F7bb8C8A45baeDE41091c616506` |
+
+**The default provider for above mainnet chains is `0x52DeaA1c84233F7bb8C8A45baeDE41091c616506`.**
+
+The default provider on mainnet has a reveal delay to avoid changes on the outcome of the Entropy request because of block reorgs.
+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.
+
+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.
+
+## Testnets
+
+The Entropy contract is deployed on the following testnet chains:
+
+| Network          | Contract Address                             | Gas Limit | Provider                                     |
+| ---------------- | -------------------------------------------- | --------- | -------------------------------------------- |
+| Ethereum Sepolia | `0x41c9e39574F40Ad34c79f1C99B66A45eFB830d4c` | 100,000   | `0x6CC14824Ea2918f5De5C2f75A9Da968ad4BD6344` |
+| Arbitrum Sepolia | `0x36825bf3Fbdf5a29E2d5148bfe7Dcf7B5639e320` | 100,000   | `0x6CC14824Ea2918f5De5C2f75A9Da968ad4BD6344` |
+| Avalanche Fuji   | `0x36825bf3Fbdf5a29E2d5148bfe7Dcf7B5639e320` | 100,000   | `0x6CC14824Ea2918f5De5C2f75A9Da968ad4BD6344` |
+| Base Sepolia     | `0x41c9e39574F40Ad34c79f1C99B66A45eFB830d4c` | 100,000   | `0x6CC14824Ea2918f5De5C2f75A9Da968ad4BD6344` |
+| BNB Testnet      | `0x41c9e39574F40Ad34c79f1C99B66A45eFB830d4c` | 100,000   | `0x6CC14824Ea2918f5De5C2f75A9Da968ad4BD6344` |
+| Optimism Sepolia | `0x41c9e39574F40Ad34c79f1C99B66A45eFB830d4c` | 100,000   | `0x6CC14824Ea2918f5De5C2f75A9Da968ad4BD6344` |
+| Polygon Amoy     | `0x41c9e39574F40Ad34c79f1C99B66A45eFB830d4c` | 100,000   | `0x6CC14824Ea2918f5De5C2f75A9Da968ad4BD6344` |
+
+**The default provider for above testnet chains is `0x6CC14824Ea2918f5De5C2f75A9Da968ad4BD6344`.**
+
+The default provider on testnet has reveal delays identical to the corresponding mainnet chains to ensure consistent environment.
+
+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

@@ -0,0 +1,108 @@
+---
+title: Create your first Entropy app on EVM
+description: Build a coin flip application using Pyth Entropy
+---
+
+# Create your first Entropy app on EVM
+
+In this tutorial we will implement and deploy a coin flip contract which will use entropy to generate a random output.
+
+## Preliminaries
+
+Before we start, please make sure you have the following tools installed:
+
+- [Foundry](https://book.getfoundry.sh/getting-started/installation)
+- [Node.js](https://nodejs.org/en/download) (version >= v18.0.0)
+
+## Getting Started
+
+Create a directory named `coin-flip` and initialize a new Foundry project:
+
+```bash
+mkdir coin-flip
+cd coin-flip
+forge init contracts
+```
+
+Install the Pyth Entropy SDK:
+
+```bash
+cd contracts
+npm init -y
+npm install @pythnetwork/entropy-sdk-solidity
+```
+
+Add a `remappings.txt` file to the `contracts` directory:
+
+```text
+@pythnetwork/entropy-sdk-solidity/=node_modules/@pythnetwork/entropy-sdk-solidity
+```
+
+## Smart Contract Implementation
+
+Replace the content of `contracts/src/Counter.sol` with the following coin flip contract:
+
+```solidity
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+import "@pythnetwork/entropy-sdk-solidity/IEntropy.sol";
+import "@pythnetwork/entropy-sdk-solidity/IEntropyConsumer.sol";
+
+contract CoinFlip is IEntropyConsumer {
+    IEntropy entropy;
+
+    struct FlipRequest {
+        address player;
+        bool isHeads;
+    }
+
+    mapping(uint64 => FlipRequest) public requests;
+    mapping(address => uint256) public results; // 0 = not played, 1 = won, 2 = lost
+
+    constructor(address entropyAddress) {
+        entropy = IEntropy(entropyAddress);
+    }
+
+    function flipCoin(bool isHeads) external payable {
+        uint256 fee = entropy.getFee(entropy.getDefaultProvider());
+        require(msg.value >= fee, "Insufficient fee");
+
+        bytes32 userRandomNumber = keccak256(abi.encode(block.timestamp, msg.sender));
+        uint64 sequenceNumber = entropy.requestWithCallback{value: fee}(
+            entropy.getDefaultProvider(),
+            userRandomNumber
+        );
+
+        requests[sequenceNumber] = FlipRequest(msg.sender, isHeads);
+    }
+
+    function entropyCallback(
+        uint64 sequenceNumber,
+        address,
+        bytes32 randomNumber
+    ) internal override {
+        FlipRequest memory request = requests[sequenceNumber];
+        bool coinIsHeads = uint256(randomNumber) % 2 == 0;
+
+        if (coinIsHeads == request.isHeads) {
+            results[request.player] = 1; // won
+        } else {
+            results[request.player] = 2; // lost
+        }
+    }
+}
+```
+
+## Deployment
+
+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.
+
+## Next Steps
+
+- Add more complex game logic
+- Implement proper error handling
+- Add events for better tracking
+- Consider gas optimization techniques
+
+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

@@ -0,0 +1,39 @@
+---
+title: Current Fees
+description: Current fees for using Pyth Entropy
+---
+
+# Current Fees
+
+The following tables shows the total fees payable when using the **default provider**.
+Note that the fees shown below will vary over time with prevailing gas prices on each chain.
+
+## Mainnet
+
+> ⚠️ **Warning**
+> The fees for mainnet are dynamically set. Always use the on-chain method `entropy.getFeeV2()` to get the current fee.
+
+| Network   | Fee (Native Token) |
+| --------- | ------------------ |
+| Ethereum  | Dynamic            |
+| Arbitrum  | Dynamic            |
+| Avalanche | Dynamic            |
+| Base      | Dynamic            |
+| BNB Chain | Dynamic            |
+| Optimism  | Dynamic            |
+| Polygon   | Dynamic            |
+
+## Testnet
+
+> ℹ️ **Note**
+> The fees for testnets kept deliberately low and different from the mainnet fees.
+
+| Network          | Fee (Native Token) |
+| ---------------- | ------------------ |
+| Ethereum Sepolia | 0.0001 ETH         |
+| Arbitrum Sepolia | 0.0001 ETH         |
+| Avalanche Fuji   | 0.01 AVAX          |
+| Base Sepolia     | 0.0001 ETH         |
+| BNB Testnet      | 0.001 BNB          |
+| Optimism Sepolia | 0.0001 ETH         |
+| Polygon Amoy     | 0.01 MATIC         |

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

@@ -0,0 +1,75 @@
+---
+title: Debug Callback Failures
+description: How to identify and resolve issues with Entropy callbacks
+---
+
+# Debug Callback Failures
+
+> 🔍 **Quick Debug Tool**
+> Use the [Entropy Explorer](https://entropy-debugger.pyth.network/) to quickly diagnose and resolve callback issues.
+
+This guide explains how to identify and resolve issues with the Entropy callback.
+The intended audience for this guide is developers who have made an Entropy random number request, but their application hasn't received a callback.
+
+## Dependencies
+
+This guide uses [Foundry](https://book.getfoundry.sh/getting-started/installation) to submit transactions to the blockchain.
+Please install Foundry before continuing.
+
+## Run the Callback
+
+Developers can run the Entropy callback themselves to see the reason for the failure.
+To run the callback, invoke the `revealWithCallback` function on the Entropy contract on your blockchain.
+The function has the following signature:
+
+```solidity
+function revealWithCallback(
+    address provider,
+    uint64 sequenceNumber,
+    bytes32 userRandomNumber,
+    bytes32 providerRevelation
+)
+```
+
+This call requires the chain ID, contract address, and four arguments.
+The chain ID and contract address can be retrieved from [Contract Addresses](contract-addresses).
+Export these values as environment variables for later use:
+
+```bash
+export CHAIN_ID=blast
+export ENTROPY_ADDRESS=0x5744Cbf430D99456a0A8771208b674F27f8EF0Fb
+```
+
+Three of the arguments can be retrieved from the request transaction's event logs.
+Look at the event logs of the request transaction in a block explorer.
+You should see a `RequestedWithCallback` event emitted from the Entropy contract.
+
+Copy the following values from the event into environment variables:
+
+```bash
+export PROVIDER=0x52DeaA1c84233F7bb8C8A45baeDE41091c616506
+export SEQUENCE_NUMBER=12345
+export USER_RANDOM_NUMBER=0x1234...
+```
+
+The fourth argument (provider revelation) must be retrieved from the provider's API.
+This value becomes available after the reveal delay has passed.
+
+## Common Issues
+
+### Gas Limit Exceeded
+
+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.
+
+### Callback Function Errors
+
+Your callback function might contain logic that throws an error. Review your callback implementation for:
+
+- Division by zero
+- Array out of bounds access
+- Failed require statements
+- Insufficient contract balance for operations
+
+### Transaction Timing
+
+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

@@ -0,0 +1,23 @@
+---
+title: Error Codes
+description: Error codes and their meanings for Pyth Entropy
+---
+
+# Error Codes
+
+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).
+This information is derived from [EntropyErrors.sol](https://github.com/pyth-network/pyth-crosschain/blob/d290f4ec47a73636cf77711f5f68c3455bb8a8ca/target_chains/ethereum/entropy_sdk/solidity/EntropyErrors.sol)
+in the Pyth EntropySDK and can be used to decode error codes programmatically.
+
+| Error Codes | Error                       | Error Description                                         |
+| ----------- | --------------------------- | --------------------------------------------------------- |
+| 0xd82dd966  | AssertionFailure()          | Contract invariant failed.                                |
+| 0xda041bdf  | ProviderAlreadyRegistered() | Provider already registered.                              |
+| 0xdf51c431  | NoSuchProvider()            | Requested Provider does not exist.                        |
+| 0xc4237352  | NoSuchRequest()             | Request does not exist or the request has been fulfilled. |
+| 0x3e515085  | OutOfRandomness()           | Provider is out of committed random numbers.              |
+| 0x025dbdd4  | InsufficientFee()           | Request fee is insufficient.                              |
+| 0xb8be1a8d  | IncorrectRevelation()       | Revelation does not match commitment.                     |
+| 0x2763cc69  | RequestAlreadyRevealed()    | Request has already been revealed.                        |
+| 0xdb8b95b8  | RevealTooEarly()            | Reveal delay has not passed.                              |
+| 0x8f4eb604  | RandomnessNotRevealed()     | Random number has not been revealed.                      |

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

@@ -0,0 +1,13 @@
+---
+title: Example Applications
+description: Example applications using Pyth Entropy
+---
+
+# Example Applications
+
+The [Coin Flip](https://github.com/pyth-network/pyth-examples/tree/main/entropy/coin_flip) example demonstrates how to build a smart contract that
+interacts with Pyth Entropy as well as a typescript client for that application.
+
+## Other Examples
+
+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

@@ -0,0 +1,21 @@
+---
+title: Fees
+description: Understanding Pyth Entropy fee structure
+---
+
+# Fees
+
+The Entropy protocol has been designed to charge fees on a per-request basis. The total fee is
+the sum of the provider fee, which is determined by the individual provider on a per-blockchain
+basis, and the protocol fee, which is subject to Pyth governance decisions also on a per-chain
+basis. These are accessible via the smart contract functions.
+
+Providers can withdraw their fees from the contract whenever they want. The allocation of the fees collected by the Entropy protocol
+is governed by the collective decisions of its governance body. All fees are denominated in the native token
+of the respective blockchain, ensuring a seamless and integrated operation.
+
+Note that protocols integrating with Entropy can pass these fees along to their users. Whenever a user
+submits a transaction that requests a random number, the user can directly pay the entropy fees required
+with the native blockchain token. There are no fees for revealing the random numbers.
+
+You can check the [current fees](current-fees) page to see the latest fees for each blockchain.