fix: address reviewer feedback from nickgs1337 and RomuloSiebra

- Fix SmartContract type from 9 to 63 (transaction.proto)
- Fix SC sub-types: deploy=scType:1, invoke=scType:0 (were swapped)
- Fix callValue format to map of token ID to amount ({KLV: amount})
- Fix Freeze type from 2 to 4 (FreezeContractType)
- Fix TransactionBuildRequest to use flat contracts array
- Add builder methods to KleverChainClient (buildTransfer, buildDeploy,
  buildInvoke, buildFreeze) to move chain logic out of server.ts
- Extract fetchWithTimeout to reduce duplication in fetchJson/postJson
- Add wasmPath option to deploy_sc (reads file server-side)
- Add caller field to query_sc and VMQueryRequest
- Add log() alias for console.error with comment explaining MCP stderr

Author: fbsobreira

src/chain/client.test.ts

@@ -407,14 +407,162 @@ describe('KleverChainClient', () => {
         type: 0,
         sender: 'klv1sender',
         nonce: 5,
-        contract: [{ type: 0, parameter: { amount: 1000000, toAddress: 'klv1receiver' } }],
+        contracts: [{ amount: 1000000, toAddress: 'klv1receiver' }],
       });
 
       expect(result.result.txHash).toBe('hash123');
       expect(result.result.tx).toBe('proto_encoded_tx');
     });
   });
 
