Pyth Entropy is an on-chain random number generator (RNG) that provides cryptographically secure, verifiable randomness for blockchain applications. Entropy uses a two-party commit-reveal protocol, a well-known protocol in the cryptography space for generating a random number, offering lower fees, direct integration with Pyth Network, scalability, and faster response times compared to traditional VRF solutions. Entropy delivers randomness that is trustless, low-latency, cost-efficient, and requires no registration.Documentation Index
Fetch the complete documentation index at: https://seilabs.mintlify.app/llms.txt
Use this file to discover all available pages before exploring further.
What You’ll Be Doing in This Guide
In this tutorial, you’ll learn 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 using the Entropy protocol
- Implement a complete gaming application with fair, transparent randomness
- Handle fees, callbacks, and error management for production-ready randomness
Prerequisites
Before starting this tutorial, ensure you have:Technical Requirements
- Solidity Knowledge: Basic understanding of Solidity smart contract development
- JavaScript/Node.js: For off-chain interaction and frontend integration
- Development Environment: Remix IDE, Hardhat, Foundry, or similar Solidity development setup
- Sei Network Access: RPC endpoint and familiarity with Sei’s EVM environment
- Native Tokens: SEI tokens required for paying Entropy request fees
Required Dependencies
- Pyth Entropy Solidity SDK (
@pythnetwork/entropy-sdk-solidity)
Install
Sei Network Configuration
Make sure your development environment is configured for Sei:- Mainnet RPC:
https://evm-rpc.sei-apis.com - Chain ID: 1329 (mainnet)
- Testnet RPC:
https://evm-rpc-testnet.sei-apis.com - Testnet Chain ID: 1328 (testnet)
Pyth Entropy Architecture Overview
Entropy uses a two-party commit-reveal protocol consisting of:- Entropy Provider: Off-chain service that commits to a sequence of random numbers using hash chains
- User Commitment: Users contribute their own random input to ensure unpredictability
- Commit-Reveal Protocol: Two-party system where both parties contribute to 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 implementing, it’s important to understand the key aspects of working with 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 fulfill the request by calling your contract’s
entropyCallback()method
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-3 blocks)
- Use events and polling to know when randomness is fulfilled
Fee Management
Entropy requires payment for each randomness request:- Always call
getFeeV2()to get the current fee before making requests - 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 randomness is fulfilled
- It receives the
sequenceNumber,providerAddress, andrandomNumber - All your game logic should be handled in this callback
Sequence Number Tracking
Each request has a uniquesequenceNumber:
- Use this to map requests to your application state
- Store game/request data using the sequence number as the key
- Multiple requests can be pending simultaneously
Error Handling
Always implement proper error handling:- Requests can fail or timeout
- 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 using 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:| Network | Entropy Contract Address |
|---|---|
| Sei Mainnet | 0x98046bd286715d3b0bc227dd7a956b83d8978603 |
| Sei Testnet | 0x36825bf3fbdf5a29e2d5148bfe7dcf7b5639e320 |
Step 2: JavaScript Integration for Entropy Management
Create a module to interact with Entropy and manage randomness requests: Note: The JavaScript examples below use CommonJS (require/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
Here’s a simple usage example that puts it all together: 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 several important fields:- sequenceNumber: Unique identifier for the randomness request (uint64)
- randomNumber: The cryptographically secure random bytes32 value
- providerAddress: Address of the entropy provider that fulfilled the request
- blockNumber: 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 simplifies the process by removing the need for user random numbers
Best Practices
- Fee Management: Always check current fees using
getFeeV2()before submitting requests - Callback Gas Limits: Set appropriate gas limits for complex callback logic using Entropy V2’s custom gas limit features
- Error Handling: Implement proper timeout and error handling for unfulfilled requests
- Sequential Processing: Handle multiple requests appropriately as they may be fulfilled out of order
- Storage Optimization: Remember that fulfilled randomness is not stored by the contract - save it if needed for multiple uses