Builder FAQ
Builder FAQ
Answers to the questions builders ask most, on the testnet, the challenges, the audit, the precompiles, agents, QoreX signing and the Q-Day Drill.
Testnet, faucet and addresses
My wallet shows a 0x address but the faucet only accepts qor1. Which address do I use?
They are the same account. On QoreChain the EVM address and the qor1 address are two encodings of the same 20 bytes. Convert the 0x address to qor1 (bech32 with the prefix qor, for example bech32.encode("qor", bech32.toWords(bytes)) with @scure/base) and paste the qor1 address into the faucet. The test QOR also shows in MetaMask on diana (EVM chain ID 9800).
The faucet says I have to wait. How often can I claim?
Once every 24 hours per account. fUSD, fETH and fBTC come with that same claim, so they share the 24 hour wait with test QOR.
My fUSD balance is zero. Do I need fUSD for the swap challenge?
No. Pool 2 is fUSD/QOR, so you can swap test QOR into fUSD straight away. fUSD lives on the EVM side (0x97143B771D34ddb9130b807b135Ae675A5a963CA); add it as a token in your wallet to see the balance.
I lost access to the wallet I linked at registration. Does that hurt my project?
No. Ship Weeks checks every qor1 address listed on your project page, plus the linked QoreX address. Add the addresses you actually build with and press Check again. Prizes are not paid to the linked address: winners are asked for a payout wallet and network when prizes are paid.
Can a lost QoreX wallet be recovered?
Only with its recovery phrase or a guardian you set up. QoreX is non-custodial and keeps keys only on your device, so without either the wallet cannot be recovered by anyone. Write the phrase down right after creating a wallet.
Ship Weeks challenges
Which network do the challenges count on?
Only the diana testnet. Nothing on mainnet is needed or counted.
Which addresses are checked?
Every qor1 address on your project page plus your linked QoreX address. A transaction from an address that is not listed does not count, so add it first, then press Check again.
"First swap in a pool": does a swap on Dashboard → Trade count?
No. That page uses the EVM DEX. The challenge looks for a native AMM swap (MsgSwapExactIn or MsgSwapExactOut). There is no wallet button for it yet; use the SDK or the CLI:
const swap = msg.amm.swapExactIn({
sender: acc.cosmos,
poolId: 2n,
tokenIn: { denom: "uqor", amount: "100000" }, // 0.1 QOR
denomOut: "erc20:0x97143B771D34ddb9130b807b135Ae675A5a963CA",
minOut: "1",
});
// sign hybrid with EthNativeSigner and broadcast on qorechain-dianaqorechaind tx amm swap-exact-in 2 100000uqor erc20:0x97143B771D34ddb9130b807b135Ae675A5a963CA 1 --from mykey --chain-id qorechain-diana --gas 400000 --fees 60000uqor --generate-only > swap.json
qorechaind tx pqc cosign swap.json --from mykey --pqc-key mypqc --chain-id qorechain-dianaThe account needs its ML-DSA-87 key registered first.
"First contract with a PQC check": how does the checker decide?
It reads the deployment receipt, fetches the contract's runtime code and looks for the address of a PQC precompile in it. No verified source and no trace is needed. Constants, literal addresses and immutables (for example an address passed to the constructor) are all recognised.
Does it have to be pqcVerify?
No. pqcVerify (0x…0a01) and pqcKeyStatus (0x…0a02) count the same.
My contract does call the precompile but the check said no. What now?
Press Check again with the same deployment transaction; no redeploy is needed. If it still fails, post the deployment tx hash in #builders.
Why does my Solidity contract not compile with 0x…0A01?
Solidity treats a mixed-case address as a checksum and rejects this one. Write precompile addresses in lowercase.
"First QoreSeal key": does a fresh wallet work?
Yes. The challenge looks for a successful MsgRegisterKEMKey from any address on your project or your linked QoreX. Add the fresh wallet's qor1 address to the project first. The official register-and-encrypt example sends exactly that transaction; it derives a secp256k1 qor1 address from the mnemonic, so add that exact address. The account needs its ML-DSA-87 key registered first. There is no wallet button for this yet.
Project page: Declared and Verified
What is the difference between Declared and Verified?
Declared is what you select. Verified is what we found ourselves:
- Kits: the package appears by name in a dependency file in your repo (package.json, go.mod, Cargo.toml, pyproject and similar).
- Features: proven by transactions from the qor1 addresses on your project.
The check runs when you save, on every GitHub push, daily, and when you press Check again.
Some items never turn Verified. Is that a problem?
No. A few items cannot be verified automatically yet: create-qorechain-dapp (a scaffolder, usually not left in your dependencies) and the Solidity PQC verify and key status features. Jurors check those in your repo by hand.
QCAI audit (Post-Quantum dApp track)
Which audit setting should I use for QoreChain EVM (Solidity) contracts?
An EVM/Solidity setting, for example "Ethereum (EVM/Solidity)". The "QoreChain (CosmWasm + PQC)" setting is for CosmWasm contracts. On Solidity it reports a "mismatch", which is not a finding about your contract.
Why do I see "Not scored" for quantum readiness?
The readiness rating is only produced by the CosmWasm setting today, so EVM settings show "Not scored". That is expected and does not count against you. A QoreChain EVM setting that knows the PQC precompiles is planned. Meanwhile, explain your PQC design in docs/AUDIT.md: where you call pqcVerify or pqcKeyStatus, what each call protects, and which tests cover it.
What counts as Stage 2?
A second QCAI run after you have worked through every Stage 1 finding. Fixing a finding, adding a regression test for it, or documenting why it is a false positive or does not need a contract change are all valid ways to work through it. Zero findings is not required.
My Stage 2 score is lower than Stage 1. Is that bad?
Not by itself. The audit score is not fed into judging automatically. Jurors score by hand and read the reports together with your explanations.
Is there a submission field for the audit?
No. Put it in your repo:
docs/audit/with both reports (PDF), each with its date;docs/AUDIT.mdmapping each Stage 1 finding to what you did (fixed, regression test with its name, or false positive and why), or a link to your public audit response;- one line in your README and in the "How it's made" field of your project page pointing to it.
Use the same audit setting for both stages so the reports can be compared.
PQC precompiles and contracts
Are pqcVerify and pqcKeyStatus live on mainnet?
Not yet. They are active on the diana testnet. On mainnet they need a chain upgrade and then a governance vote to switch them on; there is no date yet and it will be announced. Contracts you build and test on diana now will not need changes.
How do I check which precompiles are active?
GET /cosmos/evm/vm/v1/params on the REST endpoint, field active_static_precompiles.
Can I verify my contract's source on explore.qore.network, or use hardhat-verify?
Not yet. The explorer has no source verification and no Etherscan-compatible API. Keep the source and exact compiler settings in your repo and link the deployment in your README.
Why does my EVM transaction from MetaMask get refused?
On QoreChain an EVM transaction only goes through while the account has an open EVM window. Opening one takes the account's ML-DSA-87 key, registered on chain first. You can do both from the Dashboard or QoreX. A scoped window (limited blocks, transactions, value and targets) is the safer choice.
Agents and account abstraction
Can an agent act within limits while the owner's ML-DSA key stays offline?
Yes, for payments and EVM calls. The owner links an agent key once with spending rules (per-transaction and daily limits, allowed denoms, allowed EVM calls). After that the agent signs with its own key and a relayer submits the transaction. The owner's ML-DSA key is needed only to link, to revoke, and to re-link at least every 30 days.
Does an agent's EVM call need an EVM window?
No. EVM calls made this way (MsgExecuteEVM) do not need a window. An agent cannot open or renew the owner's EVM window; that needs the owner's own hybrid signature.
Which nonce does an agent sign with?
The linked key's own counter: GET /qorechain/abstractaccount/v1/auth_nonce/{address}/{pubkey_hex}. It is not the account's EVM nonce. A stale nonce is refused with code 11.
Where are examples?
The Account abstraction and Authenticators pages in the docs, the authenticator-spend example in the SDK, and the Workshop 2 bill-paying agent. Agents (abstract accounts) are testnet only for now.
Signing messages with QoreX (ML-DSA-87)
Can a website ask QoreX for an ML-DSA-87 signature and get it back?
Yes, with signArbitrary (Keplr style) in the QoreSign message-signing-v1 format. Check window.qorex.native.capabilities.includes("signArbitrary") first.
const q = window.qorex.native;
await q.enable("qorechain-diana");
const { bech32Address } = await q.getKey("qorechain-diana");
const sig = await q.signArbitrary("qorechain-diana", bech32Address, data);Does QoreX sign my raw bytes?
No. It signs "qorechain-msg-v1|" + chainId + "|" + data, so a message signature can never be reused as a transaction or key registration. Messages are 1 to 4096 bytes and the user sees all of it before approving. A message that starts with a reserved signing prefix (qorechain-…) is refused.
How do I verify the signature against the account's registered key?
import { verifyMessageWithChain } from "@qorechain/qoresign/network";
await verifyMessageWithChain({
rest: "https://api-testnet.qore.host",
chainId: "qorechain-diana",
signer: bech32Address,
data,
signature: sig,
}); // throws if invalid or no ML-DSA-87 key is registeredIt checks both layers: secp256k1 (ADR-36) and ML-DSA-87 against the key registered on chain. In the page you can also call q.verifyArbitrary(chainId, signer, data, sig). To check it in a contract with pqcVerify, pass the prefixed bytes as the message.
How do I test this on QoreX mobile?
Switch the app to testnet first (developer mode, then testnet), then open your dApp in the app's built-in browser. The phone cannot reach localhost on your computer, so serve the dApp on a public HTTPS URL.
The QoreX extension does not unlock after I reopen it.
Click the Unlock button (Enter does not submit in the current version) and wait a few seconds; unlocking shows no progress yet. A fix is coming in the next extension update. If QoreX is listed twice in chrome://extensions, each copy has its own wallet and password. Your recovery phrase restores the same wallet on any install.
Q-Day Drill
When does it run?
Registration closes 17 November, 23:59 UTC. The attack runs for one UTC day, 18 November. Proof hashes are accepted until 19 November, 23:59 UTC; the proof transaction itself must fall on 18 November.
How is the ranking decided?
- Proof of a normal transaction submitted on your project page;
- fewest successful attacks;
- most value kept;
- the jury breaks ties.
Does it include my registered contracts?
Value kept covers the drill account only: the native account of the registered key and the EVM address of the same key. Your registered contracts (up to 5) are attacked too, and any attack that succeeds against them counts in "fewest successful attacks", which ranks first.
Do fees burned by the attack bot count as lost value?
Yes. The bot signs with your drill key, so gas it burns comes out of your account. If an EVM attack would revert, the bot estimates gas first and does not send it, so that costs nothing. Only transactions sent and then reverted on chain burn gas.
Should I keep my EVM window closed?
A closed window is the zero-risk choice. A small, tightly scoped window is fine if it is part of your threat model; the jury reads that when breaking ties.
What counts as the proof of a normal transaction?
Either an EVM transaction from the drill key's 0x address, or a hybrid-signed native transaction where the drill account is a sender. It must succeed (code 0), land during the drill day, and its hash must be submitted on your project page (a native hash is 64 hex characters without 0x).