거래소 및 통합자 가이드

거래소, 커스터디언, 결제 통합자가 QOR을 상장하고 입출금을 처리하는 데 필요한 모든 것: 인터페이스 선택, 안전한 입금 감지, 출금 서명.

노트

이 가이드는 qorechain-vladi 메인넷(체인 버전 v3.1.85)을 대상으로 합니다. 먼저 qorechain-diana 테스트넷에서 전체 흐름을 리허설하세요 — 두 네트워크의 엔드포인트는 네트워크에 있습니다. 자체 풀 노드를 운영하는 경우 노드를 현재 체인 버전으로 유지하세요 — 오래된 노드는 새로운 트랜잭션 유형을 디코딩하지 못하고 동기화가 중단됩니다.

통합 경로 선택

QoreChain은 세 가지 인터페이스를 통해 노출되는 하나의 통합 네이티브 QOR 잔액을 가진 단일 체인입니다. 동일한 개인 키가 동일한 자금을 제어하며, Cosmos(qor1...), EVM(0x...), SVM(base58) 주소 아래에 있습니다 — 여러분의 스택에 맞는 인터페이스를 선택하세요.

	A) Cosmos (네이티브)	B) EVM	C) SVM (Solana VM)
주소	`qor1...` (bech32)	`0x...` (Ethereum)	Solana base58 (동일 키)
소수 자릿수 (네이티브 QOR)	6 (`uqor`)	18 (wei 방식)	9 (lamports; 1 uqor = 1,000 lamports)
툴링	Cosmos SDK / CosmJS	표준 Ethereum (ethers/web3, MetaMask)	`@solana/web3.js`
출금 서명	하이브리드 PQC 필수 (ML-DSA-87 + secp256k1)	표준 secp256k1 / EIP-155 — PQC 불필요	Cosmos 트랜잭션 또는 노드에서 직접 제출
메모 / 태그 지원	예 (공유 주소 + 메모)	아니요 (사용자당 주소 1개)	아니요 (사용자당 주소 1개)
입금 감지	`MsgSend` 이벤트 스캔	`eth_getBlockByNumber`로 블록 스캔	`getBalance` / `getSignaturesForAddress`
적합한 대상	Cosmos 네이티브 플랫폼	기존 EVM 통합을 보유한 플랫폼	Solana 툴링 플랫폼

권장 사항: 이미 EVM 체인을 지원한다면 경로 B(EVM) 가 가장 적은 노력으로 통합할 수 있는 방법입니다 — 표준 Ethereum 툴링을 사용하며, 출금에 포스트 양자 서명이 필요하지 않습니다(EVM ante 경로는 면제됨). 경로 A(Cosmos)는 메모 기반 공유 입금 주소를 사용하는 네이티브 경로입니다. 경로 C(SVM)도 완전한 네이티브 QOR 인터페이스이며, 특별히 Solana 툴링을 선호하는 경우 선택하세요.

세 인터페이스는 상호 배타적이지 않습니다 — 동일한 키의 0x, qor1, SVM 형태로 보내진 자금은 동일한 잔액입니다.

노드 운영

프로덕션 통합에서는 서드파티 엔드포인트가 아닌 자체 동기화된 노드를 통해 입금을 검증해야 합니다. 메인넷 연결하기를 따르세요 — 사전 빌드된 바이너리 번들(SHA-256 체크섬 포함), 제네시스, 공개 피어, 수수료 하한(0.1uqor), 게시된 체인 데이터 스냅샷을 통한 빠른 부트스트랩을 다룹니다. 비검증 풀 노드 운영에는 라이선스가 필요하지 않습니다.

QoreChain은 즉시 완결성(리오그 없음)을 가지므로 1 컨펌이 곧 최종이며, 1–2 블록을 기다리면 충분한 운영상의 여유를 확보할 수 있습니다.

경로 A — Cosmos (네이티브)

기본 REST URL: https://api.qore.host (또는 자체 노드의 http://localhost:1317).

입금 모니터링

# latest height
curl -s https://rpc.qore.host/status | jq -r .result.sync_info.latest_block_height

# all txs in a height (deposit scanning)
curl -s "https://api.qore.host/cosmos/tx/v1beta1/txs/block/{HEIGHT}" | jq '.txs'

# incoming transfers to an address
curl -s "https://api.qore.host/cosmos/tx/v1beta1/txs?query=transfer.recipient='qor1...'&pagination.limit=50" | jq '.tx_responses[].txhash'

# balance (uqor — divide by 1e6 for QOR)
curl -s "https://api.qore.host/cosmos/bank/v1beta1/balances/qor1.../by_denom?denom=uqor" | jq -r .balance.amount

가짜 입금 방지 체크리스트

다음 조건이 모두 충족될 때에만 입금을 반영하세요:

