Boundless CLI

boundless-cli is a command-line interface for interacting with the Boundless Market, specifically designed to help handle deposits, withdrawing, staking and submitting proof requests.

boundless-cli [GLOBAL OPTIONS] <COMMAND> [COMMAND OPTIONS]

Global Options

You pass these before specifying a command:

Option	Description
`-r, --rpc-url <RPC_URL>`	Ethereum RPC endpoint URL. Defaults to `http://localhost:8545`.
`--private-key <PRIVATE_KEY>`	A private key string (hex-encoded); used to sign transactions.
`-b, --boundless-market-address <ADDR>`	Address of the Boundless Market contract.
`-v, --verifier-address <ADDR>`	Address of the Verifier contract.
`-s, --set-verifier-address <ADDR>`	Address of the SetVerifier contract.
`--tx-timeout <SECONDS>`	Transaction timeout in seconds. If set, the CLI will wait up to this duration for mining.
`-h, --help`	Print help.
`-V, --version`	Print version.

Commands

Command	Description
`account`	Account management commands
`request`	Proof request commands
`proving`	Proof execution commands
`ops`	Operations on the boundless market
`config`	Display configuration and environment variables

Example:

boundless-cli \
  --rpc-url http://localhost:8545 \
  --private-key 0xabcdef... \
  --boundless-market-address 0x1234... \
  --verifier-address 0x5678... \
  --set-verifier-address 0x5679... \
  account deposit 1.5

Alternatively, you can set the environment variables RPC_URL, PRIVATE_KEY, BOUNDLESS_MARKET_ADDRESS, VERIFIER_ADDRESS, SET_VERIFIER_ADDRESS and ORDER_STREAM_URL to avoid passing them each time. The environment variables BOUNDLESS_MARKET_ADDRESS, VERIFIER_ADDRESS, SET_VERIFIER_ADDRESS and ORDER_STREAM_URL can be also set by running:

source <(just env testnet)

or, if running a local devnet, with

source <(just env devnet)

This will set the environment variables to the correct values for the testnet or devnet.

Configuration check

To make sure everything is set up correctly, you can run the following command:

boundless-cli config

This will display the current configuration, including the RPC URL, private key, Boundless Market address, Verifier address, and SetVerifier address. This is useful for verifying that the CLI is correctly configured to interact with the Boundless Market and the Ethereum network.

Subcommands

Below is a command-by-command summary. Each command is run in the form:

boundless-cli [GLOBAL OPTIONS] <COMMAND> [COMMAND OPTIONS]

1. Account subcommands

The account subcommand is used to manage your account on the Boundless Market. It allows you to deposit and withdraw Ether, check your balance, and manage your stake.

1. deposit

Deposits Ether (converted to an ERC-20 balance) into the Boundless Market.

Syntax:

account deposit <amount>

Where <amount> is an amount of Ether to deposit, e.g. 1.5.

Example:

boundless-cli account deposit 1

This deposits 1 ETH from your wallet into the Boundless Market contract.

2. withdraw

Withdraws Ether from the Boundless Market back into your externally owned account (EOA).

Syntax:

account withdraw <amount>

Example:

boundless-cli account withdraw 1

This withdraws 1 ETH of your in-market balance back to your wallet.

3. balance

Checks the current in-market ETH balance for a given address (defaults to your address if not specified).

Syntax:

account balance [address]

[address] (optional) — The address to check. If omitted, uses the caller’s address.

Example:

boundless-cli account balance 0xabc123...
boundless-cli account balance

4. deposit-stake

Deposits HP (hit points) into the market as a stake. (HP is used for trust/staking in Boundless.)

Syntax:

account deposit-stake <amount>

Example:

boundless-cli account deposit-stake 100

This deposits 100 HP into your staked balance.

5. withdraw-stake

Withdraws staked HP from the market.

Syntax:

account withdraw-stake <amount>

Example:

boundless-cli account withdraw-stake 50

6. stake-balance

Checks the current staked HP balance for a given address (defaults to your address if none given).

Syntax:

account stake-balance [address]

Example:

boundless-cli account stake-balance 0xabc123...
boundless-cli account stake-balance

2. Request subcommands

The request subcommand is used to manage proof requests on the Boundless Market. It allows you to create, submit, and manage proof requests.

1. submit-offer

Constructs and submits a proof request by reading a YAML offer definition, plus specifying guest ELF, input data, and additional requirements on the command line. This is effectively a “shortcut” for quickly submitting a structured request.

Syntax (excerpt of key options):

request submit-offer [OPTIONS] <YAML_OFFER> [ID] [--wait] [--offchain] [--no-preflight]
             --elf <PATH_TO_ELF>
             --input <STRING> OR --input-file <PATH>
             [--encode-input]
             [--inline-input]
             [--journal-digest <HEX> | --journal-prefix <STRING>]
             [--callback-address <ADDRESS> --callback-gas-limit <NUM>]

