quantumcoin 8.0.0 → 8.0.2

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`
@@ -576,24 +610,91 @@ ABI encoding/decoding compatibility layer.
 
 - `new Interface(abi: any[] | Interface | null)`
 
-**Methods**
+**Fragment lookup** — each accepts a bare name, a canonical signature
+(`name(type,...)`), or a hex identifier, mirroring ethers.js v6:
+- `getFunction(nameOrSignatureOrSelector: string): FunctionFragment`
+  - Resolves by name, `transfer(address,uint256)`, or 4-byte selector `0xa9059cbb`.
+  - Throws `INVALID_ARGUMENT` when unresolved or when a bare name is ambiguous
+    across overloads (pass the full signature instead).
+- `getEvent(nameOrSignatureOrTopic: string): EventFragment`
+  - Resolves by name, signature, or topic0 (`0x` + 64 hex).
+- `getError(nameOrSignatureOrSelector: string): ErrorFragment`
+  - Resolves by name, signature, or 4-byte selector.
+- `getConstructor(): ConstructorFragment | null`
+- `getSighash(fragmentOrName): string` — 4-byte function selector.
 - `formatJson(): string`
 - `format(format?: string | null): string`
-- `getFunction(name: string): FunctionFragment`
-- `getEvent(name: string): EventFragment`
-- `getError(name: string): ErrorFragment`
-- `getConstructor(): ConstructorFragment | null`
 
-**Encoding**
+`FunctionFragment` / `ErrorFragment` expose a `selector` getter and
+`EventFragment` a `topicHash` getter (both require `Initialize()`).
+
+**Encoding / decoding**
 - `encodeFunctionData(functionFragmentOrName, values?: any[] | null): string`
+- `decodeFunctionData(functionFragmentOrName, data: string): Result` — decode a
+  call's arguments (selector + args). The data's selector must match the resolved
+  function, otherwise it throws `INVALID_ARGUMENT`. `encodeFunctionData(fragment,
+  decodeFunctionData(fragment, data))` reproduces `data` byte-for-byte.
 - `decodeFunctionResult(functionFragmentOrName, data: string): any`
+- `encodeDeploy(values?: any[]): string` — ABI-encode constructor arguments (no
+  selector), or `"0x"` when the constructor takes no arguments. Append to the
+  creation bytecode for a deployment.
 - `encodeEventLog(eventFragmentOrName, values?: any[] | null): { topics: string[], data: string }`
 - `decodeEventLog(eventFragmentOrName, topics: string[], data: string): any`
 
 **Parsing**
+- `parseTransaction(tx: { data: string, value?: BigNumberish }): { fragment, name, signature, selector, args: Result, value: bigint }`
+  - Resolves the function by the 4-byte selector in `tx.data`, decodes the
+    arguments from the real bytes, and reports `value` as a `bigint`.
+- `parseError(data: string): { fragment, name, signature, selector, args: Result }`
+  - Resolves a custom error by its 4-byte selector and decodes its arguments.
 - `parseLog(log: { topics: string[], data: string }): { fragment, name, signature, topic, args }`
   - Uses signature topic matching and `decodeEventLog(...)`
 
+> **32-byte addresses:** QuantumCoin addresses are 32 bytes and occupy a full ABI
+> word, whereas Ethereum left-pads a 20-byte address. Canonical signatures are
+> identical strings, so keccak-derived selectors and event topics match Ethereum
+> exactly (e.g. `transfer(address,uint256)` → `0xa9059cbb`); only the contents of
+> an address-bearing calldata word differ.
+
+**Example (JS):**
+
+```js
+const { Initialize } = require("quantumcoin/config");
+const { Interface } = require("quantumcoin");
+
+await Initialize(null);
+const iface = new Interface([
+  { type: "function", name: "transfer",
+    inputs: [{ name: "to", type: "address" }, { name: "amount", type: "uint256" }],
+    outputs: [{ type: "bool" }] },
+]);
+
+const to = "0x" + "ab".repeat(32); // 32-byte address
+const data = iface.encodeFunctionData("transfer", [to, 1000n]);
+
+const tx = iface.parseTransaction({ data, value: "0x0" });
+console.log(tx.name, tx.signature, tx.selector); // transfer transfer(address,uint256) 0xa9059cbb
+console.log(tx.args.to, tx.args.amount);          // <to> 1000n
+
+// "What you see is what you sign": re-encode the decoded args and compare.
+const ok = iface.encodeFunctionData(tx.fragment, Array.from(tx.args)) === data; // true
+```
+
+**Example (TS):**
+
+```ts
+import { Initialize } from "quantumcoin/config";
+import qc from "quantumcoin";
+
+await Initialize(null);
+const iface = new qc.Interface([
+  { type: "error", name: "InsufficientBalance",
+    inputs: [{ name: "have", type: "uint256" }, { name: "want", type: "uint256" }] },
+]);
+const selector: string = iface.getError("InsufficientBalance").selector;
+// const desc = iface.parseError(revertData); // { name, args: { have, want }, ... }
+```
+
 ### `AbiCoder`
 
 Minimal ABI coder for encoding/decoding tuples of values.
@@ -601,6 +702,8 @@ Minimal ABI coder for encoding/decoding tuples of values.
 - `encode(types: (string|any)[], values: any[]): string`
 - `decode(types: (string|any)[], data: string): any`
 - `getDefaultValue(types: (string|any)[]): any`
+- `static defaultAbiCoder(): AbiCoder` — shared singleton instance (ethers.js v6
+  shape): `AbiCoder.defaultAbiCoder().encode(["uint256"], [1n])`.
 
 ## Utilities
 
@@ -679,6 +782,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
@@ -102,6 +148,48 @@ const staking = new Contract(address, abi, provider);
 console.log(await staking.getDepositorCount());
 ```
 
