본문으로 건너뛰기

React 키트 (@qorechain/react)

@qorechain/react는 @qorechain/sdk 위에 얹은 공식 React 레이어입니다. 하나의 프로바이더, 몇 개의 훅, 그리고 즉시 사용 가능한 두 개의 컴포넌트(한 줄짜리 PQC 상태 배지 포함)를 제공합니다. 하이브리드 ML-DSA-87 서명을 사용하는 dApp을 만드는 것을 기본 경로로 만듭니다.

npm i @qorechain/react @qorechain/sdk react react-dom

react(>=18)는 피어 의존성이며, @qorechain/sdk는 직접 의존성입니다(키트 0.14.0부터 ^0.14.0. 0.x 버전에서 캐럿은 0.14 안에 머무르므로 SDK 패치가 두 번째 사본을 설치하지 않습니다). @qorechain/react 0.14.0을 사용하세요(0.9.0 이상도 같은 방식으로 동작합니다). 0.8.0은 SDK 0.8.0에 고정되어 있는데, 이 버전은 메인넷에서 잘못된 하이브리드 형식으로 서명하며, 그 이전의 0.8.x 릴리스는 주소 변경 후 오래된 잔액이나 상태를 표시할 수 있습니다.

React 키트(0.9.0~0.14.0)의 라이브 네트워크 제한 사항

useTx는 지갑의 서명자로 연결하며 포스트 양자 키쌍은 사용하지 않으므로 클래식 서명만으로 전송하는데, 라이브 네트워크는 이를 거부합니다(Native 경로는 하이브리드 ML-DSA-87 확장을 요구합니다). 따라서 send / sendTokens로는 메인넷이나 테스트넷에 트랜잭션을 반영할 수 없습니다. 전송에는 SDK의 하이브리드 TxClient (client.connectTx(signer, { pqcKeypair }), 하이브리드 서명 참고)를 사용하세요. usePqcStatus와 <PqcStatusBadge/>는 프로바이더의 구성된 클라이언트와 함께 getPqcStatus를 통해 상태를 읽는데, SDK 0.9.0부터 이는 REST (/qorechain/pqc/v1/account/{address})로 읽으므로 *.qore.host에 대해서도 작동합니다(키트 0.8.x는 퍼블릭 엔드포인트가 제공하지 않는 qor_getPQCKeyStatus를 읽었고, 그곳에서는 키를 확인할 수 없었습니다). 잔액 조회(useBalance)와 지갑 연결은 작동합니다.

프로바이더​

앱을 QoreChainProvider로 한 번 감싸세요. 이는 단일 createClient() 인스턴스와 모든 훅이 읽어 가는 실시간 월렛 연결 상태를 보유합니다.

import { QoreChainProvider } from "@qorechain/react";

function Root() {
return (
<QoreChainProvider
config={{
network: "testnet",
endpoints: {
rpc: "https://rpc-testnet.qore.host",
rest: "https://api-testnet.qore.host",
evmRpc: "https://evm-testnet.qore.host",
},
}}
>
<App />
</QoreChainProvider>
);
}

런타임에 네트워크를 전환하려면 다른 React key로 프로바이더를 다시 마운트하세요. 테스트의 경우 config 대신 미리 빌드된(또는 모킹된) client prop을 전달하세요.

훅​

훅반환값
useQoreClient()임시 읽기를 위한 구성된 QoreChainClient.
useAccount(){ addresses, address, isConnected, status, wallet } — 네이티브 / EVM / SVM 주소.
useBalance(address?, options?){ data, isLoading, error, refetch }; refreshInterval을 통한 자동 새로고침.
useConnect() / useWallet(){ connect, disconnect, status, isConnecting, error }.
useTx(){ send, sendTokens, status, data, error, isPending, reset }.
usePqcStatus(address?, options?){ data, isRegistered, isLoading, error, refetch }.

월렛 연결​

useConnect는 기존 SDK 어댑터를 래핑합니다:

const { connect } = useConnect();
await connect({ kind: "keplr" }); // or "leap" | "evm" | "svm"
  • keplr / leap — getCosmosWallet을 통한 Cosmos 월렛. 체인을 제안하고 활성화하며, TxClient에 연결된 서명자를 반환하므로 useTx가 즉시 서명할 수 있습니다. addresses.native를 설정합니다.
  • evm — eth_requestAccounts를 통한 모든 주입형 EIP-1193 프로바이더 (window.ethereum, 예: MetaMask). addresses.evm을 설정합니다.
  • svm — connect()를 통한 모든 주입형 Wallet-Standard 프로바이더 (window.solana, 예: Phantom). addresses.svm을 설정합니다.

EVM 및 SVM 경로는 주입된 프로바이더의 표준 request API를 직접 사용하므로 viem이나 Solana SDK가 끌려 들어오지 않습니다. 테스트용 월렛을 주입하려면 connect 옵션에 provider를 전달하세요. 각 VM별 전체 도구가 필요하면 @qorechain/evm / @qorechain/svm과 함께 사용하세요.

트랜잭션 전송​

import { msg } from "@qorechain/sdk";
import { useTx } from "@qorechain/react";

function Send() {
const { sendTokens, isPending } = useTx();
return (
<button
disabled={isPending}
onClick={() =>
sendTokens("qor1recipient…", [{ denom: "uqor", amount: "1000000" }])
}
>
Send 1 QOR
</button>
);
}

send([{ typeUrl, value }], opts)는 단순 bank 전송을 넘어서는 작업을 위해 msg.* 컴포저의 원시 메시지를 받습니다.

컴포넌트​

<ConnectButton/>​

최소한의, 거의 헤드리스에 가까운 연결 / 연결 해제 컨트롤입니다. 선택기를 제공하려면 wallets를, 테마를 지정하려면 className / style을, 완전한 제어를 위해서는 children render-prop을 전달하세요:

<ConnectButton wallets={["keplr", "leap", "evm"]} />

<PqcStatusBadge/>​

주소에 등록된 포스트 양자 키가 있을 때(usePqcStatus를 통해) 상태 표시를 보여주고, 그렇지 않으면 흐릿한 "등록되지 않음" 상태를 보여줍니다. 기본값은 연결된 계정입니다. 기본 레이블은 "PQC key registered"와 "No PQC key"이며 (safeLabel / unsafeLabel로 재정의), 루트 요소는 같은 값을 갖는 data-pqc-status와 data-quantum-safe를 가집니다.

<PqcStatusBadge />
<PqcStatusBadge address="qor1…" hideWhenUnsafe />

PqcStatusBadge는 키트 0.11.0에서 도입되었습니다. QuantumSafeBadge(QuantumSafeBadgeProps, QuantumSafeRenderState 포함)는 같은 컴포넌트의 더 이상 사용되지 않는 별칭으로 계속 내보내지므로 기존 코드는 그대로 동작합니다.

한데 엮기​

import {
ConnectButton,
PqcStatusBadge,
useAccount,
useBalance,
} from "@qorechain/react";

function Dashboard() {
const { address, isConnected } = useAccount();
const { data: balance } = useBalance(undefined, { refreshInterval: 10_000 });
return (
<>
<ConnectButton wallets={["keplr", "leap", "evm"]} />
{isConnected && (
<p>
{balance?.amount ?? "…"} {balance?.denom} <PqcStatusBadge />
</p>
)}
</>
);
}

실행 가능한 react-dapp 예제와 기반이 되는 SDK 호출은 하이브리드 서명 가이드를 참고하세요.