@qorechain/wallet-adapter 0.1.0

package/README.md

@@ -0,0 +1,87 @@
+# @qorechain/wallet-adapter
+
+Add **QoreChain** to any Cosmos wallet — Keplr, Leap, Cosmostation — and send its
+**PQC-required** transactions, with **no wallet-side changes**.
+
+QoreChain's ante chain rejects any Cosmos tx that lacks a FIPS-204 **ML-DSA-87**
+hybrid signature (in a tx-body extension option) alongside the account's classical
+secp256k1 signature. Stock wallets can't produce ML-DSA signatures — so this
+adapter does. The design is what makes it drop-in:
+
+> The wallet only ever produces a **standard `SIGN_MODE_DIRECT` signature** over
+> the final transaction body. The adapter bakes the ML-DSA-87 extension **into
+> that body before the wallet signs it**. So `wallet.signDirect(...)` works
+> exactly as it does for any Cosmos chain — it has no idea PQC is involved.
+
+The ML-DSA part uses [`@qorechain/pqc`](../qorechain-pqc) — the same FIPS-204
+implementation the chain itself was migrated to, so the signatures are
+byte-compatible and verify in the chain's ante. (Before that migration this was
+impossible: the chain ran a non-standard Dilithium variant no JS lib could match.)
+
+## Why it works — the protocol
+
+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
+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.
+
+**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**
+against a live 7-validator QoreChain — the PQC ante accepted it.
+
+## Usage (Keplr)
+
+```js
+import {
+  QoreChainSigner, qoreChainInfo, derivePqcKeyFromWallet,
+} from '@qorechain/wallet-adapter';
+
+// 1. Register the chain with the wallet (one click for the user).
+await window.keplr.experimentalSuggestChain(qoreChainInfo({ rpc, rest }));
+await window.keplr.enable('qorechain-diana');
+const signer = window.keplr.getOfflineSigner('qorechain-diana');
+const [account] = await signer.getAccounts();
+
+// 2. Derive the user's ML-DSA-87 key, bound to their wallet (no mnemonic export).
+const pqc = await derivePqcKeyFromWallet(window.keplr, 'qorechain-diana', account.address);
+// (first time only) register the PQC public key on-chain via MsgRegisterPQCKey —
+// that message is classical-exempt, so the wallet can sign it normally.
+
+// 3. Sign + broadcast a PQC-required tx. The wallet signs an ordinary SignDoc.
+const adapter = new QoreChainSigner({
+  wallet: window.keplr, chainId: 'qorechain-diana', address: account.address,
+  pubkeySecp256k1: account.pubkey, accountNumber, pqc,
+});
+const txBytes = await adapter.signHybrid({ messages, fee, sequence });
+await fetch(`${rpc}`, { method:'POST', body: JSON.stringify({
+  jsonrpc:'2.0', id:1, method:'broadcast_tx_sync', params:{ tx: toBase64(txBytes) } }) });
+```
+
+## Wallet support
+
+| Wallet | How | Status |
+|---|---|---|
+| **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 |
+
+## 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.
+- `QoreChainSigner#signHybrid({ messages, fee, sequence, memo?, timeoutHeight? })` → `TxRaw` bytes.
+- `qoreChainInfo({ chainId?, rpc, rest })` — Keplr chain descriptor.
+
+## License
+
+Apache-2.0

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@qorechain/wallet-adapter",
+  "version": "0.1.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",
+  "types": "src/index.d.ts",
+  "exports": { ".": "./src/index.js" },
+  "files": ["src", "README.md"],
+  "scripts": { "test": "node --test" },
+  "keywords": ["qorechain", "keplr", "cosmos", "wallet", "post-quantum", "ml-dsa", "pqc", "dilithium"],
+  "license": "Apache-2.0",
+  "publishConfig": { "access": "public" },
+  "dependencies": {
+    "@qorechain/pqc": "^0.1.0",
+    "cosmjs-types": "^0.9.0"
+  },
+  "peerDependencies": {
+    "@cosmjs/proto-signing": "^0.32.0",
+    "@cosmjs/stargate": "^0.32.0"
+  }
+}

package/src/framing.js

@@ -0,0 +1,18 @@
+// Pure, dependency-free QoreChain PQC tx-extension framing (the chain-matching bits).
+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

@@ -0,0 +1,10 @@
+export const HYBRID_SIG_TYPE_URL: string;
+export const ALGORITHM_ML_DSA_87: number;
+export function frame(b0: Uint8Array, auth: Uint8Array): Uint8Array;
+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>;
+}

package/src/index.js

