qorollup — the operator CLI
qorollup is the command line for creating, operating, and monitoring rollups
on the QoreChain network. It is a thin, friendly wrapper over
@qorechain/rdk: every command
maps to a documented library call, so anything the CLI does you can also do in
code.
Install
npm i -g @qorechain/rdk-cli
# or run it without installing:
npx @qorechain/rdk-cli doctor
The package ships the qorollup binary and targets Node.js 20+.
Configure
qorollup reads endpoints and signing material from flags or QORE_*
environment variables. Flags always win over environment variables.
export QORE_NETWORK=testnet # or mainnet (default: testnet)
export QORE_REST_URL=https://rest... # REST (LCD) — reads
export QORE_RPC_URL=https://rpc... # consensus RPC — signing/broadcast
export QORE_EVM_RPC_URL=https://evm... # EVM + qor_ JSON-RPC
export QORE_MNEMONIC="word word ..." # signer (mnemonic)
# or, instead of a mnemonic:
export QORE_OPERATOR_PRIVATE_KEY_HEX=0x... # signer (raw hex key)
export QORE_GAS_PRICE=0.15uqor # gas price for "auto" fees (chain fee floor: 0.1uqor/gas)
export QORE_FAUCET_URL=https://faucet... # testnet faucet endpoint (no fixed default)
The default endpoints point at localhost, so set QORE_REST_URL (and, for
signing, QORE_RPC_URL) — or pass --rest/--rpc — to talk to a real node.
Global flags
| Flag | Meaning |
|---|---|
--network testnet|mainnet | Target network. Default testnet. |
--rest <url> | REST (LCD) endpoint override (or QORE_REST_URL). |
--rpc <url> | Consensus RPC endpoint, used for signing (or QORE_RPC_URL). |
--evm-rpc <url> | EVM / qor_ JSON-RPC endpoint (or QORE_EVM_RPC_URL). |
--mnemonic <value> | Signer mnemonic (or QORE_MNEMONIC). |
--key <hex> | Signer raw hex key (or QORE_OPERATOR_PRIVATE_KEY_HEX). |
--profile <name> | defi, gaming, nft, enterprise, or custom. |
--json | Machine-readable JSON output. |
-y, --yes | Skip confirmation prompts. |
-h, --help | Show help. |
-v, --version | Print the version. |
Read commands (status, watch, params, suggest, advise, receipt,
watchtower, doctor) need only a REST endpoint (the advise and watchtower
commands also use the EVM / qor_ JSON-RPC endpoint for their reads). Anything
that broadcasts a transaction (create, pause, resume, stop, withdraw)
signs hybrid (ML-DSA-87 + secp256k1) from 0.7.1, with the post-quantum key from
--mnemonic / QORE_MNEMONIC or --pqc-seed / QORE_PQC_SEED_HEX, and
also needs a signer and an RPC endpoint.
Commands
doctor
Run preflight checks before you create or operate a rollup: REST reachable,
network as expected, module parameters readable, config valid (when a
--profile is given), a signer configured, and the operator balance covering
the stake plus a fee buffer. Each check prints ok, warn, or fail with a
hint. Exit code is 0 only when nothing failed (warnings are allowed).
qorollup doctor
qorollup doctor --profile defi --rest https://api-testnet.qore.host
qorollup doctor --json
This is the checkPreflight library call. See the
zero-to-rollup guide.
create
Create a rollup from a preset profile. The command validates the config against
the compatibility matrix, reads live module parameters, prints the stake and the
amount burned on creation, asks for confirmation, then broadcasts
MsgCreateRollup. The signer's address is the creator.
The rollup id is checked against the chain's id grammar first
(^[a-z0-9][a-z0-9._-]{2,63}$, enforced from chain v3.2.2). The chain only
checks it at creation, after the fee is paid, so an id it would refuse stops
here with nothing spent.
qorollup create --rollup-id my-roll --profile defi
qorollup create --rollup-id my-roll --profile defi --stake-uqor 12000000000
qorollup create --rollup-id my-roll --profile defi -y
| Flag | Meaning |
|---|---|
--rollup-id <id> | Required. The rollup id. |
--profile <name> | Preset profile. Default defi. |
--stake-uqor <amount> | Stake in uqor. Default: the live minStakeForRollup. |
--dry-run | Validate and price the rollup, then run the create flow against an offline mock — no broadcast. |
--dry-run exercises the full create path without a node, using the in-library
MockTxClient. Use it to confirm your config and cost before spending anything:
qorollup create --rollup-id my-roll --profile defi --dry-run
# Dry run OK — would submit MsgCreateRollup (no broadcast).
status
Show a rollup's status, profile, settlement mode, DA backend, VM, and a
consolidated health read (latest batch, its age, and — for optimistic batches —
the challenge window, measured the way the chain measures it). From chain v3.2.5,
when the latest batch's window has passed but an earlier batch is still
submitted or challenged, it prints finality held back: batches finalize in
order.
qorollup status my-roll
qorollup status my-roll --json
For a batch submitted before chain v3.2.4 the window is a block count, and
status says so:
latest batch #7 (submitted), age 120 blocks
challenge window closes in 100680 blocks (after height 4006807)
From v3.2.4 it is measured in seconds of block time from the recorded submission time, and printed as seconds with the closing time.
This combines rest.getRollup and getRollupHealth. See
Monitoring.
watch
Poll a rollup's health on an interval and print each snapshot until you press Ctrl-C.
qorollup watch my-roll
qorollup watch my-roll --interval 2000
| Flag | Meaning |
|---|---|
--interval <ms> | Poll interval in milliseconds. Default 5000. |
This is the watchRollup helper.
params
Print the live module parameters: max rollups, min stake, creation burn rate, default challenge window, max DA blob size, blob retention, and max batches per block.
qorollup params
qorollup params --json
suggest
Ask the QCAI-assisted advisory for a starting profile, given a plain-language
description of your app. Falls back to defi when the advisory is unavailable.
qorollup suggest "high-frequency DeFi DEX"
# Suggested profile: defi (source: advisory)
advise
Print the QCAI Rollup Copilot's aggregated advice for a rollup: a live fee estimate, network recommendations, fraud investigations referencing the rollup, the reinforcement-learning agent status, and plain-language suggestions. It is best-effort — unreachable advisory services degrade to warnings rather than failing the command.
qorollup advise my-roll
qorollup advise my-roll --json
This is the getRollupAdvice library call. See the
QCAI Rollup Copilot guide.
receipt
Build a quantum-safe settlement receipt for a batch — a portable record that the
batch was anchored to the Main Chain under an ML-DSA-87 (Dilithium-5) signature.
Optionally verify it inline or write it to a file. --verify checks the receipt
against live chain state (a receipt on its own is a claim, not evidence).
qorollup receipt my-roll 7 # build and print the receipt
qorollup receipt my-roll 7 --verify # build, then verify it
qorollup receipt my-roll 7 --out receipt.json
| Flag | Meaning |
|---|---|
--verify | Verify the receipt after building it. |
--out <file> | Write the receipt JSON to a file (otherwise printed). |
Note what --verify does and does not do: it verifies the receipt this
command just built from chain. It is a self-check on your own output, not a way
to check a receipt you were given.
receipt verify
Verify a receipt somebody handed you against live chain state — the relying-party path. Use this when an operator, counterparty, or exchange gives you a receipt file and you have to decide whether to believe it. It never rebuilds the receipt, so what gets checked is exactly what was presented to you.
qorollup receipt verify receipt.json # verify a receipt you received
cat receipt.json | qorollup receipt verify - # ... or from stdin
qorollup receipt verify receipt.json --json # machine-readable result
Each check is reported individually, so a failure tells you which claim did not hold:
Receipt claims — my-roll batch #7
layer: layer-main @ height 8891
state root: 98d658fb…
creator: qor1…
checked on: mainnet
PASS rollup belongs to the receipt's layer
PASS chain's batch carries the receipt's state root
PASS a matching anchor exists on chain (heights, time, validator set, tx count, proof)
PASS creator matches the chain and has a registered key
PASS receipt names the network that was queried
PASS quantum-safe anchor signature verifies
✓ Receipt is genuine on mainnet: the rollup and its layer, the batch's state
root, the anchor (state root, layer and Main Chain heights, anchor time,
validator set, transaction count, proof, signature), the creator and the
network all match live chain state, and the signature verifies under the
creator's registered key. Your trust anchor is the node you queried.
With --json the output is { valid, receipt, verification }, where receipt
is the receipt as read from the chain (or null when it did not verify),
never the file's own copy: a relying party reading the JSON gets chain facts
only. A receipt with an unknown version or algorithm is refused before the
chain is queried.
The exit code is 0 only when the receipt is genuine, so this is safe to use in
a script or a CI gate. A malformed or truncated file is reported as such (naming
the missing fields) rather than as a verification failure, so you can tell "this
file is broken" from "this receipt is a lie".
Point --network (or --rest) at a node you trust: verification is only as
good as the endpoint you query.
These wrap buildSettlementReceipt and verifySettlementReceipt. See
Quantum-safe settlement receipts.
watchtower
Run the auto-challenger framework for an optimistic rollup: follow its batches,
print each new batch and its challenge-window deadline, until you press Ctrl-C.
With --canonical it also checks each batch against the chain's own fraud rule
(its state root must be the canonical transition root of its inputs) and reports
any batch a challenge would win. It reports; to challenge automatically, wire
transitionRootValidator and fraudProofForBatch into watchBatches in code.
qorollup watchtower my-roll
qorollup watchtower my-roll --canonical
This is the watchBatches helper. See the Watchtower guide.
pause / resume / stop
Lifecycle transitions for a rollup you created. The CLI reads the current status,
guards the transition (you cannot resume an active rollup or pause a
stopped one), confirms, then broadcasts. Creator only.
qorollup pause my-roll --reason "maintenance"
qorollup resume my-roll
qorollup stop my-roll -y
| Flag | Meaning |
|---|---|
--reason <text> | Optional reason, attached to pause. |
keygen
Generate a new operator key — a mnemonic and its derived qor1… address. The
mnemonic is printed once; store it securely and offline.
qorollup keygen
qorollup keygen --json
This wraps generateMnemonic + deriveNativeAccount. See
Keys & funding.
manifest export / manifest import
A rollup manifest is a portable JSON snapshot of a rollup's resolved config, target network, endpoints, and key addresses — save it, commit it, share it, and load it back.
# Write a manifest for a profile-derived config.
qorollup manifest export --rollup-id my-roll --profile defi --out rollup.manifest.json
# Load a manifest and validate it.
qorollup manifest import rollup.manifest.json
| Flag | Meaning |
|---|---|
--rollup-id <id> | Required for export. |
--profile <name> | Profile for export. Default defi. |
--out <file> | Write export output to a file (otherwise printed). |
export is toManifest; import is parseManifest + fromManifest. See
Local & dry-run testing.
withdraw
Build a withdrawal proof exactly as the chain does and submit
MsgExecuteWithdrawal. The withdrawal spec is a JSON file.
qorollup withdraw --file withdrawal.json
qorollup withdraw --file withdrawal.json --dry-run
| Flag | Meaning |
|---|---|
--file <json> | Required. The withdrawal spec (see below). |
--dry-run | Build the proof and report it without broadcasting. |
The spec lists the batch's withdrawals in index order and the one to execute:
{
"rollupId": "my-roll",
"batchIndex": 7,
"index": 1,
"withdrawals": [
{ "recipient": "qor1…", "denom": "uqor", "amount": "1500000" },
{ "recipient": "qor1…", "denom": "uqor", "amount": "2000000" }
]
}
It reads the batch to use the leaf encoding the chain judges it by (v2 for a
batch from chain v3.2.5), and refuses, before paying any fee, a proof whose
root is not the batch's withdrawals_root. A spec with leaves (hex leaf
hashes in the chain's encoding) plus recipient, denom and amount is still
accepted. See Withdrawals.
faucet
Request testnet funds for an address from a configured faucet. The network does
not publish a fixed faucet endpoint, so you must supply one via QORE_FAUCET_URL
or --faucet-url; without it the command fails with a clear message.
export QORE_FAUCET_URL=https://faucet.testnet.example
qorollup faucet qor1youraddress...
This is the requestFaucet helper. See Keys & funding.
Exit codes
0 on success, 1 on a failed check, validation error, cancelled prompt, or a
non-zero transaction code. With --json, the same status is reflected in the
emitted object.