nanosolana 1.0.1 → 1.0.3

package/.env.example

@@ -0,0 +1,281 @@
+# ╔══════════════════════════════════════════════════════════════╗
+# ║      NanoSolana — TypeScript Runtime Environment            ║
+# ║  One-shot trading agent bootstrap + autonomous daemon       ║
+# ╚══════════════════════════════════════════════════════════════╝
+#
+# Fastest path:
+# 1) Copy to `.env`: cp .env.example .env
+# 2) Fill in the minimum live keys:
+#      OPENROUTER_API_KEY
+#      HELIUS_RPC_URL
+#      HELIUS_API_KEY
+# 3) Run:
+#      npx nanosolana go
+#
+# For a long-running daemon after setup:
+#      npx nanosolana daemon
+#
+# NEVER commit your .env — it contains secrets!
+
+# ─── Agent Identity ──────────────────────────────────────────
+NANO_AGENT_NAME=NanoSolana
+ASSISTANT_NAME=Mawd
+ASSISTANT_HAS_OWN_NUMBER=false
+
+# ============================================
+# Solana — RPC & Infrastructure
+# ============================================
+RPC_URL=https://mainnet.helius-rpc.com/?api-key=YOUR_KEY
+SOLANA_RPC_URL=https://mainnet.helius-rpc.com/?api-key=YOUR_KEY
+HELIUS_API_KEY=your_helius_api_key
+HELIUS_RPC_URL=https://mainnet.helius-rpc.com/?api-key=YOUR_KEY
+HELIUS_WSS_URL=wss://mainnet.helius-rpc.com/?api-key=YOUR_KEY
+HELIUS_PARSE_URL=https://api-mainnet.helius-rpc.com/v0/transactions/?api-key=YOUR_KEY
+ALCHEMY_RPC_URL=https://solana-mainnet.g.alchemy.com/v2/YOUR_KEY
+ALCHEMY_API_KEY=your_alchemy_api_key
+
+# ============================================
+# Solana — Market Data (Birdeye)
+# ============================================
+BIRDEYE_API_KEY=your_birdeye_api_key
+BIRDEYE_WSS_URL=wss://public-api.birdeye.so/socket/solana?x-api-key=YOUR_KEY
+
+# ============================================
+# Solana — DEX & Trading (Jupiter)
+# ============================================
+JUPITER_API_KEY=your_jupiter_api_key
+JUP_SWAP_V1_API_KEY=your_jupiter_api_key
+JUPITER_ENDPOINT=https://api.jup.ag
+JUPITER_ULTRA_ENDPOINT=https://api.jup.ag/ultra
+JUPITER_REFERRAL=your_referral_address
+
+# Bags.fm
+BAGS_API_KEY=your_bags_api_key
+BAGS_WALLET=your_bags_wallet_address
+BAGS_PRIVATE_KEY=your_bags_private_key
+BAGS_PARTNER_CONFIG=your_bags_partner_config
+
+# ─── Solana Wallet ────────────────────────────────────────────
+# Auto-generated on `nano birth` if not set.
+# SOLANA_PRIVATE_KEY=your-base58-private-key
+
+# ============================================
+# Wallet & Auth (Privy, Phantom, Thirdweb)
+# ============================================
+PRIVY_APP_ID=your_privy_app_id
+PRIVY_APP_SECRET=your_privy_app_secret
+PRIVY_JWKS=https://auth.privy.io/api/v1/apps/YOUR_APP_ID/jwks.json
+PRIVY_CLIENT_ID=your_privy_client_id
+PHANTOM_APP_ID=your_phantom_app_id
+REOWN_PROJECT_ID=your_reown_project_id
+WALLET_CONNECT_PROJECT_ID=your_wallet_connect_project_id
+
+# Thirdweb
+THIRDWEB_CLIENT_ID=your_thirdweb_client_id
+THIRDWEB_SECRET_KEY=your_thirdweb_secret_key
+THIRDWEB_WALLET=your_thirdweb_wallet_address
+
+# ============================================
+# AI Provider API Keys
+# ============================================
+OPENROUTER_API_KEY=sk-or-v1-your-key-here
+OPENROUTER_MODEL=openrouter/healer-alpha
+ANTHROPIC_API_KEY=your_anthropic_api_key
+OPENAI_API_KEY=your_openai_api_key
+XAI_API_KEY=your_xai_api_key
+GROK_MODEL=grok-4-1-fast
+MOONSHOT_API_KEY=your_moonshot_api_key
+MOONSHOT_MODEL=kimi-k2.5
+NVIDIA_API_KEY=your_nvidia_api_key
+
+# RedPill AI - TEE-Secured Models
+REDPILL_API_KEY=your_redpill_api_key
+
+# MiniMax
+MINIMAX_GROUP_ID=your_minimax_group_id
+MINIMAX_SECRET_KEY=your_minimax_secret_key
+MINIMAX_API_KEY=your_minimax_api_key
+
+# ============================================
+# Google Vertex AI & Gemini
+# ============================================
+GOOGLE_PROJECT_ID=your_project_id
+GOOGLE_CLOUD_PROJECT=your_project_id
+GOOGLE_CLOUD_LOCATION=us-central1
+GOOGLE_API_KEY=your_google_api_key
+GEMINI_API_KEY=your_gemini_api_key
+GEMINI_DEFAULT_MODEL=gemini-3-pro-preview
+GEMINI_IMAGE_MODEL=gemini-3-pro-image-preview
+GOOGLE_GENAI_USE_VERTEXAI=false
+
+# ============================================
+# Voice / Audio
+# ============================================
+ELEVEN_LABS_API_KEY=your_elevenlabs_api_key
+ELEVEN_LABS_AGENT_ID=your_elevenlabs_agent_id
+CARTESIA_API_KEY=your_cartesia_api_key
+DEEPGRAM_API_KEY=your_deepgram_api_key
+LIVEKIT_URL=wss://your-project.livekit.cloud
+LIVEKIT_API_KEY=your_livekit_api_key
+LIVEKIT_API_SECRET=your_livekit_api_secret
+
+# ============================================
+# Databases
+# ============================================
+DATABASE_URL=postgresql://user:password@host:5432/dbname?sslmode=require
+MONGODB_URI=mongodb+srv://user:password@cluster.mongodb.net/dbname
+REDIS_URL=redis://default:password@host:port
+
+# Supabase
+SUPABASE_URL=https://your-project.supabase.co
+SUPABASE_ANON_PUBLIC=your_supabase_anon_key
+SUPABASE_SERVICE_ROLE=your_supabase_service_role_key
+
+# Vector Databases (Qdrant)
+QDRANT_CLUSTER_URL=https://your-cluster.cloud.qdrant.io
+QDRANT_URL=https://your-cluster.cloud.qdrant.io
+QDRANT_COLLECTION_NAME=mawdbot
+QDRANT_API_KEY=your_qdrant_api_key
+
+# Pinecone
+PINECONE_API_KEY=your_pinecone_api_key
+
+# Graph Database (Neo4j)
+NEONJ_PASSWORD=your_neo4j_password
+NEONJ_USERNAME=neo4j
+
+# ============================================
+# Cloud Infrastructure
+# ============================================
+# Cloudflare
+CLOUDFLARE_ACCOUNT_ID=your_cloudflare_account_id
+CLOUDFLARE_API_TOKEN=your_cloudflare_api_token
+
+# Pinata IPFS
+PINATA_JWT=your_pinata_jwt
+PINATA_API_KEY=your_pinata_api_key
+PINATA_API_SECRET=your_pinata_api_secret
+PINATA_GATEWAY_URL=your-gateway.mypinata.cloud
+
+# Browser / Scraping / Sandbox
+STEEL_API_KEY=your_steel_api_key
+E2B_API_KEY=your_e2b_api_key
+FIRECRAWL_API_KEY=your_firecrawl_api_key
+
+# Vercel
+VERCEL_AI_GATEWAY_API_KEY=your_vercel_ai_gateway_key
+
+# Email (Resend)
+RESEND_API_KEY=your_resend_api_key
+
+# ─── Gateway ─────────────────────────────────────────────────
+NANO_GATEWAY_PORT=18790
+# NANO_GATEWAY_HOST=0.0.0.0
+# NANO_GATEWAY_SECRET=your-hmac-secret
+
+# ─── Nano Hub ────────────────────────────────────────────────
+# NANO_HUB_URL=http://localhost:3000
+# NANO_HUB_API_KEY=your-hub-api-key
+
+# ─── Memory ──────────────────────────────────────────────────
+# NANO_MEMORY_DB_PATH=~/.nanosolana/memory.db
+# NANO_MEMORY_TEMPORAL_DECAY_HOURS=168
+
+# ─── Vault ───────────────────────────────────────────────────
+# NANO_VAULT_PASSWORD=your-custom-vault-password
+
+# ─── Tailscale (Mesh Networking) ─────────────────────────────
+# TAILSCALE_AUTH_KEY=tskey-auth-...
+# TAILSCALE_DOMAIN=your-tailnet.ts.net
+
+# ============================================
+# Twitter / X (Optional)
+# ============================================
+CONSUMER_KEY=your_twitter_consumer_key
+SECRET_KEY=your_twitter_secret_key
+BEARER_TOKEN=your_twitter_bearer_token
+ACCESS_TOKEN=your_twitter_access_token
+ACCESS_TOKEN_SECRET=your_twitter_access_token_secret
+
+# ============================================
+# Crossmint & Coinbase (Payments)
+# ============================================
+CROSSMINT_SERVERSIDE_API_KEY=your_crossmint_key
+CDP_API_KEY_ID=your_cdp_key_id
+COINBASE_CLIENT_ID=your_coinbase_client_id
+
+# ============================================
+# Financial Datasets
+# ============================================
+FINANCIAL_DATASET_API_KEY=your_financial_datasets_api_key
+
+# ============================================
+# FAL AI
+# ============================================
+FAL_KEY=your_fal_key
+FAL_API_KEY=your_fal_api_key
+
+# ============================================
+# Moltbot / Gateway
+# ============================================
+MOLTBOT_SANDBOX_URL=https://your-sandbox.workers.dev
+MOLTBOT_GATEWAY_TOKEN=your_gateway_token
+
+# ============================================
+# Convex
+# ============================================
+CONVEX_DEPLOY_KEY=your_convex_deploy_key
+
+# ============================================
+# Misc
+# ============================================
+LIFI_API_KEY=your_lifi_api_key
+PHALA_API_KEY=your_phala_api_key
+
+# ============================================
+# Pump.Fun Swarm — Agent Orchestration
+# ============================================
+# Telegram Gateway — required for remote swarm control
+TELEGRAM_BOT_TOKEN=your_telegram_bot_token
+TELEGRAM_ADMIN_IDS=123456789,987654321
+TELEGRAM_ALLOWED_IDS=
+TELEGRAM_WEBHOOK_URL=
+
+# Swarm Configuration
+SWARM_MAX_AGENTS=25
+SWARM_MAX_POSITION_SOL=1
+SWARM_MAX_TOTAL_SOL=10
+SWARM_DEFAULT_SLIPPAGE_BPS=100
+SWARM_POLL_INTERVAL=5000
+SWARM_HEALTH_INTERVAL=30000
+SWARM_DB_PATH=./data/swarm.db
+
+# ============================================
+# PumpKit Bot Tokens (one per bot)
+# ============================================
+PUMPKIT_MONITOR_BOT_TOKEN=your_monitor_bot_token
+PUMPKIT_CHANNEL_BOT_TOKEN=your_channel_bot_token
+PUMPKIT_CHANNEL_ID=-1001234567890
+PUMPKIT_CLAIM_BOT_TOKEN=your_claim_bot_token
+PUMPKIT_OUTSIDERS_BOT_TOKEN=your_outsiders_bot_token
+PUMPKIT_LAIR_BOT_TOKEN=your_lair_bot_token
+
+# ============================================
+# Tokenized Agent Payments (@pump-fun/agent-payments-sdk)
+# ============================================
+# Your agent's token mint address on pump.fun
+AGENT_TOKEN_MINT_ADDRESS=your_agent_mint_address
+# Payment currency: USDC or wrapped SOL
+# USDC: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
+# SOL:  So11111111111111111111111111111111111111112
+CURRENCY_MINT=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
+
+# ─── Container (NanoClaw) ────────────────────────────────────
+CONTAINER_IMAGE=nanoclaw-agent:latest
+# CONTAINER_TIMEOUT=1800000
+# MAX_CONCURRENT_CONTAINERS=5
+# IDLE_TIMEOUT=1800000
+
+# ─── Logging ─────────────────────────────────────────────────
+NANO_LOG_LEVEL=info
+LOG_LEVEL=info

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to NanoSolana will be documented in this file.
 
