# PILSO Architecture

**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**

```plaintext
"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)**

```json
{
  "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.