Skip to main content

Integration

Switchboard's VRF implementation allows the creator to specify a program callback that will be called each time a new proof is verified on-chain.

Callback​

When creating a VRF Account, the VRF vrf.authority should specify a vrf.callback function that will be called by the oracle when a new randomness value is produced.

FieldTypeDescription
programIdpublicKeyThe program ID of the callback program being invoked.
accountsAccountMetaZC[32]The accounts being used in the callback instruction.
accountsLenu32The number of accounts in the accounts array.
ixDatau8[1024]The serialized instruction data.
ixDataLenu32The length of the instruction buffer.

Pseudorandom Result​

The VRF function produces a u8[32] buffer, vrf.result, that can be transmuted to most data types using the bytemuck crate.

let result_buffer: [u8; 32];
// get result buffer from parsed VRF Account
msg!("Result buffer is {:?}", result_buffer);
let value: &[u128] = bytemuck::cast_slice(&result_buffer[..]);
msg!("u128 buffer {:?}", value);
let result = value[0] % max_result as u128;
msg!("Current VRF Value [0 - {}) = {}!", max_result, result);

Update Cost​

A VRF Account is required to have 0.002 wrapped SOL in their vrf.escrow before requesting randomness. If the vrf.escrow has insufficient funds, the difference will be deducted from the requesters token wallet. The oracle fulfilling the crank will receive 0.002 / 277 wrapped SOL upon submitting the proof, with the remaining amount being dispersed to the account who turned the VRF crank, which is typically the oracle.

Update Lifecycle​

Update Request​

  • The vrf.authority calls vrfRequestRandomness
  • sbv2 program checks if the request is valid by:
    • The previous vrf.status is equal to StatusNone, StatusCallbackSuccess, or StatusVerifyFailure
    • The previous vrf.status is equal to StatusRequesting, StatusVerifying, or StatusVerified and one minute has elapsed since the previous VRF request
  • sbv2 program sets the current vrf.status to StatusRequesting
  • sbv2 program checks the requester provided the required oracle reward and transfers it to vrf.escrow
  • sbv2 program increments vrf.counter
  • sbv2 program emits VrfRequestRandomnessEvent

Oracle Execution​

  • Oracle watches the chain for a VrfRequestRandomnessEvent with the oracle's public key assigned to the update request
  • Oracle calculates the VRF proof and submits a vrfProveAndVerify instruction on-chain
    • Oracle receives 1 / 277 of the reward
  • sbv2 program sets the current vrf.status to StatusVerifying
  • Oracle submits 276 Γ— vrfProveAndVerify instructions on-chain
    • Invoker receives 1 / 277 of the reward per each successful instruction
  • If proof verification fails,
    • sbv2 program sets vrf.status to StatusVerifyFailure
  • If proof verification succeeds,
    • sbv2 program sets vrf.status to StatusVerified
    • Oracle invokes vrf.callback
    • If vrf.callback is successfully invoked,
      • sbv2 program sets vrf.status to StatusCallbackSuccess