chore(dev-hub) Entropy remaining page Improvements

Author: aditya520

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

@@ -3,38 +3,6 @@ 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).
@@ -55,3 +23,50 @@ function mapRandomNumber(
     return minRange + int256(randomUint % range);
 }
 ```
+
+Notice that using the modulo operator can distort the distribution of random numbers if it's not a power of 2. This is
+negligible for small and medium ranges, but it can be noticeable for large ranges.
+For example, if you want to generate a random number between 1 and 52, the probability of having value 5 is approximately
+`10^-77` higher than the probability of having value 50 which is infinitesimal.
+
+## Generating multiple random values in a single transaction
+
+If you need to generate multiple random values in a single transaction, you can hash the random input provided by Entropy with a unique identifier for each random number.
+
+In the following example, `mapRandomNumber` is used to generate 6 random attributes for a character.
+
+```solidity
+function generateAttributes(bytes32 randomNumber) internal {
+  int256 strength = mapRandomNumber(
+    keccak256(abi.encodePacked(randomNumber, "strength")),
+    15,
+    20
+  );
+  int256 stamina = mapRandomNumber(
+    keccak256(abi.encodePacked(randomNumber, "stamina")),
+    10,
+    15
+  );
+  int256 agility = mapRandomNumber(
+    keccak256(abi.encodePacked(randomNumber, "agility")),
+    5,
+    15
+  );
+  int256 stealth = mapRandomNumber(
+    keccak256(abi.encodePacked(randomNumber, "stealth")),
+    0,
+    5
+  );
+  int256 positionX = mapRandomNumber(
+    keccak256(abi.encodePacked(randomNumber, "positionX")),
+    -100,
+    100
+  );
+  int256 positionY = mapRandomNumber(
+    keccak256(abi.encodePacked(randomNumber, "positionY")),
+    -100,
+    100
+  );
+}
+
+```

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

@@ -7,6 +7,12 @@ import { EntropyTable } from "../../../src/components/EntropyTable";
 
 ## Mainnets
 
+> ⚠️ **Warning**
+> The fees for mainnet are dynamically set. Always use the on-chain method `entropy.getFeeV2()` to get the current fee.
+
+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.
+
 The Entropy contract is deployed on the following mainnet chains:
 
 <EntropyTable isMainnet={true} />
@@ -16,11 +22,14 @@ The Entropy contract is deployed on the following mainnet chains:
 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 or as set by the user in the request. 
+The default provider fulfills the request by sending a transaction with a gas limit as mentioned in above table or as set by the user in the request.
 Entropy callbacks the consumer as part of this transaction.
 
 ## Testnets
 
+> ℹ️ **Note**
+> The fees for testnets kept deliberately low and different from the mainnet fees.
+
 The Entropy contract is deployed on the following testnet chains:
 
 <EntropyTable isMainnet={false} />

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

@@ -1,10 +1,8 @@
 ---
 title: Error Codes
-description: Error codes and their meanings for Pyth Entropy
+description: On chain error codes from the Pyth Entropy EVM contracts
 ---
 
-# 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.

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

@@ -3,8 +3,6 @@ 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
@@ -18,4 +16,4 @@ Note that protocols integrating with Entropy can pass these fees along to their
 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.
+You can check the current fees in the [contract addresses](contract-addresses) page for each blockchain.

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

@@ -51,11 +51,12 @@ import { IEntropyV2 } from "@pythnetwork/entropy-sdk-solidity/IEntropyV2.sol";
 
 // @param entropyAddress The address of the entropy contract.
 contract YourContract is IEntropyConsumer {
-    IEntropyV2 public entropy;
+IEntropyV2 public entropy;
 
     constructor(address entropyAddress) {
         entropy = IEntropyV2(entropyAddress);
     }
+
 }
 `} />
 
@@ -81,6 +82,7 @@ code={`function requestRandomNumber() external payable {
     uint256 fee = entropy.getFeeV2();
 
     uint64 sequenceNumber = entropy.requestV2{ value: fee }();
+
 }
 `} />
 
