LiopClient

High-level orchestration for intent routing, peer discovery, and in-situ logic execution

The LiopClient class acts as the primary dispatch coordinator for Agent Nodes in the Logic-Injection-on-Origin Protocol. It manages transport negotiation across heterogeneous topologies (direct HTTP/JSON-RPC gateways, authenticated perimeter proxies, and sovereign P2P gRPC channels), executes cryptographic handshakes, and dispatches WebAssembly or JavaScript logic modules to remote Data Nodes.

Unlike traditional Model Context Protocol (MCP) clients that pull massive raw datasets across the network via polling or streaming endpoints, LiopClient packages analytical intent into isolated micro-modules and transmits them directly to where the data resides.

---

Constructor & Configuration

The constructor configures the transport-level TLS credentials applied to all underlying gRPC connections.

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

const tls: LiopTlsOptions = {
  rootCertPath: "/etc/ssl/certs/liop-ca.pem",
  clientCertPath: "/etc/ssl/certs/agent-client.pem",
  clientKeyPath: "/etc/ssl/private/agent-key.pem",
  serverNameOverride: "mesh.enclave.internal",
};

const client = new LiopClient(tls);

Constructor Parameters

tls · LiopTlsOptions

Cryptographic credentials for mutual TLS (mTLS) or server verification over gRPC transport.

Show LiopTlsOptions Properties

rootCertPath · string

Filesystem path to the root CA certificate used to validate server identity.

clientCertPath · string

Filesystem path to the client certificate for mTLS client authentication.

clientKeyPath · string

Filesystem path to the private key corresponding to clientCertPath.

serverNameOverride · string

Overrides the expected SNI server name when connecting through internal proxies or container networks.

---

Connecting to the Mesh (connect)

The connect() method establishes identity, provisions machine-to-machine (M2M) OAuth 2.1 tokens, and mounts either a direct point-to-point gRPC channel or a distributed libp2p node.

// Pattern A: Connecting to a specific gateway or enclave address
await client.connect("127.0.0.1:15021", {
  auth: {
    clientId: "analytics-agent-01",
    clientSecret: process.env.LIOP_CLIENT_SECRET,
    nexusUrl: "http://127.0.0.1:15000",
    audience: "urn:liop:mesh:api",
    scope: "liop:tools:call liop:tools:list",
  },
});

// Pattern B: Connecting dynamically to the P2P Mesh backbone
await client.connect(undefined, {
  meshConfig: {
    bootstrapNodes: [
      "/ip4/198.51.100.10/tcp/15001/p2p/12D3KooWDpJ7As7BWAwRMfu1VU2WCqNjvq387JEYKDBj4kx6nXTN"
    ],
    listenAddresses: ["/ip4/0.0.0.0/tcp/0"],
  },
});

Connection Options

address · string

Target endpoint in host:port format. When specified, creates a direct high-speed LiopRpcClient targeting that endpoint. When omitted, LiopClient routes requests dynamically through the peer-to-peer DHT.

options · object

Advanced connection settings covering authentication and peer-to-peer discovery.

Show Connection Options Properties

auth.clientId · string

OAuth 2.1 client identifier registered with the Nexus OIDC authorization server. Falls back to process.env.LIOP_OAUTH_CLIENT_ID.

auth.clientSecret · string

Client secret for the RFC 6749 Client Credentials grant. Falls back to process.env.LIOP_OAUTH_CLIENT_SECRET.

auth.nexusUrl · string

