@qorechain/chain-bridge 0.1.1

package/README.md

@@ -0,0 +1,115 @@
+# @qorechain/chain-bridge
+
+Server-side, autonomous bridge between a Web2 backend (dashboard, exchange,
+payment worker) and QoreChain's on-chain modules. It turns an off-chain event —
+"USDT payment confirmed", "user requested a contract" — into a **real on-chain
+effect**, with no CLI and no human in the loop.
+
+It handles the two things a plain backend can't: the FIPS-204 **ML-DSA-87 hybrid
+signature** the chain's PQC ante chain requires on every Cosmos tx, and the
+exact wire encoding of QoreChain's custom module messages.
+
+```
+USDT paid ──► backend verifies ──► chain-bridge.grantLicenseSet() ──► x/license MsgGrantLicense (PQC-signed)
+                                                                       └─► license is REAL on-chain
+```
+
+## Install
+
+```bash
+npm install @qorechain/chain-bridge
+```
+
+Peer stack (installed automatically): `@cosmjs/proto-signing`,
+`@cosmjs/stargate`, `cosmjs-types`, `ethers`, and the published
+`@qorechain/wallet-adapter` + `@qorechain/pqc`. Pure JS — runs in an AWS Lambda
+(no native addons).
+
+## Quick start
+
+```js
+import { ChainBridge } from '@qorechain/chain-bridge';
+
+const bridge = new ChainBridge({
+  cosmosRpc: process.env.QORE_RPC,          // http://node:26657
+  chainId:   process.env.QORE_CHAIN_ID,     // qorechain-diana
+  evmRpc:    process.env.QORE_EVM_RPC,      // http://node:8545
+  evmChainId: 9800,
+  authorityMnemonic: process.env.LICENSE_AUTHORITY_MNEMONIC, // genesis license.authority
+  signerMnemonic:    process.env.DEPLOYER_MNEMONIC,          // funded operator key
+});
+
+// After a USDT payment is verified, grant the license on-chain to the user's
+// REAL qor1 address (NOT a custodial pseudo-address):
+const { grants, dropped } = await bridge.grantLicenseSet({
+  grantee: 'qor1user…',
+  type: 'validator',
+  chains: ['Solana', 'Ethereum'],   // → validator_operator, validator_solana, validator_ethereum
+  metadata: 'licenseId:abc123',
+});
+// grants = [{ featureId, txHash }, …]
+```
+
+## API
+
+| Method | Module / path | Signer | PQC |
+|---|---|---|---|
+| `grantLicenseSet({grantee,type,chains})` | x/license `MsgGrantLicense` ×N | authority | hybrid |
+| `grantLicense / revokeLicense / suspendLicense / resumeLicense` | x/license | authority | hybrid |
+| `registerLightNode({operatorMnemonic,…})` | x/lightnode `MsgRegisterLightNode` | operator | hybrid |
+| `deployEvm({bytecode,abi?,args?})` | EVM `eth_sendRawTransaction` | deployer | none (EVM lane) |
+| `deploySvm({bytecode})` | x/svm `MsgDeployProgram` | signer | hybrid |
+| `sendTokens({to,amountUqor})` | bank `MsgSend` | signer | hybrid |
+| `registerPqc({mnemonic})` | x/pqc `MsgRegisterPQCKeyV2` | self | classical (exempt) |
+
+`featureIdsFor({type, chains})` maps a dashboard license to on-chain feature IDs
+(`validator_*`, `bridge_*`, `qcb_bridge`, `lightnode_operator`); unknown chains
+are **dropped**, never minted into an invalid ID.
+
+## Keys & PQC bootstrap
+
+License/lifecycle messages must be signed by the chain's configured
+`license.authority` (genesis `app_state.license.authority`). Pass that key's
+24-word mnemonic as `authorityMnemonic` — keep it in a secrets manager
+(SSM / Secrets Manager), never on disk.
+
+Every hybrid signer needs its ML-DSA-87 public key registered on-chain once.
+`chain-bridge` derives that key deterministically and **auto-registers it on
+first use** if the chain reports it missing (the registration tx is PQC-exempt,
+so it goes through classically). You can also pre-register at deploy time:
+
+```bash
+qorechaind tx pqc register-key <ml-dsa-pubkey-hex> hybrid --from authority
+```
+
+### Canonical PQC derivation (v0.1.1+)
+
+The **ecosystem-standard** ML-DSA-87 seed is address-bound and identical across
+`@qorechain/wallet-adapter`, the SDK, and both signer paths here:
+
+```
+seed = SHAKE-256( "qorechain:pqc:v1|" + <account-bech32-address> + "|" + <mnemonic> )
+key  = ML-DSA-87.keygen(seed)      # deterministic (FIPS-204)
+```
+
+So the same mnemonic yields the **same** PQC key in every tool — recover it with
+`qorechaind tx pqc recover-key <name> <address> --derivation adapter`.
+
+> **Legacy note.** Before v0.1.1 the coin-118 path derived `SHAKE-256(mnemonic)`
+> (no address binding). The chain cannot rotate a key within one algorithm, so
+> accounts registered that way keep the legacy key; `chain-bridge` derives it too
+> and falls back to it automatically when a canonical signature is rejected.
+> Recover a legacy key with `recover-key … --derivation bridge`.
+
+## Decimals
+
+- Cosmos lane (`uqor`): 6 decimals. `sendTokens` amounts are in `uqor`.
+- EVM lane (`aqor`): 18 decimals. `deployEvm` `value` is in wei (aqor).
+
+## Tests
+
+```bash
+npm test   # wire-encoder + feature-map tests (offline, no chain needed)
+```
+
+Author: Liviu Epure · License: Apache-2.0

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@qorechain/chain-bridge",
+  "version": "0.1.1",
+  "description": "Server-side, autonomous bridge between Web2 backends (dashboards, exchanges) and the QoreChain on-chain modules. Grants licenses on-chain (PQC-signed), deploys contracts on the 3 VMs, registers light nodes, and moves QOR — all from a backend, no CLI.",
+  "type": "module",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "exports": {
+    ".": "./src/index.js",
+    "./proto": "./src/proto.js",
+    "./features": "./src/features.js"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@cosmjs/proto-signing": "^0.32.0",
+    "@cosmjs/stargate": "^0.32.0",
+    "@qorechain/pqc": "^0.1.1",
+    "@qorechain/wallet-adapter": "^0.1.4",
+    "cosmjs-types": "^0.9.0",
+    "ethers": "^6.13.0"
+  },
+  "keywords": [
+    "qorechain",
+    "cosmos",
+    "pqc",
+    "ml-dsa",
+    "license",
+    "bridge",
+    "evm",
+    "svm"
+  ],
+  "author": "Liviu Epure",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/cosmos.js

