Zum Hauptinhalt springen

Authenticatoren & delegiertes Ausgeben

Authenticator-Lanes (SDK 0.7.0, Chain v3.1.85) erlauben es einem verknüpften externen Schlüssel — einem Phantom-ed25519-Schlüssel oder einem MetaMask-/EVM-secp256k1-Schlüssel — vom EINEN kanonischen PQC-pflichtigen Konto auszugeben: nach dem Prinzip der geringsten Berechtigung, mit Ausgabenlimits und jederzeit widerrufbar, ohne dass der externe Schlüssel jemals eine ML-DSA-Co-Signatur erzeugt.

Dies ist das SDK-Gegenstück zum Account-Abstraction-Modul der Chain.

Im Mainnet nicht verfügbar

Das Modul x/abstractaccount ist auf qorechain-vladi (Mainnet) deaktiviert: GET /qorechain/abstractaccount/v1/config liefert "enabled": false. Ab Chain v3.2.0 wird dieses Flag auf jedem Pfad durchgesetzt (Erstellen eines Abstract Accounts, Verknüpfen eines Authenticators sowie MsgExecuteEVM / MsgExecuteCosmos), und die Chain weist sie mit abstract account module is disabled (Code 9) ab. Keine Transaktion kann es einschalten. Auf dem Testnet qorechain-diana lieferte dieselbe Route am 27. Oktober 2026 "enabled": true, sodass die folgenden Abläufe dort ausprobiert werden können. Bauen Sie für das Mainnet keinen Ablauf mit verknüpften Schlüsseln oder delegiertem Ausgeben, solange das Modul dort nicht aktiviert ist, und prüfen Sie das Flag auf dem Netzwerk, das Sie ansprechen, bevor Sie einen solchen Ablauf anbieten.

Das Relayer-Modell​

Ein Relayer reicht die Transaktion ein und bezahlt die Gebühren. Die eigene hybride Signatur des Relayers (klassisch + ML-DSA-87) erfüllt den Ante-Handler auf dem Envelope, sodass die PQC-Signatur des kanonischen Kontos on-chain nicht benötigt wird. Die Autorisierung ist stattdessen die Signatur des verknüpften Schlüssels über einen domänen-separierten, replay-gebundenen Sign-Bytes-Digest.

Phantom / MetaMask key Relayer (pays fees) Chain
───────────────────── ─────────────────── ─────
sign(authSignBytes) ──────────▶ wrap in Msg, sign envelope ──▶ verify authenticator sig
check permission + rule
spend FROM canonical account

Der Relayer ist ein anderes Konto als der Eigentümer. Die Nonce, die der Authenticator signiert, ist die eigene Sequenz des verknüpften Schlüssels, die von der Chain geführt wird (siehe Nonces), nicht die EVM-Nonce des Kontos.

Die drei Lanes​

LaneMessageSign-BytesGibt aus
EVMMsgExecuteEVMevmAuthSignBytesnatives QOR / EVM-Call von der 0x-Adresse des Kontos
NativeMsgExecuteCosmoscosmosAuthSignBytesnatives QOR über x/bank vom Konto
SchlüsselrotationMsgRotatePQCKeyrotationSignBytes(rotiert den PQC-Schlüssel des Kontos)

Die Message-Typ-URLs sind /qorechain.abstractaccount.v1.MsgExecuteEVM, /qorechain.abstractaccount.v1.MsgExecuteCosmos und /qorechain.pqc.v1.MsgRotatePQCKey.

Einen Phantom-Authenticator registrieren​

Das Verknüpfen eines Schlüssels ist owner-signiert (eine normale hybride Transaktion des kanonischen Kontos): MsgRegisterAuthenticator benennt den Schlüssel (Schema + rohe Pubkey-Bytes), die gewährten permissions und eine expiryUnix-Sitzungsfrist. Ausgabenlimits werden mit einer SpendingRule über MsgUpdateSpendingRules angehängt:

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] });
Eine Regel begrenzt einen Schlüssel nur, wenn eine existiert

