PILSO Architecture

Agent → MCP CLI → Servers → Wallet → Blockchain

PILSO OS is a modular, LLM-native operating system that enables secure, natural-language-based execution of blockchain actions. Its architecture is designed to separate intent, execution, and authorization into clear, composable layers — making it both safe and deeply extensible.

At its core, PILSO connects:

• A prompting agent (LLM)

• A tooling layer (MCP servers)

• A signing layer (Web3 wallet) … to form a trust-minimized execution pipeline for onchain actions.

---

High-Level Architecture

User → LLM Agent → MCP Server(s) → Wallet (Signer) → Blockchain

Each step plays a specific role:

• LLM Agent → interprets natural language instructions

• MCP Servers → execute tool-specific blockchain operations (e.g., compiling contracts, fetching balances, generating transactions)

• Wallet → signs transactions using secure user-held keys

• Blockchain → final execution and state change

---

1. The Agent Layer

Intent parsing and agent personality

This layer handles natural language input, transforms it into structured tasks, and coordinates tool calls based on predefined roles.

Key elements:

• LLM Provider: Claude, GPT-4, DeepSeek, and others — interchangeable via config

• Agent Role: A scoped behavior template (e.g. signer, dev, watcher) defined in .roles.json

• Session Memory: Context is preserved across tasks; roles act like stateful agents

• Prompt Execution: Natural language is translated into tool calls with arguments

Example

"Deploy this contract on Optimism and verify it on Etherscan"
↓
Role: "deployer"
↓
Tool chain: solc-mcp → metamask-mcp → verify-mcp

This layer never interacts directly with wallets or private keys. It’s an instructional interface, not an execution engine.

---

2. The MCP Layer

Tool execution and response handling

This layer is the protocol bridge between the LLM and the chain.

MCP (Model Context Protocol) servers are purpose-specific tool modules. Each one runs as a local or remote server and exposes a single unit of functionality (a "tool") that agents can call.

Key architectural benefits:

• Isolation: Each server handles one task, reducing attack surface

• Modularity: Add/remove servers depending on the agent's needs

• Security: Agents cannot run arbitrary code — they invoke only whitelisted tools

• Auditability: Every tool invocation is recorded and tied to an agent prompt

Example JSON (agent → MCP call)

{
  "tool": "erc20.transfer",
  "args": {
    "token": "USDC",
    "to": "0xabc...",
    "amount": "50"
  }
}

MCP servers do not sign or broadcast transactions — they simply prepare or simulate operations.

---

3. The Wallet Layer

Authorization and final execution

This is the signing surface. It's where the final transaction, message, or operation is approved by the user, either through a local wallet or a connected signer device.

This layer is intentionally abstracted behind CLI interfaces. It is non-custodial by design:

• No keys are stored or passed to agents

• No “relayer” signs on your behalf

• All signing happens only after user-side confirmation

Benefits:

• User retains full key control

• No backend compromise can result in asset loss

• Agent mistakes can’t drain a wallet

---

Execution Flow Summary

Here’s what happens when you run a PILSO agent session:

1. Prompt is entered → "Swap 0.5 ETH to USDC on Arbitrum"

2. LLM agent parses the intent using its role’s context

3. PILSO MCP servers — chainlist for RPC, erc20-mcp for swap payload

4. Transaction is constructed and returned to CLI

5. Wallet signs the transaction (user confirms in MetaMask)

6. Signed transaction is broadcast to the chain

---

Why This Architecture?

Design Principle	Result
Separation of concerns	No component can unilaterally act
Modular composition	Easy to extend, fork, or embed
Security-first defaults	Keys are never exposed
CLI-native	Fits developer workflows
LLM-agnostic	Bring your own agent provider

---

Built to Scale

PILSO OS is not a closed system — it’s an execution protocol you can extend:

• Add new MCP tools (e.g. cross-chain swaps, DAO voting, NFT interactions)

• Run hosted agents with secure delegation

• Create permissioned agents for organizations or multisigs

• Use role configurations to enforce security policies on agent behavior

Whether you're building AI agents, crypto assistants, or next-gen wallet UX, PILSO is the operating layer that makes it safe, modular, and production-grade.