본문으로 건너뛰기

QoreChain Native 가이드

QoreChain Native는 QoreChain이 자체 CosmWasm 스마트 컨트랙트 런타임을 부르는 이름이므로, 이 페이지에 나오는 CosmWasm 라이브러리와 클라이언트 패키지가 이 런타임에서 사용하는 것들입니다.

TypeScript 코어(@qorechain/sdk)에는 QoreChain Native 컨트랙트를 쿼리하고 실행하기 위한, @cosmjs/cosmwasm-stargate 위의 얇고 타입이 지정된 래퍼가 포함되어 있습니다. 읽기에는 읽기 전용 클라이언트를 사용하고, 상태 변경에는 서명 클라이언트를 사용합니다.

읽기 전용 쿼리​

createClient() 인스턴스에서 읽기 전용 QoreChain Native 클라이언트를 엽니다 — 이는 합의 RPC 엔드포인트를 통해 연결되며 클라이언트에 메모이즈됩니다.

import {
createClient,
queryContractSmart,
getContractInfo,
} from "@qorechain/sdk";

const client = createClient({
network: "testnet",
endpoints: { rpc: "https://rpc-testnet.qore.host" }, // mainnet: https://rpc.qore.host
});

const cw = await client.cosmwasm(); // read-only CosmWasmReadClient

// Contract metadata.
const info = await getContractInfo(cw, contractAddress);

// A smart query (the message shape is contract-specific).
const result = await queryContractSmart(cw, contractAddress, { token_info: {} });

createCosmWasmClient로 읽기 클라이언트를 직접 구성할 수도 있습니다.

서명: 인스턴스화, 실행, 업로드​

업로드와 인스턴스화는 권한이 필요합니다

qorechain-vladi(메인넷)에서는 code_upload_access와 instantiate_default_permission이 Nobody로 설정되어 있으며, MsgStoreCode / MsgInstantiateContract / MsgInstantiateContract2도 체인의 서킷 브레이커에 의해 꺼져 있으므로, 일반 계정의 uploadCode와 instantiate는 거부됩니다. qorechain-diana(테스트넷, 2026년 10월 27일 확인)에서는 code_upload_access가 Nobody이고 MsgStoreCode만 꺼져 있으며, instantiate_default_permission은 Everybody이므로 이미 존재하는 코드에 대해서는 instantiate가 열려 있습니다. 이미 존재하는 컨트랙트는 쿼리(위 참고)하고 실행할 수 있습니다. 현재 권한은 GET /cosmwasm/wasm/v1/codes/params에서 확인하세요. QoreChain Native 개발을 참고하세요.

QoreChain Native 서명 클라이언트는 클래식 방식으로 서명합니다

connectCosmWasmSigner는 CosmJS 서명 클라이언트를 감싸며, 이는 클래식 secp256k1 서명만 첨부합니다. 라이브 네트워크는 모든 Native 경로 트랜잭션에 하이브리드 (secp256k1 + ML-DSA-87) 서명을 요구하므로, 이를 통해 전송한 트랜잭션은 거기서 거부됩니다. 하이브리드 확장을 요구하지 않는 노드(로컬 개발 노드)에서는 동작합니다. 라이브 네트워크에서 execute를 수행하려면 메시지를 구성하여 signAndBroadcastHybrid로 전송하세요(아래 샘플 참고).

클래식 서명을 허용하는 노드에 대한 상태 변경의 경우, connectCosmWasmSigner로 서명 클라이언트를 연결한 다음(directSignerFromPrivateKey가 생성하는 것과 동일한 종류의 오프라인 서명자를 받습니다), 타입이 지정된 래퍼를 사용하세요. 결과 타입을 지정하지 않으면 헬퍼는 Promise<unknown>을 반환합니다:

import {
connectCosmWasmSigner,
uploadCode,
instantiate,
execute,
} from "@qorechain/sdk";

const signingCw = await connectCosmWasmSigner(rpcUrl, signer);

// Upload Wasm bytecode -> a code id.
const { codeId } = await uploadCode<{ codeId: number }>(
signingCw, sender, wasmBytes, "auto",
);

// Instantiate a contract from a code id (the last argument is InstantiateOpts).
const { contractAddress } = await instantiate<{ contractAddress: string }>(
signingCw,
sender,
codeId,
{ /* init msg */ },
"label",
{ fee: "auto" },
);

// Execute a message against a deployed contract.
const res = await execute(
signingCw,
sender,
contractAddress,
{ /* execute msg */ },
"auto",
);

정확한 인자 형태는 @cosmjs/cosmwasm-stargate를 따릅니다. SDK는 타입이 지정된 ContractMsg, FeeInput, InstantiateOpts, CosmWasmReadClient, CosmWasmSigningClient 타입을 추가합니다.

라이브 네트워크에서 실행하기 (하이브리드)​

