Passa al contenuto principale

Multi-VM (chiamate cross-VM)

L'RDK include helper TypeScript che codificano una chiamata da un contratto EVM al precompile cross-VM all'indirizzo 0x0000000000000000000000000000000000000901, progettato per instradarla verso un contratto QoreChain Native sul runtime QoreChain Native (Wasm), e un template di scaffold multivm-rollup che li collega. Gli strumenti coprono soltanto EVM → QoreChain Native; SVM è un runtime separato e non fa parte del precompile.

Non ancora utilizzabile sulle reti live

Il precompile cross-VM non è attivato sulla mainnet: l'elenco dei precompile statici attivi del modulo EVM è vuoto lì (verificato il 4 novembre 2026). Sulla testnet l'elenco conteneva solo 0x…0A01, 0x…0A02 e 0x…0C01 quando è stato verificato il 27 ottobre 2026, e anche 0x…0901 dal 4 novembre; è stato riletto il 7 novembre 2026 e li elenca ancora tutti e quattro (vedi la nota sotto Chain v3.2.5). Il 7 novembre 2026, dopo che la testnet ha applicato la chain v3.2.7, è stata testata una eth_call in sola lettura verso 0x…0901 sulla testnet: un target nella allowlist ha raggiunto il suo contratto e un target fuori da essa è stato rifiutato (vedi Testato sulla testnet). Sulla mainnet eth_getCode per 0x…0901 restituisce 0x, e una chiamata ad esso riesce con dati vuoti e non esegue nulla (una eth_call verso di esso ha restituito dati vuoti il 4 novembre 2026). Anche il caricamento di contratti QoreChain Native è chiuso su entrambe le reti, e la corsia di transazioni SVM è disabilitata su tutta la rete. Sulla mainnet, finché il precompile non sarà attivato e i caricamenti QoreChain Native non saranno riaperti, non c'è nulla da chiamare; sulla testnet il precompile è attivo con una allowlist ed è stato testato con eth_call. Questa pagina documenta gli strumenti in modo che tu possa prepararti; non costruire flussi di produzione su di essi. Vedi Precompile EVM: stato della rete.

Dalla 0.6.0 l'encoder corrisponde al layout della chain

encodeCrossVmCalldata in @qorechain/rdk 0.5.0 e precedenti (e lo starter CrossVmCaller.sol nel template multivm-rollup di quelle release) usava executeCrossVMCall(string,bytes), un selettore di funzione diverso da quello che il nodo decodifica, quindi nessuna chiamata da esso codificata avrebbe potuto raggiungere il precompile nemmeno su una rete che l'avesse attivato. La 0.6.0 codifica executeCrossVMCall(uint8 targetVM, string targetContract, bytes payload) (selettore 0x3c11078c), che è ciò che il nodo decodifica (selettore di 4 byte, poi gli argomenti codificati ABI; targetVM 1 è QoreChain Native, l'unico target supportato), e secondo le note di rilascio i calldata dell'helper passano il round-trip attraverso il decoder della chain stessa. L'ABI potrebbe ancora cambiare prima dell'attivazione.

nota

A partire da RDK v0.4.2 l'identificatore dell'opzione VM del runtime Wasm è native (QoreChain Native); cosmwasm rimane un alias legacy accettato, ed entrambi vengono mappati su cosmwasm a livello di protocollo.

L'indirizzo del precompile​

import { CROSS_VM_PRECOMPILE } from "@qorechain/rdk";

console.log(CROSS_VM_PRECOMPILE); // 0x0000000000000000000000000000000000000901

Codifica di una chiamata cross-VM​

Codifica direttamente il layout del nodo. payload è il messaggio di esecuzione del contratto come byte JSON UTF-8 (mostrato con viem):

import { encodeFunctionData, parseAbi, toHex } from "viem";

const abi = parseAbi([
"function executeCrossVMCall(uint8 targetVM, string targetContract, bytes payload)",
]);

