diff --git a/pages/entropy/_meta.json b/pages/entropy/_meta.json index 3ed7038a..3701fc44 100644 --- a/pages/entropy/_meta.json +++ b/pages/entropy/_meta.json @@ -47,6 +47,7 @@ "newWindow": true }, "examples": "Example Applications", + "request-callback-variants": "Request Callback Variants", "-- Understanding Entropy": { "title": "Understanding Entropy", diff --git a/pages/entropy/generate-random-numbers/evm.mdx b/pages/entropy/generate-random-numbers/evm.mdx index 84527756..e5ce13b6 100644 --- a/pages/entropy/generate-random-numbers/evm.mdx +++ b/pages/entropy/generate-random-numbers/evm.mdx @@ -82,20 +82,7 @@ function requestRandomNumber() external payable { This method returns a sequence number and emits a [`Requested`](https://github.com/pyth-network/pyth-crosschain/blob/main/target_chains/ethereum/entropy_sdk/solidity/EntropyEventsV2.sol#L30) event. You can store this sequence number to identify the request in next step. -Note that there are several variants of `requestV2` that allow the caller to configure the provider fulfilling the request and the gas limit for the callback. - - -Users can also request a random number with a custom gas limit by passing a **custom `gasLimit`** to the `requestV2(uint32 gasLimit){:bash}` call. -For example, -```solidity copy -function requestRandomNumber(uint32 gasLimit) external payable { - uint256 fee = entropy.getFeeV2(); - -uint64 sequenceNumber = entropy.requestV2{ value: fee }(gasLimit); -} - -```` - +Note that there are several variants of `requestV2` that allow the caller to configure the provider fulfilling the request and the gas limit for the callback. Refer [request callback variants](../request-callback-variants.mdx) for more details. Please see the method documentation in the [IEntropyV2 interface](https://github.com/pyth-network/pyth-crosschain/blob/main/target_chains/ethereum/entropy_sdk/solidity/IEntropyV2.sol). @@ -147,7 +134,7 @@ contract YourContract is IEntropyConsumer { } } -```` +``` 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. diff --git a/pages/entropy/request-callback-variants.mdx b/pages/entropy/request-callback-variants.mdx new file mode 100644 index 00000000..30e832f8 --- /dev/null +++ b/pages/entropy/request-callback-variants.mdx @@ -0,0 +1,131 @@ +# 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 + +```solidity copy +function requestV2() external payable returns (uint64 assignedSequenceNumber); + +``` + +This is the simplest variant that requests entropy using the default randomness provider and default gas settings. Uses in-contract PRNG for the user contribution to randomness. + +Use this when you want the most straightforward implementation and don't need to customize provider or gas parameters. + +### Example + +```solidity copy +function requestBasicRandomNumber() external payable { + // Get the fee for the default provider and gas limit + uint256 fee = entropy.getFeeV2(); + + require(msg.value >= fee, "Insufficient fee"); + + // Request randomness with default settings + uint64 sequenceNumber = entropy.requestV2{ value: fee }(); +} + +``` + +## 2. Request with Gas Limit + +```solidity copy +function requestV2( + uint32 gasLimit +) external payable returns (uint64 assignedSequenceNumber); + +``` + +This variant allows you to specify a custom gas limit for the callback function execution. Uses in-contract PRNG for the user contribution. + +Use this when your `entropyCallback` function has complex logic that requires more gas than the default amount, or when you want to optimize gas usage by setting a lower limit for simple callbacks. + +### Example + +```solidity copy +function requestWithCustomGas() external payable { + uint32 customGasLimit = 150000; // Custom gas limit for callback + + // Get fee for the custom gas limit + uint256 fee = entropy.getFeeV2(customGasLimit); + + require(msg.value >= fee, "Insufficient fee"); + + // Request with custom gas limit + uint64 sequenceNumber = entropy.requestV2{ value: fee }(customGasLimit); +} + +``` + +## 3. Request with Provider and Gas Limit + +```solidity copy +function requestV2( + address provider, + uint32 gasLimit +) external payable returns (uint64 assignedSequenceNumber); + +``` + +This variant allows you to specify both a custom randomness provider and a custom gas limit for the callback. Uses in-contract PRNG for the user contribution. + +Use this when you need full control over both the randomness source and the gas allocation for your callback execution. + +### Example + +```solidity copy +function requestWithProviderAndGas() external payable { + address preferredProvider = 0x1234567890123456789012345678901234567890; // Your chosen provider + uint32 customGasLimit = 100000; + + // Get fee for the specific provider and gas limit + uint256 fee = entropy.getFeeV2(preferredProvider, customGasLimit); + + require(msg.value >= fee, "Insufficient fee"); + + // Request with specific provider and gas limit + uint64 sequenceNumber = entropy.requestV2{ value: fee }( + preferredProvider, + customGasLimit + ); +} + +``` + +## 4. Request with Provider, User Randomness and Gas Limit + +```solidity copy +function requestV2( + address provider, + bytes32 userRandomNumber, + uint32 gasLimit +) external payable returns (uint64 assignedSequenceNumber); + +``` + +This is the most complete variant that allows you to specify a custom randomness provider, a custom gas limit for the callback, and provide your own user contribution to the randomness. The `userRandomNumber` parameter allows you to contribute your own randomness to the entropy generation process instead of relying on the in-contract PRNG. + +Use this when you need maximum control over all aspects of the randomness generation, including providing your own source of entropy for the user contribution. + +### Example + +```solidity copy +function requestWithFullControl(bytes32 userContribution) external payable { + address preferredProvider = 0x1234567890123456789012345678901234567890; + uint32 customGasLimit = 120000; + + // Get fee for the specific provider and gas limit + uint256 fee = entropy.getFeeV2(preferredProvider, customGasLimit); + + require(msg.value >= fee, "Insufficient fee"); + + // Request with full customization + uint64 sequenceNumber = entropy.requestV2{ value: fee }( + preferredProvider, + userContribution, // Your own randomness contribution + customGasLimit + ); +} + +```