quantumcoin 8.0.1 → 8.0.2

package/README-SDK.md

@@ -610,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.
@@ -635,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
 

package/README.md

@@ -148,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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quantumcoin",
-  "version": "8.0.1",
+  "version": "8.0.2",
   "description": "QuantumCoin.js - a post quantum cryptography SDK for QuantumCoin",
   "main": "index.js",
   "types": "src/index.d.ts",

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