Add guide for debugging entropy callbacks (#365)

* Add docs for debugging entropy callbacks

* fixes

---------

Co-authored-by: Aditya Arora <arora.aditya520@gmail.com>

Author: jayantk

images/entropy_event_log.png

@@ -24,6 +24,7 @@
   },
 
   "generate-random-numbers": "Generate Random Numbers",
+  "debug-callback-failures": "Debug Callback Failures",
 
   "-- Reference Material": {
     "title": "Reference Material",

pages/entropy/_meta.json

@@ -0,0 +1,91 @@
+# Debug Callback Failures
+
+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](/entropy/contract-addresses).
+Export these values as environment variables for later use:
+
+```bash copy
+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, similar to the one below:
+
+![Example Entropy event logs](../../images/entropy_event_log.png)
+
+Copy the following values from the event into environment variables:
+
+```bash
+export PROVIDER=0x52DeaA1c84233F7bb8C8A45baeDE41091c616506
+export SEQUENCE_NUMBER=264793
+# First row of the "Data" field with a 0x prefix
+export USER_RANDOM_NUMBER=0xb1db70cfe95d9e823ac591362921c20eb45f136dbf417362f0a045dc7100519e
+```
+
+Next, collect the provider's revelation.
+Every provider exposes a URL that allows users to get the provider's revelation for unfulfilled requests.
+The URLs for the default providers are as follows:
+
+| Network type | Provider URL                             |
+| ------------ | ---------------------------------------- |
+| testnet      | `https://fortuna-staging.dourolabs.app/` |
+| mainnet      | `https://fortuna.dourolabs.app`          |
+
+Retrieve the `/v1/chains/$CHAIN_ID/revelations/$SEQUENCE_NUMBER` endpoint from this server:
+
+```bash copy
+curl https://fortuna.dourolabs.app/v1/chains/$CHAIN_ID/revelations/$SEQUENCE_NUMBER
+```
+
+This endpoint will return the provider's revelation as a hexadecimal value, such as:
+
+```json
+{
+  "value": {
+    "encoding": "hex",
+    "data": "5d4bfa3abeaf15fe8b7771c74c0e3e210096015632831460870bc5374e05d4d8"
+  }
+}
+```
+
+Export this value as an environment variable (prefixed with 0x):
+
+```bash copy
+export PROVIDER_REVELATION=0x5d4bfa3abeaf15fe8b7771c74c0e3e210096015632831460870bc5374e05d4d8
+```
+
+Finally, submit the transaction to invoke `revealWithCallback`:
+
+```bash copy
+cast send $ENTROPY_ADDRESS 'revealWithCallback(address, uint64, bytes32, bytes32)' $ENTROPY_ADDRESS $SEQUENCE_NUMBER $USER_RANDOM_NUMBER $PROVIDER_REVELATION
+```
+
+You may also need to provide the `-r` with an RPC for your chain, plus an additional argument (such as `--private-key`) to specify the wallet to use to sign the transaction.
+
+## Interpeting the Results
+
+If the transaction succeeds, check how much gas the transaction used.
+If the gas exceeds the callback gas limit for your chain as shown on [Contract Addresses](/entropy/contract-addresses), please reduce the gas usage to allow the provider to invoke the callback in the future.
+
+If the transaction fails, it typically indicates a failure originating from the implementation of the callback function.
+Check your implementation of the `entropyCallback` function to ensure that it does not throw an error when invoked.

pages/entropy/debug-callback-failures.mdx

@@ -1,9 +1,7 @@
 # Generate Random Numbers
 
-Integrations use a simple one-step on-chain process:
-
-1. **Request** a random number. Send a transaction with a random number that you have generated off-chain and receive a sequence number.
-
-Entropy will callback your contract with the generated random number once the request is fullfilled by the provider.
+Integrations simply call an on-chain function to request a random number from Entropy.
+This function takes a random number that you have generated off-chain and returns a sequence number.
+Entropy will then callback your contract with the generated random number once the request is fullfilled by the provider.
 
 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.mdx

@@ -95,3 +95,7 @@ function entropyCallback(
 ```
 
 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.
+
+## Additional Resources
+
+If you are having trouble getting the callback to run, please see the guide on how to [Debug Callback Failures](/entropy/debug-callback-failures).