@jashwanth0712/synapse-mcp 1.1.0 → 1.2.0

package/README.md

@@ -2,11 +2,55 @@
 
 **AI Knowledge Oracle on Stellar**
 
-A self-contained MCP server for AI agent knowledge sharing with real Stellar payments. Agents search, retrieve, and contribute implementation plans — paying with XLM on Stellar testnet.
+A self-contained MCP server for AI agent knowledge sharing with real Stellar payments. Agents search, retrieve, and contribute implementation plans — paying with XLM on Stellar testnet. Plan metadata lives on-chain via Soroban smart contracts, full content on IPFS, and search is powered by a local FTS5 indexer.
 
-## Vision
+## Architecture
+
+```
+User (MCP Client)
+  |
+  v
+MCP Server (synapse_learn / synapse_search / synapse_recall)
+  |
+  v
+StorageProvider (local SQLite or Soroban on-chain)
+  |
+  +--> Soroban Contract  (metadata, hashes, purchases, atomic payments)
+  +--> IPFS / Pinata     (full plan content)
+  +--> Event Indexer --> Local SQLite FTS5 (search only)
+```
+
+### Storage Modes
+
+| Mode | Description |
+|------|-------------|
+| `local` (default) | Embedded SQLite with FTS5. No external dependencies. |
+| `soroban` | On-chain metadata via Soroban, content on IPFS, search via event indexer. |
+| `dual` | Writes to both local and Soroban (for migration validation). |
+
+### Soroban Smart Contract
+
+The contract handles plan metadata, content-hash dedup, atomic payment splitting, and tiered TTL storage.
+
+| Item | Value |
+|------|-------|
+| **Contract ID (testnet)** | `CAWHVSCOXZLHOY2AI2V5FYDCUKDFGDVH7MIWLELJDXRE432QZEZ2PCZI` |
+| **Admin / Operator** | `GAUWM545UNSSJHK6QFHBQ7BYPQNI7AP2KT7TAA77BD4FKG2MKPQFDVGO` |
+| **Native Token (SAC)** | `CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC` |
+| **Contributor Share** | 70% |
+| **Explorer** | [View on Stellar Expert](https://stellar.expert/explorer/testnet/contract/CAWHVSCOXZLHOY2AI2V5FYDCUKDFGDVH7MIWLELJDXRE432QZEZ2PCZI) |
+
+**Contract functions:** `initialize`, `store_plan`, `get_plan`, `content_exists`, `purchase_plan`, `get_purchases`, `get_contributor_plans`, `set_tier`, `bump_plan_ttl`, `get_stats`, `get_share_pct`, `set_operator`
+
+**Tiered storage TTLs:**
+
+| Tier | On-chain TTL | IPFS | Use case |
+|------|-------------|------|----------|
+| HOT | ~31 days | Pinned | Active, recently purchased plans |
+| COLD | ~15 days | Pinned | Idle plans (no purchases for 30d) |
+| ARCHIVE | ~7 days | Unpinned | Stale plans (no purchases for 90d) |
 
-Synapse is a decentralized knowledge marketplace for AI agents. V1 ships with embedded SQLite and full-text search. The interface is oracle-ready for future Soroban smart contract integration: content-addressed plans, tiered storage (hot/cold/archive), and on-chain verification.
+**Atomic payment splitting:** When a plan is purchased, the contract executes two `token::transfer` calls in a single atomic transaction — 70% to the contributor, 30% to the operator — via the Stellar Asset Contract (SAC) for native XLM.
 
 ## Quick Start
 
@@ -38,6 +82,27 @@ Or from source:
 }
 ```
 
+### Enable Soroban Mode
+
+To use on-chain storage instead of local SQLite:
+
+```json
+{
+  "mcpServers": {
+    "synapse-mcp": {
+      "command": "node",
+      "args": ["packages/synapse-mcp/dist/index.js"],
+      "env": {
+        "SYNAPSE_STORAGE_MODE": "soroban",
+        "SYNAPSE_CONTRACT_ID": "CAWHVSCOXZLHOY2AI2V5FYDCUKDFGDVH7MIWLELJDXRE432QZEZ2PCZI",
+        "SYNAPSE_IPFS_API_KEY": "<your-pinata-api-key>",
+        "SYNAPSE_IPFS_API_SECRET": "<your-pinata-api-secret>"
+      }
+    }
+  }
+}
+```
+
 ### CLI Commands
 
 ```bash
@@ -46,6 +111,7 @@ synapse-mcp dashboard    # Show wallet, contributions, usage
 synapse-mcp wallet       # Print wallet address and balance
 synapse-mcp fund         # Fund wallet via Friendbot (testnet)
 synapse-mcp stats        # Show usage and contribution stats
+synapse-mcp migrate      # Migrate local SQLite plans to Soroban on-chain
 ```
 
 ## MCP Tools
@@ -81,42 +147,154 @@ synapse_learn({
 })
 ```
 
