entropy-rng-api

API crate for interacting with the Entropy RNG (Random Number Generator) program on Solana.

Entropy is a provably-fair random number generation protocol for Solana. It uses a commit-reveal scheme paired with slothash sampling strategy to generate random numbers on-chain in a secure and cost-effective way.

Features

✅ Instruction builders for all Entropy RNG instructions
✅ State types and account deserialization
✅ PDA derivation utilities
✅ SDK functions for common operations
✅ Type-safe error handling

Installation

Add to your Cargo.toml:

[dependencies]
entropy-rng-api = "0.1.1"

Quick Start

use entropy_rng_api::prelude::*;

// Derive a Var PDA
let seed = b"my-seed";
let (var_pda, _bump) = var_pda(&seed);

// Build an Open instruction
let instruction = open(
    signer,
    var_address,
    commit,
    end_slot,
    is_auto,
);

Modules

Instructions

Open - Opens a new variable account
Close - Closes a variable account
Next - Moves a variable to the next value
Reveal - Reveals a seed to finalize the variable value
Sample - Samples the slothash from the chain

State

Var - Variable account that tracks a unique random variable

SDK

Helper functions for:

PDA derivation
Instruction building
Account deserialization

How It Works

Open: Create a new variable with a commit from the Entropy API
Sample: Sample the slothash from the chain at the specified slot
Reveal: Reveal the seed to finalize the variable value
Next: Reset the variable for its next value (using previous seed as new commit)

The protocol ensures provably-fair randomness by:

Committing to future seeds before the slothash is known
Using on-chain slothash that's unpredictable at commit time
Keeping future seeds secret until reveal time

Example

use entropy_rng_api::prelude::*;
use solana_program::pubkey::Pubkey;

// Derive variable PDA
let seed = b"my-random-seed";
let (var_pda, _bump) = var_pda(&seed);

// Build Open instruction
let open_ix = open(
    &signer.pubkey(),
    &var_pda,
    commit,           // From Entropy API
    end_slot,         // Target slot
    false,            // is_auto
);

// Build Sample instruction
let sample_ix = sample(
    &signer.pubkey(),
    &var_pda,
);

// Build Reveal instruction
let reveal_ix = reveal(
    &signer.pubkey(),
    &var_pda,
    seed_value,       // From Entropy API after sampling
);

Documentation

Full API documentation is available at:

docs.rs: https://docs.rs/entropy-rng-api
Repository: https://github.com/oil-protocol/entropy-rng

License

Licensed under Apache-2.0

Entropy Program - The on-chain Solana program
Entropy CLI - Command-line tools

entropy-rng-api 0.1.1