Die Chain ermittelt das Limit in dieser Reihenfolge: die eigene Regel des Authenticators, wenn sie gesetzt und enabled ist; andernfalls die erste enabled-Regel des Kontos; andernfalls keine, und dann gibt es kein Limit. Eine mit enabled: false gespeicherte Regel bedeutet kein Limit, nicht ein Limit von null. MsgRegisterAuthenticator trägt keine Regel, ein allein mit dieser Message verknüpfter Schlüssel ist also nur durch eine Regel auf Kontoebene begrenzt. Setzen Sie bewusst eine Regel mit MsgUpdateSpendingRules und registrieren Sie nur die Berechtigungen, die der Schlüssel braucht. Ein Limit begrenzt den Schaden, den ein verknüpfter Schlüssel anrichten kann; es ersetzt nicht den Widerruf des Schlüssels. Ausgaberegeln binden nur Authenticators und Session-Keys, nicht den eigenen Schlüssel des Eigentümers (auf der EVM-Lane wird der Schlüssel des Eigentümers durch das EVM-Fenster begrenzt).

Um einen Schlüssel sofort zu deaktivieren, broadcastet der Eigentümer msg.abstractaccount.revokeAuthenticator({ owner, accountAddress, scheme, pubkey }).

Ab Chain v3.2.8 (das Testnet seit dem 12. November 2026; das Mainnet hat sie nicht angewendet) wird die obige Registrierung abgelehnt, wenn sie keinen Besitznachweis trägt: Der zu verknüpfende Schlüssel signiert eine Klartextnachricht, die die Chain, das Konto, das Schema und den Schlüssel nennt. Ein Schlüssel mit send, evm, deploy, svm oder all braucht außerdem eine erste aktivierte Ausgabenregel des Kontos, die jede Denom begrenzt. SDK 0.14.0 hat Helfer für beides; linkAuthenticatorMsgs baut die Ausgabenregel und die Verknüpfung in der Reihenfolge, in der sie in einer vom Eigentümer signierten Transaktion gesendet werden. Dieses Snippet folgt dem Quellcode von 0.14.0 und wurde nicht ausgeführt:

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.

Dieselbe Datei hat signAuthenticatorLinkEd25519, signAuthenticatorLinkSecp256k1, signAuthenticatorLinkEip191 und signAuthenticatorLinkMetaMask für die anderen Schlüsseltypen, und die Register-Composer lehnen einen leeren Nachweis ab. In einem Netzwerk unter v3.2.8 bleibt der Nachweis optional.

Ab v3.2.8 liefert ein autorisiertes MsgExecuteEVM oder MsgExecuteCosmos, das fehlschlägt, success=false innerhalb einer Transaktion mit Code 0 und verbraucht trotzdem die Nonce. Rufen Sie nach einem Relayer-Broadcast assertAuthenticatorExecutionsSucceeded(result, messages) auf, oder decodeAuthenticatorExecutions, um jedes Ergebnis zu lesen, damit eine fehlgeschlagene Ausführung nicht für einen Erfolg gehalten wird.

Von Phantom ausgeben (Native-Lane, über einen Relayer)​

Sobald der Schlüssel verknüpft ist, baut der Browser eine relayer-fertige MsgExecuteCosmos: buildPhantomExecuteCosmos rekonstruiert den domänen-separierten Digest, lässt ihn von Phantom signieren (signMessage) und liefert die { typeUrl, value }-Message zurück.

Browser (der Phantom-Nutzer):

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(),
},
}),
});

Server (der Relayer): signiert den Envelope mit seinem eigenen Konto über den Hybrid-Pfad (signAndBroadcastHybrid, mit übergebenem rest) und bezahlt die Gebühren. Der ML-DSA-87-Schlüssel des Relayers muss wie bei jedem Konto registriert sein. Die Signatur des Authenticators innerhalb der Message ist die Autorisierung, vom Konto des Eigentümers auszugeben.

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);

Eine lauffähige End-to-End-Version (mit einem lokalen ed25519-Schlüssel als Stellvertreter für Phantom) ist das Beispiel authenticator-spend.

