Skip to main content

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​

FlagMeaning
--network testnet|mainnetTarget 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.
--jsonMachine-readable JSON output.
-y, --yesSkip confirmation prompts.
-h, --helpShow help.
-v, --versionPrint 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
FlagMeaning
--rollup-id <id>Required. The rollup id.
--profile <name>Preset profile. Default defi.
--stake-uqor <amount>Stake in uqor. Default: the live minStakeForRollup.
--dry-runValidate 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).

See Local & dry-run testing.

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
FlagMeaning
--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
FlagMeaning
--verifyVerify 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
FlagMeaning
--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
FlagMeaning
--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
FlagMeaning
--file <json>Required. The withdrawal spec (see below).
--dry-runBuild 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.