Base URL of the OIDC Identity Provider (e.g. http://127.0.0.1:15000). Automatically normalizes /oidc/token endpoints.

auth.audience · string

RFC 8707 Resource Indicator targeting the destination enclave (default: urn:liop:mesh:api).

auth.scope · string

Space-delimited OAuth 2.1 scopes required for execution. Defaults to standard capability scopes.

auth.token · string

Pre-computed static Bearer token. Bypasses the dynamic TokenManager handshake when supplied.

meshConfig · MeshNodeConfig

Configuration object for the underlying libp2p instance, including bootstrap multiaddrs and swarm keys.

---

Capability Discovery & Tool Invocations

LiopClient unifies tool discovery and execution under standard MCP schema shapes while enforcing post-quantum transport security under the hood.

// 1. Discover all tools registered across connected peers
const tools = await client.discoverTools();
console.log(`Discovered ${tools.length} mesh tools`);

// 2. Resolve capability target peer
const targetPeer = await client.resolveCapability("Analyze_Bank_Ledger");

// 3. Invoke tool with in-situ logic
const response = await client.callTool({
  name: "Analyze_Bank_Ledger",
  arguments: {
    account_id: "ACC-88219",
    currency: "USD",
    min_amount: 10000,
  },
});

for (const item of response.content) {
  if (item.type === "text") {
    console.log("Analytical Result:", item.text);
  }
}

In-Situ Logic Injection (WASM Bytecode)

For zero-data-movement pipelines, pass compiled WebAssembly bytecode directly via the optional second argument of callTool(). The remote enclave validates the bytecode through Guardian AST before executing it in an isolated V8 sandbox.

import { readFileSync } from "node:fs";

const wasmBinary = readFileSync("./aggregators/p99_latency.wasm");

const result = await client.callTool(
  {
    name: "Query_Telemetry_Logs",
    arguments: { service: "auth-gateway", window: "1h" },
  },
  wasmBinary, // Injected logic executed at the origin
);

---

Mathematical Verification (ZK-Receipts)

Every analytical payload executed by a compliant LIOP Data Node generates a cryptographic ZK-Receipt. The client verifier automatically inspects receipts returned during callTool(), supporting all three protocol modes:

• Mode 0 (Version 1): HMAC-SHA256 session commitment negotiated via ML-KEM-768.
• Mode 2 (Version 2): Groth16 Zero-Knowledge SNARK proof over the BN254 pairing-friendly elliptic curve.
• Mode 3 (Version 2.1): Dual-layer hybrid receipt combining a Groth16 BN254 mathematical proof with an ML-DSA-65 post-quantum digital signature.

To manually verify receipts received out-of-band:

import { LiopVerifier } from "@nekzus/liop";

const verifier = new LiopVerifier();

const isValid = await verifier.verifyZkReceipt(
  wasmPayload,          // Buffer containing the exact injected logic code
  remoteImageIdHex,     // Expected 32-byte guest image identifier
  zkReceiptBuffer,      // Cryptographic receipt returned by the server
  { zkPolicy: "required" } // "none" | "optimistic" | "required"
);

if (!isValid) {
  throw new Error("Zero-Trust Verification Failure: Computation tampering detected");
}

Pre-Flight Hardware TEE Attestation

When communicating with confidential virtual machines on untrusted cloud hosts, verify hardware root-of-trust evidence before initiating cryptographic handshakes:

import { verifyTeeAttestationDetailed } from "@nekzus/liop";

const attestationResult = await verifyTeeAttestationDetailed(
  attestationEvidenceBytes,
  expectedSessionNonce,
  {
    allowedMeasurements: ["b7f8c9..."],
    requireHardwareSigned: true,
  }
);

if (!attestationResult.valid) {
  throw new Error(`Confidential hardware validation failed: ${attestationResult.reason}`);
}

The pre-flight verifier validates:

• AMD SEV-SNP: Inspects 1,184-byte snp_report_t headers, checks REPORT_DATA at byte offset 0x50 against SHA-256(publicKey || nonce), verifies VCEK certificate signatures, and ensures debug mode is disabled.
• AWS Nitro Enclaves: Decodes CBOR-encoded COSE_Sign1 documents, checks PCR registers (PCR0, PCR1, PCR2), validates user_data binding, and verifies certificates up to AWS Nitro Root CA.

---

Low-Level gRPC Transport (LiopRpcClient)

For applications that need fine-grained control over gRPC channels, metadata streaming, or token injection without spawning a P2P node, use LiopRpcClient directly:

import { LiopRpcClient } from "@nekzus/liop";

const rpc = new LiopRpcClient(
  "127.0.0.1:15021",
  tlsConfig,
  async () => tokenManager.getToken(), // Dynamic async token resolver
);

// Step 1: Negotiate intent and acquire ephemeral Kyber public key
const intent = await rpc.negotiateIntent({
  capabilityName: "Analyze_Bank_Ledger",
  requesterPeerId: "12D3KooW...",
  clearanceLevel: 3,
});

// Step 2: Stream logic execution
const stream = rpc.executeLogic(encryptedLogicRequest);

stream.on("data", (response) => {
  console.log("Stream Chunk:", response.payload);
});
stream.on("error", (err) => {
  console.error("RPC Stream Error:", err);
});

gRPC Channel Invariants

LiopRpcClient configures symmetric channel options to ensure long-running analytical queries do not drop across stateful NATs or corporate firewalls:

Channel Option	Value	Purpose
grpc.keepalive_time_ms	30000 (30s)	Sends keepalive pings every 30 seconds to maintain open TCP state.
grpc.keepalive_timeout_ms	10000 (10s)	Awaits ping acknowledgments for up to 10 seconds before declaring dropped connection.
grpc.keepalive_permit_without_calls	1	Allows keepalive pings even when no active RPC calls are inflight.
grpc.http2.max_pings_without_data	0	Eliminates ping burst limits to prevent aggressive proxy resets.

---

Public Methods Reference

Method	Parameters	Return Type	Description
connect(address?, options?)	address?: string, options?: ConnectOptions	Promise<void>	Initializes discovery, acquires M2M tokens, and mounts transport channels.
callTool(request, wasmBuffer?)	request: CallToolRequest, wasmBuffer?: Buffer	Promise<CallToolResult>	Dispatches tool invocation with optional in-situ logic bytecode.
discoverTools()	None	Promise<ToolDefinition[]>	Queries connected peers and returns all advertised tool definitions.
listTools()	None	Promise<ToolDefinition[]>	Alias of discoverTools() providing 100% MCP client compatibility.
resolveCapability(name)	name: string	Promise<string | undefined>	Resolves peer multiaddr or endpoint advertising the given tool name.
getRoutingTable()	None	RoutingTable | undefined	Returns the active internal hybrid routing table instance.
getMeshNode()	None	MeshNode | null	Returns the underlying libp2p node instance when connected in mesh mode.
getServerInfo()	None	{ name: string; version: string } | undefined	Returns peer identification headers negotiated during handshake.
close()	None	Promise<void>	Gracefully terminates all active gRPC channels, worker pools, and P2P sockets.

---

Error Handling & Exception Catalog

LiopClient throws structured exceptions when security policies, authentication checks, or sandbox boundaries reject an execution.

import { LiopError, ErrorCode } from "@nekzus/liop";

try {
  await client.callTool({
    name: "Analyze_Bank_Ledger",
    arguments: { query: "DROP TABLE users;" },
  });
} catch (error) {
  if (error instanceof LiopError) {
    switch (error.code) {
      case ErrorCode.AST_SECURITY_VIOLATION:
        console.error("Layer 1 Rejection: Injected code accessed forbidden globals");
        break;
      case ErrorCode.UNAUTHENTICATED:
        console.error("Token Expired or Invalid: Check OAuth 2.1 credentials");
        break;
      case ErrorCode.CIRCUIT_BREAKER_OPEN:
        console.warn("Peer is currently degraded. Rerouting to standby enclave");
        break;
      default:
        console.error(`Protocol Error [${error.code}]:`, error.message);
    }
  }
}

Protocol Error Codes

Error Code	HTTP / RPC Equivalence	Cause	Recommended Action
UNAUTHENTICATED	HTTP 401 / gRPC 16	Missing, expired, or invalid OAuth 2.1 Bearer token.	Refresh credentials via TokenManager.invalidate().
FORBIDDEN	HTTP 403 / gRPC 7	Caller clearance tier does not meet resource taxonomy requirements.	Request scope elevation in Nexus OIDC console.
AST_SECURITY_VIOLATION	RPC -32099 / gRPC 3	Guardian AST detected forbidden imports or poisoned globals.	Ensure bytecode complies with strict WASI Preview 1 allowlist.
SANDBOX_HALTED	RPC -32098 / gRPC 9	V8 Isolate exceeded allocated CPU fuel or heap memory limits.	Optimize inner loops or raise maxHeapMb configuration.
CIRCUIT_BREAKER_OPEN	HTTP 503 / gRPC 14	Target endpoint reached 5 consecutive failures (MAX_FAILURES = 5).	Wait for decay interval or use alternative gateway route.
ZK_VERIFICATION_FAILED	RPC -32097 / gRPC 10	Output proof failed Groth16 pairing check, HMAC seal, or ML-DSA-65 post-quantum signature verification.	Potential active network tampering or untrusted enclave image. Drop response immediately.