const calldata = encodeFunctionData({
abi,
functionName: "executeCrossVMCall",
args: [
1, // QoreChain Native
"qor1cosmwasmcontractaddress...",
toHex(new TextEncoder().encode(JSON.stringify({ transfer: { recipient: "qor1...", amount: "100" } }))),
],
});

encodeCrossVmCalldata di @qorechain/rdk 0.6.0 e successive (la 0.8.0 è la release attuale) costruisce per te gli stessi calldata:

import {
CROSS_VM_PRECOMPILE,
CROSS_VM_TARGET,
encodeCrossVmCalldata,
isCrossVmPrecompileActive,
} from "@qorechain/rdk";

// Ask the node first: today this answers `active: false` on both networks.
const status = await isCrossVmPrecompileActive("https://api.qore.host");
console.log(status.active, status.reason);

const calldata = encodeCrossVmCalldata({
contract: "qor1cosmwasmcontractaddress...",
msg: JSON.stringify({ increment: {} }),
targetVm: CROSS_VM_TARGET.NATIVE, // 1 = QoreChain Native (CosmWasm); the default
});
// An EVM transaction to CROSS_VM_PRECOMPILE with `data: calldata`.

isCrossVmPrecompileActive(restBase) legge via REST il parametro EVM active_static_precompiles e risponde active: true solo quando l'indirizzo del precompile è elencato. È l'unico controllo affidabile e deve avvenire off-chain: il precompile restituisce la risposta grezza del target, quindi una risposta vuota non permette di distinguere un precompile inattivo da una chiamata genuina a un contratto che non restituisce nulla, e un precompile non ha bytecode che sia attivo o no. Anche quando riporta active: true, il pacchetto documenta che dalla v3.2.3 della chain una chiamata raggiunge solo i target in allowlist per la governance (il parametro cross-VM bridge_allowed_targets, ogni voce <vm>:<contract>), e che EVM-verso-EVM viene rifiutato.

Testnet cambiata dopo il 30 ottobre 2026

Il 4 novembre 2026 l'elenco dei precompile attivi della testnet (active_static_precompiles nei parametri EVM) conteneva anche 0x…0901, e GET /qorechain/crossvm/v1/params sulla testnet elencava tre target CosmWasm in bridge_allowed_targets. La mainnet quel giorno non era cambiata: elenco dei precompile attivi vuoto, allowlist vuota, e una chiamata a 0x…0901 tramite eth_call ha restituito dati vuoti. L'elenco della testnet è stato riletto il 7 novembre 2026 e contiene ancora 0x…0901. Le affermazioni qui sotto secondo cui il precompile o l'allowlist sono inattivi o vuoti sulla testnet descrivono il periodo dal 27 al 30 ottobre 2026; il comportamento attuale della testnet è in Testato sulla testnet.

Chain v3.2.5: allowlist, formato della risposta e rifiuti (entrambe le reti)​

La chain v3.2.5 cambia il comportamento del bridge. Il mainnet la esegue dal 29 ottobre 2026 (proposta di governance 14, altezza 3.906.833) e il testnet dal 26 ottobre; la mainnet esegue ora la v3.2.7 e la testnet la v3.2.8. Poiché il precompile non è attivo sulla mainnet, il formato della risposta descritto sotto è il comportamento della release e non è stato verificato lì; il formato dei rifiuti è stato osservato sulla testnet il 7 novembre 2026 (vedi Testato sulla testnet). Ovunque questa pagina dica che il precompile restituisce la risposta grezza del target, ciò descrive le release precedenti alla v3.2.5.

  • Una route per l'allowlist. GET /qorechain/crossvm/v1/params serve i parametri del bridge, inclusa l'allowlist dei target. Sulla mainnet l'allowlist è vuota (verificato il 4 novembre 2026), quindi nessun target è ancora consentito; sulla testnet era vuota il 30 ottobre (vedi la nota sopra).
  • Un formato di risposta fisso. Il precompile restituisce abi.encode(bytes), quindi una risposta è sempre di almeno 64 byte e una risposta vuota si distingue da una assente; decodificala con abi.decode(ret, (bytes)).
  • I rifiuti riportano un motivo. Quando il bridge rifiuta una chiamata, fa revert con Error(string), che un contratto può leggere e inoltrare.
  • Attivo sulla testnet, non sulla mainnet. 0x...0901 non è nell'elenco dei precompile attivi della mainnet; l'elenco della testnet lo contiene (letto il 7 novembre 2026), e il rifiuto e il comportamento dell'allowlist sono stati testati lì in quel giorno. La mainnet mantiene disattivate le chiamate cross-VM fino a una decisione di governance separata, anche dopo l'upgrade alla v3.2.7 (applicato sulla mainnet il 12 novembre 2026; il messaggio di chiamata cross-VM resta in pausa tramite il circuit breaker).