yaml_offer: path to a YAML file describing the Offer.
id: optional integer ID to assign to the request.
--elf <PATH>: path to the ELF guest image to run.
--input <STRING> or --input-file <PATH>: data to feed the guest image.
--encode-input: if used, the input is encoded with risc0_zkvm::serde.
--inline-input: if used, the input is pushed onchain rather than stored offchain.
--journal-digest <HEX>: require the guest’s journal to match this digest.
--journal-prefix <STRING>: require the guest’s journal to start with these bytes.
--callback-address <ADDRESS> --callback-gas-limit <NUM>: optional callback triggered upon proof success.
--wait: block until the proof request is fulfilled (or expires).
--offchain: submit the request offchain to an order-stream server (requires --order-stream-url).
--no-preflight: skip local “dry-run” execution of the guest.
--proof-type <PROOF_TYPE>: specify the proof type to request. This is a string that indicates the type of proof you want to generate for the request.
- any: Any proof type
- groth16: Groth16 proof type
- inclusion: Inclusion proof type

Example:

boundless-cli request submit-offer offer.yaml --elf guest.wasm \
  --input-file data.bin --journal-prefix "ABCDEF" --wait

Submits a request reading the YAML from offer.yaml, providing guest.wasm as the ELF, data.bin as input, and requiring the journal to start with “ABCDEF”. It waits for fulfillment.

2. submit

Submits a proof request from a single YAML file containing the entire ProofRequest structure. Allows offchain or onchain submission, plus optional local preflight.

Syntax:

request submit [OPTIONS] <YAML_REQUEST> [ID] [--wait] [--offchain] [--no-preflight]

yaml_request: path to a YAML file describing a ProofRequest.
id: optional integer ID for the request (otherwise generated or from the YAML itself).
--wait: wait for fulfillment.
--offchain: submit to an order-stream server (requires --order-stream-url).
--no-preflight: skip local “dry-run” execution.
--callback-address <ADDRESS> --callback-gas-limit <NUM>: optional callback triggered upon proof success.
--proof-type <PROOF_TYPE>: specify the proof type to request. This is a string that indicates the type of proof you want to generate for the request.
- any: Any proof type
- groth16: Groth16 proof type
- inclusion: Inclusion proof type

Example:

boundless-cli request submit ./request.yaml --wait

3. status

Shows the request status and whether it’s open, locked, fulfilled, or expired.

Syntax:

request status <REQUEST_ID> [expires_at]

expires_at: optional expiration timestamp (UNIX time). If omitted, uses the request’s known end time.

Example:

boundless-cli request status 0x5...

4. get-proof

Retrieves the final journal and seal from onchain storage for a given request ID (once fulfilled).

Syntax:

request get-proof <REQUEST_ID>

Example:

boundless-cli request get-proof 0x5...

11. verify-proof

Verifies a proof for a given request ID on the local side, checking the onchain journal and seal with the chosen image ID.

Syntax:

request verify-proof <REQUEST_ID> <IMAGE_ID>

Where <IMAGE_ID> is a 32-byte hex digest identifying the guest code.

Example:

boundless-cli request verify-proof 0x5... 0x0002f87ec0...

3. Proving subcommands

The proving subcommand is used to execute guest code locally and generate proofs for specific requests.

Note: The proving subcommands are not equivalent to running a bento prover.

1. execute

Locally executes (without proving) the given request’s guest code, either from a YAML file or fetching from chain/offchain. Allows checking correctness prior to submission.

Syntax:

proving execute [--request-path <PATH> | --request-id <U256> [--tx-hash <HASH>] [--request-digest <B256>]]
        [--order-stream-url <URL>]

--request-path: path to a YAML file containing the request.
--request-id: the proof request identifier.
--request-digest: request’s EIP712 digest (optional).
--tx-hash: transaction hash (optional, to find the request).
--order-stream-url: fetch request data from an offchain server.

Examples:

Execute from local YAML:

boundless-cli proving execute --request-path ./request.yaml

Execute from onchain (specifying the request ID):

boundless-cli proving execute --request-id 0x5... --tx-hash 0xabc...

2. fulfill

Generates a valid proof locally, then publishes the fulfillment onchain. This subcommand uses the RISC Zero default prover.

Syntax:

proving fulfill --request-id <U256> [--request-digest <B256>] [--tx-hash <B256>]
        [--order-stream-url <URL>]

--request-id: the proof request identifier.
--request-digest: request’s EIP712 digest (optional).
--tx-hash: transaction hash (optional, to find the request).
--order-stream-url: fetch request data from an offchain server.

Example:

boundless-cli proving fulfill --request-id 0x5...

4. Ops subcommands

The ops subcommand is used to manage operations on the Boundless Market. Currently, it only supports slashing expired orders.

1. slash

Slashes a prover for failing to meet obligations for a given request ID. Only the request’s buyer can slash.

Syntax:

ops slash <REQUEST_ID>

Example:

boundless-cli ops slash 0x5...