Authenticators y gasto delegado
Los carriles de authenticator (SDK 0.7.0, cadena v3.1.85) permiten que una clave externa vinculada — una clave ed25519 de Phantom, o una clave secp256k1 de MetaMask / EVM — gaste desde la ÚNICA cuenta canónica con PQC obligatorio bajo condiciones de mínimo privilegio, con límites de gasto y revocables, sin que la clave externa produzca jamás una co-firma ML-DSA.
Esta es la contraparte en el SDK del módulo de abstracción de cuentas de la cadena.
El módulo x/abstractaccount está desactivado en qorechain-vladi (mainnet):
GET /qorechain/abstractaccount/v1/config devuelve "enabled": false. Desde la
cadena v3.2.0 ese indicador se aplica en todas las rutas (crear una cuenta
abstracta, vincular un authenticator, y tanto MsgExecuteEVM como
MsgExecuteCosmos), y la cadena las rechaza con abstract account module is disabled (código 9). Ninguna transacción puede activarlo. En la testnet
qorechain-diana la misma ruta devolvió "enabled": true el 27 de octubre de
2026, así que los flujos siguientes se pueden probar allí. No construyas un flujo
de clave vinculada ni de gasto delegado para la mainnet hasta que el módulo esté
activado allí, y comprueba el indicador en la red a la que apuntas antes de
ofrecer cualquier flujo de ese tipo.
El modelo de relayer
Un relayer envía la transacción y paga las comisiones. La propia firma híbrida (clásica + ML-DSA-87) del relayer satisface el ante handler en el sobre, de modo que la firma PQC de la cuenta canónica no se necesita on-chain. La autorización es, en cambio, la firma de la clave vinculada sobre un digest de sign-bytes con separación de dominio y protección contra replay.
Phantom / MetaMask key Relayer (pays fees) Chain
───────────────────── ─────────────────── ─────
sign(authSignBytes) ──────────▶ wrap in Msg, sign envelope ──▶ verify authenticator sig
check permission + rule
spend FROM canonical account
El relayer es una cuenta distinta a la del propietario. El nonce que firma el authenticator es la propia secuencia de la clave vinculada, que mantiene la cadena (véase Nonces), no el nonce EVM de la cuenta.
Los tres carriles
| Carril | Mensaje | Sign-bytes | Gasta |
|---|---|---|---|
| EVM | MsgExecuteEVM | evmAuthSignBytes | QOR nativo / llamada EVM desde la dirección 0x de la cuenta |
| Nativo | MsgExecuteCosmos | cosmosAuthSignBytes | QOR nativo vía x/bank desde la cuenta |
| Rotación de clave | MsgRotatePQCKey | rotationSignBytes | (rota la clave PQC de la cuenta) |
Las URL de tipo de mensaje son /qorechain.abstractaccount.v1.MsgExecuteEVM,
/qorechain.abstractaccount.v1.MsgExecuteCosmos y
/qorechain.pqc.v1.MsgRotatePQCKey.
Registrar un authenticator de Phantom
Vincular una clave está firmado por el propietario (una transacción híbrida
normal de la cuenta canónica): MsgRegisterAuthenticator nombra la clave
(esquema + bytes de la pubkey en crudo), los permissions concedidos y una
fecha límite de sesión expiryUnix. Los límites de gasto se adjuntan con una
SpendingRule mediante MsgUpdateSpendingRules:
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] });
La cadena resuelve el límite en este orden: la regla propia del authenticator si
está definida y enabled; si no, la primera regla enabled de la cuenta; si no,
ninguna, y entonces no hay límite. Una regla almacenada con enabled: false
equivale a ningún límite, no a un límite cero. MsgRegisterAuthenticator no
lleva ninguna regla, así que una clave vinculada solo con ese mensaje queda
limitada únicamente por una regla a nivel de cuenta. Define una regla de forma
deliberada con MsgUpdateSpendingRules y registra solo los permisos que la
clave necesita. Un límite acota el daño que puede causar una clave vinculada; no
sustituye revocar la clave. Las reglas de gasto solo vinculan a los autenticadores y a las claves de sesión, no a la clave propia del titular (en el carril EVM la clave del titular está limitada por la ventana EVM).
Para desactivar una clave al instante, el propietario difunde
msg.abstractaccount.revokeAuthenticator({ owner, accountAddress, scheme, pubkey }).
Vincular desde la cadena v3.2.8 (SDK 0.14.0)
Desde la cadena v3.2.8 (la testnet desde el 12 de noviembre de 2026; la mainnet no la ha
aplicado) el registro anterior se rechaza si no lleva una prueba de posesión: la clave
que se vincula firma un mensaje de texto plano que nombra la cadena, la cuenta, el esquema
y la clave. Una clave con send, evm, deploy, svm o all necesita además que la
primera regla de gasto habilitada de la cuenta acote cada denominación. El SDK 0.14.0 tiene
ayudantes para ambas cosas; linkAuthenticatorMsgs construye la regla de gasto y el vínculo
en el orden en que se envían en una sola transacción firmada por el propietario. Este
fragmento sigue el código fuente de la 0.14.0 y no se ha ejecutado:
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.
El mismo archivo tiene signAuthenticatorLinkEd25519, signAuthenticatorLinkSecp256k1,
signAuthenticatorLinkEip191 y signAuthenticatorLinkMetaMask para los demás tipos de
clave, y los compositores de registro rechazan una prueba vacía. En una red anterior a
v3.2.8 la prueba sigue siendo opcional.
Desde v3.2.8, un MsgExecuteEVM o MsgExecuteCosmos autorizado que falla devuelve
success=false dentro de una transacción con code 0 y aun así consume el nonce. Tras una
difusión del relayer, llama a assertAuthenticatorExecutionsSucceeded(result, messages), o
a decodeAuthenticatorExecutions para leer cada resultado, de modo que una ejecución
fallida no se tome por un éxito.
Gastar desde Phantom (carril Nativo, mediante un relayer)
Una vez vinculada la clave, el navegador construye un MsgExecuteCosmos listo
para el relayer: buildPhantomExecuteCosmos reconstruye el digest con
separación de dominio, hace que Phantom lo firme (signMessage) y devuelve el
mensaje { typeUrl, value }.
Navegador (el usuario de 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(),
},
}),
});
Servidor (el relayer): firma el sobre con su propia cuenta por la ruta
híbrida (signAndBroadcastHybrid, pasando rest) y paga las comisiones. La
clave ML-DSA-87 del relayer debe estar registrada, como la de cualquier cuenta.
La firma del authenticator dentro del mensaje es la autorización para gastar
desde la cuenta del propietario.
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);
Una versión ejecutable de extremo a extremo (con una clave ed25519 local en
lugar de Phantom) es el ejemplo
authenticator-spend.
Gastar desde MetaMask (carril EVM)
Una clave de MetaMask se vincula por su dirección ETH de 20 bytes (esquema
secp256k1) con registerEthAuthenticatorMsg, y autoriza gastos con una firma
personal_sign EIP-191 de 65 bytes sobre el mismo tipo de digest.
1) El propietario vincula la dirección de MetaMask (firmado por el propietario, híbrido):
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 autoriza una transferencia EVM — buildMetaMaskExecuteEvm
construye el digest, solicita personal_sign (EIP-191) al proveedor y
devuelve un MsgExecuteEVM listo para el relayer:
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 funciona del mismo modo para el carril Nativo
(to: "qor1…", amount: "100uqor", nonce = la secuencia por authenticator).
Existen composers de bajo nivel equivalentes — executeEvmMsg,
executeCosmosMsg, registerEthAuthenticatorMsg, revokeAuthenticatorMsg,
rotatePqcKeyMsg — si gestionas las claves y firmas por tu cuenta.
Sign-bytes (byte a byte exactos)
Dos helpers de bytes: BE64(n) es un entero big-endian de 8 bytes; LP(bytes)
es BE64(len) ‖ bytes (con prefijo de longitud).
Carril EVM — evmAuthSignBytes({ chainId, account, pubkey, to, value, data, nonce })
devuelve un digest de 32 bytes:
sha256( "qorechain-evm-auth-v1"
‖ LP(chainId) ‖ LP(account) ‖ LP(pubkey)
‖ LP(to) ‖ LP(value) ‖ LP(data) ‖ BE64(nonce) )
to es el destinatario en 0x-hex, value la cadena decimal en wei, data
el calldata en crudo.
Carril EVM, v2 (cadena v3.2.3) — evmAuthSignBytesV2({ …, gasLimit }) añade el
límite de gas de la llamada, de modo que un relayer no pueda reproducir una firma
válida con otro límite. La cadena verifica exactamente una forma por bloque: v1
antes de la actualización v3.2.3, v2 a partir de ella. resolveEvmAuthDigestVersion({ rest })
devuelve "v2" una vez que la red ha aplicado v3.2.3 y "v1" antes, y
buildPhantomExecuteEvm / buildMetaMaskExecuteEvm aceptan digestVersion
(por defecto "v1", así que pasa "v2" en una red en v3.2.3 o posterior).
gasLimit no puede ser cero.
sha256( "qorechain-evm-auth-v2"
‖ LP(chainId) ‖ LP(account) ‖ LP(pubkey)
‖ LP(to) ‖ LP(value) ‖ LP(data) ‖ BE64(nonce) ‖ BE64(gasLimit) )
Carril Nativo — cosmosAuthSignBytes({ chainId, account, pubkey, to, amount, nonce })
devuelve un digest de 32 bytes:
sha256( "qorechain-cosmos-auth-v1"
‖ LP(chainId) ‖ LP(account) ‖ LP(pubkey)
‖ LP(to) ‖ LP(amount) ‖ BE64(nonce) )
amount es la cadena canónica de una sola moneda (p. ej. 100uqor).
Rotación — rotationSignBytes(chainId, algorithmId, account, oldPub, newPub)
devuelve la cadena que ambas claves firman (su UTF-8):
qorechain-pqc-rotate-v1|<chainId>|<algorithmId>|<account>|<oldHex>|<newHex>
Nonces
Ambos carriles usan la secuencia por authenticator para (account, pubkey): un
contador que la cadena mantiene para cada clave vinculada, que empieza en 0 y se
incrementa con cada ejecución correcta.
MsgExecuteEVM.noncees este contador, no el nonce EVM de la cuenta (eth_getTransactionCount).MsgExecuteCosmos.noncees el mismo tipo de contador.
Desde la cadena v3.2.4 (ambas redes sirven la ruta) y el SDK 0.10.0 o posterior puedes leer el
contador en lugar de llevarlo tú: fetchAuthNonce({ rest, address, pubkey }) llama
a GET /qorechain/abstractaccount/v1/auth_nonce/{address}/{pubkey_hex} y devuelve
{ nonce, linked }. Una clave que nunca ejecutó lee 0, y el contador se conserva
incluso para una clave que ya no está vinculada (linked indica cuál es el caso).
Enviar un valor que no sea el contador actual de la cadena produce un rechazo por
replay (código 11 de abstractaccount, ver más abajo). Con un SDK o una cadena más
antiguos, llévalo por clave vinculada: 0 para una clave recién vinculada, +1 tras
cada ejecución que acepte la cadena.
Leer las reglas almacenadas y las claves vinculadas
Desde la cadena v3.2.5 (SDK 0.12.0), en ambas redes se puede preguntar qué almacenó una cuenta, en lugar de reconstruirlo a partir de las transacciones:
fetchSpendingRules({ rest, address })lee las reglas de gasto, de toda la cuenta y por clave vinculada (GET /qorechain/abstractaccount/v1/accounts/{address}/spending_rules).fetchAuthenticators({ rest, address })lee las claves vinculadas, incluidas las revocadas (.../accounts/{address}/authenticators).msg.abstractaccount.updateConfiges el mensaje de gobernanza que fija los límites del módulo (la autoridad es la cuenta del módulo de gobernanza, así que una cuenta ordinaria no puede enviarlo). El SDK comprueba los valores antes de firmar.
Las reglas se comprueban como las comprueba la cadena: un denom erc20/, erc721/ o
erc1155/ debe nombrar una dirección de contrato 0x, y los códigos 8 (regla de gasto
no válida) y 9 (módulo deshabilitado) del módulo tienen nombre. El módulo sigue
desactivado en la mainnet y activado en la testnet.
El esquema de permisos
La cadena publica la taxonomía canónica de permisos de authenticator para que
los clientes validen los scopes sin hardcodear cadenas, y detecten
desincronizaciones mediante 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
La ruta REST es GET /qorechain/abstractaccount/v1/permission_schema; el
cliente de consultas gRPC tipado expone los mismos datos como
clients.abstractaccount.permissionSchema(). El módulo también sirve
/config, /accounts y /accounts/{address}.
Códigos de error
Los fallos se decodifican con decodeTxError con un kind amigable:
| Codespace | Código | 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 significa que la firma ML-DSA-87 no se verificó. La firma
hedged no es la causa (la cadena acepta por igual firmas ML-DSA-87 hedged y
deterministas); ver
Solución de problemas del código 21.
También es lo que verás si un SDK anterior a 0.6.1 codificó en JSON la extensión
híbrida (actualiza - ver
Cuentas y firma PQC).
Rotación de claves
Rota la clave ML-DSA-87 de una cuenta a una nueva clave del mismo
algoritmo — por ejemplo, para migrar una clave heredada derivada del
chain-bridge (shake256(mnemonic)) a la clave canónica ligada a la dirección
(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) reproduce por sí solo el keypair heredado cuando lo
necesites (p. ej. para seguir firmando hasta que la rotación se confirme).
Siguientes pasos
- Cuentas y firma PQC — cuentas unificadas y firma híbrida.
- Abstracción de cuentas — el módulo del lado de la cadena.
- Ejemplo ejecutable:
authenticator-spend.