tx_response.code == 0 — 트랜잭션이 성공했습니다. 실패한 트랜잭션은 절대 반영하지 마세요.
메시지가 /cosmos.bank.v1beta1.MsgSend(또는 MsgMultiSend 출력)여야 합니다 — 컨트랙트 호출이나 다른 모듈이 아닙니다.
to_address 가 여러분의 입금 주소와 일치하고, (공유 주소 모델의 경우) memo 가 해당 사용자와 일치해야 합니다.
denom == "uqor" 이고 amount가 반영할 금액이어야 합니다(uqor → QOR로 환산 시 ÷ 10⁶). 다른 denom은 모두 거부하세요.
트랜잭션이 커밋된 블록에 포함되어야 합니다(height가 존재하고 최신 커밋 높이 이하). 완결성은 즉시입니다 — 1 컨펌이 곧 최종이며, 여유를 위해 1–2 블록을 기다리세요.
전송 이벤트(coin_received / coin_spent)에서 금액을 재계산하고 메시지 금액과 교차 검증하세요 — 단일 필드나 메모만 신뢰해서는 안 됩니다.
자체 동기화된 노드에 대해 GET /cosmos/tx/v1beta1/txs/{hash}로 트랜잭션 해시가 존재하는지 확인하세요.

출금 — 하이브리드 PQC 서명

메인넷은 cosmos 트랜잭션에 대해 포스트 양자 서명을 강제합니다(allow_classical_fallback = false): 모든 출금에는 하이브리드 서명이 필요합니다 — ML-DSA-87(Dilithium-5, FIPS-204) 및 secp256k1. 입금에는 이것이 필요하지 않습니다(체인을 모니터링만 하면 됩니다).

서명 라이브러리는 @qorechain/wallet-adapter(npm)이며, FIPS-204 프리미티브를 위해 @qorechain/pqc를 함께 가져옵니다:

npm i @qorechain/wallet-adapter @qorechain/pqc @cosmjs/proto-signing cosmjs-types@0.9.0
# pin cosmjs-types to 0.9.x — 0.10 breaks the subpath imports the adapter uses

서명은 2단계 흐름입니다(qorechaind tx pqc cosign을 반영):

1단계 — 핫 월렛당 1회: ML-DSA-87 키 등록. 이 단일 등록 트랜잭션은 클래식 서명됩니다(부트스트랩 예외): 메시지 /qorechain.pqc.v1.MsgRegisterPQCKeyV2와 {sender, public_key, algorithm_id: 1, key_type: "hybrid"}. 기존 시크릿에서 복구할 수 있도록 ML-DSA 키를 결정론적으로 파생하세요 — 예: seed = SHAKE-256("qorechain:pqc:v1|" + address + "|" + mnemonic), 그다음 mldsa.keygen(seed) — 그리고 시드를 핫 월렛 키와 함께 보관하세요.

2단계 — 이후 모든 출금: MsgSend를 하이브리드 서명. 어댑터는 일반 secp256k1 signDirect 이전에 ML-DSA-87 서명을 tx-body 확장에 넣으므로, 기존 서명자는 변경 없이 그대로 유지됩니다:

import { QoreChainSigner } from "@qorechain/wallet-adapter";
import { MsgSend } from "cosmjs-types/cosmos/bank/v1beta1/tx.js";

// pqc = { publicKey, secretKey } from mldsa.keygen(seed)
// accountNumber + sequence from the auth query
const signer = new QoreChainSigner({ wallet, chainId: "qorechain-vladi",
  address, pubkeySecp256k1, accountNumber, pqc });
const txBytes = await signer.signHybrid({
  messages: [{ typeUrl: "/cosmos.bank.v1beta1.MsgSend",
    value: MsgSend.encode(MsgSend.fromPartial({ fromAddress, toAddress,
      amount: [{ denom: "uqor", amount: "1000000" }] })).finish() }],
  fee: { amount: [{ denom: "uqor", amount: "40000" }], gasLimit: 400000n },
  sequence });

서명된 바이트를 브로드캐스트하세요:

curl -s -X POST https://api.qore.host/cosmos/tx/v1beta1/txs \
  -H 'Content-Type: application/json' \
  -d '{"tx_bytes":"<base64-signed-tx>","mode":"BROADCAST_MODE_SYNC"}' | jq .tx_response.code
# 0 => accepted into the mempool
# code 8 "classical fallback not allowed" => step 1 not done yet for this account

그다음 GET /cosmos/tx/v1beta1/txs/{hash}를 폴링하여 code == 0으로 블록에 나타날 때까지 기다리세요.

