stellar-vrf-sdk
Rust SDK for the Stellar VRF Oracle — verifiable, tamper-proof on-chain randomness for Stellar/Soroban.
Randomness comes from the drand quicknet beacon and is proven with a BLS12-381 pairing check executed on-chain, so every result is publicly auditable. Each request is bound to a future drand round, so with the registered keys unchanged the oracle can neither predict nor bias the outcome.
Trust assumption: the oracle account can rotate the oracle and drand keys (
rotate_oracle_keys/rotate_drand_pk), andfulfill()verifies against the keys registered at fulfillment time. Whoever controls that account can therefore bias outputs. Watch forrotate_ok/rotate_dkevents. See THREAT_MODEL.md.
Live on Stellar Mainnet:
CAW6KECQMHRTX2GS3JVHWBMOB5JNNOHNOCE635RQS4SWJ72YF56EUPRX
Installation
Scope — read this first
This crate is a read-only client. It is intentionally dependency-light: it does
not pull in stellar-xdr, and instead talks to Soroban JSON-RPC
simulateTransaction using compact hand-rolled XDR builders.
| Capability | Supported |
|---|---|
Query state (is_fulfilled, is_refunded, get_beta, derive_random_in_range, derive_range_for_domain) |
✅ |
Read events (get_request_events, get_fulfill_events) |
✅ |
| Wait for fulfillment | ✅ |
Offline derivation identical to the contract (derive_range_from_beta, derive_range_for_domain_from_beta, derive_u64_from_beta) |
✅ |
Submitting transactions (request, fulfill) |
❌ not supported |
Why: a signed submission needs a real source account and sequence number, a
Soroban resource footprint and fee from simulation, auth entries, and a signature.
The internal builder produces only the unsigned simulation envelope: a v1
TransactionEnvelope with an all-zero source account, sequence 1, fee 100, no
auth and no signatures. That is what RPC simulateTransaction accepts for
read-only calls, and it is byte-identical to what @stellar/stellar-sdk's
TransactionBuilder produces for the same call (checked by
test_simulation_envelope_matches_stellar_sdk). It would be rejected if
submitted, so this SDK doesn't expose write operations, and secret_key in
VrfClientConfig is currently unused (an empty string is fine).
Wire format. The encoders and the XDR decoder are tested against vectors from
the official @stellar/stellar-sdk encoder, against the contract's real event XDR,
and against live Mainnet getEvents output. Event values are decoded strictly:
an unexpected shape is an error, never a silent default.
Upgrade note: releases before this fix used wrong
ScValdiscriminants (e.g.Symbol = 10, which isI128). As a result,get_request_events/get_fulfill_eventsnever returned events, and the simulation envelope was rejected by the RPC ("Could not unmarshal transaction"). Upgrade if you depend on either.
To submit transactions, use the JavaScript SDK or the Stellar CLI, both of which use audited XDR serialization.
Quick Start
use ;
async
⚠ Domains must be committed before fulfillment.
derive_range_for_domain/derive_range_for_domain_from_betawork after the result is public, so a domain chosen afterwards can be ground (tryA,B,C, keep the best). If the value must be fair, the domain has to be a constant or a value stored beforerequest().
Waiting for fulfillment
// Polls every 3s until fulfilled; returns VrfError::Timeout after timeout_secs.
client.wait_for_fulfillment.await?;
Reading oracle activity
let latest = client.get_latest_ledger.await?;
// (start_ledger, limit)
let requests = client.get_request_events.await?;
let fulfills = client.get_fulfill_events.await?;
Error type
All fallible calls return Result<_, VrfError>, covering RPC failures, a
not-yet-fulfilled request (NotFulfilled) and polling timeouts (Timeout).
How it works
Your dApp ──request()──▶ VRF Contract ◀──fulfill()── Oracle
│ │
│ drand beacon
▼ BLS-VRF proof
✓ pairing check verified on-chain
✓ random output recorded on-chain
- Call
request()with arbitrary context bytes. - The oracle waits for a future drand round and builds a BLS12-381 VRF proof.
- The contract verifies
e(gamma, G2) == e(H(alpha), PK)on-chain and stores it. - Read the result, or derive a number in any range.
Independently verifying a result
You do not have to trust the oracle. The proof is stored in contract storage after
fulfillment (until it is removed via cleanup_proof() or archived by storage TTL)
and is always recoverable from the fulfill transaction itself:
alpha = sha256(request_id ‖ context ‖ drand_round ‖ sha256(drand_signature))
beta = sha256(BETA_DOMAIN ‖ gamma)
Cross-check the beacon against the public drand API:
https://api.drand.sh/52db9ba70e0cc0f6eaf7803dd07447a1f5477735fd3f661792ba94600c84e971/public/<round>
Security notes
- This client never signs anything.
secret_keyis not used or transmitted, so don't give it a real key. - Binding to a future drand round (published 3–6 s after the request ledger under normal ledger-clock alignment) prevents the oracle from choosing a favourable output while the registered keys are unchanged.
- Fulfillment is idempotent: a request can only be fulfilled once.
- If the oracle never answers, the requester can call
timeout_refund()after the timeout window (currently 20 drand rounds). - Full threat model.
Related
- JavaScript/TypeScript SDK:
stellar-vrf-sdkon npm - Interactive Playground
- Live Dashboard
- Integration Guide
- Repository
License
MIT