Web SDK reference (@vrand.io/web)

npm install @vrand.io/web

Everything below is fully typed; this page is the map. The package also re-exports all of @vrand.io/client (instruction builders, PDA derivations, the local proof verifier, the bias-free scale module).

Entry points

Export	What it is
vrand	zero-config instance: mainnet, auto-detected wallet. For production apps, prefer createVrand with your own RPC.
createVrand(config)	a configured instance
CLUSTERS	per-cluster defaults (public RPC + fleet prover PDA) for devnet and mainnet-beta
keypairWallet(kp)	wrap a Keypair as a wallet (Node, bots, tests)
detectWallet()	the injected Phantom/Solflare provider, if any
deriveWinners(beta, entrants, count)	the published verifiable-draw spec
Draw, Session, VrandWebError	classes/types below

createVrand(config)

Option	Default	Meaning
cluster	"mainnet-beta"	"mainnet-beta" or "devnet" (free test SOL) — selects default RPC + fleet prover
wallet	auto-detect	any injected provider or wallet-adapter (WalletLike)
connection / rpcUrl	cluster default	your own web3.js Connection, or just an endpoint
prover	fleet prover for the cluster	the Prover PDA requests pin to
atRiskLamports	0	delivery coverage — the exact amount a silent prover forfeits to you (economics)
commitment	"confirmed"	web3.js commitment
timeoutMs	90000	wait budget per request before RequestTimeout
pollIntervalMs	1500	outcome poll cadence (websocket accelerates when available)
onStatus	—	phase callback: checking-terms → showing-terms → preflight → signing → confirming → awaiting-outcome → verifying
onTermsRequired	built-in modal	custom Terms display; resolve true only after the user agrees. Required in non-DOM environments
storage	localStorage	where session keys persist
verifier	local proof verification	test seam — leave unset

Requesting

Every helper returns a locally-verified result or throws a typed error — never an unverified value.

Method	Returns	Cost
random()	float in [0, 1)	1 request
randomInt(min, max)	integer, both ends inclusive	1 request
pick(items)	one element	1 request
shuffle(items)	shuffled copy	1 request
coinFlip()	boolean	1 request
weighted(items, weights)	one element, ∝ integer weight	1 request
draw(opts?)	a Draw — one request, many outcomes	1 request
randoms(count, opts?)	count independent floats	count requests, ~6 per signature
startSession(opts)	a Session	1 transfer
reclaim()	closes finished requests → rent + escrow back	tx fees only

random() also accepts a callback: vrand.random(r => …). Per-call opts: { atRiskLamports, timeoutMs, onStatus }.

First use per wallet per network: the full Terms of Use are displayed and the wallet signs a standalone acknowledgment transaction before its first request — explicit consent, once, details.

Draw

One verified request shaped into any number of outcomes via a shared deterministic stream (order matters; same order = same results, replayable from the chain).

Member	Meaning
float() int(min,max) pick(xs) shuffle(xs) coinFlip() weighted(xs,ws)	consume the stream
record	{ beta, proof, alpha, seed, address, requester, fulfilledSlot, signature, verified: true }
explorerUrl(cluster?)	link to the on-chain request

Session

Sign once, play all night. All request methods above, prompt-free, plus:

Member	Meaning
sessionKey	the session key's address
balance()	lamports remaining
recoveredLamports / toppedUpLamports	how startSession funded it (resume vs transfer)
end()	reclaim + sweep back + forget the key

deriveWinners(beta, entrants, count)

The receipt-reproducible draw spec: unweighted lists take the first count of the stream's permutation; entrants with { name, weight } draw sequentially without replacement; zero weights never win; entrant order is significant. Verification walkthrough.

Errors

Every failure is a VrandWebError with a code — the full table. The ones to handle in real apps: TermsDeclined, InsufficientBalance (carries exact numbers), RequestTimeout (retry; reclaim() recovers rent), RequestSlashed (compensated if covered), VerificationFailed (never use the value).