인증자(Authenticator)와 위임 지출
인증자 레인(SDK 0.7.0, 체인 v3.1.85)을 사용하면 연결된 외부 키 — Phantom ed25519 키 또는 MetaMask / EVM secp256k1 키 — 가 최소 권한, 지출 한도, 철회 가능한 조건 하에서 단 하나의 정식(canonical) PQC 필수 계정에서 지출할 수 있으며, 외부 키가 ML-DSA 공동 서명을 생성할 필요가 전혀 없습니다.
이는 체인의 계정 추상화 모듈에 대응하는 SDK 기능입니다.
x/abstractaccount 모듈은 qorechain-vladi(메인넷)에서 비활성화되어
있습니다. GET /qorechain/abstractaccount/v1/config가 "enabled": false를
반환합니다. 체인 v3.2.0부터 이 플래그는 모든 경로(추상 계정 생성, 인증자 연결,
MsgExecuteEVM / MsgExecuteCosmos 모두)에서 강제되며, 체인은 이러한 요청을
abstract account module is disabled(코드 9)로 거부합니다. 어떤 트랜잭션으로도
이를 켤 수 없습니다. qorechain-diana 테스트넷에서는 2026년 10월 27일에 같은
경로가 "enabled": true를 반환했으므로, 아래 흐름을 그곳에서 시험해 볼 수 있습니다.
메인넷에서 모듈이 활성화되기 전까지는 메인넷용 연결된 키 또는 위임 지출 흐름을
구축하지 마시고, 그러한 흐름을 제공하기 전에 대상 네트워크에서 이 플래그를
확인하세요.
릴레이어 모델
릴레이어(relayer) 가 트랜잭션을 제출하고 수수료를 지불합니다. 릴레이어 자신의 하이브리드(클래식 + ML-DSA-87) 서명이 봉투(envelope)에 대한 ante 핸들러 검증을 충족하므로, 정식 계정의 PQC 서명은 온체인에서 필요하지 않습니다. 대신 도메인 분리(domain-separated)되고 리플레이가 방지된 sign-bytes 다이제스트에 대한 연결된 키의 서명이 승인 역할을 합니다.
Phantom / MetaMask key Relayer (pays fees) Chain
───────────────────── ─────────────────── ─────
sign(authSignBytes) ──────────▶ wrap in Msg, sign envelope ──▶ verify authenticator sig
check permission + rule
spend FROM canonical account
릴레이어는 소유자와 다른 계정입니다. 인증자가 서명하는 논스는 계정의 EVM 논스가 아니라, 체인이 관리하는 연결된 키 자체의 시퀀스입니다(논스(Nonce) 참조).
세 가지 레인
| 레인 | 메시지 | Sign-bytes | 지출 대상 |
|---|---|---|---|
| EVM | MsgExecuteEVM | evmAuthSignBytes | 계정의 0x 주소에서 네이티브 QOR / EVM 호출 |
| Native | MsgExecuteCosmos | cosmosAuthSignBytes | 계정에서 x/bank를 통한 네이티브 QOR |
| 키 로테이션 | MsgRotatePQCKey | rotationSignBytes | (계정의 PQC 키를 교체) |
메시지 타입 URL은 /qorechain.abstractaccount.v1.MsgExecuteEVM,
/qorechain.abstractaccount.v1.MsgExecuteCosmos,
/qorechain.pqc.v1.MsgRotatePQCKey입니다.
Phantom 인증자 등록하기
키 연결은 소유자 서명(정식 계정이 수행하는 일반적인 하이브리드
트랜잭션)으로 이루어집니다. MsgRegisterAuthenticator는 키(스킴 + 원시
공개키 바이트), 부여된 permissions, 그리고 expiryUnix 세션 만료 시각을
지정합니다. 지출 한도는 MsgUpdateSpendingRules를 통해 SpendingRule로
첨부합니다:
import { msg } from "@qorechain/sdk";
// The Phantom wallet in the browser:
const phantomPubkey = window.solana.publicKey.toBytes(); // 32-byte ed25519
// 1) Link the key: least privilege ("send" only) + a session expiry.
const register = msg.abstractaccount.registerAuthenticator({
owner: canonicalAccount, // the PQC-required account ("qor1…")
accountAddress: canonicalAccount, // the account the key may act for
scheme: "ed25519", // Phantom keys are ed25519
pubkey: phantomPubkey,
permissions: ["send"], // e.g. "send", "evm", "svm" — never "all" for a hot key
expiryUnix: String(Math.floor(Date.now() / 1000) + 7 * 24 * 3600), // 7 days
label: "phantom",
});
// 2) Bound what it can move: per-tx and daily limits, uqor only.
const limits = msg.abstractaccount.updateSpendingRules({
owner: canonicalAccount,
accountAddress: canonicalAccount,
rules: [
{
id: "phantom-hot",
perTxLimit: "1000000", // ≤ 1 QOR per spend
dailyLimit: "10000000", // ≤ 10 QOR per day
allowedDenoms: ["uqor"],
enabled: true,
},
],
});
// Broadcast BOTH owner-signed (hybrid) — e.g. via the hybrid tx path:
// await signAndBroadcastHybrid({ ..., messages: [register, limits] });
체인은 다음 순서로 한도를 결정합니다. 인증자 자체의 규칙이 설정되어 있고
enabled이면 그 규칙, 그렇지 않으면 계정의 첫 번째 enabled 규칙, 그것도
없으면 규칙이 없으며, 이 경우 한도가 없습니다. enabled: false로 저장된
규칙은 한도 0이 아니라 한도 없음입니다. MsgRegisterAuthenticator에는 규칙이
포함되지 않으므로, 해당 메시지만으로 연결된 키는 계정 수준 규칙에 의해서만
제한됩니다. MsgUpdateSpendingRules로 규칙을 의도적으로 설정하고, 키에
필요한 권한만 등록하세요. 한도는 연결된 키가 입힐 수 있는 피해를 제한할 뿐이며,
키를 철회하는 것을 대체하지 않습니다. 지출 규칙은 인증자와 세션 키에만 적용되며
소유자 자신의 키에는 적용되지 않습니다(EVM 레인에서 소유자의 키는 EVM 윈도우로 제한됩니다).
키를 즉시 비활성화하려면 소유자가
msg.abstractaccount.revokeAuthenticator({ owner, accountAddress, scheme, pubkey })를 브로드캐스트합니다.
체인 v3.2.8부터의 연결 (SDK 0.14.0)
체인 v3.2.8부터(테스트넷은 2026년 11월 12일부터, 메인넷은 아직 적용하지 않음)
위의 등록은 소유 증명이 없으면 거부됩니다. 연결할 키가 체인, 계정, 방식, 키를
명시한 일반 텍스트 메시지에 서명하는 것입니다. send, evm, deploy, svm,
all 권한이 있는 키는 계정의 첫 번째 활성 지출 규칙이 모든 denom을 제한해야 합니다.
SDK 0.14.0에는 둘 모두를 위한 헬퍼가 있으며, linkAuthenticatorMsgs는 지출 규칙과
연결을 소유자가 서명하는 한 트랜잭션에서 보낼 순서대로 구성합니다. 이 스니펫은
0.14.0 소스를 따랐으며 실행하지 않았습니다.
import { linkAuthenticatorMsgs, signAuthenticatorLinkPhantom } from "@qorechain/sdk";
// The key being linked signs the link message (Phantom signMessage here).
const proof = await signAuthenticatorLinkPhantom({
chainId: "qorechain-diana",
account: canonicalAccount,
wallet: window.solana,
});
const msgs = linkAuthenticatorMsgs({
owner: canonicalAccount,
chainId: "qorechain-diana", // optional: checks the proof before anything is built
scheme: proof.scheme,
pubkey: proof.pubkey,
possessionProof: proof.possessionProof,
permissions: ["send"],
expiryUnix: Math.floor(Date.now() / 1000) + 7 * 24 * 3600,
label: "phantom",
// Replaces the account's rules wholesale: pass every rule to keep.
spendingRules: [{ id: "phantom-hot", enabled: true, perTxLimit: "1000000", allowedDenoms: ["uqor"] }],
});
// Sign msgs in one owner-signed hybrid transaction.
같은 파일에 다른 키 유형을 위한 signAuthenticatorLinkEd25519,
signAuthenticatorLinkSecp256k1, signAuthenticatorLinkEip191,
signAuthenticatorLinkMetaMask가 있으며, 등록 컴포저는 빈 증명을 거부합니다.
v3.2.8 미만 네트워크에서는 증명이 선택 사항으로 남습니다.
v3.2.8부터 인가된 MsgExecuteEVM 또는 MsgExecuteCosmos가 실패하면 코드 0
트랜잭션 안에서 success=false를 반환하고 논스는 그대로 소비됩니다. 릴레이어
브로드캐스트 후에는 assertAuthenticatorExecutionsSucceeded(result, messages)를
호출하거나, decodeAuthenticatorExecutions로 각 결과를 읽어 실패한 실행을 성공으로
착각하지 않도록 하세요.
Phantom으로 지출하기 (Native 레인, 릴레이어 경유)
키가 연결되면 브라우저에서 릴레이어에 전달할 수 있는 MsgExecuteCosmos를
구성합니다. buildPhantomExecuteCosmos는 도메인 분리 다이제스트를 재구성하고,
Phantom이 이를 서명하도록 하며(signMessage), { typeUrl, value } 메시지를
반환합니다.
브라우저 (Phantom 사용자):
import { buildPhantomExecuteCosmos } from "@qorechain/sdk";
// window.solana is a Phantom-style wallet: { publicKey, signMessage }.
const msgExecute = await buildPhantomExecuteCosmos({
wallet: window.solana,
relayer: relayerAddress, // who will submit + pay fees
chainId: "qorechain-vladi",
account: canonicalAccount, // the PQC-required owner
to: recipient, // "qor1…"
amount: "100uqor", // single-coin amount string
nonce, // the per-authenticator sequence for (account, pubkey)
});
// Ship `msgExecute` to your relayer service (it is already signed by Phantom):
await fetch("/api/relay", {
method: "POST",
body: JSON.stringify({
typeUrl: msgExecute.typeUrl,
value: {
...msgExecute.value,
pubkey: Buffer.from(msgExecute.value.pubkey).toString("base64"),
signature: Buffer.from(msgExecute.value.signature).toString("base64"),
nonce: msgExecute.value.nonce.toString(),
},
}),
});
서버 (릴레이어): 하이브리드 경로(signAndBroadcastHybrid, rest를 전달)를
사용해 자신의 고유 계정으로 봉투에 서명하고 수수료를 지불합니다. 릴레이어의
ML-DSA-87 키는 다른 모든 계정과 마찬가지로 등록되어 있어야 합니다. 메시지
내부에 포함된 인증자의 서명이 소유자 계정에서 지출할 수 있는 승인입니다.
import { StargateClient } from "@cosmjs/stargate";
import {
deriveNativeAccount,
directSignerFromPrivateKey,
derivePqcCanonical,
signAndBroadcastHybrid,
qorechainRegistry,
} from "@qorechain/sdk";
const REST = "https://api.qore.host";
const RPC = "https://rpc.qore.host";
// The relayer's OWN account: a different account than the owner.
const mnemonic = process.env.RELAYER_MNEMONIC!;
const relayer = await deriveNativeAccount(mnemonic);
const signer = await directSignerFromPrivateKey(relayer.privateKey, "qor");
const pqcKeypair = derivePqcCanonical(relayer.address, mnemonic);
const transport = await StargateClient.connect(RPC);
const info = await transport.getSequence(relayer.address);
// `msgExecute` is the message decoded from the request. The relayer pays fees.
const result = await signAndBroadcastHybrid({
registry: qorechainRegistry(),
signer,
pqcKeypair,
messages: [msgExecute],
fee: { amount: [{ denom: "uqor", amount: "40000" }], gas: "400000" },
chainId: "qorechain-vladi",
accountNumber: info.accountNumber,
sequence: info.sequence,
rest: REST,
transport,
});
console.log(result.transactionHash);
(Phantom 대신 로컬 ed25519 키를 사용하는) 실행 가능한 엔드투엔드 버전은
authenticator-spend
예제에서 확인할 수 있습니다.
MetaMask로 지출하기 (EVM 레인)
MetaMask 키는 registerEthAuthenticatorMsg를 사용해 20바이트 ETH 주소
(스킴 secp256k1)로 연결하며, 동일한 종류의 다이제스트에 대한 65바이트
EIP-191 personal_sign 서명으로 지출을 승인합니다.
1) 소유자가 MetaMask 주소를 연결 (소유자 서명, 하이브리드):
import { registerEthAuthenticatorMsg } from "@qorechain/sdk";
const [ethAddress] = await window.ethereum.request({
method: "eth_requestAccounts",
params: [],
});
const register = registerEthAuthenticatorMsg({
owner: canonicalAccount,
ethAddress, // 0x-hex 20-byte address = the authenticator pubkey
permissions: ["evm"], // EVM lane only
expiryUnix: Math.floor(Date.now() / 1000) + 24 * 3600, // 24 h session
label: "metamask",
});
// broadcast owner-signed (hybrid), like any other message
2) MetaMask가 EVM 전송을 승인 — buildMetaMaskExecuteEvm은 다이제스트를
구성하고, 프로바이더에 personal_sign(EIP-191)을 요청한 뒤, 릴레이어에
전달할 수 있는 MsgExecuteEVM을 반환합니다:
import { buildMetaMaskExecuteEvm } from "@qorechain/sdk";
const msgExecute = await buildMetaMaskExecuteEvm({
provider: window.ethereum, // any EIP-1193 provider
address: ethAddress, // the linked 20-byte address (0x-hex)
relayer: relayerAddress,
chainId: "qorechain-vladi",
account: canonicalAccount, // the PQC-required owner
to: "0xRecipient…", // 0x-hex recipient
value: "1000000000000000000",// decimal wei string (EVM lane: 18 decimals)
gasLimit: 100000,
nonce: authSequence, // the linked key's authenticator sequence (see Nonces) — NOT the EVM nonce
digestVersion: "v2", // from chain v3.2.3 (see "Sign-bytes"); use resolveEvmAuthDigestVersion
});
// hand `msgExecute` to the relayer, exactly as in the Phantom flow
buildMetaMaskExecuteCosmos는 Native 레인에서 동일한 방식으로 동작합니다
(to: "qor1…", amount: "100uqor", nonce = 인증자별 시퀀스). 키와 서명을
직접 관리하는 경우를 위해 대응하는 저수준 컴포저 — executeEvmMsg,
executeCosmosMsg, registerEthAuthenticatorMsg, revokeAuthenticatorMsg,
rotatePqcKeyMsg — 도 제공됩니다.
Sign-bytes (바이트 단위 정의)
두 가지 바이트 헬퍼가 있습니다. BE64(n)은 8바이트 빅엔디언 정수이고,
LP(bytes)는 BE64(len) ‖ bytes(길이 접두)입니다.
EVM 레인 — evmAuthSignBytes({ chainId, account, pubkey, to, value, data, nonce })
는 32바이트 다이제스트를 반환합니다:
sha256( "qorechain-evm-auth-v1"
‖ LP(chainId) ‖ LP(account) ‖ LP(pubkey)
‖ LP(to) ‖ LP(value) ‖ LP(data) ‖ BE64(nonce) )
to는 0x-hex 수신자, value는 10진수 wei 문자열, data는 원시
calldata입니다.
EVM 레인, v2 (체인 v3.2.3) — evmAuthSignBytesV2({ …, gasLimit })는 호출의
가스 한도를 덧붙이므로, 릴레이어가 유효한 서명을 다른 한도로 재사용할 수
없습니다. 체인은 블록마다 정확히 한 가지 형식만 검증합니다. v3.2.3 업그레이드
이전에는 v1, 그 이후에는 v2입니다. resolveEvmAuthDigestVersion({ rest })는
네트워크가 v3.2.3을 적용한 뒤에는 "v2"를, 그 전에는 "v1"을 반환하며,
buildPhantomExecuteEvm / buildMetaMaskExecuteEvm은 digestVersion을
받습니다(기본값은 "v1"이므로 v3.2.3 이상의 네트워크에서는 "v2"를
전달하세요). gasLimit은 0이 아니어야 합니다.
sha256( "qorechain-evm-auth-v2"
‖ LP(chainId) ‖ LP(account) ‖ LP(pubkey)
‖ LP(to) ‖ LP(value) ‖ LP(data) ‖ BE64(nonce) ‖ BE64(gasLimit) )
Native 레인 — cosmosAuthSignBytes({ chainId, account, pubkey, to, amount, nonce })
는 32바이트 다이제스트를 반환합니다:
sha256( "qorechain-cosmos-auth-v1"
‖ LP(chainId) ‖ LP(account) ‖ LP(pubkey)
‖ LP(to) ‖ LP(amount) ‖ BE64(nonce) )
amount는 정식 단일 코인 문자열입니다(예: 100uqor).
로테이션 — rotationSignBytes(chainId, algorithmId, account, oldPub, newPub)
는 두 키가 서명하는 문자열(그 UTF-8 인코딩)을 반환합니다:
qorechain-pqc-rotate-v1|<chainId>|<algorithmId>|<account>|<oldHex>|<newHex>
논스(Nonce)
두 레인 모두 (account, pubkey)에 대한 인증자별 시퀀스를 사용합니다. 이는
체인이 연결된 키마다 관리하는 카운터로, 0에서 시작하여 실행이 성공할 때마다
증가합니다.
MsgExecuteEVM.nonce는 계정의 EVM 논스(eth_getTransactionCount)가 아니라 이 카운터입니다.MsgExecuteCosmos.nonce도 같은 종류의 카운터입니다.
체인 v3.2.4(두 네트워크 모두 이 경로를 제공합니다)와 SDK 0.10.0 이상부터는 카운터를
추적하는 대신 읽을 수 있습니다. fetchAuthNonce({ rest, address, pubkey })는
GET /qorechain/abstractaccount/v1/auth_nonce/{address}/{pubkey_hex}를 호출하고
{ nonce, linked }를 반환합니다. 한 번도 실행하지 않은 키는 0으로 읽히며, 카운터는
더 이상 연결되어 있지 않은 키에 대해서도 유지됩니다(linked가 어느 쪽인지 알려
줍니다). 체인의 현재 카운터가 아닌 값을 보내면 리플레이 거부(abstractaccount
코드 11, 아래 참조)가 발생합니다. 이전 SDK나 체인에서는 연결된 키별로 직접
추적하세요. 새로 연결된 키는 0이고, 체인이 수락한 실행마다 +1입니다.
저장된 규칙과 연결된 키 읽기
체인 v3.2.5(SDK 0.12.0)부터 두 네트워크 모두에서 트랜잭션으로부터 재구성하는 대신 계정이 저장한 내용을 직접 조회할 수 있습니다.
fetchSpendingRules({ rest, address })는 계정 전체 및 연결된 키별 지출 규칙을 읽습니다 (GET /qorechain/abstractaccount/v1/accounts/{address}/spending_rules).fetchAuthenticators({ rest, address })는 해지된 키를 포함하여 연결된 키를 읽습니다 (.../accounts/{address}/authenticators).msg.abstractaccount.updateConfig는 모듈의 한도를 설정하는 거버넌스 메시지입니다 (권한 주체는 거버넌스 모듈 계정이므로 일반 계정은 보낼 수 없습니다). SDK는 서명하기 전에 값을 확인합니다.
규칙은 체인이 확인하는 방식 그대로 확인됩니다. erc20/, erc721/ 또는 erc1155/ denom은
0x 컨트랙트 주소를 지정해야 하며, 모듈의 코드 8(잘못된 지출 규칙)과 9(모듈 비활성화)에
이름이 붙어 있습니다. 모듈은 여전히 메인넷에서 꺼져 있고
테스트넷에서는 활성화되어 있습니다.
권한 스키마
체인은 정식 인증자 권한 분류 체계를 게시하므로, 클라이언트는 문자열을
하드코딩하지 않고 스코프를 검증할 수 있으며 schema_version을 통해 변경
여부를 감지할 수 있습니다:
// REST (LCD):
const schema = await client.rest.getPermissionSchema();
schema.schema_version; // bumps on any taxonomy/mapping change
schema.permissions; // ["send", "evm", "svm", "all", ...]
schema.msg_permissions; // { "/qorechain.abstractaccount.v1.MsgExecuteEVM": "evm", ... }
schema.key_management_msgs; // typeURLs NEVER delegable to a linked key
REST 라우트는 GET /qorechain/abstractaccount/v1/permission_schema이며, 타입이
지정된 gRPC 쿼리 클라이언트는 동일한 데이터를
clients.abstractaccount.permissionSchema()로 제공합니다. 이 모듈은
/config, /accounts, /accounts/{address} 엔드포인트도 제공합니다.
오류 코드
실패는 decodeTxError를 통해 읽기 쉬운 kind로 디코딩됩니다:
| Codespace | 코드 | Kind |
|---|---|---|
abstractaccount | 5 | spending_limit_exceeded |
abstractaccount | 6 | session_key_expired |
abstractaccount | 10 | permission_denied |
abstractaccount | 11 | authenticator_replay |
pqc | 21 | hybrid_verify_failed |
import { decodeTxError } from "@qorechain/sdk";
const decoded = decodeTxError({
code: result.code,
codespace: result.codespace,
rawLog: result.rawLog,
});
switch (decoded.kind) {
case "spending_limit_exceeded": // over the per-tx or daily SpendingRule
break;
case "session_key_expired": // expiryUnix passed — re-register the key
break;
case "permission_denied": // scope missing — check the permission_schema
break;
case "authenticator_replay": // wrong nonce — refetch and re-sign
break;
case "hybrid_verify_failed": // ML-DSA sig did not verify (see note below)
break;
}
hybrid_verify_failed는 ML-DSA-87 서명이 검증되지 않았음을 의미합니다. 헤지드
서명은 원인이 아닙니다(체인은 헤지드와 결정론적 ML-DSA-87 서명을 똑같이
수락합니다). 코드 21 문제 해결을
참고하세요. 0.6.1 이전 SDK가 하이브리드 확장을 JSON으로 인코딩한 경우에도 이
오류가 발생합니다(업그레이드하세요 -
계정 & PQC 서명 참고).
키 로테이션
계정의 ML-DSA-87 키를 동일한 알고리즘의 새 키로 교체합니다 — 예를 들어
레거시 체인 브리지 파생 키(shake256(mnemonic))를 정식 주소 바인딩 키
(shake256("qorechain:pqc:v1|addr|mnemonic"))로 마이그레이션할 때
사용합니다:
import { rotatePqcKeyMsgFromMnemonic, derivePqcLegacy } from "@qorechain/sdk";
const { msg, oldKeypair, newKeypair } = rotatePqcKeyMsgFromMnemonic({
account,
mnemonic,
chainId: "qorechain-vladi",
// oldDerivation: "bridge" (legacy), newDerivation: "adapter" (canonical) by default
});
// broadcast `msg` BY the account, cosigned (hybrid) with the OLD key —
// both keys dual-sign the rotation bytes (old proves ownership, new proves control).
derivePqcLegacy(mnemonic)은 필요할 때(예: 로테이션이 반영되기 전까지 계속
서명해야 하는 경우) 레거시 키페어를 단독으로 재생성합니다.
다음 단계
- 계정 & PQC 서명 — 통합 계정과 하이브리드 서명.
- 계정 추상화 — 체인 측 모듈.
- 실행 가능한 예제:
authenticator-spend.