# 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*](/randcast/getting-started/use-solidity-development-tools.md)*.* ### 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 --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.arpanetwork.io/randcast/getting-started/use-randcast-cli.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.