ORAO VRF Callback

A crate to interact with the orao-vrf-cb smart contract on the Solana network.

Provides an interface to request verifiable randomness (Ed25519 Signature) on the Solana network and receive a CPI callback upon fulfill.

Crate features

• sdk (default) — use this feature to build an off-chain client

• cpi — use this feature to integrate your program with the oracle

  [dependencies.orao-solana-vrf-cb]
  version = "..."
  default-features = false
  features = ["cpi"]
  

Integration

The integration process consists of the following steps:

1. Write and deploy a client program. It must be able to invoke the Request instruction via CPI. It might define the callback.
2. Register your program as a VRF client by sending the Register instruction.
3. Fund a new client created on a previous step (just transfer some SOL to the Client PDA).
4. Now you are ready to perform a Request instruction CPI

Callback functionality

Callback is an instruction invoked via CPI as soon as the randomness request is fulfilled.

The following rules are applied to the callback:

• it could be any instruction of the registered program

• it would be called with the following accounts:

  • The Client PDA (signer).
  • The state PDA (writable) (see Client::state).
  • The corresponding RequestAccount PDA (read-only).
  • ... zero or more subsequent accounts (see Callback::remaining_accounts).

The following rules are applied to the list of remaining accounts:

• it is possible to give an arbitrary read-only account
• it is only possible to give a writable account only if it is a registered program's PDA

Note that callbacks are optional. You can go without a callback giving None during the client registration. Also note, that there are two levels of callbacks:

1. Client-level callback — defined upon the client registration and couldn't be avoided, but you can override it with the Request-level callback (see Client::callback). You can update the Client-level callback using the SetCallback instruction.
2. Request-level callback — overrides the Client-level callback (even if it is not defined).

Callback faults

If Callback invocation is somehow fails then it is considered as a client misbehavior - well-written client's callback should never fail.

In any case the oracle will continue trying to fulfill such a client's request with increasing interval but eventually will fulfill it without invoking the Callback at all.

Clients

Any program may register any number of clients as long as unique state PDA is used for every registration. Every registered client maintains a SOL balance used to pay request fee and rent (note that the rent is reimbursed upon the fulfill).

It is trivial to fund a client — you should transfer some SOL to its address. The Withdraw instruction should be used to withdraw client funds but note that you couldn't withdraw past the Client PDA rent.

The client ownership might be transferred using the Transfer instruction.