logos-layer 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dtzrr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,44 @@
+# logos-layer
+
+An MCP server that lets an AI agent trade inside a mandate-guarded vault on Robinhood Chain. The vault's on-chain guard enforces the mandate on every order: compliant orders execute, violations revert with the exact rule they broke. The guard does not care how smart the agent is.
+
+## Tools
+
+- `get_portfolio`: the vault's current cash, positions, prices, and mandate thresholds
+- `check_order`: preview an order against the mandate before sending it
+- `execute_order`: submit an order; the chain reverts anything the mandate forbids
+
+## Setup
+
+Add to your MCP client config (Claude Desktop, Claude Code, or any MCP client):
+
+```json
+{
+  "mcpServers": {
+    "logos-layer": {
+      "command": "npx",
+      "args": ["-y", "logos-layer"],
+      "env": {
+        "VAULT_ADDRESS": "<your-vault-address>",
+        "RPC_URL": "https://rpc.testnet.chain.robinhood.com",
+        "PRIVATE_KEY": "<your-agent-wallet-key>"
+      }
+    }
+  }
+}
+```
+
+Requires Node 20+.
+
+| Env | Required | Meaning |
+| --- | --- | --- |
+| `VAULT_ADDRESS` | yes | The deployed vault the agent trades inside |
+| `RPC_URL` | yes | Robinhood Chain RPC endpoint |
+| `PRIVATE_KEY` | yes | The agent wallet key; must be the vault owner to trade |
+| `EXPLORER_URL` | no | Explorer base URL for transaction links |
+
+## Safety
+
+The agent wallet must be the vault owner to trade, so use the key you deployed the vault with. Never use a key that holds real funds. Testnet instruments only; this is a research demo, not investment advice.
+
+This package ships as a compiled artifact.

package/dist/index.js

