@qorechain/wallet-adapter 0.1.5 → 0.2.0

package/README.md

@@ -24,14 +24,77 @@ Mirrors the chain's own `qorechaind tx pqc cosign`:
 
 ```
 B0   = TxBody{messages, memo, timeoutHeight}              // no extension
-sigP = ML-DSA-87.sign( frame(B0, authInfoBytes) )         // adapter does this
+v    = resolveSignBytesVersion({ chainId, rest })          // 'v1' | 'v2', per network
+sigP = ML-DSA-87.sign( hybridSignBytes(v, chainId, B0, authInfoBytes) )  // adapter does this
 body = TxBody{ ...B0, extensionOptions:[ PQCHybridSignature{1, sigP} ] }
 sigC = wallet.signDirect( SignDoc{ body, authInfo, chainId, accountNumber } )
 tx   = TxRaw{ body, authInfo, [sigC] }
 ```
 
-where `frame(b0, auth) = BE32(len b0) ‖ b0 ‖ BE32(len auth) ‖ auth`, the extension
-type URL is `/qorechain.pqc.v1.PQCHybridSignature`, and algorithm `1` = ML-DSA-87.
+The extension type URL is `/qorechain.pqc.v1.PQCHybridSignature` and algorithm
+`1` = ML-DSA-87. The sign-bytes form `v` is chosen per network — see below.
+
+## Hybrid sign-bytes: v1 and v2 (chain v3.1.98)
+
+The ML-DSA key signs one of two byte forms (B0 = body without the PQC extension,
+A = AuthInfo bytes):
+
+```
+v1 (legacy): BE32(len B0) ‖ B0 ‖ BE32(len A) ‖ A
+v2:          "qorechain-pqc-hybrid-v2" ‖ BE64(len chainId) ‖ chainId ‖ BE32(len B0) ‖ B0 ‖ BE32(len A) ‖ A
+```
+
+v2 adds a domain tag (a signature the key made in any other context can never be
+valid transaction sign-bytes) and binds the chain-id. **A network accepts exactly
+one form at any height.** The networks that existed before chain v3.1.98
+(`qorechain-vladi` mainnet, `qorechain-diana` testnet) verify v1 until the
+`v3.1.98` upgrade plan is applied on them and v2 from then on; they upgrade at
+different heights. Today the testnet verifies v2 and **mainnet stays on v1 until
+its own upgrade**. Any other chain verifies v2 from its first block.
+
+`signBytesVersion` (on `QoreChainSigner`, per `signHybrid` call, and on
+`signHybridEth`) takes:
+
+- `'auto'` (default) — a non-legacy chain signs v2 with no network call. On
+  `qorechain-vladi` / `qorechain-diana` the adapter asks the network
+  `GET {rest}/cosmos/upgrade/v1beta1/applied_plan/v3.1.98` and signs v2 iff the
+  returned height is > 0 (compared numerically: mainnet answers `{"height":"0"}`).
+  The answer is cached per (rest, chain-id) for 60 s. **Pass `rest` (the LCD URL)**;
+  without it, or if the query fails, signing throws instead of guessing.
+- `'v1'` / `'v2'` — used as given, no network call.
+
+**Upgrading to 0.2.0.** `rest` is optional in the TypeScript types, so a caller that forgets it compiles cleanly and only fails at runtime on `qorechain-vladi` / `qorechain-diana`. Cover your wiring with a runtime test, not just a type check. In unit tests, pass `signBytesVersion: "v1"` or `"v2"` explicitly (or inject `fetch`): `"auto"` asks the network, so a test that omits it silently depends on a live node.
+
+Signed results are the usual `TxRaw` `Uint8Array`, with `.signBytesVersion`
+(`'v1' | 'v2'`) set to the form actually used.
+
+### Retry once on a sign-bytes refusal (caller side)
+
+The adapter only signs; you broadcast. A network can upgrade while a wallet is
+open, so when the version was `'auto'`, handle a refusal with `pqc` code 21
+("hybrid PQC signature verification failed") by re-resolving once:
+
+```js
+import { QoreChainSigner, isHybridSignBytesRejection } from '@qorechain/wallet-adapter';
+
+const signer = new QoreChainSigner({ wallet, chainId, address, pubkeySecp256k1,
+  accountNumber, pqc, rest: lcdUrl /* signBytesVersion: 'auto' is the default */ });
+
+let txBytes = await signer.signHybrid({ messages, fee, sequence });
+try {
+  await client.broadcastTx(txBytes);            // cosmjs throws BroadcastTxError / returns {code, rawLog}
+} catch (err) {
+  if (!isHybridSignBytesRejection(err)) throw err;   // only codespace "pqc" code 21
+  await signer.refreshSignBytesVersion();            // bypasses the cache
+  txBytes = await signer.signHybrid({ messages, fee, sequence });
+  await client.broadcastTx(txBytes);            // broadcast ONCE more; surface any error
+}
+```
+
+If you check a returned result instead of catching, pass it to
+`isHybridSignBytesRejection(result)` the same way (`{ code, rawLog }` works).
+Do not retry when you passed an explicit `'v1'`/`'v2'`, and do not treat code 21
+from another codespace as this case.
 
 **Verified end-to-end:** an adapter-built tx (ML-DSA-87 via `@noble/post-quantum`
 + classical via a cosmjs signer standing in for Keplr) **committed with code 0**
