Saltar al contenido principal

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.

No disponible en la mainnet

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​

CarrilMensajeSign-bytesGasta
EVMMsgExecuteEVMevmAuthSignBytesQOR nativo / llamada EVM desde la dirección 0x de la cuenta
NativoMsgExecuteCosmoscosmosAuthSignBytesQOR nativo vía x/bank desde la cuenta
Rotación de claveMsgRotatePQCKeyrotationSignBytes(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] });
Una regla limita una clave solo cuando existe

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 }).

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.nonce es este contador, no el nonce EVM de la cuenta (eth_getTransactionCount).
  • MsgExecuteCosmos.nonce es 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.updateConfig es 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:

CodespaceCódigoKind
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 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​