Von MetaMask ausgeben (EVM-Lane)​

Ein MetaMask-Schlüssel wird über seine 20-Byte-ETH-Adresse (Schema secp256k1) mit registerEthAuthenticatorMsg verknüpft und autorisiert Ausgaben mit einer 65-Byte-EIP-191-personal_sign-Signatur über dieselbe Art von Digest.

1) Der Eigentümer verknüpft die MetaMask-Adresse (owner-signiert, hybrid):

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 autorisiert einen EVM-Transfer — buildMetaMaskExecuteEvm baut den Digest, fordert personal_sign (EIP-191) vom Provider an und liefert eine relayer-fertige MsgExecuteEVM zurück:

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 funktioniert auf dieselbe Weise für die Native-Lane (to: "qor1…", amount: "100uqor", nonce = die Sequenz pro Authenticator). Es gibt passende Low-Level-Composer — executeEvmMsg, executeCosmosMsg, registerEthAuthenticatorMsg, revokeAuthenticatorMsg, rotatePqcKeyMsg — falls Sie Schlüssel und Signaturen selbst verwalten.

Sign-Bytes (byte-exakt)​

Zwei Byte-Helfer: BE64(n) ist eine 8-Byte-Big-Endian-Ganzzahl; LP(bytes) ist BE64(len) ‖ bytes (längenpräfixiert).

EVM-Lane — evmAuthSignBytes({ chainId, account, pubkey, to, value, data, nonce }) liefert einen 32-Byte-Digest zurück:

sha256( "qorechain-evm-auth-v1"
‖ LP(chainId) ‖ LP(account) ‖ LP(pubkey)
‖ LP(to) ‖ LP(value) ‖ LP(data) ‖ BE64(nonce) )

to ist der 0x-Hex-Empfänger, value der dezimale wei-String, data die rohen Calldata.

EVM-Lane, v2 (Chain v3.2.3) — evmAuthSignBytesV2({ …, gasLimit }) hängt das Gas-Limit des Aufrufs an, sodass ein Relayer eine gültige Signatur nicht mit einem anderen Limit wiederverwenden kann. Die Chain verifiziert pro Block genau eine Form: v1 vor dem Upgrade v3.2.3, v2 ab diesem. resolveEvmAuthDigestVersion({ rest }) liefert "v2", sobald das Netzwerk v3.2.3 angewendet hat, und davor "v1", und buildPhantomExecuteEvm / buildMetaMaskExecuteEvm nehmen digestVersion entgegen (Standard "v1", übergeben Sie also "v2" auf einem Netzwerk ab v3.2.3). gasLimit darf nicht null sein.

sha256( "qorechain-evm-auth-v2"
‖ LP(chainId) ‖ LP(account) ‖ LP(pubkey)
‖ LP(to) ‖ LP(value) ‖ LP(data) ‖ BE64(nonce) ‖ BE64(gasLimit) )

Native-Lane — cosmosAuthSignBytes({ chainId, account, pubkey, to, amount, nonce }) liefert einen 32-Byte-Digest zurück:

sha256( "qorechain-cosmos-auth-v1"
‖ LP(chainId) ‖ LP(account) ‖ LP(pubkey)
‖ LP(to) ‖ LP(amount) ‖ BE64(nonce) )

amount ist der kanonische Single-Coin-String (z. B. 100uqor).

Rotation — rotationSignBytes(chainId, algorithmId, account, oldPub, newPub) liefert den String zurück, den beide Schlüssel signieren (dessen UTF-8):

qorechain-pqc-rotate-v1|<chainId>|<algorithmId>|<account>|<oldHex>|<newHex>

Nonces​

Beide Lanes verwenden die Sequenz pro Authenticator für (account, pubkey): einen Zähler, den die Chain für jeden verknüpften Schlüssel führt, der bei 0 beginnt und bei jeder erfolgreichen Ausführung inkrementiert wird.

  • MsgExecuteEVM.nonce ist dieser Zähler, nicht die EVM-Nonce des Kontos (eth_getTransactionCount).
  • MsgExecuteCosmos.nonce ist derselbe Zähler-Typ.

