entropy-rng-api 0.1.1

API for interacting with the Entropy RNG program on Solana
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122

# 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`:

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

## Quick Start

```rust
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

1. **Open**: Create a new variable with a commit from the Entropy API
2. **Sample**: Sample the slothash from the chain at the specified slot
3. **Reveal**: Reveal the seed to finalize the variable value
4. **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

```rust
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

## Related

- [Entropy Program](https://github.com/oil-protocol/entropy-rng) - The on-chain Solana program
- [Entropy CLI](https://github.com/oil-protocol/entropy-rng) - Command-line tools