LiopClient

Routing intent and injecting autonomous logic via the Logic-Injection-on-Origin Protocol

The LiopClient class is the orchestrator for Agent Nodes. It connects your Node.js or edge application to the Kademlia DHT Mesh, validates cryptographic identities, and dispatches WebAssembly logic payloads directly to remote Data Nodes (Servers).

Unlike traditional REST clients that just <fetch> static JSON endpoints, a LiopClient literally pushes its logic functions across the internet to be executed natively at the server.

Initialization and Configuration

The client accepts optional TLS configuration for secure gRPC communication.

import { LiopClient } from "@nekzus/liop";
import type { LiopTlsOptions } from "@nekzus/liop";

const tlsConfig: LiopTlsOptions = {
  // Optional: provide custom TLS credentials for gRPC
};

const client = new LiopClient(tlsConfig);

Configuration Options

When creating a LiopClient, you may provide:

• tls? (LiopTlsOptions): Optional TLS credentials for secure gRPC communication. If omitted, insecure transport is used (suitable for local development).

Connecting to the Mesh

Unlike MCP which requires a direct stdio pipe or a hardcoded SSE URL, LIOP uses decentralized peer-to-peer routing. libp2p handles NAT traversal automatically.

// Connect to the Mesh network backbone with default config
await client.connect();

// Or connect to a specific bootstrap node
await client.connect("/ip4/127.0.0.1/tcp/4001/p2p/PEER_ID", {
  meshConfig: {
    bootstrapNodes: ["/ip4/1.2.3.4/tcp/4001"],
    identityPath: "~/.liop/identity.json"
  }
});

// Check the mesh node state after connection
console.log("Mesh connected:", client.getServerInfo());

Calling a Server Capability (Tool)

Use resolveCapability() to discover available servers on the DHT, then invoke tools via callTool() with a CallToolRequest object:

// Discover tools available on the mesh
const tools = await client.discoverTools();
console.log("Available tools:", tools);

// Resolve a capability to a specific peer
const target = await client.resolveCapability("execute_complex_sql");

// Invoke the tool
const result = await client.callTool({
  name: "execute_complex_sql",
  arguments: { 
    query: "SELECT * FROM petabytes_table WHERE anomaly_detected = true" 
  }
});

console.log(result.content[0].text);

For fine-grained control over the WASM payload sent to the server, use the second parameter of callTool() to pass a raw Buffer.

Creating Watchdogs (Push Subscriptions) [PLANNED]

This feature is on the roadmap but not yet implemented in the current SDK release.

Watchdogs enable persistent push subscriptions. Instead of manually polling callTool(), you will be able to deploy a persistent watcher module that pushes events asynchronously over multiplexed QUIC channels back to the agent. Track progress on the GitHub repository.

Cryptographic Validation (The ZK Shield)

While the network layer is encrypted using symmetric AES-256-GCM, the LiopClient fundamentally doubts the execution origin.

When callTool returns from the remote Data Node, the client performs ZK verification internally through its built-in LiopVerifier whenever receipts are present in the execution flow. The exposed callTool result remains MCP-compatible (content/isError). You can also manually verify when you have raw proof artifacts:

// The client automatically verifies ZK receipts during callTool().
// For manual verification, use the public verifier instance:
const isValid = await client.verifier.verifyZkReceipt(
  wasmPayload, 
  remoteImageIdHex, 
  zkReceiptBuffer
);

if (!isValid) {
  throw new Error("Mathematical Proof Mismatch (Hack Detected)");
}

Note: The LiopMcpBridge automatically runs this validation natively on behalf of legacy MCP clients.

Lifecycle Management

Always close the client gracefully to release mesh resources:

try {
  await client.connect();
  // ... calls
} finally {
  await client.close();
}

Error Handling & Zero-Trust Rejections

Because the Server enforces a strict WASI sandbox and uses the Zero-Time Guardian to inspect your .wasm payload BEFORE execution, your client must be prepared to handle sandbox rejections.

try {
  await client.callTool({ name: "read_file", arguments: { path: "/etc/passwd" } });
} catch (error) {
  if (error instanceof Error) {
    console.error("Sandbox Execution Halted:", error.message);
  }
}

LiopError and ErrorCode are exported by the SDK and can be used by applications that normalize or re-wrap protocol errors. Current runtime paths may still throw native Error instances depending on context.