본문으로 건너뛰기

크로스-VM 가이드

QoreChain은 EVM, SVM, QoreChain Native을 나란히 실행하며, x/crossvm 모듈을 통해 하나의 네이티브 계정이 그중 어느 것에 있는 컨트랙트라도 호출할 수 있습니다. SDK는 이러한 호출을 빌드, 서명, 브로드캐스트하기 위한 고수준 createCrossVMClient 헬퍼를 제공하며 — 여러 호출을 세 VM 전체에 걸친 하나의 원자적 트랜잭션으로 묶는 것을 포함합니다 — 메시지 상태를 추적하기 위한 타입이 지정된 읽기 헬퍼도 제공합니다. EVM 내부에서 시작되는 EVM→네이티브 라우팅은 여전히 @qorechain/evm의 크로스-VM 브리지 프리컴파일을 통해 온체인에서 실행됩니다.

현재 작동하는 것

크로스-VM 호출은 대상 레인이 사용 가능한 만큼만 사용할 수 있습니다:

  • MsgCrossVMCall은 메인넷에서 체인의 서킷 브레이커에 의해 꺼져 있습니다 (GET /cosmos/circuit/v1/disable_list에 /qorechain.crossvm.v1.MsgCrossVMCall이 나열됩니다). 테스트넷에서는 활성화되어 있습니다.
  • SVM 트랜잭션 레인은 네트워크 전체에서 비활성화되어 있고, QoreChain Native 업로드와 인스턴스화는 허가제이며(메인넷에는 컨트랙트가 없습니다), EVM 브리지 프리컴파일은 활성화되어 있지 않습니다 (EVM 프리컴파일 참조).
  • 아래의 타입이 지정된 REST 읽기 헬퍼는 공개 게이트웨이가 제공하지 않는 경로를 호출합니다. 대신 connectQueryClients(rpc).crossvm으로 메시지를 읽으세요.
  • 모든 Native 경로 트랜잭션과 마찬가지로, 크로스-VM 호출도 하이브리드 서명을 담아야 합니다. 서명 클라이언트를 계정의 키쌍과 함께 연결하면 (client.connectTx(signer, { pqcKeypair }), SDK 0.9.0 이상) 크로스-VM 클라이언트가 하이브리드로 서명합니다(계정 및 PQC 서명 참조). 0.9.0 이전 릴리스는 클래식 방식으로 서명하므로 공개 네트워크가 이를 거부합니다.

통합 크로스-VM 호출​

createCrossVMClient는 MsgCrossVMCall(타입 URL /qorechain.crossvm.v1.MsgCrossVMCall)을 래핑하므로, { typeUrl, value }를 직접 손으로 빌드하거나 페이로드를 직접 인코딩할 필요가 없습니다. 클라이언트의 sender는 연결된 TxClient의 주소이며, sourceVm은 기본적으로 "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은 "evm" | "cosmwasm" | "svm" 중 하나입니다(VM_TYPES 배열로도 내보내집니다).

VM별 페이로드 인코딩​

호출마다 정확히 하나의 페이로드 형태를 선택하세요:

형태인코딩
{ payload: Uint8Array | Hex }원시 바이트, 변경 없이 그대로 전달
{ evm: { abi, functionName, args } }viem의 encodeFunctionData로 ABI 인코딩(셀렉터 + 인자)
{ cosmwasm: object }JSON.stringify 후 UTF-8 바이트(QoreChain Native execute-msg 관례)
{ svm: { data: Uint8Array | Hex } }원시 바이트(SVM 명령어 blob)

EVM 경로는 viem을 지연 임포트하므로, 선택적 viem 피어는 실제로 { evm: ... } 페이로드를 사용할 때만 필요합니다.

빌드 전용(오프라인)​

buildCall은 브로드캐스트하지 않고 EncodeObject를 반환합니다 — 검사, 직접 배칭, 또는 다른 곳에서의 서명에 유용합니다. (EVM 페이로드는 비동기적으로 ABI 인코딩되므로, 그런 경우에는 call/callAtomic을 사용하거나 미리 인코딩하여 { payload }를 전달하세요.)

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

원자적 트리플-VM 트랜잭션​

callAtomic은 여러 MsgCrossVMCall 메시지를 하나의 트랜잭션 본문으로 묶어서 단일 서명 하에 원자적으로 실행되도록 합니다 — 바로 트리플-VM의 핵심입니다. 하나의 서명으로, EVM + SVM + QoreChain Native 전체에 걸친 호출이 모두 함께 처리되거나 전혀 처리되지 않습니다:

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

메시지 다시 읽기​

getMessage는 id로 크로스-VM 메시지를 읽으며, 타입이 지정된 쿼리 클라이언트를 우선 사용하고 qor_getCrossVMMessage JSON-RPC 메서드(공개 엔드포인트는 이를 제공하지 않습니다)로 폴백합니다. 컨센서스 RPC를 통해 읽는, 타입이 지정된 쿼리 클라이언트를 전달하세요:

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

크로스-VM 메시지 상태 읽기​

@qorechain/sdk는 x/crossvm 위의 타입이 지정된 REST 래퍼를 내보냅니다. 이들은 /qorechain/crossvm/v1/{message/{id},pending,params}를 호출하는데, 공개 게이트웨이는 이 경로를 제공하지 않으므로(api.qore.host와 api-testnet.qore.host에서 Not Implemented), 공개 엔드포인트에 대해서는 QoreHttpError를 던집니다. 이들은 해당 경로를 노출하는 노드를 위한 것이며, 공개 네트워크에서는 위의 connectQueryClients를 사용하세요.

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

이들은 타입이 지정된 형태를 반환합니다: CrossVmMessage, CrossVmMessageResponse, PendingCrossVmMessagesResponse, CrossVmParamsResponse.

노드가 제공하기 시작하면 qor_ JSON-RPC 네임스페이스를 통해 메시지를 읽을 수도 있습니다:

아직 제공되지 않음: 릴리스된 어떤 노드 빌드도 qor_ JSON-RPC 네임스페이스를 제공하지 않으므로, 이 호출은 현재 모든 공개 엔드포인트에서 -32601(메서드를 찾을 수 없음)을 반환합니다. qor_ 네임스페이스를 참조하세요.

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

EVM 브리지 프리컴파일​

EVM→네이티브 라우팅은 @qorechain/evm에 노출된 크로스-VM 브리지 프리컴파일을 통해 온체인에서 실행됩니다:

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

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

메인넷에서는 활성화되지 않음, 테스트넷에서는 활성화됨. 크로스-VM 브리지 프리컴파일은 메인넷의 활성 목록에 없으므로 그곳에서 0x…0901 호출은 빈 데이터를 반환하고 아무것도 라우팅하지 않습니다. 테스트넷의 목록에는 들어 있습니다(2026년 11월 7일 확인). 2026년 11월 7일에 이에 대한 읽기 전용 eth_call은 허용 목록에 있는 컨트랙트에 도달했고 그 밖의 대상은 거부되었습니다("is not allowlisted"). EVM 프리컴파일: 네트워크 상태를 참조하세요.

활성화되면, Solidity 컨트랙트(또는 viem)가 해당 주소의 프리컴파일을 호출하여 메시지를 네이티브 레이어로 라우팅한 다음, 위의 읽기 헬퍼로 그 상태를 추적합니다. 전체 프리컴파일 목록은 EVM 가이드를 참고하세요.