QoreChain Native-Leitfaden
QoreChain Native ist QoreChains Name für seine CosmWasm-Smart-Contract-Laufzeitumgebung; die auf dieser Seite genannten CosmWasm-Bibliotheken und Client-Pakete sind also diejenigen, die du damit verwendest.
Der TypeScript-Core (@qorechain/sdk) enthält dünne, typisierte Wrapper über
@cosmjs/cosmwasm-stargate zum Abfragen und Ausführen von QoreChain Native-Verträgen. Lesevorgänge
nutzen einen schreibgeschützten Client; Zustandsänderungen nutzen einen signierenden Client.
Schreibgeschützte Abfragen
Öffne einen schreibgeschützten QoreChain Native-Client aus deiner createClient()-Instanz — er
verbindet sich über den Konsens-RPC-Endpunkt und wird auf dem Client memoisiert.
import {
createClient,
queryContractSmart,
getContractInfo,
} from "@qorechain/sdk";
const client = createClient({
network: "testnet",
endpoints: { rpc: "https://rpc-testnet.qore.host" }, // mainnet: https://rpc.qore.host
});
const cw = await client.cosmwasm(); // read-only CosmWasmReadClient
// Contract metadata.
const info = await getContractInfo(cw, contractAddress);
// A smart query (the message shape is contract-specific).
const result = await queryContractSmart(cw, contractAddress, { token_info: {} });
Du kannst einen Lese-Client auch direkt mit createCosmWasmClient konstruieren.
Signieren: instanziieren, ausführen, hochladen
Auf qorechain-vladi (Mainnet) sind code_upload_access und
instantiate_default_permission auf Nobody gesetzt, und
MsgStoreCode / MsgInstantiateContract / MsgInstantiateContract2 sind
zusätzlich durch den Circuit Breaker der Chain abgeschaltet, sodass uploadCode
und instantiate für gewöhnliche Konten abgelehnt werden. Auf qorechain-diana
(Testnet, geprüft am 27. Oktober 2026) ist code_upload_access auf Nobody
gesetzt und nur MsgStoreCode abgeschaltet, während
instantiate_default_permission auf Everybody steht, sodass instantiate dort
für bereits vorhandenen Code offen ist. Bereits vorhandene
Verträge können abgefragt (siehe oben) und ausgeführt werden. Prüfe
GET /cosmwasm/wasm/v1/codes/params für die aktuellen Berechtigungen.
Siehe QoreChain Native-Entwicklung.
connectCosmWasmSigner umhüllt den CosmJS-Signing-Client, der nur die klassische
secp256k1-Signatur anhängt. Die Live-Netzwerke verlangen bei jeder Transaktion
über den Native-Pfad die Hybrid-Signatur (secp256k1 + ML-DSA-87); eine darüber
gesendete Transaktion wird dort daher abgelehnt. Sie funktioniert gegen einen
Node, der die Hybrid-Erweiterung nicht verlangt (ein lokaler Dev-Node). Für
execute auf einem Live-Netzwerk baue die Nachricht und sende sie mit
signAndBroadcastHybrid (Beispiel unten).
Für Zustandsänderungen gegen einen Node, der klassische Signaturen akzeptiert,
verbinde einen signierenden Client mit connectCosmWasmSigner (er nimmt einen
Offline-Signierer entgegen, dieselbe Art, die von directSignerFromPrivateKey
erzeugt wird), und verwende dann die typisierten Wrapper. Die Helfer liefern
Promise<unknown> zurück, sofern du den Ergebnistyp nicht angibst:
import {
connectCosmWasmSigner,
uploadCode,
instantiate,
execute,
} from "@qorechain/sdk";
const signingCw = await connectCosmWasmSigner(rpcUrl, signer);
// Upload Wasm bytecode -> a code id.
const { codeId } = await uploadCode<{ codeId: number }>(
signingCw, sender, wasmBytes, "auto",
);
// Instantiate a contract from a code id (the last argument is InstantiateOpts).
const { contractAddress } = await instantiate<{ contractAddress: string }>(
signingCw,
sender,
codeId,
{ /* init msg */ },
"label",
{ fee: "auto" },
);
// Execute a message against a deployed contract.
const res = await execute(
signingCw,
sender,
contractAddress,
{ /* execute msg */ },
"auto",
);
Die genauen Argumentformen folgen @cosmjs/cosmwasm-stargate; das SDK fügt typisierte
ContractMsg-, FeeInput-, InstantiateOpts-, CosmWasmReadClient- und
CosmWasmSigningClient-Typen hinzu.
Ausführen auf einem Live-Netzwerk (Hybrid)
Füge die QoreChain Native-Nachrichtentypen zu einer Registry hinzu und sende die
MsgExecuteContract über den Hybrid-Builder. Der ML-DSA-87-Schlüssel des Kontos
muss zuvor registriert sein (siehe Hybrides Signieren).
Benötigt
npm i @cosmjs/cosmwasm-stargate @cosmjs/proto-signing cosmjs-types @cosmjs/stargate:
import { Registry } from "@cosmjs/proto-signing";
import { wasmTypes } from "@cosmjs/cosmwasm-stargate";
import { StargateClient } from "@cosmjs/stargate";
import { SigningCosmWasmClient } from "@cosmjs/cosmwasm-stargate";
import { MsgExecuteContract } from "cosmjs-types/cosmwasm/wasm/v1/tx";
import {
qorechainRegistryTypes,
signAndBroadcastHybrid,
derivePqcCanonical,
} from "@qorechain/sdk";
const registry = new Registry([...qorechainRegistryTypes, ...wasmTypes]);
const transport = await StargateClient.connect("https://rpc.qore.host");
const info = await transport.getSequence(sender);
// Never hardcode gas for a contract call: simulate it, then add at least 30%.
// The simulation already includes the cost of loading the contract code and a
// congestion margin (see "Gas for contract calls" below).
const cwClient = await SigningCosmWasmClient.connectWithSigner(
"https://rpc.qore.host",
signer,
);
const msgs = [
{
typeUrl: "/cosmwasm.wasm.v1.MsgExecuteContract",
value: MsgExecuteContract.fromPartial({
sender,
contract: contractAddress,
msg: new TextEncoder().encode(JSON.stringify({ /* execute msg */ })),
funds: [],
}),
},
];
const simulatedGas = await cwClient.simulate(sender, msgs, undefined);
const gas = Math.ceil(simulatedGas * 1.3);
const gasPrice = 0.15; // uqor per unit of gas; the network floor is 0.1
const result = await signAndBroadcastHybrid({
registry,
signer, // from directSignerFromPrivateKey
pqcKeypair: derivePqcCanonical(sender, mnemonic), // the key registered on-chain
messages: msgs,
fee: {
amount: [{ denom: "uqor", amount: String(Math.ceil(gas * gasPrice)) }],
gas: String(gas),
},
chainId: "qorechain-vladi",
accountNumber: info.accountNumber,
sequence: info.sequence,
rest: "https://api.qore.host",
transport,
});
Gas für Contract-Aufrufe
Legen Sie Gas für einen Contract-Aufruf nicht fest im Code ab. Feste 400,000 reichen für einen einfachen Transfer bei einem Aufruf und gehen beim nächsten aus. Ab Release v3.2.8 (nur Testnet, bis ein späteres Mainnet-Upgrade folgt) wird CosmWasm-Gas neu bepreist:
- Der erste Aufruf eines Contract-Codes in einem Block zahlt Ladekosten. Ein cw20-Transfer kostet etwa 533,000 Gas als erster Aufruf seines Codes in einem Block und etwa 84,000 für jede Wiederholung. Die Governance kann beliebte Codes anheften (Pinning), und bei angehefteten Codes entfällt die Ladegebühr.
- Gebühren steigen mit der Auslastung. Ein Auslastungsfaktor skaliert das Contract-Gas standardmäßig von 1x bis 20x, wenn Blöcke mit Contract-Aufrufen ausgelastet sind, und ein Block hat ein begrenztes Budget für Contract-Ausführung, von dem eine einzelne Transaktion höchstens die Hälfte nutzen kann.
- Die Simulation enthält beides. Eine Simulation berechnet immer das Kaltladen und addiert einen Puffer für die Auslastung, sodass
simulated gas x 1.3ein sicheres Limit ist. Nutzen Siefee: "auto", wo Ihr Client es anbietet (CosmJS"auto", der SDK-TxClient, der React-HookuseTx), und simulieren Sie selbst, wenn Sie die Gebühr wie oben von Hand aufbauen. - Bleiben Sie unter der Transaktionsobergrenze. Eine Cosmos-Transaktion darf kein Gaslimit über 50,000,000 setzen und wird abgelehnt, bevor ihre Gebühr erhoben wird. SDK 0.14.0 lehnt ein solches Limit vor dem Signieren ab (und eine EVM-Transaktion über 30,000,000), gibt CosmWasm- und Cross-VM-Transaktionen mindestens das 1,3-Fache des simulierten Gas und fällt für sie nie auf ein festes Gaslimit zurück. Es hat außerdem Opt-in-Helfer, die den minimalen Gaspreis des Netzwerks lesen; der Standard-Gaspreis bleibt unverändert.
Dasselbe gilt für Instantiate, Migrate und jede andere Nachricht, die Contract-Code ausführt.
Siehe das cosmwasm-query-Beispiel für ein lauffähiges Lesebeispiel.