Seit Chain v3.2.4 (beide Netzwerke stellen die Route bereit) und SDK 0.10.0 oder neuer können Sie den Zähler lesen, statt ihn mitzuführen: fetchAuthNonce({ rest, address, pubkey }) ruft GET /qorechain/abstractaccount/v1/auth_nonce/{address}/{pubkey_hex} auf und liefert { nonce, linked }. Ein Schlüssel, der nie ausgeführt hat, liest 0, und der Zähler bleibt auch für einen Schlüssel erhalten, der nicht mehr verknüpft ist (linked gibt an, welcher Fall vorliegt). Einen Wert zu senden, der nicht dem aktuellen Zähler der Chain entspricht, ist eine Replay-Ablehnung (abstractaccount Code 11, siehe unten). Mit einem älteren SDK oder einer älteren Chain verfolgen Sie ihn pro verknüpftem Schlüssel: 0 für einen neu verknüpften Schlüssel, +1 nach jeder Ausführung, die die Chain akzeptiert.

Gespeicherte Regeln und verknüpfte Schlüssel lesen​

Ab Chain v3.2.5 (SDK 0.12.0) kann auf beiden Netzwerken abgefragt werden, was ein Konto gespeichert hat, statt es aus Transaktionen zu rekonstruieren:

  • fetchSpendingRules({ rest, address }) liest die Spending-Regeln, kontoweit und pro verknüpftem Schlüssel (GET /qorechain/abstractaccount/v1/accounts/{address}/spending_rules).
  • fetchAuthenticators({ rest, address }) liest die verknüpften Schlüssel, einschließlich widerrufener (.../accounts/{address}/authenticators).
  • msg.abstractaccount.updateConfig ist die Governance-Nachricht, die die Grenzen des Moduls festlegt (die Autorität ist das Governance-Modulkonto, ein gewöhnliches Konto kann sie also nicht senden). Das SDK prüft die Werte vor dem Signieren.

Regeln werden so geprüft, wie die Chain sie prüft: ein Denom erc20/, erc721/ oder erc1155/ muss eine 0x-Contract-Adresse nennen, und die Codes 8 (ungültige Spending-Regel) und 9 (Modul deaktiviert) des Moduls werden benannt. Das Modul ist auf dem Mainnet weiterhin ausgeschaltet und auf dem Testnet aktiviert.

Das Permission-Schema​

Die Chain veröffentlicht die kanonische Authenticator-Permission-Taxonomie, damit Clients Scopes validieren können, ohne Strings zu hartkodieren, und Abweichungen über schema_version erkennen:

// 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

Die REST-Route ist GET /qorechain/abstractaccount/v1/permission_schema; der typisierte gRPC-Query-Client stellt dieselben Daten als clients.abstractaccount.permissionSchema() bereit. Das Modul bedient außerdem /config, /accounts und /accounts/{address}.

Fehlercodes​

Fehlschläge werden über decodeTxError mit einem verständlichen kind dekodiert:

CodespaceCodeKind
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 bedeutet, dass die ML-DSA-87-Signatur nicht verifiziert wurde. Hedged Signierung ist nicht die Ursache (die Chain akzeptiert hedged und deterministische ML-DSA-87-Signaturen gleichermaßen); siehe Fehlerbehebung für Code 21. Derselbe Fehler tritt auch auf, wenn ein SDK vor 0.6.1 die Hybrid-Extension JSON-kodiert hat (bitte upgraden - siehe Accounts & PQC-Signierung).

Schlüsselrotation​

Rotieren Sie den ML-DSA-87-Schlüssel eines Kontos zu einem neuen Schlüssel desselben Algorithmus — zum Beispiel bei der Migration eines Legacy-Schlüssels aus der Chain-Bridge-Ableitung (shake256(mnemonic)) zum kanonischen adressgebundenen Schlüssel (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) reproduziert das Legacy-Schlüsselpaar eigenständig, wenn Sie es benötigen (z. B. um bis zum Abschluss der Rotation weiter zu signieren).

Weiter​