@@ -0,0 +1,136 @@
+// @qorechain/wallet-adapter
+//
+// Add QoreChain to any Cosmos wallet (Keplr, Leap, Cosmostation, …) and sign its
+// PQC-required transactions WITHOUT any wallet-side changes.
+//
+// QoreChain's ante chain requires every Cosmos tx to carry a FIPS-204 ML-DSA-87
+// hybrid signature in a tx-body extension option, in addition to the account's
+// classical secp256k1 signature. The trick that makes this wallet-compatible:
+// the wallet only ever produces a *standard SIGN_MODE_DIRECT* signature over the
+// final body — and the PQC extension is baked into that body BEFORE the wallet
+// signs it. So `wallet.signDirect(...)` works unmodified; the adapter does the
+// ML-DSA part with @qorechain/pqc (standard, interoperable since the chain was
+// migrated to the FIPS standards).
+//
+// 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
+//   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.
+
+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 { 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';
+import { PubKey } from 'cosmjs-types/cosmos/crypto/secp256k1/keys.js';
+
+
+// Deterministically derive an ML-DSA-87 keypair bound to the wallet, without ever
+// touching the mnemonic: the wallet ADR-36-signs a fixed message, and SHAKE-256 of
+// that signature seeds the keygen. The same wallet always yields the same PQC key.
+export async function derivePqcKeyFromWallet(wallet, chainId, address, domain = 'qorechain:pqc:v1') {
+  const { signature } = await wallet.signArbitrary(chainId, address, domain);
+  const sigBytes = typeof signature === 'string' ? Uint8Array.from(Buffer.from(signature, 'base64')) : signature;
+  const seed = shake256(sigBytes, 32);
+  return mldsa.keygen(seed); // { publicKey, secretKey } — deterministic from seed
+}
+
+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 });
+  }
+
+  // Build + hybrid-sign + return TxRaw bytes ready to broadcast.
+  async signHybrid({ messages, fee, memo = '', sequence, timeoutHeight = 0n }) {
+    // 1. AuthInfo: single DIRECT signer (secp256k1) + fee.
+    const pubAny = {
+      typeUrl: '/cosmos.crypto.secp256k1.PubKey',
+      value: PubKey.encode(PubKey.fromPartial({ key: this.pubkeySecp256k1 })).finish(),
+    };
+    const authInfo = AuthInfo.fromPartial({
+      signerInfos: [SignerInfo.fromPartial({
+        publicKey: pubAny,
+        modeInfo: ModeInfo.fromPartial({ single: { mode: SignMode.SIGN_MODE_DIRECT } }),
+        sequence: BigInt(sequence),
+      })],
+      fee: Fee.fromPartial(fee),
+    });
+    const authInfoBytes = AuthInfo.encode(authInfo).finish();
+
+    // 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));
+
+    // 4. body WITH the PQC hybrid extension.
+    const bodyWithExt = TxBody.encode(TxBody.fromPartial({
+      messages, memo, timeoutHeight,
+      extensionOptions: [{ typeUrl: HYBRID_SIG_TYPE_URL, value: encodePqcHybridSignature(ALGORITHM_ML_DSA_87, pqcSig) }],
+    })).finish();
+
+    // 5. Classical secp256k1 signature from the wallet over the final SignDoc.
+    const signDoc = SignDoc.fromPartial({
+      bodyBytes: bodyWithExt, authInfoBytes, chainId: this.chainId, accountNumber: BigInt(this.accountNumber),
+    });
+    const { signature } = await this.wallet.signDirect(this.chainId, this.address, {
+      bodyBytes: bodyWithExt, authInfoBytes, chainId: this.chainId, accountNumber: BigInt(this.accountNumber),
+    });
+    const classicalSig = typeof signature.signature === 'string'
+      ? Uint8Array.from(Buffer.from(signature.signature, 'base64')) : signature.signature;
+
+    // 6. Assemble TxRaw.
+    return TxRaw.encode(TxRaw.fromPartial({
+      bodyBytes: bodyWithExt, authInfoBytes, signatures: [classicalSig],
+    })).finish();
+  }
+}
+
+// Keplr chain-registration descriptor for QoreChain (pass to keplr.experimentalSuggestChain).
+export function qoreChainInfo({ chainId = 'qorechain-diana', rpc, rest } = {}) {
+  return {
+    chainId, chainName: 'QoreChain', rpc, rest,
+    bip44: { coinType: 118 },
+    bech32Config: {
+      bech32PrefixAccAddr: 'qor', bech32PrefixAccPub: 'qorpub',
+      bech32PrefixValAddr: 'qorvaloper', bech32PrefixValPub: 'qorvaloperpub',
+      bech32PrefixConsAddr: 'qorvalcons', bech32PrefixConsPub: 'qorvalconspub',
+    },
+    currencies: [{ coinDenom: 'QOR', coinMinimalDenom: 'uqor', coinDecimals: 6 }],
+    feeCurrencies: [{
+      coinDenom: 'QOR', coinMinimalDenom: 'uqor', coinDecimals: 6,
+      // matches the chain's minimum-gas-prices (0.001uqor); avg/high give headroom
+      gasPriceStep: { low: 0.001, average: 0.0025, high: 0.004 },
+    }],
+    stakeCurrency: { coinDenom: 'QOR', coinMinimalDenom: 'uqor', coinDecimals: 6 },
+    features: ['cosmwasm'],
+  };
+}
+
+// EIP-3085 `wallet_addEthereumChain` params for QoreChain's EVM, for MetaMask &
+// any EIP-1193 wallet. IMPORTANT: the EVM native currency is the 18-decimal
+// `aqor` view of QOR (1 QOR = 1e18 aqor = 1e6 uqor; the EVM lane scales the
+// 6-decimal bank denom by 1e12). nativeCurrency.decimals MUST be 18 here — do
+// NOT copy the 6 from the Cosmos `uqor` currency, or balances render 1e12x off.
+export function qoreEvmChainParams({ evmChainId = 9800, rpcUrl, wsUrl, explorerUrl, testnet = true } = {}) {
+  if (!rpcUrl) throw new Error('qoreEvmChainParams: rpcUrl is required');
+  return {
+    chainId: '0x' + Number(evmChainId).toString(16), // 9800 -> 0x2648, 9801 -> 0x2649
+    chainName: testnet ? 'QoreChain Testnet' : 'QoreChain',
+    nativeCurrency: { name: 'QORE', symbol: 'QOR', decimals: 18 },
+    rpcUrls: wsUrl ? [rpcUrl, wsUrl] : [rpcUrl],
+    blockExplorerUrls: explorerUrl ? [explorerUrl] : [],
+  };
+}
+
+// One-call helper: prompt an EIP-1193 wallet (MetaMask) to add QoreChain's EVM.
+export async function addQoreEvmToWallet(provider, opts) {
+  return provider.request({ method: 'wallet_addEthereumChain', params: [qoreEvmChainParams(opts)] });
+}