# Use Randcast CLI Randcast users can leverage our [Randcast CLI](https://github.com/ARPA-Network/BLS-TSS-Network/tree/main/crates/user-cli) tool to manage their subscription and consumer contracts, read and filter historical requests and fulfillment results, and estimate the gas cost of the callback function, all in one place. ***Note**: This is our recommended method to interact with Randcast, but we also offer additional methods, such as direct contract interaction, in the* [*following section*](https://docs.arpanetwork.io/randcast/getting-started/use-solidity-development-tools)*.* ### Prerequisites * Smart Contract development experience in Solidity * Experience with [Foundry](https://github.com/foundry-rs/foundry) Solidity development toolkit ### Installation * (**Recommended**) Install from Docker image * `docker pull arpachainio/user-shell:latest` * (Optional) Build from the [codebase](https://github.com/ARPA-Network/BLS-TSS-Network/tree/main/crates/user-cli) ### Usage ```bash docker run -it -v :/data ghcr.io/arpa-network/user-shell:latest "user-shell -c /data/user_config.yml -H /data/user-shell.history" ``` * create a \ as the directory for Randcast CLI on your host, e.g. /home/ubuntu/randcast-cli * prepare a `user_config.yml` under \ of your host. Please see the [example](https://github.com/ARPA-Network/BLS-TSS-Network/blob/main/crates/user-cli/conf/user_config.yml.example) for reference. ***Note**: we recommend directly setting account identity in `user_config.yml` rather than passing an env variable to docker.* * use `-H` to set a file to save history commands. * `--network=host`(optional config for local chains) \ If you want the Randcast CLI container to access a local chain on the host (ex: Anvil), you can use the above flag. This will allow the container to access ports on the localhost such as "[http://127.0.0.1:8545](http://127.0.0.1:8545/)". ### Steps ***Note**: Always use `[COMMAND] -h` to get help.* #### Create a subscription: ```bash ARPA User CLI〉send cs ``` *** #### Get subscriptions(\): ```bash ARPA User CLI〉randcast mss ``` ``` my subscriptions: [ 1, ] ``` *** #### Write and deploy a consumer contract. Here we use `forge` from `Foundry` to complete this step. Note that `--rpc-url` is needed unless you are performing tests using a local chain: *(Reference:* [*forge create*](https://book.getfoundry.sh/forge/deploying)*)* 
git clone https://github.com/ARPA-Network/Randcast-User-Contract
cd Randcast-User-Contract
forge create contracts/user/examples/GetRandomNumberExample.sol:GetRandomNumberExample --rpc-url <RPC_URL> --private-key <USER_PRIVATE_KEY> --constructor-args <ADAPTER_CONTRACT_ADDRESS>