+  describe('querySmartContract with caller', () => {
+    it('passes caller field in VM query', async () => {
+      const vmResult = {
+        returnData: ['AQID'],
+        returnCode: 'ok',
+        returnMessage: '',
+      };
+
+      mockFetch.mockResolvedValueOnce(
+        jsonResponse({ data: vmResult, error: '', code: 'successful' })
+      );
+
+      await client.querySmartContract({
+        scAddress: 'klv1contract',
+        funcName: 'getBalance',
+        caller: 'klv1caller',
+      });
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        'https://node.testnet.klever.org/vm/query',
+        expect.objectContaining({
+          method: 'POST',
+          body: JSON.stringify({
+            scAddress: 'klv1contract',
+            funcName: 'getBalance',
+            caller: 'klv1caller',
+          }),
+        })
+      );
+    });
+  });
+
+  describe('buildTransfer', () => {
+    it('fetches nonce and builds a transfer transaction', async () => {
+      // Mock getNonce
+      mockFetch.mockResolvedValueOnce(
+        jsonResponse({ data: { nonce: 10 }, error: '', code: 'successful' })
+      );
+      // Mock buildTransaction
+      mockFetch.mockResolvedValueOnce(
+        jsonResponse({
+          data: { result: { txHash: 'hash1', tx: 'proto1' } },
+          error: '',
+          code: 'successful',
+        })
+      );
+
+      const result = await client.buildTransfer({
+        sender: 'klv1sender',
+        receiver: 'klv1receiver',
+        amount: 5000000,
+      });
+
+      expect(result.result.txHash).toBe('hash1');
+      // Verify the buildTransaction POST body
+      const postCall = mockFetch.mock.calls[1];
+      const body = JSON.parse(postCall[1]?.body as string);
+      expect(body.type).toBe(0);
+      expect(body.contracts[0].amount).toBe(5000000);
+      expect(body.contracts[0].toAddress).toBe('klv1receiver');
+    });
+  });
+
+  describe('buildDeploy', () => {
+    it('builds a deploy transaction with correct type 63 and scType 1', async () => {
+      mockFetch.mockResolvedValueOnce(
+        jsonResponse({ data: { nonce: 3 }, error: '', code: 'successful' })
+      );
+      mockFetch.mockResolvedValueOnce(
+        jsonResponse({
+          data: { result: { txHash: 'deploy1', tx: 'deploy_proto' } },
+          error: '',
+          code: 'successful',
+        })
+      );
+
+      const result = await client.buildDeploy({
+        sender: 'klv1deployer',
+        wasmHex: 'deadbeef',
+      });
+
+      expect(result.result.txHash).toBe('deploy1');
+      const postCall = mockFetch.mock.calls[1];
+      const body = JSON.parse(postCall[1]?.body as string);
+      expect(body.type).toBe(63);
+      expect(body.contracts[0].scType).toBe(1);
+      expect(body.data).toEqual(['deadbeef']);
+    });
+  });
+
+  describe('buildInvoke', () => {
+    it('builds an invoke transaction with correct type 63, scType 0, and callValue map', async () => {
+      mockFetch.mockResolvedValueOnce(
+        jsonResponse({ data: { nonce: 7 }, error: '', code: 'successful' })
+      );
+      mockFetch.mockResolvedValueOnce(
+        jsonResponse({
+          data: { result: { txHash: 'invoke1', tx: 'invoke_proto' } },
+          error: '',
+          code: 'successful',
+        })
+      );
+
+      const result = await client.buildInvoke({
+        sender: 'klv1caller',
+        scAddress: 'klv1contract',
+        funcName: 'doSomething',
+        args: ['AQID'],
+        callValue: { KLV: 1000000 },
+      });
+
+      expect(result.result.txHash).toBe('invoke1');
+      const postCall = mockFetch.mock.calls[1];
+      const body = JSON.parse(postCall[1]?.body as string);
+      expect(body.type).toBe(63);
+      expect(body.contracts[0].scType).toBe(0);
+      expect(body.contracts[0].address).toBe('klv1contract');
+      expect(body.contracts[0].callValue).toEqual({ KLV: 1000000 });
+      expect(body.data).toEqual(['doSomething', 'AQID']);
+    });
+  });
+
+  describe('buildFreeze', () => {
+    it('builds a freeze transaction with correct type 4', async () => {
+      mockFetch.mockResolvedValueOnce(
+        jsonResponse({ data: { nonce: 5 }, error: '', code: 'successful' })
+      );
+      mockFetch.mockResolvedValueOnce(
+        jsonResponse({
+          data: { result: { txHash: 'freeze1', tx: 'freeze_proto' } },
+          error: '',
+          code: 'successful',
+        })
+      );
+
+      const result = await client.buildFreeze({
+        sender: 'klv1sender',
+        amount: 10000000,
+      });
+
+      expect(result.result.txHash).toBe('freeze1');
+      const postCall = mockFetch.mock.calls[1];
+      const body = JSON.parse(postCall[1]?.body as string);
+      expect(body.type).toBe(4);
+      expect(body.contracts[0].amount).toBe(10000000);
+    });
+  });
+
   describe('getNodeStatus', () => {
     it('fetches node health status', async () => {
       const statusData = {

src/chain/client.ts

@@ -5,6 +5,10 @@
  * Uses native fetch (Node 18+) — no external HTTP dependencies.
  */
 
+import {
+  ContractType,
+  SCType,
+} from './types.js';
 import type {
   KleverNetwork,
   NetworkConfig,
@@ -21,6 +25,10 @@ import type {
   NodeStatusData,
   TransactionBuildRequest,
   TransactionBuildData,
+  TransferParams,
+  DeployParams,
+  InvokeParams,
+  FreezeParams,
 } from './types.js';
 
 /** Network URL mapping */
@@ -86,22 +94,19 @@ export class KleverChainClient {
 
   // ─── Core HTTP Methods ───────────────────────────────────
 
-  private async fetchJson<T>(url: string): Promise<T> {
+  private async fetchWithTimeout(url: string, init?: RequestInit): Promise<Response> {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
 
     try {
-      const response = await fetch(url, {
-        signal: controller.signal,
-        headers: { Accept: 'application/json' },
-      });
+      const response = await fetch(url, { ...init, signal: controller.signal });
 
       if (!response.ok) {
         const text = await response.text().catch(() => '');
         throw new Error(`HTTP ${response.status}: ${text || response.statusText}`);
       }
 
-      return (await response.json()) as T;
+      return response;
     } catch (error) {
       if (error instanceof Error && error.name === 'AbortError') {
         throw new Error(`Request timed out after ${this.timeout}ms: ${url}`);
@@ -112,35 +117,23 @@ export class KleverChainClient {
     }
   }
 
-  private async postJson<T>(url: string, body: unknown): Promise<T> {
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
-
-    try {
-      const response = await fetch(url, {
-        method: 'POST',
-        signal: controller.signal,
-        headers: {
-          'Content-Type': 'application/json',
-          Accept: 'application/json',
-        },
-        body: JSON.stringify(body),
-      });
-
-      if (!response.ok) {
-        const text = await response.text().catch(() => '');
-        throw new Error(`HTTP ${response.status}: ${text || response.statusText}`);
-      }
+  private async fetchJson<T>(url: string): Promise<T> {
+    const response = await this.fetchWithTimeout(url, {
+      headers: { Accept: 'application/json' },
+    });
+    return (await response.json()) as T;
+  }
 
-      return (await response.json()) as T;
-    } catch (error) {
-      if (error instanceof Error && error.name === 'AbortError') {
-        throw new Error(`Request timed out after ${this.timeout}ms: ${url}`);
-      }
-      throw error;
-    } finally {
-      clearTimeout(timeoutId);
-    }
+  private async postJson<T>(url: string, body: unknown): Promise<T> {
+    const response = await this.fetchWithTimeout(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+      },
+      body: JSON.stringify(body),
+    });
+    return (await response.json()) as T;
   }
 
   /** Unwrap a Klever API response, throwing on error */
@@ -235,6 +228,88 @@ export class KleverChainClient {
     return this.unwrap(response, `querySmartContract(${request.scAddress}::${request.funcName})`);
   }
 
+  // ─── Transaction Builder Methods ────────────────────────
+
+  /** Build an unsigned transfer (KLV or KDA) transaction */
+  async buildTransfer(
+    params: TransferParams,
+    network?: KleverNetwork
+  ): Promise<TransactionBuildData> {
+    const nonce = await this.getNonce(params.sender, network);
+
+    const contracts: Array<Record<string, unknown>> = [
+      {
+        amount: params.amount,
+        toAddress: params.receiver,
+        ...(params.assetId ? { assetId: params.assetId } : {}),
+      },
+    ];
+
+    return this.buildTransaction(
+      { type: ContractType.Transfer, sender: params.sender, nonce, contracts },
+      network
+    );
+  }
+
+  /** Build an unsigned smart contract deploy transaction */
+  async buildDeploy(
+    params: DeployParams,
+    network?: KleverNetwork
+  ): Promise<TransactionBuildData> {
+    const nonce = await this.getNonce(params.sender, network);
+
+    const data = [params.wasmHex, ...(params.initArgs || [])];
+
+    const contracts: Array<Record<string, unknown>> = [
+      { scType: SCType.SCDeploy },
+    ];
+
+    return this.buildTransaction(
+      { type: ContractType.SmartContract, sender: params.sender, nonce, contracts, data },
+      network
+    );
+  }
+
+  /** Build an unsigned smart contract invoke transaction */
+  async buildInvoke(
+    params: InvokeParams,
+    network?: KleverNetwork
+  ): Promise<TransactionBuildData> {
+    const nonce = await this.getNonce(params.sender, network);
+
+    const data = [params.funcName, ...(params.args || [])];
+
+    const contracts: Array<Record<string, unknown>> = [
+      {
+        scType: SCType.SCInvoke,
+        address: params.scAddress,
+        ...(params.callValue ? { callValue: params.callValue } : {}),
+      },
+    ];
+
+    return this.buildTransaction(
+      { type: ContractType.SmartContract, sender: params.sender, nonce, contracts, data },
+      network
+    );
+  }
+
+  /** Build an unsigned freeze KLV transaction */
+  async buildFreeze(
+    params: FreezeParams,
+    network?: KleverNetwork
+  ): Promise<TransactionBuildData> {
+    const nonce = await this.getNonce(params.sender, network);
+
+    const contracts: Array<Record<string, unknown>> = [
+      { amount: params.amount },
+    ];
+
+    return this.buildTransaction(
+      { type: ContractType.Freeze, sender: params.sender, nonce, contracts },
+      network
+    );
+  }
+
   // ─── Transaction Operations ──────────────────────────────
 
   /** Get transaction details by hash (from node) */

src/chain/index.ts

@@ -1,5 +1,9 @@
 export { KleverChainClient, NETWORK_CONFIGS } from './client.js';
 export type { ChainClientOptions } from './client.js';
+export {
+  ContractType,
+  SCType,
+} from './types.js';
 export type {
   KleverNetwork,
   NetworkConfig,
@@ -16,4 +20,8 @@ export type {
   NodeStatusData,
   TransactionBuildRequest,
   TransactionBuildData,
+  TransferParams,
+  DeployParams,
+  InvokeParams,
+  FreezeParams,
 } from './types.js';