quantumcoin 8.0.0 → 8.0.1

package/README-SDK.md

@@ -419,6 +419,8 @@ Core signing implementation.
 - `getAddress(): Promise<string>`
 - `signTransaction(tx: TransactionRequest): Promise<string>`
 - `sendTransaction(tx: TransactionRequest): Promise<TransactionResponse>`
+- `signMessageSync(message: string | Uint8Array, signingContext?: number | null): string` — signs an arbitrary message using the EIP-191 personal-message digest (see [Message signing](#message-signing-eip-191)). Returns an opaque post-quantum signature blob (0x hex) that embeds the signer's public key. The message may be at most 1 MiB once UTF-8 encoded (`INVALID_ARGUMENT` otherwise). Optional `signingContext`: omitted/`null` derives the compact context from the key type (`0` for keyType 3, `1` for keyType 5); `2` selects the full-signature scheme for a keyType 3 wallet.
+- `signMessage(message: string | Uint8Array, signingContext?: number | null): Promise<string>` — async wrapper over `signMessageSync` (honors the ethers `Signer` interface contract; the underlying signing is synchronous).
 
 ### `Wallet`
 
@@ -487,6 +489,38 @@ Address-only signer.
 - `new VoidSigner(address: string, provider?: AbstractProvider)`
 - `getAddress(): Promise<string>`
 
+### Message signing (EIP-191)
+
+Arbitrary-message signing and verification, adapted from ethers for
+QuantumCoin's post-quantum cryptography.
+
+- `Wallet.signMessage(message, signingContext?)` / `Wallet.signMessageSync(message, signingContext?)` — see [`BaseWallet`](#basewallet).
+- `hashMessage(message: string | Uint8Array): string` — the EIP-191 digest,
+  `keccak256("\x19Ethereum Signed Message:\n" + len + message)` (32 bytes). Same
+  prefix as Ethereum, so it matches `personal_sign` in `quantum-coin-go`. Strings
+  are UTF-8 encoded; the length prefix counts message **bytes**.
+- `verifyMessage(message: string | Uint8Array, signature: string | Uint8Array): string`
+  — **synchronous** (matches ethers; there is no `verifyMessageSync`). Returns the
+  recovered 32-byte signer address; throws `INVALID_ARGUMENT` if the signature is
+  malformed or does not verify.
+
+```js
+const { Wallet, verifyMessage } = require("quantumcoin");
+const wallet = Wallet.createRandom();
+const sig = await wallet.signMessage("Hello Joe");
+verifyMessage("Hello Joe", sig) === wallet.address; // true
+```
+
+**Key differences vs Ethereum**
+
+| Property | Ethereum | QuantumCoin |
+| --- | --- | --- |
+| Message prefix / hash | EIP-191 + keccak256 | Identical EIP-191 + keccak256 |
+| Signature | 65-byte `(r, s, v)` | Opaque multi-KB blob (scheme id byte + **embedded public key**) |
+| Address size | 20 bytes | 32 bytes |
+| Recovery | ECDSA `ecrecover` | Extract embedded public key + PQC verify (no `ecrecover`) |
+| `signTypedData` (EIP-712) | Supported | Not yet supported |
+
 ## Contracts
 
 ### `Contract`
@@ -679,6 +713,7 @@ const asOutput: Uint256 = 123n;
 - `sha512(data: BytesLike): string`
 - `ripemd160(data: BytesLike): string`
 - `id(text: string): string` (=`keccak256(utf8Bytes(text))`)
+- `hashMessage(message: BytesLike): string` — EIP-191 personal-message digest, `keccak256("\x19Ethereum Signed Message:\n" + len + message)`. See [Message signing](#message-signing-eip-191).
 - `randomBytes(length: number): Uint8Array`
 - `computeHmac(algorithm: string, key: BytesLike, data: BytesLike): string`
 - `pbkdf2(password: BytesLike, salt: BytesLike, iterations: number, keylen: number, algorithm?: string): string`

package/README.md

@@ -86,6 +86,52 @@ const restored = Wallet.fromEncryptedJsonSync(json, "mySecurePassword123");
 console.log(restored.address);
 ```
 
+## Message signing (EIP-191 / `personal_sign`)
+
+Sign and verify arbitrary messages using QuantumCoin's post-quantum keys. The
+message digest uses the exact same EIP-191 prefix as Ethereum
+(`keccak256("\x19Ethereum Signed Message:\n" + len + message)`), so it is
+byte-for-byte compatible with `personal_sign` in `quantum-coin-go`.
+
+```js
+const { Wallet, verifyMessage, hashMessage } = require("quantumcoin");
+const { Initialize } = require("quantumcoin/config");
+
+await Initialize(null);
+
+const wallet = Wallet.createRandom();
+
+// async (ethers Signer contract) or sync
+const signature = await wallet.signMessage("Hello Joe");
+const signatureSync = wallet.signMessageSync("Hello Joe");
+
+// verifyMessage is synchronous and returns the recovered signer address
+const signer = verifyMessage("Hello Joe", signature);
+console.log(signer === wallet.address); // true
+
+// The EIP-191 digest is available on its own if needed
+console.log(hashMessage("Hello Joe")); // 0x...32-byte hash
+```
+
+### Differences vs Ethereum
+
+- **Signature shape:** not a 65-byte `(r, s, v)` value. It is an opaque,
+  scheme-dependent multi-kilobyte hex blob whose first byte is the scheme id and
+  which **embeds the signer's public key**. There is no `Signature`/`r`/`s`/`v`
+  object.
+- **Address size:** recovered addresses are the full 32 bytes (66 hex chars).
+- **No `ecrecover`:** `verifyMessage` does not recover a key from `(digest, sig)`
+  cryptographically. It extracts the embedded public key, verifies it against the
+  digest, and returns its address; a signature that fails verification throws.
+- **Signing context:** `signMessage`/`signMessageSync` accept an optional
+  `signingContext`. When omitted it derives the compact context from the key type
+  (`0` for keyType 3, `1` for keyType 5); pass `2` to request the full-signature
+  scheme for a keyType 3 wallet.
+- **Message size:** the message must be at most 1 MiB (once UTF-8 encoded);
+  larger inputs throw `INVALID_ARGUMENT`. The message is only ever hashed to a
+  32-byte digest, so there is no need for larger payloads.
+- **EIP-712 (`signTypedData`)** is not yet supported.
+
 ## Contracts (read-only)
 
 ```js
@@ -156,6 +202,7 @@ Common types:
 ```bash
 npm run example
 npm run example:wallet
+npm run example:sign-message
 npm run example:contract:read
 npm run example:events
 # Run all examples (including SDK generator JS/TS)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quantumcoin",
-  "version": "8.0.0",
+  "version": "8.0.1",
   "description": "QuantumCoin.js - a post quantum cryptography SDK for QuantumCoin",
   "main": "index.js",
   "types": "src/index.d.ts",
@@ -59,12 +59,14 @@
     "example:events:ts": "npx tsx examples/events.ts",
     "example:offline-signing": "node examples/offline-signing.js",
     "example:offline-signing:ts": "npx tsx examples/offline-signing.ts",
+    "example:sign-message": "node examples/sign-message.js",
+    "example:sign-message:ts": "npx tsx examples/sign-message.ts",
     "example:generator-js": "node examples/example-generator-sdk-js.js",
     "example:generator-js:ts": "npx tsx examples/example-generator-sdk-js.ts",
     "example:generator-ts": "node examples/example-generator-sdk-ts.js",
     "example:generator-ts:ts": "npx tsx examples/example-generator-sdk-ts.ts",
-    "examples": "node examples/example.js && node examples/wallet-offline.js && node examples/read-operations.js && node examples/events.js && node examples/example-generator-sdk-js.js && node examples/example-generator-sdk-ts.js",
-    "examples:ts": "npx tsx examples/example.ts && npx tsx examples/wallet-offline.ts && npx tsx examples/read-operations.ts && npx tsx examples/events.ts && npx tsx examples/example-generator-sdk-js.ts && npx tsx examples/example-generator-sdk-ts.ts",
+    "examples": "node examples/example.js && node examples/wallet-offline.js && node examples/sign-message.js && node examples/read-operations.js && node examples/events.js && node examples/example-generator-sdk-js.js && node examples/example-generator-sdk-ts.js",
+    "examples:ts": "npx tsx examples/example.ts && npx tsx examples/wallet-offline.ts && npx tsx examples/sign-message.ts && npx tsx examples/read-operations.ts && npx tsx examples/events.ts && npx tsx examples/example-generator-sdk-js.ts && npx tsx examples/example-generator-sdk-ts.ts",
     "build": "npx -p typescript tsc -p tsconfig.build.json && node scripts/copy-declarations.js"
   },
   "repository": {

package/src/index.d.ts

@@ -29,6 +29,7 @@ declare const _exports: {
     sha512(data: string | Uint8Array): string;
     ripemd160(data: string | Uint8Array): string;
     id(text: string): string;
+    hashMessage(message: string | Uint8Array): string;
     randomBytes(length: number): Uint8Array;
     computeHmac(algorithm: string, key: string | Uint8Array, data: string | Uint8Array): string;
     pbkdf2(password: string | Uint8Array, salt: string | Uint8Array, iterations: number, keylen: number, algorithm?: string | undefined): string;
@@ -88,6 +89,7 @@ declare const _exports: {
     ContractTransactionResponse: typeof import("./contract/contract").ContractTransactionResponse;
     ContractTransactionReceipt: typeof import("./contract/contract").ContractTransactionReceipt;
     EventLog: typeof import("./contract/contract").EventLog;
+    verifyMessage(message: string | Uint8Array, signature: string | Uint8Array): string;
     SigningKey: typeof import("./wallet/wallet").SigningKey;
     AbstractSigner: typeof import("./wallet/wallet").AbstractSigner;
     BaseWallet: typeof import("./wallet/wallet").BaseWallet;

package/src/utils/hashing.d.ts

@@ -28,6 +28,24 @@ export function ripemd160(data: string | Uint8Array): string;
  * @returns {string}
  */
 export function id(text: string): string;
+/**
+ * Compute the EIP-191 "personal message" digest for a message.
+ *
+ * QuantumCoin uses the exact same prefix as Ethereum, so this is byte-for-byte
+ * compatible with `personal_sign` in `quantum-coin-go`:
+ *
+ *   keccak256("\x19Ethereum Signed Message:\n" + message.length + message)
+ *
+ * The resulting 32-byte hash is the digest passed to `Wallet.signMessage` /
+ * `Wallet.signMessageSync` and re-derived by `verifyMessage`. The decimal length
+ * prefix counts message BYTES, not characters. A string message is UTF-8
+ * encoded; a Uint8Array (or 0x hex string coerced via `arrayify`) is treated as
+ * raw bytes.
+ *
+ * @param {string|Uint8Array} message The message to hash. Strings are UTF-8 encoded.
+ * @returns {string} 0x-prefixed, 32-byte keccak256 digest.
+ */
+export function hashMessage(message: string | Uint8Array): string;
 /**
  * Generate cryptographically strong random bytes.
  *

package/src/utils/hashing.js

@@ -89,6 +89,32 @@ function id(text) {
   return keccak256(utf8ToBytes(text));
 }
 
+/**
+ * Compute the EIP-191 "personal message" digest for a message.
+ *
+ * QuantumCoin uses the exact same prefix as Ethereum, so this is byte-for-byte
+ * compatible with `personal_sign` in `quantum-coin-go`:
+ *
+ *   keccak256("\x19Ethereum Signed Message:\n" + message.length + message)
+ *
+ * The resulting 32-byte hash is the digest passed to `Wallet.signMessage` /
+ * `Wallet.signMessageSync` and re-derived by `verifyMessage`. The decimal length
+ * prefix counts message BYTES, not characters. A string message is UTF-8
+ * encoded; a Uint8Array (or 0x hex string coerced via `arrayify`) is treated as
+ * raw bytes.
+ *
+ * @param {string|Uint8Array} message The message to hash. Strings are UTF-8 encoded.
+ * @returns {string} 0x-prefixed, 32-byte keccak256 digest.
+ */
+function hashMessage(message) {
+  const msgBytes = typeof message === "string" ? utf8ToBytes(message) : arrayify(message);
+  const prefix = utf8ToBytes(`\x19Ethereum Signed Message:\n${msgBytes.length}`);
+  const composed = new Uint8Array(prefix.length + msgBytes.length);
+  composed.set(prefix, 0);
+  composed.set(msgBytes, prefix.length);
+  return keccak256(composed);
+}
+
 /**
  * Generate cryptographically strong random bytes.
  *
@@ -181,6 +207,7 @@ module.exports = {
   sha512,
   ripemd160,
   id,
+  hashMessage,
   randomBytes,
   computeHmac,
   pbkdf2,

package/src/utils/index.d.ts

@@ -17,6 +17,7 @@ declare const _exports: {
     sha512(data: string | Uint8Array): string;
     ripemd160(data: string | Uint8Array): string;
     id(text: string): string;
+    hashMessage(message: string | Uint8Array): string;
     randomBytes(length: number): Uint8Array;
     computeHmac(algorithm: string, key: string | Uint8Array, data: string | Uint8Array): string;
     pbkdf2(password: string | Uint8Array, salt: string | Uint8Array, iterations: number, keylen: number, algorithm?: string | undefined): string;

package/src/wallet/index.d.ts

@@ -1,4 +1,5 @@
 declare const _exports: {
+    verifyMessage(message: string | Uint8Array, signature: string | Uint8Array): string;
     SigningKey: typeof import("./wallet").SigningKey;
     AbstractSigner: typeof import("./wallet").AbstractSigner;
     BaseWallet: typeof import("./wallet").BaseWallet;

package/src/wallet/wallet.d.ts

@@ -51,6 +51,24 @@ export class BaseWallet extends AbstractSigner {
      * @returns {Promise<string>}
      */
     signTransaction(tx: import("../providers/provider").TransactionRequest): Promise<string>;
+    /**
+     * Sign an arbitrary message (EIP-191 personal-message scheme), synchronously.
+     * Returns an opaque post-quantum signature blob (0x hex) that embeds the
+     * signer's public key. Optional signingContext: when omitted/null the compact
+     * context is derived from the key type (0 for keyType 3, 1 for keyType 5);
+     * pass 2 for the full-signature scheme on a keyType 3 wallet.
+     * @param {string|Uint8Array} message
+     * @param {number|null=} signingContext
+     * @returns {string}
+     */
+    signMessageSync(message: string | Uint8Array, signingContext?: (number | null) | undefined): string;
+    /**
+     * Sign an arbitrary message (EIP-191). Async wrapper over signMessageSync.
+     * @param {string|Uint8Array} message
+     * @param {number|null=} signingContext
+     * @returns {Promise<string>}
+     */
+    signMessage(message: string | Uint8Array, signingContext?: (number | null) | undefined): Promise<string>;
     /**
      * Internal: sign a transaction and return both the raw serialized transaction
      * and the signer-computed transaction hash. The hash is later used to
@@ -225,3 +243,16 @@ export class VoidSigner extends AbstractSigner {
     _address: string;
     getAddress(): Promise<string>;
 }
+/**
+ * Recover the signer's 32-byte address from an EIP-191 message signature.
+ *
+ * QuantumCoin has no ECDSA ecrecover; the post-quantum signature embeds the
+ * public key, which is extracted and verified against the message digest before
+ * the address is returned. Throws INVALID_ARGUMENT if the signature is malformed
+ * or does not verify. Synchronous, matching ethers' verifyMessage.
+ *
+ * @param {string|Uint8Array} message The original message (strings are UTF-8 encoded).
+ * @param {string|Uint8Array} signature The signature produced by signMessage.
+ * @returns {string} 0x-prefixed 32-byte signer address.
+ */
+export function verifyMessage(message: string | Uint8Array, signature: string | Uint8Array): string;

package/src/wallet/wallet.js

@@ -12,8 +12,9 @@ const qcsdk = require("quantum-coin-js-sdk");
 const seedWords = require("seed-words");
 const { JsonRpcProvider } = require("../providers/json-rpc-provider");
 const { assertArgument, assertSecretArgument, makeError } = require("../errors");
-const { arrayify, bytesToHex, bytesToUtf8, hexToBytes, isHexString, normalizeHex } = require("../internal/hex");
-const { getAddress } = require("../utils/address");
+const { arrayify, bytesToHex, bytesToUtf8, hexToBytes, isHexString, normalizeHex, utf8ToBytes } = require("../internal/hex");
+const { computeAddress, getAddress } = require("../utils/address");
+const { hashMessage } = require("../utils/hashing");
 const { WeiPerEther } = require("../constants");
 
 function _requireInitialized() {
@@ -34,6 +35,13 @@ function _bytesToNumberArray(bytes) {
   return Array.from(bytes);
 }
 
+// Upper bound on the message size accepted by signMessage/signMessageSync. The
+// message is only ever hashed to a 32-byte digest, so there is no protocol need
+// for large inputs; this cap is a guardrail against accidentally signing an
+// unbounded buffer (e.g. a whole file passed in by mistake). 1 MiB is far larger
+// than any realistic personal_sign payload.
+const MAX_MESSAGE_BYTES = 1024 * 1024;
+
 /**
  * Verify that a private/public key pair is internally consistent (the public
  * key really corresponds to the private key). Constructing a wallet from a
@@ -214,6 +222,74 @@ class BaseWallet extends AbstractSigner {
     return raw;
   }
 
+  /**
+   * Sign an arbitrary message using QuantumCoin's EIP-191 personal-message
+   * scheme, synchronously.
+   *
+   * The message is hashed with {@link hashMessage} (the same
+   * `keccak256("\x19Ethereum Signed Message:\n" + len + message)` digest used by
+   * `personal_sign` in quantum-coin-go), producing a 32-byte digest that is then
+   * signed with the wallet's post-quantum key.
+   *
+   * Unlike Ethereum's 65-byte `(r, s, v)` signature, the returned value is an
+   * opaque, scheme-dependent multi-kilobyte blob whose first byte is the scheme
+   * id and which EMBEDS the signer's public key. This is what allows
+   * {@link verifyMessage} to recover the signer address without an ecrecover
+   * primitive.
+   *
+   * @param {string|Uint8Array} message The message to sign (strings are UTF-8 encoded).
+   *   Must be at most {@link MAX_MESSAGE_BYTES} (1 MiB) once UTF-8 encoded.
+   * @param {number|null=} signingContext Optional signing context. When omitted or
+   *   null, `quantum-coin-js-sdk` derives the compact context from the key type
+   *   (0 for keyType 3, 1 for keyType 5); pass 2 to request the full-signature
+   *   scheme for a keyType 3 wallet.
+   * @returns {string} 0x-prefixed signature blob (public key embedded).
+   * @throws {TypeError} INVALID_ARGUMENT if the message exceeds the size limit.
+   */
+  signMessageSync(message, signingContext) {
+    _requireInitialized();
+    const msgBytes = typeof message === "string" ? utf8ToBytes(message) : arrayify(message);
+    assertArgument(
+      msgBytes.length <= MAX_MESSAGE_BYTES,
+      `message too long (max ${MAX_MESSAGE_BYTES} bytes)`,
+      "message",
+      msgBytes.length,
+    );
+    const digestArr = _bytesToNumberArray(hexToBytes(hashMessage(msgBytes)));
+    const privArr = _bytesToNumberArray(this.signingKey.privateKeyBytes);
+    const pubArr = _bytesToNumberArray(this.signingKey.publicKeyBytes);
+    const ctx = signingContext == null ? null : signingContext;
+    const res = qcsdk.sign(privArr, digestArr, ctx);
+    if (!res || typeof res !== "object" || res.resultCode !== 0 || res.signature == null) {
+      throw makeError("signMessage failed", "UNKNOWN_ERROR", {
+        resultCode: res && typeof res === "object" ? res.resultCode : null,
+      });
+    }
+    // qcsdk.sign returns the signature-only bytes. Combine the public key into
+    // the blob (sig + pubKey) so the result is self-describing and verifyMessage
+    // can recover the signer without a separately supplied public key.
+    const sigArr = Array.from(res.signature);
+    const combined = qcsdk.combinePublicKeySignature(pubArr, sigArr);
+    if (typeof combined !== "string") {
+      throw makeError("signMessage failed to combine public key with signature", "UNKNOWN_ERROR", {});
+    }
+    return normalizeHex(combined);
+  }
+
+  /**
+   * Sign an arbitrary message (EIP-191). Async wrapper over
+   * {@link BaseWallet#signMessageSync} that honors the ethers `Signer` interface
+   * contract (`Signer.signMessage` is async); the underlying PQC signing is
+   * synchronous.
+   *
+   * @param {string|Uint8Array} message The message to sign (strings are UTF-8 encoded).
+   * @param {number|null=} signingContext Optional signing context (see signMessageSync).
+   * @returns {Promise<string>} 0x-prefixed signature blob (public key embedded).
+   */
+  async signMessage(message, signingContext) {
+    return this.signMessageSync(message, signingContext);
+  }
+
   /**
    * Internal: sign a transaction and return both the raw serialized transaction
    * and the signer-computed transaction hash. The hash is later used to
@@ -739,6 +815,39 @@ class VoidSigner extends AbstractSigner {
   }
 }
 
+/**
+ * Recover the signer's 32-byte address from an EIP-191 message signature.
+ *
+ * QuantumCoin has no ECDSA `ecrecover`: signatures are opaque post-quantum blobs
+ * that embed the signer's public key. This function re-derives the EIP-191
+ * digest with {@link hashMessage}, extracts and cryptographically verifies the
+ * embedded public key against that digest via
+ * `quantum-coin-js-sdk.publicKeyFromSignature`, and returns the corresponding
+ * 32-byte address. If the signature does not verify there is nothing to recover,
+ * so the function throws.
+ *
+ * Synchronous, matching ethers' `verifyMessage` (there is no async variant).
+ *
+ * @param {string|Uint8Array} message The original message (strings are UTF-8 encoded).
+ * @param {string|Uint8Array} signature The signature produced by `signMessage`.
+ * @returns {string} 0x-prefixed 32-byte signer address.
+ * @throws {TypeError} INVALID_ARGUMENT if the signature is malformed or does not verify.
+ */
+function verifyMessage(message, signature) {
+  _requireInitialized();
+  const digestHex = hashMessage(message);
+  const digestArr = _bytesToNumberArray(hexToBytes(digestHex));
+  const sigArr = _bytesToNumberArray(arrayify(signature));
+  const pubHex = qcsdk.publicKeyFromSignature(digestArr, sigArr);
+  if (typeof pubHex !== "string") {
+    throw makeError("verifyMessage failed: signature did not verify", "INVALID_ARGUMENT", {
+      argument: "signature",
+      value: "[signature]",
+    });
+  }
+  return computeAddress(pubHex);
+}
+
 module.exports = {
   SigningKey,
   AbstractSigner,
@@ -747,5 +856,6 @@ module.exports = {
   NonceManager,
   JsonRpcSigner,
   VoidSigner,
+  verifyMessage,
 };