@@ -59,6 +122,7 @@ const pqc = await derivePqcKeyFromWallet(window.keplr, 'qorechain-diana', accoun
 const adapter = new QoreChainSigner({
   wallet: window.keplr, chainId: 'qorechain-diana', address: account.address,
   pubkeySecp256k1: account.pubkey, accountNumber, pqc,
+  rest, // LCD URL: lets the adapter pick the sign-bytes form this network verifies
 });
 const txBytes = await adapter.signHybrid({ messages, fee, sequence });
 await fetch(`${rpc}`, { method:'POST', body: JSON.stringify({
@@ -72,7 +136,7 @@ await fetch(`${rpc}`, { method:'POST', body: JSON.stringify({
 | **Keplr** | `experimentalSuggestChain` + `signDirect` | ✅ supported |
 | **Leap / Cosmostation** | same `signDirect` interface | ✅ supported (any wallet exposing `signDirect`) |
 | **MetaMask** | uses QoreChain's **EVM** path (chainId 9800) — structurally PQC-exempt | ✅ works natively, no adapter needed |
-| **Phantom** | derive a unified account from a Phantom signature (`walletFromSeed`) | ✅ connect → qor1/0x/svm, receive on any, spend on any (incl. hybrid PQC) |
+| **Phantom** | register the Phantom key as an authenticator on a QoreChain account | ✅ authorises spending under a permission set + SpendingRule, and is revocable. The old signature-derived recipe is withdrawn — see "Derive from a seed" |
 
 ## API
 
@@ -82,13 +146,18 @@ Wallet generation & unified addresses:
 
 eth-native Cosmos signing (chain ≥ v3.1.83):
 - `signClassicalEth({ key, chainId, accountNumber, sequence, messages, fee, memo?, timeoutHeight? })` → `TxRaw` bytes (classical, e.g. PQC key registration).
-- `signHybridEth({ ... })` → `TxRaw` bytes (eth_secp256k1 + ML-DSA-87 hybrid).
+- `signHybridEth({ ..., signBytesVersion?, rest? })` → `TxRaw` bytes (eth_secp256k1 + ML-DSA-87 hybrid); throws on a legacy network with neither an explicit version nor `rest`.
 - `ETHSECP256K1_PUBKEY_TYPE` — the eth pubkey type URL.
 
 Keplr / any-signDirect adapter + PQC framing:
-- `QoreChainSigner#signHybrid({ messages, fee, sequence, memo?, timeoutHeight? })` → `TxRaw` bytes.
+- `new QoreChainSigner({ wallet, chainId, address, pubkeySecp256k1, accountNumber, pqc, rest?, signBytesVersion? = 'auto', fetch? })`.
+- `QoreChainSigner#signHybrid({ messages, fee, sequence, memo?, timeoutHeight?, signBytesVersion? })` → `TxRaw` bytes with `.signBytesVersion`.
+- `QoreChainSigner#refreshSignBytesVersion()` → re-resolves, bypassing the cache.
 - `derivePqcKeyFromWallet(wallet, chainId, address)` — deterministic ML-DSA-87 key from a wallet signature.
-- `frame(b0, auth)` — QoreChain hybrid sign-bytes framing; `encodePqcHybridSignature(algId, sig)` — proto encoder for the extension.
+- `hybridSignBytesV1(b0, auth)`, `hybridSignBytesV2(chainId, b0, auth)`, `hybridSignBytes(version, chainId, b0, auth)` — the two sign-bytes forms and a dispatcher (version required; the old implicit `frame()` is removed).
+- `signBytesVersionFor(chainId, v2AppliedHeight)`, `resolveSignBytesVersion({ chainId, rest?, signBytesVersion?, fetch?, ttlMs?, forceRefresh? })`, `clearSignBytesCache()`, `isHybridSignBytesRejection(errOrResult)`.
+- Constants `HYBRID_SIGN_BYTES_V2_DOMAIN`, `SIGN_BYTES_V2_UPGRADE` (`"v3.1.98"`), `LEGACY_SIGN_BYTES_CHAINS`.
+- `encodePqcHybridSignature(algId, sig)` — proto encoder for the extension.
 - `qoreChainInfo({ chainId?, rpc, rest })` — Keplr chain descriptor; `qoreEvmChainParams(...)` / `addQoreEvmToWallet(provider, opts)` — MetaMask (EIP-3085) EVM descriptor.
 
 ## License
@@ -122,22 +191,31 @@ under which the chain reads one `x/bank` balance. The account can sign EVM txs
 `addressesFrom20(bytes20)` / `qoreAddresses({cosmos|evm|hex})` derive the three
 encodings from a known account (for explorers / backends).
 
-### Derive from a seed (Phantom & other non-mnemonic flows)
-
-`walletFromSeed(seed32)` builds the same unified wallet from any 32 bytes (the
-seed becomes the secp256k1 key). Because a wallet's signature over a fixed message
-is deterministic, you can derive **one canonical QoreChain account from a Phantom
-(ed25519) signature** — a Phantom user connects once and gets three usable
-QoreChain addresses they fully control:
-
-```js
-import { walletFromSeed } from "@qorechain/wallet-adapter";
-import { shake256 } from "@qorechain/pqc";
-
-const msg = new TextEncoder().encode("QoreChain unified account derivation v1");
-const { signature } = await window.solana.signMessage(msg); // Phantom, deterministic
-const w = await walletFromSeed(shake256(signature, 32));     // → qor1 / 0x / svm + pqc
-```
+### Derive from a seed (non-mnemonic flows)
+
+`walletFromSeed(seed32)` builds the same unified wallet from any 32 bytes. **The
+seed becomes the secp256k1 private key**, so it must come from something secret
+and stay secret: a CSPRNG, or a KDF over material only the user holds.
+
+> **Do not derive the seed from a wallet signature.** Versions of this README up
+> to 0.1.7 showed a Phantom "connect → three addresses" recipe built on
+> `shake256(signature)` over a fixed message. That recipe is unsound and has
+> been withdrawn. Signature schemes like ed25519 are deterministic (RFC 8032)
+> and the message was public, so the signature is a *constant* that any website
+> can ask the same wallet to reproduce — and whoever obtains it reconstructs the
+> account's entire key material, classical and ML-DSA-87, with nothing to
+> revoke. Changing the message does not fix it: any message an attacker can also
+> request yields the same key.
+>
+> If you followed that recipe, treat every account derived from it as
+> compromised and move the funds.
+
+To let an external wallet (Phantom, MetaMask, …) authorise spending on a
+QoreChain account, register its key as an **authenticator** instead:
+`MsgRegisterAuthenticator`, with an explicit permission set and a `SpendingRule`.
+The external key then signs authorisations for an account it never owned, and it
+can be revoked. See the authenticator execution lanes (`MsgExecuteEVM` /
+`MsgExecuteCosmos`, chain ≥ v3.1.85).
 
 ## eth-native Cosmos signing (requires chain ≥ v3.1.83)
 
@@ -161,7 +239,8 @@ const regTx = await signClassicalEth({ key, chainId, accountNumber, sequence,
 
 // 2) thereafter: hybrid eth_secp256k1 + ML-DSA-87 (e.g. a bank MsgSend)
 const sendTx = await signHybridEth({ key, chainId, accountNumber, sequence,
-  messages: [{ typeUrl: "/cosmos.bank.v1beta1.MsgSend", value: msgSendBytes }], fee });
+  messages: [{ typeUrl: "/cosmos.bank.v1beta1.MsgSend", value: msgSendBytes }], fee,
+  rest: lcdUrl /* picks v1/v2 for this network; or signBytesVersion: 'v1' | 'v2' */ });
 ```
 
 > **Requires QoreChain ≥ v3.1.83** — that release registers the `eth_secp256k1`
@@ -170,3 +249,52 @@ const sendTx = await signHybridEth({ key, chainId, accountNumber, sequence,
 > `@qorechain/chain-bridge` wraps this server-side (`keyType: 'eth_secp256k1'`,
 > auto-registers the PQC key on first send). **Proven live** on QoreChain: register
 > (code 0) + hybrid send (code 0) + an EVM transfer from the same key, one balance.
+
+## Authenticator lanes + key rotation (v3.1.85)
+
+Let a linked external key (Phantom ed25519 / a secp256k1 key) **spend from the
+one unified PQC-required account** under least-privilege, spend-limited terms —
+via a relayer, with no ML-DSA co-signature from the external key. Owner links the
+key once (`registerAuthenticatorMsg`, hybrid-signed); thereafter the external key
+authorizes actions on three lanes:
+
+- **SVM** — `buildPhantomSvmEnvelope` / `buildPhantomTransfer` (post to `sendTransaction`).
+- **EVM** — `buildPhantomExecuteEvm` → `MsgExecuteEVM` (relayer broadcasts).
+- **Native** — `buildPhantomExecuteCosmos` → `MsgExecuteCosmos` (relayer broadcasts).
+
+```js
+import { buildPhantomExecuteEvm, buildPhantomExecuteCosmos } from "@qorechain/wallet-adapter";
+
+// nonce = the account's CURRENT EVM nonce (eth_getTransactionCount(account0x)).
+// The relayer is a DIFFERENT account than the owner, so it does NOT pre-increment it.
+const evmMsg = await buildPhantomExecuteEvm({
+  wallet: phantom, relayer: relayerAddr, chainId, account: qor1,
+  to: "0x…", value: "100000000000000000" /* wei */, nonce });
+
+const sendMsg = await buildPhantomExecuteCosmos({
+  wallet: phantom, relayer: relayerAddr, chainId, account: qor1,
+  to: "qor1…", amount: "250uqor", nonce: authSeq /* per-authenticator sequence */ });
+// → hand each msg to your relayer; it broadcasts with its own hybrid-PQC signature.
+```
+
+Errors (codespace `abstractaccount`): `5` spending-limit, `6` session-key expired
+(render "re-link"), `10` permission-denied, `11` replay. Fetch the live scope
+taxonomy over REST: `GET /qorechain/abstractaccount/v1/permission_schema`.
+
+**Key rotation** (`MsgRotatePQCKey`) — migrate a legacy chain-bridge key
+(`shake256(mnemonic)`) to the canonical address-bound key of the SAME algorithm:
+
+```js
+import { rotatePqcKeyMsgFromMnemonic } from "@qorechain/wallet-adapter";
+const { msg, oldKeypair } = rotatePqcKeyMsgFromMnemonic({ account: qor1, mnemonic, chainId });
+// broadcast `msg` from the account, cosigned (hybrid) with `oldKeypair` (still the
+// registered key until the rotation lands) — e.g. a QoreChainSigner whose pqc=oldKeypair.
+```
+
+For a **MetaMask / EVM** key use `registerEthAuthenticatorMsg` (link by 0x address) + `buildMetaMaskExecuteEvm` / `buildMetaMaskExecuteCosmos` — the key signs the digest with `personal_sign` (EIP-191) and the chain verifies by ecrecover, so no raw pubkey is needed. Live-proven: a MetaMask-signed EVM transfer from the unified account committed on QoreChain.
+
+> **Requires QoreChain ≥ v3.1.85.** Auth sign-bytes (`evmAuthSignBytes`,
+> `cosmosAuthSignBytes`) are rebuilt byte-for-byte from the chain and guarded by
+> tests. For a **secp256k1** authenticator the chain uses cosmos `VerifySignature`
+> (sha256-based), NOT MetaMask `personal_sign` — sign the digest with a
+> cosmos-style secp256k1 signer, not `personal_sign`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qorechain/wallet-adapter",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "Drop-in adapter to add QoreChain to any Cosmos wallet (Keplr, Leap, Cosmostation, …) and sign its PQC-required transactions. The wallet signs an ordinary SIGN_MODE_DIRECT SignDoc; the adapter layers a standard FIPS-204 ML-DSA-87 hybrid signature into the tx body, so no wallet code changes are needed.",
   "type": "module",
   "main": "src/index.js",

package/src/authenticator.js

@@ -0,0 +1,314 @@
+// @qorechain/wallet-adapter — v3.1.85 authenticator lanes (EVM + Native/Cosmos)
+// and same-algorithm PQC key rotation.
+//
+// v3.1.84 introduced the SVM authenticator lane (see phantom.js). v3.1.85 adds
+// two more lanes so a linked external key (Phantom ed25519 / a secp256k1 key)
+// can spend from the ONE unified PQC-required account under least-privilege,
+// spend-limited, revocable terms — via a relayer, WITHOUT the external key ever
+// producing an ML-DSA co-signature:
+//
+//   • EVM lane    — MsgExecuteEVM:    EVM call/transfer from the account's 0x addr.
+//   • Native lane — MsgExecuteCosmos: bank send from the account (Cosmos).
+//
+// The relayer submits + pays fees (its own hybrid-PQC signature satisfies the
+// ante on the envelope); the authenticator's signature over the domain-separated,
+// replay-bound sign-bytes IS the authorization. The digests below are rebuilt
+// BYTE-FOR-BYTE from the chain (x/abstractaccount/types/{evm,cosmos}_sign.go) — a
+// mismatch is rejected on-chain (codespace abstractaccount, code 11 replay / 10
+// permission / 5 spending-limit / 6 session-expired).
+//
+// Chain signature check (keeper.VerifyAuthenticatorSignature): for scheme
+// "ed25519" it is ed25519.Verify(pubkey, digest, sig) — so a Phantom
+// `signMessage(digest)` matches directly (the builders below). For "secp256k1"
+// the chain uses cosmos secp256k1 VerifySignature (sha256-based, NOT MetaMask
+// personal_sign), so a MetaMask personal_sign will NOT verify — provide the
+// digest to a cosmos-style secp256k1 signer instead.
+
+import { mldsa, shake256 } from '@qorechain/pqc';
+
+// ---- byte helpers (match the chain's binary.BigEndian + length-prefix framing) ----
+
+const enc = new TextEncoder();
+
+function be64(n) {
+  const b = new Uint8Array(8);
+  let v = BigInt(n);
+  for (let i = 7; i >= 0; i--) { b[i] = Number(v & 0xffn); v >>= 8n; }
+  return b;
+}
+
+function concat(parts) {
+  let len = 0; for (const p of parts) len += p.length;
+  const out = new Uint8Array(len); let o = 0;
+  for (const p of parts) { out.set(p, o); o += p.length; }
+  return out;
+}
+
+// length-prefixed field: BE64(len) ‖ bytes
+function lp(bytes) { return concat([be64(bytes.length), bytes]); }
+
+function toBytes(x) {
+  if (x instanceof Uint8Array) return x;
+  if (typeof x === 'string') return enc.encode(x);
+  return new Uint8Array(x);
+}
+
+async function sha256(bytes) {
+  if (typeof globalThis.crypto?.subtle?.digest === 'function') {
+    return new Uint8Array(await globalThis.crypto.subtle.digest('SHA-256', bytes));
+  }
+  const { createHash } = await import('crypto');
+  return new Uint8Array(createHash('sha256').update(bytes).digest());
+}
+
+function toHexLower(bytes) {
+  let s = ''; for (const b of bytes) s += b.toString(16).padStart(2, '0');
+  return s;
+}
+
+// ---- sign-bytes (the digest an authenticator signs) ----
+
+/**
+ * evmAuthSignBytes rebuilds the 32-byte digest the chain re-derives for a
+ * MsgExecuteEVM (types.EVMAuthSignBytes):
+ *   sha256( "qorechain-evm-auth-v1"
+ *           ‖ LP(chainId) ‖ LP(account) ‖ LP(pubkey)
+ *           ‖ LP(to) ‖ LP(value) ‖ LP(data) ‖ BE64(nonce) )
+ * `to` is the 0x-hex recipient string, `value` is the decimal wei (aqor) string,
+ * `data` is the raw calldata (Uint8Array). `pubkey` is the authenticator's raw
+ * public key (32 bytes for ed25519). Returns Uint8Array(32) — what the wallet signs.
+ *
+ * NONCE: the account's CURRENT EVM nonce (eth_getTransactionCount(account0x)).
+ * In production the relayer is a DIFFERENT account than the owner, so the relayer
+ * envelope does NOT bump the account's nonce — use the current value as-is. (Only
+ * if relayer === owner does the envelope pre-increment it, needing current+1.)
+ */
+export async function evmAuthSignBytes({ chainId, account, pubkey, to = '', value = '0', data = new Uint8Array(0), nonce }) {
+  const body = concat([
+    enc.encode('qorechain-evm-auth-v1'),
+    lp(toBytes(chainId)), lp(toBytes(account)), lp(toBytes(pubkey)),
+    lp(toBytes(to)), lp(toBytes(value)), lp(toBytes(data)),
+    be64(nonce),
+  ]);
+  return sha256(body);
+}
+
+/**
+ * cosmosAuthSignBytes rebuilds the 32-byte digest the chain re-derives for a
+ * MsgExecuteCosmos (types.CosmosAuthSignBytes):
+ *   sha256( "qorechain-cosmos-auth-v1"
+ *           ‖ LP(chainId) ‖ LP(account) ‖ LP(pubkey)
+ *           ‖ LP(to) ‖ LP(amount) ‖ BE64(nonce) )
+ * `to` is the bech32 recipient, `amount` is the CANONICAL sdk.Coins string
+ * (sorted, e.g. "100uqor"). Returns Uint8Array(32).
+ *
+ * NONCE: the per-authenticator sequence for (account, pubkey) — a store counter
+ * distinct from the account's own sequence, incremented on each successful
+ * Native-lane spend. (Query it from the chain / track it client-side.)
+ */
+export async function cosmosAuthSignBytes({ chainId, account, pubkey, to, amount, nonce }) {
+  const body = concat([
+    enc.encode('qorechain-cosmos-auth-v1'),
+    lp(toBytes(chainId)), lp(toBytes(account)), lp(toBytes(pubkey)),
+    lp(toBytes(to)), lp(toBytes(amount)),
+    be64(nonce),
+  ]);
+  return sha256(body);
+}
+
+/**
+ * rotationSignBytes returns the domain-separated STRING both the old and the new
+ * key sign for a MsgRotatePQCKey (types.RotationSignBytes):
+ *   "qorechain-pqc-rotate-v1|<chainId>|<algorithmId>|<account>|<oldHex>|<newHex>"
+ * oldHex/newHex are lowercase hex of the public keys. Sign `utf8(this string)`.
+ */
+export function rotationSignBytes(chainId, algorithmId, account, oldPub, newPub) {
+  return `qorechain-pqc-rotate-v1|${chainId}|${algorithmId}|${account}|${toHexLower(oldPub)}|${toHexLower(newPub)}`;
+}
+
+// ---- message composers (shapes for cosmjs registry / *.fromPartial) ----
+
+/** parse a single-coin amount string like "100uqor" → [{denom,amount}]. */
+function parseCoins(amount) {
+  const m = /^([0-9]+)([a-zA-Z][a-zA-Z0-9/:._-]*)$/.exec(String(amount).trim());
+  if (!m) throw new Error(`invalid amount "${amount}" (expected e.g. "100uqor")`);
+  return [{ denom: m[2], amount: m[1] }];
+}
+
+/** MsgExecuteEVM — the relayer broadcasts this (it is the message `relayer`/fee payer). */
+export function executeEvmMsg({ relayer, account, scheme, pubkey, signature, to = '', value = '0', data = new Uint8Array(0), gasLimit, nonce }) {
+  return {
+    typeUrl: '/qorechain.abstractaccount.v1.MsgExecuteEVM',
+    value: {
+      relayer, account, scheme,
+      pubkey: toBytes(pubkey), signature: toBytes(signature),
+      to, value, data: toBytes(data),
+      gasLimit: BigInt(gasLimit), nonce: BigInt(nonce),
+    },
+  };
+}
+
+/** MsgExecuteCosmos — the relayer broadcasts this. `amount` is "100uqor"-style. */
+export function executeCosmosMsg({ relayer, account, scheme, pubkey, signature, to, amount, nonce }) {
+  return {
+    typeUrl: '/qorechain.abstractaccount.v1.MsgExecuteCosmos',
+    value: {
+      relayer, account, scheme,
+      pubkey: toBytes(pubkey), signature: toBytes(signature),
+      to, amount: parseCoins(amount), nonce: BigInt(nonce),
+    },
+  };
+}
+
+/** MsgRevokeAuthenticator — owner-signed; instantly disables a linked key. */
+export function revokeAuthenticatorMsg({ owner, account = owner, scheme, pubkey }) {
+  return {
+    typeUrl: '/qorechain.abstractaccount.v1.MsgRevokeAuthenticator',
+    value: { owner, accountAddress: account, scheme, pubkey: toBytes(pubkey) },
+  };
+}
+
+/** MsgRotatePQCKey — sender-signed (hybrid, with the OLD key); dual-signed payload. */
+export function rotatePqcKeyMsg({ sender, oldPublicKey, newPublicKey, oldSignature, newSignature }) {
+  return {
+    typeUrl: '/qorechain.pqc.v1.MsgRotatePQCKey',
+    value: {
+      sender,
+      oldPublicKey: toBytes(oldPublicKey), newPublicKey: toBytes(newPublicKey),
+      oldSignature: toBytes(oldSignature), newSignature: toBytes(newSignature),
+    },
+  };
+}
+
+// ---- Phantom (ed25519) envelope builders for the EVM + Native lanes ----
+
+function walletPubkey(wallet) {
+  return wallet.publicKey?.toBytes ? wallet.publicKey.toBytes() : new Uint8Array(wallet.publicKey);
+}
+
+/**
+ * buildPhantomExecuteEvm signs the EVM auth digest with a Phantom-style ed25519
+ * wallet and returns a MsgExecuteEVM ready for the relayer to broadcast. The
+ * relayer address is the fee payer (a DIFFERENT account than `account`).
+ */
+export async function buildPhantomExecuteEvm({ wallet, relayer, chainId, account, to = '', value = '0', data = new Uint8Array(0), gasLimit = 100000, nonce }) {
+  const pubkey = walletPubkey(wallet);
+  const digest = await evmAuthSignBytes({ chainId, account, pubkey, to, value, data, nonce });
+  const { signature } = await wallet.signMessage(digest);
+  return executeEvmMsg({ relayer, account, scheme: 'ed25519', pubkey, signature, to, value, data, gasLimit, nonce });
+}
+
+/**
+ * buildPhantomExecuteCosmos signs the Native auth digest with a Phantom-style
+ * ed25519 wallet and returns a MsgExecuteCosmos ready for the relayer. `amount`
+ * is a single-coin string like "100uqor".
+ */
+export async function buildPhantomExecuteCosmos({ wallet, relayer, chainId, account, to, amount, nonce }) {
+  const pubkey = walletPubkey(wallet);
+  const digest = await cosmosAuthSignBytes({ chainId, account, pubkey, to, amount, nonce });
+  const { signature } = await wallet.signMessage(digest);
+  return executeCosmosMsg({ relayer, account, scheme: 'ed25519', pubkey, signature, to, amount, nonce });
+}
+
+// ---- MetaMask (EIP-191 personal_sign / secp256k1) envelope builders ----
+//
+// A browser EVM wallet exposes only its 20-byte address + `personal_sign`, never
+// the raw public key, so the account is linked by its ETH ADDRESS (scheme
+// "secp256k1", 20-byte pubkey). The chain verifies with EIP-191 + ecrecover
+// (v3.1.85). The digest the wallet signs is the SAME one the Phantom/cosmos
+// paths use — only the signing scheme differs.
+
+function hexToBytes(hex) {
+  hex = String(hex).replace(/^0x/, '');
+  const o = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < o.length; i++) o[i] = parseInt(hex.substr(i * 2, 2), 16);
+  return o;
+}
+function bytesToHex0x(b) { let s = '0x'; for (const x of b) s += x.toString(16).padStart(2, '0'); return s; }
+
+// personal_sign over the 32-byte digest via an EIP-1193 provider (e.g. MetaMask).
+async function ethPersonalSign(provider, address, digest) {
+  const sigHex = await provider.request({ method: 'personal_sign', params: [bytesToHex0x(digest), address] });
+  return hexToBytes(sigHex); // 65 bytes r‖s‖v (v = 27/28)
+}
+
+/**
+ * registerEthAuthenticatorMsg builds the owner-signed MsgRegisterAuthenticator
+ * that links a MetaMask / EVM key (by its 0x address) to the owner's account.
+ * `ethAddress` is the 0x-hex 20-byte address.
+ */
+export function registerEthAuthenticatorMsg({ owner, account = owner, ethAddress, permissions = ['evm'], expiryUnix, label = 'metamask' }) {
+  return {
+    typeUrl: '/qorechain.abstractaccount.v1.MsgRegisterAuthenticator',
+    value: {
+      owner, accountAddress: account, scheme: 'secp256k1',
+      pubkey: hexToBytes(ethAddress), permissions, expiryUnix: BigInt(expiryUnix), label,
+    },
+  };
+}
+
+/** buildMetaMaskExecuteEvm: MetaMask (EIP-191) → MsgExecuteEVM ready for the relayer. */
+export async function buildMetaMaskExecuteEvm({ provider, address, relayer, chainId, account, to = '', value = '0', data = new Uint8Array(0), gasLimit = 100000, nonce }) {
+  const pubkey = hexToBytes(address); // 20-byte eth address = the authenticator pubkey
+  const digest = await evmAuthSignBytes({ chainId, account, pubkey, to, value, data, nonce });
+  const signature = await ethPersonalSign(provider, address, digest);
+  return executeEvmMsg({ relayer, account, scheme: 'secp256k1', pubkey, signature, to, value, data, gasLimit, nonce });
+}
+
+/** buildMetaMaskExecuteCosmos: MetaMask (EIP-191) → MsgExecuteCosmos ready for the relayer. */
+export async function buildMetaMaskExecuteCosmos({ provider, address, relayer, chainId, account, to, amount, nonce }) {
+  const pubkey = hexToBytes(address);
+  const digest = await cosmosAuthSignBytes({ chainId, account, pubkey, to, amount, nonce });
+  const signature = await ethPersonalSign(provider, address, digest);
+  return executeCosmosMsg({ relayer, account, scheme: 'secp256k1', pubkey, signature, to, amount, nonce });
+}
+
+// ---- key rotation (legacy → canonical migration) ----
+
+const CANONICAL = 'adapter'; // shake256("qorechain:pqc:v1|addr|mnemonic")  (SDK/wallet-adapter)
+const LEGACY = 'bridge';     // shake256(mnemonic)                          (chain-bridge/faucet-api)
+
+function derivePqcByScheme(scheme, account, mnemonic) {
+  if (scheme === LEGACY || scheme === 'mnemonic-only') {
+    return mldsa.keygen(shake256(enc.encode(mnemonic), 32));
+  }
+  if (scheme === CANONICAL || scheme === '' || scheme === undefined) {
+    return mldsa.keygen(shake256(enc.encode(`qorechain:pqc:v1|${account}|${mnemonic}`), 32));
+  }
+  throw new Error(`unknown derivation "${scheme}" (use adapter|bridge)`);
+}
+
+/**
+ * rotatePqcKeyMsgFromMnemonic builds a MsgRotatePQCKey that rotates an account's
+ * ML-DSA-87 key (SAME algorithm) from one derivation to another — the canonical
+ * use is migrating a LEGACY chain-bridge key (`shake256(mnemonic)`) to the
+ * canonical address-bound key (`shake256("qorechain:pqc:v1|addr|mnemonic")`), so
+ * a wallet whose key was registered by a backend can move to the standard
+ * derivation. Both keys dual-sign the domain-separated rotation bytes.
+ *
+ * The returned message must be broadcast BY the account, cosigned (hybrid) with
+ * the OLD key (it is still the registered key until the rotation lands) — i.e.
+ * sign the envelope with a QoreChainSigner whose `pqc` is the OLD keypair.
+ *
+ * @returns {{ msg: object, oldKeypair: {publicKey,secretKey}, newKeypair: {publicKey,secretKey} }}
+ */
+export function rotatePqcKeyMsgFromMnemonic({ account, mnemonic, chainId, algorithmId = 1, oldDerivation = LEGACY, newDerivation = CANONICAL }) {
+  const oldKp = derivePqcByScheme(oldDerivation, account, mnemonic);
+  const newKp = derivePqcByScheme(newDerivation, account, mnemonic);
+  if (toHexLower(oldKp.publicKey) === toHexLower(newKp.publicKey)) {
+    throw new Error('old and new derivations produce the same key — rotation would be a no-op');
+  }
+  const sb = enc.encode(rotationSignBytes(chainId, algorithmId, account, oldKp.publicKey, newKp.publicKey));
+  const msg = rotatePqcKeyMsg({
+    sender: account,
+    oldPublicKey: oldKp.publicKey, newPublicKey: newKp.publicKey,
+    oldSignature: mldsa.sign(oldKp.secretKey, sb),
+    newSignature: mldsa.sign(newKp.secretKey, sb),
+  });
+  return { msg, oldKeypair: oldKp, newKeypair: newKp };
+}
+
+/** derivePqcLegacy exposes the LEGACY (chain-bridge) derivation for a mnemonic. */
+export function derivePqcLegacy(mnemonic) {
+  return mldsa.keygen(shake256(enc.encode(mnemonic), 32));
+}

package/src/framing.js

@@ -1,17 +1,11 @@
-// Pure, dependency-free QoreChain PQC tx-extension framing (the chain-matching bits).
+// Pure, dependency-free QoreChain PQC tx-extension encoding (the chain-matching bits).
+//
+// The bytes the ML-DSA key signs are built in ./signbytes.js, which carries both
+// forms (v1 legacy / v2) and the per-network resolver. There is deliberately no
+// helper here that picks a form implicitly: every caller passes the version.
 export const HYBRID_SIG_TYPE_URL = '/qorechain.pqc.v1.PQCHybridSignature';
 export const ALGORITHM_ML_DSA_87 = 1; // chain AlgorithmDilithium5 == FIPS-204 ML-DSA-87
 
-export function frame(b0, auth) {
-  const out = new Uint8Array(4 + b0.length + 4 + auth.length);
-  const dv = new DataView(out.buffer);
-  dv.setUint32(0, b0.length, false);
-  out.set(b0, 4);
-  dv.setUint32(4 + b0.length, auth.length, false);
-  out.set(auth, 8 + b0.length);
-  return out;
-}
-
 export function encodePqcHybridSignature(algorithmId, sig) {
   const varint = (n) => { const b = []; while (n > 0x7f) { b.push((n & 0x7f) | 0x80); n >>>= 7; } b.push(n); return b; };
   return Uint8Array.from([0x08, ...varint(algorithmId), 0x12, ...varint(sig.length), ...sig]);

package/src/index.d.ts

@@ -36,8 +36,11 @@ export interface EthSignArgs {
 }
 /** Classical-only eth_secp256k1 Cosmos tx (e.g. the bootstrap MsgRegisterPQCKeyV2). */
 export function signClassicalEth(args: EthSignArgs): Promise<Uint8Array>;
-/** Hybrid eth_secp256k1 + ML-DSA-87 Cosmos tx (key.pqc required). */
-export function signHybridEth(args: EthSignArgs): Promise<Uint8Array>;
+/**
+ * Hybrid eth_secp256k1 + ML-DSA-87 Cosmos tx (key.pqc required). Throws on a
+ * legacy network when neither an explicit signBytesVersion nor `rest` is given.
+ */
+export function signHybridEth(args: EthSignArgs & { signBytesVersion?: SignBytesVersionOption; rest?: string; fetch?: typeof globalThis.fetch }): Promise<SignedTxBytes>;
 
 // --- EVM network descriptors (EIP-3085 / MetaMask) ---
 export function qoreEvmChainParams(opts?: { evmChainId?: number; rpcUrl?: string; wsUrl?: string; explorerUrl?: string; testnet?: boolean }): any;
@@ -53,11 +56,78 @@ export function authSignBytes(p: { programId: string; accounts: SvmAccountMeta[]
 export function buildPhantomSvmEnvelope(p: { wallet: any; programId?: string; accounts: SvmAccountMeta[]; data: Uint8Array; recentBlockhashHex: string }): Promise<any>;
 export function buildPhantomTransfer(p: { wallet: any; fromSvmAddr: string; toSvmAddr: string; lamports: number | bigint; recentBlockhashHex: string }): Promise<any>;
 export function registerAuthenticatorMsg(p: { owner: string; phantomPubkey: Uint8Array; permissions?: string[]; expiryUnix: number | bigint; label?: string }): { typeUrl: string; value: any };
-export function frame(b0: Uint8Array, auth: Uint8Array): Uint8Array;
+// --- Per-network hybrid PQC sign-bytes (v1 legacy / v2, chain v3.1.98) ---
+export type SignBytesVersion = 'v1' | 'v2';
+export type SignBytesVersionOption = SignBytesVersion | 'auto';
+export const HYBRID_SIGN_BYTES_V2_DOMAIN: 'qorechain-pqc-hybrid-v2';
+export const SIGN_BYTES_V2_UPGRADE: 'v3.1.98';
+export const LEGACY_SIGN_BYTES_CHAINS: readonly string[];
+/** v1: BE32(len b0) ‖ b0 ‖ BE32(len authInfo) ‖ authInfo. */
+export function hybridSignBytesV1(b0: Uint8Array, authInfo: Uint8Array): Uint8Array;
+/** v2: domain ‖ BE64(len chainId) ‖ chainId ‖ BE32(len b0) ‖ b0 ‖ BE32(len authInfo) ‖ authInfo. */
+export function hybridSignBytesV2(chainId: string, b0: Uint8Array, authInfo: Uint8Array): Uint8Array;
+/** Version-dispatching builder; `version` is required. */
+export function hybridSignBytes(version: SignBytesVersion, chainId: string, b0: Uint8Array, authInfo: Uint8Array): Uint8Array;
+/** Mirror of the chain's SignBytesVersionFor; the height is compared numerically ("0" → not applied). */
+export function signBytesVersionFor(chainId: string, v2AppliedHeight: string | number | bigint | null | undefined): SignBytesVersion;
+export function resolveSignBytesVersion(opts: {
+  chainId: string;
+  rest?: string;
+  signBytesVersion?: SignBytesVersionOption;
+  fetch?: typeof globalThis.fetch;
+  ttlMs?: number;
+  forceRefresh?: boolean;
+}): Promise<SignBytesVersion>;
+export function clearSignBytesCache(): void;
+/** True iff the error/result is the chain refusing the hybrid PQC signature (codespace "pqc", code 21). */
+export function isHybridSignBytesRejection(errOrResult: unknown): boolean;
+/** TxRaw bytes plus the sign-bytes form that was used. */
+export type SignedTxBytes = Uint8Array & { signBytesVersion: SignBytesVersion };
 export function encodePqcHybridSignature(algorithmId: number, sig: Uint8Array): Uint8Array;
 export function derivePqcKeyFromWallet(wallet: any, chainId: string, address: string, domain?: string): Promise<{ publicKey: Uint8Array; secretKey: Uint8Array }>;
 export function qoreChainInfo(opts?: { chainId?: string; rpc?: string; rest?: string }): any;
 export class QoreChainSigner {
-  constructor(opts: { wallet: any; chainId: string; address: string; pubkeySecp256k1: Uint8Array; accountNumber: number | bigint; pqc: { publicKey: Uint8Array; secretKey: Uint8Array } });
-  signHybrid(opts: { messages: any[]; fee: any; memo?: string; sequence: number | bigint; timeoutHeight?: bigint }): Promise<Uint8Array>;
+  constructor(opts: {
+    wallet: any; chainId: string; address: string; pubkeySecp256k1: Uint8Array; accountNumber: number | bigint;
+    pqc: { publicKey: Uint8Array; secretKey: Uint8Array };
+    /** LCD URL; required to auto-resolve the sign-bytes form on qorechain-vladi / qorechain-diana. */
+    rest?: string;
+    /** Default 'auto'. */
+    signBytesVersion?: SignBytesVersionOption;
+    fetch?: typeof globalThis.fetch;
+  });
+  signHybrid(opts: { messages: any[]; fee: any; memo?: string; sequence: number | bigint; timeoutHeight?: bigint; signBytesVersion?: SignBytesVersionOption }): Promise<SignedTxBytes>;
+  /** Re-resolve bypassing the cache; returns the new form. */
+  refreshSignBytesVersion(): Promise<SignBytesVersion>;
 }
+
+// --- v3.1.85 authenticator lanes (EVM + Native/Cosmos) + PQC key rotation (requires chain >= v3.1.85) ---
+export interface PqcKeypairFull { publicKey: Uint8Array; secretKey: Uint8Array; }
+/** 32-byte digest an authenticator signs to authorize a MsgExecuteEVM. */
+export function evmAuthSignBytes(p: { chainId: string; account: string; pubkey: Uint8Array; to?: string; value?: string; data?: Uint8Array; nonce: number | bigint }): Promise<Uint8Array>;
+/** 32-byte digest an authenticator signs to authorize a MsgExecuteCosmos. */
+export function cosmosAuthSignBytes(p: { chainId: string; account: string; pubkey: Uint8Array; to: string; amount: string; nonce: number | bigint }): Promise<Uint8Array>;
+/** Domain-separated STRING both keys sign for a MsgRotatePQCKey (sign utf8 of it). */
+export function rotationSignBytes(chainId: string, algorithmId: number, account: string, oldPub: Uint8Array, newPub: Uint8Array): string;
+/** MsgExecuteEVM (relayer broadcasts + pays fees). */
+export function executeEvmMsg(p: { relayer: string; account: string; scheme: string; pubkey: Uint8Array; signature: Uint8Array; to?: string; value?: string; data?: Uint8Array; gasLimit: number | bigint; nonce: number | bigint }): { typeUrl: string; value: any };
+/** MsgExecuteCosmos (relayer broadcasts). `amount` is a single-coin string e.g. "100uqor". */
+export function executeCosmosMsg(p: { relayer: string; account: string; scheme: string; pubkey: Uint8Array; signature: Uint8Array; to: string; amount: string; nonce: number | bigint }): { typeUrl: string; value: any };
+/** MsgRevokeAuthenticator (owner-signed) — instantly disables a linked key. */
+export function revokeAuthenticatorMsg(p: { owner: string; account?: string; scheme: string; pubkey: Uint8Array }): { typeUrl: string; value: any };
+/** MsgRotatePQCKey (sender-signed hybrid with the OLD key). */
+export function rotatePqcKeyMsg(p: { sender: string; oldPublicKey: Uint8Array; newPublicKey: Uint8Array; oldSignature: Uint8Array; newSignature: Uint8Array }): { typeUrl: string; value: any };
+/** Phantom (ed25519) → MsgExecuteEVM ready for the relayer. */
+export function buildPhantomExecuteEvm(p: { wallet: any; relayer: string; chainId: string; account: string; to?: string; value?: string; data?: Uint8Array; gasLimit?: number | bigint; nonce: number | bigint }): Promise<{ typeUrl: string; value: any }>;
+/** Phantom (ed25519) → MsgExecuteCosmos ready for the relayer. */
+export function buildPhantomExecuteCosmos(p: { wallet: any; relayer: string; chainId: string; account: string; to: string; amount: string; nonce: number | bigint }): Promise<{ typeUrl: string; value: any }>;
+/** Build a MsgRotatePQCKey to migrate a key between derivations (default legacy→canonical). Broadcast cosigned with the OLD keypair. */
+export function rotatePqcKeyMsgFromMnemonic(p: { account: string; mnemonic: string; chainId: string; algorithmId?: number; oldDerivation?: 'adapter' | 'bridge'; newDerivation?: 'adapter' | 'bridge' }): { msg: { typeUrl: string; value: any }; oldKeypair: PqcKeypairFull; newKeypair: PqcKeypairFull };
+/** The LEGACY (chain-bridge) ML-DSA-87 derivation `shake256(mnemonic)`. */
+export function derivePqcLegacy(mnemonic: string): PqcKeypairFull;
+/** Link a MetaMask / EVM key (by 0x address) as a scoped authenticator (owner-signed). */
+export function registerEthAuthenticatorMsg(p: { owner: string; account?: string; ethAddress: string; permissions?: string[]; expiryUnix: number | bigint; label?: string }): { typeUrl: string; value: any };
+/** MetaMask (EIP-191 personal_sign) → MsgExecuteEVM ready for the relayer. `provider` is EIP-1193. */
+export function buildMetaMaskExecuteEvm(p: { provider: any; address: string; relayer: string; chainId: string; account: string; to?: string; value?: string; data?: Uint8Array; gasLimit?: number | bigint; nonce: number | bigint }): Promise<{ typeUrl: string; value: any }>;
+/** MetaMask (EIP-191 personal_sign) → MsgExecuteCosmos ready for the relayer. */
+export function buildMetaMaskExecuteCosmos(p: { provider: any; address: string; relayer: string; chainId: string; account: string; to: string; amount: string; nonce: number | bigint }): Promise<{ typeUrl: string; value: any }>;

package/src/index.js

@@ -14,16 +14,27 @@
 //
 // Protocol (mirrors the chain's `tx pqc cosign`):
 //   B0   = TxBody{messages, memo, timeoutHeight}            (no extension)
-//   sigP = ML-DSA-87.sign( frame(B0, authInfoBytes) )       // frame = below
+//   v    = resolveSignBytesVersion({chainId, rest})         // 'v1' | 'v2', per network
+//   sigP = ML-DSA-87.sign( hybridSignBytes(v, chainId, B0, authInfoBytes) )
 //   body = TxBody{...B0, extensionOptions:[PQCHybridSignature{1, sigP}]}
 //   sigC = wallet.signDirect( SignDoc{body, authInfo, chainId, accountNumber} )
 //   tx   = TxRaw{ body, authInfo, [sigC] }
 //
-// where frame(b0, auth) = BE32(len b0) ‖ b0 ‖ BE32(len auth) ‖ auth.
+// v1 = BE32(len b0) ‖ b0 ‖ BE32(len auth) ‖ auth
+// v2 = "qorechain-pqc-hybrid-v2" ‖ BE64(len chainId) ‖ chainId ‖ v1-layout
+// A network accepts exactly one form at a time; see ./signbytes.js.
 
 import { mldsa, shake256 } from '@qorechain/pqc';
-import { frame, encodePqcHybridSignature, HYBRID_SIG_TYPE_URL, ALGORITHM_ML_DSA_87 } from './framing.js';
-export { frame, encodePqcHybridSignature, HYBRID_SIG_TYPE_URL, ALGORITHM_ML_DSA_87 };
+import { encodePqcHybridSignature, HYBRID_SIG_TYPE_URL, ALGORITHM_ML_DSA_87 } from './framing.js';
+import { hybridSignBytes, resolveSignBytesVersion } from './signbytes.js';
+export { encodePqcHybridSignature, HYBRID_SIG_TYPE_URL, ALGORITHM_ML_DSA_87 };
+// Per-network hybrid sign-bytes (v1 legacy / v2) + resolver + rejection detector.
+export {
+  HYBRID_SIGN_BYTES_V2_DOMAIN, SIGN_BYTES_V2_UPGRADE, LEGACY_SIGN_BYTES_CHAINS,
+  hybridSignBytesV1, hybridSignBytesV2, hybridSignBytes,
+  signBytesVersionFor, resolveSignBytesVersion, clearSignBytesCache,
+  isHybridSignBytesRejection,
+} from './signbytes.js';
 // Phantom / any-ed25519-wallet support: drive the one unified account from Phantom.
 export {
   base58Encode, base58Decode, SYSTEM_PROGRAM_ID, systemTransferData,
@@ -37,6 +48,14 @@ export {
 export {
   signClassicalEth, signHybridEth, ETHSECP256K1_PUBKEY_TYPE,
 } from './sign-eth.js';
+// v3.1.85 authenticator lanes (EVM + Native/Cosmos) + PQC key rotation.
+export {
+  evmAuthSignBytes, cosmosAuthSignBytes, rotationSignBytes,
+  executeEvmMsg, executeCosmosMsg, revokeAuthenticatorMsg, rotatePqcKeyMsg,
+  buildPhantomExecuteEvm, buildPhantomExecuteCosmos,
+  registerEthAuthenticatorMsg, buildMetaMaskExecuteEvm, buildMetaMaskExecuteCosmos,
+  rotatePqcKeyMsgFromMnemonic, derivePqcLegacy,
+} from './authenticator.js';
 import { TxBody, AuthInfo, TxRaw, SignerInfo, ModeInfo, Fee } from 'cosmjs-types/cosmos/tx/v1beta1/tx.js';
 import { SignMode } from 'cosmjs-types/cosmos/tx/signing/v1beta1/signing.js';
 import { SignDoc } from 'cosmjs-types/cosmos/tx/v1beta1/tx.js';
@@ -56,12 +75,37 @@ export async function derivePqcKeyFromWallet(wallet, chainId, address, domain =
 export class QoreChainSigner {
   // wallet: a Keplr-like object exposing signDirect(chainId, signer, signDoc) and
   //         (optionally) signArbitrary(...). pqc: { publicKey, secretKey } ML-DSA-87.
-  constructor({ wallet, chainId, address, pubkeySecp256k1, accountNumber, pqc }) {
-    Object.assign(this, { wallet, chainId, address, pubkeySecp256k1, accountNumber, pqc });
+  // rest:   the network's LCD URL; needed to auto-resolve the sign-bytes form on
+  //         qorechain-vladi / qorechain-diana.
+  // signBytesVersion: 'auto' (default) | 'v1' | 'v2'.
+  // fetch:  optional fetch implementation for the resolver (defaults to globalThis.fetch).
+  constructor({ wallet, chainId, address, pubkeySecp256k1, accountNumber, pqc, rest, signBytesVersion = 'auto', fetch }) {
+    Object.assign(this, { wallet, chainId, address, pubkeySecp256k1, accountNumber, pqc, rest, signBytesVersion });
+    if (fetch) this.fetch = fetch;
+  }
+
+  _resolve(signBytesVersion, forceRefresh = false) {
+    return resolveSignBytesVersion({
+      chainId: this.chainId, rest: this.rest,
+      signBytesVersion: signBytesVersion ?? this.signBytesVersion ?? 'auto',
+      forceRefresh,
+      ...(this.fetch ? { fetch: this.fetch } : {}),
+    });
+  }
+
+  // Re-ask the network (bypassing the cache) which form it verifies. Call this
+  // after a broadcast is refused with isHybridSignBytesRejection(err), then sign
+  // again and broadcast once more. With an explicit version it returns that version.
+  async refreshSignBytesVersion() {
+    return this._resolve(undefined, true);
   }
 
-  // Build + hybrid-sign + return TxRaw bytes ready to broadcast.
-  async signHybrid({ messages, fee, memo = '', sequence, timeoutHeight = 0n }) {
+  // Build + hybrid-sign + return TxRaw bytes ready to broadcast. The returned
+  // Uint8Array also carries `.signBytesVersion` ('v1' | 'v2'), the form used.
+  // `signBytesVersion` overrides the signer's setting for this call.
+  async signHybrid({ messages, fee, memo = '', sequence, timeoutHeight = 0n, signBytesVersion }) {
+    const version = await this._resolve(signBytesVersion);
+
     // 1. AuthInfo: single DIRECT signer (secp256k1) + fee.
     const pubAny = {
       typeUrl: '/cosmos.crypto.secp256k1.PubKey',
@@ -80,8 +124,8 @@ export class QoreChainSigner {
     // 2. B0 = body without the PQC extension.
     const b0 = TxBody.encode(TxBody.fromPartial({ messages, memo, timeoutHeight })).finish();
 
-    // 3. ML-DSA-87 sign the framed (B0, authInfo).
-    const pqcSig = mldsa.sign(this.pqc.secretKey, frame(b0, authInfoBytes));
+    // 3. ML-DSA-87 sign the hybrid sign-bytes in the form this network verifies.
+    const pqcSig = mldsa.sign(this.pqc.secretKey, hybridSignBytes(version, this.chainId, b0, authInfoBytes));
 
     // 4. body WITH the PQC hybrid extension.
     const bodyWithExt = TxBody.encode(TxBody.fromPartial({
@@ -100,9 +144,11 @@ export class QoreChainSigner {
       ? Uint8Array.from(Buffer.from(signature.signature, 'base64')) : signature.signature;
 
     // 6. Assemble TxRaw.
-    return TxRaw.encode(TxRaw.fromPartial({
+    const txRaw = TxRaw.encode(TxRaw.fromPartial({
       bodyBytes: bodyWithExt, authInfoBytes, signatures: [classicalSig],
     })).finish();
+    txRaw.signBytesVersion = version;
+    return txRaw;
   }
 }
 

package/src/phantom.js

@@ -11,6 +11,10 @@
 // blockhash, so a signature cannot be replayed for a different action/account or
 // (via the blockhash window) indefinitely. This mirrors the on-chain
 // `resolveEnvelopeSigner` / `authSignBytes` in x/svm/rpc.
+//
+// NOTE: the SVM lane is currently closed on both mainnet and testnet (and the
+// authenticator module is disabled), so nothing signed here is accepted yet. When
+// the lane reopens it verifies only the v2 digest ("qorechain-svm-auth-v2") built below.
 
 const B58 = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
 const B58MAP = (() => { const m = {}; for (let i = 0; i < B58.length; i++) m[B58[i]] = i; return m; })();
@@ -64,23 +68,46 @@ export function systemTransferData(lamports) {
 
 /**
  * authSignBytes rebuilds, byte-for-byte, the digest the node signs-checks:
- *   sha256( "qorechain-svm-auth-v1" ‖ programId(32) ‖
- *           Σ[ addr(32) ‖ flags ]  ‖ data ‖ recentBlockhash(32) )
+ *   sha256( "qorechain-svm-auth-v2" ‖ programId(32) ‖
+ *           BE64(accounts.length) ‖ Σ[ addr(32) ‖ flags(1) ] ‖
+ *           BE64(data.length) ‖ data ‖
+ *           BE64(blockhash.length) ‖ blockhash )
  * where flags = (isSigner?1) | (isWritable?2). All addresses are decoded to
  * their raw 32 bytes; recentBlockhash is the getLatestBlockhash HEX string.
  * Returns a 32-byte Uint8Array (what the wallet actually signs).
+ *
+ * v1 had no count and no length framing, so the encoding was not injective: the
+ * boundary between the fixed-size account entries and `data` was ambiguous (N
+ * accounts plus D hashed the same as N-1 accounts plus addr‖flags‖D), and bytes
+ * could move between `data` and the blockhash. One approval therefore authorised
+ * more than one account set. The count and length prefixes make every field
+ * self-delimiting. The tag is bumped so a v1 client fails closed against a v2
+ * node rather than signing something ambiguous; keep this in lockstep with
+ * qorechain-core/x/svm/types/auth_sign.go.
  */
 export async function authSignBytes({ programId, accounts, data, recentBlockhashHex }) {
   const parts = [];
   const enc = new TextEncoder();
-  parts.push(enc.encode('qorechain-svm-auth-v1'));
+  // Big-endian uint64, matching the chain's other sign-bytes helpers.
+  const be64 = (n) => {
+    const b = new Uint8Array(8);
+    let v = BigInt(n);
+    for (let i = 7; i >= 0; i--) { b[i] = Number(v & 0xffn); v >>= 8n; }
+    return b;
+  };
+  parts.push(enc.encode('qorechain-svm-auth-v2'));
   parts.push(base58Decode(programId));
+  parts.push(be64(accounts.length));
   for (const a of accounts) {
     parts.push(base58Decode(a.pubkey));
     parts.push(new Uint8Array([(a.isSigner ? 1 : 0) | (a.isWritable ? 2 : 0)]));
   }
-  parts.push(data instanceof Uint8Array ? data : new Uint8Array(data));
-  parts.push(hexToBytes(recentBlockhashHex));
+  const dataBytes = data instanceof Uint8Array ? data : new Uint8Array(data);
+  parts.push(be64(dataBytes.length));
+  parts.push(dataBytes);
+  const bhBytes = hexToBytes(recentBlockhashHex);
+  parts.push(be64(bhBytes.length));
+  parts.push(bhBytes);
   let len = 0; for (const p of parts) len += p.length;
   const buf = new Uint8Array(len); let o = 0; for (const p of parts) { buf.set(p, o); o += p.length; }
   return sha256(buf);

package/src/sign-eth.js

@@ -16,7 +16,8 @@ import { TxBody, AuthInfo, TxRaw, SignerInfo, ModeInfo, Fee, SignDoc } from 'cos
 import { SignMode } from 'cosmjs-types/cosmos/tx/signing/v1beta1/signing.js';
 import { PubKey } from 'cosmjs-types/cosmos/crypto/secp256k1/keys.js';
 import { mldsa } from '@qorechain/pqc';
-import { frame, encodePqcHybridSignature, HYBRID_SIG_TYPE_URL, ALGORITHM_ML_DSA_87 } from './framing.js';
+import { encodePqcHybridSignature, HYBRID_SIG_TYPE_URL, ALGORITHM_ML_DSA_87 } from './framing.js';
+import { hybridSignBytes, resolveSignBytesVersion } from './signbytes.js';
 
 // cosmos/evm eth_secp256k1 pubkey type. Wire shape is identical to the cosmos
 // secp256k1 PubKey ({1: bytes key}), only the typeUrl differs.
@@ -72,13 +73,24 @@ export async function signClassicalEth({ key, chainId, accountNumber, messages,
 /**
  * Hybrid eth_secp256k1 + ML-DSA-87 Cosmos tx. `key` must include `pqc`
  * ({publicKey, secretKey}) as produced by generateQoreWallet/walletFromMnemonic.
+ *
+ * Sign-bytes form: `signBytesVersion` 'v1' | 'v2' is used as given; 'auto'
+ * (default) asks the network via `rest` (LCD URL). On qorechain-vladi /
+ * qorechain-diana with neither an explicit version nor `rest` this THROWS rather
+ * than guess. The returned Uint8Array carries `.signBytesVersion`.
  */
-export async function signHybridEth({ key, chainId, accountNumber, messages, fee, sequence, memo = '', timeoutHeight = 0n }) {
+export async function signHybridEth({
+  key, chainId, accountNumber, messages, fee, sequence, memo = '', timeoutHeight = 0n,
+  signBytesVersion = 'auto', rest, fetch,
+}) {
+  const version = await resolveSignBytesVersion({
+    chainId, rest, signBytesVersion, ...(fetch ? { fetch } : {}),
+  });
   const authInfoBytes = buildAuthInfo(key.pubkey, sequence, fee);
   // B0 = body without the PQC extension.
   const b0 = TxBody.encode(TxBody.fromPartial({ messages, memo, timeoutHeight })).finish();
-  // ML-DSA-87 over frame(B0, authInfo).
-  const pqcSig = mldsa.sign(key.pqc.secretKey, frame(b0, authInfoBytes));
+  // ML-DSA-87 over the hybrid sign-bytes in the form this network verifies.
+  const pqcSig = mldsa.sign(key.pqc.secretKey, hybridSignBytes(version, chainId, b0, authInfoBytes));
   const bodyWithExt = TxBody.encode(TxBody.fromPartial({
     messages, memo, timeoutHeight,
     extensionOptions: [{ typeUrl: HYBRID_SIG_TYPE_URL, value: encodePqcHybridSignature(ALGORITHM_ML_DSA_87, pqcSig) }],
@@ -87,5 +99,7 @@ export async function signHybridEth({ key, chainId, accountNumber, messages, fee
     bodyBytes: bodyWithExt, authInfoBytes, chainId, accountNumber: BigInt(accountNumber),
   })).finish();
   const classical = await ethSign(signBytes, key.privateKey);
-  return TxRaw.encode(TxRaw.fromPartial({ bodyBytes: bodyWithExt, authInfoBytes, signatures: [classical] })).finish();
+  const txRaw = TxRaw.encode(TxRaw.fromPartial({ bodyBytes: bodyWithExt, authInfoBytes, signatures: [classical] })).finish();
+  txRaw.signBytesVersion = version;
+  return txRaw;
 }

package/src/signbytes.js

@@ -0,0 +1,173 @@
+// @qorechain/wallet-adapter — per-network hybrid PQC sign-bytes (v1 / v2).
+//
+// The ML-DSA-87 key in a hybrid transaction signs one of two byte forms, and a
+// network accepts EXACTLY ONE of them at any height (no overlap, by design):
+//
+//   v1 (legacy):  BE32(len B0) ‖ B0 ‖ BE32(len A) ‖ A
+//   v2:           "qorechain-pqc-hybrid-v2" ‖ BE64(len chainId) ‖ chainId ‖
+//                   BE32(len B0) ‖ B0 ‖ BE32(len A) ‖ A
+//
+// B0 = TxBody WITHOUT the PQC extension option, A = AuthInfo bytes verbatim.
+// Byte-identical to the chain's x/pqc/types.HybridSignBytesLegacy / HybridSignBytes.
+//
+// Which form to sign: a network that existed before chain release v3.1.98
+// (qorechain-vladi mainnet, qorechain-diana testnet) verifies v1 until the
+// "v3.1.98" upgrade plan is applied on it, and v2 from then on. Any other chain
+// verifies v2 from its first block. The two networks upgrade at different
+// heights, so a client must ASK the target network (applied_plan) rather than
+// hardcode a form. That is what resolveSignBytesVersion does.
+
+export const HYBRID_SIGN_BYTES_V2_DOMAIN = 'qorechain-pqc-hybrid-v2';
+export const SIGN_BYTES_V2_UPGRADE = 'v3.1.98';
+export const LEGACY_SIGN_BYTES_CHAINS = Object.freeze(['qorechain-vladi', 'qorechain-diana']);
+
+const te = new TextEncoder();
+
+function assertBytes(name, v) {
+  if (!(v instanceof Uint8Array)) throw new TypeError(`${name} must be a Uint8Array`);
+}
+
+/** v1 (legacy) hybrid sign-bytes: BE32(len b0) ‖ b0 ‖ BE32(len authInfo) ‖ authInfo. */
+export function hybridSignBytesV1(b0, authInfo) {
+  assertBytes('b0', b0);
+  assertBytes('authInfo', authInfo);
+  const out = new Uint8Array(4 + b0.length + 4 + authInfo.length);
+  const dv = new DataView(out.buffer);
+  let o = 0;
+  dv.setUint32(o, b0.length, false); o += 4;
+  out.set(b0, o); o += b0.length;
+  dv.setUint32(o, authInfo.length, false); o += 4;
+  out.set(authInfo, o);
+  return out;
+}
+
+/** v2 hybrid sign-bytes: domain ‖ BE64(len chainId) ‖ chainId ‖ BE32(len b0) ‖ b0 ‖ BE32(len authInfo) ‖ authInfo. */
+export function hybridSignBytesV2(chainId, b0, authInfo) {
+  if (typeof chainId !== 'string' || chainId.length === 0) {
+    throw new Error('hybridSignBytesV2: chainId is required (v2 sign-bytes bind the chain-id)');
+  }
+  assertBytes('b0', b0);
+  assertBytes('authInfo', authInfo);
+  const domain = te.encode(HYBRID_SIGN_BYTES_V2_DOMAIN);
+  const cid = te.encode(chainId);
+  const out = new Uint8Array(domain.length + 8 + cid.length + 4 + b0.length + 4 + authInfo.length);
+  const dv = new DataView(out.buffer);
+  let o = 0;
+  out.set(domain, o); o += domain.length;
+  dv.setBigUint64(o, BigInt(cid.length), false); o += 8;
+  out.set(cid, o); o += cid.length;
+  dv.setUint32(o, b0.length, false); o += 4;
+  out.set(b0, o); o += b0.length;
+  dv.setUint32(o, authInfo.length, false); o += 4;
+  out.set(authInfo, o);
+  return out;
+}
+
+function assertVersion(version, fn) {
+  if (version !== 'v1' && version !== 'v2') {
+    throw new Error(`${fn}: version must be 'v1' or 'v2', got ${JSON.stringify(version)} (resolve it with resolveSignBytesVersion first)`);
+  }
+}
+
+/** Version-dispatching hybrid sign-bytes. `version` is REQUIRED ('v1' | 'v2'); there is no implicit form. */
+export function hybridSignBytes(version, chainId, b0, authInfo) {
+  assertVersion(version, 'hybridSignBytes');
+  return version === 'v2' ? hybridSignBytesV2(chainId, b0, authInfo) : hybridSignBytesV1(b0, authInfo);
+}
+
+function toHeight(h) {
+  if (h === undefined || h === null || h === '') return 0n;
+  if (typeof h === 'bigint') return h;
+  if (typeof h === 'number') {
+    if (!Number.isFinite(h)) throw new Error(`invalid applied height ${h}`);
+    return BigInt(Math.trunc(h));
+  }
+  return BigInt(String(h)); // throws on garbage, never guesses
+}
+
+/**
+ * The form a client must sign for `chainId`, given the height at which the
+ * v3.1.98 plan was applied on it (0 / "0" / missing = not applied). Mirrors the
+ * chain's SignBytesVersionFor. Heights are compared NUMERICALLY: the node returns
+ * the height as a string, and "0" is truthy.
+ */
+export function signBytesVersionFor(chainId, v2AppliedHeight) {
+  if (toHeight(v2AppliedHeight) > 0n) return 'v2';
+  return LEGACY_SIGN_BYTES_CHAINS.includes(chainId) ? 'v1' : 'v2';
+}
+
+const cache = new Map(); // `${rest}|${chainId}` -> { version, at }
+
+/** Drop every cached resolver answer. */
+export function clearSignBytesCache() { cache.clear(); }
+
+function normRest(rest) { return String(rest).replace(/\/+$/, ''); }
+
+/**
+ * Resolve the hybrid sign-bytes form for a network.
+ *   - 'v1' | 'v2' are returned as-is (no network).
+ *   - 'auto' (default): a chain that is not a legacy network gets 'v2' with no
+ *     HTTP; a legacy network is asked `GET {rest}/cosmos/upgrade/v1beta1/applied_plan/v3.1.98`
+ *     and signs v2 iff the returned height > 0. Answers are cached per
+ *     (rest, chainId) for `ttlMs`; `forceRefresh` bypasses the cache.
+ * Throws (never guesses) when a legacy network has no `rest` or the query fails.
+ */
+export async function resolveSignBytesVersion({
+  chainId, rest, signBytesVersion = 'auto', fetch = globalThis.fetch, ttlMs = 60_000, forceRefresh = false,
+} = {}) {
+  const mode = signBytesVersion ?? 'auto';
+  if (mode === 'v1' || mode === 'v2') return mode;
+  if (mode !== 'auto') {
+    throw new Error(`signBytesVersion must be 'auto', 'v1' or 'v2', got ${JSON.stringify(signBytesVersion)}`);
+  }
+  if (typeof chainId !== 'string' || chainId.length === 0) {
+    throw new Error('resolveSignBytesVersion: chainId is required');
+  }
+  if (!LEGACY_SIGN_BYTES_CHAINS.includes(chainId)) return 'v2';
+
+  const hint = `pass \`rest\` (the network's LCD URL) or an explicit signBytesVersion 'v1' | 'v2'`;
+  if (!rest) {
+    throw new Error(`Cannot choose the hybrid sign-bytes form for ${chainId} without asking the network: ${hint}.`);
+  }
+  const base = normRest(rest);
+  const key = `${base}|${chainId}`;
+  if (!forceRefresh) {
+    const hit = cache.get(key);
+    if (hit && Date.now() - hit.at < ttlMs) return hit.version;
+  }
+  if (typeof fetch !== 'function') {
+    throw new Error(`Cannot query ${base}: no fetch implementation available; ${hint}.`);
+  }
+  const url = `${base}/cosmos/upgrade/v1beta1/applied_plan/${SIGN_BYTES_V2_UPGRADE}`;
+  let version;
+  try {
+    const res = await fetch(url, { headers: { accept: 'application/json' } });
+    if (!res || !res.ok) throw new Error(`HTTP ${res ? res.status : 'no response'}`);
+    const body = await res.json();
+    version = signBytesVersionFor(chainId, body?.height ?? '0');
+  } catch (e) {
+    throw new Error(`Cannot determine the hybrid sign-bytes form for ${chainId} from ${url} (${e && e.message ? e.message : e}); ${hint}.`);
+  }
+  cache.set(key, { version, at: Date.now() });
+  return version;
+}
+
+const REJECTION_TEXT = 'hybrid PQC signature verification failed';
+
+/**
+ * True iff a broadcast failure is the chain refusing the hybrid PQC signature
+ * (x/pqc ErrHybridSigInvalid: codespace "pqc", code 21) — the signal that the
+ * wrong sign-bytes form was used. Accepts a cosmjs BroadcastTxError
+ * ({ code, codespace, log }), a DeliverTxResponse-like ({ code, rawLog }), a
+ * plain Error, or a string. Code 21 from another codespace does NOT match.
+ */
+export function isHybridSignBytesRejection(errOrResult) {
+  if (!errOrResult) return false;
+  if (typeof errOrResult === 'string') return errOrResult.includes(REJECTION_TEXT);
+  const x = errOrResult;
+  if (x.codespace === 'pqc' && Number(x.code) === 21) return true;
+  for (const f of [x.log, x.rawLog, x.raw_log, x.message]) {
+    if (typeof f === 'string' && f.includes(REJECTION_TEXT)) return true;
+  }
+  return false;
+}

package/src/wallet.js

@@ -89,10 +89,25 @@ export async function walletFromMnemonic(mnemonic) {
 /**
  * Derive a unified QoreChain wallet directly from a 32-byte seed (no mnemonic).
  *
- * The seed is used as the secp256k1 private key, so a caller can derive one
- * canonical eth-native account deterministically from any 32 bytes — e.g.
- * `shake256(phantomSignature)` for the Phantom "connect → 3 addresses" flow, or
- * an HKDF/KDF output from another wallet. Same 20-byte identity model as
+ * The seed IS the secp256k1 private key. It must therefore come from something
+ * that is secret and stays secret — a CSPRNG, or a KDF over material only the
+ * user holds.
+ *
+ * DO NOT derive it from a wallet signature. Earlier versions of this comment
+ * recommended `shake256(phantomSignature)` for a "connect → 3 addresses" flow.
+ * That is unsound: signature schemes like ed25519 are deterministic (RFC 8032),
+ * and the message such flows sign is fixed and public, so the signature is a
+ * constant that any site can ask the same wallet to reproduce. Whoever obtains
+ * it reconstructs this account's entire key material, classical and ML-DSA-87.
+ * Changing the message does not help — any message an attacker can also request
+ * yields the same key.
+ *
+ * To let an external wallet authorise spending, register its key as an
+ * AUTHENTICATOR on a QoreChain account (MsgRegisterAuthenticator, with a
+ * permission set and a SpendingRule) instead of pretending a signature is a
+ * seed. Reported as QSR-2026-0049 and QSR-2026-0176.
+ *
+ * Same 20-byte identity model as
  * `walletFromMnemonic`: qor1 / 0x / svm all resolve to the same account and the
  * same balance, and the key signs on every interface (incl. hybrid PQC).
  *