@qorechain/wallet-adapter 0.1.4 → 0.1.7

package/README.md

@@ -72,15 +72,24 @@ 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** | QoreChain's Solana-compatible RPC (`:8899`) | ⚠️ read/native-send; PQC SVM execute needs the same hybrid pattern |
+| **Phantom** | derive a unified account from a Phantom signature (`walletFromSeed`) | ✅ connect → qor1/0x/svm, receive on any, spend on any (incl. hybrid PQC) |
 
 ## API
 
-- `frame(b0, auth)` — QoreChain hybrid sign-bytes framing.
-- `encodePqcHybridSignature(algId, sig)` — proto encoder for the extension.
-- `derivePqcKeyFromWallet(wallet, chainId, address)` — deterministic ML-DSA-87 key from a wallet signature.
+Wallet generation & unified addresses:
+- `generateQoreWallet(strength?)` / `walletFromMnemonic(mnemonic)` / `walletFromSeed(seed32)` — a unified wallet `{ mnemonic, privateKey, pubkey, cosmos, evm, svm, pqc }`.
+- `addressesFrom20(bytes20)` / `qoreAddresses({cosmos|evm|hex})` — the three encodings of a known account.
+
+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).
+- `ETHSECP256K1_PUBKEY_TYPE` — the eth pubkey type URL.
+
+Keplr / any-signDirect adapter + PQC framing:
 - `QoreChainSigner#signHybrid({ messages, fee, sequence, memo?, timeoutHeight? })` → `TxRaw` bytes.