HSM이나 다른 언어의 커스텀 서명자를 사용하는 경우, 독립형 qorechain-pqc FIPS-204 라이브러리(npm, PyPI, crates.io, Maven Central, Go)를 사용하여 동일한 확장을 조립하세요. ML-DSA 서명은 반드시 결정론적이어야 합니다(FIPS-204 §3.4) — 결정론적 서명을 참조하세요. 체인은 hedged 서명을 거부합니다.

서버 사이드 대안: `@qorechain/chain-bridge`

완전히 서버 사이드에서 동작하는 핫 월렛 워커(브라우저 지갑 불필요)의 경우, @qorechain/chain-bridge(npm)가 전체 흐름 — 키 파생, 최초 사용 시 PQC 자동 등록, 하이브리드 서명, 브로드캐스트 — 을 하나의 호출로 감쌉니다. 순수 JavaScript(네이티브 애드온 없음)이므로 서버리스 워커에 적합합니다:

import { ChainBridge } from "@qorechain/chain-bridge";

const bridge = new ChainBridge({
  cosmosRpc: "https://rpc.qore.host",       // or your own node
  chainId: "qorechain-vladi",
  signerMnemonic: process.env.HOT_WALLET_MNEMONIC,  // from your secrets manager
});

// One call: derives the canonical ML-DSA-87 key, auto-registers it if missing,
// hybrid-signs the MsgSend, and broadcasts. Amounts are in uqor (6 decimals).
const { txHash } = await bridge.sendTokens({
  to: "qor1recipient...",
  amountUqor: "1000000",   // 1 QOR
});

chain-bridge(≥0.1.1)는 스택의 나머지와 동일한 정식(canonical) 주소 결합 PQC 파생 — SHAKE-256("qorechain:pqc:v1|address|mnemonic") — 을 사용하므로, qorechaind tx pqc recover-key로 니모닉에서 키를 복구할 수 있습니다. 이전 툴링으로 등록된 계정은 자동으로 처리되며(레거시 키 폴백), MsgRotatePQCKey로 정식 키로 한 번에 마이그레이션할 수 있습니다.

경로 B — EVM

https://evm.qore.host(체인 ID 9801) 또는 자체 노드의 8545 포트를 대상으로 하는 표준 Ethereum 통합입니다.

소수 자릿수: 네이티브 QOR은 EVM 레일에서 18 자릿수입니다(1 uqor = 10¹² wei). 이를 잘못 처리하면 입금이 10¹² 배만큼 잘못 반영됩니다.
입금: eth_getBlockByNumber로 블록을 스캔하여 여러분의 주소로 향하는 네이티브 전송을 찾고, eth_getTransactionReceipt(status == 0x1)로 확인하세요.
출금: 표준 secp256k1 / EIP-155 서명 — EVM ante 경로에서는 PQC가 필요하지 않습니다. 모든 Ethereum 서명 스택이 변경 없이 동작합니다.
가짜 입금 방지: 영수증 상태를 검증하고, 이동한 값이 (인덱싱하지 않는 ERC-20 이벤트가 아닌) 네이티브 전송인지 확인하고, 자체 노드에 대해 확인하세요.
주소 매핑: 0x 주소와 qor1 주소는 동일한 계정의 두 가지 인코딩이며 자금은 공유됩니다. EVM 개발을 참조하세요.

경로 C — SVM (Solana 호환)

v3.1.82부터 SVM 인터페이스는 네이티브 QOR을 제공합니다(SVM 인터페이스의 네이티브 QOR 참조):

잔액: getBalance는 lamports를 반환합니다(QOR로 환산 시 ÷ 10⁹; 1 uqor = 1,000 lamports).
입금: getSignaturesForAddress는 주소의 트랜잭션 기록을 제공합니다. System Program 전송이 네이티브 QOR을 이동시킵니다.
공개 엔드포인트(https://svm.qore.host, https://svm-testnet.qore.host)는 읽기 전용입니다. 트랜잭션은 자체 노드를 통해 제출하세요.

흐름 요약

작업	경로	서명 필요 여부
입금 (사용자 → 플랫폼)	동기화된 노드에서 여러분의 주소로 향하는 전송을 모니터링 (Cosmos에서는 + 메모)	아니요 — 모니터링만
출금 (플랫폼 → 사용자)	전송 구성, 오프라인 서명, 브로드캐스트	Cosmos: 하이브리드 PQC · EVM: 표준 secp256k1
잔액 / 스윕	REST / EVM / SVM 잔액 조회 + 전송	스윕 시에만 서명

통합 경로 선택​

노드 운영​

경로 A — Cosmos (네이티브)​

입금 모니터링​

가짜 입금 방지 체크리스트​

출금 — 하이브리드 PQC 서명​

서버 사이드 대안: @qorechain/chain-bridge​

경로 B — EVM​

경로 C — SVM (Solana 호환)​

흐름 요약​

관련 문서​