Skip to content

adrianosousa/oikos

BranchesTags

Repository files navigation

Oikos Protocol

Oikos Protocol

Sovereign Agent Wallet Protocol

License Tests TypeScript Hackathon

Pear Runtime WDK QVAC

Ethereum Bitcoin Spark ERC-8004

Process-isolated, multi-chain wallet infrastructure for autonomous AI agents.
Built on Tether's runtime stack — Bare/Pear Runtime + WDK.

Agents hold USDt, XAUt, and USAt. They reason about money, execute DeFi strategies, and trade with each other over Hyperswarm — all under policy-enforced constraints with full audit trails.

Hackathon: Tether Hackathon Galactica WDK Edition 1 (DoraHacks) Track: Track 1 — Agent Wallets Builder: Adriano Sousa

Quick Demo

git clone https://github.com/AdrianSousa/oikos.git && cd oikos
npm install    # installs deps + auto-builds TypeScript
npm run demo   # opens dashboard at localhost:3420

Zero API keys. Zero blockchain. Mock wallet with simulated agents, live policy engine, and full audit trail. Requires Node.js >= 22.

Why Oikos

Every agent wallet today is a wrapper around an API key. Oikos is different: the wallet runs in a separate process from the agent. The agent reasons. The wallet signs. They communicate over IPC. Even if the agent process is compromised, the wallet's policy engine still gates every transaction.

This is wallet infrastructure. Agent-agnostic, framework-agnostic, with six integration surfaces. And for humans, a sovereign P2P desktop app to monitor, instruct, and override their agents. No servers, no cloud, just a direct encrypted channel.

Live Demo: Agent-to-Agent Commerce

Two agents. One swarm. No intermediaries.

Agent A (Ludwig)                    Agent B (Baruch)
────────────────                    ────────────────
swarm_announce →
  SELL: Strategy file               ← swarm discovers listing
  50–200 USDT
                                    → swarm_bid (80 USDT)
swarm_accept_bid ←
swarm_deliver_result →              ← strategy file received (E2E encrypted)
  payment settles on-chain automatically
ERC-8004 reputation ←──────────────→ both agents' on-chain scores updated

Both agents hold real testnet balances. Discovery, negotiation, delivery, and settlement happen peer-to-peer over Hyperswarm — no servers, no intermediaries.

Get Started

For AI Agents

Point your agent at the skill file. It covers setup, seed generation, wallet startup, MCP tools, and policy configuration.

SKILL.md

Or connect via any integration surface: MCP Server · CLI · Direct IPC · Hyperswarm · x402

For Humans

  1. Oikos Wallet — Node.js CLI + dashboard 
    npm run demo
# localhost:3420
  2. Oikos App — Pear Runtime desktop 
    pear run --dev .
  3. Oikos Mobile — Coming soon

Brain Modes

When an external agent (OpenClaw, Claude, etc.) connects via MCP or CLI, it brings its own LLM — no brain config needed. These modes control oikos-wallet's built-in brain for standalone and companion use:

Mode Config Requirements
Mock BRAIN_TYPE=mock Nothing — deterministic demo responses
Local BRAIN_TYPE=ollama Ollama/QVAC running with any model. We used oikos-agent model (Qwen 3 4B fine-tuned)
Remote BRAIN_TYPE=http Any OpenAI-compatible endpoint (LLM_BASE_URL + LLM_API_KEY)

Architecture

                         Oikos Protocol
  ┌─────────────────────────────────────────────────────────────┐
  │                                                             │
  │  ┌─────────────────────┐    IPC     ┌────────────────────┐  │
  │  │    OIKOS-WALLET     │ stdin/out  │   WALLET ISOLATE   │  │
  │  │    (Node.js)        │ ◄────────► │   (Bare Runtime)   │  │
  │  │                     │ JSON-lines │                    │  │
  │  │  ┌───────────────┐  │            │  ┌──────────────┐  │  │
  │  │  │ Hyperswarm    │  │            │  │ WDK Core     │  │  │
  │  │  │ Agent Swarm   │  │            │  │ Keys + Signer│  │  │
  │  │  └───────────────┘  │            │  └──────────────┘  │  │
  │  │  ┌───────────────┐  │            │  ┌──────────────┐  │  │
  │  │  │ MCP Server    │  │            │  │ PolicyEngine │  │  │
  │  │  │ Dashboard     │  │            │  │ 8 Rule Types |  │  │
  │  │  └───────────────┘  │            │  └──────────────┘  │  │
  │  │  ┌───────────────┐  │            │  ┌──────────────┐  │  │
  │  │  │ CLI + x402    │  │            │  │ Audit Log    │  │  │
  │  │  │ + RGB         │  │            │  │ Append-Only  │  │  │
  │  │  └───────────────┘  │            │  └──────────────┘  │  │
  │  └─────────────────────┘            └────────────────────┘  │
  │                                                             │
  │  ┌───────────────────────────────────────────────────────┐  │
  │  │                  INTEGRATION LAYER                    │  │
  │  │  OpenClaw │ MCP │ CLI │ IPC │ Hyperswarm │ x402       │  │
  │  └───────────────────────────────────────────────────────┘  │
  └─────────────────────────────────────────────────────────────┘
         ▲                    ▲                    ▲
         │                    │                    │
    Oikos App            Any Agent              x402 Clients
    (Pear Runtime)      (MCP/REST/CLI)      (Machine Payments)