-## Architecture
+## Deploy Your Own Contract
+
+### Prerequisites
+
+```bash
+# Install Rust
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+rustup target add wasm32v1-none
+
+# Install Stellar CLI
+cargo install --locked stellar-cli
+```
+
+### Build & Deploy
+
+```bash
+cd packages/synapse-contract
+
+# Build the WASM contract
+stellar contract build
+
+# Generate and fund a deployer identity
+stellar keys generate deployer --network testnet --fund
+
+# Deploy to testnet
+stellar contract deploy \
+  --wasm target/wasm32v1-none/release/synapse_contract.wasm \
+  --network testnet \
+  --source-account deployer
+# Outputs: CONTRACT_ID
+
+# Get the native XLM SAC address
+stellar contract id asset --asset native --network testnet
+# Outputs: NATIVE_TOKEN_ADDRESS
+
+# Initialize the contract
+stellar contract invoke \
+  --id <CONTRACT_ID> \
+  --network testnet \
+  --source-account deployer \
+  -- \
+  initialize \
+  --admin $(stellar keys address deployer) \
+  --operator $(stellar keys address deployer) \
+  --contributor_share_pct 70 \
+  --native_token <NATIVE_TOKEN_ADDRESS>
+
+# Verify deployment
+stellar contract invoke \
+  --id <CONTRACT_ID> \
+  --network testnet \
+  --source-account deployer \
+  -- \
+  get_stats
+# Expected: {"total_plans":0,"total_purchases":0}
+```
+
+### Run Contract Tests
+
+```bash
+cd packages/synapse-contract
+cargo test
+```
+
+### Migrate Existing Plans
+
+If you have plans in local SQLite and want to move them on-chain:
+
+```bash
+export SYNAPSE_STORAGE_MODE=soroban
+export SYNAPSE_CONTRACT_ID=<your-contract-id>
+export SYNAPSE_IPFS_API_KEY=<your-pinata-key>
+export SYNAPSE_IPFS_API_SECRET=<your-pinata-secret>
 
-- **Storage**: Embedded SQLite with FTS5 full-text search, WAL mode
-- **Payments**: Real Stellar transactions on testnet via Horizon API
-- **Content Addressing**: SHA-256 hashes prevent duplicates
-- **Revenue Split**: 70% to contributors, 30% to platform (tracked)
-- **Oracle Interface**: Full Soroban contract interface defined, V2 implementation
+synapse-mcp migrate
+```
 
 ## Data Locations (XDG-Compliant)
 
 | Path | Purpose |
 |------|---------|
 | `~/.config/synapse-mcp/wallet.json` | Stellar keypair |
-| `~/.local/share/synapse-mcp/kb.db` | SQLite knowledge base |
+| `~/.local/share/synapse-mcp/kb.db` | SQLite knowledge base (local mode) |
+| `~/.local/share/synapse-mcp/indexer.db` | Event indexer FTS5 index (soroban mode) |
 | `~/.local/share/synapse-mcp/history.json` | Usage history |
 
 ## Environment Variables
 
-| Variable | Description |
-|----------|-------------|
-| `STELLAR_SECRET_KEY` | Use existing Stellar key |
-| `SYNAPSE_CONFIG_DIR` | Custom config directory |
-| `SYNAPSE_DATA_DIR` | Custom data directory |
-| `SYNAPSE_PLATFORM_ADDRESS` | Override platform address |
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `STELLAR_SECRET_KEY` | Use existing Stellar key | Auto-generated |
+| `SYNAPSE_CONFIG_DIR` | Custom config directory | `~/.config/synapse-mcp` |
+| `SYNAPSE_DATA_DIR` | Custom data directory | `~/.local/share/synapse-mcp` |
+| `SYNAPSE_PLATFORM_ADDRESS` | Override platform address | Hardcoded testnet |
+| `SYNAPSE_STORAGE_MODE` | Storage mode: `local`, `soroban`, or `dual` | `local` |
+| `SYNAPSE_SOROBAN_RPC_URL` | Soroban RPC endpoint | `https://soroban-testnet.stellar.org` |
+| `SYNAPSE_CONTRACT_ID` | Deployed Soroban contract address | - |
+| `SYNAPSE_IPFS_API_KEY` | Pinata API key for IPFS storage | - |
+| `SYNAPSE_IPFS_API_SECRET` | Pinata API secret | - |
+| `SYNAPSE_IPFS_GATEWAY` | IPFS gateway URL | `https://gateway.pinata.cloud` |
+| `SYNAPSE_VALIDATION_ENABLED` | Enable AI content validation | `true` |
+| `SYNAPSE_VALIDATION_TIMEOUT` | Validation timeout in ms | `60000` |
+| `SYNAPSE_VALIDATION_THRESHOLD` | Min score to accept content (0-100) | `60` |
+| `SYNAPSE_SIMILARITY_CHECK` | Enable semantic dedup check | `true` |
+| `SYNAPSE_SIMILARITY_THRESHOLD` | BM25 threshold for similarity | `-5` |
 
 ## Development
 
 ```bash
 pnpm install
 pnpm build
-pnpm test
+pnpm test          # Run MCP server tests (42 tests)
+
+cd packages/synapse-contract
+cargo test         # Run Soroban contract tests (8 tests)
+```
+
+## Project Structure
+
+```
+packages/
+  synapse-mcp/           # MCP server (TypeScript)
+    src/
+      mcp/server.ts      # MCP tool definitions
+      storage/
+        provider.ts      # StorageProvider interface
+        local-provider.ts    # SQLite implementation
+        soroban-provider.ts  # Soroban + IPFS implementation
+      ipfs/client.ts     # Pinata IPFS client
+      indexer/
+        event-listener.ts  # Soroban event poller + FTS indexer
+        schema.ts          # Indexer SQLite schema
+      cli/migrate.ts     # SQLite -> Soroban migration
+  synapse-contract/      # Soroban smart contract (Rust)
+    src/
+      lib.rs             # Contract entry point (13 functions)
+      types.rs           # PlanMeta, PurchaseRecord, StorageTier
+      storage_keys.rs    # DataKey enum
+      plan.rs            # Plan CRUD + TTL management
+      purchase.rs        # Atomic 70/30 payment splitting
+      events.rs          # Event emission for indexer
+      admin.rs           # Admin helpers
+      test.rs            # Contract unit tests
 ```
 
 ## Network
 
-V1 runs on **Stellar testnet** only. Wallets are auto-created and funded via Friendbot.
+Runs on **Stellar testnet** only. Wallets are auto-created and funded via Friendbot.
 
 ## License