From 7bf378cb1a86eb83e202f911075c83a2c33ce1fc Mon Sep 17 00:00:00 2001 From: nidhi-singh02 Date: Thu, 28 Aug 2025 15:53:49 +0400 Subject: [PATCH 1/3] add different variants of request v2 --- pages/entropy/generate-random-numbers/evm.mdx | 66 ++++++++++++++----- 1 file changed, 50 insertions(+), 16 deletions(-) diff --git a/pages/entropy/generate-random-numbers/evm.mdx b/pages/entropy/generate-random-numbers/evm.mdx index 84527756..97dadab6 100644 --- a/pages/entropy/generate-random-numbers/evm.mdx +++ b/pages/entropy/generate-random-numbers/evm.mdx @@ -58,6 +58,55 @@ contract YourContract is IEntropyConsumer { ## Usage +### requestV2 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. + +#### 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. + +#### 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. + +#### 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. + To generate a random number, follow these steps. ### 1. Request a number from Entropy @@ -82,21 +131,6 @@ 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); -} - -```` - - 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). ### 2. Implement the Entropy callback @@ -147,7 +181,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. From d3377f1cc167fd7fd872a7d4b3fbaafdf55e24dd Mon Sep 17 00:00:00 2001 From: nidhi-singh02 Date: Fri, 29 Aug 2025 13:25:16 +0400 Subject: [PATCH 2/3] add variants of request in reference material --- pages/entropy/_meta.json | 1 + pages/entropy/generate-random-numbers/evm.mdx | 51 +------ pages/entropy/request-variants.mdx | 131 ++++++++++++++++++ 3 files changed, 134 insertions(+), 49 deletions(-) create mode 100644 pages/entropy/request-variants.mdx diff --git a/pages/entropy/_meta.json b/pages/entropy/_meta.json index 3ed7038a..63d31858 100644 --- a/pages/entropy/_meta.json +++ b/pages/entropy/_meta.json @@ -47,6 +47,7 @@ "newWindow": true }, "examples": "Example Applications", + "request-variants": "Request 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 97dadab6..7745298e 100644 --- a/pages/entropy/generate-random-numbers/evm.mdx +++ b/pages/entropy/generate-random-numbers/evm.mdx @@ -58,55 +58,6 @@ contract YourContract is IEntropyConsumer { ## Usage -### requestV2 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. - -#### 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. - -#### 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. - -#### 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. - To generate a random number, follow these steps. ### 1. Request a number from Entropy @@ -131,6 +82,8 @@ 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. Refer [request variants](../request-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). ### 2. Implement the Entropy callback diff --git a/pages/entropy/request-variants.mdx b/pages/entropy/request-variants.mdx new file mode 100644 index 00000000..da4bbfad --- /dev/null +++ b/pages/entropy/request-variants.mdx @@ -0,0 +1,131 @@ +# Request 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 + ); +} + +``` From 565c08299eef1fb04051988d2cab281ebf364e39 Mon Sep 17 00:00:00 2001 From: nidhi-singh02 Date: Sat, 30 Aug 2025 14:18:49 +0400 Subject: [PATCH 3/3] changed title to request callback variants --- pages/entropy/_meta.json | 2 +- pages/entropy/generate-random-numbers/evm.mdx | 2 +- .../{request-variants.mdx => request-callback-variants.mdx} | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) rename pages/entropy/{request-variants.mdx => request-callback-variants.mdx} (99%) diff --git a/pages/entropy/_meta.json b/pages/entropy/_meta.json index 63d31858..3701fc44 100644 --- a/pages/entropy/_meta.json +++ b/pages/entropy/_meta.json @@ -47,7 +47,7 @@ "newWindow": true }, "examples": "Example Applications", - "request-variants": "Request Variants", + "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 7745298e..e5ce13b6 100644 --- a/pages/entropy/generate-random-numbers/evm.mdx +++ b/pages/entropy/generate-random-numbers/evm.mdx @@ -82,7 +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. Refer [request variants](../request-variants.mdx) for more details. +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). diff --git a/pages/entropy/request-variants.mdx b/pages/entropy/request-callback-variants.mdx similarity index 99% rename from pages/entropy/request-variants.mdx rename to pages/entropy/request-callback-variants.mdx index da4bbfad..30e832f8 100644 --- a/pages/entropy/request-variants.mdx +++ b/pages/entropy/request-callback-variants.mdx @@ -1,4 +1,4 @@ -# Request Variants +# 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: