Aller au contenu principal

Guide Cross-VM

QoreChain exécute EVM, SVM et QoreChain Native côte à côte, et le module x/crossvm permet à un seul compte natif d'invoquer un contrat sur n'importe lequel d'entre eux. Le SDK fournit un assistant de haut niveau createCrossVMClient pour construire, signer et diffuser ces appels — y compris en empaquetant plusieurs d'entre eux dans une seule transaction atomique à travers les trois VM — plus des assistants de lecture typés pour suivre l'état des messages. Le routage EVM→natif initié depuis l'intérieur de l'EVM s'exécute toujours sur la chaîne via le précompilé du pont cross-VM dans @qorechain/evm.

Ce qui fonctionne aujourd'hui

Les appels cross-VM ne sont disponibles que dans la mesure où leur voie cible l'est :

  • MsgCrossVMCall est désactivé par le disjoncteur de la chaîne sur le mainnet (GET /cosmos/circuit/v1/disable_list liste /qorechain.crossvm.v1.MsgCrossVMCall) ; il est activé sur le testnet.
  • La voie de transaction SVM est désactivée sur l'ensemble du réseau, le téléversement et l'instanciation QoreChain Native sont soumis à permission (et il n'y a aucun contrat sur le mainnet), et le précompilé de pont EVM n'est pas actif (voir Précompilés EVM).
  • Les assistants de lecture REST typés ci-dessous appellent des routes que la passerelle publique ne sert pas. Lisez plutôt les messages avec connectQueryClients(rpc).crossvm.
  • Comme toute transaction du chemin Native, un appel cross-VM doit porter la signature hybride : connectez le client de signature avec la paire de clés du compte (client.connectTx(signer, { pqcKeypair }), SDK 0.9.0 ou ultérieur) afin que le client cross-VM signe en mode hybride (voir Comptes et signature PQC). Les versions antérieures à la 0.9.0 le signent de façon classique et les réseaux publics le refusent.

Appels cross-VM unifiés​

createCrossVMClient encapsule MsgCrossVMCall (URL de type /qorechain.crossvm.v1.MsgCrossVMCall) de sorte que vous n'ayez jamais à construire manuellement un { typeUrl, value } ni à encoder une charge utile vous-même. L'expéditeur du client est l'adresse du TxClient connecté ; sourceVm vaut par défaut "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 est l'un de "evm" | "cosmwasm" | "svm" (également exporté sous forme du tableau VM_TYPES).

Encodage de la charge utile par VM​

Choisissez exactement une forme de charge utile par appel :

FormeEncodage
{ payload: Uint8Array | Hex }octets bruts, transmis tels quels
{ evm: { abi, functionName, args } }encodé en ABI avec encodeFunctionData de viem (sélecteur + args)
{ cosmwasm: object }JSON.stringify puis octets UTF-8 (la convention execute-msg de QoreChain Native)
{ svm: { data: Uint8Array | Hex } }octets bruts (un blob d'instruction SVM)

Le chemin EVM importe viem de façon paresseuse ; le pair optionnel viem n'est donc nécessaire que lorsque vous utilisez réellement une charge utile { evm: ... }.

Construction seule (hors ligne)​

buildCall renvoie l'EncodeObject sans le diffuser — pratique pour l'inspection, le regroupement manuel ou la signature ailleurs. (Les charges utiles EVM sont encodées en ABI de façon asynchrone ; pour celles-ci, utilisez donc call/callAtomic, ou encodez-les au préalable et passez { payload }.)

const msg = xvm.buildCall({
targetVm: "svm",
targetContract: "Prog...",
svm: { data: new Uint8Array([1, 2, 3]) },
});

Transactions atomiques tri-VM​

callAtomic empaquette plusieurs messages MsgCrossVMCall dans un seul corps de transaction afin qu'ils s'exécutent de façon atomique sous une seule signature — l'argument phare tri-VM. Une signature, des appels à travers EVM + SVM + QoreChain Native qui aboutissent tous ensemble ou pas du tout :

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: {} } },
]);

Relire un message​

getMessage lit un message cross-VM par identifiant, en privilégiant le client de requête typé et en se rabattant sur la méthode JSON-RPC qor_getCrossVMMessage (que les points d'accès publics ne servent pas). Donnez-lui le client de requête typé, qui lit via le RPC de consensus :

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();

Lire l'état des messages cross-VM​

@qorechain/sdk exporte des wrappers REST typés au-dessus de x/crossvm. Ils appellent /qorechain/crossvm/v1/{message/{id},pending,params}, que la passerelle publique ne sert pas (Not Implemented sur api.qore.host et api-testnet.qore.host), de sorte qu'ils lèvent QoreHttpError contre les points d'accès publics. Ils sont destinés aux nœuds qui exposent ces routes ; sur les réseaux publics, utilisez connectQueryClients ci-dessus.

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);

Ils renvoient des formes typées : CrossVmMessage, CrossVmMessageResponse, PendingCrossVmMessagesResponse et CrossVmParamsResponse.

Vous pouvez également lire un message via l'espace de noms JSON-RPC qor_, une fois que les nœuds le serviront :

Pas encore servi : aucune version de nœud publiée ne sert l'espace de noms JSON-RPC qor_, de sorte que cet appel renvoie -32601 (méthode introuvable) sur tous les points d'accès publics aujourd'hui. Voir l'espace de noms qor_.

const m = await client.qor.getCrossVmMessage(messageId);

Le précompilé du pont EVM​

Le routage EVM→natif s'exécute sur la chaîne via le précompilé du pont cross-VM, exposé dans @qorechain/evm :

import { PRECOMPILE_ADDRESSES } from "@qorechain/evm";

console.log(PRECOMPILE_ADDRESSES.crossVmBridge);
// 0x0000000000000000000000000000000000000901

Non actif sur le mainnet ; actif sur le testnet. Le précompilé du pont cross-VM ne figure pas dans la liste active du mainnet, donc un appel à 0x…0901 y renvoie des données vides et ne route rien. La liste du testnet le contient (lu le 7 novembre 2026) ; le 7 novembre 2026, un eth_call en lecture seule vers celui-ci a atteint un contrat de la liste d'autorisation et a été refusé (« is not allowlisted ») pour toute autre cible. Voir Précompilés EVM : état du réseau.

Une fois actif, un contrat Solidity (ou viem) appelle le précompilé à cette adresse pour router un message vers la couche native, puis suit son état avec les assistants de lecture ci-dessus. Voir le guide EVM pour la liste complète des précompilés.