Guida Cross-VM
QoreChain esegue EVM, SVM e QoreChain Native fianco a fianco, e il modulo x/crossvm
permette a un singolo account nativo di invocare un contratto su uno qualsiasi di essi. L'SDK
fornisce un helper di alto livello createCrossVMClient per costruire, firmare e trasmettere
queste chiamate — incluso il raggruppamento di più chiamate in un'unica transazione atomica
su tutte e tre le VM — più helper di lettura tipizzati per tracciare lo stato dei messaggi. Il routing EVM→nativo
avviato dall'interno dell'EVM viene comunque eseguito on-chain tramite il precompilato del bridge
cross-VM in @qorechain/evm.
Le chiamate cross-VM sono disponibili solo quanto la loro corsia di destinazione:
MsgCrossVMCallè disattivato dal circuit breaker della catena su mainnet (GET /cosmos/circuit/v1/disable_listelenca/qorechain.crossvm.v1.MsgCrossVMCall); è abilitato sul testnet.- La corsia di transazioni SVM è disabilitata su tutta la rete, l'upload e l'istanziazione QoreChain Native sono soggetti a permessi (e su mainnet non ci sono contratti), e il precompilato del bridge EVM non è attivo (vedi Precompilati EVM).
- Gli helper di lettura REST tipizzati qui sotto chiamano route che il gateway pubblico non serve.
Leggi invece i messaggi con
connectQueryClients(rpc).crossvm. - Come ogni transazione del percorso Native, una chiamata cross-VM deve portare la firma
ibrida: connetti il client di firma con la coppia di chiavi dell'account
(
client.connectTx(signer, { pqcKeypair }), SDK 0.9.0 o successivo) così che il client cross-VM firmi in modalità ibrida (vedi Account e firma PQC). Le release precedenti alla 0.9.0 la firmano in modo classico e le reti pubbliche la rifiutano.
Chiamate cross-VM unificate
createCrossVMClient incapsula MsgCrossVMCall (type URL
/qorechain.crossvm.v1.MsgCrossVMCall) così non devi mai costruire a mano un { typeUrl, value } né codificare tu stesso un payload. Il mittente del client è l'indirizzo del
TxClient connesso; sourceVm ha come valore predefinito "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 è uno tra "evm" | "cosmwasm" | "svm" (esportato anche come array
VM_TYPES).
Codifica del payload per ciascuna VM
Scegli esattamente una forma di payload per chiamata:
| Forma | Codifica |
|---|---|
{ payload: Uint8Array | Hex } | byte grezzi, passati invariati |
{ evm: { abi, functionName, args } } | codificato in ABI con encodeFunctionData di viem (selector + args) |
{ cosmwasm: object } | JSON.stringify poi byte UTF-8 (la convenzione execute-msg di QoreChain Native) |
{ svm: { data: Uint8Array | Hex } } | byte grezzi (un blob di istruzioni SVM) |
Il percorso EVM importa viem in modo lazy, quindi il peer opzionale viem serve solo
quando usi effettivamente un payload { evm: ... }.
Solo costruzione (offline)
buildCall restituisce l'EncodeObject senza trasmetterlo — utile per
l'ispezione, per il batching manuale o per firmare altrove. (I payload EVM vengono
codificati in ABI in modo asincrono, quindi per questi usa call/callAtomic, oppure codificali prima
e passa { payload }.)
const msg = xvm.buildCall({
targetVm: "svm",
targetContract: "Prog...",
svm: { data: new Uint8Array([1, 2, 3]) },
});
Transazioni atomiche su tripla VM
callAtomic raggruppa più messaggi MsgCrossVMCall in un unico corpo di
transazione così che vengano eseguiti in modo atomico con una sola firma — il punto di forza
della tripla VM. Una firma, chiamate su EVM + SVM + QoreChain Native che vanno a buon fine tutte insieme
oppure per nulla:
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: {} } },
]);
Rileggere un messaggio
getMessage legge un messaggio cross-VM per id, preferendo il client di query tipizzato
e ripiegando sul metodo JSON-RPC qor_getCrossVMMessage (che gli endpoint
pubblici non servono). Passagli il client di query tipizzato, che legge tramite l'RPC
di 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();
Lettura dello stato dei messaggi cross-VM
@qorechain/sdk esporta wrapper REST tipizzati sopra x/crossvm. Chiamano
/qorechain/crossvm/v1/{message/{id},pending,params}, che il gateway pubblico
non serve (Not Implemented su api.qore.host e api-testnet.qore.host),
quindi sollevano QoreHttpError contro gli endpoint pubblici. Sono pensati per nodi
che espongono quelle route; sulle reti pubbliche usa connectQueryClients qui sopra.
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);
// Messaggi in attesa. Su una rete che esegue la v3.2.8 o successiva la route è
// paginata (al massimo 100 per pagina) e `payload_hex` è troncato a 1.024 byte
// nella lista: leggi il payload completo con getCrossVmMessage.
const pending = await getPendingCrossVmMessages(client.rest);
// Module parameters.
const params = await getCrossVmParams(client.rest);
Questi restituiscono forme tipizzate: CrossVmMessage, CrossVmMessageResponse,
PendingCrossVmMessagesResponse e CrossVmParamsResponse.
Puoi anche leggere un messaggio tramite il namespace JSON-RPC qor_, una volta che i nodi
lo serviranno:
Non ancora servito: nessuna build di nodo rilasciata serve il namespace JSON-RPC
qor_, quindi questa chiamata restituisce-32601(metodo non trovato) su ogni endpoint pubblico oggi. Vedi il namespaceqor_.
const m = await client.qor.getCrossVmMessage(messageId);
Il precompilato bridge EVM
Il routing EVM→nativo viene eseguito on-chain tramite il precompilato del bridge cross-VM,
esposto in @qorechain/evm:
import { PRECOMPILE_ADDRESSES } from "@qorechain/evm";
console.log(PRECOMPILE_ADDRESSES.crossVmBridge);
// 0x0000000000000000000000000000000000000901
Non attivo sulla mainnet; attivo sulla testnet. Il precompilato del bridge cross-VM non è nell'elenco attivo della mainnet, quindi una chiamata a
0x…0901lì restituisce dati vuoti e non instrada nulla. L'elenco della testnet lo contiene (letto il 7 novembre 2026); il 7 novembre 2026 unaeth_callin sola lettura verso di esso ha raggiunto un contratto nella allowlist ed è stata rifiutata ("is not allowlisted") per qualsiasi altro target. Vedi Precompilati EVM: stato della rete.
Una volta attivo, un contratto Solidity (o viem) chiama il precompilato a quell'indirizzo per instradare un messaggio al livello nativo, poi ne traccia lo stato con gli helper di lettura qui sopra. Vedi la guida EVM per l'elenco completo dei precompilati.