Guía Cross-VM
QoreChain ejecuta EVM, SVM y QoreChain Native en paralelo, y el módulo x/crossvm
permite que una sola cuenta nativa invoque un contrato en cualquiera de ellos. El
SDK proporciona un ayudante de alto nivel createCrossVMClient para construir,
firmar y difundir estas llamadas, incluso empaquetando varias en una
transacción atómica a través de las tres VM, además de ayudantes de lectura
tipados para seguir el estado de los mensajes. El enrutamiento EVM→nativo iniciado
desde dentro de la EVM aún se ejecuta en la cadena a través del precompilado
del puente cross-VM en @qorechain/evm.
Las llamadas cross-VM solo están disponibles en la medida en que lo esté su carril de destino:
MsgCrossVMCallestá desactivado por el circuit breaker de la cadena en mainnet (GET /cosmos/circuit/v1/disable_listlista/qorechain.crossvm.v1.MsgCrossVMCall); está habilitado en la testnet.- El carril de transacciones SVM está deshabilitado en toda la red, la subida e instanciación de QoreChain Native requieren permisos (y no hay contratos en mainnet), y el precompilado del puente EVM no está activo (consulta Precompilados EVM).
- Los ayudantes de lectura REST tipados de abajo llaman a rutas que la pasarela pública no sirve.
Lee los mensajes con
connectQueryClients(rpc).crossvmen su lugar. - Como toda transacción de la ruta Native, una llamada cross-VM debe llevar la firma
híbrida: conecta el cliente de firma con el par de claves de la cuenta
(
client.connectTx(signer, { pqcKeypair }), SDK 0.9.0 o posterior) para que el cliente cross-VM firme de forma híbrida (consulta Cuentas y firma PQC). Las versiones anteriores a la 0.9.0 la firman de forma clásica y las redes públicas la rechazan.
Llamadas cross-VM unificadas
createCrossVMClient envuelve MsgCrossVMCall (URL de tipo
/qorechain.crossvm.v1.MsgCrossVMCall) para que nunca tengas que construir a mano
un { typeUrl, value } ni codificar una carga útil por tu cuenta. El emisor del
cliente es la dirección del TxClient conectado; sourceVm toma por defecto el
valor "evm".
import { createClient, createCrossVMClient } from "@qorechain/sdk";
const client = createClient({ network: "testnet", endpoints: { rpc, rest } });
const tx = await client.connectTx(signer, { pqcKeypair }); // hybrid-signed (SDK 0.9.0)
const xvm = createCrossVMClient(tx);
// Call an EVM contract from a native account — the payload is ABI-encoded.
const { messageId, result } = await xvm.call({
sourceVm: "cosmwasm",
targetVm: "evm",
targetContract: "0xToken",
evm: { abi: erc20Abi, functionName: "transfer", args: ["0xRecipient", 1n] },
});
VMType es uno de "evm" | "cosmwasm" | "svm" (también exportado como el array
VM_TYPES).
Codificación de la carga útil por VM
Elige exactamente una forma de carga útil por llamada:
| Forma | Codificación |
|---|---|
{ payload: Uint8Array | Hex } | bytes en bruto, pasados sin cambios |
{ evm: { abi, functionName, args } } | codificada en ABI con encodeFunctionData de viem (selector + args) |
{ cosmwasm: object } | JSON.stringify y luego bytes UTF-8 (la convención de mensaje de ejecución de QoreChain Native) |
{ svm: { data: Uint8Array | Hex } } | bytes en bruto (un blob de instrucción SVM) |
La ruta EVM importa viem de forma diferida, por lo que el par opcional viem
solo se necesita cuando realmente usas una carga útil { evm: ... }.
Solo construcción (sin conexión)
buildCall devuelve el EncodeObject sin difundirlo: práctico para inspección,
para agrupar a mano o para firmar en otro lugar. (Las cargas útiles EVM se
codifican en ABI de forma asíncrona, así que para esas usa call/callAtomic, o
precodifica y pasa { payload }.)
const msg = xvm.buildCall({
targetVm: "svm",
targetContract: "Prog...",
svm: { data: new Uint8Array([1, 2, 3]) },
});
Transacciones atómicas a través de tres VM
callAtomic empaqueta varios mensajes MsgCrossVMCall en un único cuerpo de
transacción para que se ejecuten de forma atómica bajo una sola firma: el
titular de las tres VM. Una firma, llamadas a través de EVM + SVM + QoreChain Native que
aterrizan todas juntas o ninguna:
const { messageIds, result } = await xvm.callAtomic([
{
targetVm: "evm",
targetContract: "0xToken",
evm: { abi: erc20Abi, functionName: "transfer", args: ["0xRecipient", 2n] },
},
{ targetVm: "svm", targetContract: "Prog...", svm: { data: instructionBytes } },
{ targetVm: "cosmwasm", targetContract: "qor1c...", cosmwasm: { ping: {} } },
]);
Volver a leer un mensaje
getMessage lee un mensaje cross-VM por id, prefiriendo el cliente de consulta
tipado y recurriendo al método JSON-RPC qor_getCrossVMMessage (que los endpoints
públicos no sirven). Pásale el cliente de consulta tipado, que lee a través del
RPC de consenso:
import { connectQueryClients } from "@qorechain/sdk";
// rpcClient: a connected consensus-RPC client (the CosmJS RPC client type).
const queries = connectQueryClients(rpcClient);
const reader = createCrossVMClient(tx, { query: queries.crossvm });
const msg = await reader.getMessage(messageId);
// Module parameters and the pending queue, over the same typed client:
const params = await queries.crossvm.params();
const pending = await queries.crossvm.pendingMessages();
Lectura del estado de los mensajes cross-VM
@qorechain/sdk exporta envoltorios REST tipados sobre x/crossvm. Llaman a
/qorechain/crossvm/v1/{message/{id},pending,params}, que la pasarela pública
no sirve (Not Implemented en api.qore.host y api-testnet.qore.host),
por lo que lanzan QoreHttpError contra los endpoints públicos. Son para nodos
que exponen esas rutas; en las redes públicas usa connectQueryClients, descrito arriba.
import {
createClient,
getCrossVmMessage,
getPendingCrossVmMessages,
getCrossVmParams,
} from "@qorechain/sdk";
const client = createClient({
endpoints: { rest: "https://api-testnet.qore.host" },
});
// A single message by id.
const msg = await getCrossVmMessage(client.rest, messageId);
// Pending messages. On a network running v3.2.8 or later the route is paginated
// (at most 100 per page) and `payload_hex` is cut to 1,024 bytes in the list:
// read the full payload with getCrossVmMessage.
const pending = await getPendingCrossVmMessages(client.rest);
// Module parameters.
const params = await getCrossVmParams(client.rest);
Estos devuelven formas tipadas: CrossVmMessage, CrossVmMessageResponse,
PendingCrossVmMessagesResponse y CrossVmParamsResponse.
También puedes leer un mensaje a través del espacio de nombres JSON-RPC qor_, una vez que los nodos
lo sirvan:
Aún no se sirve: ninguna compilación publicada de nodo sirve el espacio de nombres JSON-RPC
qor_, por lo que esta llamada devuelve-32601(método no encontrado) en todos los endpoints públicos hoy. Consulta el espacio de nombresqor_.
const m = await client.qor.getCrossVmMessage(messageId);
El precompilado del puente EVM
El enrutamiento EVM→nativo se ejecuta en la cadena a través del precompilado del
puente cross-VM, expuesto en @qorechain/evm:
import { PRECOMPILE_ADDRESSES } from "@qorechain/evm";
console.log(PRECOMPILE_ADDRESSES.crossVmBridge);
// 0x0000000000000000000000000000000000000901
No activo en mainnet; activo en la testnet. El precompilado del puente cross-VM no está en la lista de activos de mainnet, así que una llamada a
0x…0901allí devuelve datos vacíos y no enruta nada. La lista de la testnet lo contiene (leída el 7 de noviembre de 2026); el 7 de noviembre de 2026 uneth_callde solo lectura a él llegó a un contrato de la lista de permitidos y fue rechazado ("is not allowlisted") para cualquier otro destino. Consulta Precompilados EVM: Estado de la red.
Una vez activo, un contrato de Solidity (o viem) llama al precompilado en esa dirección para enrutar un mensaje a la capa nativa, y luego sigue su estado con los ayudantes de lectura de arriba. Consulta la guía de EVM para ver la lista completa de precompilados.