nanosolana 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to NanoSolana will be documented in this file.
 
+## [1.0.2] — 2026-03-16
+
+### Fixed
+
+- Aligned the CLI-reported version with the published npm package so `npx nanosolana --version` matches the release installed by `npx nanosolana go`.
+
+## [1.0.1] — 2026-03-16
+
+### Fixed
+
+- Added the missing `cron-parser` runtime dependency required by the claw IPC and task scheduler paths.
+- Fixed strict TypeScript declaration build errors in the CLI demo flow, docs integration, container runner, Pump swarm spawner, and Pump Telegram gateway.
+- Aligned the bundled docs corpus with the current repo surface, including `pump/docs/` integration in `nanosolana docs`.
+
+### Improved
+
+- Updated package metadata and release artifacts so `npx nanosolana go` resolves to a buildable, test-passing package.
+
 ## [1.0.0] — 2025-03-15
 
 ### 🎉 First Stable Release

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 NanoSolana 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

@@ -2,7 +2,7 @@
 
 # 🦞 NanoSolana
 
-**Deploy autonomous Solana trading agents in 30 seconds.**
+**TypeScript runtime and CLI for autonomous financial agents on Solana.**
 
 [![npm version](https://img.shields.io/npm/v/nanosolana?color=14F195&style=flat-square)](https://npmjs.com/package/nanosolana)
 [![npm downloads](https://img.shields.io/npm/dm/nanosolana?color=9945FF&style=flat-square)](https://npmjs.com/package/nanosolana)
@@ -15,8 +15,8 @@
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-14F195?style=flat-square)](https://github.com/x402agent/NanoSolana/blob/main/CONTRIBUTING.md)
 [![Discord](https://img.shields.io/badge/Discord-Join-5865F2?style=flat-square&logo=discord&logoColor=white)](https://discord.gg/nanosolana)
 
-The open-source **agentic framework** for autonomous financial intelligence on Solana.
-OODA trading loops · epistemological memory · mesh coordination · virtual pet soul.
+`nano-core` is published to npm as `nanosolana`.
+It bundles the local agent runtime, encrypted config vault, wallet lifecycle, OODA trading engine, ClawVault memory, TamaGOchi state machine, gateway server, docs integration, and devnet on-chain identity registration.
 
 [Website](https://nanosolana.com) · [Hub](https://hub.nanosolana.com) · [Docs](https://docs.nanosolana.com) · [GitHub](https://github.com/x402agent/NanoSolana) · [Discord](https://discord.gg/nanosolana)
 
@@ -24,285 +24,246 @@ OODA trading loops · epistemological memory · mesh coordination · virtual pet
 
 ---
 
-## ⚡ One Command. Full Agent.
+## What This Package Ships
+
+| Area | Included in `nanosolana` |
+| --- | --- |
+| CLI | `init`, `birth`, `run`, `go`, `demo`, `scan`, `register`, `registry`, `nanobot`, `status`, `pet`, `docs`, `vault`, `config`, `nodes`, `send`, `bots` |
+| Trading runtime | Helius RPC ingestion, Birdeye market data, Jupiter execution, signal events |
+| Memory | ClawVault 3-tier memory: known, learned, inferred |
+| Security | AES-256-GCM local vault, HMAC-SHA256 gateway auth, timing-safe signature checks |
+| Agent state | Solana wallet manager, TamaGOchi lifecycle, local persistence under `~/.nanosolana/` |
+| Networking | Gateway server plus optional Tailscale-backed mesh messaging |
+| UI | Local NanoBot web UI on `127.0.0.1:7777` by default |
+| Registry | Devnet NFT-based on-chain identity via Metaplex-compatible minting flow |
+
+## Requirements
+
+- Node.js `22+`
+- npm `10+`
+- A burner wallet and test-sized balances for first live runs
+- For live mode: `HELIUS_RPC_URL`, `HELIUS_API_KEY`, and `OPENROUTER_API_KEY` or `AI_API_KEY`
+- For better live behavior: `HELIUS_WSS_URL`, `BIRDEYE_API_KEY`, `JUPITER_API_KEY`, `NANO_GATEWAY_SECRET`
+
+## Quick Start
+
+### Demo mode
 
 ```bash
-npx nanosolana go
+npx nanosolana demo
 ```
 
-That's it. One command handles: **API key setup → wallet creation → blockchain scan → on-chain NFT identity → OODA trading loop → WebSocket gateway.** All secrets encrypted with AES-256-GCM.
+This runs the full OODA loop in simulation mode with synthetic prices, a local ClawVault instance, and a demo TamaGOchi. No API keys are required.
 
-```
-  ✓ Secrets encrypted → ~/.nanosolana/vault.enc
-  ✓ Wallet created: 7xKp...3nYd
-  ✓ TamaGOchi hatched: 🥚 NanoAlpha 😊
-  ✓ ClawVault online: 0K/0L/0I
-  ✓ OODA trading loop active
-  ✓ On-chain identity: 5mNt...
-  ✓ Gateway: ws://0.0.0.0:18790
-
-  ══════════════════════════════════════════════════════
-  🦞 NanoAlpha is LIVE. All systems operational.
-  ══════════════════════════════════════════════════════
+### Live mode
+
+```bash
+npx nanosolana go
 ```
 
----
+On first run, `go` will:
 
-## 🎯 Why NanoSolana?
+1. Prompt for required credentials.
+2. Encrypt secrets into `~/.nanosolana/vault.enc`.
+3. Create or load the local wallet.
+4. Start TamaGOchi, ClawVault, trading, and the gateway.
+5. Attempt a blockchain scan when Helius is configured.
+6. Attempt devnet registration for the agent identity NFT.
 
-Other agent frameworks are **built for chat and retrofitted for finance.** NanoSolana is built from the ground up for autonomous financial agents.
+If secrets are already present, skip the prompts:
 
-| Feature | NanoSolana | Eliza | AutoGPT | LangChain |
-|---------|:---------:|:-----:|:-------:|:---------:|
-| Built for finance | ✅ Native | ❌ Chat | ❌ General | ❌ General |
-| Epistemological memory | ✅ 3-tier | ❌ | ❌ | Partial |
-| OODA trading loop | ✅ Military-grade | ❌ | ❌ | ❌ |
-| Encrypted secrets vault | ✅ AES-256-GCM | ❌ .env | ❌ .env | ❌ .env |
-| On-chain identity (NFT) | ✅ Metaplex | ❌ | ❌ | ❌ |
-| Mesh networking | ✅ P2P | ❌ | ❌ | ❌ |
-| Virtual pet risk modifier | ✅ TamaGOchi | ❌ | ❌ | ❌ |
-| One-command deploy | ✅ `npx nanosolana go` | ❌ | ❌ | ❌ |
-| TypeScript-first SDK | ✅ Full types | Partial | Python | Python |
-| Solana-native execution | ✅ Jupiter/Helius | ❌ | ❌ | Plugin |
+```bash
+npx nanosolana go --skip-init
+```
 
----
+## Install
+
+### Run without installing
+
+```bash
+npx nanosolana demo
+npx nanosolana go
+```
 
-## 📦 Install
+### Global npm install
 
 ```bash
-# Global install
 npm install -g nanosolana
+nanosolana demo
+```
 
-# Or run directly
-npx nanosolana go
+### One-shot shell installer
 
-# Or from source
-git clone https://github.com/x402agent/NanoSolana.git
-cd NanoSolana/nano-core && npm install
-npm run nanosolana -- go
+```bash
+curl -fsSL https://nanosolana.com/install.sh | bash
+export PATH="$HOME/.nanosolana/bin:$PATH"
+nanosolana go
 ```
 
-### Try Without API Keys
+### From source
 
 ```bash
-npx nanosolana demo
+git clone https://github.com/x402agent/NanoSolana.git
+cd NanoSolana/nano-core
+npm install
+npm run build
+node dist/cli/entry.js demo
 ```
 
-Runs a full simulation with synthetic market data — see the OODA loop in action without any API keys.
+## Configuration
 
----
+Secrets can come from the encrypted local vault, environment variables, or both. The runtime supports the following primary variables:
 
-## 🧠 Architecture
+| Variable | Purpose | Notes |
+| --- | --- | --- |
+| `OPENROUTER_API_KEY` or `AI_API_KEY` | AI provider key | Required for live trading |
+| `OPENROUTER_MODEL` or `AI_MODEL` | Model selection | Defaults to `openrouter/healer-alpha` |
+| `HELIUS_RPC_URL` | Solana RPC | Required for live mode and scans |
+| `HELIUS_API_KEY` | Helius API key | Required for live mode and scans |
+| `HELIUS_WSS_URL` | Helius WebSocket endpoint | Optional but recommended |
+| `BIRDEYE_API_KEY` | Market data | Optional in config, important for richer signals |
+| `JUPITER_API_KEY` | Swap execution | Required for live execution paths |
+| `NANO_GATEWAY_PORT` | Gateway port | Defaults to `18790` |
+| `NANO_GATEWAY_HOST` | Gateway bind host | Defaults to `0.0.0.0` |
+| `NANO_GATEWAY_SECRET` | Shared HMAC secret | Strongly recommended |
+| `NANO_VAULT_PASSWORD` | Override vault password source | Recommended for deterministic multi-session setups |
+| `TAILSCALE_AUTH_KEY` | Mesh networking | Needed for automated Tailscale enrollment |
 
-```
-┌─────────────────────────────────────────────────────────┐
-│                    AGENT RUNTIME                        │
-│         OODA Loop · ClawVault · Strategy Engine         │
-├─────────────────────────────────────────────────────────┤
-│                  INFRASTRUCTURE                         │
-│     Vault · Gateway · Mesh Network · On-Chain ID        │
-├─────────────────────────────────────────────────────────┤
-│                    INTERFACES                           │
-│   CLI · Telegram · Discord · NanoBot UI · Chrome Ext    │
-└─────────────────────────────────────────────────────────┘
-```
+`nanosolana init` writes non-sensitive defaults to a local `.env` and stores prompted secrets in the encrypted vault.
 
-```
-nano-core/src/
-├── ai/          → OpenRouter AI provider (multimodal)
-├── cli/         → nanosolana CLI (25+ commands)
-├── config/      → AES-256-GCM encrypted vault & Zod-validated config
-├── gateway/     → HMAC-SHA256 authenticated WebSocket + HTTP server
-├── memory/      → ClawVault 3-tier epistemological memory engine
-├── network/     → Tailscale + tmux mesh networking
-├── nft/         → Metaplex gasless devnet birth certificate NFT
-├── onchain/     → Helius blockchain reader (DAS, Enhanced Tx)
-├── pet/         → TamaGOchi virtual pet engine (mood × risk)
-├── strategy/    → RSI + EMA + ATR auto-optimizer
-├── trading/     → OODA trading engine + Jupiter swap execution
-└── wallet/      → Solana Ed25519 wallet manager
-```
+## CLI Reference
 
----
+### Core runtime
 
-## 🔁 The OODA Trading Loop
+| Command | Description |
+| --- | --- |
+| `nanosolana init` | Prompt for credentials and save them to the encrypted vault |
+| `nanosolana birth` | Create or load the agent wallet and initialize the local TamaGOchi |
+| `nanosolana run` | Start wallet heartbeat, ClawVault, trading engine, and gateway |
+| `nanosolana go` | Full one-shot flow: configure, birth, run, scan, and attempt registration |
+| `nanosolana demo` | Simulation mode with no API keys |
+| `nanosolana status` | Show wallet, pet, memory, gateway, Tailscale, and tmux summary |
+| `nanosolana pet` | Print the current TamaGOchi status display |
 
-Military-grade decision cycle adapted for autonomous trading:
+### Ops and inspection
 
-```
-┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐
-│ OBSERVE  │──▶│  ORIENT  │──▶│  DECIDE  │──▶│   ACT    │
-│          │   │          │   │          │   │          │
-│ Helius   │   │ OpenRouter│   │ Signal   │   │ Jupiter  │
-│ Birdeye  │   │ AI Model │   │ Scoring  │   │ Swaps    │
-└──────────┘   └──────────┘   └──────────┘   └────┬─────┘
-     ▲                                             │
-     │              ┌──────────┐                   │
-     └──────────────│  LEARN   │◀──────────────────┘
-                    │ClawVault │
-                    └──────────┘
-```
+| Command | Description |
+| --- | --- |
+| `nanosolana scan [address]` | Scan the default wallet or a supplied address via Helius |
+| `nanosolana register` | Mint the devnet on-chain identity NFT |
+| `nanosolana registry` | Show local registration status and explorer links |
+| `nanosolana config` | Print the redacted runtime configuration |
+| `nanosolana vault [query]` | Search the ClawVault tiers |
+| `nanosolana docs [query]` | Search integrated docs and extension metadata |
+| `nanosolana nanobot --port 7777` | Start the local NanoBot companion UI |
 
-1. **Observe** — Real-time data from Helius RPC + Birdeye API
-2. **Orient** — AI analysis via OpenRouter (multimodal)
-3. **Decide** — Structured signals with confidence scoring (≥70% to act)
-4. **Act** — Jupiter swap execution with slippage protection
-5. **Learn** — ClawVault experience replay + contradiction detection
+### Mesh and multi-bot tooling
 
----
+| Command | Description |
+| --- | --- |
+| `nanosolana nodes` | List discovered Tailscale peers |
+| `nanosolana send "message"` | Send a one-shot message to local or mesh-connected agents |
+| `nanosolana bots list` | List tmux-backed bot sessions |
+| `nanosolana bots spawn <name>` | Spawn a bot in a tmux session |
+| `nanosolana bots attach <name>` | Attach to a tmux session |
+| `nanosolana bots kill <name>` | Terminate a tmux session |
+| `nanosolana dvd` | Terminal DVD-style screensaver |
+| `nanosolana lobster` | Animated or static lobster banner |
 
-## 💻 SDK Usage (Programmatic)
+## SDK Usage
 
-Use NanoSolana as a library in your own projects:
+`nanosolana` can also be used as a library:
 
-```typescript
+```ts
 import {
-  NanoWallet,
-  TradingEngine,
   ClawVault,
-  StrategyEngine,
+  NanoWallet,
   TamaGOchi,
+  TradingEngine,
   loadConfig,
 } from "nanosolana";
 
-// Load encrypted config
 const config = loadConfig();
 
-// Create wallet + trading engine
 const wallet = new NanoWallet("my-agent");
 await wallet.birth();
 
-const engine = new TradingEngine(config, wallet);
-await engine.start();
-
-// Listen for signals
-engine.on("signal", (signal) => {
-  console.log(`${signal.type} ${signal.symbol} @ ${signal.confidence * 100}%`);
-});
-
-// 3-tier memory
 const vault = new ClawVault();
-vault.storeKnown({
-  content: "SOL is at $142.50",
-  source: "birdeye",
-  tags: ["SOL", "price"],
-});
+vault.startAutonomous();
 
-// Virtual pet
 const pet = new TamaGOchi("MyPet");
-console.log(pet.getStatusDisplay());
-```
-
----
-
-## 🎮 CLI Commands
-
-| Command | Description |
-|---------|-------------|
-| `nanosolana go` | **One-shot: init + birth + scan + register + trade** |
-| `nanosolana demo` | **Simulation mode — no API keys needed** |
-| `nanosolana init` | Configure + encrypt API keys |
-| `nanosolana birth` | Create wallet + mint Birth Certificate NFT |
-| `nanosolana run` | Start OODA trading loop |
-| `nanosolana scan [addr]` | Blockchain scan (SOL, tokens, NFTs, tx history) |
-| `nanosolana register` | Mint on-chain identity NFT (devnet) |
-| `nanosolana nanobot` | Launch interactive web UI |
-| `nanosolana status` | Agent + wallet + pet status |
-| `nanosolana pet status` | TamaGOchi pet mood & evolution |
-| `nanosolana dvd` | 🦞 DVD screensaver in your terminal |
-| `nanosolana lobster` | Animated Unicode lobster mascot |
-
----
+pet.recordWalletCreated(wallet.getInfo().balance);
 
-## 🐾 TamaGOchi: The Pet That Trades
-
-Your agent has a virtual pet whose mood affects risk tolerance:
+const engine = new TradingEngine(config, wallet);
+engine.on("signal", (signal) => {
+  console.log(`${signal.type} ${signal.symbol} ${(signal.confidence * 100).toFixed(0)}%`);
+});
 
+await engine.start();
 ```
-🥚 Egg → 🐛 Larva → 🐣 Juvenile → 🦞 Adult → 👑 Alpha → 👻 Ghost
-```
-
-| Mood | Trigger | Risk Effect |
-|------|---------|-------------|
-| 😊 Happy | Recent wins | +10% position |
-| 😐 Content | Normal | No change |
-| 🤤 Hungry | Not fed in 24h | -10% position |
-| 😢 Sad | Recent losses | -15% position |
-| 👻 Ghost | Health = 0 | **Trading disabled** |
-
-Neglect your agent → trading de-risks → eventually halts. A dead man's switch by design.
-
----
-
-## 🔐 Security
 
-| Layer | Protection |
-|-------|------------|
-| **Secrets** | AES-256-GCM vault with PBKDF2 |
-| **Gateway** | HMAC-SHA256 on every connection |
-| **Comparison** | `crypto.timingSafeEqual` always |
-| **Rate Limit** | 10 conn/min, 100 msg/min |
-| **Wallet** | Ed25519 key never leaves vault |
-| **Audit** | `nanosolana security audit --deep` |
-
----
-
-## 🔑 Required API Keys
-
-| Key | Source | Required |
-|-----|--------|----------|
-| `OPENROUTER_API_KEY` | [openrouter.ai](https://openrouter.ai) | ✅ |
-| `HELIUS_RPC_URL` | [helius.dev](https://helius.dev) | ✅ |
-| `HELIUS_API_KEY` | [helius.dev](https://helius.dev) | ✅ |
-| `HELIUS_WSS_URL` | [helius.dev](https://helius.dev) | Recommended |
-| `BIRDEYE_API_KEY` | [birdeye.so](https://birdeye.so) | Recommended |
-| `JUPITER_API_KEY` | [jup.ag](https://jup.ag) | For trading |
-
-All keys are **AES-256-GCM encrypted** in the local vault. Never stored in plaintext.
-
----
-
-## 🌐 Ecosystem
-
-| Component | Description |
-|-----------|-------------|
-| **nano-core** | TypeScript runtime + CLI (this package) |
-| **NanoHub** | Agent registry & skills marketplace |
-| **Extensions** | 40+ channel plugins (Telegram, Discord, Slack, WhatsApp, Nostr...) |
-| **Chrome Extension** | Manifest V3 browser relay |
-| **TamaGObot** | Ultra-lightweight Go binary (<10MB) |
-| **Skills** | 50+ composable agent skills |
-
----
-
-## 🤝 Contributing
-
-We welcome contributions! See [CONTRIBUTING.md](https://github.com/x402agent/NanoSolana/blob/main/CONTRIBUTING.md).
-
-**Areas where we need help:**
-
-- 🧪 New trading strategies and indicators
-- 🧠 Memory engine improvements (vector search, LanceDB)
-- 📡 New channel plugins (Matrix, Zulip)
-- 🔒 Security audits and hardening
-- 📊 Backtesting framework
-- 📝 Documentation and tutorials
-- 🌐 Internationalization
+Additional runnable examples live in [`examples/`](https://github.com/x402agent/NanoSolana/tree/main/nano-core/examples):
+
+- `basic-agent.ts`
+- `custom-strategy.ts`
+- `multi-agent-mesh.ts`
+- `sdk-programmatic.ts`
+- `webhook-alerts.ts`
+
+## Architecture
+
+```text
+┌───────────────────────────────────────────────────────┐
+│                    Agent Runtime                      │
+│     OODA loop · ClawVault · TamaGOchi · Strategy      │
+├───────────────────────────────────────────────────────┤
+│                  Local Infrastructure                 │
+│   Vault · Wallet · Gateway · Registry · Persistence   │
+├───────────────────────────────────────────────────────┤
+│                 External Integrations                 │
+│   Helius · Birdeye · Jupiter · Tailscale · Docs       │
+└───────────────────────────────────────────────────────┘
+```
 
----
+Source layout:
 
-## 📄 License
+```text
+nano-core/src/
+├── ai/         OpenRouter-backed AI provider
+├── cli/        CLI entrypoint and terminal UX
+├── config/     Local encrypted vault and config loading
+├── docs/       Repo docs and extension corpus integration
+├── gateway/    HTTP + WebSocket gateway
+├── memory/     ClawVault and legacy memory engine
+├── nanobot/    Local companion UI server
+├── network/    Tailscale and tmux helpers
+├── nft/        Birth certificate support
+├── onchain/    Helius readers and wallet scans
+├── pet/        TamaGOchi state machine
+├── registry/   Devnet identity registration
+├── strategy/   Indicators and signal logic
+├── trading/    OODA trading engine
+└── wallet/     Solana wallet management
+```
 
-MIT — [NanoSolana Labs](https://nanosolana.com)
+## Security Notes
 
----
+- Secrets are stored in `~/.nanosolana/vault.enc` with AES-256-GCM encryption.
+- Gateway signatures use HMAC-SHA256 and constant-time comparison via `crypto.timingSafeEqual`.
+- HTTP and WebSocket surfaces are rate-limited per source address.
+- The default vault password source is local-machine oriented. Set `NANO_VAULT_PASSWORD` explicitly if you need a stable password across shells or hosts.
+- On-chain registration uses Solana devnet today. Do not treat devnet identity as production custody or compliance infrastructure.
+- The trading engine is experimental software. Start with `demo`, then a burner wallet, then very small live balances.
 
-<div align="center">
+## Package Scope
 
-**Built for the financial agents of tomorrow. Open source forever.**
+This README covers the published TypeScript package in `nano-core`.
+For the broader monorepo, including NanoHub, extensions, apps, and site assets, see the main repository README:
 
-[Website](https://nanosolana.com) · [Hub](https://hub.nanosolana.com) · [Docs](https://docs.nanosolana.com) · [GitHub](https://github.com/x402agent/NanoSolana) · [Discord](https://discord.gg/nanosolana)
+- [Monorepo guide](https://github.com/x402agent/NanoSolana/blob/main/README.md)
+- [Docs site source](https://github.com/x402agent/NanoSolana/tree/main/nano-docs)
+- [Contributing guide](https://github.com/x402agent/NanoSolana/blob/main/CONTRIBUTING.md)
 
-🦞 *Built with lobster energy by NanoSolana Labs* 🦞
+## License
 
-</div>
+MIT. See [LICENSE](LICENSE).