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 릴리스는 주소 변경 후 오래된 잔액이나 상태를 표시할 수
있습니다.
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 호출은 하이브리드 서명 가이드를 참고하세요.