[⠢] Compiling...
No files changed, compilation skipped
Enter private key:
Deployer: 0x70997970C51812dc3A010C7d01b50e0d17dc79C8
Deployed to: 0x712516e61C8B383dF4A63CFe83d7701Bce54B03e
Transaction hash: 0xbf63e615506fb89fee3fd53a04f09335eafcb826b7283d2997db86eb7fa852c0
*** #### Bind the consumer contract to the subscription: ```bash ARPA User CLI〉send add-consumer ``` *** #### Check a specific subscription to make sure that a consumer contract has been added: ```bash ARPA User CLI〉randcast s ``` ``` owner: 0x70997970c51812dc3a010c7d01b50e0d17dc79c8, consumers: [ 0x712516e61C8B383dF4A63CFe83d7701Bce54B03e, ], balance: 0, inflight_cost: 0, req_count: 0, free_request_count: 1, referral_sub_id: 0, req_count_in_current_period: 0, last_request_timestamp: 0 ``` *** #### Estimate gas cost for the fulfillment of the first request: ```bash ARPA User CLI〉randcast estimate-callback-gas "getRandomNumber()" "" ``` ``` estimate_callback_gas_limit_res: 97191 ``` ```bash ARPA User CLI〉randcast estimate-payment-amount 97191 ``` ``` payment_amount_in_eth_wei: 2883418467348405 in 3 times of current gas price: 3 * 1425618985 ``` *** #### Fund the subscription with a little more than the estimated payment amount to cover the surge in gas price: ```bash ARPA User CLI〉send fs 3000000000000000 Fund subscription successfully, transaction hash: 0x1301eb5d3751aaed2fe224ed96f6fa31a210d55a05e0e759eb34a4cd577398cb ``` *** #### The subscription should be ready to use now, double-check it: ```bash ARPA User CLI〉randcast s ``` ``` owner: 0x70997970c51812dc3a010c7d01b50e0d17dc79c8, consumers: [ 0x712516e61C8B383dF4A63CFe83d7701Bce54B03e, ], balance: 3000000000000000, inflight_cost: 0, req_count: 0, free_request_count: 1, referral_sub_id: 0, req_count_in_current_period: 0, last_request_timestamp: 0 ``` *** #### Request randomness in any way that you need. Here we use `cast` from `Foundry` (note that `--rpc-url` is needed unless you are using a local chain): *(Reference:* [*cast send*](https://book.getfoundry.sh/reference/cast/cast-send)*)* ```bash cast send "getRandomNumber()" --rpc-url --private-key ``` *** #### Query historical randomness requests paid by the subscription Note: it is possible to add an optional filter to filter by consumer address or by status (pending / success / failed). You can view these options by running `randcast rs --help`. 
ARPA User CLI〉randcast rs <CHAIN_ID> <SUB_ID>
``` 4 request(s) found! requests: [ RandomnessRequest { request_id: "f824e7e71084837988642d6e80b6cb632e8dc5bced216143970573cf0e471d48", sub_id: 1, group_index: 0, request_type: Randomness, params: Bytes(0x), sender: 0x5ee8ba836860dd0f65f0815353f924562c32321a, seed: 74177094504516131371017173948908728010834945092155580109839890742103808072250, request_confirmations: 6, callback_gas_limit: 97191, callback_max_gas_price: 85572193836, estimated_payment: 57692002934486676, fulfillment_result: Some( RandomnessRequestResult { request_id: "f824e7e71084837988642d6e80b6cb632e8dc5bced216143970573cf0e471d48", group_index: 0, committer: 0x6d49d417c2ab52b941253cb9f018597f98c2e94b, participant_members: [ 0x6d49d417c2ab52b941253cb9f018597f98c2e94b, 0xc8edfe4a67bccc676222f0e65ef4bd2ede513d92, 0xc832555ba1285fcd9ff224a879727fe80c5c2fe6, ], randommness: 72268503294186913141421904411716557309821678372656178088948653025159185717542, payment: 58534118894026752, flat_fee: 0, success: true, }, ), }, RandomnessRequest { request_id: "63057a4c16c3955847235ec0b2a7e804633dea38f1cc4629dff9c34fd15030ed", sub_id: 1, group_index: 0, request_type: Randomness, params: Bytes(0x), sender: 0x5ee8ba836860dd0f65f0815353f924562c32321a, seed: 89821905989940142828936339811540536617118967869705504742968373863645089094375, request_confirmations: 6, callback_gas_limit: 97191, callback_max_gas_price: 53119805535, estimated_payment: 36312894813447185, fulfillment_result: Some( RandomnessRequestResult { request_id: "63057a4c16c3955847235ec0b2a7e804633dea38f1cc4629dff9c34fd15030ed", group_index: 0, committer: 0xc832555ba1285fcd9ff224a879727fe80c5c2fe6, participant_members: [ 0x6d49d417c2ab52b941253cb9f018597f98c2e94b, 0xc8edfe4a67bccc676222f0e65ef4bd2ede513d92, 0xc832555ba1285fcd9ff224a879727fe80c5c2fe6, ], randommness: 27769558289933409672681258774250203594411447646562338907630847289833910951376, payment: 12159332538611792, flat_fee: 500000000000000, success: true, }, ), }, RandomnessRequest { request_id: "bc258e216cf5b8c4549e2667b9f0f2f8a0e5324283a5dca264a639dd3208a948", sub_id: 1, group_index: 1, request_type: Randomness, params: Bytes(0x), sender: 0x5ee8ba836860dd0f65f0815353f924562c32321a, seed: 65689501420482864634999382338188236957641370482439689010961927607951890384023, request_confirmations: 6, callback_gas_limit: 97191, callback_max_gas_price: 38074832601, estimated_payment: 26169709466100791, fulfillment_result: Some( RandomnessRequestResult { request_id: "bc258e216cf5b8c4549e2667b9f0f2f8a0e5324283a5dca264a639dd3208a948", group_index: 1, committer: 0xc07d3983594dc9ad7259e50736651a617df43170, participant_members: [ 0xde59c3f995d43bbb685652d3e7094c845120f98e, 0xbb38b3302fa38acf3a3aeb7fa2b3d5765cd11244, 0xc07d3983594dc9ad7259e50736651a617df43170, ], randommness: 95246188166766731484576812306679763734598701698698797793739803330019880659163, payment: 10059228421561584, flat_fee: 500000000000000, success: true, }, ), }, RandomnessRequest { request_id: "595e03b0f8ed7a0bcf19b71c8cba59a962d36f85f5e96b0099f03f5ceb19b3bb", sub_id: 1, group_index: 2, request_type: Randomness, params: Bytes(0x), sender: 0x5ee8ba836860dd0f65f0815353f924562c32321a, seed: 116151869703078905907283770278682715348011778460587914840440360538538455582, request_confirmations: 6, callback_gas_limit: 97191, callback_max_gas_price: 38073220653, estimated_payment: 26168622705266723, fulfillment_result: Some( RandomnessRequestResult { request_id: "595e03b0f8ed7a0bcf19b71c8cba59a962d36f85f5e96b0099f03f5ceb19b3bb", group_index: 2, committer: 0xeecc599896c326a692ed88e077d83ae70b368060, participant_members: [ 0xd0ff7138f54b84ac8180a1c0777f56f57845a9f2, 0xeecc599896c326a692ed88e077d83ae70b368060, 0x666bcd629be685c8a197541f3e98ab12f1c5b673, ], randommness: 32764317417096660201628975371287017617294336828480713865304328240339078207177, payment: 9812265191830704, flat_fee: 500000000000000, success: true, }, ), }, ] ``` [^1]: ConsumerContractAddress