diff --git a/images/entropy_event_log.png b/images/entropy_event_log.png new file mode 100644 index 00000000..0715245c Binary files /dev/null and b/images/entropy_event_log.png differ diff --git a/pages/entropy/_meta.json b/pages/entropy/_meta.json index 3a61162a..f4917851 100644 --- a/pages/entropy/_meta.json +++ b/pages/entropy/_meta.json @@ -24,6 +24,7 @@ }, "generate-random-numbers": "Generate Random Numbers", + "debug-callback-failures": "Debug Callback Failures", "-- Reference Material": { "title": "Reference Material", diff --git a/pages/entropy/debug-callback-failures.mdx b/pages/entropy/debug-callback-failures.mdx new file mode 100644 index 00000000..9ca6111a --- /dev/null +++ b/pages/entropy/debug-callback-failures.mdx @@ -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. diff --git a/pages/entropy/generate-random-numbers.mdx b/pages/entropy/generate-random-numbers.mdx index 1c005ae6..4ada56c9 100644 --- a/pages/entropy/generate-random-numbers.mdx +++ b/pages/entropy/generate-random-numbers.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. diff --git a/pages/entropy/generate-random-numbers/evm.mdx b/pages/entropy/generate-random-numbers/evm.mdx index 961e3d73..5639569f 100644 --- a/pages/entropy/generate-random-numbers/evm.mdx +++ b/pages/entropy/generate-random-numbers/evm.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).