@@ -0,0 +1,212 @@
+// @qorechain/chain-bridge — cosmos tx signing + broadcast.
+//
+// Two broadcast paths:
+//   submitHybrid()    — the normal path. Layers the FIPS-204 ML-DSA-87 hybrid
+//                       signature the chain's PQC ante chain requires (via
+//                       @qorechain/wallet-adapter's QoreChainSigner), then the
+//                       classical secp256k1 signature. Used for MsgGrantLicense,
+//                       MsgRegisterLightNode, MsgDeployProgram, MsgSend, …
+//   submitClassical() — secp256k1-only, for the PQC-exempt registration msgs
+//                       (MsgRegisterPQCKeyV2 et al.) used to bootstrap a key.
+//
+// Both derive the secp256k1 wallet from a mnemonic and the ML-DSA-87 keypair
+// deterministically as SHAKE-256(mnemonic) — identical to the chain's
+// examples/server-signer, so a key registered there works here and vice versa.
+
+import { DirectSecp256k1HdWallet } from '@cosmjs/proto-signing';
+import { StargateClient, accountFromAny } from '@cosmjs/stargate';
+import { BaseAccount } from 'cosmjs-types/cosmos/auth/v1beta1/auth.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 { PubKey } from 'cosmjs-types/cosmos/crypto/secp256k1/keys.js';
+import {
+  frame, encodePqcHybridSignature, HYBRID_SIG_TYPE_URL, ALGORITHM_ML_DSA_87,
+  walletFromMnemonic, signClassicalEth, signHybridEth,
+} from '@qorechain/wallet-adapter';
+import { mldsa, shake256 } from '@qorechain/pqc';
+
+// Build the full signer context from a mnemonic.
+//
+// keyType:
+//   'secp256k1'      (default) — coinType-118 cosmos-native account
+//                    (address = ripemd160(sha256(pubkey))). Signs Cosmos txs
+//                    with sha256-secp256k1. PQC seed = SHAKE-256(mnemonic).
+//                    This is the historical path — the faucet and every already
+//                    -registered coinType-118 account MUST keep using it.
+//   'eth_secp256k1'  — eth-native unified account (address = keccak(pubkey)[12:]),
+//                    so its qor1 / 0x / svm forms are ONE identity spendable on
+//                    both the Cosmos and EVM lanes. Signs Cosmos txs with
+//                    keccak-secp256k1 and the /cosmos.evm.crypto.v1.ethsecp256k1
+//                    pubkey (requires qorechain-core >= v3.1.83). PQC key +
+//                    signing are delegated to @qorechain/wallet-adapter's
+//                    walletFromMnemonic / signHybridEth / signClassicalEth so the
+//                    same key registered by the wallet SDK verifies here.
+export async function signerContext(mnemonic, prefix = 'qor', { keyType = 'secp256k1' } = {}) {
+  if (keyType === 'eth_secp256k1') {
+    const w = await walletFromMnemonic(mnemonic); // { privateKey, pubkey, cosmos, evm, svm, pqc }
+    return {
+      ethNative: true,
+      address: w.cosmos,
+      pubkeySecp256k1: w.pubkey, // compressed eth_secp256k1 pubkey (used as ecdsa_pubkey in register)
+      pqc: w.pqc,
+      ethKey: { privateKey: w.privateKey, pubkey: w.pubkey, pqc: w.pqc },
+    };
+  }
+  const wallet = await DirectSecp256k1HdWallet.fromMnemonic(mnemonic, { prefix });
+  const [acct] = await wallet.getAccounts();
+  // CANONICAL ecosystem PQC derivation: bind the ML-DSA-87 seed to the account
+  // address, IDENTICAL to @qorechain/wallet-adapter / SDK and to the eth_secp256k1
+  // branch above (walletFromMnemonic). Unifies the derivation across every tool so
+  // the same mnemonic yields the same key everywhere.
+  const pqc = mldsa.keygen(shake256(new TextEncoder().encode(`qorechain:pqc:v1|${acct.address}|${mnemonic}`), 32));
+  // LEGACY fallback: pre-fix chain-bridge derived coin-118 PQC keys as
+  // shake256(mnemonic) (no address binding). Accounts registered that way still
+  // hold that key on-chain, and the chain cannot rotate a key within the same
+  // algorithm — so keep the legacy key available; _submitHybridAuto falls back to
+  // it when the canonical signature is rejected.
+  const pqcLegacy = mldsa.keygen(shake256(new TextEncoder().encode(mnemonic), 32));
+  return { wallet, address: acct.address, pubkeySecp256k1: acct.pubkey, pqc, pqcLegacy };
+}
+
+function feeFor(gasLimit, gasPrice) {
+  // gasPrice in uqor/gas (the chain's min-gas-price is gas-proportional).
+  const amount = Math.ceil(Number(gasLimit) * Number(gasPrice));
+  return { amount: [{ denom: 'uqor', amount: String(amount) }], gasLimit: BigInt(gasLimit) };
+}
+
+// cosmjs's default account parser calls decodePubkey, which throws
+// "Pubkey type URL '/cosmos.evm.crypto.v1.ethsecp256k1.PubKey' not recognized"
+// once an eth-native account has sent (its on-chain pubkey is ethsecp256k1). We
+// never need the account's stored pubkey (authInfo is built from ctx), so decode
+// only address/number/sequence from the BaseAccount and ignore the pubkey.
+function qoreAccountParser(any) {
+  if (any.typeUrl === '/cosmos.auth.v1beta1.BaseAccount') {
+    const ba = BaseAccount.decode(any.value);
+    return { address: ba.address, pubkey: null, accountNumber: Number(ba.accountNumber), sequence: Number(ba.sequence) };
+  }
+  return accountFromAny(any);
+}
+
+async function withClient(rpc, fn) {
+  const client = await StargateClient.connect(rpc, { accountParser: qoreAccountParser });
+  try { return await fn(client); } finally { client.disconnect(); }
+}
+
+function assertOk(res, what) {
+  if (res.code !== 0) {
+    const err = new Error(`${what} failed: code ${res.code}: ${res.rawLog || ''}`);
+    err.code = res.code;
+    err.rawLog = res.rawLog;
+    err.txHash = res.transactionHash;
+    throw err;
+  }
+  return {
+    txHash: res.transactionHash, code: res.code, height: res.height,
+    gasUsed: res.gasUsed, events: res.events || [],
+  };
+}
+
+// Find the first attribute value for (eventType, attrKey) in a DeliverTx result.
+export function findEventAttr(events, eventType, attrKey) {
+  for (const ev of events || []) {
+    if (ev.type !== eventType) continue;
+    for (const a of ev.attributes || []) {
+      const k = typeof a.key === 'string' ? a.key : Buffer.from(a.key).toString();
+      if (k === attrKey) return typeof a.value === 'string' ? a.value : Buffer.from(a.value).toString();
+    }
+  }
+  return undefined;
+}
+
+// Hybrid (PQC + classical) broadcast. messages: [{ typeUrl, value:Uint8Array }].
+// Mirrors the chain's `tx pqc cosign`:
+//   B0   = TxBody{messages, memo, timeoutHeight}            (no extension)
+//   sigP = ML-DSA-87(deterministic).sign( frame(B0, authInfo) )
+//   body = TxBody{...B0, extensionOptions:[PQCHybridSignature{1, sigP}]}
+//   sigC = wallet.signDirect( SignDoc{body, authInfo, chainId, accountNumber} )
+//   tx   = TxRaw{ body, authInfo, [sigC] }
+export async function submitHybrid({ ctx, rpc, chainId, messages, gasLimit, gasPrice, memo = '', what = 'tx' }) {
+  return withClient(rpc, async (client) => {
+    const acct = await client.getAccount(ctx.address);
+    if (!acct) throw new Error(`account ${ctx.address} not found on-chain — fund it first`);
+
+    // eth-native path: delegate the whole build+sign to the wallet SDK (keccak
+    // secp256k1 + ethsecp256k1 pubkey + ML-DSA-87 hybrid), then broadcast.
+    if (ctx.ethNative) {
+      const txBytes = await signHybridEth({
+        key: ctx.ethKey, chainId, accountNumber: acct.accountNumber,
+        messages, fee: feeFor(gasLimit, gasPrice), sequence: acct.sequence, memo,
+      });
+      return assertOk(await client.broadcastTx(txBytes), what);
+    }
+
+    const pubAny = {
+      typeUrl: '/cosmos.crypto.secp256k1.PubKey',
+      value: PubKey.encode(PubKey.fromPartial({ key: ctx.pubkeySecp256k1 })).finish(),
+    };
+    const authInfo = AuthInfo.fromPartial({
+      signerInfos: [SignerInfo.fromPartial({
+        publicKey: pubAny,
+        modeInfo: ModeInfo.fromPartial({ single: { mode: SignMode.SIGN_MODE_DIRECT } }),
+        sequence: BigInt(acct.sequence),
+      })],
+      fee: Fee.fromPartial(feeFor(gasLimit, gasPrice)),
+    });
+    const authInfoBytes = AuthInfo.encode(authInfo).finish();
+
+    const b0 = TxBody.encode(TxBody.fromPartial({ messages, memo, timeoutHeight: 0n })).finish();
+    // @qorechain/pqc >=0.1.1 signs deterministically (FIPS-204 §3.4) by default,
+    // as QoreChain's PQC ante verifier requires.
+    const pqcSig = mldsa.sign(ctx.pqc.secretKey, frame(b0, authInfoBytes));
+    const bodyBytes = TxBody.encode(TxBody.fromPartial({
+      messages, memo, timeoutHeight: 0n,
+      extensionOptions: [{ typeUrl: HYBRID_SIG_TYPE_URL, value: encodePqcHybridSignature(ALGORITHM_ML_DSA_87, pqcSig) }],
+    })).finish();
+
+    const { signature } = await ctx.wallet.signDirect(ctx.address, {
+      bodyBytes, authInfoBytes, chainId, accountNumber: BigInt(acct.accountNumber),
+    });
+    const classicalSig = typeof signature.signature === 'string'
+      ? Uint8Array.from(Buffer.from(signature.signature, 'base64')) : signature.signature;
+    const txBytes = TxRaw.encode(TxRaw.fromPartial({ bodyBytes, authInfoBytes, signatures: [classicalSig] })).finish();
+    return assertOk(await client.broadcastTx(txBytes), what);
+  });
+}
+
+// Classical secp256k1-only broadcast (for PQC-exempt registration msgs).
+export async function submitClassical({ ctx, rpc, chainId, messages, gasLimit, gasPrice, memo = '', what = 'tx' }) {
+  return withClient(rpc, async (client) => {
+    const acct = await client.getAccount(ctx.address);
+    if (!acct) throw new Error(`account ${ctx.address} not found on-chain — fund it first`);
+    if (ctx.ethNative) {
+      const txBytes = await signClassicalEth({
+        key: ctx.ethKey, chainId, accountNumber: acct.accountNumber,
+        messages, fee: feeFor(gasLimit, gasPrice), sequence: acct.sequence, memo,
+      });
+      return assertOk(await client.broadcastTx(txBytes), what);
+    }
+    const pubAny = {
+      typeUrl: '/cosmos.crypto.secp256k1.PubKey',
+      value: PubKey.encode(PubKey.fromPartial({ key: ctx.pubkeySecp256k1 })).finish(),
+    };
+    const authInfo = AuthInfo.fromPartial({
+      signerInfos: [SignerInfo.fromPartial({
+        publicKey: pubAny,
+        modeInfo: ModeInfo.fromPartial({ single: { mode: SignMode.SIGN_MODE_DIRECT } }),
+        sequence: BigInt(acct.sequence),
+      })],
+      fee: Fee.fromPartial(feeFor(gasLimit, gasPrice)),
+    });
+    const authInfoBytes = AuthInfo.encode(authInfo).finish();
+    const bodyBytes = TxBody.encode(TxBody.fromPartial({ messages, memo, timeoutHeight: 0n })).finish();
+    const signDoc = { bodyBytes, authInfoBytes, chainId, accountNumber: BigInt(acct.accountNumber) };
+    const { signature } = await ctx.wallet.signDirect(ctx.address, signDoc);
+    const sig = typeof signature.signature === 'string'
+      ? Uint8Array.from(Buffer.from(signature.signature, 'base64'))
+      : signature.signature;
+    const txRaw = TxRaw.encode(TxRaw.fromPartial({ bodyBytes, authInfoBytes, signatures: [sig] })).finish();
+    return assertOk(await client.broadcastTx(txRaw), what);
+  });
+}
+
+export { feeFor };

package/src/evm.js

@@ -0,0 +1,60 @@
+// @qorechain/chain-bridge — EVM contract deployment.
+//
+// The EVM lane is the only deploy path that is PQC-exempt: it uses a standard
+// secp256k1 Ethereum tx (eth_sendRawTransaction) over JSON-RPC, exactly like
+// any EVM chain. The native currency is the 18-decimal `aqor` view of QOR and
+// the testnet chain-id is 9800 (mainnet 9801). ethers handles gas/nonce.
+//
+// Two modes:
+//   - { abi, args }  → ContractFactory deploy (constructor args supported)
+//   - { bytecode }   → raw create tx (precompiled creation bytecode)
+
+import { ethers } from 'ethers';
+
+export async function deployEvm({
+  evmRpc,
+  evmChainId,
+  privateKey,
+  mnemonic,
+  bytecode,
+  abi,
+  args = [],
+  value, // optional wei to send with constructor (aqor, 18-dec)
+}) {
+  if (!evmRpc) throw new Error('deployEvm: evmRpc is required');
+  if (!bytecode) throw new Error('deployEvm: bytecode is required');
+
+  const provider = new ethers.JsonRpcProvider(
+    evmRpc,
+    evmChainId ? { chainId: Number(evmChainId), name: 'qorechain-evm' } : undefined,
+  );
+  const wallet = privateKey
+    ? new ethers.Wallet(privateKey, provider)
+    : ethers.Wallet.fromPhrase(mnemonic).connect(provider);
+
+  const overrides = value != null ? { value } : {};
+
+  if (abi) {
+    const factory = new ethers.ContractFactory(abi, bytecode, wallet);
+    const contract = await factory.deploy(...args, overrides);
+    const receipt = await contract.deploymentTransaction().wait();
+    return {
+      vm: 'evm',
+      address: await contract.getAddress(),
+      txHash: receipt.hash,
+      blockNumber: receipt.blockNumber,
+      deployer: wallet.address,
+    };
+  }
+
+  const data = bytecode.startsWith('0x') ? bytecode : '0x' + bytecode;
+  const sent = await wallet.sendTransaction({ data, ...overrides });
+  const receipt = await sent.wait();
+  return {
+    vm: 'evm',
+    address: receipt.contractAddress,
+    txHash: receipt.hash,
+    blockNumber: receipt.blockNumber,
+    deployer: wallet.address,
+  };
+}

package/src/features.js

@@ -0,0 +1,82 @@
+// @qorechain/chain-bridge — dashboard license → on-chain feature_id mapping.
+//
+// The dashboard stores a license as { type, tier, chains[] }; the chain gates
+// on flat feature_id strings (x/license/types/feature_ids.go). This module maps
+// one to the other, normalizing free-text chain names to the canonical slugs.
+//
+// type → feature_ids:
+//   light_node     → ["lightnode_operator"]
+//   validator      → ["validator_operator", "validator_<chain>"…]
+//   cross_network  → ["qcb_bridge", "bridge_<chain>"…]
+// Unknown chains are dropped (logged by the caller) rather than minting an
+// invalid feature_id the chain would reject.
+
+// Canonical per-chain slugs (mirror feature_ids.go exactly).
+const VALIDATOR_CHAINS = new Set([
+  'akash', 'algorand', 'arbitrum', 'avalanche', 'babylon', 'base', 'berachain',
+  'blast', 'bsc', 'celestia', 'cosmoshub', 'cronos', 'ethereum', 'filecoin',
+  'hedera', 'hyperliquid', 'injective', 'kaia', 'linea', 'mantle', 'monad',
+  'noble', 'optimism', 'osmosis', 'plasma', 'polygon', 'scroll', 'sei',
+  'solana', 'sonic', 'starknet', 'stellar', 'stride', 'sui', 'ton', 'xrpl',
+  'zksync_era',
+]);
+const BRIDGE_CHAINS = new Set([
+  'algorand', 'arbitrum', 'avalanche', 'base', 'berachain', 'bitcoin', 'blast',
+  'bsc', 'cardano', 'cronos', 'ethereum', 'filecoin', 'hedera', 'hyperliquid',
+  'injective', 'kaia', 'linea', 'mantle', 'monad', 'near', 'optimism', 'plasma',
+  'polkadot', 'polygon', 'scroll', 'sei', 'solana', 'sonic', 'starknet',
+  'stellar', 'sui', 'tezos', 'ton', 'tron', 'xrpl', 'zksync_era',
+]);
+
+// Free-text → canonical slug aliases (lowercase keys).
+const ALIASES = {
+  eth: 'ethereum', ether: 'ethereum',
+  bnb: 'bsc', binance: 'bsc', 'bnb smart chain': 'bsc', 'bnb chain': 'bsc', 'binance smart chain': 'bsc',
+  'zksync': 'zksync_era', 'zksync era': 'zksync_era', 'zk sync': 'zksync_era',
+  'cosmos': 'cosmoshub', 'cosmos hub': 'cosmoshub', atom: 'cosmoshub',
+  'xrp': 'xrpl', ripple: 'xrpl', 'xrp ledger': 'xrpl',
+  matic: 'polygon', 'polygon pos': 'polygon',
+  avax: 'avalanche', 'avalanche c-chain': 'avalanche',
+  btc: 'bitcoin', sol: 'solana', dot: 'polkadot', xtz: 'tezos', trx: 'tron',
+  'arbitrum one': 'arbitrum', op: 'optimism', 'op mainnet': 'optimism',
+  fil: 'filecoin', xlm: 'stellar', algo: 'algorand',
+};
+
+export function normalizeChain(name) {
+  const k = String(name || '').trim().toLowerCase();
+  if (!k) return '';
+  if (ALIASES[k]) return ALIASES[k];
+  return k.replace(/[\s\-./]+/g, '_');
+}
+
+// Returns { featureIds: string[], dropped: string[] }.
+export function featureIdsFor({ type, chains = [] } = {}) {
+  const t = String(type || '').trim().toLowerCase();
+  const ids = [];
+  const dropped = [];
+  const list = Array.isArray(chains) ? chains : (chains ? [chains] : []);
+
+  if (t === 'light_node' || t === 'lightnode' || t === 'light-node') {
+    ids.push('lightnode_operator');
+  } else if (t === 'validator') {
+    ids.push('validator_operator');
+    for (const c of list) {
+      const s = normalizeChain(c);
+      if (VALIDATOR_CHAINS.has(s)) ids.push(`validator_${s}`);
+      else if (s) dropped.push(c);
+    }
+  } else if (t === 'cross_network' || t === 'bridge' || t === 'crossnetwork') {
+    ids.push('qcb_bridge');
+    for (const c of list) {
+      const s = normalizeChain(c);
+      if (BRIDGE_CHAINS.has(s)) ids.push(`bridge_${s}`);
+      else if (s) dropped.push(c);
+    }
+  } else if (t) {
+    dropped.push(`type:${type}`);
+  }
+
+  return { featureIds: [...new Set(ids)], dropped };
+}
+
+export const __test__ = { VALIDATOR_CHAINS, BRIDGE_CHAINS };

package/src/index.d.ts

