Zetrix MCP Server

Instructions

Implementation Reference

• src/index.ts:1216-1236 (handler)

  MCP server handler for the tool: parses arguments and delegates to ZetrixSDK.invokeContract

  case "zetrix_sdk_invoke_contract": {
    if (!args) {
      throw new Error("Missing arguments");
    }
    const result = await zetrixSDK.invokeContract({
      sourceAddress: args.sourceAddress as string,
      privateKey: args.privateKey as string,
      contractAddress: args.contractAddress as string,
      amount: args.amount as string,
      input: args.input as string,
      metadata: args.metadata as string | undefined,
    });
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(result, null, 2),
        },
      ],
    };
  }

• src/index.ts:492-525 (schema)

  Input schema definition for the tool validation

  {
    name: "zetrix_sdk_invoke_contract",
    description: "Invoke a smart contract function with state change (requires private key)",
    inputSchema: {
      type: "object",
      properties: {
        sourceAddress: {
          type: "string",
          description: "The account address initiating the transaction",
        },
        privateKey: {
          type: "string",
          description: "Private key for signing the transaction",
        },
        contractAddress: {
          type: "string",
          description: "The smart contract address to invoke",
        },
        amount: {
          type: "string",
          description: "Amount of ZTX to send with invocation (in micro-ZTX)",
        },
        input: {
          type: "string",
          description: "JSON string with method and params",
        },
        metadata: {
          type: "string",
          description: "Optional transaction description",
        },
      },
      required: ["sourceAddress", "privateKey", "contractAddress", "amount", "input"],
    },
  },

• src/index.ts:492-525 (registration)

  Tool object registration in the tools array used by ListToolsRequestHandler

  {
    name: "zetrix_sdk_invoke_contract",
    description: "Invoke a smart contract function with state change (requires private key)",
    inputSchema: {
      type: "object",
      properties: {
        sourceAddress: {
          type: "string",
          description: "The account address initiating the transaction",
        },
        privateKey: {
          type: "string",
          description: "Private key for signing the transaction",
        },
        contractAddress: {
          type: "string",
          description: "The smart contract address to invoke",
        },
        amount: {
          type: "string",
          description: "Amount of ZTX to send with invocation (in micro-ZTX)",
        },
        input: {
          type: "string",
          description: "JSON string with method and params",
        },
        metadata: {
          type: "string",
          description: "Optional transaction description",
        },
      },
      required: ["sourceAddress", "privateKey", "contractAddress", "amount", "input"],
    },
  },

• src/zetrix-sdk.ts:158-240 (helper)

  Main helper function implementing the contract invocation logic using official Zetrix SDK: creates operation, evaluates fees, builds/signs/submits transaction.

  /**
   * Invoke a smart contract (with state change and gas payment)
   */
  async invokeContract(params: ZetrixContractInvokeParams): Promise<any> {
    await this.initSDK();
  
    try {
      // Create contract invoke operation
      const operation = this.sdk.operation.contractInvokeByGasOperation({
        contractAddress: params.contractAddress,
        amount: params.amount,
        input: params.input,
        metadata: params.metadata,
      });
  
      if (operation.errorCode !== 0) {
        throw new Error(
          operation.errorDesc || `SDK Error: ${operation.errorCode}`
        );
      }
  
      // Build and sign transaction
      const feeData = await this.sdk.transaction.evaluateFee({
        sourceAddress: params.sourceAddress,
        nonce: "auto", // SDK will fetch nonce automatically
        operations: [operation.result.operation],
        signtureNumber: "1",
        metadata: params.metadata,
      });
  
      if (feeData.errorCode !== 0) {
        throw new Error(
          feeData.errorDesc || `SDK Error: ${feeData.errorCode}`
        );
      }
  
      // Submit transaction
      const txParams = {
        sourceAddress: params.sourceAddress,
        nonce: feeData.result.nonce,
        operations: [operation.result.operation],
        gasPrice: feeData.result.gasPrice,
        feeLimit: feeData.result.feeLimit,
        metadata: params.metadata,
      };
  
      const blob = await this.sdk.transaction.buildBlob(txParams);
  
      if (blob.errorCode !== 0) {
        throw new Error(blob.errorDesc || `SDK Error: ${blob.errorCode}`);
      }
  
      // Sign the transaction
      const signature = this.sdk.transaction.sign({
        privateKeys: [params.privateKey],
        blob: blob.result.transactionBlob,
      });
  
      if (signature.errorCode !== 0) {
        throw new Error(
          signature.errorDesc || `SDK Error: ${signature.errorCode}`
        );
      }
  
      // Submit to blockchain
      const submitResult = await this.sdk.transaction.submit({
        blob: blob.result.transactionBlob,
        signature: signature.result.signatures,
      });
  
      if (submitResult.errorCode !== 0) {
        throw new Error(
          submitResult.errorDesc || `SDK Error: ${submitResult.errorCode}`
        );
      }
  
      return submitResult.result;
    } catch (error) {
      throw new Error(
        `Failed to invoke contract: ${error instanceof Error ? error.message : String(error)}`
      );
    }
  }