Testato sulla testnet​

La testnet esegue la chain v3.2.8 dal 12 novembre 2026 (altezza 9.929.500). Il 7 novembre 2026 sono state inviate a 0x…0901 due richieste eth_call in sola lettura con i calldata di executeCrossVMCall(uint8,string,bytes) (VM di destinazione 1, payload {}):

TargetRisultato
Un indirizzo CosmWasm che non è in bridge_allowed_targetsRevert con cross-VM bridge call refused: target cosmwasm:<address> is not allowlisted
Un contratto CosmWasm presente in bridge_allowed_targetsLa chiamata ha raggiunto il contratto, che ha rifiutato il payload vuoto (Error parsing into type cw20::msg::Cw20ExecuteMsg), quindi il bridge l'ha consegnata; non è stato inviato alcun messaggio che il contratto accetti

Questo mostra l'allowlist e il motivo del revert. Non mostra una chiamata riuscita che modifica lo stato, perché eth_call non modifica nulla e il payload non era volutamente un messaggio valido. Il precompile accetta tre argomenti; la forma a due argomenti della 0.5.0 e precedenti non lo raggiunge. La mainnet non ha questo comportamento: lì il precompile è disattivato.

@qorechain/rdk 0.7.0 e successive hanno helper per questi aspetti (verificati rispetto a codifiche prodotte da Solidity): getCrossVmParams (l'allowlist), crossVmTargetReady (precompile attivo, bridge abilitato e target in allowlist, con il motivo del blocco quando non lo è), decodeCrossVmResult (abi.decode(ret, (bytes))) e decodeRevertReason (Error(string)).

Il lato Solidity​

Da un contratto EVM chiami l'indirizzo del precompile con la chiamata codificata:

address constant CROSS_VM_PRECOMPILE = 0x0000000000000000000000000000000000000901;

function callCosmWasm(string calldata contractAddr, bytes calldata msg_)
external returns (bytes memory)
{
bytes memory data = abi.encodeWithSignature(
"executeCrossVMCall(uint8,string,bytes)", uint8(1), contractAddr, msg_
);
(bool ok, bytes memory ret) = CROSS_VM_PRECOMPILE.call(data);
require(ok, "cross-VM call failed");
return ret;
}

Poiché il precompile è inattivo sulla mainnet, una semplice .call verso di esso lì restituisce successo con dati vuoti e non fa nulla; il flag ok non indica che la chiamata abbia avuto effetto. La protezione affidabile all'interno del contratto è un target che restituisce sempre una conferma non vuota, con un require(ret.length > 0) dopo la chiamata, in modo che una risposta vuota sia trattata come un fallimento; il template multivm-rollup fa così (dalla 0.6.0 in poi).

Scaffold di un rollup multi-VM​

npm create qorechain-rollup my-app -- --template multivm-rollup

Il template multivm-rollup include src/crossvm-call.ts (verifica se il precompile è attivo, poi stampa i calldata) e un contracts/CrossVmCaller.sol che chiama executeCrossVMCall(uint8,string,bytes) e richiede una risposta non vuota dal target. Dalla 0.7.0 il contratto decodifica il risultato abi.encode(bytes), richiede il minimo di 64 byte che restituisce un precompile attivo e inoltra il motivo del rifiuto della chain. Non fa funzionare una chiamata finché il precompile è inattivo. Vedi Distribuire un rollup per tutti i template dello scaffolder.