+## ABI encoding & decoding
+
+`Interface` and `AbiCoder` provide ethers.js v6-compatible ABI handling. Beyond
+encoding, you can resolve fragments by name, canonical signature, or hex
+identifier, and decode/parse raw calldata — useful for a strict "what you see is
+what you sign" verification (decode the real bytes, then re-encode and compare).
+
+```js
+const { Initialize } = require("quantumcoin/config");
+const { Interface, AbiCoder } = require("quantumcoin");
+
+await Initialize(null);
+const iface = new Interface([
+  { type: "function", name: "transfer",
+    inputs: [{ name: "to", type: "address" }, { name: "amount", type: "uint256" }],
+    outputs: [{ type: "bool" }] },
+]);
+
+const to = "0x" + "ab".repeat(32);           // 32-byte QuantumCoin address
+const data = iface.encodeFunctionData("transfer", [to, 1000n]);
+
+const tx = iface.parseTransaction({ data }); // resolves by selector, decodes args
+// tx.name === "transfer", tx.selector === "0xa9059cbb", tx.args.amount === 1000n
+
+// Re-encode the decoded args and confirm they reproduce the original calldata.
+const verified = iface.encodeFunctionData(tx.fragment, Array.from(tx.args)) === data;
+
+const coder = AbiCoder.defaultAbiCoder();
+coder.encode(["uint256"], [1n]);
+```
+
+Highlights: `getFunction`/`getError` (by name, signature, or 4-byte selector),
+`getEvent` (by name, signature, or topic0), `decodeFunctionData`,
+`parseTransaction`, `parseError`, `getSighash`, `FunctionFragment.selector`,
+`EventFragment.topicHash`, `Interface.encodeDeploy`, and
+`AbiCoder.defaultAbiCoder()`.
+
+> QuantumCoin addresses are 32 bytes and fill a full ABI word (Ethereum left-pads
+> a 20-byte address). Canonical signatures are identical, so selectors and event
+> topics match Ethereum exactly; only address-bearing calldata words differ. See
+> [README-SDK.md](./README-SDK.md#interface) for the full API.
+
 ## Typed contract generator
 
 This repo includes a generator described in `SPEC.md` section 15.
@@ -156,6 +244,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.2",
   "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/abi/fragments.d.ts

@@ -29,10 +29,28 @@ export class Fragment {
 export class NamedFragment extends Fragment {
 }
 export class FunctionFragment extends NamedFragment {
+    /**
+     * The 4-byte function selector (sighash), e.g. "0xa9059cbb". Requires the SDK
+     * to be initialized (uses keccak256). Mirrors ethers.js v6.
+     * @returns {string}
+     */
+    get selector(): string;
 }
 export class EventFragment extends NamedFragment {
+    /**
+     * The event topic hash (topic0). Requires the SDK to be initialized (uses
+     * keccak256). Mirrors ethers.js v6.
+     * @returns {string}
+     */
+    get topicHash(): string;
 }
 export class ErrorFragment extends NamedFragment {
+    /**
+     * The 4-byte error selector. Requires the SDK to be initialized (uses
+     * keccak256). Mirrors ethers.js v6.
+     * @returns {string}
+     */
+    get selector(): string;
 }
 export class ConstructorFragment extends Fragment {
 }

package/src/abi/fragments.js

@@ -43,9 +43,52 @@ class Fragment {
 }
 
 class NamedFragment extends Fragment {}
-class FunctionFragment extends NamedFragment {}
-class EventFragment extends NamedFragment {}
-class ErrorFragment extends NamedFragment {}
+
+class FunctionFragment extends NamedFragment {
+  /**
+   * The 4-byte function selector (sighash), e.g. "0xa9059cbb". Requires the SDK
+   * to be initialized (uses keccak256). Mirrors ethers.js v6.
+   * @returns {string}
+   */
+  get selector() {
+    // Lazy require to keep fragment construction dependency-free.
+    // eslint-disable-next-line global-require
+    const { functionSelectorHex } = require("./js-abi-coder");
+    return functionSelectorHex(this.name, Array.isArray(this.inputs) ? this.inputs : []);
+  }
+}
+
+class EventFragment extends NamedFragment {
+  /**
+   * The event topic hash (topic0). Requires the SDK to be initialized (uses
+   * keccak256). Mirrors ethers.js v6.
+   * @returns {string}
+   */
+  get topicHash() {
+    // eslint-disable-next-line global-require
+    const { canonicalType } = require("./js-abi-coder");
+    // eslint-disable-next-line global-require
+    const { id } = require("../utils/hashing");
+    // eslint-disable-next-line global-require
+    const { normalizeHex } = require("../internal/hex");
+    const inputs = Array.isArray(this.inputs) ? this.inputs : [];
+    return normalizeHex(id(`${this.name}(${inputs.map((i) => canonicalType(i)).join(",")})`));
+  }
+}
+
+class ErrorFragment extends NamedFragment {
+  /**
+   * The 4-byte error selector. Requires the SDK to be initialized (uses
+   * keccak256). Mirrors ethers.js v6.
+   * @returns {string}
+   */
+  get selector() {
+    // eslint-disable-next-line global-require
+    const { functionSelectorHex } = require("./js-abi-coder");
+    return functionSelectorHex(this.name, Array.isArray(this.inputs) ? this.inputs : []);
+  }
+}
+
 class ConstructorFragment extends Fragment {}
 class StructFragment extends Fragment {}
 class FallbackFragment extends Fragment {}

package/src/abi/interface.d.ts

@@ -31,23 +31,26 @@ export class Interface {
      */
     format(format?: string | undefined): string;
     /**
-     * Get a function fragment by name (first match).
-     * @param {string} nameOrSignature
+     * Get a function fragment by bare name, canonical signature
+     * (`name(type,...)`), or 4-byte selector (`0x` + 8 hex). Mirrors ethers.js v6.
+     * @param {string} nameOrSignatureOrSelector
      * @returns {FunctionFragment}
      */
-    getFunction(nameOrSignature: string): FunctionFragment;
+    getFunction(nameOrSignatureOrSelector: string): FunctionFragment;
     /**
-     * Get an event fragment by name (first match).
-     * @param {string} nameOrSignature
+     * Get an event fragment by bare name, canonical signature, or topic0
+     * (`0x` + 64 hex). Mirrors ethers.js v6.
+     * @param {string} nameOrSignatureOrTopic
      * @returns {EventFragment}
      */
-    getEvent(nameOrSignature: string): EventFragment;
+    getEvent(nameOrSignatureOrTopic: string): EventFragment;
     /**
-     * Get an error fragment by name (first match).
-     * @param {string} nameOrSignature
+     * Get an error fragment by bare name, canonical signature, or 4-byte selector.
+     * Mirrors ethers.js v6.
+     * @param {string} nameOrSignatureOrSelector
      * @returns {ErrorFragment}
      */
-    getError(nameOrSignature: string): ErrorFragment;
+    getError(nameOrSignatureOrSelector: string): ErrorFragment;
     /**
      * Returns the constructor fragment if present.
      * @returns {ConstructorFragment|null}
@@ -60,6 +63,23 @@ export class Interface {
      * @returns {string}
      */
     encodeFunctionData(functionFragment: FunctionFragment | string, values: any[]): string;
+    /**
+     * Encode ABI constructor arguments for a contract deployment (no selector).
+     * Returns "0x" when the constructor takes no arguments. The caller appends
+     * this to the creation bytecode. Mirrors ethers.js v6.
+     * @param {any[]=} values
+     * @returns {string}
+     */
+    encodeDeploy(values?: any[] | undefined): string;
+    /**
+     * Decode the calldata of a function call (4-byte selector + ABI-encoded
+     * arguments), returning the decoded input arguments as a Result. The data's
+     * selector must match the resolved function. Mirrors ethers.js v6.
+     * @param {FunctionFragment|string} fragment
+     * @param {string} data
+     * @returns {Result}
+     */
+    decodeFunctionData(fragment: FunctionFragment | string, data: string): Result;
     /**
      * Decode function result using quantum-coin-js-sdk.
      * @param {FunctionFragment|string} functionFragment
@@ -85,7 +105,25 @@ export class Interface {
      * @returns {any}
      */
     decodeEventLog(eventFragment: EventFragment | any, topics: string[], data: string): any;
-    parseTransaction(): void;
+    /**
+     * Parse a transaction's calldata into its function + decoded arguments.
+     * Resolves the function by the 4-byte selector in `tx.data`, decodes the
+     * arguments from the real bytes, and reports `value` as a bigint. Mirrors
+     * ethers.js v6 (returns a TransactionDescription-shaped object).
+     * @param {{ data: string, value?: any }} tx
+     * @returns {{ fragment: FunctionFragment, name: string, signature: string, selector: string, args: Result, value: bigint }}
+     */
+    parseTransaction(tx: {
+        data: string;
+        value?: any;
+    }): {
+        fragment: FunctionFragment;
+        name: string;
+        signature: string;
+        selector: string;
+        args: Result;
+        value: bigint;
+    };
     parseLog(...args: any[]): {
         fragment: EventFragment;
         name: any;
@@ -93,8 +131,27 @@ export class Interface {
         topic: string;
         args: Result;
     };
-    parseError(): void;
-    getSighash(): void;
+    /**
+     * Parse custom-error return data into its error fragment + decoded arguments.
+     * Resolves the error by the 4-byte selector in `data`. Mirrors ethers.js v6
+     * (returns an ErrorDescription-shaped object).
+     * @param {string} data
+     * @returns {{ fragment: ErrorFragment, name: string, signature: string, selector: string, args: Result }}
+     */
+    parseError(data: string): {
+        fragment: ErrorFragment;
+        name: string;
+        signature: string;
+        selector: string;
+        args: Result;
+    };
+    /**
+     * Return the 4-byte function selector (sighash) for a function fragment or
+     * name. Mirrors ethers.js v5 getSighash / v6 FunctionFragment.selector.
+     * @param {FunctionFragment|string} fragmentOrName
+     * @returns {string}
+     */
+    getSighash(fragmentOrName: FunctionFragment | string): string;
     /**
      * Compute the topic0 (event signature hash) for an event.
      * @param {string|EventFragment|any} nameOrFragment
@@ -105,6 +162,11 @@ export class Interface {
     getReceive(): null;
 }
 export class AbiCoder {
+    /**
+     * Return the shared default AbiCoder instance (ethers.js v6 shape).
+     * @returns {AbiCoder}
+     */
+    static defaultAbiCoder(): AbiCoder;
     /**
      * Encode values by types into ABI data.
      * @param {(string|any)[]} types

package/src/abi/interface.js

@@ -8,12 +8,45 @@
 
 const qcsdk = require("quantum-coin-js-sdk");
 const { makeError, assertArgument } = require("../errors");
-const { normalizeHex, arrayify, bytesToHex } = require("../internal/hex");
+const { normalizeHex, arrayify, bytesToHex, isHexString } = require("../internal/hex");
 const { EventFragment, FunctionFragment, ErrorFragment, ConstructorFragment } = require("./fragments");
 const { Result } = require("../utils/result");
 const { id } = require("../utils/hashing");
 const jsAbi = require("./js-abi-coder");
 
+// Remove all whitespace (used to normalize a caller-supplied canonical signature
+// like "transfer(address, uint256)" before comparing against the ABI).
+function _stripWhitespace(s) {
+  return String(s).replace(/\s+/g, "");
+}
+
+// Canonical Solidity signature for a fragment, e.g. "transfer(address,uint256)".
+// Tuples/arrays are expanded via the shared js-abi-coder canonicalizer so it
+// matches the selector/topic hashing used everywhere else.
+function _canonicalSignature(frag) {
+  const inputs = Array.isArray(frag.inputs) ? frag.inputs : [];
+  return `${frag.name}(${inputs.map((i) => jsAbi.canonicalType(i)).join(",")})`;
+}
+
+// 0x + 8 hex => a 4-byte function/error selector.
+function _isSelectorHex(s) {
+  return typeof s === "string" && /^0x[0-9a-fA-F]{8}$/.test(s.trim());
+}
+
+// 0x + 64 hex => a 32-byte event topic (topic0).
+function _isTopicHex(s) {
+  return typeof s === "string" && /^0x[0-9a-fA-F]{64}$/.test(s.trim());
+}
+
+// Resolve a function fragment for decode/encode. A fragment object (e.g. the one
+// returned by parseTransaction/getFunction) is used AS-IS so an overloaded name
+// is never re-resolved ambiguously; a string resolves through the ABI.
+function _resolveFunctionFragment(iface, fragment) {
+  if (fragment instanceof FunctionFragment) return fragment;
+  if (fragment && typeof fragment === "object" && fragment.name) return new FunctionFragment(fragment);
+  return iface.getFunction(fragment);
+}
+
 function _requireInitialized() {
   // eslint-disable-next-line global-require
   const { isInitialized, getInitializationPromise } = require("../../config");
@@ -289,39 +322,96 @@ class Interface {
   }
 
   /**
-   * Get a function fragment by name (first match).
-   * @param {string} nameOrSignature
+   * Get a function fragment by bare name, canonical signature
+   * (`name(type,...)`), or 4-byte selector (`0x` + 8 hex). Mirrors ethers.js v6.
+   * @param {string} nameOrSignatureOrSelector
    * @returns {FunctionFragment}
    */
-  getFunction(nameOrSignature) {
-    assertArgument(typeof nameOrSignature === "string", "name must be a string", "nameOrSignature", nameOrSignature);
-    const found = this.abi.find((f) => f && f.type === "function" && f.name === nameOrSignature);
-    if (!found) throw makeError("function not found", "INVALID_ARGUMENT", { nameOrSignature });
-    return new FunctionFragment(found);
+  getFunction(nameOrSignatureOrSelector) {
+    assertArgument(typeof nameOrSignatureOrSelector === "string", "name must be a string", "nameOrSignatureOrSelector", nameOrSignatureOrSelector);
+    const key = nameOrSignatureOrSelector.trim();
+    const fns = this.abi.filter((f) => f && f.type === "function" && f.name);
+
+    if (_isSelectorHex(key)) {
+      const sel = normalizeHex(key).toLowerCase();
+      const found = fns.find((f) => jsAbi.functionSelectorHex(f.name, f.inputs || []).toLowerCase() === sel);
+      if (!found) throw makeError("no matching function for selector", "INVALID_ARGUMENT", { selector: key });
+      return new FunctionFragment(found);
+    }
+
+    if (key.indexOf("(") >= 0) {
+      const norm = _stripWhitespace(key);
+      const found = fns.find((f) => _canonicalSignature(f) === norm);
+      if (!found) throw makeError("no matching function for signature", "INVALID_ARGUMENT", { signature: key });
+      return new FunctionFragment(found);
+    }
+
+    const matches = fns.filter((f) => f.name === key);
+    if (matches.length === 0) throw makeError("function not found", "INVALID_ARGUMENT", { nameOrSignatureOrSelector });
+    if (matches.length > 1) {
+      throw makeError("ambiguous function name; specify the full signature", "INVALID_ARGUMENT", { nameOrSignatureOrSelector });
+    }
+    return new FunctionFragment(matches[0]);
   }
 
   /**
-   * Get an event fragment by name (first match).
-   * @param {string} nameOrSignature
+   * Get an event fragment by bare name, canonical signature, or topic0
+   * (`0x` + 64 hex). Mirrors ethers.js v6.
+   * @param {string} nameOrSignatureOrTopic
    * @returns {EventFragment}
    */
-  getEvent(nameOrSignature) {
-    assertArgument(typeof nameOrSignature === "string", "name must be a string", "nameOrSignature", nameOrSignature);
-    const found = this.abi.find((f) => f && f.type === "event" && f.name === nameOrSignature);
-    if (!found) throw makeError("event not found", "INVALID_ARGUMENT", { nameOrSignature });
-    return new EventFragment(found);
+  getEvent(nameOrSignatureOrTopic) {
+    assertArgument(typeof nameOrSignatureOrTopic === "string", "name must be a string", "nameOrSignatureOrTopic", nameOrSignatureOrTopic);
+    const key = nameOrSignatureOrTopic.trim();
+    const evs = this.abi.filter((f) => f && f.type === "event" && f.name);
+
+    if (_isTopicHex(key)) {
+      const topic = normalizeHex(key);
+      const found = evs.find((f) => !f.anonymous && normalizeHex(id(_canonicalSignature(f))) === topic);
+      if (!found) throw makeError("no matching event for topic", "INVALID_ARGUMENT", { topic: key });
+      return new EventFragment(found);
+    }
+
+    if (key.indexOf("(") >= 0) {
+      const norm = _stripWhitespace(key);
+      const found = evs.find((f) => _canonicalSignature(f) === norm);
+      if (!found) throw makeError("no matching event for signature", "INVALID_ARGUMENT", { signature: key });
+      return new EventFragment(found);
+    }
+
+    const matches = evs.filter((f) => f.name === key);
+    if (matches.length === 0) throw makeError("event not found", "INVALID_ARGUMENT", { nameOrSignatureOrTopic });
+    return new EventFragment(matches[0]);
   }
 
   /**
-   * Get an error fragment by name (first match).
-   * @param {string} nameOrSignature
+   * Get an error fragment by bare name, canonical signature, or 4-byte selector.
+   * Mirrors ethers.js v6.
+   * @param {string} nameOrSignatureOrSelector
    * @returns {ErrorFragment}
    */
-  getError(nameOrSignature) {
-    assertArgument(typeof nameOrSignature === "string", "name must be a string", "nameOrSignature", nameOrSignature);
-    const found = this.abi.find((f) => f && f.type === "error" && f.name === nameOrSignature);
-    if (!found) throw makeError("error not found", "INVALID_ARGUMENT", { nameOrSignature });
-    return new ErrorFragment(found);
+  getError(nameOrSignatureOrSelector) {
+    assertArgument(typeof nameOrSignatureOrSelector === "string", "name must be a string", "nameOrSignatureOrSelector", nameOrSignatureOrSelector);
+    const key = nameOrSignatureOrSelector.trim();
+    const errs = this.abi.filter((f) => f && f.type === "error" && f.name);
+
+    if (_isSelectorHex(key)) {
+      const sel = normalizeHex(key).toLowerCase();
+      const found = errs.find((f) => jsAbi.functionSelectorHex(f.name, f.inputs || []).toLowerCase() === sel);
+      if (!found) throw makeError("no matching error for selector", "INVALID_ARGUMENT", { selector: key });
+      return new ErrorFragment(found);
+    }
+
+    if (key.indexOf("(") >= 0) {
+      const norm = _stripWhitespace(key);
+      const found = errs.find((f) => _canonicalSignature(f) === norm);
+      if (!found) throw makeError("no matching error for signature", "INVALID_ARGUMENT", { signature: key });
+      return new ErrorFragment(found);
+    }
+
+    const matches = errs.filter((f) => f.name === key);
+    if (matches.length === 0) throw makeError("error not found", "INVALID_ARGUMENT", { nameOrSignatureOrSelector });
+    return new ErrorFragment(matches[0]);
   }
 
   /**
@@ -341,24 +431,76 @@ class Interface {
    */
   encodeFunctionData(functionFragment, values) {
     _requireInitialized();
-    const name = typeof functionFragment === "string" ? functionFragment : functionFragment?.name;
+    const rawArgs = Array.isArray(values) ? values : [];
+
+    // When a fragment object is supplied (e.g. from parseTransaction /
+    // getFunction), encode directly from its exact inputs via the pure-JS coder.
+    // This guarantees encode/decode is a faithful round-trip (including
+    // overloaded functions) and matches decodeFunctionData byte-for-byte.
+    if (functionFragment && typeof functionFragment === "object") {
+      const fname = functionFragment.name;
+      assertArgument(typeof fname === "string" && fname.length > 0, "invalid function", "functionFragment", functionFragment);
+      const finputs = Array.isArray(functionFragment.inputs) ? functionFragment.inputs : [];
+      return jsAbi.encodeFunctionData(fname, finputs, rawArgs);
+    }
+
+    const name = functionFragment;
     assertArgument(typeof name === "string" && name.length > 0, "invalid function", "functionFragment", functionFragment);
     const frag = this.getFunction(name);
     const inputs = Array.isArray(frag.inputs) ? frag.inputs : [];
-    const rawArgs = Array.isArray(values) ? values : [];
 
     // Fallback for complex ABI surfaces where qcsdk packing is unreliable.
     if (jsAbi.needsJsAbi(inputs)) {
-      return jsAbi.encodeFunctionData(name, inputs, rawArgs);
+      return jsAbi.encodeFunctionData(frag.name, inputs, rawArgs);
     }
 
     const args = inputs.map((p, idx) => _convertInputValueForQcsdk(p, rawArgs[idx]));
-    const res = qcsdk.packMethodData(this._qcsdkAbiJson, name, ...args);
+    const res = qcsdk.packMethodData(this._qcsdkAbiJson, frag.name, ...args);
     if (!res || typeof res.error !== "string") throw makeError("packMethodData failed", "UNKNOWN_ERROR", {});
-    if (res.error) throw makeError(res.error, "UNKNOWN_ERROR", { operation: "packMethodData", function: name });
+    if (res.error) throw makeError(res.error, "UNKNOWN_ERROR", { operation: "packMethodData", function: frag.name });
     return normalizeHex(res.result);
   }
 
+  /**
+   * Encode ABI constructor arguments for a contract deployment (no selector).
+   * Returns "0x" when the constructor takes no arguments. The caller appends
+   * this to the creation bytecode. Mirrors ethers.js v6.
+   * @param {any[]=} values
+   * @returns {string}
+   */
+  encodeDeploy(values) {
+    _requireInitialized();
+    const ctor = this.getConstructor();
+    const inputs = ctor && Array.isArray(ctor.inputs) ? ctor.inputs : [];
+    const rawArgs = Array.isArray(values) ? values : [];
+    if (inputs.length === 0) return "0x";
+    return normalizeHex(bytesToHex(jsAbi.encodeTupleLike(inputs, rawArgs)));
+  }
+
+  /**
+   * Decode the calldata of a function call (4-byte selector + ABI-encoded
+   * arguments), returning the decoded input arguments as a Result. The data's
+   * selector must match the resolved function. Mirrors ethers.js v6.
+   * @param {FunctionFragment|string} fragment
+   * @param {string} data
+   * @returns {Result}
+   */
+  decodeFunctionData(fragment, data) {
+    _requireInitialized();
+    assertArgument(typeof data === "string" && isHexString(data), "data must be a hex string", "data", data);
+    const frag = _resolveFunctionFragment(this, fragment);
+    const inputs = Array.isArray(frag.inputs) ? frag.inputs : [];
+    const selector = jsAbi.functionSelectorHex(frag.name, inputs).toLowerCase();
+    const norm = normalizeHex(data);
+    const bytes = arrayify(norm);
+    if (bytes.length < 4 || norm.slice(0, 10).toLowerCase() !== selector) {
+      throw makeError("data selector does not match function", "INVALID_ARGUMENT", { function: frag.name, data });
+    }
+    const items = jsAbi.decodeTupleLike(inputs, bytes.slice(4), 0);
+    const keys = inputs.map((i) => (i && typeof i.name === "string" && i.name.length ? i.name : null));
+    return Result.fromItems(items, keys);
+  }
+
   /**
    * Decode function result using quantum-coin-js-sdk.
    * @param {FunctionFragment|string} functionFragment
@@ -442,9 +584,40 @@ class Interface {
     }
   }
 
-  // The following methods exist in ethers.js v6. We provide placeholders to keep API shape.
-  parseTransaction() {
-    throw makeError("parseTransaction not implemented", "NOT_IMPLEMENTED", {});
+  /**
+   * Parse a transaction's calldata into its function + decoded arguments.
+   * Resolves the function by the 4-byte selector in `tx.data`, decodes the
+   * arguments from the real bytes, and reports `value` as a bigint. Mirrors
+   * ethers.js v6 (returns a TransactionDescription-shaped object).
+   * @param {{ data: string, value?: any }} tx
+   * @returns {{ fragment: FunctionFragment, name: string, signature: string, selector: string, args: Result, value: bigint }}
+   */
+  parseTransaction(tx) {
+    _requireInitialized();
+    assertArgument(tx && typeof tx === "object", "tx must be an object", "tx", tx);
+    const data = tx.data;
+    assertArgument(typeof data === "string" && isHexString(data), "tx.data must be a hex string", "tx.data", data);
+    const norm = normalizeHex(data);
+    if (arrayify(norm).length < 4) throw makeError("data too short for a function selector", "INVALID_ARGUMENT", { data });
+    const selector = norm.slice(0, 10);
+    const frag = this.getFunction(selector);
+    const args = this.decodeFunctionData(frag, norm);
+    let value = 0n;
+    if (tx.value != null) {
+      try {
+        value = BigInt(tx.value);
+      } catch {
+        value = 0n;
+      }
+    }
+    return {
+      fragment: frag,
+      name: frag.name,
+      signature: _canonicalSignature(frag),
+      selector: jsAbi.functionSelectorHex(frag.name, Array.isArray(frag.inputs) ? frag.inputs : []),
+      args,
+      value,
+    };
   }
   parseLog() {
     _requireInitialized();
@@ -512,11 +685,47 @@ class Interface {
       args,
     };
   }
-  parseError() {
-    throw makeError("parseError not implemented", "NOT_IMPLEMENTED", {});
+  /**
+   * Parse custom-error return data into its error fragment + decoded arguments.
+   * Resolves the error by the 4-byte selector in `data`. Mirrors ethers.js v6
+   * (returns an ErrorDescription-shaped object).
+   * @param {string} data
+   * @returns {{ fragment: ErrorFragment, name: string, signature: string, selector: string, args: Result }}
+   */
+  parseError(data) {
+    _requireInitialized();
+    assertArgument(typeof data === "string" && isHexString(data), "data must be a hex string", "data", data);
+    const norm = normalizeHex(data);
+    const bytes = arrayify(norm);
+    if (bytes.length < 4) throw makeError("data too short for an error selector", "INVALID_ARGUMENT", { data });
+    const selector = norm.slice(0, 10).toLowerCase();
+    const errs = this.abi.filter((f) => f && f.type === "error" && f.name);
+    const found = errs.find((f) => jsAbi.functionSelectorHex(f.name, f.inputs || []).toLowerCase() === selector);
+    if (!found) throw makeError("no matching error for selector", "INVALID_ARGUMENT", { selector });
+    const inputs = Array.isArray(found.inputs) ? found.inputs : [];
+    const items = jsAbi.decodeTupleLike(inputs, bytes.slice(4), 0);
+    const keys = inputs.map((i) => (i && typeof i.name === "string" && i.name.length ? i.name : null));
+    return {
+      fragment: new ErrorFragment(found),
+      name: found.name,
+      signature: _canonicalSignature(found),
+      selector: jsAbi.functionSelectorHex(found.name, inputs),
+      args: Result.fromItems(items, keys),
+    };
   }
-  getSighash() {
-    throw makeError("getSighash not implemented", "NOT_IMPLEMENTED", {});
+
+  /**
+   * Return the 4-byte function selector (sighash) for a function fragment or
+   * name. Mirrors ethers.js v5 getSighash / v6 FunctionFragment.selector.
+   * @param {FunctionFragment|string} fragmentOrName
+   * @returns {string}
+   */
+  getSighash(fragmentOrName) {
+    const frag =
+      fragmentOrName && typeof fragmentOrName === "object" && fragmentOrName.name
+        ? fragmentOrName
+        : this.getFunction(fragmentOrName);
+    return jsAbi.functionSelectorHex(frag.name, Array.isArray(frag.inputs) ? frag.inputs : []);
   }
   /**
    * Compute the topic0 (event signature hash) for an event.
@@ -599,6 +808,15 @@ class AbiCoder {
     assertArgument(Array.isArray(types), "types must be an array", "types", types);
     return types.map(() => null);
   }
+
+  /**
+   * Return the shared default AbiCoder instance (ethers.js v6 shape).
+   * @returns {AbiCoder}
+   */
+  static defaultAbiCoder() {
+    if (!AbiCoder._instance) AbiCoder._instance = new AbiCoder();
+    return AbiCoder._instance;
+  }
 }
 
 module.exports = { Interface, AbiCoder };

package/src/abi/js-abi-coder.d.ts

@@ -6,3 +6,5 @@ export function functionSelectorHex(name: any, inputs: any): string;
 export function encodeFunctionData(name: any, inputs: any, values: any): string;
 export function encodeTupleLike(params: any, values: any, depth: any): Uint8Array<any>;
 export function decodeFunctionResult(outputs: any, dataHex: any): any[];
+export function decodeTupleLike(params: any, data: any, baseOffset: any, depth: any): any[];
+export function decodeParam(param: any, data: any, offset: any, depth: any): any;

package/src/abi/js-abi-coder.js

@@ -534,5 +534,7 @@ module.exports = {
   encodeFunctionData,
   encodeTupleLike,
   decodeFunctionResult,
+  decodeTupleLike,
+  decodeParam,
 };
 

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,
 };