Use Randcast CLI
Randcast users can leverage our Randcast 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.
Prerequisites
Smart Contract development experience in Solidity
Experience with Foundry Solidity development toolkit
Installation
(Recommended) Install from Docker image
docker pull arpachainio/user-shell:latest
(Optional) Build from the codebase
Usage
docker run -it -v <WORK_DIR>:/data ghcr.io/arpa-network/user-shell:latest "user-shell -c /data/user_config.yml -H /data/user-shell.history"
create a <WORK_DIR> as the directory for Randcast CLI on your host, e.g. /home/ubuntu/randcast-cli
prepare a
user_config.yml
under <WORK_DIR> of your host. Please see the 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".
Steps
Note: Always use [COMMAND] -h
to get help.
Create a subscription:
ARPA User CLI〉send cs <CHAIN_ID>
Get subscriptions(<SUB_ID>):
ARPA User CLI〉randcast mss <CHAIN_ID>
my subscriptions: [
1,
]
Write and deploy a consumer contract. Here we use forge
from Foundry
to complete this step.
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)
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
Transaction hash: 0xbf63e615506fb89fee3fd53a04f09335eafcb826b7283d2997db86eb7fa852c0
Bind the consumer contract to the subscription:
ARPA User CLI〉send add-consumer <CHAIN_ID> <SUB_ID> <CONSUMER_CONTRACT_ADDRESS>
Check a specific subscription to make sure that a consumer contract has been added:
ARPA User CLI〉randcast s <CHAIN_ID> <SUB_ID>
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:
ARPA User CLI〉randcast estimate-callback-gas <CHAIN_ID> <CONSUMER_CONTRACT_ADDRESS> <USER_ADDRESS> "getRandomNumber()" ""
estimate_callback_gas_limit_res: 97191
ARPA User CLI〉randcast estimate-payment-amount <CHAIN_ID> 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:
ARPA User CLI〉send fs <CHAIN_ID> <SUB_ID> 3000000000000000
Fund subscription successfully, transaction hash: 0x1301eb5d3751aaed2fe224ed96f6fa31a210d55a05e0e759eb34a4cd577398cb
The subscription should be ready to use now, double-check it:
ARPA User CLI〉randcast s <CHAIN_ID> <SUB_ID>
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):
cast
from Foundry
(note that --rpc-url
is needed unless you are using a local chain):(Reference: cast send)
cast send <CONSUMER_CONTRACT_ADDRESS> "getRandomNumber()" --rpc-url <RPC_URL> --private-key <USER_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,
},
),
},
]
Last updated