@@ -102,7 +104,7 @@ import { IEntropyConsumer } from "@pythnetwork/entropy-sdk-solidity/IEntropyCons
 import { IEntropyV2 } from "@pythnetwork/entropy-sdk-solidity/IEntropyV2.sol";
 
 contract YourContract is IEntropyConsumer {
-    IEntropyV2 entropy;
+IEntropyV2 entropy;
 
     // @param entropyAddress The address of the entropy contract.
     constructor(address entropyAddress) {
@@ -140,6 +142,7 @@ contract YourContract is IEntropyConsumer {
     function getEntropy() internal view override returns (address) {
         return address(entropy);
     }
+
 }
 `} />
 

apps/developer-hub/content/docs/entropy/generate-random-numbers-evm.mdx

@@ -13,13 +13,15 @@
     "debug-callback-failures",
     "---Reference Material---",
     "contract-addresses",
-    "current-fees",
     "best-practices",
-    "fees",
-    "protocol-design",
-    "error-codes",
-    "examples",
     "request-callback-variants",
+    "error-codes",
+    "[Example Applications](https://github.com/pyth-network/pyth-examples/tree/main/entropy)",
+    "[Entropy Explorer](https://entropy-explorer.pyth.network/)",
+    "[Fortuna API Reference](https://fortuna.dourolabs.app/docs/)",
+    "---Understanding Entropy---",
+    "protocol-design",
+    "fees",
     "create-your-first-entropy-app"
   ]
 }

apps/developer-hub/content/docs/entropy/meta.json

@@ -3,40 +3,50 @@ title: Protocol Design
 description: Understanding how Pyth Entropy generates secure random numbers
 ---
 
-# Protocol Design
-
 The Entropy protocol implements a secure 2-party random number generation procedure. The protocol
 is an extension of a simple commit/reveal protocol. The original version has the following steps:
 
-1. Two parties A and B each randomly sample secret contributions to the random number, $x_A$ and $x_B$.
-2. A commits to their number by sharing $h_A = \mathrm{hash}(x_A)$
+1. Two parties A and B each randomly sample secret contributions to the random number, $$(x_A)$$ and $$(x_B)$$.
+2. A commits to their number by sharing $$(h_A) = hash(x_A).$$
 3. B reveals $x_B$
 4. A reveals $x_A$
-5. B verifies that $\mathrm{hash}(x_{A}) == h_A$
-6. The random number $r = \mathrm{hash}(x_A, x_B)$
+5. B verifies that $$hash(x_{A}) == h_A$$
+6. The random number $$r = hash(x_A, x_B)$$
 
 This protocol has the property that the result is random as long as either A or B are honest.
-Honesty means that (1) they draw their value at random, and (2) for A, they keep $x_A$ a secret until
+Honesty means that (1) they draw their value at random, and (2) for A, they keep $$(x_A)$$ a secret until
 step 4. Thus, neither party needs to trust the other -- as long as they are themselves honest, they can
-ensure that the result $r$ is random.
+ensure that the result $$(r)$$ is random.
 
 Entropy implements a version of this protocol that is optimized for on-chain usage. The
 key difference is that one of the participants (the provider) commits to a sequence of random numbers
 up-front using a hash chain. Users of the protocol then simply grab the next random number in the sequence.
 
-**Setup**: The provider P computes a sequence of $N$ random numbers, $x_i$ for $0 \leq i \leq N-1$:
+**Setup**: The provider $$P$$ computes a sequence of $$N$$ random numbers, $$x_i$$ for $$0 \leq i \leq N-1$$:
 
-- $x_{N-1} = \mathrm{random}()$
-- $x_i = \mathrm{hash}(x_{i + 1})$
+- $$x_{N-1} = random()$$
+- $$x_i = hash(x_{i + 1})$$
 
-The provider commits to $x_0$ by posting it to the Entropy contract.
-Each random number in the sequence can then be verified against the previous one in the sequence by hashing it, i.e., $\mathrm{hash}(x_i) = x_{i - 1}$
+The provider commits to $$x_0$$ by posting it to the Entropy contract.
+Each random number in the sequence can then be verified against the previous one in the sequence by hashing it, i.e., $$hash(x_i) = x_{i - 1}$$
 
 **Request**: To produce a random number, the following steps occur.
 
-1. The user randomly samples a secret value $x_u$ and sends a request to the Entropy contract containing $\mathrm{hash}(x_u)$.
-2. The Entropy contract stores the request and assigns it a sequence number corresponding to the provider's next random number $x_i$.
-3. The provider fulfills the request by revealing $x_i$ to the Entropy contract.
-4. The Entropy contract verifies that $\mathrm{hash}(x_i) = x_{i-1}$ (the previous commitment), then computes the random number $r = \mathrm{hash}(x_u, x_i)$ and delivers it to the user's callback function.
+1. The user randomly samples their contribution $$(x_U)$$ and submits it to the contract.
+   (Users may also run this step using an on-chain PRNG if they trust the validator to not collude with the provider.)
+2. The contract remembers $$(x_U)$$ and assigns it an incrementing sequence number $$(i)$$, representing which
+   of the provider's random numbers the user will receive.
+3. After sufficient block confirmations, the provider submits a transaction to the contract revealing their contribution $$(x_i)$$ to the contract.
+4. The contract verifies $$hash(x_i) == x_{i-1}$$ to prove that $$(x_i)$$ is the $$(i)$$'th random number.
+   The contract stores $$(x_i)$$ as the $$(i)$$'th random number to reuse for future verifications.
+5. If the condition above is satisfied, the random number $$(r) = hash(x_i, x_U)$$.
+6. The contract submits a callback to the calling contract with the random number $$(r)$$.
+
+This flow is secure as long as several trust assumptions hold:
+
+- Providers are trusted to reveal their random number $$(x_i)$$ regardless of what the final result $$(r)$$ is. Providers can compute $$(r)$$ off-chain before they reveal $$(x_i)$$, which permits a censorship attack.
+- Providers are trusted not to front-run user transactions (via the mempool or colluding with the validator). Providers who observe user transactions can manipulate the result by inserting additional reuests or rotating their commitment.
+- Providers are trusted not to keep their hash chain a secret. Anyone with the hash chain can predict the result of a randomness request before it is requested,
+  and therefore manipulate the result. This applies both to users of the protocol as well as blockchain validators who can use this information to manipulate the on-chain PRNG or reorder user transactions.
 
-This approach ensures that the resulting random number is unpredictable as long as either the user or the provider is honest, while being efficiently verifiable on-chain.
+The code of default deployed provider can be found [here](https://github.com/pyth-network/pyth-crosschain/tree/7bccde484f01c19844b7105d63df207a24018957/apps/fortuna).

apps/developer-hub/content/docs/entropy/protocol-design.mdx

@@ -3,11 +3,9 @@ title: Request Callback Variants
 description: Different ways to request random numbers with Pyth Entropy
 ---
 
-# Request Callback Variants
-
 The [`IEntropyV2`](https://github.com/pyth-network/pyth-crosschain/blob/main/target_chains/ethereum/entropy_sdk/solidity/IEntropyV2.sol) interface provides multiple variants of the `requestV2` function:
 
-## 1. Basic Request
+## 1. Basic request
 
 ```solidity
 function requestV2() external payable returns (uint64 assignedSequenceNumber);
@@ -31,7 +29,7 @@ function requestBasicRandomNumber() external payable {
 }
 ```
 
-## 2. Request with Gas Limit
+## 2. Request with custom gas limit
 
 ```solidity
 function requestV2(
@@ -59,7 +57,7 @@ function requestWithCustomGas() external payable {
 }
 ```
 
-## 3. Request with Provider
+## 3. Request with custom provider
 
 ```solidity
 function requestV2(
@@ -69,7 +67,7 @@ function requestV2(
 
 This variant allows you to specify a custom entropy provider instead of using the default one.
 
-## 4. Full Custom Request
+## 4. Full custom request
 
 ```solidity
 function requestV2(
@@ -79,4 +77,4 @@ function requestV2(
 ) external payable returns (uint64 assignedSequenceNumber);
 ```
 
-This is the most flexible variant that allows you to specify all parameters: custom provider, gas limit, and user random number.
+This is the most flexible variant that allows you to specify all parameters: custom provider, custom gas limit, and user random number.

apps/developer-hub/content/docs/entropy/request-callback-variants.mdx

@@ -42,6 +42,7 @@ code={`function requestRandomNumberWithCustomGas(
     uint64 sequenceNumber = entropy.requestV2{ value: fee }(customGasLimit);
 
     // Store the sequence number for tracking if needed
+
 }
 `} />
 
@@ -67,8 +68,8 @@ import { IEntropyConsumer } from "@pythnetwork/entropy-sdk-solidity/IEntropyCons
 import { IEntropyV2 } from "@pythnetwork/entropy-sdk-solidity/IEntropyV2.sol";
 
 contract CustomGasLimitExample is IEntropyConsumer {
-    IEntropyV2 public entropy;
-    mapping(uint64 => bool) public processedRequests;
+IEntropyV2 public entropy;
+mapping(uint64 => bool) public processedRequests;
 
     constructor(address entropyAddress) {
       entropy = IEntropyV2(entropyAddress);
@@ -119,6 +120,7 @@ contract CustomGasLimitExample is IEntropyConsumer {
     function getEntropy() internal view override returns (address) {
       return address(entropy);
     }
+
 }
 `} />