-- `qoreChainInfo({ chainId?, rpc, rest })` — Keplr chain descriptor.
+- `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.
+- `qoreChainInfo({ chainId?, rpc, rest })` — Keplr chain descriptor; `qoreEvmChainParams(...)` / `addQoreEvmToWallet(provider, opts)` — MetaMask (EIP-3085) EVM descriptor.
 
 ## License
 
@@ -112,3 +121,101 @@ 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
+```
+
+## eth-native Cosmos signing (requires chain ≥ v3.1.83)
+
+The unified account **signs on the Cosmos lane too**, with the `eth_secp256k1`
+scheme (secp256k1 over `keccak256(signBytes)`, pubkey
+`/cosmos.evm.crypto.v1.ethsecp256k1.PubKey`). `signClassicalEth` builds a
+classical-only tx (for the one-time, bootstrap-exempt PQC key registration);
+`signHybridEth` adds the ML-DSA-87 hybrid signature the ante requires for
+everything else. Both return broadcast-ready `TxRaw` bytes.
+
+```js
+import { walletFromMnemonic, signClassicalEth, signHybridEth } from "@qorechain/wallet-adapter";
+
+const key = await walletFromMnemonic(mnemonic); // has { privateKey, pubkey, pqc }
+const fee = { amount: [{ denom: "uqor", amount: "30000" }], gasLimit: 300000n };
+
+// 1) one-time: register the account's ML-DSA-87 key (classical, PQC-exempt)
+const regTx = await signClassicalEth({ key, chainId, accountNumber, sequence,
+  messages: [{ typeUrl: "/qorechain.pqc.v1.MsgRegisterPQCKeyV2", value: registerMsgBytes }],
+  fee: { amount: [{ denom: "uqor", amount: "600000" }], gasLimit: 6000000n } });
+
+// 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 });
+```
+
+> **Requires QoreChain ≥ v3.1.83** — that release registers the `eth_secp256k1`
+> pubkey on the node's interface registry so eth-native Cosmos txs decode. Both
+> `qorechain-diana` (testnet) and `qorechain-vladi` (mainnet) run it.
+> `@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.4",
+  "version": "0.1.7",
   "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/index.d.ts

@@ -1,6 +1,48 @@
 export const HYBRID_SIG_TYPE_URL: string;
 export const ALGORITHM_ML_DSA_87: number;
 
+// --- Unified wallet generation (one eth-native key → qor1 / 0x / svm) ---
+export interface PqcKeypair { publicKey: Uint8Array; secretKey: Uint8Array; }
+export interface QoreAddresses {
+  addressBytes: Uint8Array;
+  cosmos: string; // qor1… (bech32)
+  evm: string;    // 0x… (EIP-55)
+  svm: string;    // base58
+}
+export interface QoreWallet extends QoreAddresses {
+  mnemonic: string | null;
+  privateKey: string; // 0x-hex, 32 bytes
+  pubkey: string;     // 0x-hex, 33-byte compressed secp256k1
+  pqc: PqcKeypair;    // ML-DSA-87 (Dilithium-5)
+}
+export function generateQoreWallet(strength?: number): Promise<QoreWallet>;
+export function walletFromMnemonic(mnemonic: string): Promise<QoreWallet>;
+export function walletFromSeed(seed: Uint8Array | string): Promise<QoreWallet>;
+export function addressesFrom20(addr20: Uint8Array): QoreAddresses;
+export function qoreAddresses(opts: { cosmos?: string; evm?: string; hex?: string }): QoreAddresses;
+
+// --- eth-native (eth_secp256k1) Cosmos signing (requires chain >= v3.1.83) ---
+export const ETHSECP256K1_PUBKEY_TYPE: string;
+export interface EthSignKey { privateKey: Uint8Array | string; pubkey: Uint8Array | string; pqc?: PqcKeypair; }
+export interface EthSignArgs {
+  key: EthSignKey;
+  chainId: string;
+  accountNumber: number | bigint;
+  messages: Array<{ typeUrl: string; value: Uint8Array }>;
+  fee: any;
+  sequence: number | bigint;
+  memo?: string;
+  timeoutHeight?: bigint;
+}
+/** 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>;
+
+// --- EVM network descriptors (EIP-3085 / MetaMask) ---
+export function qoreEvmChainParams(opts?: { evmChainId?: number; rpcUrl?: string; wsUrl?: string; explorerUrl?: string; testnet?: boolean }): any;
+export function addQoreEvmToWallet(provider: any, opts?: any): Promise<any>;
+
 // --- Phantom / any-ed25519-wallet support ---
 export const SYSTEM_PROGRAM_ID: string;
 export function base58Encode(bytes: Uint8Array): string;
@@ -19,3 +61,34 @@ 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>;
 }
+
+// --- 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

@@ -31,12 +31,20 @@ export {
 } from './phantom.js';
 // Unified wallet generation: one eth-native key → cosmos/evm/svm addresses + PQC key.
 export {
-  generateQoreWallet, walletFromMnemonic, addressesFrom20, qoreAddresses,
+  generateQoreWallet, walletFromMnemonic, walletFromSeed, addressesFrom20, qoreAddresses,
 } from './wallet.js';
 // eth-native (eth_secp256k1) Cosmos signing — classical (register) + hybrid (PQC).
 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';

package/src/wallet.js

@@ -86,6 +86,40 @@ export async function walletFromMnemonic(mnemonic) {
   return fromMnemonicObj(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
+ * `walletFromMnemonic`: qor1 / 0x / svm all resolve to the same account and the
+ * same balance, and the key signs on every interface (incl. hybrid PQC).
+ *
+ * The ML-DSA-87 key is bound to `qorechain:pqc:v1|<qor1>|seed:<hex>` so it is
+ * recoverable from the same seed and never collides with a mnemonic wallet.
+ * `seed` accepts a 32-byte Uint8Array or a (0x-)hex string.
+ */
+export async function walletFromSeed(seed) {
+  const privkey = typeof seed === 'string' ? fromHex(seed.replace(/^0x/, '')) : seed;
+  if (!(privkey instanceof Uint8Array) || privkey.length !== 32) {
+    throw new Error('seed must be 32 bytes (Uint8Array or hex)');
+  }
+  const kp = await Secp256k1.makeKeypair(privkey); // validates the scalar is in [1, n-1]
+  const uncompressed = kp.pubkey;
+  const compressed = Secp256k1.compressPubkey(uncompressed);
+  const addr20 = new Keccak256(uncompressed.slice(1)).digest().slice(12);
+  const enc = addressesFrom20(addr20);
+  const pqcSeed = shake256(new TextEncoder().encode(`qorechain:pqc:v1|${enc.cosmos}|seed:${toHex(privkey)}`), 32);
+  return {
+    mnemonic: null,
+    privateKey: '0x' + toHex(privkey),
+    pubkey: '0x' + toHex(compressed),
+    ...enc,
+    pqc: mldsa.keygen(pqcSeed),
+  };
+}
+
 /** Convenience: the three address encodings of an existing account. */
 export function qoreAddresses({ cosmos, evm, hex }) {
   let addr20;