Layer Description
Wallet Protocol Process-isolated, policy-enforced multi-chain wallet on Bare Runtime
oikos-wallet Agent-agnostic infrastructure: MCP, CLI, dashboard, swarm, x402
Agent Swarm Multi-agent trading over Hyperswarm with Noise E2E encryption
Oikos App Pear Runtime P2P desktop app — monitor, instruct, override

Oikos App

A sovereign desktop application built on Pear Runtime. No servers, no cloud — connects directly to your agent over a Hyperswarm Noise-encrypted P2P channel, authenticated with Ed25519 keypairs.

Tab What you get
Feed Real-time activity stream — payments, swaps, bridges, yield, swarm events. Full audit log with status and error details.
Wealth Portfolio valuation, asset allocation chart, live prices (Bitfinex), multi-chain balance breakdown, recent transactions.
Swarm Marketplace announcements, peer count, reputation score, economics dashboard (revenue, costs, open/closed deals), tag-based filtering.
Policy Engine Edit guardrails (budgets, cooldowns, time windows, confidence thresholds). Manage strategies — load, toggle, approve/reject. View loaded modules.

Chat panel — Always visible. Natural language instructions to the agent with markdown-rendered reasoning responses. Every instruction becomes a policy-evaluated proposal.

Pairing — First launch generates an Ed25519 keypair. Exchange pubkeys with your agent. Mutual Noise handshake. No passwords, no accounts.

The app never talks to the Wallet Isolate directly. It talks to the Agent Brain, which translates instructions into IPC proposals. Process isolation is preserved.

Features

  • Multi-chain — Bitcoin testnet + Sepolia (EVM) + any WDK-supported chain
  • Multi-asset — USDt, XAUt, USAt, BTC, ETH (all three mandatory Tether assets)
  • DeFi operations — Swaps, bridges, yield — all policy-enforced
  • PolicyEngine — 8 rule types: per-tx limits, session caps, daily budgets, cooldowns, confidence thresholds, whitelists, time windows
  • Agent Swarm — Hyperswarm DHT discovery, two-layer topic model (public board + private rooms), audit-derived reputation
  • x402 Machine Payments — HTTP 402 protocol for commodity services with EIP-3009 signing
  • ERC-8004 On-Chain Identity — Trustless Agents standard for Sybil-resistant agent reputation
  • Live pricing — Bitfinex real-time feed via WDK pricing modules
  • Encrypted seed management — PBKDF2-SHA256 + XSalsa20-Poly1305 via WDK SecretManager
  • Sovereign AI — Qwen 3 4B, Q8-quantized, LoRA fine-tuned on custom Oikos dataset via Unsloth, running on QVAC Fabric LLM — zero cloud dependencies
  • 140 tests passing — TypeScript strict mode, zero any types

Testnet note: All operations currently run on Sepolia (EVM) and Bitcoin testnet. The architecture is mainnet-ready — switching to production requires funded wallets and live RPC endpoints, no code changes. DeFi operations (swaps, bridges, yield) use mock implementations in testnet/demo mode.

On-Chain Agent Identity (ERC-8004)

Oikos implements the ERC-8004 Trustless Agents standard — the first live agent identity protocol on Ethereum.

When an agent receives its first ETH, it automatically:

  1. Mints an ERC-721 NFT on the IdentityRegistry contract (Sepolia)
  2. Links its wallet address via EIP-712 signed setAgentWallet
  3. Begins accumulating on-chain reputation via tagged feedback after every swarm settlement
Agent starts → funded → NFT minted → agentId assigned → reputation grows

Why it matters: Any agent can verify a counterparty's track record before trading. No trust assumptions, no intermediaries — just on-chain history.