@@ -0,0 +1,67 @@
+// Type definitions for @qorechain/chain-bridge
+
+export interface ChainBridgeConfig {
+  cosmosRpc: string;          // e.g. http://node:26657
+  chainId: string;            // e.g. qorechain-diana
+  cosmosRest?: string;        // optional REST/LCD (:1317)
+  evmRpc?: string;            // EVM JSON-RPC (:8545)
+  evmChainId?: number;        // 9800 testnet / 9801 mainnet
+  prefix?: string;            // bech32 prefix, default 'qor'
+  denom?: string;             // base denom, default 'uqor'
+  gasPrice?: number;          // uqor/gas, default 0.1
+  authorityMnemonic?: string; // x/license authority key (for grant/revoke/…)
+  signerMnemonic?: string;    // funded operator/treasury key (deploy/send)
+  evmDeployerKey?: string;    // EVM deployer private key (hex)
+  gas?: Partial<Record<'grant' | 'licenseAction' | 'registerPqc' | 'registerLightNode' | 'deploySvm' | 'send', number>>;
+}
+
+export interface TxResult {
+  txHash: string;
+  code: number;
+  height?: number;
+  gasUsed?: bigint;
+}
+
+export interface GrantSetResult {
+  grants: Array<{ featureId: string; txHash: string; height?: number }>;
+  dropped: string[];
+}
+
+export interface EvmDeployResult {
+  vm: 'evm';
+  address: string;
+  txHash: string;
+  blockNumber: number;
+  deployer: string;
+}
+
+export interface LicenseSpec { type: string; chains?: string[] }
+export interface FeatureMapResult { featureIds: string[]; dropped: string[] }
+
+export class ChainBridge {
+  constructor(cfg: ChainBridgeConfig);
+  featureIdsFor(license: LicenseSpec): FeatureMapResult;
+  normalizeChain(name: string): string;
+
+  registerPqc(opts: { mnemonic: string }): Promise<TxResult>;
+
+  grantLicense(opts: { grantee: string; featureId: string; expiresAt?: number; metadata?: string; authorityMnemonic?: string }): Promise<TxResult>;
+  grantLicenseSet(opts: { grantee: string; type: string; chains?: string[]; expiresAt?: number; metadata?: string; authorityMnemonic?: string }): Promise<GrantSetResult>;
+  revokeLicense(opts: { grantee: string; featureId: string; authorityMnemonic?: string }): Promise<TxResult>;
+  suspendLicense(opts: { grantee: string; featureId: string; authorityMnemonic?: string }): Promise<TxResult>;
+  resumeLicense(opts: { grantee: string; featureId: string; authorityMnemonic?: string }): Promise<TxResult>;
+
+  registerLightNode(opts: { operatorMnemonic: string; nodeType?: string; version?: string; capabilities?: string[] }): Promise<TxResult>;
+
+  deployEvm(opts: { bytecode: string; abi?: any[]; args?: any[]; value?: bigint; evmRpc?: string; evmChainId?: number; privateKey?: string; mnemonic?: string }): Promise<EvmDeployResult>;
+  deploySvm(opts: { bytecode: string | Uint8Array; signerMnemonic?: string; gasLimit?: number }): Promise<TxResult>;
+
+  sendTokens(opts: { to: string; amountUqor: string | number; signerMnemonic?: string }): Promise<TxResult>;
+
+  createVestingAccount(opts: { toAddress: string; amountUqor: string | number; endTime: number; delayed?: boolean; signerMnemonic?: string }): Promise<TxResult>;
+  createPeriodicVestingAccount(opts: { toAddress: string; startTime: number; periods: Array<{ length: number; amountUqor: string | number }>; signerMnemonic?: string }): Promise<TxResult>;
+}
+
+export function featureIdsFor(license: LicenseSpec): FeatureMapResult;
+export function normalizeChain(name: string): string;
+export default ChainBridge;

package/src/index.js

