client.js

/**
 * Quantova q_ JSON-RPC client.
 *
 * A small, dependency-light wrapper over the Quantova `q_` JSON-RPC namespace.
 * Every method is a POST to the HTTP endpoint with a JSON body
 * { jsonrpc, id, method, params }. Account addresses are Q-format strings;
 * numeric results come back as QUANTITY hex you convert to a number.
 *
 * See docs/interacting.md for usage and the full method list.
 */

const DEFAULT_RPC = process.env.QUANTOVA_RPC_URL || "http://127.0.0.1:9933";

export class QuantovaClient {
  constructor(rpcUrl = DEFAULT_RPC) {
    this.rpcUrl = rpcUrl;
    this._id = 0;
  }

  /** Low-level JSON-RPC call. `params` is a JSON array in the documented order. */
  async call(method, params = []) {
    const res = await fetch(this.rpcUrl, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ jsonrpc: "2.0", id: ++this._id, method, params }),
    });
    if (!res.ok) throw new Error(`RPC HTTP ${res.status}`);
    const { result, error } = await res.json();
    if (error) throw new Error(`RPC error ${error.code}: ${error.message}`);
    return result;
  }

  // ---- convenience helpers -------------------------------------------------

  /** Height of the most recent block, as a number. */
  async blockNumber() {
    return parseInt(await this.call("q_blockNumber"), 16);
  }

  /** Chain id (used in signing to prevent cross-chain replay). */
  async chainId() {
    return await this.call("q_chainId");
  }

  /**
   * Balance of a Q-format address, in QTOV (base units / 10^18).
   * `block` is a block-number QUANTITY hex; defaults to the latest height.
   * Named tags like "latest" are NOT implemented — we resolve a height first.
   */
  async getBalanceQTOV(address, block) {
    const ref = block ?? "0x" + (await this.blockNumber()).toString(16);
    const raw = await this.call("q_getBalance", [address, ref]);
    return Number(BigInt(raw)) / 1e18;
  }

  /** Account nonce — set this on the next transaction you build. */
  async getNonce(address, block) {
    const ref = block ?? "0x" + (await this.blockNumber()).toString(16);
    return parseInt(await this.call("q_getTransactionCount", [address, ref]), 16);
  }

  /** Read-only contract call (no QGAS, no transaction). */
  async callContract(callObject, block) {
    const ref = block ?? "0x" + (await this.blockNumber()).toString(16);
    return await this.call("q_call", [callObject, ref]);
  }

  /** Estimate QGAS for a call or deployment. */
  async estimateGas(callObject) {
    return parseInt(await this.call("q_estimateGas", [callObject]), 16);
  }

  /** Broadcast an already-signed, serialized transaction. Returns the tx hash. */
  async sendRawTransaction(signedTxHex) {
    return await this.call("q_sendRawTransaction", [signedTxHex]);
  }

  /** Fetch a transaction receipt (status, QGAS used, logs, contract address). */
  async getTransactionReceipt(txHash) {
    return await this.call("q_getTransactionReceipt", [txHash]);
  }

  /**
   * Poll until a transaction has a receipt, then return it.
   * Note: a receipt means included — confirm finality (~3s) before treating
   * value as settled. See docs/interacting.md.
   */
  async waitForReceipt(txHash, { intervalMs = 1000, timeoutMs = 60000 } = {}) {
    const start = Date.now();
    for (;;) {
      const receipt = await this.getTransactionReceipt(txHash).catch(() => null);
      if (receipt) return receipt;
      if (Date.now() - start > timeoutMs) throw new Error("Timed out waiting for receipt");
      await new Promise((r) => setTimeout(r, intervalMs));
    }
  }
}

export default QuantovaClient;