@@ -0,0 +1,303 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  createPublicClient,
+  createWalletClient,
+  defineChain,
+  http,
+  parseAbi
+} from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { z } from "zod";
+
+// ../mandate-schema/src/index.ts
+var ASSETS = ["AMZN", "TSLA", "NFLX", "GOOG", "AAPL"];
+var RULES = [
+  {
+    id: 1,
+    name: "Concentration limit",
+    english: "The market value of any single security shall not exceed 20% of the total Account value."
+  },
+  {
+    id: 2,
+    name: "Minimum cash reserve",
+    english: "The Account shall at all times maintain a cash balance of no less than 5% of the total Account value."
+  },
+  {
+    id: 3,
+    name: "Prohibition on leverage",
+    english: "The cash balance shall not at any time be negative."
+  },
+  {
+    id: 4,
+    name: "Prohibition on short sales",
+    english: "The quantity held of each security shall at all times be greater than or equal to zero."
+  },
+  {
+    id: 5,
+    name: "Order size limitation",
+    english: "No single order shall have a notional value exceeding 10% of the total Account value immediately prior to the order."
+  }
+];
+
+// ../checker-ts/src/rat.ts
+function gcd(a, b) {
+  a = a < 0n ? -a : a;
+  b = b < 0n ? -b : b;
+  while (b !== 0n) [a, b] = [b, a % b];
+  return a;
+}
+function rat(n, d = 1n) {
+  if (d === 0n) throw new Error("rat: zero denominator");
+  if (d < 0n) {
+    n = -n;
+    d = -d;
+  }
+  const g = gcd(n, d);
+  return g === 0n ? { n: 0n, d: 1n } : { n: n / g, d: d / g };
+}
+var ZERO = rat(0n);
+function fromInt(n) {
+  return rat(BigInt(n));
+}
+function add(a, b) {
+  return rat(a.n * b.d + b.n * a.d, a.d * b.d);
+}
+function sub(a, b) {
+  return rat(a.n * b.d - b.n * a.d, a.d * b.d);
+}
+function mul(a, b) {
+  return rat(a.n * b.n, a.d * b.d);
+}
+function abs(a) {
+  return { n: a.n < 0n ? -a.n : a.n, d: a.d };
+}
+function le(a, b) {
+  return a.n * b.d <= b.n * a.d;
+}
+function toNumber(a) {
+  return Number(a.n) / Number(a.d);
+}
+
+// ../checker-ts/src/checker.ts
+var BPS_DEN = fromInt(1e4);
+function totalValue(p, prices) {
+  let acc = p.cash;
+  for (const a of ASSETS) acc = add(acc, mul(p.positions[a], prices[a]));
+  return acc;
+}
+function applyOrder(p, o, prices) {
+  const positions = { ...p.positions };
+  positions[o.asset] = add(positions[o.asset], o.qty);
+  return {
+    cash: sub(p.cash, mul(o.qty, prices[o.asset])),
+    positions
+  };
+}
+function checkRules(m, prices, p, o) {
+  const tv = totalValue(p, prices);
+  const post = applyOrder(p, o, prices);
+  const postTv = totalValue(post, prices);
+  return {
+    // rule 1: single-asset cap — 10000·(pos·price) ≤ maxAssetBps·postTv
+    1: ASSETS.every(
+      (a) => le(mul(BPS_DEN, mul(post.positions[a], prices[a])), mul(m.maxAssetBps, postTv))
+    ),
+    // rule 2: cash floor — minCashBps·postTv ≤ 10000·cash
+    2: le(mul(m.minCashBps, postTv), mul(BPS_DEN, post.cash)),
+    // rule 3: no leverage — 0 ≤ cash
+    3: le(ZERO, post.cash),
+    // rule 4: no shorts — 0 ≤ position, all assets
+    4: ASSETS.every((a) => le(ZERO, post.positions[a])),
+    // rule 5: throttle — 10000·|qty·price| ≤ maxOrderBps·tv (pre-trade)
+    5: le(mul(BPS_DEN, abs(mul(o.qty, prices[o.asset]))), mul(m.maxOrderBps, tv))
+  };
+}
+function firstViolation(m, prices, p, o) {
+  const r = checkRules(m, prices, p, o);
+  for (const id of [1, 2, 3, 4, 5]) if (!r[id]) return id;
+  return null;
+}
+
+// src/index.ts
+var VAULT = requireEnv("VAULT_ADDRESS");
+var RPC_URL = requireEnv("RPC_URL");
+var PRIVATE_KEY = requireEnv("PRIVATE_KEY");
+var EXPLORER_URL = process.env.EXPLORER_URL;
+function requireEnv(name) {
+  const v = process.env[name];
+  if (!v) {
+    console.error(`Missing required env var ${name}`);
+    process.exit(1);
+  }
+  return v;
+}
+var vaultAbi = parseAbi([
+  "struct Portfolio { int256 cash; int256[5] positions; }",
+  "function portfolio() view returns (Portfolio)",
+  "function mandate() view returns (int256 maxAssetBps, int256 minCashBps, int256 maxOrderBps)",
+  "function prices(uint256) view returns (int256)",
+  "function preview(uint8 asset, int256 qty) view returns (bool ok, uint8 ruleId)",
+  "function execute(uint8 asset, int256 qty) returns (uint256)",
+  "error MandateViolation(uint8 ruleId)"
+]);
+var account = privateKeyToAccount(
+  PRIVATE_KEY.startsWith("0x") ? PRIVATE_KEY : `0x${PRIVATE_KEY}`
+);
+async function makeClients() {
+  const probe = createPublicClient({ transport: http(RPC_URL) });
+  const chainId = await probe.getChainId();
+  const chain = defineChain({
+    id: chainId,
+    name: `chain-${chainId}`,
+    nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
+    rpcUrls: { default: { http: [RPC_URL] } }
+  });
+  return {
+    publicClient: createPublicClient({ chain, transport: http(RPC_URL) }),
+    walletClient: createWalletClient({ account, chain, transport: http(RPC_URL) })
+  };
+}
+var { publicClient, walletClient } = await makeClients();
+async function readVault() {
+  const [portfolio, mandate, ...priceResults] = await Promise.all([
+    publicClient.readContract({ address: VAULT, abi: vaultAbi, functionName: "portfolio" }),
+    publicClient.readContract({ address: VAULT, abi: vaultAbi, functionName: "mandate" }),
+    ...ASSETS.map(
+      (_, i) => publicClient.readContract({
+        address: VAULT,
+        abi: vaultAbi,
+        functionName: "prices",
+        args: [BigInt(i)]
+      })
+    )
+  ]);
+  const positions = Object.fromEntries(
+    ASSETS.map((a, i) => [a, Number(portfolio.positions[i])])
+  );
+  const prices = Object.fromEntries(
+    ASSETS.map((a, i) => [a, Number(priceResults[i])])
+  );
+  const nav = Number(portfolio.cash) + ASSETS.reduce((acc, a) => acc + positions[a] * prices[a], 0);
+  return {
+    cash: Number(portfolio.cash),
+    positions,
+    prices,
+    mandate: {
+      maxAssetPct: Number(mandate[0]) / 100,
+      minCashPct: Number(mandate[1]) / 100,
+      maxOrderPct: Number(mandate[2]) / 100
+    },
+    nav
+  };
+}
+function localVerdict(state, asset, signedQty) {
+  const m = {
+    maxAssetBps: fromInt(Math.round(state.mandate.maxAssetPct * 100)),
+    minCashBps: fromInt(Math.round(state.mandate.minCashPct * 100)),
+    maxOrderBps: fromInt(Math.round(state.mandate.maxOrderPct * 100))
+  };
+  const p = {
+    cash: fromInt(state.cash),
+    positions: Object.fromEntries(
+      ASSETS.map((a) => [a, fromInt(state.positions[a])])
+    )
+  };
+  const pr = Object.fromEntries(
+    ASSETS.map((a) => [a, fromInt(state.prices[a])])
+  );
+  const o = { asset, qty: fromInt(signedQty) };
+  const rules = checkRules(m, pr, p, o);
+  const post = applyOrder(p, o, pr);
+  return {
+    rules,
+    firstViolation: firstViolation(m, pr, p, o),
+    postNav: toNumber(totalValue(post, pr))
+  };
+}
+var orderShape = {
+  asset: z.enum(ASSETS).describe("Asset symbol to trade"),
+  side: z.enum(["buy", "sell"]).describe("Order side"),
+  quantity: z.number().int().positive().describe("Number of shares")
+};
+function describeVerdict(state, asset, side, quantity) {
+  const signedQty = side === "buy" ? quantity : -quantity;
+  const v = localVerdict(state, asset, signedQty);
+  const lines = RULES.map((r) => {
+    const pass = v.rules[r.id];
+    return `  rule ${r.id} ${pass ? "PASS" : "FAIL"} \u2014 ${r.name}`;
+  });
+  return { signedQty, verdict: v, ruleLines: lines.join("\n") };
+}
+var server = new McpServer({ name: "logos-layer", version: "0.1.0" });
+server.tool(
+  "get_portfolio",
+  "Read the vault's on-chain portfolio: cash, positions, prices, NAV, and the mandate thresholds that every trade must satisfy.",
+  {},
+  async () => {
+    const s = await readVault();
+    const text = [
+      `Vault ${VAULT}`,
+      `NAV $${s.nav.toLocaleString("en-US")}  \xB7  cash $${s.cash.toLocaleString("en-US")}`,
+      ...ASSETS.map(
+        (a) => `  ${a}: ${s.positions[a]} shares @ $${s.prices[a]} = $${(s.positions[a] * s.prices[a]).toLocaleString("en-US")}`
+      ),
+      "",
+      `Mandate (enforced on-chain, proven in Lean):`,
+      `  concentration cap ${s.mandate.maxAssetPct}% of NAV per asset`,
+      `  cash floor ${s.mandate.minCashPct}% of NAV`,
+      `  order throttle ${s.mandate.maxOrderPct}% of pre-trade NAV`,
+      `  no leverage, no short sales`
+    ].join("\n");
+    return { content: [{ type: "text", text }] };
+  }
+);
+server.tool(
+  "check_order",
+  "Dry-run an order against the formally verified compliance checker without sending a transaction. Returns the verdict of each mandate rule.",
+  orderShape,
+  async ({ asset, side, quantity }) => {
+    const s = await readVault();
+    const { verdict, ruleLines } = describeVerdict(s, asset, side, quantity);
+    const ok = verdict.firstViolation === null;
+    const text = [
+      `${side.toUpperCase()} ${quantity} ${asset} \u2192 ${ok ? `PASS. Trade would execute; post-trade NAV $${verdict.postNav.toLocaleString("en-US")}.` : `FAIL. On-chain this reverts MandateViolation(${verdict.firstViolation}).`}`,
+      ruleLines
+    ].join("\n");
+    return { content: [{ type: "text", text }] };
+  }
+);
+server.tool(
+  "execute_order",
+  "Execute an order on-chain through the mandate guard. Compliant orders execute and update the portfolio; non-compliant orders are refused before sending (the contract would revert them regardless).",
+  orderShape,
+  async ({ asset, side, quantity }) => {
+    const s = await readVault();
+    const { signedQty, verdict, ruleLines } = describeVerdict(s, asset, side, quantity);
+    if (verdict.firstViolation !== null) {
+      const rule = RULES.find((r) => r.id === verdict.firstViolation);
+      const text2 = [
+        `REFUSED: ${side.toUpperCase()} ${quantity} ${asset} violates rule ${verdict.firstViolation} (${rule?.name}).`,
+        `The on-chain guard would revert this with MandateViolation(${verdict.firstViolation}); not sending the transaction.`,
+        ruleLines
+      ].join("\n");
+      return { content: [{ type: "text", text: text2 }] };
+    }
+    const hash = await walletClient.writeContract({
+      address: VAULT,
+      abi: vaultAbi,
+      functionName: "execute",
+      args: [ASSETS.indexOf(asset), BigInt(signedQty)]
+    });
+    const receipt = await publicClient.waitForTransactionReceipt({ hash });
+    const link = EXPLORER_URL ? `
+${EXPLORER_URL}/tx/${hash}` : "";
+    const text = receipt.status === "success" ? `EXECUTED: ${side.toUpperCase()} ${quantity} ${asset} in block ${receipt.blockNumber}. Post-trade NAV $${verdict.postNav.toLocaleString("en-US")}.${link}` : `REVERTED on-chain (block ${receipt.blockNumber}). The guard refused the trade.${link}`;
+    return { content: [{ type: "text", text }] };
+  }
+);
+await server.connect(new StdioServerTransport());
+console.error(`aristotem-vault MCP server ready \xB7 vault ${VAULT} \xB7 agent ${account.address}`);

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "logos-layer",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Logos Layer: an MCP server that lets AI agents trade inside a mandate-guarded vault on Robinhood Chain. Compliant orders execute; violations revert on-chain.",
+  "license": "MIT",
+  "bin": {
+    "logos-layer": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsup",
+    "start": "node dist/index.js",
+    "prepublishOnly": "pnpm build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "viem": "^2.55.8",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@pct/checker-ts": "workspace:*",
+    "@pct/mandate-schema": "workspace:*",
+    "tsup": "^8.5.0"
+  }
+}