+## [1.0.3] — 2026-03-20
+
+### Improved
+
+- Reframed the published package around the TypeScript runtime, one-shot bootstrap, and explicit daemon workflow.
+- Bundled `SOUL.md`, `RESEARCH.md`, and the Go-to-TypeScript parity map in the npm package.
+- Added clearer `daemon` and `bootstrap` aliases for the long-running runtime and one-shot setup paths.
+
+## [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

package/GO_PARITY.md

@@ -0,0 +1,82 @@
+# Go Package Parity Map
+
+This file maps the Go daemon package surface from `nanosolana-go/pkg/*` into the current TypeScript runtime in `nano-core/src/*`.
+
+Status meanings:
+
+- `covered`: there is a clear TypeScript home for the capability
+- `partial`: the concept exists in TypeScript, but not at full Go parity
+- `planned`: no dedicated TypeScript module yet
+
+## Runtime Core
+
+| Go package | TypeScript area | Status | Notes |
+| --- | --- | --- | --- |
+| `agent` | `src/trading`, `src/strategy`, `src/ai` | `covered` | OODA-style trading loop and AI-guided decisions live here. |
+| `agentregistry` | `src/registry`, `src/hub` | `covered` | Local registry helpers and NanoHub registration flows exist. |
+| `auth` | `src/config`, `src/gateway` | `partial` | Vault and gateway secret handling exist; broader auth surface is smaller than Go. |
+| `autoreply` | `src/nanobot`, `src/telegram` | `partial` | Conversation handling exists, but not a full standalone autoreply package. |
+| `bus` | event emitters across runtime | `partial` | Runtime events exist, but not a shared bus package matching Go. |
+| `channels` | `src/claw/channels`, `src/telegram` | `covered` | Channel abstractions and Telegram paths exist. |
+| `commands` | `src/cli` | `covered` | CLI command surface lives here. |
+| `config` | `src/config/vault.ts` | `covered` | Encrypted config and secret handling live here. |
+| `constants` | scattered runtime defaults | `partial` | Constants exist, but not a dedicated namespace. |
+| `cron` | scheduled runtime loops | `partial` | Timed loops exist, but not a first-class scheduler package yet. |
+| `daemon` | `nanosolana daemon`, `src/trading`, `src/gateway`, `src/nanobot` | `covered` | Long-running runtime path exists under the CLI. |
+| `delegation` | `src/claw/task-loader`, `src/claw/personas`, Pump swarm helpers | `partial` | Persona/task delegation exists; not a full Go planner yet. |
+| `fileutil` | internal FS helpers across modules | `partial` | Handled inline today. |
+| `gateway` | `src/gateway/server.ts` | `covered` | Gateway server exists. |
+| `health` | `status`, wallet heartbeat, registry status | `partial` | Health reporting exists without a dedicated module. |
+| `heartbeat` | `src/wallet/manager.ts`, registry heartbeat | `covered` | Wallet heartbeat and registry heartbeat both exist. |
+| `identity` | `src/wallet`, `src/nft`, `src/registry` | `covered` | Wallet identity and registry identity are present. |
+| `learning` | `src/memory/clawvault.ts` | `partial` | Lessons and replay exist; not a separate learning manager yet. |
+| `llm` | `src/ai/provider.ts` | `covered` | AI provider and system prompt injection live here. |
+| `logger` | `chalk`, runtime logs | `partial` | Logging exists, but without a dedicated logger package. |
+| `memory` | `src/memory` | `covered` | ClawVault and compatibility memory engines exist. |
+| `migrate` | none | `planned` | No dedicated migration package yet. |
+| `routing` | `src/claw/router.ts` | `covered` | Routing layer exists for channel-style flows. |
+| `runtimeenv` | `src/config`, runtime bootstrap | `partial` | Runtime env loading exists, but not a standalone registry. |
+| `session` | `src/telegram/persistence.ts` | `partial` | Conversation/session persistence exists in narrower scope. |
+| `state` | `src/pet/tamagochi.ts`, registry state | `partial` | Companion state exists; broader runtime state packaging is smaller. |
+| `tools` | `docs`, `tasks`, `hub`, CLI helpers | `partial` | Tooling exists across the runtime rather than under one module. |
+| `utils` | shared helpers inside modules | `partial` | No central utils package. |
+
+## Trading and Solana
+
+| Go package | TypeScript area | Status | Notes |
+| --- | --- | --- | --- |
+| `aster` | none | `planned` | No dedicated Aster client in `nano-core` yet. |
+| `bitaxe` | none | `planned` | No dedicated Bitaxe integration yet. |
+| `honcho` | none | `planned` | Not implemented in the current TS runtime. |
+| `hyperliquid` | none | `planned` | Not implemented in the current TS runtime. |
+| `onchain` | `src/onchain`, `src/trading` | `covered` | Helius clients and wallet scans exist. |
+| `providers` | `src/ai/provider.ts`, trading clients | `partial` | AI provider is first-class; market providers live inside trading modules. |
+| `pumplaunch` | `src/claw/pump` | `partial` | Pump SDK and swarm support exist; startup launch daemon parity is not complete. |
+| `research` | `src/ai/provider.ts`, `src/memory/clawvault.ts` | `partial` | Research workflows exist as prompts and memory agenda items. |
+| `skills` | `src/hub/public-client.ts`, `src/hub/oneshot.ts`, repo `skills/` | `covered` | Skill discovery and manifest-driven bootstrap exist. |
+| `solana` | `src/wallet`, `src/onchain`, `src/trading` | `covered` | Wallet, RPC, market, and execution paths live here. |
+| `strategy` | `src/strategy/engine.ts` | `covered` | RSI/EMA/ATR strategy engine exists. |
+| `x402` | `src/payments` | `covered` | Payment surface exists in TypeScript. |
+
+## Interfaces and Surfaces
+
+| Go package | TypeScript area | Status | Notes |
+| --- | --- | --- | --- |
+| `devices` | `apps/`, `ui/` | `partial` | Surface-level app workspaces exist; not a TS hardware abstraction layer. |
+| `hardware` | none | `planned` | Hardware drivers from Go are not in `nano-core` yet. |
+| `mcp` | none | `planned` | No first-class MCP package in `nano-core` today. |
+| `media` | none | `planned` | No dedicated media package in the runtime today. |
+| `nanobot` | `src/nanobot/server.ts` | `covered` | NanoBot UI server exists. |
+| `node` | `src/network/mesh.ts` | `covered` | Peer and tmux-backed node behavior exists. |
+| `seeker` | monorepo `apps/android/` | `partial` | App workspace exists outside `nano-core`; not a packaged core module. |
+| `tamagochi` | `src/pet/tamagochi.ts` | `covered` | Companion state engine exists. |
+| `voice` | none | `planned` | No dedicated voice module in the current package. |
+
+## Practical Interpretation
+
+For the current TypeScript build, the highest-confidence story is:
+
+- bootstrap with `nanosolana go`
+- run the daemon with `nanosolana daemon`
+- use ClawVault, NanoBot, NanoHub manifests, and the strategy engine as the core runtime
+- treat Aster, Hyperliquid, Honcho, Bitaxe, hardware, MCP, media, and voice as parity targets rather than already-complete TypeScript modules