Skip to main content
Pyth Entropy is an on-chain random number generator (RNG) that supplies cryptographically secure, verifiable randomness to blockchain applications. Entropy uses a two-party commit-reveal protocol, which is a well-known way to generate a random number in cryptography. Compared to traditional VRF solutions, Entropy offers lower fees, direct integration with Pyth Network, scalability, and faster response times. Entropy delivers trustless, low-latency, cost-efficient randomness. It does not require registration.

What you’ll be doing in this guide

This tutorial shows you how to:
  1. Integrate Pyth Entropy’s commit-reveal randomness system into your Sei EVM application
  2. Create smart contracts that request and consume verifiable random numbers with the Entropy protocol
  3. Implement a complete gaming application with fair, transparent randomness
  4. Handle fees, callbacks, and errors for production-ready randomness
By the end of this guide, you will have a working demo that uses Pyth Entropy. It can request cryptographically secure random numbers on the Sei network, with proper verification mechanisms.

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:
  1. Entropy provider: An off-chain service that commits to a sequence of random numbers with hash chains
  2. User commitment: Users contribute their own random input to make sure that the result is unpredictable
  3. Commit-reveal protocol: A two-party system where both parties contribute to the final randomness
  4. On-chain verification: Smart contracts verify the randomness proofs and execute callbacks
  5. 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 a sequenceNumber
  • 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 the entropyCallback function:
  • This method is called automatically when the randomness is fulfilled
  • It receives the sequenceNumber, providerAddress, and randomNumber
  • Handle all your game logic in this callback

Sequence number tracking

Each request has a unique sequenceNumber:
  • 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 requestV2 variants
  • 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:
Deploy this contract with Remix. Use the Entropy contract address for your target network: 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):
Then create the demo script:

Expected output

To run the complete demo, execute the demo.js script:
When you run the Pyth Entropy integration, you should see output similar to this:

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

  1. Fee management: Before you submit a request, always check the current fee with getFeeV2()
  2. Callback gas limits: For complex callback logic, set appropriate gas limits with the custom gas limit features of Entropy V2
  3. Error handling: Implement proper timeout and error handling for unfulfilled requests
  4. Sequential processing: Handle multiple requests appropriately, because they may be fulfilled out of order
  5. Storage optimization: The contract does not store fulfilled randomness. If you need it for multiple uses, save it.

Resources