メインコンテンツまでスキップ

オーセンティケーターと委任支出

オーセンティケーターレーン(SDK 0.7.0、チェーン v3.1.85)を使うと、リンクされた外部キー — Phantom の ed25519 キー、または MetaMask / EVM の secp256k1 キー — が、外部キーが ML-DSA 共同署名を一切生成することなく、最小権限・支出上限付き・失効可能な条件のもとで、唯一の正準(canonical)な PQC 必須アカウントから支出できます。

これはチェーン側の アカウント抽象化モジュールに対応する 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 を返したため、以下のフローはそこで試せます。メインネットでモジュールが有効になるまでは、メインネット向けのリンクキーや委任支出のフローを構築しないでください。また、そのようなフローを提供する前に、対象とするネットワークでフラグを確認してください。

リレイヤーモデル​

リレイヤーがトランザクションを送信し、手数料を支払います。リレイヤー自身のハイブリッド(クラシカル + ML-DSA-87)署名がエンベロープの ante ハンドラーを満たすため、正準アカウントの PQC 署名はオンチェーンでは不要です。代わりに、認可はドメイン分離されリプレイ拘束された 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 ノンスではありません。

3 つのレーン​

レーンメッセージSign-bytes支出内容
EVMMsgExecuteEVMevmAuthSignBytesアカウントの 0x アドレスからのネイティブ QOR / EVM コール
NativeMsgExecuteCosmoscosmosAuthSignBytesアカウントからの x/bank 経由のネイティブ QOR
キーローテーションMsgRotatePQCKeyrotationSignBytes(アカウントの PQC キーをローテーション)

メッセージの type 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 で保存されたルールは、上限ゼロではなく上限なしです。MsgRegisterAuthenticator はルールを持たないため、このメッセージだけでリンクされたキーは、アカウントレベルのルールによってのみ制限されます。MsgUpdateSpendingRules で意図的にルールを設定し、キーが必要とするパーミッションだけを登録してください。上限はリンク済みキーが与えうる被害を抑えるものであり、キーの失効に代わるものではありません。支出ルールが対象とするのはオーセンティケーターとセッションキーのみで、オーナー自身の鍵には適用されません(EVM レーンでは、オーナーの鍵は EVM ウィンドウによって制限されます)。

キーを即座に無効化するには、オーナーが msg.abstractaccount.revokeAuthenticator({ owner, accountAddress, scheme, pubkey }) をブロードキャストします。

チェーン v3.2.8 以降(テストネットは 2026年11月12日から。メインネットはまだ適用していません)では、 上記の登録は、所有証明がない限り拒否されます。リンクする鍵が、チェーン、アカウント、スキーム、 鍵を明記した平文のメッセージに署名します。send、evm、deploy、svm、all のいずれかを持つ鍵では、 アカウントで最初に有効な支出ルールがすべてのデノミネーションを制限している必要もあります。 SDK 0.14.0 には両方のヘルパーがあり、linkAuthenticatorMsgs は、支出ルールとリンクを、 オーナーが署名する 1 つのトランザクションで送る順序で構築します。このスニペットは 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 があり、register コンポーザーは空の証明を 拒否します。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 のキーは、その 20 バイトの ETH アドレス(スキーム secp256k1)を registerEthAuthenticatorMsg でリンクし、同種のダイジェストに対する 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(バイト単位で厳密)​

2 つのバイトヘルパーがあります。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 16 進の受取人、value は 10 進の wei 文字列、data は生の calldata です。

EVM レーン、v2(チェーン v3.2.3) — evmAuthSignBytesV2({ …, gasLimit }) は 呼び出しのガスリミットを追加するため、リレイヤーが有効な署名を別のリミットで リプレイすることはできません。チェーンはブロックごとに正確に 1 つの形式のみを検証します。 v3.2.3 アップグレードより前は v1、それ以降は v2 です。resolveEvmAuthDigestVersion({ rest }) は、 ネットワークが v3.2.3 を適用した後は "v2"、それ以前は "v1" を返し、 buildPhantomExecuteEvm / buildMetaMaskExecuteEvm は digestVersion を受け取ります(デフォルトは "v1" なので、v3.2.3 以降のネットワークでは "v2" を渡してください)。 gasLimit はゼロ以外でなければなりません。

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>

ノンス​

両レーンとも、(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
abstractaccount5spending_limit_exceeded
abstractaccount6session_key_expired
abstractaccount10permission_denied
abstractaccount11authenticator_replay
pqc21hybrid_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 署名が検証されなかったことを意味します。hedged 署名は原因ではありません (チェーンは hedged と決定的な ML-DSA-87 署名を同様に受け入れます)。 コード 21 のトラブルシューティング を参照してください。また、0.6.1 より前の SDK がハイブリッド拡張を JSON エンコードした場合にも表示されます(アップグレードしてください。 アカウントと PQC 署名を参照)。

キーローテーション​

アカウントの ML-DSA-87 キーを、同じアルゴリズムの新しいキーにローテーションします — 例えば、レガシーな chain-bridge 派生キー(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) は、必要なとき(例: ローテーションが確定するまで署名を続ける場合)に、レガシーな鍵ペアを単独で再現します。

次のステップ​