@unicitylabs/openclaw-unicity 0.1.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Unicity Labs
+
+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,285 @@
+# Unicity wallet plugin for [OpenClaw](https://github.com/openclaw/openclaw) agents
+
+<p align="center">
+  <img src="logo.png" alt="Unicity" width="300" />
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@unicitylabs/openclaw-unicity"><img src="https://img.shields.io/npm/v/@unicitylabs/openclaw-unicity" alt="npm version" /></a>
+  <a href="https://github.com/unicitynetwork/openclaw-unicity/blob/main/LICENSE"><img src="https://img.shields.io/github/license/unicitynetwork/openclaw-unicity" alt="license" /></a>
+</p>
+
+---
+
+**Unicity** is an [OpenClaw](https://github.com/openclaw/openclaw) plugin that gives your AI agent a Unicity wallet identity and the ability to send and receive encrypted direct messages over Unicity's private Nostr relay network, powered by the [Unicity Sphere SDK](https://github.com/unicitylabs/sphere-sdk).
+
+## Features
+
+- **Wallet identity** — Auto-generates a Unicity wallet on first run (BIP-32 HD wallet with mnemonic backup)
+- **Nametag minting** — Register a human-readable `@nametag` for your agent on the Unicity network
+- **Encrypted DMs** — Send and receive direct messages over Unicity's private Nostr relays
+- **Token management** — Send/receive tokens, check balances, view transaction history
+- **Payment requests** — Request payments from other users, accept/reject/pay incoming requests
+- **Faucet top-up** — Request test tokens on testnet via built-in faucet tool
+- **Agent tools** — 9 tools for messaging, wallet operations, and payments (see [Agent Tools](#agent-tools))
+- **OpenClaw channel** — Full channel plugin with inbound/outbound message handling, status reporting, and DM access control
+- **Interactive setup** — `openclaw unicity setup` wizard and `openclaw onboard` integration
+- **CLI commands** — `openclaw unicity init`, `status`, `send`, and `listen` for wallet management
+
+## Quick Start
+
+### 1. Install the plugin
+
+```bash
+openclaw plugins install @unicitylabs/openclaw-unicity
+```
+
+To update to the latest version later:
+
+```bash
+openclaw plugins update openclaw-unicity
+```
+
+### 2. Run interactive setup
+
+```bash
+openclaw unicity setup
+```
+
+This walks you through choosing a nametag, owner, and network, then writes the config for you.
+
+Alternatively, Unicity integrates with OpenClaw's onboarding wizard:
+
+```bash
+openclaw onboard
+```
+
+### 3. Start the gateway
+
+```bash
+openclaw gateway start
+```
+
+On first start, Unicity auto-generates a wallet and mints your chosen nametag. The mnemonic backup is saved to `~/.openclaw/unicity/mnemonic.txt` (owner-only permissions).
+
+That's it. Your agent can now send and receive encrypted DMs on the Unicity network.
+
+## Manual Configuration
+
+If you prefer to edit config directly, add to `~/.openclaw/openclaw.json`:
+
+```json5
+{
+  // Plugin settings (identity, owner, network)
+  "plugins": {
+    "entries": {
+      "unicity": {
+        "enabled": true,
+        "config": {
+          "nametag": "my-agent",        // Optional: register a @nametag
+          "owner": "alice",             // Nametag or pubkey of the trusted human owner
+          "network": "testnet",         // testnet (default) | mainnet | dev
+          "additionalRelays": [         // Optional: extra Nostr relays
+            "wss://custom-relay.example.com"
+          ]
+        }
+      }
+    }
+  },
+
+  // Channel settings (DM access control)
+  "channels": {
+    "unicity": {
+      "enabled": true,
+      "dmPolicy": "open",            // open | pairing | allowlist | disabled
+      "allowFrom": ["@trusted-user"] // Required when dmPolicy is "allowlist"
+    }
+  }
+}
+```
+
+Config changes take effect on the next gateway restart — no need to reinstall the plugin.
+
+### Owner trust model
+
+The `owner` field identifies the human who controls the agent. When set:
+
+- **Only the owner** can give the agent commands, change its behavior, or instruct it to perform actions via DMs.
+- **Anyone else** can chat with the agent — negotiate deals, discuss topics, ask questions — but the agent will not follow operational commands from non-owner senders.
+- Owner matching works by nametag or public key (case-insensitive, `@` prefix optional).
+
+## CLI Commands
+
+### Interactive setup
+
+```bash
+openclaw unicity setup
+```
+
+Prompts for nametag, owner, and network, then writes the config file. Run this once to get started, or re-run to change settings.
+
+### Initialize wallet
+
+```bash
+openclaw unicity init
+```
+
+Creates a new wallet (if one doesn't exist), displays the public key and address, and mints the configured nametag. The mnemonic is automatically saved to `~/.openclaw/unicity/mnemonic.txt` (owner-only permissions).
+
+### Check status
+
+```bash
+openclaw unicity status
+```
+
+Shows network, public key, address, and nametag.
+
+## Agent Tools
+
+Once the plugin is loaded, the agent has access to the following tools:
+
+### Messaging
+
+| Tool | Description |
+|------|-------------|
+| `unicity_send_message` | Send an encrypted DM to a nametag or public key |
+
+### Wallet & Balances
+
+| Tool | Description |
+|------|-------------|
+| `unicity_get_balance` | Check token balances (optionally filtered by coin) |
+| `unicity_list_tokens` | List individual tokens with status and creation time |
+| `unicity_get_transaction_history` | View recent transactions (sent/received) |
+
+### Transfers & Payments
+
+| Tool | Description |
+|------|-------------|
+| `unicity_send_tokens` | Transfer tokens to a recipient (requires owner instruction) |
+| `unicity_request_payment` | Send a payment request to another user |
+| `unicity_list_payment_requests` | View incoming/outgoing payment requests |
+| `unicity_respond_payment_request` | Pay, accept, or reject a payment request |
+| `unicity_top_up` | Request test tokens from the faucet (testnet only) |
+
+Recipients can be specified as a `@nametag` or a 64-character hex public key.
+
+**Examples:**
+
+> "Send a message to @alice saying hello"
+>
+> "What's my balance?"
+>
+> "Send 100 UCT to @bob for the pizza"
+>
+> "Top up 50 USDU from the faucet"
+
+### Receive messages
+
+When the gateway is running, incoming DMs, token transfers, and payment requests are automatically routed to the agent's reply pipeline. The agent receives the event, processes it, and replies are delivered back as encrypted DMs.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────┐
+│  OpenClaw Gateway                               │
+│                                                 │
+│  ┌────────────┐   ┌──────────┐   ┌───────────┐  │
+│  │  Unicity   │──▶│  Sphere  │──▶│  Unicity  │  │
+│  │  Plugin    │◀──│  SDK     │◀──│  Relays   │  │
+│  └────────────┘   └──────────┘   └───────────┘  │
+│       │                                         │
+│       ▼                                         │
+│  ┌───────────┐                                  │
+│  │  Agent    │                                  │
+│  │  Pipeline │                                  │
+│  └───────────┘                                  │
+└─────────────────────────────────────────────────┘
+```
+
+- **Plugin service** starts the Sphere SDK, creates/loads the wallet, and connects to Unicity relays
+- **Gateway adapter** listens for inbound DMs, token transfers, and payment requests, dispatching them through OpenClaw's reply pipeline
+- **Outbound adapter** delivers agent replies as encrypted DMs
+- **Agent tools** (9 tools) allow the agent to send messages, manage tokens, and handle payments
+
+## Data Storage
+
+| Path | Contents |
+|------|----------|
+| `~/.openclaw/unicity/` | Wallet data (keys, state) |
+| `~/.openclaw/unicity/mnemonic.txt` | Mnemonic backup (mode 0600) |
+| `~/.openclaw/unicity/tokens/` | Token storage |
+| `~/.openclaw/unicity/trustbase.json` | Cached BFT trustbase (auto-downloaded) |
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `UNICITY_TRUSTBASE_URL` | Override the BFT trustbase download URL | GitHub raw URL |
+| `UNICITY_FAUCET_URL` | Override the faucet API endpoint | `https://faucet.unicity.network/api/v1/faucet/request` |
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run E2E tests (requires network, skipped in CI)
+npm run test:e2e
+
+# Lint
+npm run lint
+```
+
+## Project Structure
+
+```
+unicity/
+├── src/
+│   ├── index.ts              # Plugin entry point & registration
+│   ├── config.ts             # Configuration schema & validation
+│   ├── validation.ts         # Shared validation (nametag regex, recipient format)
+│   ├── sphere.ts             # Sphere SDK singleton lifecycle
+│   ├── channel.ts            # Channel plugin (7 adapters + onboarding)
+│   ├── assets.ts             # Asset registry & decimal conversion
+│   ├── setup.ts              # Interactive setup wizard
+│   ├── cli-prompter.ts       # WizardPrompter adapter for CLI
+│   ├── resources/
+│   │   └── unicity-ids.testnet.json  # Fungible asset metadata
+│   └── tools/
+│       ├── send-message.ts           # Send encrypted DMs
+│       ├── get-balance.ts            # Check wallet balances
+│       ├── list-tokens.ts            # List individual tokens
+│       ├── get-transaction-history.ts # View transaction history
+│       ├── send-tokens.ts            # Transfer tokens
+│       ├── request-payment.ts        # Request payment from a user
+│       ├── list-payment-requests.ts  # View payment requests
+│       ├── respond-payment-request.ts # Pay/accept/reject requests
+│       └── top-up.ts                 # Testnet faucet
+├── test/
+│   ├── config.test.ts
+│   ├── assets.test.ts
+│   ├── sphere.test.ts
+│   ├── sphere.integration.test.ts
+│   ├── channel.test.ts
+│   ├── index.test.ts
+│   ├── tools/                # One test file per tool
+│   └── e2e/
+│       └── wallet.test.ts    # End-to-end wallet + DM + transfer tests
+├── openclaw.plugin.json      # Plugin manifest
+├── package.json
+├── vitest.config.ts
+├── vitest.e2e.config.ts
+├── LICENSE
+└── README.md
+```
+
+## License
+
+[MIT](LICENSE)

package/openclaw.plugin.json

@@ -0,0 +1,26 @@
+{
+  "id": "unicity",
+  "channels": ["unicity"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "network": {
+        "type": "string",
+        "enum": ["testnet", "mainnet", "dev"],
+        "default": "testnet"
+      },
+      "nametag": {
+        "type": "string"
+      },
+      "owner": {
+        "type": "string",
+        "description": "Nametag or public key of the trusted human owner. Only the owner can give commands to the agent."
+      },
+      "additionalRelays": {
+        "type": "array",
+        "items": { "type": "string" }
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@unicitylabs/openclaw-unicity",
+  "version": "0.1.6",
+  "description": "Unicity wallet identity and encrypted DMs for OpenClaw agents — powered by Sphere SDK",
+  "type": "module",
+  "main": "src/index.ts",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/unicitynetwork/openclaw-unicity.git"
+  },
+  "homepage": "https://github.com/unicitynetwork/openclaw-unicity#readme",
+  "bugs": {
+    "url": "https://github.com/unicitynetwork/openclaw-unicity/issues"
+  },
+  "keywords": [
+    "unicity",
+    "openclaw",
+    "nostr",
+    "wallet",
+    "agent",
+    "dm",
+    "sphere-sdk"
+  ],
+  "files": [
+    "src/**/*",
+    "openclaw.plugin.json",
+    "LICENSE",
+    "README.md"
+  ],
+  "openclaw": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:e2e": "vitest run --config vitest.e2e.config.ts",
+    "lint": "oxlint src/ test/"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.10.0",
+    "@sinclair/typebox": "^0.34.48",
+    "@unicitylabs/sphere-sdk": "^0.1.9"
+  },
+  "peerDependencies": {
+    "openclaw": "*"
+  },
+  "devDependencies": {
+    "openclaw": "latest",
+    "oxlint": "^1.43.0",
+    "vitest": "^4.0.18"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}

package/src/assets.ts

@@ -0,0 +1,164 @@
+/** Asset registry — loads coin metadata from unicity-ids JSON. */
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+interface AssetEntry {
+  network: string;
+  assetKind: string;
+  name: string;
+  symbol?: string;
+  decimals?: number;
+  description?: string;
+  id: string;
+}
+
+interface AssetRegistry {
+  /** Map from lowercase name, symbol, or coin id to coin name */
+  aliases: Map<string, string>;
+  /** Map from coin name to symbol */
+  symbols: Map<string, string>;
+  /** Map from coin name to decimals */
+  decimals: Map<string, number>;
+  /** Map from coin name to coin id */
+  coinIds: Map<string, string>;
+  /** List of all available symbols */
+  availableSymbols: string[];
+}
+
+let cachedRegistry: AssetRegistry | null = null;
+
+function loadRegistry(): AssetRegistry {
+  if (cachedRegistry) return cachedRegistry;
+
+  const jsonPath = join(__dirname, "resources", "unicity-ids.testnet.json");
+  const raw = readFileSync(jsonPath, "utf-8");
+  const entries: AssetEntry[] = JSON.parse(raw);
+
+  const aliases = new Map<string, string>();
+  const symbols = new Map<string, string>();
+  const decimals = new Map<string, number>();
+  const coinIds = new Map<string, string>();
+  const availableSymbols: string[] = [];
+
+  for (const entry of entries) {
+    // Only include fungible assets
+    if (entry.assetKind !== "fungible") continue;
+    if (!entry.symbol) continue;
+
+    const name = entry.name;
+    const symbol = entry.symbol;
+
+    // Map name, symbol (lowercase), and coin id to the coin name
+    aliases.set(name.toLowerCase(), name);
+    aliases.set(symbol.toLowerCase(), name);
+    aliases.set(entry.id, name);
+
+    // Store symbol, decimals, and coin id
+    symbols.set(name, symbol);
+    coinIds.set(name, entry.id);
+    if (entry.decimals !== undefined) {
+      decimals.set(name, entry.decimals);
+    }
+
+    availableSymbols.push(symbol);
+  }
+
+  cachedRegistry = { aliases, symbols, decimals, coinIds, availableSymbols };
+  return cachedRegistry;
+}
+
+/** Resolve user input (name or symbol) to coin name, or null if not found */
+export function resolveCoinId(input: string): string | null {
+  const registry = loadRegistry();
+  return registry.aliases.get(input.toLowerCase().trim()) ?? null;
+}
+
+/** Get symbol for a coin (accepts name, symbol, or coin id) */
+export function getCoinSymbol(coin: string): string {
+  const registry = loadRegistry();
+  const name = registry.aliases.get(coin) ?? registry.aliases.get(coin.toLowerCase()) ?? coin;
+  return registry.symbols.get(name) ?? coin.toUpperCase();
+}
+
+/** Get decimals for a coin (accepts name, symbol, or coin id) */
+export function getCoinDecimals(coin: string): number | undefined {
+  const registry = loadRegistry();
+  const name = registry.aliases.get(coin) ?? registry.aliases.get(coin.toLowerCase());
+  return name ? registry.decimals.get(name) : registry.decimals.get(coin);
+}
+
+/** Get coin id for a coin (accepts name, symbol, or coin id) */
+export function getCoinId(coin: string): string | undefined {
+  const registry = loadRegistry();
+  const name = registry.aliases.get(coin) ?? registry.aliases.get(coin.toLowerCase());
+  return name ? registry.coinIds.get(name) : registry.coinIds.get(coin);
+}
+
+/** Get list of all available symbols for display */
+export function getAvailableSymbols(): string[] {
+  const registry = loadRegistry();
+  return registry.availableSymbols;
+}
+
+// =============================================================================
+// Currency Conversion Utilities
+// =============================================================================
+
+/**
+ * Convert human-readable amount to smallest unit string
+ * @example toSmallestUnit("1.5", 18) => "1500000000000000000"
+ */
+export function toSmallestUnit(amount: number | string, decimals: number): string {
+  if (!amount) return "0";
+
+  const str = amount.toString();
+  const [integer, fraction = ""] = str.split(".");
+
+  // Pad fraction to exact decimal places, truncate if longer
+  const paddedFraction = fraction.padEnd(decimals, "0").slice(0, decimals);
+
+  // Remove leading zeros but keep at least one digit
+  const result = (integer + paddedFraction).replace(/^0+/, "") || "0";
+  return result;
+}
+
+/**
+ * Convert smallest unit string to human-readable amount
+ * @example toHumanReadable("1500000000000000000", 18) => "1.5"
+ */
+export function toHumanReadable(amount: string, decimals: number): string {
+  if (!amount || amount === "0") return "0";
+
+  const str = amount.padStart(decimals + 1, "0");
+  const integer = str.slice(0, -decimals) || "0";
+  const fraction = str.slice(-decimals).replace(/0+$/, "");
+
+  return fraction ? `${integer}.${fraction}` : integer;
+}
+
+/**
+ * Format amount for display with symbol
+ * @param amount Amount in smallest units
+ * @param coinName Coin name (e.g., "unicity")
+ */
+export function formatAmount(amount: string, coinName: string): string {
+  const decimals = getCoinDecimals(coinName) ?? 0;
+  const symbol = getCoinSymbol(coinName);
+  const readable = toHumanReadable(amount, decimals);
+  return `${readable} ${symbol}`;
+}
+
+/**
+ * Parse user input amount to smallest units for a given coin
+ * @param amount Human-readable amount (e.g., "100" or "1.5")
+ * @param coinName Coin name (e.g., "unicity")
+ */
+export function parseAmount(amount: number | string, coinName: string): string {
+  const decimals = getCoinDecimals(coinName) ?? 0;
+  return toSmallestUnit(amount, decimals);
+}