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.

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
Deployed to: 0x712516e61C8B383dF4A63CFe83d7701Bce54B03e
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):

(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,
          },
      ),
  },
]