# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.pil.so/core-concepts/pilso-architecture.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.