QoreChain Native 메시지 타입을 레지스트리에 추가하고 MsgExecuteContract를 하이브리드 빌더를 통해 전송합니다. 계정의 ML-DSA-87 키가 먼저 등록되어 있어야 합니다 (하이브리드 서명 참고). npm i @cosmjs/cosmwasm-stargate @cosmjs/proto-signing cosmjs-types @cosmjs/stargate가 필요합니다:

import { Registry } from "@cosmjs/proto-signing";
import { wasmTypes } from "@cosmjs/cosmwasm-stargate";
import { StargateClient } from "@cosmjs/stargate";
import { SigningCosmWasmClient } from "@cosmjs/cosmwasm-stargate";
import { MsgExecuteContract } from "cosmjs-types/cosmwasm/wasm/v1/tx";
import {
qorechainRegistryTypes,
signAndBroadcastHybrid,
derivePqcCanonical,
} from "@qorechain/sdk";

const registry = new Registry([...qorechainRegistryTypes, ...wasmTypes]);
const transport = await StargateClient.connect("https://rpc.qore.host");
const info = await transport.getSequence(sender);

// Never hardcode gas for a contract call: simulate it, then add at least 30%.
// The simulation already includes the cost of loading the contract code and a
// congestion margin (see "Gas for contract calls" below).
const cwClient = await SigningCosmWasmClient.connectWithSigner(
"https://rpc.qore.host",
signer,
);
const msgs = [
{
typeUrl: "/cosmwasm.wasm.v1.MsgExecuteContract",
value: MsgExecuteContract.fromPartial({
sender,
contract: contractAddress,
msg: new TextEncoder().encode(JSON.stringify({ /* execute msg */ })),
funds: [],
}),
},
];
const simulatedGas = await cwClient.simulate(sender, msgs, undefined);
const gas = Math.ceil(simulatedGas * 1.3);
const gasPrice = 0.15; // uqor per unit of gas; the network floor is 0.1

const result = await signAndBroadcastHybrid({
registry,
signer, // from directSignerFromPrivateKey
pqcKeypair: derivePqcCanonical(sender, mnemonic), // the key registered on-chain
messages: msgs,
fee: {
amount: [{ denom: "uqor", amount: String(Math.ceil(gas * gasPrice)) }],
gas: String(gas),
},
chainId: "qorechain-vladi",
accountNumber: info.accountNumber,
sequence: info.sequence,
rest: "https://api.qore.host",
transport,
});

컨트랙트 호출 가스​

컨트랙트 호출의 가스를 하드코딩하지 마세요. 고정값 400,000은 한 번의 단순 전송에는 충분하지만 다음 호출에서는 부족해집니다. 릴리스 v3.2.8부터(이후 메인넷 업그레이드 전까지는 테스트넷 전용) CosmWasm 가스가 재산정됩니다.

  • 블록에서 컨트랙트 코드를 처음 호출할 때는 로드 비용이 부과됩니다. cw20 전송은 블록 내 해당 코드의 첫 호출로서 약 533,000 가스, 반복 호출마다 약 84,000 가스가 듭니다. 거버넌스는 자주 쓰는 코드를 고정(pin)할 수 있으며, 고정된 코드는 로드 비용이 면제됩니다.
  • 수수료는 혼잡에 따라 오릅니다. 블록이 컨트랙트 호출로 바쁠 때 혼잡 계수가 컨트랙트 가스를 기본적으로 1배에서 최대 20배까지 조정하며, 블록에는 제한된 컨트랙트 실행 예산이 있고 한 트랜잭션은 그 절반까지만 사용할 수 있습니다.
  • 시뮬레이션에는 둘 다 포함됩니다. 시뮬레이션은 항상 콜드 로드 비용을 부과하고 혼잡에 대한 여유분을 더하므로, 시뮬레이션 가스 x 1.3이 안전한 한도입니다. 클라이언트가 제공하면 fee: "auto"를 사용하고(CosmJS "auto", SDK TxClient, React useTx 훅), 위와 같이 수수료를 직접 구성할 때는 직접 시뮬레이션하세요.
  • 트랜잭션 상한 아래로 유지하세요. Cosmos 트랜잭션은 가스 한도를 50,000,000을 넘게 설정할 수 없으며, 수수료가 청구되기 전에 거부됩니다. SDK 0.14.0은 이런 한도(와 30,000,000을 넘는 EVM 트랜잭션)를 서명 전에 거부하고, CosmWasm 및 크로스 VM 트랜잭션에는 시뮬레이션된 가스의 1.3배 이상을 부여하며, 이들에 고정 가스 한도로 대체하지 않습니다. 또한 네트워크의 최소 가스 가격을 읽는 선택 사용 헬퍼가 있으며, 기본 가스 가격은 바뀌지 않았습니다.

instantiate, migrate 및 컨트랙트 코드를 실행하는 모든 다른 메시지에도 동일하게 적용됩니다.

실행 가능한 읽기 예제는 cosmwasm-query 예제를 참고하세요.