Deploying a Rollup
You can set up an application-specific rollup three ways: through the Dashboard (a request form, not an on-chain transaction), through the chain CLI (qorechaind, full control over the on-chain transaction), or with the TypeScript RDK (@qorechain/rdk plus the create-qorechain-rollup scaffolder), which covers configuration, reads and, when you give it a post-quantum key, hybrid-signed transactions (see RDK 0.8.0: changes and limits). This page covers all three, plus the operator lifecycle and batch commands.
No rollup has been created on mainnet (GET /qorechain/rdk/v1/rollups returned an empty list on 12 November 2026); the testnet was last checked on 30 October 2026, when it held none. The commands below use the qorechain-diana testnet (EVM chain ID 9800, chain version v3.2.8: v3.2.4 was applied there on 19 October 2026, v3.2.5 on 26 October at height 8,890,800, v3.2.6 on 27 October at height 8,970,638, v3.2.7 on 6 November at height 9,594,600 and v3.2.8 on 12 November at height 9,929,500; v3.2.8 is not on mainnet). Mainnet (qorechain-vladi, EVM chain ID 9801, live since 7 June 2026) runs chain version v3.2.7 since 12 November 2026 (applied at height 4,164,600 by governance proposal 16; v3.2.6 was applied at height 4,020,000 on 4 November 2026 by proposal 15; v3.2.5 was applied at height 3,906,833 on 29 October 2026 by proposal 14 and v3.2.4 at height 3,742,566 on 23 October 2026 by proposal 13), so what v3.2.5 changes for rollups is marked "from v3.2.5" and applies on both networks (a summary table is in the Rollups Overview). Earlier releases differ in a few details, which this page marks "from v3.2.4". The testnet is a staging network with its own module parameters (for example a default challenge window of 3,600 seconds against 604,800 on mainnet, and 200 rollups at most against 100); read GET /qorechain/rdk/v1/params on the network you target. Validate every deployment on testnet first.
The network enforces a minimum gas price of 0.1uqor, so a bare --fees 500uqor is refused, and every native-lane transaction needs the hybrid post-quantum co-signature. The CLI samples on this page therefore build the transaction with --generate-only and cosign it with qorechaind tx pqc cosign, which signs and broadcasts it (create the key once with qorechaind tx pqc gen-key, and register it on-chain once with qorechaind tx pqc register-key, or through QoreX or the SDK, which do it for you). The fee is fixed when the unsigned file is generated, so set the gas limit and the fee together: the fee must be at least the gas limit × 0.1 uqor. Gas limits below are indicative — simulate before you rely on them. See First Transaction and Post-Quantum Signing.
Requirements
| Requirement | Details |
|---|---|
| Minimum stake | At least 10,000 QOR (min_stake_for_rollup); the stake is escrowed when the rollup is created |
| Creation burn | 1 % of the stake you supply is permanently burned on creation (a creation that cannot apply the burn is refused); the remainder is held in escrow and returned when the rollup is stopped |
| Layer registration stake | Creation also registers the rollup's layer in the multilayer module, which locks a further 1,000 QOR (min_sidechain_stake) from the creator, returned when the layer is decommissioned on stop. If the layer cannot be registered (balance too low, or the multilayer sidechain limit of 10 is reached) the rollup is still created but has no layer, so its batches cannot be anchored |
| Rollup id | Use 3–64 characters: lower-case letters, digits, ., _ and -, starting with a letter or digit. The chain enforces this rule on both networks since v3.2.2 (the CLI checks it before it builds the transaction), so a non-conforming id is refused |
| Account | A funded QoreChain account with a registered post-quantum key, with enough balance for the stake, the layer stake and transaction fees |
Query the live module parameters for the current minimum stake and burn rate before deploying:
qorechaind query rdk config
Deploy via the Dashboard (Tools → Rollups)
The Dashboard has a Deploy a Rollup form under Tools → Rollups. It is a request form: submitting it records a provisioning request for your account, reviewed by The Qore Trust, and a new request shows a provisioning status. It does not broadcast an on-chain create-rollup transaction — to register a rollup on-chain, use the CLI below.
Steps
- Sign in. The form requires an authenticated session to submit a request and to list your existing requests.
- Name your rollup. Enter a rollup name (2–41 characters: letters, numbers, spaces, hyphens, or underscores).
- Pick a virtual machine. The on-chain record stores a VM label. Your rollup executes off-chain in its own runtime; the choice does not run on QoreChain's own EVM, QoreChain Native or SVM lanes:
- EVM — Solidity / Vyper contracts with full Ethereum tooling (Hardhat, Foundry, MetaMask)
- QoreChain Native — Rust smart contracts on the Cosmos SDK runtime (the CosmWasm runtime), with native IBC
- SVM — the Solana Virtual Machine, for parallel-execution, high-throughput apps
- Choose a data-availability layer. Where your rollup publishes transaction data so anyone can reconstruct state: QoreChain DA, Celestia, or EigenDA. Note that EigenDA is a Dashboard-level option, whereas the on-chain
x/rdkDA backends are native, Celestia, or both — see Data Availability. - Set a gas token. The token used to pay for execution on your rollup. Defaults to QOR; enter a custom symbol to use your own native token.
- Choose a sequencer. Who orders transactions before settlement: Shared sequencer (the QoreChain shared set), Dedicated (single) (run your own single sequencer), or Decentralized (a permissionless sequencer set).
- Choose a settlement target. Where the rollup anchors its state roots and validity proofs: QoreChain mainnet or Ethereum.
- Submit the request. Provisioning is reviewed by The Qore Trust, so a freshly submitted request appears with a provisioning status until review completes.
Your submitted requests appear in the Your rollups list with their VM, DA layer, gas token, sequencer, settlement target, and current status.
The form's options (virtual machine, data-availability layer, gas token, sequencer, settlement target) describe what you are asking for; they are broader than what the on-chain x/rdk module currently supports. On-chain, data availability is native (Celestia is not active), and sequencing is by the rollup creator or a configured sequencer address. See Data Availability.
Deploy via the CLI
The CLI creates the rollup directly on-chain. create-rollup takes three positional arguments — the rollup ID, a profile, and the stake amount (in uqor) — plus an optional --vm flag.
Since chain version v3.1.74, create-rollup applies the chosen profile's preset automatically — settlement mode, sequencer, DA, gas model, and VM are all taken from the preset. You no longer need to set them by hand (previously the message hardcoded a sovereign configuration). The --vm flag now defaults to empty, so the profile's VM applies unless you explicitly override it.
qorechaind tx rdk create-rollup [rollup-id] [profile] [stake-amount] \
--from mykey \
--chain-id qorechain-diana \
--gas 600000 --fees 60000uqor \
--generate-only > create-rollup.json
Example — create a rollup from the defi preset (settlement, sequencer, DA, and VM all come from the preset; defi resolves to zk settlement on the EVM). Build the unsigned transaction, then attach the post-quantum co-signature and broadcast:
# 1. Build the unsigned transaction (10,000 QOR stake)
qorechaind tx rdk create-rollup my-defi-rollup defi 10000000000 \
--from mykey \
--chain-id qorechain-diana \
--gas 600000 --fees 60000uqor \
--generate-only > create-rollup.json
# 2. Cosign with your post-quantum key and broadcast
qorechaind tx pqc cosign create-rollup.json \
--from mykey --pqc-key mypqckey --chain-id qorechain-diana
Do not create a defi (ZK) rollup on mainnet yet. The chain accepts the creation and escrows the stake. The verification-key messages are enabled on mainnet since chain v3.2.7 (12 November 2026) and were accepted on the testnet, but RDK 0.8.0 has no builder for them and no ZK rollup has been tried on either network. Choose an optimistic profile such as nft or custom for now (see ZK / STARK & Withdrawals).
Flags:
| Flag | Default | Description |
|---|---|---|
--vm | (empty — use the profile's VM) | Override the rollup VM type: evm, cosmwasm, svm, or custom. Leave unset to apply the preset's VM. (In the RDK clients the Wasm runtime is the native VM type — QoreChain Native — with cosmwasm kept as a legacy alias; cosmwasm is the on-wire value, which is what this chain-level flag takes.) |
--vm records which runtime your rollup uses. The host chain only settles the rollup; it does not execute its contracts. The host chain's own QoreChain Native upload is currently closed and its SVM transaction lane is disabled network-wide, which does not affect settlement of an off-chain rollup but does mean you cannot deploy contracts for a rollup onto those host-chain lanes.
The [profile] argument selects a preset configuration that is applied automatically — see Preset Profiles. The [stake-amount] is the bond in uqor; the creation burn is 1 % of it.
Inspect what you deployed
# Query a specific rollup by ID
qorechaind query rdk rollup my-defi-rollup
# List all registered rollups
qorechaind query rdk list-rollups
Deploy with the TypeScript RDK (@qorechain/rdk)
The Rollup Development Kit ships as two public npm packages for the same on-chain x/rdk module as the CLI. No rollup exists on either network yet, so no transaction path of the kit has been exercised on a live rollup; read RDK 0.8.0: changes and limits before you rely on it to send transactions:
@qorechain/rdk(v0.9.0) — the TypeScript SDK: a config builder with preset profiles, transaction helpers for the rollup and settlement-batch lifecycles, native DA, typed read clients, settlement receipts with an ML-DSA-87 signature, the QCAI Rollup Copilot, cross-VM calldata helpers, and the watchtower. It depends on@qorechain/sdk^0.10.0(from 0.7.0; 0.6.x used^0.9.0) and@qorechain/evm^0.8.0.create-qorechain-rollup(v0.9.0) — a scaffolder that clones one runnable starter template per profile (including themultivm-rolluptemplate).
These are published to npm. The repo also ships a published operator CLI, @qorechain/rdk-cli (qorollup, v0.9.0), with doctor, create, status, watch, params, suggest, lifecycle (pause/resume/stop), keygen, manifest, withdraw, and faucet commands, plus the receipt, advise, and watchtower commands. Since 0.7.1 its transaction commands sign hybrid (see the limits below).
Highlights by release:
- v0.4.2 — works against the live network out of the box. The
mainnetandtestnetpresets now ship the publicqore.hostendpoints (REST atapi.qore.host/api-testnet.qore.host), socreateRdkClient({ network })reaches the chain with no manualendpoints— override only to target your own node. The same release renamed the Wasm rollup VM identifier tonative(QoreChain Native);cosmwasmremains an accepted legacy alias, and both map tocosmwasmon the wire — the chain, explorer, and Dashboard are unchanged. - v0.4.3 — dependency bump for the SDK's hybrid-signature encoding fix. The RDK transaction client itself still signed classical-only.
- v0.4.4 — tracks
@qorechain/sdk^0.7.0, the SDK release for the chain v3.1.85 authenticator lanes. No RDK API change. - v0.5.0 (18 October 2026) — settlement-receipt verification checks against chain state and never reports a receipt valid from its own fields; the TypeScript transaction client signs hybrid when given a
pqcKeypair. It depends on@qorechain/sdk^0.8.0. - v0.6.0 (GitHub release of 20 October 2026) — the compatibility release for chain v3.2.2 to v3.2.4: anchored batches, settlement receipts that can verify, challenge windows measured as the chain measures them, an encoder that matches the chain's cross-VM layout, templates that sign hybrid, and
@qorechain/sdk^0.9.0. The details are below. - v0.6.1 (GitHub release of 25 October 2026) — a security and template fix release for chain v3.2.3 onward, in all five languages: settlement-receipt verification compares every field the receipt states with the chain's anchor, the six starter templates no longer submit batches the chain refuses (they leave
dataHashempty), and the optimistic templates publish the chain's canonical state root instead of a placeholder. It keeps the@qorechain/sdk^0.9.0and@qorechain/evm^0.8.0ranges. The details are below. - v0.6.2 (GitHub release of 27 October 2026): a CLI hotfix with no library changes:
qorollupinstalled from npm (local, global ornpx) runs again, andqorollup --versionandcreate-qorechain-rollup --versionprint their real versions. The other packages were re-released as 0.6.2 so every registry stays on one version. - v0.7.0 (GitHub release of 27 October 2026): ready for chain v3.2.5 in all five languages (both networks run it, and v3.2.6 and v3.2.7 too: mainnet applied v3.2.5 on 29 October 2026, v3.2.6 on 4 November and v3.2.7 on 12 November, the testnet v3.2.5 on 26 October and v3.2.6 on 27 October; the testnet has since moved to v3.2.7 and then v3.2.8), and it fixes how withdrawals and data-availability blobs are hashed: withdrawal proofs built with the 0.6.x defaults never verified on chain, and 0.7.0 builds the chain's exact tree. It moves to
@qorechain/sdk^0.10.0, and the templates pin@qorechain/rdk^0.7.0. The details are below. - v0.7.1 (GitHub release of 30 October 2026): a hotfix for the
qorollupoperator CLI, whose transaction commands now sign hybrid, as both networks require. - v0.8.0 (GitHub release of 30 October 2026): the Python, Go, Rust and Java clients sign hybrid too, so every RDK client can send transactions on mainnet and the testnet. Java 21 is required.
- v0.9.0 (GitHub release of 12 November 2026; current): supports chain v3.2.8 (the testnet runs it since 12 November 2026): rollup data posting, based sequencing, qledger-v1 optimistic rollups with fraud proofs, private rollups, canonical ZK inputs; STARK settlement is paused. See the release notes on GitHub. A new account must register its post-quantum key in a transaction of its own before anything else; the RDK clients 0.9.0 do that registration for you.
Published versions (checked on every registry on 12 November 2026). npm @qorechain/rdk, @qorechain/rdk-cli and create-qorechain-rollup: 0.9.0 (latest); PyPI qorechain-rdk: 0.9.0; crates.io qorechain-rdk: 0.9.0; Maven Central io.github.qorechain:qorechain-rdk: 0.9.0 (earlier versions stay available); Go module github.com/qorechain/qorechain-rdk/packages/go: v0.9.0 (the module proxy's @latest can lag a new tag, so pin @v0.9.0 explicitly). The GitHub release is v0.9.0.
RDK 0.8.0: changes and limits
This section states what the published 0.8.0 packages do (and what 0.7.1, 0.7.0, 0.6.2, 0.6.1 and 0.6.0 changed before them), checked against the package contents and the GitHub release notes, and what they still cannot do. None of these items is a chain behaviour. Where a statement says "untested live", no rollup exists on either network, so the path has only been checked against the code and offline.
What 0.8.0 and 0.7.1 changed (the 0.8.0 and 0.7.1 release notes have the full list). Both networks require a hybrid (ML-DSA-87 + secp256k1) signature on native-lane transactions.
- 0.7.1:
qorolluptransactions are accepted.create,pause,resume,stopandwithdrawsigned classical-only in 0.7.0 and earlier, so the networks refused every one of them. The CLI now signs hybrid. It resolves the post-quantum key the way the templates do: derived from--mnemonicorQORE_MNEMONICand matched against the key the chain has registered, or taken from--pqc-seedorQORE_PQC_SEED_HEXalongside--key. Without a key it refuses to send instead of paying for a refused transaction. - 0.7.1: Python parity fix.
transition_root_version_for_batch,RestClient.get_applied_plan_heightandBatchView.withdrawals_boundare now in the Python client too (the 0.6.1 notes had counted the first in all five languages; it was in four). - 0.8.0: Python, Go, Rust and Java sign hybrid. Before, only their reads worked on mainnet and the testnet. Each now signs hybrid when given a post-quantum keypair, through its own published QoreChain SDK (0.10.x), with the sign-bytes form (v1 or v2) resolved from the chain. The release notes state that every client produces transactions byte-identical to the TypeScript client for the same input (a shared fixture holds four hybrid transactions that each language reproduces exactly).
- 0.8.0: key resolution in every language, matching TypeScript: from a mnemonic, the canonical or the legacy derivation, whichever the chain has registered; or a 32-byte seed from
QORE_PQC_SEED_HEX, checked against the registered key. Pythonresolve_pqc_keypair/pqc_keypair_from_env, GoResolvePqcKeypair/PqcKeypairFromEnv, Rustresolve_pqc_keypair/pqc_keypair_from_env, JavaAccounts.resolvePqcKeypair/pqcKeypairFromEnv. - 0.8.0: Java 21 is required (it was 17), because the QoreChain Java SDK it depends on needs it.
- 0.8.0: new dependencies.
qorechain-sdk0.10.x on PyPI, the Go modulegithub.com/qorechain/qorechain-sdk/packages/gov0.10.0,qorechain-sdk0.10 on crates.io (Rust moves tocosmrs0.22) andio.github.qorechain:qorechain-sdk[0.10.0,0.11)on Maven. The templates pin@qorechain/rdk^0.8.0. - 0.8.0: Go
RdkTxClient.Signreturns([]byte, error), because hybrid signing can fail. This breaks Go code that used the old single return value. - Untested live. No rollup exists on either network, so no hybrid transaction from any client has been sent through a live rollup.
What 0.7.0 changed (all five languages, unless a line says otherwise; the release notes have the full list). Behaviour that belongs to chain v3.2.5 is labelled with its network: both networks run v3.2.5 or later (mainnet runs v3.2.7 since 12 November 2026, the testnet v3.2.8 since 12 November).
- Withdrawal proofs verify on chain. The Merkle and withdrawal helpers defaulted to SHA-256 and re-hashed each leaf, while the chain hashes nodes with SHAKE-256 and builds its leaves from the withdrawal itself, so a proof built with the 0.6.x defaults never verified.
withdrawalsTreenow builds a batch's withdrawals root and every proof exactly as the chain does (leaf position is the withdrawal index): with first-form leaves, or with second-form leaves that also name the chain id, which the chain uses for batches from v3.2.5 (both networks).withdrawalLeafV1andwithdrawalLeafV2build one leaf,assembleWithdrawalProofbuilds the chain's tree by default, and the generic Merkle helpers default to SHAKE-256. This is breaking for code that relied on the SHA-256 defaults (passhashexplicitly to keep them). The new byte formats were tested against vectors produced by the chain's own code, and every withdrawal proof in those vectors is accepted by the chain's verifier. See Leaf and node encoding. qorollup withdrawchecks before it pays. It takes the batch's withdrawals (qorollup withdraw --file withdrawal.json [--dry-run]), builds the proof under the batch's own binding, and refuses before paying a fee when the result is not the batch's on-chainwithdrawals_root.buildDaBlobcommits as the chain does. Its commitment is SHAKE-256, not SHA-256 (no transaction posts a blob, sodataHashis still left empty).- Watchtower. The Watchtower told batches apart by index only, so it missed a batch resubmitted at a rejected index. From chain v3.2.5 (both networks) an upheld fraud rejects the batch and every later unfinalized one, and the sequencer resubmits under the same indexes; the Watchtower now tells batches apart by index and state root and never validates a rejected batch. New helpers
transitionRootValidator(avalidatepredicate that applies the chain's fraud rule) andfraudProofForBatch(the proof that wins, or none for an honest batch), andqorollup watchtower --canonical, which reports the batches a challenge would win. - Chain v3.2.5 settlement helpers (both networks):
getRollupHealthreportsheldBackBywhen the latest batch could finalize on its own window but an earlier batch is still submitted or challenged (batches finalize in order), andqorollup statusprints it;stopRollupErrorand a pre-check instopRollup(TypeScript and Rust), because a rollup whose latest batch is submitted or challenged cannot be stopped;MAX_PENDING_OPTIMISTIC_BATCHES(4,096);withdrawalsRootError(a withdrawals root is empty or exactly 32 bytes), checked before every batch submission in all five languages. - Cross-VM helpers for chain v3.2.5 (both networks):
getCrossVmParams(the allowlist, at/qorechain/crossvm/v1/params),crossVmTargetReady(precompile active, bridge enabled and target allowlisted, with the blocking reason),decodeCrossVmResult(the reply isabi.encode(bytes)) anddecodeRevertReason(a refusal isError(string)), checked against encodings Solidity produced. See Multi-VM. - Error decoding and small additions.
decodeRdkTxErrorandRDK_ERRORSname therdkmodule's error codes (2 to 36) and what to do about the ones an operator meets;qorehash(SHAKE-256, 32 bytes) is exported in all five languages;FEATURE_RDK_CHALLENGE_SETTLEMENTnames the chain feature flag. - The
defitemplate stops before it wastes a fee. No chain release up to v3.2.6 can register a ZK verification key, so every ZK batch was refused there. The template now stops before sending, andRollupView.hasVerificationKeyreads a field meant for chain v3.2.7 (testnet since 6 November, mainnet since 12 November 2026); it could not be checked against a live rollup because none exists. - Dependencies.
@qorechain/sdk^0.10.0(was^0.9.0), so an application on SDK 0.10.0 now shares one SDK copy with the kit; the templates pin@qorechain/rdk^0.7.0(^0.8.0since 0.8.0).
What 0.6.2 changed (the CLI and scaffolder only; the library packages are unchanged):
qorollupruns when installed from npm. The CLI started only whenprocess.argv[1]equalled its own file path, but npm starts a package's bin through a symlink innode_modules/.bin, so 0.6.1 and earlier, installed locally, globally or run withnpx, exited with code 0 and printed nothing; onlynode .../dist/index.jsworked. 0.6.2 compares real paths. Afternpm i -g @qorechain/rdk-cli,qorollup ...works.- Versions print correctly.
qorollup --versionprinted0.4.1andcreate-qorechain-rollup --versionprinted0.2.0in earlier releases; both now read their ownpackage.json(checked on 27 October 2026:qorollup --versionprints0.6.2).
What 0.6.1 changed (all five languages, unless a line says otherwise; the release notes have the full list):
- Receipt verification compares every field.
verifySettlementReceiptnow requires every anchor field the receipt states to equal the chain's anchor (a mismatch names the field), requiresbatchStateRootto equal the chain's batch root, and refuses a receipt with an unknownversionor analgorithmother thanML-DSA-87before anything is read from the chain. The result carries the chain's matchedanchorand, when valid, averifiedReceiptrebuilt from chain state;qorollup receipt verify --jsonreturns that chain-read receipt asreceipt. See Settlement receipts. - Native data availability: leave
dataHashempty. Every rollup profile usesnativedata availability, where the chain accepts a non-emptydata_hashonly when a matching blob is stored on chain, and no transaction can store one (see Data Availability). The six starter templates put a data hash on their batches in 0.6.0 and earlier, so the chain refused every template batch after the fee was paid. They now leave it empty;SubmitBatchInput.dataHashis optional in TypeScript (omitted means empty),dataHashError(data_hash_error,DataHashError,Rules.dataHashError) exposes the rule, andRdkTxClient.submitBatchrefuses such a batch before broadcasting when it can read the rollup (a hybrid client with a REST endpoint). - Optimistic templates publish the canonical state root. The chain judges an optimistic batch by its canonical transition root, a SHAKE-256 commitment of the batch's previous state root, data hash and transaction count (
batchTransitionRootin the RDK, withtransitionRootVersionForchoosing the binding the connected network applies). Thecustom,multivmandnfttemplates used to submit a fixed placeholder root, which does not match the canonical root the chain checks; they now publish the canonical root and no longer send a placeholder proof. Thenfttemplate'schallenge.tsreads the batch from chain and challenges only a batch whose root is provably wrong. Do not hand-roll the formula: usebatchTransitionRootso the binding matches the network you submit to. The chain's own check is the same for every client, so an optimistic batch whose state root is not the canonical root can be challenged successfully, whichever client sent it. - New helpers.
fraudProof,transitionRootVersionForBatch,receiptSchemaErrorwithSUPPORTED_RECEIPT_VERSIONS,RestClient.getProtocolFeatures/isProtocolFeatureEnabled(a chain without the route reads as "not enabled") andgetAppliedPlanHeight.@qorechain/rdknow depends on@noble/hashesdirectly (SHAKE-256 for the transition root; it was already installed through@qorechain/sdk). The templates pin@qorechain/rdk^0.6.1.
What changed in 0.6.0 (TypeScript, unless a line says otherwise):
- Signing.
RdkClient.connectTx(signer, { pqcKeypair, rest })signs hybrid (secp256k1 + ML-DSA-87) when you pass a keypair; without one it signs classical-only and the networks refuse the transaction.signermust be anOfflineDirectSigner, and the fee must be explicit (afee, or agasPriceon connect). New helpersresolvePqcKeypairandpqcKeypairFromEnvderive both the canonical and the legacy ML-DSA-87 key from a mnemonic and use whichever the account has registered on-chain; they refuse, rather than guess, when the account holds a different key.QORE_PQC_SEED_HEXsupplies a seed for an operator who signs with a raw private key. The kit now depends on@qorechain/sdk^0.9.0, so a fresh install holds one SDK copy (0.9.0); with 0.5.0, npm installed SDK 0.8.3 nested under the kit. - Anchored batches.
MsgSubmitBatchcarriesanchor_signatureandvalidator_set_hash.RdkTxClient.submitBatchsigns the anchor itself only when the client signs hybrid, has a REST endpoint, and is the rollup's creator (the chain checks the anchor against the creator's registered key); in every other case it submits unanchored, as before. Passanchor: "require"to refuse instead of submitting unanchored,anchor: "off"to never sign, oranchorSignatureto send a signature you obtained yourself.anchorSignBytesForBatchbuilds the v2 bytes for a creator who signs out of band, which a rollup with a separate sequencer needs. Untested live. - Settlement receipts. The PQC account lookup uses the singular route
/qorechain/pqc/v1/account/{address}(0.5.0 used a plural path the networks do not serve). Verification supports both anchor sign-bytes forms and picks one by the anchor's height, never by trying both: v1 below the v3.2.2 switch, v2 from it. Receipt schema v2 recordschainId; verification refuses a receipt checked against a node of another chain, and reportssignBytesVersionand achainBindingcheck. Version-1 receipts still verify. See Settlement receipts. - Reads.
getLatestBatchcalls/qorechain/rdk/v1/latest_batch/{rollup_id}(0.5.0 called a form the chain does not serve), andlistBatchesfollows every page (listBatchesPagereads one).RollupViewcarriesescrowBalanceand, where the node reports them,challengeWindowSec,challengeBondandproofSystem;BatchViewcarriessubmittedTime. - Challenge windows.
batchChallengeWindowcomputes a batch's window the way the chain does and judges it against the chain tip (getChainTip), not the local clock: seconds of block time for a batch that has a recorded submission time (the v3.2.4 rule: the testnet since height 8,337,253, mainnet since height 3,742,566),window / 6blocks counted from the submission height otherwise (the rule for batches submitted before the upgrade height). The health check behindqorollup statusand the watchtower use it (see Watchtower). - Cross-VM.
encodeCrossVmCalldatanow encodesexecuteCrossVMCall(uint8,string,bytes), the layout the node decodes, and takes atargetVm.isCrossVmPrecompileActivereads the live list of active precompiles (see Multi-VM). - Rules checked before a fee is paid.
rollupIdErrorchecks the id grammar when you validate a config and beforecreateRollupbroadcasts;withdrawalErrorschecks a withdrawal beforeexecuteWithdrawalbroadcasts. - Templates. The scaffolded templates connect through
pqcKeypairFromEnv, so theircreateandsubmit-batchscripts sign hybrid, and they depended on@qorechain/rdk^0.6.0(^0.6.1since the 0.6.1 scaffolder). Themultivm-rolluptemplate checks that the precompile is live and requires a non-empty reply from the target. - Python, Go, Rust and Java. The read-side fixes above (singular PQC route,
latest_batch, anchor sign bytes v2, challenge-window rules, id and withdrawal checks) are in the published packages of the four other languages as well. - Breaking changes.
encodeCrossVmCalldatatakestargetVm, andCROSS_VM_DEFAULT_SIGNATUREchanged.RollupHealthandBatchDeadlinecarry achallengeWindowinstead of the old seconds-based deadline.
Limits that remain in 0.8.0:
-
ZK settlement has not been tried on either network. The
defiprofile, thedefi-rolluptemplate and every rollup created withzksettlement are affected: the verification-key messages are enabled on mainnet since chain v3.2.7 (12 November 2026) and on the testnet since 6 November 2026, but no ZK rollup has been created and RDK 0.8.0 has no builder for the messages. Useoptimisticsettlement for now (see ZK / STARK & Withdrawals). -
The
defitemplate's demo circuit cannot verify. It is asnarkjsmultiplier circuit, while the chain checks Groth16 over BLS12-381 with three public inputs (the previous state root, the new state root and the data hash). Even once key registration exists, a proof from the demo circuit would not pass; replace the circuit with your own state-transition circuit. -
Fixed in 0.7.0: withdrawal Merkle helpers. In 0.6.2 and earlier the helpers defaulted to SHA-256 and a proof built with the defaults never verified on chain; use
withdrawalsTree/assembleWithdrawalProoffrom 0.7.0 (see Leaf and node encoding). -
Hybrid signing needs your post-quantum key. Every client (TypeScript, the
qorollupCLI from 0.7.1, and Python, Go, Rust and Java from 0.8.0) signs hybrid only when it has a post-quantum keypair; without one a transaction is classical-only and both networks refuse it. Releases before those versions sign classical-only, so the CLI before 0.7.1 and the Python, Go, Rust and Java clients before 0.8.0 cannot send a transaction the networks accept. The Python message builders have noanchor_signatureorvalidator_set_hashfield (checked in the 0.8.0 source; not checked for the other three), so for an anchored batch from Python build and sign with the chain CLI (--generate-only, thenqorechaind tx pqc cosign) or use the TypeScript client with apqcKeypair. -
No hybrid creation of a rollup has been exercised live, because no rollup exists on either network. The same holds for anchored batches, withdrawals and the whole receipt flow.
-
Anchoring needs the creator. A batch is anchored in the same transaction only if the creator's signature is in it. If the sequencer is another address, the creator has to sign the v2 bytes out of band and the sequencer sends the result.
-
The cross-VM precompile at
0x…0901is not active on mainnet, so a call from a contract does nothing there. On the testnet it is active with an allowlist, and a call was tested witheth_callon 7 November 2026 (see Multi-VM). -
Challenge-window length. The kit reads a rollup's own window only when the node reports it (the package documents this as v3.2.4 and later, which both networks run). Otherwise it uses the module's default window; pass
challengeWindowSecsfor a rollup that configured its own. The older helperschallengeWindowDeadlineandisChallengeWindowClosedare still exported and still take seconds, so do not feed them a block height. -
Data availability. No transaction posts a blob, so a batch on a
nativeorbothrollup must leavedataHashempty (see Data Availability).buildDaBlobhashed with SHA-256 in 0.6.2 and earlier; from 0.7.0 its commitment is the chain's SHAKE-256.
Versions before 0.8.0. 0.7.0 and earlier cannot send qorollup transactions the networks accept (fixed in 0.7.1), and before 0.8.0 the Python, Go, Rust and Java clients could not send any transaction. 0.6.2 and earlier build withdrawal proofs that never verify on chain and hash buildDaBlob with SHA-256; use 0.8.0. 0.6.1 and earlier installed the qorollup CLI from npm in a state where it printed nothing and exited 0 (fixed in 0.6.2). 0.6.0 compares fewer fields in receipt verification than 0.6.1 and ships templates that submit batches the chain refuses (a data hash on a native-DA rollup, a placeholder state root on the optimistic ones). 0.5.0 and earlier should not be used for settlement receipts, the watchtower or cross-VM calldata: 0.5.0 looked up the creator's key on a route the networks do not serve (so receipt verification failed closed on every genuine receipt), rebuilt only the v1 anchor message, read a block height as a timestamp (every batch age and challenge deadline was wrong, and the watchtower raised its deadline alert at once for every batch), called a latest-batch route the chain does not serve, read only the first 50 batches, encoded a function the precompile does not decode, and shipped templates that signed classical-only. 0.4.x had no hybrid signing in the transaction client.
Python, Go, Rust, and Java clients
Alongside the TypeScript package, the RDK provides full Python, Go, Rust, and Java clients that mirror the TypeScript surface: the config builder with validation, the five preset profiles, denom/economics/bech32 utilities, binary-Merkle and withdrawal-proof helpers, rollup manifests, REST and qor_ JSON-RPC read clients, preflight/health checks, accounts (mnemonic → qor address), and, from 0.8.0, hybrid transaction signing + broadcast (ML-DSA-87 + secp256k1, as both networks require; before 0.8.0 they signed classical-only and only their reads worked — see RDK 0.8.0: changes and limits). All are verified against shared cross-language golden vectors and are published to their registries:
# Python — installs as qorechain-rdk, imports as qorrdk
pip install qorechain-rdk
# Rust
cargo add qorechain-rdk
# Go (pin the version)
go get github.com/qorechain/qorechain-rdk/packages/go@v0.9.0
# Java (Maven / Gradle)
# io.github.qorechain:qorechain-rdk:0.9.0 (needs Java 21)
import qorrdk
Current published versions, all 0.9.0 (checked 12 November 2026): Python qorechain-rdk (PyPI, import qorrdk), Go module github.com/qorechain/qorechain-rdk/packages/go (v0.9.0), Rust qorechain-rdk (crates.io) and Java io.github.qorechain:qorechain-rdk (Maven Central; Java 21 or later from 0.8.0). These clients read chain state and, from 0.8.0, send transactions signed hybrid when you give them a post-quantum keypair (see RDK 0.8.0: changes and limits).
The TypeScript RDK and its templates default to the qorechain-diana testnet, and the presets reach the live public endpoints out of the box. Pin versions and validate on testnet before mainnet.
Scaffold a project with create-qorechain-rollup
Each profile has a matching starter template (defi-rollup, gaming-rollup, nft-rollup, enterprise-rollup, custom-rollup). Scaffold one with either form:
npm create qorechain-rollup my-rollup
# or
npx create-qorechain-rollup my-rollup
For non-interactive / CI use, pass the template and network explicitly:
npx create-qorechain-rollup my-rollup --template defi-rollup --network testnet --yes
The scaffolder prints the documented stake and creation-burn cost and the next steps to create your rollup and read its status.
The templates of create-qorechain-rollup 0.9.0 depend on @qorechain/rdk ^0.9.0. Their create and submit-batch scripts connect through connectOperator() in src/signer.ts, which resolves your post-quantum key from QORE_MNEMONIC (or from QORE_PQC_SEED_HEX when you sign with QORE_OPERATOR_PRIVATE_KEY_HEX), checks it against the chain, and signs hybrid; with neither set the script warns and signs classical-only, which both networks refuse. No rollup has been created through a template on a live network, so this path is untested live. The starter's submit-batch script is a reference flow only: since 0.6.1 it leaves dataHash empty (the chain refuses a data hash on a native-DA rollup), and the optimistic templates publish the canonical state root instead of a placeholder; it still uses illustrative values for the rest, and it is not expected to finalise a batch on a live network. The defi-rollup template (ZK) stops before sending a batch from 0.7.0, because the chain would refuse it (see ZK / STARK & Withdrawals).
Build a rollup configuration from code
Build a config from a preset, read the live stake and burn rate from the chain, and produce the create message. The config builder enforces the settlement → proof compatibility matrix on validate() / build(). Submit the resulting values with the CLI above, or with the TypeScript client given a pqcKeypair — see RDK 0.8.0: changes and limits.
import { createRdkClient, presets, estimateCreationCost, uqorToQor } from "@qorechain/rdk";
// A config builder pre-filled with the defi preset's defaults; override via .set({ ... }).
const config = presets.defi({ rollupId: "my-defi-rollup" }).validate();
// The public qore.host endpoints are baked into the presets (RDK ≥ 0.4.2).
// `params()` is a REST read of /qorechain/rdk/v1/params, served on both networks.
const rdk = createRdkClient({ network: "testnet" });
// Read the live module parameters — never hardcode the stake or burn rate.
const params = await rdk.params();
const cost = estimateCreationCost({
stakeUqor: params.minStakeForRollup,
burnRate: params.rollupCreationBurnRate,
});
console.log(`Stake: ${uqorToQor(cost.stakeUqor)} QOR — burned: ${uqorToQor(cost.burnUqor)} QOR`);
// The values to pass to `qorechaind tx rdk create-rollup`.
const msg = config.toCreateMsg("<your qor address>", { stakeAmount: params.minStakeForRollup });
console.log(msg.rollupId, msg.profile, msg.vmType, msg.stakeAmount);
Not sure which profile fits? rdk.suggestProfile(...) is meant to return a QCAI-assisted recommendation; on the current public endpoints it always returns the defi fallback (source: "fallback"), so choose from the profile table.
Read state from code
The typed REST client needs no signer and reads both networks:
const rollup = await rdk.rest.getRollup("my-defi-rollup");
console.log(rollup.status, rollup.settlementMode, rollup.daBackend, rollup.vmType);
For batches, use rdk.rest.getBatch(rollupId, index) or qorechaind query rdk batch [rollup-id] (below); getLatestBatch and listBatches read the chain's latest_batch route and every page of the batch list since 0.6.0 (see RDK 0.8.0: changes and limits).
Lifecycle management
A rollup moves through pending, active, paused, and stopped states; a new rollup starts active immediately. Only the creator can pause, resume or stop it (enforced since chain version v3.2.0). Each command below follows the same two-step pattern as creation: generate the unsigned transaction, then cosign it.
Pause
Temporarily halt the rollup. State is preserved and the rollup can be resumed. A reason string is required.
qorechaind tx rdk pause-rollup [rollup-id] [reason] \
--from mykey \
--chain-id qorechain-diana \
--gas 400000 --fees 40000uqor \
--generate-only > pause.json
qorechaind tx pqc cosign pause.json --from mykey --pqc-key mypqckey --chain-id qorechain-diana
Resume
Resume a previously paused rollup.
qorechaind tx rdk resume-rollup [rollup-id] \
--from mykey \
--chain-id qorechain-diana \
--gas 400000 --fees 40000uqor \
--generate-only > resume.json
qorechaind tx pqc cosign resume.json --from mykey --pqc-key mypqckey --chain-id qorechain-diana
Stop
Permanently decommission the rollup and release its stake. The staked QOR — minus the one-time creation burn, and minus anything already paid out of the rollup's escrow by withdrawals or fraud-proof rewards — is returned to the creator: since v3.2.3 a per-rollup escrow ledger records what each rollup still holds, stop-rollup refunds exactly that balance, and a stopped rollup pays no further withdrawals. The 1,000 QOR layer-registration stake is returned separately when the rollup's layer is decommissioned.
From chain v3.2.5 (both networks): a rollup cannot be stopped while its latest batch is submitted or challenged, so settle or finalize it first; a stopped rollup frees its slot under the module's rollup limit. Before v3.2.5 neither rule applied. From TypeScript, stopRollupError and the pre-check in stopRollup tell you before you pay the fee.
qorechaind tx rdk stop-rollup [rollup-id] \
--from mykey \
--chain-id qorechain-diana \
--gas 400000 --fees 40000uqor \
--generate-only > stop.json
qorechaind tx pqc cosign stop.json --from mykey --pqc-key mypqckey --chain-id qorechain-diana
Stopping a rollup is permanent. The rollup cannot be restarted after it is stopped.
Operator commands: batches and challenges
Rollup operators submit settlement batches, and challengers can dispute optimistic batches. These commands underpin the settlement layer described in Rollups Overview and ZK / STARK & Withdrawals.
Who can submit, and in what order
- Only the rollup's configured sequencer address — or, when none is configured (every preset), its creator — may submit batches. Based and shared sequencing do not yet admit proposer sets or rosters: they are labels today, and the creator submits.
- Batches form a chain: the first batch has index
0; each later batch must use the next index and carry the previous batch's state root asprev_state_root. - A batch that carries a data hash on a
nativeorbothrollup is refused unless a matching blob is already stored (see Data Availability). A batch with no data hash is not checked. - A
zkrollup must attach a proof, and the proof must verify; no ZK batch can be accepted yet (see ZK / STARK & Withdrawals). - From chain v3.2.5 (both networks): a batch's
withdrawals_rootmust be empty or exactly 32 bytes, and a rollup holds at most 4,096 pending optimistic batches (MAX_PENDING_OPTIMISTIC_BATCHESin the RDK); batches also finalize in index order, so a later batch waits for an earlier one that is stillsubmittedorchallenged. The RDK checks the root's length before every submission. Before v3.2.5 none of these three rules applied.
Submit a batch
Submit a settlement batch for a rollup. Takes the rollup ID, a batch index, and a hex-encoded state root. For every batch after the first, pass the previous batch's state root as --prev-state-root.
qorechaind tx rdk submit-batch [rollup-id] [batch-index] [state-root-hex] \
--prev-state-root <previous-state-root-hex> --tx-count 120 \
--from mykey \
--chain-id qorechain-diana \
--gas 400000 --fees 40000uqor \
--generate-only > batch.json
qorechaind tx pqc cosign batch.json --from mykey --pqc-key mypqckey --chain-id qorechain-diana
| Flag | Description |
|---|---|
--prev-state-root | Hex state root the batch starts from (required for every batch after index 0) |
--tx-count | Number of rollup transactions in the batch |
--data-hash | Hex hash of the batch data posted as a DA blob (leave empty today: there is no way to post a blob, see Data Availability) |
--withdrawals-root | Hex Merkle root of the batch's L2 → L1 withdrawals (see ZK / STARK & Withdrawals) |
--anchor-signature | Hex ML-DSA-87 signature by the rollup creator over the v2 anchor sign bytes (since v3.2.2); the batch is then anchored in x/multilayer in the same transaction, and a refused anchor refuses the batch |
--validator-set-hash | Hex validator-set commitment carried in the anchor and covered by the signature |
Without --anchor-signature the batch settles unanchored. To anchor a batch, print the bytes to sign, sign them with the creator's registered post-quantum key, and pass the signature (the --tx-count and --validator-set-hash values must match the ones you submit):
qorechaind query rdk anchor-sign-bytes [layer-id] [batch-index] [state-root-hex] \
--chain-id qorechain-diana --tx-count 120
layer-id is the rollup's layer id (the rollup id for rollups created by the RDK). From TypeScript, RdkTxClient.submitBatch in @qorechain/rdk 0.6.0 and later signs the anchor for you when the client signs hybrid and is the rollup's creator, and anchorSignBytesForBatch gives a creator the bytes to sign out of band (see RDK 0.8.0: changes and limits). The ZK --proof for a zk rollup has no CLI flag today, and the resolve-challenge message is not a CLI command: use a client. See Settlement receipts for what an anchor does and does not prove. No rollup, layer or anchor exists on either network yet.
Challenge a batch (optimistic rollups)
Any account can challenge a submitted batch inside the challenge window (100,800 blocks by default for a batch submitted on mainnet before height 3,742,566; from v3.2.4, a window in seconds of block time for new batches: on the testnet since height 8,337,253, on mainnet since height 3,742,566) by posting a bond (the rollup's challenge_bond; 1,000 QOR for the nft and custom presets) and a fraud proof. An optimistic batch is judged by whether its state root is the canonical transition root, so a submitter should publish exactly that root (the RDK templates do, from 0.6.1; see RDK 0.8.0: changes and limits). Takes the rollup ID and batch index; pass the fraud proof with --proof:
qorechaind tx rdk challenge-batch [rollup-id] [batch-index] \
--proof <hex-encoded-fraud-proof> \
--from mykey \
--chain-id qorechain-diana \
--gas 400000 --fees 40000uqor \
--generate-only > challenge.json
qorechaind tx pqc cosign challenge.json --from mykey --pqc-key mypqckey --chain-id qorechain-diana
| Flag | Description |
|---|---|
--proof | Hex-encoded fraud proof |
A challenge freezes the batch (challenged): it cannot finalise. Before v3.2.5 only the rollup creator could resolve it; from v3.2.5 (both networks) any account can, as described below. The resolution is submitted with a resolve-challenge message (not exposed as a CLI command; use a client). The chain decides the outcome itself by verifying the stored proof. If fraud is upheld the batch is rejected, the bond is returned and the challenger is paid an additional amount equal to the bond out of the rollup's stake; if it is dismissed the bond goes to the creator and the batch returns to submitted.
From chain v3.2.5 (both networks): any account can resolve a challenge, not only the creator. An upheld fraud rejects that batch and every later batch that is not yet finalized, and the sequencer resubmits those batches from the last good state root under the same indexes; the rollup carries on from there. The Watchtower tells such batches apart by index and state root (see Watchtower).
Inspect batches
# Latest batch for a rollup
qorechaind query rdk batch [rollup-id]
# A specific batch by index
qorechaind query rdk batch [rollup-id] --index 42
# A page of batches in index order (--limit up to 100, default 50)
qorechaind query rdk batches [rollup-id] --start 0 --limit 50
Querying
| Command | Purpose |
|---|---|
qorechaind query rdk rollup [rollup-id] | Details of a specific rollup |
qorechaind query rdk list-rollups | All registered rollups |
qorechaind query rdk batch [rollup-id] | Latest settlement batch (or --index) |
qorechaind query rdk batches [rollup-id] | A page of batches in index order (--start, --limit) |
qorechaind query rdk anchor-sign-bytes [layer-id] [batch-index] [state-root-hex] | The v2 anchor sign bytes for a batch (offline) |
qorechaind query rdk config | RDK module parameters |
qorechaind query rdk suggest-profile [use-case] | Prints a pointer to the qor_suggestRollupProfile RPC; the public endpoints do not serve it, so choose a profile from the Preset Profiles table |
Next steps
- Data Availability — native, Celestia, and redundant DA backends.
- ZK / STARK & Withdrawals — proof verification and the L2 → L1 withdrawal flow via
execute-withdrawal.