RandomComponent

RandomComponent is your entry point to the world of randomness. It has a publicly available method request_random() that allows you to "ask" to call your component back with a random number.

fn request_random(&self, address: ComponentAddress, method_name: String, on_error: String,
    key: u32, badge_opt: Option<FungibleBucket>, expected_fee: u8) -> u32;

• address - the address of the Component to call back (Runtime::global_component().address()).

• method_name - the handler method on that Component to call back.

• on_error - the error handler that is invoked in case the above method panics.

• key - a key that will be sent back to you with the callback. It allows matching the callback with the current invocation of request_random(). Typically, this would be a sequential number, per which to store all necessary context into a KeyValueStore, and then later restore it in the callback or error handler (see example 3 - TBD).

• badge_opt - an Optional token that will be sent back to you with the callback (see auth). Ideally this should be a token minted specifically for authenticating RandomCompnent.

• expected_fee - how much you would expect the callback to cost, cents. Set to 0 if your component pays the TX fee (see fees).

The methods on your Component should have the following signatures (method names are up to you), depending on your chosen auth method:

bucket auth

pub fn callback(&mut self, key: u32, badge: FungibleBucket, random_seed: Vec<u8>);
pub fn on_error(&mut self, key: u32, badge: FungibleBucket);

badge auth (method_auth)

pub fn callback(&mut self, key: u32, random_seed: Vec<u8>);
pub fn on_error(&mut self, key: u32);

Here:

• callback - the method that actually uses randomness. It is executed by our Watcher backend service (through RandomComponent) in a separate transaction, as soon as it notices any committed transaction with a proper invocation of request_random().

• on_error - the method that is invoked in case the main handler panics and the transaction fails. Here you can revert whatever your Component did during the first transaction, e.g. if you marked a user's ticket as "used" you can unmark it so the user can retry the transaction. You need to be careful and make sure that the error handler doesn't panic, otherwise, your Component can potentially be in a state of permanently waiting for the callback that can only be resolved manually.

• key - whatever key you passed to request_random().

• badge - a token that you sent to request_random() as badge_opt.

• random_seed - 32 random bytes that you can either use directly or to seed the Random.