@@ -0,0 +1,344 @@
+// @qorechain/chain-bridge
+//
+// Autonomous, server-side bridge between a Web2 backend and QoreChain's on-chain
+// modules. Lets a dashboard / exchange / payment worker turn an off-chain event
+// (USDT payment confirmed, contract requested) into a REAL on-chain effect with
+// no CLI and no human in the loop:
+//
+//   grantLicense / grantLicenseSet  → x/license MsgGrantLicense  (PQC-signed)
+//   revoke / suspend / resume       → x/license lifecycle msgs   (PQC-signed)
+//   registerLightNode               → x/lightnode MsgRegisterLightNode (PQC)
+//   deployEvm                       → EVM eth_sendRawTransaction (secp256k1)
+//   deploySvm                       → x/svm MsgDeployProgram      (PQC-signed)
+//   sendTokens                      → bank MsgSend                (PQC-signed)
+//   registerPqc                     → x/pqc MsgRegisterPQCKeyV2   (bootstrap)
+//
+// License/lifecycle messages must be signed by the chain's configured
+// `license.authority` (genesis: app_state.license.authority). Pass that key's
+// mnemonic as `authorityMnemonic`. Deploys / sends use `signerMnemonic`
+// (a funded operator/treasury key) unless a per-call mnemonic is given.
+
+import { MsgSend } from 'cosmjs-types/cosmos/bank/v1beta1/tx.js';
+import { MsgCreateVestingAccount, MsgCreatePeriodicVestingAccount } from 'cosmjs-types/cosmos/vesting/v1beta1/tx.js';
+import * as proto from './proto.js';
+import { signerContext, submitHybrid, submitClassical, findEventAttr } from './cosmos.js';
+import { deployEvm } from './evm.js';
+import { featureIdsFor, normalizeChain } from './features.js';
+
+const DEFAULTS = {
+  prefix: 'qor',
+  denom: 'uqor',
+  gasPrice: 0.1, // uqor/gas — matches the chain's gas-proportional min fee
+  gas: {
+    grant: 600000,
+    licenseAction: 400000,
+    registerPqc: 6000000, // large: 2592-byte ML-DSA pubkey + classical
+    registerLightNode: 500000,
+    deploySvm: 3000000,
+    storeWasm: 6000000,
+    instantiateWasm: 1000000,
+    send: 300000,
+    vesting: 400000,
+  },
+};
+
+// rawLog fragments that mean "the signer has no registered PQC key yet".
+const PQC_MISSING = /pqc|hybrid signature|public key not found|no pqc key|register.*key/i;
+
+export class ChainBridge {
+  constructor(cfg = {}) {
+    if (!cfg.cosmosRpc) throw new Error('ChainBridge: cosmosRpc is required');
+    if (!cfg.chainId) throw new Error('ChainBridge: chainId is required');
+    this.cfg = {
+      ...DEFAULTS,
+      ...cfg,
+      gas: { ...DEFAULTS.gas, ...(cfg.gas || {}) },
+    };
+    this._ctxCache = new Map(); // mnemonic → signerContext (lazy)
+    this._pqcEnsured = new Set(); // addresses we've already bootstrapped this run
+  }
+
+  async _ctx(mnemonic) {
+    if (!mnemonic) throw new Error('ChainBridge: no mnemonic available for this operation');
+    // keyType: 'secp256k1' (coinType-118, default) | 'eth_secp256k1' (unified
+    // eth-native, qor1/0x/svm one identity). Cache per (mnemonic, keyType).
+    const keyType = this.cfg.keyType || 'secp256k1';
+    const cacheKey = `${keyType}:${mnemonic}`;
+    if (!this._ctxCache.has(cacheKey)) {
+      this._ctxCache.set(cacheKey, await signerContext(mnemonic, this.cfg.prefix, { keyType }));
+    }
+    return this._ctxCache.get(cacheKey);
+  }
+
+  featureIdsFor(license) { return featureIdsFor(license); }
+  normalizeChain(name) { return normalizeChain(name); }
+
+  // ── PQC bootstrap ──────────────────────────────────────────────────────────
+  // Register the signer's ML-DSA-87 public key on-chain so its hybrid txs verify.
+  // Uses the classical (PQC-exempt) path. Idempotent within a process run.
+  async registerPqc({ mnemonic }) {
+    const ctx = await this._ctx(mnemonic);
+    const value = proto.encodeMsgRegisterPQCKeyV2({
+      sender: ctx.address,
+      publicKey: ctx.pqc.publicKey,
+      algorithmId: 1, // ML-DSA-87 / Dilithium-5
+      ecdsaPubkey: ctx.pubkeySecp256k1,
+      keyType: 'hybrid',
+    });
+    const res = await submitClassical({
+      ctx,
+      rpc: this.cfg.cosmosRpc,
+      chainId: this.cfg.chainId,
+      messages: [{ typeUrl: proto.TYPE_URLS.registerPqcV2, value }],
+      gasLimit: this.cfg.gas.registerPqc,
+      gasPrice: this.cfg.gasPrice,
+      memo: 'chain-bridge: register pqc key',
+      what: 'register-pqc-key',
+    });
+    this._pqcEnsured.add(ctx.address);
+    return res;
+  }
+
+  // Submit a hybrid tx, auto-bootstrapping the signer's PQC key once if the
+  // chain rejects it for a missing PQC registration.
+  async _submitHybridAuto({ mnemonic, messages, gasLimit, memo, what }) {
+    const ctx = await this._ctx(mnemonic);
+    const args = {
+      ctx, rpc: this.cfg.cosmosRpc, chainId: this.cfg.chainId,
+      messages, gasLimit, gasPrice: this.cfg.gasPrice, memo, what,
+    };
+    try {
+      return await submitHybrid(args);
+    } catch (err) {
+      const log = String(err.rawLog || err.message || '');
+      // (a) Legacy-derivation account: its on-chain PQC key was registered with the
+      // old shake256(mnemonic) derivation, so the canonical signature is rejected
+      // (code 21). Retry with the legacy key. Checked FIRST — PQC_MISSING is broad
+      // and would otherwise also match this "…verification failed" message.
+      if (ctx.pqcLegacy && !ctx.usedLegacy && /verification failed/i.test(log)) {
+        return submitHybrid({ ...args, ctx: { ...ctx, pqc: ctx.pqcLegacy, usedLegacy: true } });
+      }
+      // (b) No PQC key registered yet → register the CANONICAL key + retry.
+      if (!this._pqcEnsured.has(ctx.address) && PQC_MISSING.test(log)) {
+        await this.registerPqc({ mnemonic });
+        return submitHybrid(args);
+      }
+      throw err;
+    }
+  }
+
+  // ── x/license ────────────────────────────────────────────────────────────--
+  async grantLicense({ grantee, featureId, expiresAt = 0, metadata = '', authorityMnemonic }) {
+    const mnemonic = authorityMnemonic || this.cfg.authorityMnemonic;
+    const ctx = await this._ctx(mnemonic);
+    const value = proto.encodeMsgGrantLicense({
+      authority: ctx.address, grantee, featureId, expiresAt, metadata,
+    });
+    return this._submitHybridAuto({
+      mnemonic,
+      messages: [{ typeUrl: proto.TYPE_URLS.grantLicense, value }],
+      gasLimit: this.cfg.gas.grant,
+      memo: `chain-bridge: grant ${featureId}`,
+      what: `grant-license:${featureId}`,
+    });
+  }
+
+  // Grant every feature_id implied by a dashboard license {type, chains}.
+  // Returns { grants: [{featureId, txHash}], dropped: [...] }. Each grant is an
+  // independent tx so a single failure doesn't roll back the others.
+  async grantLicenseSet({ grantee, type, chains = [], expiresAt = 0, metadata = '', authorityMnemonic }) {
+    const { featureIds, dropped } = featureIdsFor({ type, chains });
+    const grants = [];
+    for (const featureId of featureIds) {
+      const res = await this.grantLicense({ grantee, featureId, expiresAt, metadata, authorityMnemonic });
+      grants.push({ featureId, txHash: res.txHash, height: res.height });
+    }
+    return { grants, dropped };
+  }
+
+  async _licenseAction(kind, { grantee, featureId, authorityMnemonic }) {
+    const mnemonic = authorityMnemonic || this.cfg.authorityMnemonic;
+    const ctx = await this._ctx(mnemonic);
+    const value = proto.encodeMsgLicenseAction({ authority: ctx.address, grantee, featureId });
+    const typeUrl = proto.TYPE_URLS[`${kind}License`];
+    return this._submitHybridAuto({
+      mnemonic,
+      messages: [{ typeUrl, value }],
+      gasLimit: this.cfg.gas.licenseAction,
+      memo: `chain-bridge: ${kind} ${featureId}`,
+      what: `${kind}-license:${featureId}`,
+    });
+  }
+  revokeLicense(a)  { return this._licenseAction('revoke', a); }
+  suspendLicense(a) { return this._licenseAction('suspend', a); }
+  resumeLicense(a)  { return this._licenseAction('resume', a); }
+
+  // ── x/lightnode ──────────────────────────────────────────────────────────--
+  async registerLightNode({ operatorMnemonic, nodeType = 'SX', version = '1.0.0', capabilities = [] }) {
+    const ctx = await this._ctx(operatorMnemonic);
+    const value = proto.encodeMsgRegisterLightNode({
+      operator: ctx.address, nodeType, version, capabilities,
+    });
+    return this._submitHybridAuto({
+      mnemonic: operatorMnemonic,
+      messages: [{ typeUrl: proto.TYPE_URLS.registerLightNode, value }],
+      gasLimit: this.cfg.gas.registerLightNode,
+      memo: 'chain-bridge: register light node',
+      what: 'register-light-node',
+    });
+  }
+
+  // ── x/svm ────────────────────────────────────────────────────────────────--
+  async deploySvm({ bytecode, signerMnemonic, gasLimit }) {
+    const mnemonic = signerMnemonic || this.cfg.signerMnemonic;
+    const ctx = await this._ctx(mnemonic);
+    const bytes = typeof bytecode === 'string'
+      ? Uint8Array.from(Buffer.from(bytecode.replace(/^0x/, ''), 'hex'))
+      : bytecode;
+    const value = proto.encodeMsgDeployProgram({ sender: ctx.address, bytecode: bytes });
+    return this._submitHybridAuto({
+      mnemonic,
+      messages: [{ typeUrl: proto.TYPE_URLS.deployProgram, value }],
+      gasLimit: gasLimit || this.cfg.gas.deploySvm,
+      memo: 'chain-bridge: deploy svm program',
+      what: 'deploy-svm-program',
+    });
+  }
+
+  // ── CosmWasm (WASM VM) ─────────────────────────────────────────────────────
+  // Store wasm bytecode → returns { txHash, codeId }.
+  async storeWasm({ wasmBytes, signerMnemonic, gasLimit }) {
+    const mnemonic = signerMnemonic || this.cfg.signerMnemonic;
+    const ctx = await this._ctx(mnemonic);
+    const bytes = typeof wasmBytes === 'string'
+      ? Uint8Array.from(Buffer.from(wasmBytes.replace(/^0x/, ''), 'hex'))
+      : wasmBytes;
+    const value = proto.encodeMsgStoreCode({ sender: ctx.address, wasmByteCode: bytes });
+    const res = await this._submitHybridAuto({
+      mnemonic,
+      messages: [{ typeUrl: proto.TYPE_URLS.storeCode, value }],
+      gasLimit: gasLimit || this.cfg.gas.storeWasm,
+      memo: 'chain-bridge: store wasm',
+      what: 'store-wasm',
+    });
+    const codeId = findEventAttr(res.events, 'store_code', 'code_id');
+    return { ...res, codeId: codeId ? Number(codeId) : undefined };
+  }
+
+  // Instantiate a stored code id → returns { txHash, contractAddress }.
+  async instantiateWasm({ codeId, initMsg = {}, label = 'qorechain-contract', admin = '', signerMnemonic, funds = [] }) {
+    const mnemonic = signerMnemonic || this.cfg.signerMnemonic;
+    const ctx = await this._ctx(mnemonic);
+    const value = proto.encodeMsgInstantiateContract({
+      sender: ctx.address, admin, codeId,
+      label, msg: JSON.stringify(initMsg), funds,
+    });
+    const res = await this._submitHybridAuto({
+      mnemonic,
+      messages: [{ typeUrl: proto.TYPE_URLS.instantiate, value }],
+      gasLimit: this.cfg.gas.instantiateWasm,
+      memo: 'chain-bridge: instantiate wasm',
+      what: 'instantiate-wasm',
+    });
+    const contractAddress = findEventAttr(res.events, 'instantiate', '_contract_address');
+    return { ...res, contractAddress };
+  }
+
+  // Store + instantiate in one call → { codeId, contractAddress, txHashes }.
+  async deployWasm({ wasmBytes, initMsg = {}, label = 'qorechain-contract', admin = '', signerMnemonic }) {
+    const stored = await this.storeWasm({ wasmBytes, signerMnemonic });
+    if (!stored.codeId) throw new Error('deployWasm: could not read code_id from store tx events');
+    const inst = await this.instantiateWasm({ codeId: stored.codeId, initMsg, label, admin, signerMnemonic });
+    return {
+      vm: 'wasm',
+      codeId: stored.codeId,
+      contractAddress: inst.contractAddress,
+      txHashes: [stored.txHash, inst.txHash],
+    };
+  }
+
+  // ── EVM ──────────────────────────────────────────────────────────────────--
+  async deployEvm(opts) {
+    return deployEvm({
+      evmRpc: opts.evmRpc || this.cfg.evmRpc,
+      evmChainId: opts.evmChainId || this.cfg.evmChainId,
+      privateKey: opts.privateKey || this.cfg.evmDeployerKey,
+      mnemonic: opts.mnemonic || this.cfg.signerMnemonic,
+      bytecode: opts.bytecode,
+      abi: opts.abi,
+      args: opts.args || [],
+      value: opts.value,
+    });
+  }
+
+  // ── vesting (x/auth/vesting) ────────────────────────────────────────────────
+  // Create a continuous (or delayed) vesting account for `toAddress`, funded by
+  // the signer. Single end_time. delayed=true → all locked until end_time (cliff
+  // only); delayed=false → linear from start (account creation) to end_time.
+  async createVestingAccount({ toAddress, amountUqor, endTime, delayed = false, signerMnemonic }) {
+    const mnemonic = signerMnemonic || this.cfg.signerMnemonic;
+    const ctx = await this._ctx(mnemonic);
+    const value = MsgCreateVestingAccount.encode(MsgCreateVestingAccount.fromPartial({
+      fromAddress: ctx.address,
+      toAddress,
+      amount: [{ denom: this.cfg.denom, amount: String(amountUqor) }],
+      endTime: BigInt(Math.trunc(endTime)),
+      delayed,
+    })).finish();
+    return this._submitHybridAuto({
+      mnemonic,
+      messages: [{ typeUrl: '/cosmos.vesting.v1beta1.MsgCreateVestingAccount', value }],
+      gasLimit: this.cfg.gas.vesting,
+      memo: 'chain-bridge: create vesting account',
+      what: 'create-vesting-account',
+    });
+  }
+
+  // Create a periodic vesting account — the right tool for "TGE unlock + cliff +
+  // linear" schedules. `periods` = [{ length: seconds, amountUqor }] (length is
+  // RELATIVE to the previous period; the amount unlocks at the END of the period).
+  // Sum of amounts MUST equal the total funded amount.
+  async createPeriodicVestingAccount({ toAddress, startTime, periods, signerMnemonic }) {
+    const mnemonic = signerMnemonic || this.cfg.signerMnemonic;
+    const ctx = await this._ctx(mnemonic);
+    const vestingPeriods = periods.map((p) => ({
+      length: BigInt(Math.trunc(p.length)),
+      amount: [{ denom: this.cfg.denom, amount: String(p.amountUqor) }],
+    }));
+    const value = MsgCreatePeriodicVestingAccount.encode(MsgCreatePeriodicVestingAccount.fromPartial({
+      fromAddress: ctx.address,
+      toAddress,
+      startTime: BigInt(Math.trunc(startTime)),
+      vestingPeriods,
+    })).finish();
+    return this._submitHybridAuto({
+      mnemonic,
+      messages: [{ typeUrl: '/cosmos.vesting.v1beta1.MsgCreatePeriodicVestingAccount', value }],
+      gasLimit: Math.max(this.cfg.gas.vesting, 200000 + periods.length * 8000),
+      memo: 'chain-bridge: create periodic vesting account',
+      what: 'create-periodic-vesting-account',
+    });
+  }
+
+  // ── bank ─────────────────────────────────────────────────────────────────--
+  async sendTokens({ to, amountUqor, signerMnemonic }) {
+    const mnemonic = signerMnemonic || this.cfg.signerMnemonic;
+    const ctx = await this._ctx(mnemonic);
+    const value = MsgSend.encode(MsgSend.fromPartial({
+      fromAddress: ctx.address,
+      toAddress: to,
+      amount: [{ denom: this.cfg.denom, amount: String(amountUqor) }],
+    })).finish();
+    return this._submitHybridAuto({
+      mnemonic,
+      messages: [{ typeUrl: '/cosmos.bank.v1beta1.MsgSend', value }],
+      gasLimit: this.cfg.gas.send,
+      memo: 'chain-bridge: send',
+      what: 'send-tokens',
+    });
+  }
+}
+
+export { featureIdsFor, normalizeChain } from './features.js';
+export * as proto from './proto.js';
+export default ChainBridge;

