Guía de QoreChain Native
QoreChain Native es el nombre que da QoreChain a su runtime de contratos inteligentes CosmWasm, así que las bibliotecas CosmWasm y los paquetes de cliente que se nombran en esta página son los que usas con él.
El núcleo de TypeScript (@qorechain/sdk) incluye envoltorios finos y tipados
sobre @cosmjs/cosmwasm-stargate para consultar y ejecutar contratos QoreChain Native.
Las lecturas usan un cliente de solo lectura; los cambios de estado usan un cliente
de firma.
Consultas de solo lectura
Abre un cliente QoreChain Native de solo lectura desde tu instancia de createClient(): se
conecta a través del endpoint RPC de consenso y se memoriza en el cliente.
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: {} });
También puedes construir un cliente de lectura directamente con
createCosmWasmClient.
Firma: instanciar, ejecutar, subir
En qorechain-vladi (mainnet), code_upload_access e
instantiate_default_permission están en Nobody, y MsgStoreCode /
MsgInstantiateContract / MsgInstantiateContract2 además están desactivados por
el cortacircuitos (circuit breaker) de la cadena, por lo que uploadCode e
instantiate se rechazan para las cuentas normales. En qorechain-diana (testnet,
comprobado el 27 de octubre de 2026), code_upload_access está en Nobody y solo
MsgStoreCode está desactivado, mientras que instantiate_default_permission está
en Everybody, por lo que instantiate está abierto allí para código que ya existe.
Los contratos que ya existen se pueden consultar (arriba) y ejecutar. Consulta GET /cosmwasm/wasm/v1/codes/params
para ver los permisos actuales. Consulta
Desarrollo con QoreChain Native.
connectCosmWasmSigner envuelve el cliente de firma de CosmJS, que solo adjunta la
firma clásica secp256k1. Las redes en vivo exigen la firma híbrida
(secp256k1 + ML-DSA-87) en cada transacción de la ruta nativa (Native), así que una
transacción enviada a través de él se rechaza allí; funciona contra un nodo que no
exige la extensión híbrida (un nodo de desarrollo local). Para execute en una red
en vivo, construye el mensaje y envíalo con signAndBroadcastHybrid (ejemplo más
abajo).
Para los cambios de estado contra un nodo que acepta firmas clásicas, conecta un
cliente de firma con connectCosmWasmSigner (recibe un firmante sin conexión, del
mismo tipo que produce directSignerFromPrivateKey) y luego usa los envoltorios
tipados. Los auxiliares devuelven Promise<unknown> salvo que indiques el tipo del
resultado:
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",
);
Las formas exactas de los argumentos siguen a @cosmjs/cosmwasm-stargate; el SDK
añade los tipos ContractMsg, FeeInput, InstantiateOpts,
CosmWasmReadClient y CosmWasmSigningClient.
Ejecutar en una red en vivo (híbrido)
Añade los tipos de mensaje de QoreChain Native a un registro y envía el
MsgExecuteContract a través del constructor híbrido. La clave ML-DSA-87 de la
cuenta debe estar registrada antes (consulta Firma híbrida).
Requiere
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 para llamadas a contratos
No fijes el gas de una llamada a un contrato. Un valor fijo de 400,000 basta para una transferencia simple en una llamada y se agota en la siguiente. Desde la versión v3.2.8 (solo testnet hasta una actualización posterior de mainnet) el gas de CosmWasm se reajusta:
- La primera llamada de un código de contrato en un bloque paga un coste de carga. Una transferencia cw20 cuesta unos 533,000 de gas como primera llamada de su código en un bloque y unos 84,000 en cada repetición. La gobernanza puede fijar (pin) los códigos populares, y los códigos fijados se saltan el cargo de carga.
- Las comisiones suben con la congestión. Un factor de congestión escala el gas de contratos de 1x hasta 20x por defecto cuando los bloques están ocupados con llamadas a contratos, y un bloque tiene un presupuesto limitado de ejecución de contratos del que una transacción puede usar como máximo la mitad.
- La simulación incluye ambos. Una simulación siempre cobra la carga en
frío y añade un margen para la congestión, así que
gas simulado x 1.3es un límite seguro. Usafee: "auto"donde tu cliente lo ofrezca ("auto"de CosmJS, elTxClientdel SDK, el hookuseTxde React), y simula tú mismo cuando construyas la comisión a mano como arriba. - Mantente por debajo del tope de transacción. Una transacción de Cosmos no puede fijar un límite de gas superior a 50,000,000 y se rechaza antes de cobrar su comisión. El SDK 0.14.0 rechaza ese límite antes de firmar (y una transacción EVM por encima de 30,000,000), da a las transacciones de CosmWasm y cross-VM al menos 1.3 veces el gas simulado y nunca recurre a un límite de gas fijo para ellas. También tiene ayudantes opcionales que leen el precio mínimo del gas de la red; el precio de gas por defecto no cambia.
Lo mismo se aplica a instantiate, migrate y a cualquier otro mensaje que ejecute código de contrato.
Consulta el ejemplo cosmwasm-query para ver un ejemplo de
lectura ejecutable.