What you’ll be doing in this guide
This tutorial shows you how to:- Integrate Pyth Entropy’s commit-reveal randomness system into your Sei EVM application
- Create smart contracts that request and consume verifiable random numbers with the Entropy protocol
- Implement a complete gaming application with fair, transparent randomness
- Handle fees, callbacks, and errors for production-ready randomness
Prerequisites
Before you start this tutorial, make sure that you have:Technical requirements
- Solidity knowledge: A basic understanding of smart contract development in Solidity
- JavaScript and Node.js: For off-chain interaction and frontend integration
- Development environment: Remix IDE, Hardhat, Foundry, or a similar Solidity development setup
- Sei network access: An RPC endpoint and familiarity with the Sei EVM environment
- Native tokens: SEI tokens, which you need to pay Entropy request fees
Required dependencies
- Pyth Entropy Solidity SDK (
@pythnetwork/entropy-sdk-solidity)
Install
Sei network configuration
Make sure that your development environment is configured for Sei:- Mainnet RPC:
https://evm-rpc.sei-apis.com - Chain ID: 1329 (Sei Mainnet)
- Testnet RPC:
https://evm-rpc-testnet.sei-apis.com - Testnet chain ID: 1328 (Sei Testnet)
Pyth Entropy architecture overview
Entropy uses a two-party commit-reveal protocol that has these parts:- Entropy provider: An off-chain service that commits to a sequence of random numbers with hash chains
- User commitment: Users contribute their own random input to make sure that the result is unpredictable
- Commit-reveal protocol: A two-party system where both parties contribute to the final randomness
- On-chain verification: Smart contracts verify the randomness proofs and execute callbacks
- Keeper network: Decentralized bots that fulfill randomness requests by revealing provider commitments
Key concepts
Before you implement the integration, make sure that you understand these main aspects of Pyth Entropy:Two-phase process
Entropy uses a two-phase approach:- Request phase: Your contract calls
entropy.requestV2()and receives asequenceNumber - Fulfillment phase: Off-chain keepers call your contract’s
entropyCallback()method to fulfill the request
Asynchronous nature
Unlike synchronous random number generation, Entropy requests are asynchronous:- The random number is not available immediately after the request
- Your application must handle the waiting period (typically 1 to 3 blocks)
- Use events and polling to detect when the randomness is fulfilled
Fee management
Entropy requires payment for each randomness request:- Before you make a request, always call
getFeeV2()to get the current fee - Fees are paid in the native token (SEI) as
msg.value - Fees are dynamic and may change based on network conditions
Callback implementation
Your contract must implement theentropyCallback function:
- This method is called automatically when the randomness is fulfilled
- It receives the
sequenceNumber,providerAddress, andrandomNumber - Handle all your game logic in this callback
Sequence number tracking
Each request has a uniquesequenceNumber:
- Use it to map requests to your application state
- Store game or request data with the sequence number as the key
- Multiple requests can be pending at the same time
Error handling
Always implement proper error handling:- Requests can fail or time out
- Network issues may prevent fulfillment
- Have fallback mechanisms for failed requests
Gas considerations
The callback execution has gas limits:- Keep callback logic simple to avoid out-of-gas errors
- For complex logic, consider custom gas limits with
requestV2variants - Store expensive computations for later execution
Steps to integrate Pyth Entropy into Sei
Step 1: Smart contract integration
Create a consumer contract that integrates with Pyth Entropy:
Entropy V2 uses a default provider system, so you do not need to specify a provider address in the constructor.
Step 2: JavaScript integration for Entropy management
Create a module that interacts with Entropy and manages randomness requests: The JavaScript examples below use CommonJS (require and module.exports). If your project uses "type": "module", rename these files to .cjs or convert the snippets to ES Modules.
Step 3: Complete integration example
This simple example combines all the parts: First, create a.env file in your project root (never commit this file):
Expected output
To run the complete demo, execute thedemo.js script:
Data structure details
Pyth Entropy V2 responses include these fields:- sequenceNumber: The unique identifier of the randomness request (uint64)
- randomNumber: The cryptographically secure random bytes32 value
- providerAddress: The address of the Entropy provider that fulfilled the request
- blockNumber: The block number when the request was fulfilled
Fee structure
- Dynamic fees: Always use the on-chain method
entropy.getFeeV2()to get the current fee - Native token payment: Fees are paid in the native blockchain token (SEI)
- Per-request basis: Each randomness request has its own fee
- No user commitment required: Entropy V2 does not need user random numbers. This makes the process simpler.
Best practices
- Fee management: Before you submit a request, always check the current fee with
getFeeV2() - Callback gas limits: For complex callback logic, set appropriate gas limits with the custom gas limit features of Entropy V2
- Error handling: Implement proper timeout and error handling for unfulfilled requests
- Sequential processing: Handle multiple requests appropriately, because they may be fulfilled out of order
- Storage optimization: The contract does not store fulfilled randomness. If you need it for multiple uses, save it.