Contracts live on Sepolia:

  • IdentityRegistry: 0x8004A818BFB912233c491871b3d84c89A494BD9e
  • ReputationRegistry: 0x8004B663056A597Dffe9eCcC1965A193B7388713

Integration Surfaces

Surface Protocol Use Case
OpenClaw Skill SKILL.md Agent reads one URL, installs wallet, pairs Oikos App via Hyperswarm, and operates full DeFi + swarm from any chat interface. Zero config.
MCP Server 21 tools via JSON-RPC 2.0 Any MCP-compatible agent framework
CLI oikos commands Shell agents, human operators, scripting
Direct IPC stdin/stdout JSON-lines Embedded use in custom agent processes
Hyperswarm P2P Noise-encrypted protomux Agent-to-agent discovery and negotiation
x402 Payments HTTP 402 + EIP-3009 Machine-to-machine commodity payments

Security

  • Process isolation — Wallet Isolate runs in a separate Bare Runtime process. It holds keys, enforces policy, signs transactions. The oikos-wallet process never sees seed material.
  • Single code path — One path moves funds: PolicyEngine.evaluate() → PaymentExecutor.execute(). All proposal types go through it.
  • Immutable policy — Policies load from JSON at startup. No IPC message can modify them.
  • Append-only audit — Every proposal is recorded. Entries never contain seeds, private keys, or API keys.
  • Encrypted seeds — WDK SecretManager with PBKDF2-SHA256 key derivation and XSalsa20-Poly1305 authenticated encryption.
  • 140 tests prove — Rejected proposals never reach the signer. Malformed IPC is dropped. Audit log is append-only.

Testing

npm test

140 tests, 0 failures across two workspaces:

  • wallet-isolate (105 tests) — PolicyEngine rules, executor rejection proofs, IPC validation, audit guarantees, encrypted seed manager, ERC-8004 encoding
  • oikos-wallet (35 tests) — Swarm topics, reputation scoring, companion auth, x402 flows, MCP handlers

Tech Stack

Wallet Isolate (Bare Runtime)

Package Purpose
@tetherto/wdk Core wallet development kit
@tetherto/wdk-wallet-btc Bitcoin wallet module
@tetherto/wdk-wallet-evm EVM wallet module (Sepolia)
@tetherto/wdk-secret-manager Encrypted seed persistence

oikos-wallet (Node.js)

Package Purpose
hyperswarm P2P DHT discovery + Noise encryption
protomux Multiplexed protocol channels
express Dashboard HTTP server (localhost-only)
@tetherto/wdk-pricing-bitfinex-http Live Bitfinex price feed

Sovereign AI

Component Details
Base model Qwen 3 4B
Quantization Q8 (8-bit GGUF)
Fine-tuning LoRA via Unsloth, trained on custom Oikos dataset
Inference QVAC Fabric LLM — Tether's edge-first runtime (Vulkan API)

Future Endeavors

  • Mobile Oikos App — Pear Runtime cross-platform (iOS + Android), native mobile UI via Bare Kit.
  • Mainnet launch — Ethereum + Bitcoin mainnet, live USDT/XAUT/USAT.
  • QVAC + BitNet b1.58 — Natively ternary (1.58-bit) model, LoRA fine-tuned on QVAC Fabric. On-device inference with near-zero power draw.
  • MPP (Machine Payments Protocol) — Tempo/Stripe's open standard for agent payments via HTTP 402 + Shared Payment Tokens. Complementary to x402 — supporting stablecoin and fiat settlement.
  • RGB Protocol — Full client-validated smart contract implementation with Hyperswarm-based consignment transfer for off-chain RGB state exchange.

Third-Party Disclosures

All dependencies are open source:

  • @tetherto/wdk ecosystem — Wallet, chain modules, DeFi protocols, pricing, secret manager (Tether / ISC)
  • Hyperswarm + Protomux — P2P networking stack (Holepunch / MIT)
  • Express — HTTP server for localhost dashboard (MIT)
  • OpenAI SDK — LLM client, used with QVAC (Apache 2.0)
  • sodium-universal — Cryptographic primitives (MIT)
  • Unsloth — LoRA fine-tuning framework (Apache 2.0)
  • QVAC Fabric LLM — Tether's edge inference runtime (Apache 2.0)

Apache License 2.0

About

Multi-chain wallet infrastructure for AI agents. Built on Tether's WDK.

reshimulabs.com/oikos

Resources

Readme

License

Apache-2.0 license

Security policy

Security policy
Activity

Stars

2 stars

Watchers

0 watching

Forks

2 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages