@qorechain/sdk 0.6.1 → 0.8.0

package/README.md

@@ -108,8 +108,8 @@ console.log(result.transactionHash);
 QoreChain supports post-quantum cryptography via ML-DSA-87 (Dilithium-5) and a
 hybrid posture. The key/sign/verify primitives are available today through
 `generatePqcKeypair`, `pqcSign`, `pqcVerify`, and the pluggable `PqcSigner` /
-`HybridSigner`. Hybrid transaction submission is being finalized for the live
-network.
+`HybridSigner`, and hybrid transactions end-to-end through `buildHybridTx` /
+`signAndBroadcastHybrid`.
 
 ```ts
 import { generatePqcKeypair, pqcSign, pqcVerify } from "@qorechain/sdk";
@@ -120,6 +120,49 @@ const signature = pqcSign(keypair.secretKey, message);
 const ok = pqcVerify(keypair.publicKey, message, signature);
 ```
 
+#### Hybrid sign-bytes: v1 / v2 per network (v0.8.0)
+
+The ML-DSA-87 half of a hybrid transaction signs the body *without* the PQC
+extension (`B0`) and the AuthInfo bytes (`A`), in one of two forms:
+
+```
+v1: BE32(len B0) ‖ B0 ‖ BE32(len A) ‖ A
+v2: "qorechain-pqc-hybrid-v2" ‖ BE64(len chainId) ‖ chainId ‖ BE32(len B0) ‖ B0 ‖ BE32(len A) ‖ A
+```
+
+A network verifies exactly **one** form at any height. `qorechain-diana`
+(testnet) switched to v2 at its v3.1.98 upgrade; `qorechain-vladi` (mainnet)
+stays on v1 until its own upgrade; chains born later are v2 from genesis. So pass
+the network's REST endpoint and let the SDK ask (`signBytesVersion: "auto"`, the
+default):
+
+```ts
+import { signAndBroadcastHybrid, isHybridSignBytesRejection } from "@qorechain/sdk";
+
+const res = await signAndBroadcastHybrid({
+  registry, signer, pqcKeypair, messages, fee,
+  chainId: "qorechain-diana",
+  rest: "https://api-testnet.qore.host", // picks v1 or v2 for this network
+  accountNumber, sequence,
+  transport, // e.g. a connected StargateClient
+});
+```
+
+- `"auto"` reads `GET {rest}/cosmos/upgrade/v1beta1/applied_plan/v3.1.98` (v2 when
+  the applied height is above 0) and caches the answer for about a minute.
+- On `qorechain-vladi` / `qorechain-diana`, `"auto"` without `rest` — or with a
+  node that cannot be asked — **throws** rather than guess. Force a form with
+  `signBytesVersion: "v1"` or `"v2"`.
+- `signAndBroadcastHybrid` and `EthNativeSigner.signAndBroadcast` re-resolve and
+  retry once on a `pqc` code 21 refusal. If you broadcast yourself, catch the
+  refusal with `isHybridSignBytesRejection(err)` and rebuild with
+  `buildHybridTx({ ..., forceRefreshSignBytesVersion: true })`.
+- `built.signBytesVersion` reports the form a built transaction used.
+- The same rule covers the PQC key-migration payload (`migrationSignBytes`) and
+  the bridge attestation payload (`bridgeAttestationSignBytes`).
+- `rest` is optional in the TypeScript types, so a caller that forgets it compiles cleanly and only fails at runtime on `qorechain-vladi` / `qorechain-diana`. Cover your wiring with a runtime test, not just a type check.
+- In unit tests, pass `signBytesVersion: "v1"` or `"v2"` explicitly (or inject `fetch`): `"auto"` asks the network, so a test that omits it silently depends on a live node.
+
 ### CosmWasm contracts
 
 Interact with CosmWasm contracts via thin wrappers over
@@ -334,11 +377,7 @@ post-quantum signature. The account parser (`parseEthPubkeyAny`) reads
 account number / sequence from an eth_secp256k1 on-chain pubkey.
 
 ```ts
-import {
-  deriveUnifiedAccount,
-  unifiedAccountFromPhantomSignature,
-  signHybridEth,
-} from "@qorechain/sdk";
+import { deriveUnifiedAccount, resolveSignBytesVersion, signHybridEth } from "@qorechain/sdk";
 
 const account = await deriveUnifiedAccount(mnemonic);
 account.cosmos; // "qor1…"  — QoreChain Native lane
@@ -346,22 +385,34 @@ account.evm; //    "0x…"   — EIP-55 checksummed
 account.svm; //    "<base58>" — 20 bytes + 12 zero pad
 
 // Sign a QoreChain Native tx from the unified eth key (hybrid PQC path).
+// signHybridEth is synchronous: resolve the sign-bytes form for the network
+// first (v1 on mainnet until its v3.1.98 upgrade, v2 after).
+const signBytesVersion = await resolveSignBytesVersion({
+  chainId: "qorechain-vladi",
+  rest: "https://api.qore.host",
+});
 const signed = signHybridEth({
-  signingKey: { privateKey: account.privateKey, publicKey: account.publicKey },
-  pqc: account.pqc,
+  account, // privateKey, publicKey and the pqc keypair
   messages: [msg.cosmos.send(/* … */)],
   chainId: "qorechain-vladi",
   accountNumber,
   sequence,
   fee,
+  signBytesVersion,
+  encodeMessage: (m) => registry.encodeAsAny(m),
 });
 
-// Phantom P1a: derive a canonical, non-custodial unified account from a
-// deterministic Phantom signature (shake256(signature, 32)).
-const fromPhantom = unifiedAccountFromPhantomSignature(phantomSignature);
-// or connectPhantomUnified(provider) to run the connect → sign → derive flow.
+// Or let EthNativeSigner resolve and retry for you:
+// new EthNativeSigner(account, { rest: "https://api.qore.host" }).signAndBroadcast(transport, params)
 ```
 
+`unifiedAccountFromSeed` uses the 32 bytes it is given **as** the spend key, so
+pass real secret entropy — a CSPRNG seed or a mnemonic-derived key — never a
+wallet signature or any other value a third party can request. (The signature-
+derived helpers `unifiedAccountFromPhantomSignature` / `connectPhantomUnified`
+were removed in v0.8.0 for exactly that reason and now throw.) To let an
+external wallet key act for an account, use the authenticator lanes below.
+
 See the [unified-wallet](../../docs/docs/guides/unified-wallet.md) guide.
 
 ### Cross-VM message reads
@@ -377,6 +428,83 @@ const params = await client.crossvm.params();
 const status = await client.qor.getCrossVmMessage("42");
 ```
 
+## Authenticator lanes (v0.7.0 / chain v3.1.85)
+
+A linked external key — a Phantom **ed25519** key, or a MetaMask **secp256k1**
+key bound **by address** — can spend from the ONE canonical PQC account through
+a **relayer** that submits the tx and pays the fee (its own hybrid-PQC signature
+satisfies the ante). The external key **never produces an ML-DSA co-signature**;
+its signature over the domain-separated, replay-bound sign-bytes **is** the
+authorization. Every lane runs under least-privilege, spending-limit and
+revocable terms enforced on-chain.
+
+Three messages carry the lanes:
+
+| Message | Type URL | Composer |
+|---|---|---|
+| `MsgExecuteEVM` | `/qorechain.abstractaccount.v1.MsgExecuteEVM` | `msg.abstractaccount.executeEvm` |
+| `MsgExecuteCosmos` | `/qorechain.abstractaccount.v1.MsgExecuteCosmos` | `msg.abstractaccount.executeCosmos` |
+| `MsgRotatePQCKey` | `/qorechain.pqc.v1.MsgRotatePQCKey` | `msg.pqc.rotatePqcKey` |
+
+**Sign-bytes helpers** rebuild the exact digest the chain re-derives, so you can
+verify byte-for-byte before signing: `evmAuthSignBytes` / `cosmosAuthSignBytes`
+(32-byte SHA-256 digests) and `rotationSignBytes` (the domain-separated string
+both keys sign).
+
+**NONCE semantics:**
+
+- `MsgExecuteEVM.nonce` = the account's **current EVM nonce** (the relayer is a
+  different account than the owner, so its envelope does **not** bump the
+  account's nonce — pass the value as-is, do **not** `+1`).
+- `MsgExecuteCosmos.nonce` = the **per-authenticator sequence** for
+  `(account, pubkey)`, a store counter distinct from the account's own sequence.
+
+**Wallet builders** sign the digest and return a ready-to-broadcast message:
+`buildPhantomExecuteEvm` / `buildPhantomExecuteCosmos` (ed25519),
+`buildMetaMaskExecuteEvm` / `buildMetaMaskExecuteCosmos` (secp256k1-by-address),
+and `registerEthAuthenticatorMsg` to link an EVM key first.
+
+**Permission taxonomy & errors.** Query the on-chain permission schema with
+`client.query.getPermissionSchema()` (REST) / `client.grpc.permissionSchema()`
+(gRPC) and compare a candidate action against it before submitting. Failed lanes
+surface structured codes via `decodeTxError` — codespace `abstractaccount`: `5`
+SpendingLimitExceeded, `6` SessionKeyExpired, `10` PermissionDenied, `11`
+AuthenticatorReplay; codespace `pqc`: `21` HybridVerifyFailed.
+
+**Key rotation.** Migrate a legacy `shake256(mnemonic)` key to the canonical,
+address-bound key with `rotatePqcKeyMsgFromMnemonic` (dual-signs over
+`rotationSignBytes`); `derivePqcLegacy` re-derives the old key for the old-key
+half of the signature.
+
+```ts
+import {
+  buildPhantomExecuteEvm,
+  rotatePqcKeyMsgFromMnemonic,
+} from "@qorechain/sdk";
+
+// Phantom ed25519 authenticator spends from the canonical account; the relayer
+// broadcasts and pays. `nonce` is the account's CURRENT EVM nonce (no +1).
+const execMsg = await buildPhantomExecuteEvm({
+  wallet, // { publicKey, signMessage }
+  relayer: "qor1relayer…",
+  chainId: "qorechain-diana",
+  account: "qor1canonical…",
+  to: "0xRecipient…",
+  value: "1000000000000000000", // 1 QOR in aqor (wei)
+  nonce: await client.qor.getTransactionCount("0xAccount…"),
+});
+
+// One-shot: migrate a legacy shake256(mnemonic) key to the address-bound key.
+const { msg: rotateMsg } = rotatePqcKeyMsgFromMnemonic({
+  account: "qor1canonical…",
+  mnemonic,
+  chainId: "qorechain-diana",
+});
+```
+
+See the [Authenticators guide](../../docs/docs/guides/authenticators.md) for the
+full lifecycle (register → spend → rotate → revoke).
+
 ## Network reference
 
 - Mainnet chain id: `qorechain-vladi` (live).