use serde::{Deserialize, Serialize};
use thiserror::Error;
#[derive(Debug, Clone)]
pub enum Network {
Testnet,
Mainnet,
Custom { rpc_url: String, passphrase: String },
}
impl Network {
pub fn rpc_url(&self) -> &str {
match self {
Network::Testnet => "https://soroban-testnet.stellar.org",
Network::Mainnet => "https://soroban.stellar.org",
Network::Custom { rpc_url, .. } => rpc_url,
}
}
pub fn passphrase(&self) -> &str {
match self {
Network::Testnet => "Test SDF Network ; September 2015",
Network::Mainnet => "Public Global Stellar Network ; September 2015",
Network::Custom { passphrase, .. } => passphrase,
}
}
}
#[derive(Debug, Clone)]
pub struct VrfClientConfig {
pub contract_id: String,
pub network: Network,
pub secret_key: String,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct VrfProof {
pub request_id: u64,
pub alpha_seed: Vec<u8>,
pub gamma_point: Vec<u8>,
pub beta_output: Vec<u8>,
pub public_key: Vec<u8>,
pub drand_round: u64,
pub drand_signature: Vec<u8>,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct VrfRequestEvent {
pub request_id: u64,
pub requester: String,
pub required_round: u64,
pub ledger: u64,
}
#[derive(Debug, Error)]
pub enum VrfError {
#[error("HTTP error: {0}")]
Http(#[from] reqwest::Error),
#[error("JSON error: {0}")]
Json(#[from] serde_json::Error),
#[error("RPC error: {0}")]
Rpc(String),
#[error("Transaction failed: {0}")]
TxFailed(String),
#[error("Timeout waiting for fulfillment of request {0}")]
Timeout(u64),
#[error("Request {0} not fulfilled")]
NotFulfilled(u64),
#[error("Simulation failed: {0}")]
SimulationFailed(String),
}
#[derive(Serialize)]
struct JsonRpcRequest {
jsonrpc: String,
id: u64,
method: String,
params: serde_json::Value,
}
#[derive(Deserialize)]
struct JsonRpcResponse {
result: Option<serde_json::Value>,
error: Option<serde_json::Value>,
}
#[derive(Deserialize)]
struct SimulateResult {
results: Option<Vec<SimulateEntry>>,
error: Option<String>,
}
#[derive(Deserialize)]
struct SimulateEntry {
xdr: Option<String>,
}
#[derive(Deserialize)]
struct EventsResult {
events: Option<Vec<EventEntry>>,
}
#[derive(Deserialize)]
#[serde(rename_all = "camelCase")]
struct EventEntry {
ledger: Option<u64>,
value: Option<serde_json::Value>,
}
#[derive(Deserialize)]
struct HealthResult {
#[serde(rename = "latestLedger")]
latest_ledger: Option<u64>,
}
mod scv {
pub const BOOL: u32 = 0;
pub const VOID: u32 = 1;
pub const U32: u32 = 3;
pub const U64: u32 = 5;
pub const BYTES: u32 = 13;
pub const SYMBOL: u32 = 15;
pub const VEC: u32 = 16;
pub const MAP: u32 = 17;
pub const ADDRESS: u32 = 18;
}
fn put_u32(buf: &mut Vec<u8>, v: u32) {
buf.extend_from_slice(&v.to_be_bytes());
}
fn put_var_opaque(buf: &mut Vec<u8>, data: &[u8]) {
put_u32(buf, data.len() as u32);
buf.extend_from_slice(data);
buf.resize(buf.len() + (4 - data.len() % 4) % 4, 0);
}
fn encode_scval_u64(val: u64) -> Vec<u8> {
let mut buf = Vec::with_capacity(12);
put_u32(&mut buf, scv::U64);
buf.extend_from_slice(&val.to_be_bytes());
buf
}
fn encode_scval_bytes(data: &[u8]) -> Vec<u8> {
let mut buf = Vec::with_capacity(8 + data.len() + 3);
put_u32(&mut buf, scv::BYTES);
put_var_opaque(&mut buf, data);
buf
}
fn encode_scval_symbol(sym: &str) -> Vec<u8> {
let mut buf = Vec::with_capacity(8 + sym.len() + 3);
put_u32(&mut buf, scv::SYMBOL);
put_var_opaque(&mut buf, sym.as_bytes());
buf
}
#[doc(hidden)]
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ScVal {
Bool(bool),
Void,
U32(u32),
U64(u64),
Bytes(Vec<u8>),
Symbol(String),
Vec(Vec<ScVal>),
Map(Vec<(ScVal, ScVal)>),
Address(String),
}
fn xdr_err(msg: impl std::fmt::Display) -> VrfError {
VrfError::Rpc(format!("XDR decode error: {msg}"))
}
#[doc(hidden)]
pub fn decode_scval_b64(b64: &str) -> Result<ScVal, VrfError> {
let bytes = base64_decode(b64)?;
let mut r = XdrReader::new(&bytes);
let val = r.scval(0)?;
if r.pos != bytes.len() {
return Err(xdr_err(format!("{} trailing bytes", bytes.len() - r.pos)));
}
Ok(val)
}
#[doc(hidden)]
pub struct XdrReader<'a> {
pub data: &'a [u8],
pub pos: usize,
}
impl<'a> XdrReader<'a> {
pub fn new(data: &'a [u8]) -> Self {
Self { data, pos: 0 }
}
fn take(&mut self, n: usize) -> Result<&'a [u8], VrfError> {
let end = self
.pos
.checked_add(n)
.filter(|&e| e <= self.data.len())
.ok_or_else(|| xdr_err("unexpected end of input"))?;
let out = &self.data[self.pos..end];
self.pos = end;
Ok(out)
}
fn u32(&mut self) -> Result<u32, VrfError> {
Ok(u32::from_be_bytes(self.take(4)?.try_into().unwrap()))
}
fn u64(&mut self) -> Result<u64, VrfError> {
Ok(u64::from_be_bytes(self.take(8)?.try_into().unwrap()))
}
fn hash32(&mut self) -> Result<[u8; 32], VrfError> {
Ok(self.take(32)?.try_into().unwrap())
}
fn var_opaque(&mut self, max_len: usize) -> Result<&'a [u8], VrfError> {
let len = self.u32()? as usize;
if len > max_len {
return Err(xdr_err(format!("length {len} exceeds {max_len}")));
}
let data = self.take(len)?;
if self.take((4 - len % 4) % 4)?.iter().any(|&b| b != 0) {
return Err(xdr_err("non-zero padding"));
}
Ok(data)
}
fn count(&mut self) -> Result<usize, VrfError> {
let n = self.u32()? as usize;
if n > (self.data.len() - self.pos) / 4 {
return Err(xdr_err(format!("element count {n} exceeds input")));
}
Ok(n)
}
pub fn scval(&mut self, depth: u32) -> Result<ScVal, VrfError> {
if depth > 8 {
return Err(xdr_err("ScVal nesting too deep"));
}
match self.u32()? {
scv::BOOL => match self.u32()? {
0 => Ok(ScVal::Bool(false)),
1 => Ok(ScVal::Bool(true)),
b => Err(xdr_err(format!("invalid bool {b}"))),
},
scv::VOID => Ok(ScVal::Void),
scv::U32 => Ok(ScVal::U32(self.u32()?)),
scv::U64 => Ok(ScVal::U64(self.u64()?)),
scv::BYTES => Ok(ScVal::Bytes(self.var_opaque(usize::MAX)?.to_vec())),
scv::SYMBOL => {
let s = self.var_opaque(32)?;
String::from_utf8(s.to_vec())
.map(ScVal::Symbol)
.map_err(|_| xdr_err("symbol is not UTF-8"))
}
scv::VEC => {
if self.u32()? == 0 {
return Ok(ScVal::Vec(Vec::new()));
}
let n = self.count()?;
let mut items = Vec::with_capacity(n);
for _ in 0..n {
items.push(self.scval(depth + 1)?);
}
Ok(ScVal::Vec(items))
}
scv::MAP => {
if self.u32()? == 0 {
return Ok(ScVal::Map(Vec::new()));
}
let n = self.count()?;
let mut entries = Vec::with_capacity(n);
for _ in 0..n {
let k = self.scval(depth + 1)?;
let v = self.scval(depth + 1)?;
entries.push((k, v));
}
Ok(ScVal::Map(entries))
}
scv::ADDRESS => match self.u32()? {
0 => match self.u32()? {
0 => Ok(ScVal::Address(strkey_encode_ed25519(&self.hash32()?))),
t => Err(xdr_err(format!("unsupported public key type {t}"))),
},
1 => Ok(ScVal::Address(strkey_encode_contract(&self.hash32()?))),
t => Err(xdr_err(format!("unsupported address type {t}"))),
},
t => Err(xdr_err(format!("unsupported ScVal type {t}"))),
}
}
}
fn to_base64(data: &[u8]) -> String {
const CHARS: &[u8] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
let mut out = String::new();
for chunk in data.chunks(3) {
let b0 = chunk[0] as u32;
let b1 = if chunk.len() > 1 { chunk[1] as u32 } else { 0 };
let b2 = if chunk.len() > 2 { chunk[2] as u32 } else { 0 };
let triple = (b0 << 16) | (b1 << 8) | b2;
out.push(CHARS[((triple >> 18) & 0x3F) as usize] as char);
out.push(CHARS[((triple >> 12) & 0x3F) as usize] as char);
if chunk.len() > 1 {
out.push(CHARS[((triple >> 6) & 0x3F) as usize] as char);
} else {
out.push('=');
}
if chunk.len() > 2 {
out.push(CHARS[(triple & 0x3F) as usize] as char);
} else {
out.push('=');
}
}
out
}
pub struct VrfClient {
config: VrfClientConfig,
http: reqwest::Client,
}
impl VrfClient {
pub fn new(config: VrfClientConfig) -> Self {
Self {
config,
http: reqwest::Client::new(),
}
}
pub async fn is_fulfilled(&self, request_id: u64) -> Result<bool, VrfError> {
let result = self
.simulate_call("is_fulfilled", &[encode_scval_u64(request_id)])
.await?;
decode_bool_result(result)
}
pub async fn is_refunded(&self, request_id: u64) -> Result<bool, VrfError> {
let result = self
.simulate_call("is_refunded", &[encode_scval_u64(request_id)])
.await?;
decode_bool_result(result)
}
pub async fn derive_random_in_range(
&self,
request_id: u64,
min: u64,
max: u64,
) -> Result<u64, VrfError> {
let span = inclusive_span(min, max)?;
let result = self
.simulate_call(
"derive_random_in_range",
&[encode_scval_u64(request_id), encode_scval_u64(span)],
)
.await?;
Ok(decode_u64_result(result, request_id)? + min)
}
pub async fn derive_range_for_domain(
&self,
request_id: u64,
domain: &[u8],
min: u64,
max: u64,
) -> Result<u64, VrfError> {
if domain.len() > MAX_DERIVE_DOMAIN_LEN {
return Err(VrfError::Rpc(format!(
"domain is {} bytes; the contract accepts at most {MAX_DERIVE_DOMAIN_LEN}",
domain.len()
)));
}
let span = inclusive_span(min, max)?;
let result = self
.simulate_call(
"derive_range_for_domain",
&[
encode_scval_u64(request_id),
encode_scval_bytes(domain),
encode_scval_u64(span),
],
)
.await?;
Ok(decode_u64_result(result, request_id)? + min)
}
pub async fn get_beta(&self, request_id: u64) -> Result<[u8; 32], VrfError> {
let result = self
.simulate_call("get_beta", &[encode_scval_u64(request_id)])
.await?;
decode_beta_result(result, request_id)
}
}
fn decode_bool_result(result: Option<String>) -> Result<bool, VrfError> {
let xdr_b64 = result.ok_or_else(|| VrfError::Rpc("simulation returned no value".into()))?;
match decode_scval_b64(&xdr_b64)? {
ScVal::Bool(b) => Ok(b),
other => Err(VrfError::Rpc(format!("expected bool ScVal, got {other:?}"))),
}
}
fn decode_beta_result(result: Option<String>, request_id: u64) -> Result<[u8; 32], VrfError> {
let xdr_b64 = result.ok_or(VrfError::NotFulfilled(request_id))?;
match decode_scval_b64(&xdr_b64)? {
ScVal::Bytes(b) => b
.try_into()
.map_err(|b: Vec<u8>| VrfError::Rpc(format!("expected 32-byte beta, got {}", b.len()))),
other => Err(VrfError::Rpc(format!(
"expected BytesN<32> ScVal, got {other:?}"
))),
}
}
fn decode_u64_result(result: Option<String>, request_id: u64) -> Result<u64, VrfError> {
let xdr_b64 = result.ok_or(VrfError::NotFulfilled(request_id))?;
match decode_scval_b64(&xdr_b64)? {
ScVal::U64(v) => Ok(v),
other => Err(VrfError::Rpc(format!("expected u64 ScVal, got {other:?}"))),
}
}
impl VrfClient {
pub async fn wait_for_fulfillment(
&self,
request_id: u64,
timeout_secs: u64,
) -> Result<(), VrfError> {
let deadline = std::time::Instant::now() + std::time::Duration::from_secs(timeout_secs);
const RPC_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(10);
while std::time::Instant::now() < deadline {
match tokio::time::timeout(RPC_TIMEOUT, self.is_fulfilled(request_id)).await {
Ok(Ok(true)) => return Ok(()),
Ok(Ok(false)) => {
}
Ok(Err(err)) => {
eprintln!(
"[stellar-vrf-sdk] wait_for_fulfillment: transient error for request {}: {}. Retrying…",
request_id, err
);
}
Err(_elapsed) => {
eprintln!(
"[stellar-vrf-sdk] wait_for_fulfillment: RPC call timed out for request {} ({}s limit). Retrying…",
request_id, RPC_TIMEOUT.as_secs()
);
}
}
tokio::time::sleep(std::time::Duration::from_secs(3)).await;
}
Err(VrfError::Timeout(request_id))
}
pub async fn get_latest_ledger(&self) -> Result<u64, VrfError> {
let resp = self.rpc_call("getHealth", serde_json::json!({})).await?;
let health: HealthResult = serde_json::from_value(resp)?;
health
.latest_ledger
.ok_or_else(|| VrfError::Rpc("No latestLedger in health response".into()))
}
pub async fn get_request_events(
&self,
start_ledger: u64,
limit: u64,
) -> Result<Vec<VrfRequestEvent>, VrfError> {
let topic_xdr = to_base64(&encode_scval_symbol("request"));
let resp = self
.rpc_call(
"getEvents",
serde_json::json!({
"filters": [{
"type": "contract",
"contractIds": [self.config.contract_id],
"topics": [[topic_xdr]]
}],
"startLedger": start_ledger,
"pagination": { "limit": limit }
}),
)
.await?;
let events_result: EventsResult = serde_json::from_value(resp)?;
events_result
.events
.unwrap_or_default()
.iter()
.map(|evt| {
let (request_id, requester, required_round) =
parse_request_event_value(event_value_b64(evt)?)?;
Ok(VrfRequestEvent {
request_id,
requester,
required_round,
ledger: evt.ledger.unwrap_or(0),
})
})
.collect()
}
pub async fn get_fulfill_events(
&self,
start_ledger: u64,
limit: u64,
) -> Result<Vec<(u64, u64)>, VrfError> {
let topic_xdr = to_base64(&encode_scval_symbol("fulfill"));
let resp = self
.rpc_call(
"getEvents",
serde_json::json!({
"filters": [{
"type": "contract",
"contractIds": [self.config.contract_id],
"topics": [[topic_xdr]]
}],
"startLedger": start_ledger,
"pagination": { "limit": limit }
}),
)
.await?;
let events_result: EventsResult = serde_json::from_value(resp)?;
events_result
.events
.unwrap_or_default()
.iter()
.map(|evt| {
let (request_id, _beta) = parse_fulfill_event_value(event_value_b64(evt)?)?;
Ok((request_id, evt.ledger.unwrap_or(0)))
})
.collect()
}
async fn rpc_call(
&self,
method: &str,
params: serde_json::Value,
) -> Result<serde_json::Value, VrfError> {
let req = JsonRpcRequest {
jsonrpc: "2.0".into(),
id: 1,
method: method.into(),
params,
};
let resp: JsonRpcResponse = self
.http
.post(self.config.network.rpc_url())
.json(&req)
.send()
.await?
.json()
.await?;
if let Some(err) = resp.error {
return Err(VrfError::Rpc(format!("{}", err)));
}
resp.result
.ok_or_else(|| VrfError::Rpc("No result in RPC response".into()))
}
async fn simulate_call(
&self,
fn_name: &str,
args: &[Vec<u8>],
) -> Result<Option<String>, VrfError> {
let contract = strkey_decode_contract(&self.config.contract_id)?;
let envelope = build_simulation_envelope(&contract, fn_name, args);
let resp = self
.rpc_call(
"simulateTransaction",
serde_json::json!({ "transaction": to_base64(&envelope) }),
)
.await?;
let sim: SimulateResult = serde_json::from_value(resp)?;
if let Some(err) = sim.error {
return Err(VrfError::SimulationFailed(err));
}
if let Some(results) = sim.results {
if let Some(first) = results.first() {
return Ok(first.xdr.clone());
}
}
Ok(None)
}
}
fn crc16_xmodem(data: &[u8]) -> u16 {
let mut crc: u16 = 0x0000;
for &byte in data {
crc ^= (byte as u16) << 8;
for _ in 0..8 {
if crc & 0x8000 != 0 {
crc = (crc << 1) ^ 0x1021;
} else {
crc <<= 1;
}
}
}
crc
}
fn base32_encode(data: &[u8]) -> String {
const ALPHABET: &[u8; 32] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
let mut out = String::new();
let mut buffer: u32 = 0;
let mut bits: u32 = 0;
for &b in data {
buffer = (buffer << 8) | b as u32;
bits += 8;
while bits >= 5 {
bits -= 5;
out.push(ALPHABET[((buffer >> bits) & 0x1F) as usize] as char);
}
}
if bits > 0 {
out.push(ALPHABET[((buffer << (5 - bits)) & 0x1F) as usize] as char);
}
out
}
fn strkey_encode(version_byte: u8, payload: &[u8]) -> String {
let mut buf = Vec::with_capacity(1 + payload.len() + 2);
buf.push(version_byte);
buf.extend_from_slice(payload);
let crc = crc16_xmodem(&buf);
buf.extend_from_slice(&crc.to_le_bytes()); base32_encode(&buf)
}
pub fn strkey_encode_ed25519(key: &[u8]) -> String {
strkey_encode(6 << 3, key)
}
pub fn strkey_encode_contract(hash: &[u8]) -> String {
strkey_encode(2 << 3, hash)
}
#[doc(hidden)]
pub fn strkey_decode_contract(contract_id: &str) -> Result<[u8; 32], VrfError> {
let bad = |m: &str| VrfError::Rpc(format!("Invalid contract ID: {}", m));
if contract_id.len() != 56 {
return Err(bad("expected 56 characters"));
}
let decoded = base32_decode(contract_id).map_err(|e| bad(&e))?;
if decoded.len() != 35 {
return Err(bad("wrong decoded length"));
}
if decoded[0] != 2 << 3 {
return Err(bad("not a contract (C...) address"));
}
let expected = crc16_xmodem(&decoded[..33]);
let actual = u16::from_le_bytes([decoded[33], decoded[34]]);
if expected != actual {
return Err(bad("checksum mismatch"));
}
if strkey_encode(2 << 3, &decoded[1..33]) != contract_id {
return Err(bad("non-canonical encoding"));
}
let mut hash = [0u8; 32];
hash.copy_from_slice(&decoded[1..33]);
Ok(hash)
}
#[doc(hidden)]
pub fn base32_decode(input: &str) -> Result<Vec<u8>, String> {
const ALPHABET: &[u8] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
let input = input.trim_end_matches('=');
let mut bits = 0u64;
let mut bit_count = 0u32;
let mut out = Vec::new();
for ch in input.bytes() {
let val = ALPHABET
.iter()
.position(|&c| c == ch)
.ok_or_else(|| format!("Invalid base32 character: {}", ch as char))?
as u64;
bits = (bits << 5) | val;
bit_count += 5;
if bit_count >= 8 {
bit_count -= 8;
out.push((bits >> bit_count) as u8);
bits &= (1 << bit_count) - 1;
}
}
Ok(out)
}
#[doc(hidden)]
pub fn base64_decode(input: &str) -> Result<Vec<u8>, VrfError> {
const TABLE: [u8; 128] = {
let mut t = [0xFF; 128];
let chars = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
let mut i = 0;
while i < 64 {
t[chars[i] as usize] = i as u8;
i += 1;
}
t
};
let input = input.trim_end_matches('=');
let mut out = Vec::new();
let bytes: Vec<u8> = input
.bytes()
.filter(|b| *b != b'\n' && *b != b'\r')
.collect();
let mut buffer: u32 = 0;
let mut bits: u32 = 0;
for &b in &bytes {
if (b as usize) >= 128 || TABLE[b as usize] == 0xFF {
return Err(VrfError::Rpc(format!(
"invalid base64 character: {:?}",
b as char
)));
}
buffer = (buffer << 6) | TABLE[b as usize] as u32;
bits += 6;
if bits >= 8 {
bits -= 8;
out.push(((buffer >> bits) & 0xFF) as u8);
}
}
Ok(out)
}
#[doc(hidden)]
pub mod internal {
pub use super::{
base32_decode, base64_decode, decode_scval_b64, strkey_decode_contract, ScVal, XdrReader,
};
}
fn build_simulation_envelope(contract: &[u8; 32], fn_name: &str, args: &[Vec<u8>]) -> Vec<u8> {
let mut b = Vec::with_capacity(160 + args.iter().map(Vec::len).sum::<usize>());
put_u32(&mut b, 2); put_u32(&mut b, 0);
b.extend_from_slice(&[0u8; 32]);
put_u32(&mut b, 100); b.extend_from_slice(&1u64.to_be_bytes()); put_u32(&mut b, 1);
b.extend_from_slice(&[0u8; 16]);
put_u32(&mut b, 0); put_u32(&mut b, 1); put_u32(&mut b, 0); put_u32(&mut b, 24); put_u32(&mut b, 0); put_u32(&mut b, 1); b.extend_from_slice(contract);
put_var_opaque(&mut b, fn_name.as_bytes());
put_u32(&mut b, args.len() as u32);
for a in args {
b.extend_from_slice(a);
}
put_u32(&mut b, 0); put_u32(&mut b, 0); put_u32(&mut b, 0); b
}
fn inclusive_span(min: u64, max: u64) -> Result<u64, VrfError> {
if max < min {
return Err(VrfError::Rpc("max must be >= min".into()));
}
(max - min).checked_add(1).ok_or_else(|| {
VrfError::Rpc(
"range [0, u64::MAX] has 2^64 values and cannot be expressed as the contract's \
exclusive u64 bound; use derive_random_from_beta() or the raw beta instead"
.into(),
)
})
}
pub const DERIVE_DOMAIN: &[u8] = b"VREP_DERIVE_V2";
const DERIVE_TAG_U64: u8 = 0x01;
const DERIVE_TAG_RANGE: u8 = 0x02;
const DERIVE_TAG_RANGE_DOMAIN: u8 = 0x03;
pub const MAX_DERIVE_DOMAIN_LEN: usize = 64;
fn derive_hash(tag: u8, request_id: u64, parts: &[&[u8]], beta: &[u8; 32]) -> [u8; 32] {
use sha2::{Digest, Sha256};
let mut h = Sha256::new();
h.update(DERIVE_DOMAIN);
h.update([tag]);
h.update(request_id.to_be_bytes());
for p in parts {
h.update(p);
}
h.update(beta);
h.finalize().into()
}
pub fn reduce_uniform(hash: &[u8; 32], max: u64) -> Result<u64, VrfError> {
if max == 0 {
return Err(VrfError::Rpc("max must be > 0".into()));
}
let m = max as u128;
let rem = 0u128.wrapping_sub(m) % m; for half in [&hash[0..16], &hash[16..32]] {
let c = u128::from_be_bytes(half.try_into().unwrap());
if c <= u128::MAX - rem {
return Ok((c % m) as u64);
}
}
Err(VrfError::Rpc(
"range derivation failed: both candidates rejected".into(),
))
}
pub fn derive_u64_from_beta(beta: &[u8; 32], request_id: u64) -> u64 {
let h = derive_hash(DERIVE_TAG_U64, request_id, &[], beta);
u64::from_be_bytes(h[0..8].try_into().unwrap())
}
pub fn derive_range_from_beta(beta: &[u8; 32], request_id: u64, max: u64) -> Result<u64, VrfError> {
if max == 0 {
return Err(VrfError::Rpc("max must be > 0".into()));
}
if max == 1 {
return Ok(0);
}
let h = derive_hash(DERIVE_TAG_RANGE, request_id, &[&max.to_be_bytes()], beta);
reduce_uniform(&h, max)
}
pub fn derive_range_for_domain_from_beta(
beta: &[u8; 32],
request_id: u64,
domain: &[u8],
max: u64,
) -> Result<u64, VrfError> {
if max == 0 {
return Err(VrfError::Rpc("max must be > 0".into()));
}
if domain.len() > MAX_DERIVE_DOMAIN_LEN {
return Err(VrfError::Rpc("domain exceeds maximum length".into()));
}
if max == 1 {
return Ok(0);
}
let len = (domain.len() as u32).to_be_bytes();
let h = derive_hash(
DERIVE_TAG_RANGE_DOMAIN,
request_id,
&[&len, domain, &max.to_be_bytes()],
beta,
);
reduce_uniform(&h, max)
}
#[deprecated(
since = "2.0.0",
note = "use derive_range_from_beta(), which matches the contract and is exactly uniform"
)]
pub fn derive_random_from_beta(beta: &[u8], min: u64, max: u64) -> Result<u64, VrfError> {
if max <= min {
return Err(VrfError::Rpc("max must be greater than min".into()));
}
if beta.len() < 16 {
return Err(VrfError::Rpc("beta must be at least 16 bytes".into()));
}
let range = (max - min) as u128 + 1;
let beta_val = u128::from_be_bytes(beta[0..16].try_into().unwrap());
Ok(min + (beta_val % range) as u64)
}
pub fn to_hex(bytes: &[u8]) -> String {
bytes.iter().map(|b| format!("{:02x}", b)).collect()
}
fn event_value_b64(evt: &EventEntry) -> Result<&str, VrfError> {
match &evt.value {
Some(serde_json::Value::String(s)) => Ok(s),
other => Err(VrfError::Rpc(format!(
"event has no base64 value: {other:?}"
))),
}
}
fn parse_request_event_value(value_b64: &str) -> Result<(u64, String, u64), VrfError> {
let bad = |v: &ScVal| VrfError::Rpc(format!("unexpected request event value: {v:?}"));
let val = decode_scval_b64(value_b64)?;
match &val {
ScVal::Vec(items) => match items.as_slice() {
[ScVal::U64(id), ScVal::Address(who), ScVal::U64(round)] => {
Ok((*id, who.clone(), *round))
}
[ScVal::U64(id), ScVal::Address(who)] => Ok((*id, who.clone(), 0)),
_ => Err(bad(&val)),
},
_ => Err(bad(&val)),
}
}
fn parse_fulfill_event_value(value_b64: &str) -> Result<(u64, [u8; 32]), VrfError> {
let bad = |v: &ScVal| VrfError::Rpc(format!("unexpected fulfill event value: {v:?}"));
let val = decode_scval_b64(value_b64)?;
match &val {
ScVal::Vec(items) => match items.as_slice() {
[ScVal::U64(id), ScVal::Bytes(beta)] => {
let beta: [u8; 32] = beta.as_slice().try_into().map_err(|_| bad(&val))?;
Ok((*id, beta))
}
_ => Err(bad(&val)),
},
_ => Err(bad(&val)),
}
}
#[cfg(test)]
#[allow(deprecated)] mod tests {
use super::*;
fn vec_beta() -> [u8; 32] {
let mut b = [0u8; 32];
for (i, x) in b.iter_mut().enumerate() {
*x = i as u8;
}
b
}
#[test]
fn test_derive_vectors_match_contract() {
let beta = vec_beta();
assert_eq!(derive_u64_from_beta(&beta, 7), 17_155_214_937_666_214_782);
assert_eq!(derive_range_from_beta(&beta, 7, 6).unwrap(), 4);
assert_eq!(
derive_range_from_beta(&beta, 7, 1_000_000).unwrap(),
889_164
);
assert_eq!(
derive_range_from_beta(&beta, 7, u64::MAX).unwrap(),
11_798_261_183_955_500_607
);
assert_eq!(
derive_range_for_domain_from_beta(&beta, 7, b"card-1", 1000).unwrap(),
595
);
}
fn halves(c1: u128, c2: u128) -> [u8; 32] {
let mut h = [0u8; 32];
h[..16].copy_from_slice(&c1.to_be_bytes());
h[16..].copy_from_slice(&c2.to_be_bytes());
h
}
#[test]
fn test_reduce_uniform_matches_contract_rules() {
assert_eq!(
reduce_uniform(&halves(123_456_789, 42), 1_000_003).unwrap(),
123_456_789 % 1_000_003
);
assert_eq!(
reduce_uniform(&halves(u128::MAX - 1, 0), 3).unwrap(),
((u128::MAX - 1) % 3) as u64
);
assert_eq!(reduce_uniform(&halves(u128::MAX, 5), 3).unwrap(), 2);
let err = reduce_uniform(&halves(u128::MAX, u128::MAX), (1 << 63) + 1).unwrap_err();
assert!(err.to_string().contains("both candidates rejected"));
assert_eq!(
reduce_uniform(&halves(u128::MAX, u128::MAX), 1 << 32).unwrap(),
u32::MAX as u64
);
assert!(reduce_uniform(&halves(0, 0), 0).is_err());
}
#[test]
fn test_derive_range_edge_cases() {
let beta = vec_beta();
assert_eq!(derive_range_from_beta(&beta, 7, 1).unwrap(), 0);
assert!(derive_range_from_beta(&beta, 7, 0).is_err());
assert!(derive_range_for_domain_from_beta(&beta, 7, &[0u8; 65], 10).is_err());
assert!(derive_range_for_domain_from_beta(&beta, 7, &[0u8; 64], 10).unwrap() < 10);
let a = derive_range_for_domain_from_beta(&beta, 7, b"card-1", u64::MAX).unwrap();
let b = derive_range_for_domain_from_beta(&beta, 7, b"card-2", u64::MAX).unwrap();
let c = derive_range_from_beta(&beta, 8, u64::MAX).unwrap();
assert_ne!(a, b);
assert_ne!(c, derive_range_from_beta(&beta, 7, u64::MAX).unwrap());
}
#[test]
fn test_network_urls() {
assert_eq!(
Network::Testnet.rpc_url(),
"https://soroban-testnet.stellar.org"
);
assert_eq!(Network::Mainnet.rpc_url(), "https://soroban.stellar.org");
assert_eq!(
Network::Testnet.passphrase(),
"Test SDF Network ; September 2015"
);
}
#[test]
fn test_derive_random_from_beta() {
let beta = vec![
0xDE, 0xAD, 0xBE, 0xEF, 0x01, 0x02, 0x03, 0x04, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8,
0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8,
];
let result = derive_random_from_beta(&beta, 1, 100).unwrap();
assert!((1..=100).contains(&result));
let result2 = derive_random_from_beta(&beta, 1, 100).unwrap();
assert_eq!(result, result2);
}
#[test]
fn test_derive_random_invalid_range() {
let beta = vec![0u8; 32];
assert!(derive_random_from_beta(&beta, 100, 1).is_err());
}
#[test]
fn test_derive_random_short_beta() {
let beta = vec![0u8; 4]; assert!(derive_random_from_beta(&beta, 1, 100).is_err());
}
#[test]
fn test_encode_scval_u64() {
let encoded = encode_scval_u64(42);
assert_eq!(encoded.len(), 12);
assert_eq!(&encoded[0..4], &5u32.to_be_bytes());
assert_eq!(&encoded[4..12], &42u64.to_be_bytes());
}
fn unhex(s: &str) -> Vec<u8> {
(0..s.len())
.step_by(2)
.map(|i| u8::from_str_radix(&s[i..i + 2], 16).unwrap())
.collect()
}
#[test]
fn test_encode_scval_symbol_matches_stellar_sdk() {
assert_eq!(
to_base64(&encode_scval_symbol("request")),
"AAAADwAAAAdyZXF1ZXN0AA=="
);
assert_eq!(
to_base64(&encode_scval_symbol("fulfill")),
"AAAADwAAAAdmdWxmaWxsAA=="
);
assert_eq!(
encode_scval_symbol("test"),
unhex("0000000f0000000474657374")
);
}
#[test]
fn test_encode_scval_bytes_matches_stellar_sdk() {
assert_eq!(
encode_scval_bytes(&[0xab]),
unhex("0000000d00000001ab000000")
);
assert_eq!(encode_scval_bytes(b""), unhex("0000000d00000000"));
}
#[test]
fn test_simulation_envelope_matches_stellar_sdk() {
let contract =
strkey_decode_contract("CBTCC5QL5T3JSLEZO4PH6LSJYEQF6GEFDCAO67OXI4DTM5NXMK6TSUHU")
.unwrap();
let env = build_simulation_envelope(&contract, "is_fulfilled", &[encode_scval_u64(1)]);
assert_eq!(
to_base64(&env),
"AAAAAgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAGQAAAAAAAAAAQAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAGAAAAAAAAAABZiF2C+z2mSyZdx5/LknBIF8YhRiA733XRwc2dbdivTkAAAAMaXNfZnVsZmlsbGVkAAAAAQAAAAUAAAAAAAAAAQAAAAAAAAAAAAAAAA=="
);
let env = build_simulation_envelope(
&contract,
"derive_range_for_domain",
&[
encode_scval_u64(7),
encode_scval_bytes(b"card-1"),
encode_scval_u64(1000),
],
);
assert_eq!(
to_base64(&env),
"AAAAAgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAGQAAAAAAAAAAQAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAGAAAAAAAAAABZiF2C+z2mSyZdx5/LknBIF8YhRiA733XRwc2dbdivTkAAAAXZGVyaXZlX3JhbmdlX2Zvcl9kb21haW4AAAAAAwAAAAUAAAAAAAAABwAAAA0AAAAGY2FyZC0xAAAAAAAFAAAAAAAAA+gAAAAAAAAAAAAAAAA="
);
}
#[test]
fn test_parse_contract_event_vectors() {
let req = unhex(
"00000010000000010000000300000005000000000000000100000012000000000000000011111111\
11111111111111111111111111111111111111111111111111111111000000050000000001eecec8",
);
assert_eq!(
parse_request_event_value(&to_base64(&req)).unwrap(),
(
1,
"GAIRCEIRCEIRCEIRCEIRCEIRCEIRCEIRCEIRCEIRCEIRCEIRCEIRCF6M".to_string(),
32_427_720
)
);
let ful = unhex(
"0000001000000001000000020000000500000000000000010000000d0000002098c612abed131631\
47239f4323d4973cb68df7302564fc791e17c1aae95a6c9d",
);
let (id, beta) = parse_fulfill_event_value(&to_base64(&ful)).unwrap();
assert_eq!(id, 1);
assert_eq!(
to_hex(&beta),
"98c612abed13163147239f4323d4973cb68df7302564fc791e17c1aae95a6c9d"
);
}
#[test]
fn test_parse_mainnet_event_values() {
let (id, who, round) = parse_request_event_value(
"AAAAEAAAAAEAAAADAAAABQAAAAAAAAADAAAAEgAAAAAAAAAAmZz3cVG/1r8BH4AiQrWoVKqmI5dAl2N2ybrtTq7t8VgAAAAFAAAAAAHuy74=",
)
.unwrap();
assert_eq!(id, 3);
assert_eq!(
who,
"GCMZZ53RKG75NPYBD6ACEQVVVBKKVJRDS5AJOY3WZG5O2TVO5XYVR4DY"
);
assert_eq!(round, 32_426_942);
let (id, beta) = parse_fulfill_event_value(
"AAAAEAAAAAEAAAACAAAABQAAAAAAAAADAAAADQAAACBDasoG50C2Z6upEOd08wHZIggLpOtuNTci6ogl5o1nkA==",
)
.unwrap();
assert_eq!(id, 3);
assert_eq!(
to_hex(&beta),
"436aca06e740b667aba910e774f301d922080ba4eb6e353722ea8825e68d6790"
);
}
#[test]
fn test_parse_request_event_contract_requester_and_legacy_shape() {
let (id, who, round) = parse_request_event_value(
"AAAAEAAAAAEAAAADAAAABQAAAAAAAAAHAAAAEgAAAAEHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwAAAAUAAAAAAe7Oyg==",
)
.unwrap();
assert_eq!((id, round), (7, 32_427_722));
assert_eq!(
who,
"CADQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQOBYHA4DQP5KR"
);
let (id, who, round) = parse_request_event_value(
"AAAAEAAAAAEAAAACAAAABQAAAAAAAAAFAAAAEgAAAAAAAAAAERERERERERERERERERERERERERERERERERERERERERE=",
)
.unwrap();
assert_eq!((id, round), (5, 0));
assert_eq!(
who,
"GAIRCEIRCEIRCEIRCEIRCEIRCEIRCEIRCEIRCEIRCEIRCEIRCEIRCF6M"
);
}
#[test]
fn test_parse_event_rejects_unexpected_shapes() {
let map = "AAAAEQAAAAEAAAABAAAADwAAAApyZXF1ZXN0X2lkAAAAAAAFAAAAAAAAAAE=";
assert!(decode_scval_b64(map).is_ok());
assert!(parse_request_event_value(map).is_err());
assert!(parse_fulfill_event_value(map).is_err());
let bare_u64 = to_base64(&encode_scval_u64(9));
assert!(parse_request_event_value(&bare_u64).is_err());
assert!(parse_fulfill_event_value(&bare_u64).is_err());
let legacy_req =
"AAAAEAAAAAEAAAACAAAABQAAAAAAAAAFAAAAEgAAAAAAAAAAERERERERERERERERERERERERERERERERERERERERERE=";
assert!(parse_fulfill_event_value(legacy_req).is_err());
let short_beta =
unhex("0000001000000001000000020000000500000000000000010000000d00000001ab000000");
assert!(parse_fulfill_event_value(&to_base64(&short_beta)).is_err());
}
#[test]
fn test_decoder_rejects_malformed_xdr() {
let full = unhex(
"0000001000000001000000020000000500000000000000010000000d0000002098c612abed131631\
47239f4323d4973cb68df7302564fc791e17c1aae95a6c9d",
);
assert!(decode_scval_b64(&to_base64(&full)).is_ok());
for n in 0..full.len() {
assert!(
decode_scval_b64(&to_base64(&full[..n])).is_err(),
"prefix {n}"
);
}
let mut extra = full.clone();
extra.extend_from_slice(&[0, 0, 0, 0]);
assert!(decode_scval_b64(&to_base64(&extra)).is_err());
assert!(decode_scval_b64(&to_base64(&unhex("0000001000000001ffffffff"))).is_err());
assert!(decode_scval_b64(&to_base64(&unhex("0000000dffffffff"))).is_err());
assert!(decode_scval_b64(&to_base64(&unhex("0000000d00000001ab000001"))).is_err());
assert!(decode_scval_b64(&to_base64(&unhex("0000000000000002"))).is_err());
assert!(decode_scval_b64(&to_base64(&unhex("00000063"))).is_err());
assert!(decode_scval_b64("!!!!").is_err());
let mut deep = Vec::new();
for _ in 0..64 {
deep.extend_from_slice(&unhex("000000100000000100000001"));
}
deep.extend_from_slice(&unhex("00000001"));
assert!(decode_scval_b64(&to_base64(&deep)).is_err());
assert_eq!(
decode_scval_b64(&to_base64(&unhex("0000001000000000"))).unwrap(),
ScVal::Vec(vec![])
);
}
#[test]
fn test_decode_simulation_results() {
assert!(decode_bool_result(Some("AAAAAAAAAAE=".into())).unwrap());
assert!(!decode_bool_result(Some("AAAAAAAAAAA=".into())).unwrap());
assert!(decode_bool_result(None).is_err());
let u64_val = to_base64(&encode_scval_u64(1 << 16)); assert!(u64_val.contains("AAAAAQ"));
assert!(decode_bool_result(Some(u64_val)).is_err());
assert_eq!(
decode_u64_result(Some(to_base64(&encode_scval_u64(889_164))), 7).unwrap(),
889_164
);
assert!(matches!(
decode_u64_result(None, 7),
Err(VrfError::NotFulfilled(7))
));
assert!(decode_u64_result(Some("AAAAAAAAAAE=".into()), 7).is_err());
let beta: Vec<u8> = (0u8..32).collect();
assert_eq!(
decode_beta_result(Some(to_base64(&encode_scval_bytes(&beta))), 1)
.unwrap()
.to_vec(),
beta
);
assert!(decode_beta_result(Some(to_base64(&encode_scval_bytes(&beta[..31]))), 1).is_err());
}
#[test]
fn test_base32_decode() {
let result = base32_decode("ME");
assert!(result.is_ok());
assert_eq!(result.unwrap(), vec![0x61]); }
#[test]
fn test_to_hex() {
assert_eq!(to_hex(&[0xDE, 0xAD, 0xBE, 0xEF]), "deadbeef");
}
#[test]
fn test_to_base64() {
assert_eq!(to_base64(b"Hello"), "SGVsbG8=");
}
#[test]
fn test_strkey_encode_ed25519_known_vector() {
let raw: [u8; 32] = [
0x6d, 0xb3, 0x7d, 0x0d, 0xa1, 0x5a, 0x1a, 0x1e, 0x7c, 0x1a, 0x1a, 0x45, 0x9a, 0x3f,
0x63, 0x19, 0x0b, 0x34, 0x63, 0x0c, 0x1e, 0x1a, 0x1e, 0x1a, 0x1e, 0x1a, 0x1e, 0x1a,
0x1e, 0x1a, 0x1e, 0x1a,
];
let encoded = strkey_encode_ed25519(&raw);
assert!(encoded.starts_with('G'), "account StrKey must start with G");
assert_eq!(encoded.len(), 56, "StrKey addresses are 56 characters");
assert!(
encoded
.chars()
.all(|c| c.is_ascii_uppercase() || ('2'..='7').contains(&c)),
"must use the RFC4648 base32 alphabet, got {encoded}"
);
let decoded = base32_decode(&encoded).expect("must decode");
assert_eq!(&decoded[1..33], &raw[..], "payload must round-trip");
}
#[test]
fn test_strkey_contract_round_trip() {
let hash: [u8; 32] = [7u8; 32];
let encoded = strkey_encode_contract(&hash);
assert!(
encoded.starts_with('C'),
"contract StrKey must start with C"
);
assert_eq!(encoded.len(), 56);
let back = strkey_decode_contract(&encoded).expect("must decode");
assert_eq!(back, hash);
}
#[test]
fn test_crc16_xmodem_known_vector() {
assert_eq!(crc16_xmodem(b"123456789"), 0x31C3);
}
#[test]
fn test_derive_random_from_beta_range_and_determinism() {
let beta = [0xABu8; 32];
for (min, max) in [
(1u64, 6u64),
(1, 100),
(0, u64::MAX / 2),
(5, 5 + (1 << 62)),
] {
let a = derive_random_from_beta(&beta, min, max).unwrap();
let b = derive_random_from_beta(&beta, min, max).unwrap();
assert_eq!(a, b, "must be deterministic");
assert!(a >= min && a <= max, "{a} outside [{min}, {max}]");
}
assert!(derive_random_from_beta(&[0u8; 8], 1, 10).is_err());
assert!(derive_random_from_beta(&beta, 10, 10).is_err());
}
#[test]
fn test_derive_random_from_beta_full_u64_range() {
let lo = derive_random_from_beta(&[0x00u8; 16], 0, u64::MAX).unwrap();
let hi = derive_random_from_beta(&[0xFFu8; 16], 0, u64::MAX).unwrap();
assert_eq!(lo, 0);
assert_eq!(hi, u64::MAX, "2^128-1 mod 2^64 = 2^64-1");
let beta = [0xABu8; 32];
for (min, max) in [
(1u64, u64::MAX),
(0, u64::MAX - 1),
(u64::MAX - 1, u64::MAX),
] {
let v = derive_random_from_beta(&beta, min, max).unwrap();
assert!(v >= min && v <= max, "{v} outside [{min}, {max}]");
}
}
#[test]
fn test_inclusive_span_boundaries() {
assert_eq!(inclusive_span(1, 100).unwrap(), 100);
assert_eq!(inclusive_span(7, 7).unwrap(), 1);
assert_eq!(inclusive_span(1, u64::MAX).unwrap(), u64::MAX);
assert_eq!(inclusive_span(0, u64::MAX - 1).unwrap(), u64::MAX);
let err = inclusive_span(0, u64::MAX).unwrap_err().to_string();
assert!(err.contains("2^64"), "unexpected error: {err}");
assert!(inclusive_span(10, 9).is_err());
}
#[tokio::test]
async fn test_client_creation() {
let client = VrfClient::new(VrfClientConfig {
contract_id: "CBEDNSJ63LANUSJHRZSNQUV22X6JYU6E7PTUDIGQDOHNH7VIT4CAJTBR".into(),
network: Network::Testnet,
secret_key: String::new(),
});
assert_eq!(
client.config.contract_id,
"CBEDNSJ63LANUSJHRZSNQUV22X6JYU6E7PTUDIGQDOHNH7VIT4CAJTBR"
);
}
#[test]
fn test_strkey_decode_contract() {
let result =
strkey_decode_contract("CBEDNSJ63LANUSJHRZSNQUV22X6JYU6E7PTUDIGQDOHNH7VIT4CAJTBR");
assert!(result.is_ok());
assert_eq!(result.unwrap().len(), 32);
}
#[test]
fn test_strkey_decode_contract_rejects_bad_ids() {
let good = "CAW6KECQMHRTX2GS3JVHWBMOB5JNNOHNOCE635RQS4SWJ72YF56EUPRX";
assert!(strkey_decode_contract(good).is_ok());
let mut typo = good.to_string();
typo.replace_range(10..11, if &good[10..11] == "A" { "B" } else { "A" });
assert!(
strkey_decode_contract(&typo).is_err(),
"typo must fail the CRC"
);
let account = strkey_encode_ed25519(&[7u8; 32]);
assert_eq!(account.len(), 56);
assert!(
strkey_decode_contract(&account).is_err(),
"G... must be rejected"
);
assert!(strkey_decode_contract(&good[..55]).is_err());
assert!(strkey_decode_contract(&format!("{good}A")).is_err());
assert!(strkey_decode_contract("").is_err());
let lower = good.to_lowercase();
assert!(strkey_decode_contract(&lower).is_err());
}
}