package/src/proto.js

@@ -0,0 +1,131 @@
+// @qorechain/chain-bridge — minimal protobuf wire encoders.
+//
+// QoreChain's custom modules (license, pqc, lightnode, svm) have no published
+// cosmjs-types codecs, so we hand-encode the handful of Msg types we need.
+// Their shapes are trivial (a few strings / bytes / varints), and proto3 wire
+// format is stable, so a ~60-line encoder is more robust than dragging in a
+// proto runtime. Field numbers/types mirror the .proto exactly:
+//   x/license/v1/tx.proto, x/pqc/v1/tx.proto, x/lightnode/v1/tx.proto,
+//   x/svm/v1/tx.proto.
+//
+// Each encoder returns a Uint8Array suitable as the `value` of a cosmos Any
+// ({ typeUrl, value }) — which is exactly what QoreChainSigner.signHybrid and
+// our classical signer consume.
+
+const EMPTY = new Uint8Array(0);
+const utf8 = (s) => new TextEncoder().encode(s);
+
+// LEB128 varint of a non-negative integer (Number or BigInt).
+function varint(n) {
+  let v = typeof n === 'bigint' ? n : BigInt(Math.trunc(n));
+  if (v < 0n) throw new RangeError('varint: negative value');
+  const out = [];
+  do {
+    let b = Number(v & 0x7fn);
+    v >>= 7n;
+    if (v > 0n) b |= 0x80;
+    out.push(b);
+  } while (v > 0n);
+  return Uint8Array.from(out);
+}
+
+function concat(chunks) {
+  let total = 0;
+  for (const c of chunks) total += c.length;
+  const out = new Uint8Array(total);
+  let o = 0;
+  for (const c of chunks) { out.set(c, o); o += c.length; }
+  return out;
+}
+
+// wire types: 0 = varint, 2 = length-delimited
+const tag = (field, wire) => varint((field << 3) | wire);
+
+const lenDelim = (field, bytes) => concat([tag(field, 2), varint(bytes.length), bytes]);
+
+// proto3: scalar default values are omitted on the wire.
+const strField = (field, s) => (s ? lenDelim(field, utf8(s)) : EMPTY);
+const bytesField = (field, b) => (b && b.length ? lenDelim(field, b instanceof Uint8Array ? b : Uint8Array.from(b)) : EMPTY);
+const varintField = (field, n) => (n ? concat([tag(field, 0), varint(n)]) : EMPTY);
+
+// ── typeUrls (cosmos Any uses a leading slash) ──────────────────────────────
+export const TYPE_URLS = {
+  grantLicense:      '/qorechain.license.v1.MsgGrantLicense',
+  revokeLicense:     '/qorechain.license.v1.MsgRevokeLicense',
+  suspendLicense:    '/qorechain.license.v1.MsgSuspendLicense',
+  resumeLicense:     '/qorechain.license.v1.MsgResumeLicense',
+  registerPqcV2:     '/qorechain.pqc.v1.MsgRegisterPQCKeyV2',
+  registerLightNode: '/qorechain.lightnode.v1.MsgRegisterLightNode',
+  deployProgram:     '/qorechain.svm.v1.MsgDeployProgram',
+  storeCode:         '/cosmwasm.wasm.v1.MsgStoreCode',
+  instantiate:       '/cosmwasm.wasm.v1.MsgInstantiateContract',
+};
+
+// ── x/license ───────────────────────────────────────────────────────────────
+// MsgGrantLicense{ authority=1, grantee=2, feature_id=3, expires_at=4, metadata=5 }
+export function encodeMsgGrantLicense({ authority, grantee, featureId, expiresAt = 0, metadata = '' }) {
+  return concat([
+    strField(1, authority),
+    strField(2, grantee),
+    strField(3, featureId),
+    varintField(4, expiresAt),
+    strField(5, metadata),
+  ]);
+}
+// Revoke/Suspend/Resume share { authority=1, grantee=2, feature_id=3 }
+export function encodeMsgLicenseAction({ authority, grantee, featureId }) {
+  return concat([strField(1, authority), strField(2, grantee), strField(3, featureId)]);
+}
+
+// ── x/pqc ─────────────────────────────────────────────────────────────────--
+// MsgRegisterPQCKeyV2{ sender=1, public_key=2, algorithm_id=3, ecdsa_pubkey=4, key_type=5 }
+export function encodeMsgRegisterPQCKeyV2({ sender, publicKey, algorithmId = 1, ecdsaPubkey, keyType = 'hybrid' }) {
+  return concat([
+    strField(1, sender),
+    bytesField(2, publicKey),
+    varintField(3, algorithmId),
+    bytesField(4, ecdsaPubkey),
+    strField(5, keyType),
+  ]);
+}
+
+// ── x/lightnode ───────────────────────────────────────────────────────────--
+// MsgRegisterLightNode{ operator=1, node_type=2, version=3, capabilities=4 (repeated) }
+export function encodeMsgRegisterLightNode({ operator, nodeType, version, capabilities = [] }) {
+  return concat([
+    strField(1, operator),
+    strField(2, nodeType),
+    strField(3, version),
+    ...(capabilities || []).map((c) => strField(4, c)),
+  ]);
+}
+
+// ── x/svm ─────────────────────────────────────────────────────────────────--
+// MsgDeployProgram{ sender=1, bytecode=2 }
+export function encodeMsgDeployProgram({ sender, bytecode }) {
+  return concat([strField(1, sender), bytesField(2, bytecode)]);
+}
+
+// ── CosmWasm (wasmd) ─────────────────────────────────────────────────────────
+// MsgStoreCode{ sender=1, wasm_byte_code=2 }  (instantiate_permission=3 omitted → default)
+export function encodeMsgStoreCode({ sender, wasmByteCode }) {
+  return concat([strField(1, sender), bytesField(2, wasmByteCode)]);
+}
+// cosmos.base.v1beta1.Coin{ denom=1, amount=2 }
+function encodeCoin({ denom, amount }) {
+  return concat([strField(1, denom), strField(2, String(amount))]);
+}
+// MsgInstantiateContract{ sender=1, admin=2, code_id=3 (uint64), label=4, msg=5 (bytes), funds=6 (repeated Coin) }
+export function encodeMsgInstantiateContract({ sender, admin = '', codeId, label, msg, funds = [] }) {
+  const msgBytes = typeof msg === 'string' ? utf8(msg) : (msg || utf8('{}'));
+  return concat([
+    strField(1, sender),
+    strField(2, admin),
+    varintField(3, codeId),
+    strField(4, label),
+    bytesField(5, msgBytes),
+    ...funds.map((c) => lenDelim(6, encodeCoin(c))),
+  ]);
+}
+
+export const __test__ = { varint, concat, tag, lenDelim, strField, bytesField, varintField };