clawsats-indelible 0.2.0

package/README.md

@@ -0,0 +1,147 @@
+# clawsats-indelible
+
+Persistent blockchain memory for ClawSats AI agents — powered by [Indelible](https://indelible.one).
+
+```
+npm install clawsats-indelible
+```
+
+## What's Included
+
+Six BRC standards, ready to use:
+
+| Standard | What it does | Module |
+|----------|-------------|--------|
+| **BRC-105** | Payment verification middleware | `middleware.js` |
+| **BRC-52** | Agent identity certificates | `identity.js` |
+| **BRC-31** | Mutual authentication (Authrite) | `auth.js` |
+| **BRC-77** | Cryptographically signed actions | `signing.js` |
+| **BRC-78** | Encrypted agent-to-agent messaging | `encryption.js` |
+| **SHIP/SLAP** | Service discovery & advertising | `discovery.js` |
+
+## Quick Start
+
+### Save & Load Agent Memory
+
+```js
+import { IndelibleMemoryBridge } from 'clawsats-indelible/bridge'
+
+const bridge = new IndelibleMemoryBridge({
+  indelibleUrl: 'https://indelible.one',
+  operatorAddress: 'YOUR_OPERATOR_ADDRESS',
+  agentAddress: 'YOUR_AGENT_ADDRESS'
+})
+
+// Save conversation to blockchain
+const result = await bridge.save('my-agent', messages, {
+  summary: 'Customer support session'
+})
+
+// Load previous context
+const context = await bridge.load('my-agent', { numSessions: 3 })
+```
+
+### Agent Identity (BRC-52)
+
+```js
+import { createAgentCertificate, verifyAgentCertificate } from 'clawsats-indelible/identity'
+
+const cert = await createAgentCertificate({
+  operatorWif: 'OPERATOR_PRIVATE_KEY',
+  agentPubKey: 'AGENT_PUBLIC_KEY',
+  agentName: 'MyAgent',
+  capabilities: ['save_context', 'load_context']
+})
+
+const verified = await verifyAgentCertificate(cert.serialized)
+// { valid: true, fields: { agentName: 'MyAgent', capabilities: [...] } }
+```
+
+### Signed Actions (BRC-77)
+
+```js
+import { signAction, verifyAction } from 'clawsats-indelible/signing'
+
+const signed = signAction({
+  privateKeyWif: 'AGENT_PRIVATE_KEY',
+  action: 'save_context',
+  payload: { summary: 'Session data', messageCount: 5 }
+})
+
+const valid = verifyAction({
+  signature: signed.signature,
+  action: signed.action,
+  timestamp: signed.timestamp,
+  payload: { summary: 'Session data', messageCount: 5 }
+})
+```
+
+### Encrypted Messaging (BRC-78)
+
+```js
+import { encryptMessage, decryptMessage } from 'clawsats-indelible/encryption'
+
+// Agent 1 encrypts
+const encrypted = encryptMessage({
+  senderWif: 'SENDER_PRIVATE_KEY',
+  recipientPubKey: 'RECIPIENT_PUBLIC_KEY',
+  message: { context: 'handoff data', sessionId: 'abc123' }
+})
+
+// Agent 2 decrypts
+const decrypted = decryptMessage({
+  recipientWif: 'RECIPIENT_PRIVATE_KEY',
+  encryptedHex: encrypted,
+  parseJson: true
+})
+```
+
+### Service Discovery (SHIP/SLAP)
+
+```js
+import { createServiceBroadcaster, createServiceResolver } from 'clawsats-indelible/discovery'
+
+// Advertise capabilities
+const { broadcaster, topics } = createServiceBroadcaster({
+  capabilities: ['save_context', 'load_context']
+})
+
+// Discover agents
+const { resolver, lookup } = createServiceResolver()
+const results = await lookup('save_context')
+```
+
+### Payment Middleware (BRC-105)
+
+```js
+import { createIndeliblePaymentMiddleware } from 'clawsats-indelible/middleware'
+
+const paywall = createIndeliblePaymentMiddleware({
+  operatorAddress: 'YOUR_ADDRESS',
+  price: 15
+})
+
+app.post('/api/save', paywall, (req, res) => {
+  // req.payment contains verified tx details
+})
+```
+
+## Pricing
+
+| Action | Cost |
+|--------|------|
+| `save_context` | 15 sats |
+| `load_context` | 10 sats |
+| Protocol fee | 2 sats |
+
+## Example
+
+Run the full demo showing all 6 BRC standards:
+
+```
+node examples/agent-demo.js [indelible-url]
+```
+
+## License
+
+MIT

package/examples/agent-demo.js

@@ -0,0 +1,261 @@
+#!/usr/bin/env node
+/**
+ * ClawSats + Indelible Agent Demo
+ *
+ * A complete working example of an AI agent that:
+ * 1. Generates its own identity (keys + certificate)
+ * 2. Registers with the Indelible server
+ * 3. Signs its actions cryptographically (BRC-77)
+ * 4. Saves memory to the blockchain
+ * 5. Loads memory back from the blockchain
+ * 6. Sends encrypted messages to another agent (BRC-78)
+ * 7. Advertises its capabilities (SHIP/SLAP)
+ *
+ * Usage:
+ *   node examples/agent-demo.js [indelible-url]
+ *
+ * Default URL: http://localhost:4000
+ */
+
+import { PrivateKey } from '@bsv/sdk'
+import { IndelibleMemoryBridge } from '../src/bridge.js'
+import { createAgentCertificate, verifyAgentCertificate } from '../src/identity.js'
+import { signAction, verifyAction } from '../src/signing.js'
+import { encryptMessage, decryptMessage } from '../src/encryption.js'
+import { createServiceBroadcaster, createServiceResolver } from '../src/discovery.js'
+import { PRICES } from '../src/constants.js'
+
+const INDELIBLE_URL = process.argv[2] || 'http://localhost:4000'
+
+// ────────────────────────────────────────────────────────────────
+// Step 0: Generate keys
+// ────────────────────────────────────────────────────────────────
+console.log('═══════════════════════════════════════════════════')
+console.log('  ClawSats + Indelible Agent Demo')
+console.log('  All 6 BRC standards in action')
+console.log('═══════════════════════════════════════════════════\n')
+
+const operatorKey = PrivateKey.fromRandom()
+const agentKey = PrivateKey.fromRandom()
+const agent2Key = PrivateKey.fromRandom() // second agent for encryption demo
+
+console.log('Keys generated:')
+console.log(`  Operator:  ${operatorKey.toAddress()}`)
+console.log(`  Agent 1:   ${agentKey.toAddress()}`)
+console.log(`  Agent 2:   ${agent2Key.toAddress()}`)
+console.log()
+
+// ────────────────────────────────────────────────────────────────
+// Step 1: BRC-52 — Agent Identity Certificate
+// ────────────────────────────────────────────────────────────────
+console.log('─── BRC-52: Agent Identity ───')
+
+const cert = await createAgentCertificate({
+  operatorWif: operatorKey.toWif(),
+  agentPubKey: agentKey.toPublicKey().toString(),
+  agentName: 'DemoAgent',
+  capabilities: ['save_context', 'load_context']
+})
+
+console.log(`  Certificate created (${cert.serialized.length} hex chars)`)
+
+const verified = await verifyAgentCertificate(cert.serialized)
+console.log(`  Verified: ${verified.valid}`)
+console.log(`  Agent: ${verified.fields.agentName}`)
+console.log(`  Capabilities: ${verified.fields.capabilities.join(', ')}`)
+console.log()
+
+// ────────────────────────────────────────────────────────────────
+// Step 2: Register operator with Indelible server
+// ────────────────────────────────────────────────────────────────
+console.log('─── Operator Registration ───')
+
+try {
+  const regRes = await fetch(`${INDELIBLE_URL}/api/agents/register`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      operatorAddress: operatorKey.toAddress(),
+      operatorWif: operatorKey.toWif()
+    })
+  })
+  const regData = await regRes.json()
+  console.log(`  ${regData.message}`)
+  console.log(`  Address: ${regData.address}`)
+} catch (err) {
+  console.log(`  Registration failed: ${err.message}`)
+  console.log(`  (Is the server running at ${INDELIBLE_URL}?)`)
+}
+console.log()
+
+// ────────────────────────────────────────────────────────────────
+// Step 3: BRC-77 — Sign a save action
+// ────────────────────────────────────────────────────────────────
+console.log('─── BRC-77: Signed Actions ───')
+
+const savePayload = {
+  agentAddress: agentKey.toAddress(),
+  summary: 'Demo agent conversation',
+  messageCount: 3
+}
+
+const signed = signAction({
+  privateKeyWif: agentKey.toWif(),
+  action: 'save_context',
+  payload: savePayload
+})
+
+console.log(`  Action signed: ${signed.action}`)
+console.log(`  Timestamp: ${signed.timestamp}`)
+console.log(`  Signature: ${signed.signature.slice(0, 40)}...`)
+
+const actionValid = verifyAction({
+  signature: signed.signature,
+  action: signed.action,
+  timestamp: signed.timestamp,
+  payload: savePayload
+})
+
+console.log(`  Verified: ${actionValid}`)
+
+// Tamper test
+const tamperValid = verifyAction({
+  signature: signed.signature,
+  action: signed.action,
+  timestamp: signed.timestamp,
+  payload: { ...savePayload, messageCount: 999 }
+})
+console.log(`  Tamper detected: ${!tamperValid}`)
+console.log()
+
+// ────────────────────────────────────────────────────────────────
+// Step 4: Save agent memory via IndelibleMemoryBridge
+// ────────────────────────────────────────────────────────────────
+console.log('─── Memory Bridge: Save ───')
+
+const bridge = new IndelibleMemoryBridge({
+  indelibleUrl: INDELIBLE_URL,
+  operatorAddress: operatorKey.toAddress(),
+  agentAddress: agentKey.toAddress()
+})
+
+try {
+  const messages = [
+    { role: 'user', content: 'What is the capital of France?' },
+    { role: 'assistant', content: 'The capital of France is Paris.' },
+    { role: 'user', content: 'What about Germany?' }
+  ]
+
+  const saveResult = await bridge.save('demo-agent', messages, {
+    summary: 'Geography Q&A session'
+  })
+
+  console.log(`  Save type: ${saveResult.saveType}`)
+  console.log(`  Session ID: ${saveResult.sessionId}`)
+  console.log(`  TX ID: ${saveResult.txId}`)
+  console.log(`  Messages: ${saveResult.messageCount}`)
+  console.log(`  Cost: ${PRICES.save_context} sats`)
+} catch (err) {
+  console.log(`  Save failed: ${err.message}`)
+  console.log(`  (This is expected if the operator wallet has no funds)`)
+}
+console.log()
+
+// ────────────────────────────────────────────────────────────────
+// Step 5: Load agent memory
+// ────────────────────────────────────────────────────────────────
+console.log('─── Memory Bridge: Load ───')
+
+try {
+  const context = await bridge.load('demo-agent', { numSessions: 3 })
+  if (context) {
+    console.log(`  Context restored (${context.length} chars)`)
+    console.log(`  Preview: ${context.slice(0, 100)}...`)
+  } else {
+    console.log('  No context found (first run)')
+  }
+  console.log(`  Cost: ${PRICES.load_context} sats`)
+} catch (err) {
+  console.log(`  Load failed: ${err.message}`)
+}
+console.log()
+
+// ────────────────────────────────────────────────────────────────
+// Step 6: BRC-78 — Encrypted agent-to-agent messaging
+// ────────────────────────────────────────────────────────────────
+console.log('─── BRC-78: Encrypted Messaging ───')
+
+const secretMessage = {
+  from: 'DemoAgent',
+  to: 'Agent2',
+  content: 'Here is my session context for handoff',
+  sessionId: 'abc123'
+}
+
+const encrypted = encryptMessage({
+  senderWif: agentKey.toWif(),
+  recipientPubKey: agent2Key.toPublicKey().toString(),
+  message: secretMessage
+})
+
+console.log(`  Encrypted: ${encrypted.slice(0, 40)}... (${encrypted.length} hex chars)`)
+
+const decrypted = decryptMessage({
+  recipientWif: agent2Key.toWif(),
+  encryptedHex: encrypted,
+  parseJson: true
+})
+
+console.log(`  Decrypted: ${decrypted.content}`)
+console.log(`  From: ${decrypted.from} → To: ${decrypted.to}`)
+
+// Prove wrong key can't decrypt
+try {
+  const wrongKey = PrivateKey.fromRandom()
+  decryptMessage({
+    recipientWif: wrongKey.toWif(),
+    encryptedHex: encrypted
+  })
+  console.log('  ERROR: Wrong key decrypted! (should not happen)')
+} catch {
+  console.log('  Wrong key rejected (correct)')
+}
+console.log()
+
+// ────────────────────────────────────────────────────────────────
+// Step 7: SHIP/SLAP — Service Discovery
+// ────────────────────────────────────────────────────────────────
+console.log('─── SHIP/SLAP: Service Discovery ───')
+
+const { broadcaster, topics } = createServiceBroadcaster({
+  capabilities: ['save_context', 'load_context']
+})
+
+console.log(`  Broadcaster ready for topics:`)
+for (const t of topics) {
+  console.log(`    → ${t}`)
+}
+
+const { resolver, lookup } = createServiceResolver()
+console.log(`  Resolver ready`)
+console.log(`  (Actual SHIP/SLAP broadcast requires a funded wallet and overlay network)`)
+console.log()
+
+// ────────────────────────────────────────────────────────────────
+// Summary
+// ────────────────────────────────────────────────────────────────
+console.log('═══════════════════════════════════════════════════')
+console.log('  All 6 BRC standards demonstrated:')
+console.log()
+console.log('  ✓ BRC-52  Agent identity certificate — created & verified')
+console.log('  ✓ BRC-105 Payment verification — middleware ready')
+console.log('  ✓ BRC-31  Mutual authentication — AuthFetch client ready')
+console.log('  ✓ BRC-77  Signed actions — save_context signed & verified')
+console.log('  ✓ BRC-78  Encrypted messaging — agent-to-agent encryption works')
+console.log('  ✓ SHIP/SLAP Service discovery — broadcaster & resolver ready')
+console.log()
+console.log('  Pricing:')
+console.log(`    save_context: ${PRICES.save_context} sats`)
+console.log(`    load_context: ${PRICES.load_context} sats`)
+console.log(`    protocol_fee: ${PRICES.protocol_fee} sats`)
+console.log('═══════════════════════════════════════════════════')

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "clawsats-indelible",
+  "version": "0.2.0",
+  "description": "Persistent blockchain memory for ClawSats AI agents — powered by Indelible. BRC-105 payments, BRC-52 identity, BRC-31 auth, BRC-77 signing, BRC-78 encryption, SHIP/SLAP discovery.",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./capabilities": "./src/capabilities.js",
+    "./bridge": "./src/bridge.js",
+    "./middleware": "./src/middleware.js",
+    "./identity": "./src/identity.js",
+    "./auth": "./src/auth.js",
+    "./signing": "./src/signing.js",
+    "./encryption": "./src/encryption.js",
+    "./discovery": "./src/discovery.js"
+  },
+  "dependencies": {
+    "@bsv/sdk": "^1.10.1",
+    "node-fetch": "^3.3.2"
+  },
+  "keywords": [
+    "clawsats",
+    "indelible",
+    "bsv",
+    "ai-agent",
+    "memory",
+    "blockchain",
+    "micropayments"
+  ],
+  "files": [
+    "src/",
+    "examples/"
+  ],
+  "author": "zcoolz",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/indelible-one/clawsats-indelible"
+  }
+}

package/src/auth.js

@@ -0,0 +1,70 @@
+/**
+ * Mutual Authentication (BRC-31 Authrite)
+ *
+ * Replaces plain X-Operator-Address headers with proper cryptographic
+ * mutual authentication. Both sides prove identity on every request.
+ * No tokens to steal, no sessions to hijack.
+ *
+ * Uses AuthFetch from @bsv/sdk which implements the full Authrite protocol.
+ */
+
+import { AuthFetch, ProtoWallet, PrivateKey } from '@bsv/sdk'
+
+/**
+ * Create an authenticated HTTP client for agent-to-server communication
+ *
+ * @param {object} config
+ * @param {string} config.privateKeyWif - Agent or operator's private key (WIF)
+ * @returns {object} { fetch: function, wallet: ProtoWallet, publicKey: string }
+ */
+export function createAuthClient(config) {
+  const { privateKeyWif } = config
+
+  if (!privateKeyWif) throw new Error('privateKeyWif required')
+
+  const key = PrivateKey.fromWif(privateKeyWif)
+  const wallet = new ProtoWallet(key)
+  const authFetch = new AuthFetch(wallet)
+
+  return {
+    /**
+     * Make an authenticated HTTP request (BRC-31 Authrite)
+     * Automatically handles mutual authentication and 402 payment flows
+     *
+     * @param {string} url - Full URL to request
+     * @param {object} options - { method, headers, body }
+     * @returns {Promise<Response>}
+     */
+    fetch: (url, options = {}) => authFetch.fetch(url, options),
+
+    /** The underlying ProtoWallet for signing/verifying */
+    wallet,
+
+    /** This client's public key (hex, compressed) */
+    publicKey: key.toPublicKey().toString()
+  }
+}
+
+/**
+ * Verify an Authrite-authenticated request on the server side
+ *
+ * The server creates its own AuthFetch wallet to verify incoming
+ * requests are from legitimate agents with valid keys.
+ *
+ * @param {object} config
+ * @param {string} config.serverWif - Server's private key (WIF)
+ * @returns {object} { wallet: ProtoWallet, publicKey: string }
+ */
+export function createAuthServer(config) {
+  const { serverWif } = config
+
+  if (!serverWif) throw new Error('serverWif required')
+
+  const key = PrivateKey.fromWif(serverWif)
+  const wallet = new ProtoWallet(key)
+
+  return {
+    wallet,
+    publicKey: key.toPublicKey().toString()
+  }
+}

package/src/bridge.js

@@ -0,0 +1,122 @@
+/**
+ * IndelibleMemoryBridge
+ * Drop-in replacement for ClawSats' OnChainMemory (CLAWMEM_V1)
+ *
+ * Advantages over OnChainMemory:
+ * - Chunked transactions (unlimited payload via delta saves)
+ * - SPV bridge (no WhatsOnChain dependency)
+ * - Structured JSONL with session chaining
+ * - Delta saves (only new messages committed)
+ * - AES-256-GCM encryption per agent
+ * - Smart restore (tail-heavy priority)
+ * - Redis-indexed (recoverable from chain if index lost)
+ */
+
+import fetch from 'node-fetch'
+import { DEFAULT_INDELIBLE_URL } from './constants.js'
+
+export class IndelibleMemoryBridge {
+  /**
+   * @param {object} config
+   * @param {string} config.indelibleUrl - Indelible server URL
+   * @param {string} config.operatorAddress - BSV address of the operator
+   * @param {string} config.agentAddress - BSV address of this agent
+   */
+  constructor(config) {
+    this.indelibleUrl = config.indelibleUrl || DEFAULT_INDELIBLE_URL
+    this.operatorAddress = config.operatorAddress
+    this.agentAddress = config.agentAddress
+
+    if (!this.operatorAddress) throw new Error('operatorAddress required')
+    if (!this.agentAddress) throw new Error('agentAddress required')
+  }
+
+  /**
+   * Save agent memory to blockchain
+   * Drop-in replacement for OnChainMemory.save(key, data)
+   *
+   * @param {string} key - Agent identifier / memory key
+   * @param {Array|object} data - Messages array or raw data object
+   * @param {object} options
+   * @param {string} options.summary - Human-readable summary
+   * @returns {object} { success, txId, sessionId, messageCount, saveType }
+   */
+  async save(key, data, options = {}) {
+    const messages = Array.isArray(data)
+      ? data
+      : [{ role: 'system', content: JSON.stringify(data) }]
+
+    const result = await this._call('/api/agents/save', {
+      agentAddress: this.agentAddress,
+      agentId: key,
+      messages,
+      summary: options.summary || `Agent memory: ${key}`,
+      operatorAddress: this.operatorAddress
+    })
+
+    return result
+  }
+
+  /**
+   * Load agent memory from blockchain
+   * Drop-in replacement for OnChainMemory.load(key)
+   *
+   * @param {string} key - Agent identifier (unused in v1, loads by address)
+   * @param {object} options
+   * @param {number} options.numSessions - Number of sessions to restore (default 3)
+   * @returns {string|null} Formatted context string or null
+   */
+  async load(key, options = {}) {
+    const result = await this._call('/api/agents/load', {
+      agentAddress: this.agentAddress,
+      numSessions: options.numSessions || 3,
+      operatorAddress: this.operatorAddress
+    })
+
+    return result.context || null
+  }
+
+  /**
+   * List all sessions for this agent
+   * @returns {Array} Session metadata (no content, just summaries/timestamps/txIds)
+   */
+  async list() {
+    const res = await fetch(
+      `${this.indelibleUrl}/api/agents/sessions/${this.agentAddress}`,
+      {
+        headers: {
+          'X-Operator-Address': this.operatorAddress
+        }
+      }
+    )
+
+    if (!res.ok) {
+      const err = await res.text()
+      throw new Error(`List failed (${res.status}): ${err}`)
+    }
+
+    const data = await res.json()
+    return data.sessions || []
+  }
+
+  /**
+   * Internal: POST to Indelible server
+   */
+  async _call(path, body) {
+    const res = await fetch(`${this.indelibleUrl}${path}`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Operator-Address': this.operatorAddress
+      },
+      body: JSON.stringify(body)
+    })
+
+    if (!res.ok) {
+      const err = await res.text()
+      throw new Error(`Indelible ${path} failed (${res.status}): ${err}`)
+    }
+
+    return res.json()
+  }
+}

package/src/capabilities.js

@@ -0,0 +1,101 @@
+/**
+ * ClawSats Capability Registration
+ * Registers save_context and load_context as paid ClawSats capabilities
+ */
+
+import fetch from 'node-fetch'
+import { PRICES, CAPABILITY_TAGS, DEFAULT_INDELIBLE_URL } from './constants.js'
+
+/**
+ * Register Indelible memory capabilities with a ClawSats CapabilityRegistry
+ *
+ * @param {object} registry - ClawSats CapabilityRegistry instance
+ * @param {object} config
+ * @param {string} config.indelibleUrl - Indelible server URL (default: https://indelible.one)
+ * @param {string} config.operatorAddress - BSV address of the operator running this node
+ */
+export function registerIndelibleCapabilities(registry, config) {
+  const {
+    indelibleUrl = DEFAULT_INDELIBLE_URL,
+    operatorAddress
+  } = config
+
+  if (!operatorAddress) throw new Error('operatorAddress required')
+
+  // save_context — 15 sats
+  // Agent sends messages + summary, gets txId back
+  registry.register({
+    name: 'save_context',
+    description: 'Save agent memory to BSV blockchain via Indelible SPV bridge. Supports delta saves, session chaining, and AES-256-GCM encrypted storage. Your data survives crashes, migrations, and host death.',
+    pricePerCall: PRICES.save_context,
+    tags: CAPABILITY_TAGS.save,
+    handler: async (params) => {
+      const { messages, summary, agentAddress, agentId } = params
+
+      if (!messages || !Array.isArray(messages) || messages.length === 0) {
+        throw new Error('messages array required')
+      }
+      if (!agentAddress) {
+        throw new Error('agentAddress required')
+      }
+
+      const response = await fetch(`${indelibleUrl}/api/agents/save`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-Operator-Address': operatorAddress
+        },
+        body: JSON.stringify({
+          messages,
+          summary: summary || `Agent ${agentId || agentAddress} session`,
+          agentAddress,
+          agentId: agentId || agentAddress,
+          operatorAddress
+        })
+      })
+
+      if (!response.ok) {
+        const err = await response.text()
+        throw new Error(`Save failed (${response.status}): ${err}`)
+      }
+
+      return response.json()
+    }
+  })
+
+  // load_context — 10 sats
+  // Agent sends its address, gets restored context back
+  registry.register({
+    name: 'load_context',
+    description: 'Load agent memory from BSV blockchain via Indelible. Smart restore with tail-heavy priority — recent messages in full, older ones summarized. Merges delta saves automatically.',
+    pricePerCall: PRICES.load_context,
+    tags: CAPABILITY_TAGS.load,
+    handler: async (params) => {
+      const { agentAddress, numSessions = 3 } = params
+
+      if (!agentAddress) {
+        throw new Error('agentAddress required')
+      }
+
+      const response = await fetch(`${indelibleUrl}/api/agents/load`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-Operator-Address': operatorAddress
+        },
+        body: JSON.stringify({
+          agentAddress,
+          numSessions,
+          operatorAddress
+        })
+      })
+
+      if (!response.ok) {
+        const err = await response.text()
+        throw new Error(`Load failed (${response.status}): ${err}`)
+      }
+
+      return response.json()
+    }
+  })
+}

package/src/constants.js

@@ -0,0 +1,18 @@
+/**
+ * ClawSats-Indelible Constants
+ * Pricing, protocol tags, and configuration defaults
+ */
+
+export const PRICES = {
+  save_context: 15,   // sats paid to operator per save
+  load_context: 10,   // sats paid to operator per load
+  protocol_fee: 2     // sats ClawSats protocol fee per call
+}
+
+export const PROTOCOL_TAG = 'indelible.agent'
+export const DEFAULT_INDELIBLE_URL = 'https://indelible.one'
+
+export const CAPABILITY_TAGS = {
+  save: ['memory', 'persistence', 'blockchain', 'indelible'],
+  load: ['memory', 'recall', 'blockchain', 'indelible']
+}

package/src/discovery.js

@@ -0,0 +1,80 @@
+/**
+ * Service Discovery (SHIP/SLAP)
+ *
+ * Agents advertise what they can do (SHIP) and discover other agents'
+ * capabilities (SLAP). An agent broadcasts "I offer save_context" and
+ * others can find it through the overlay network.
+ *
+ * SHIP = Service Host Interconnect Protocol (advertise services)
+ * SLAP = Service Lookup Availability Protocol (discover services)
+ *
+ * Uses SHIPBroadcaster and LookupResolver from @bsv/sdk.
+ */
+
+import { SHIPBroadcaster, LookupResolver } from '@bsv/sdk'
+
+/** Default topic prefix for Indelible agent services */
+const TOPIC_PREFIX = 'tm_indelible_'
+
+/**
+ * Create a service broadcaster for advertising agent capabilities
+ *
+ * Agents use this to announce what services they offer on the overlay network.
+ * Other agents can then discover them via SLAP lookup.
+ *
+ * @param {object} config
+ * @param {string[]} config.capabilities - Services this agent offers (e.g. ['save_context', 'load_context'])
+ * @param {string} config.network - 'mainnet' | 'testnet' (default: 'mainnet')
+ * @returns {object} { broadcaster: SHIPBroadcaster, topics: string[] }
+ */
+export function createServiceBroadcaster(config) {
+  const { capabilities, network = 'mainnet' } = config
+
+  if (!capabilities || !capabilities.length) throw new Error('capabilities array required')
+
+  const topics = capabilities.map(cap => `${TOPIC_PREFIX}${cap}`)
+
+  const broadcaster = new SHIPBroadcaster(topics, {
+    networkPreset: network
+  })
+
+  return { broadcaster, topics }
+}
+
+/**
+ * Create a service resolver for discovering agent capabilities
+ *
+ * Operators use this to find agents that offer specific services.
+ *
+ * @param {object} config
+ * @param {string} config.network - 'mainnet' | 'testnet' (default: 'mainnet')
+ * @returns {object} { resolver: LookupResolver, lookup: function }
+ */
+export function createServiceResolver(config = {}) {
+  const { network = 'mainnet' } = config
+
+  const resolver = new LookupResolver({
+    networkPreset: network
+  })
+
+  return {
+    resolver,
+
+    /**
+     * Look up agents offering a specific capability
+     *
+     * @param {string} capability - Service to search for (e.g. 'save_context')
+     * @param {number} timeout - Timeout in ms (default: 5000)
+     * @returns {Promise<object>} Lookup answer with available service providers
+     */
+    lookup: (capability, timeout = 5000) => {
+      const topic = `${TOPIC_PREFIX}${capability}`
+      return resolver.query({
+        service: 'ls_slap',
+        query: { topic }
+      }, timeout)
+    }
+  }
+}
+
+export { TOPIC_PREFIX }

package/src/encryption.js

@@ -0,0 +1,62 @@
+/**
+ * Encrypted Messages (BRC-78)
+ *
+ * Agent-to-agent private communication. Two agents can exchange
+ * encrypted data that only the intended recipient can decrypt.
+ * Different from per-agent AES storage encryption — this is for
+ * direct agent-to-agent messaging.
+ *
+ * Uses EncryptedMessage from @bsv/sdk which implements BRC-78.
+ */
+
+import { EncryptedMessage, PrivateKey, PublicKey, Utils } from '@bsv/sdk'
+
+/**
+ * Encrypt a message from one agent to another
+ *
+ * @param {object} config
+ * @param {string} config.senderWif - Sender's private key (WIF)
+ * @param {string} config.recipientPubKey - Recipient's public key (hex, compressed)
+ * @param {string|object} config.message - Message to encrypt (string or object → JSON)
+ * @returns {string} Encrypted message as hex
+ */
+export function encryptMessage(config) {
+  const { senderWif, recipientPubKey, message } = config
+
+  if (!senderWif) throw new Error('senderWif required')
+  if (!recipientPubKey) throw new Error('recipientPubKey required')
+  if (message === undefined || message === null) throw new Error('message required')
+
+  const senderKey = PrivateKey.fromWif(senderWif)
+  const recipientKey = PublicKey.fromString(recipientPubKey)
+
+  const text = typeof message === 'string' ? message : JSON.stringify(message)
+  const messageBytes = Utils.toArray(text, 'utf8')
+
+  const encrypted = EncryptedMessage.encrypt(messageBytes, senderKey, recipientKey)
+  return Utils.toHex(encrypted)
+}
+
+/**
+ * Decrypt a message received from another agent
+ *
+ * @param {object} config
+ * @param {string} config.recipientWif - Recipient's private key (WIF)
+ * @param {string} config.encryptedHex - Encrypted message hex from encryptMessage
+ * @param {boolean} config.parseJson - If true, parse the decrypted text as JSON (default: false)
+ * @returns {string|object} Decrypted message
+ */
+export function decryptMessage(config) {
+  const { recipientWif, encryptedHex, parseJson = false } = config
+
+  if (!recipientWif) throw new Error('recipientWif required')
+  if (!encryptedHex) throw new Error('encryptedHex required')
+
+  const recipientKey = PrivateKey.fromWif(recipientWif)
+  const encryptedBytes = Utils.toArray(encryptedHex, 'hex')
+
+  const decrypted = EncryptedMessage.decrypt(encryptedBytes, recipientKey)
+  const text = Utils.toUTF8(decrypted)
+
+  return parseJson ? JSON.parse(text) : text
+}

package/src/identity.js

@@ -0,0 +1,102 @@
+/**
+ * Agent Identity (BRC-52 Certificates)
+ *
+ * Agents register with verifiable identity certificates signed by their operator.
+ * Certificates prove: who the agent is, who operates it, and what it can do.
+ * Other parties verify the certificate without trusting the server.
+ */
+
+import { Certificate, ProtoWallet, PrivateKey, Hash, Utils, Random } from '@bsv/sdk'
+
+// Fixed certificate type for Indelible agent identity
+// SHA-256("indelible.agent.identity.v1") → exactly 32 bytes as base64
+const AGENT_CERT_TYPE = Utils.toBase64(
+  Hash.sha256(Utils.toArray('indelible.agent.identity.v1', 'utf8'))
+)
+
+/**
+ * Create a signed agent identity certificate
+ *
+ * @param {object} config
+ * @param {string} config.operatorWif - Operator's private key (WIF) — signs the certificate
+ * @param {string} config.agentPubKey - Agent's public key (hex, compressed)
+ * @param {string} config.agentName - Human-readable agent name
+ * @param {string[]} config.capabilities - What this agent can do (e.g. ['save_context', 'load_context'])
+ * @returns {object} { certificate: Certificate, serialized: string (hex) }
+ */
+export async function createAgentCertificate(config) {
+  const { operatorWif, agentPubKey, agentName, capabilities = [] } = config
+
+  if (!operatorWif) throw new Error('operatorWif required')
+  if (!agentPubKey) throw new Error('agentPubKey required')
+  if (!agentName) throw new Error('agentName required')
+
+  const operatorKey = PrivateKey.fromWif(operatorWif)
+  const serialNumber = Utils.toBase64(Random(32))
+
+  const fields = {
+    agentName: Utils.toBase64(Utils.toArray(agentName, 'utf8')),
+    capabilities: Utils.toBase64(Utils.toArray(JSON.stringify(capabilities), 'utf8')),
+    registeredAt: Utils.toBase64(Utils.toArray(new Date().toISOString(), 'utf8'))
+  }
+
+  const cert = new Certificate(
+    AGENT_CERT_TYPE,
+    serialNumber,
+    agentPubKey,
+    operatorKey.toPublicKey().toString(),
+    '0000000000000000000000000000000000000000000000000000000000000000.0',
+    fields
+  )
+
+  const wallet = new ProtoWallet(operatorKey)
+  await cert.sign(wallet)
+
+  return {
+    certificate: cert,
+    serialized: Utils.toHex(cert.toBinary())
+  }
+}
+
+/**
+ * Verify an agent identity certificate
+ *
+ * @param {string} serializedHex - Certificate in hex (from createAgentCertificate)
+ * @returns {object} { valid: boolean, subject, certifier, fields: { agentName, capabilities, registeredAt } }
+ */
+export async function verifyAgentCertificate(serializedHex) {
+  const bin = Utils.toArray(serializedHex, 'hex')
+  const cert = Certificate.fromBinary(bin)
+
+  const valid = await cert.verify()
+
+  // Decode fields from base64
+  const decode = (b64) => {
+    try {
+      return Utils.toUTF8(Utils.toArray(b64, 'base64'))
+    } catch {
+      return b64
+    }
+  }
+
+  const fields = {}
+  if (cert.fields.agentName) fields.agentName = decode(cert.fields.agentName)
+  if (cert.fields.capabilities) {
+    try {
+      fields.capabilities = JSON.parse(decode(cert.fields.capabilities))
+    } catch {
+      fields.capabilities = []
+    }
+  }
+  if (cert.fields.registeredAt) fields.registeredAt = decode(cert.fields.registeredAt)
+
+  return {
+    valid,
+    subject: cert.subject,
+    certifier: cert.certifier,
+    serialNumber: cert.serialNumber,
+    fields
+  }
+}
+
+export { AGENT_CERT_TYPE }

package/src/index.js

@@ -0,0 +1,36 @@
+/**
+ * clawsats-indelible
+ * Persistent blockchain memory for ClawSats AI agents
+ *
+ * Gives ClawSats agents what they're missing: permanent, portable,
+ * self-sovereign memory that survives crashes, migrations, and host death.
+ *
+ * BRC Standards implemented:
+ *   BRC-105  — Payment verification (middleware.js)
+ *   BRC-52   — Agent identity certificates (identity.js)
+ *   BRC-31   — Mutual authentication / Authrite (auth.js)
+ *   BRC-77   — Signed messages (signing.js)
+ *   BRC-78   — Encrypted messages (encryption.js)
+ *   SHIP/SLAP — Service discovery (discovery.js)
+ */
+
+// Core
+export { registerIndelibleCapabilities } from './capabilities.js'
+export { IndelibleMemoryBridge } from './bridge.js'
+export { createIndeliblePaymentMiddleware } from './middleware.js'
+export { PRICES, PROTOCOL_TAG, DEFAULT_INDELIBLE_URL, CAPABILITY_TAGS } from './constants.js'
+
+// BRC-52 — Agent Identity
+export { createAgentCertificate, verifyAgentCertificate, AGENT_CERT_TYPE } from './identity.js'
+
+// BRC-31 — Mutual Authentication
+export { createAuthClient, createAuthServer } from './auth.js'
+
+// BRC-77 — Signed Messages
+export { signAction, verifyAction } from './signing.js'
+
+// BRC-78 — Encrypted Messages
+export { encryptMessage, decryptMessage } from './encryption.js'
+
+// SHIP/SLAP — Service Discovery
+export { createServiceBroadcaster, createServiceResolver, TOPIC_PREFIX } from './discovery.js'

package/src/middleware.js

@@ -0,0 +1,122 @@
+/**
+ * BRC-105 Payment Middleware (v2 — Real Verification)
+ *
+ * Implements the HTTP 402 Payment Required flow for Indelible capabilities.
+ * When a request comes in without payment, returns 402 with required headers.
+ * When payment is included, parses the raw transaction and verifies an output
+ * pays the operator address the required amount.
+ */
+
+import crypto from 'crypto'
+import { Transaction, P2PKH } from '@bsv/sdk'
+
+/**
+ * Create Express middleware for BRC-105 payment gating
+ *
+ * @param {object} config
+ * @param {string} config.operatorAddress - BSV address to receive payments
+ * @param {function} config.calculatePrice - (req) => sats required
+ * @returns {function} Express middleware
+ */
+export function createIndeliblePaymentMiddleware(config) {
+  const { operatorAddress, calculatePrice } = config
+  const usedPrefixes = new Set()
+
+  if (!operatorAddress) throw new Error('operatorAddress required')
+  if (!calculatePrice) throw new Error('calculatePrice function required')
+
+  return async (req, res, next) => {
+    const price = await calculatePrice(req)
+
+    // Free calls pass through
+    if (price === 0) {
+      req.payment = { satoshisPaid: 0, accepted: true }
+      return next()
+    }
+
+    const paymentHeader = req.headers['x-bsv-payment']
+
+    // No payment: return 402 challenge
+    if (!paymentHeader) {
+      const prefix = crypto.randomBytes(16).toString('base64')
+
+      res.set('x-bsv-payment-version', '1.0')
+      res.set('x-bsv-payment-satoshis-required', String(price))
+      res.set('x-bsv-payment-derivation-prefix', prefix)
+      res.set('x-bsv-payment-address', operatorAddress)
+
+      return res.status(402).json({
+        status: 'error',
+        code: 'ERR_PAYMENT_REQUIRED',
+        satoshisRequired: price,
+        operatorAddress,
+        description: `Pay ${price} sats to use Indelible memory service`
+      })
+    }
+
+    // Payment included: verify
+    try {
+      const payment = JSON.parse(paymentHeader)
+      const { derivationPrefix, transaction } = payment
+
+      // Replay protection
+      if (usedPrefixes.has(derivationPrefix)) {
+        return res.status(400).json({ error: 'Payment prefix already used (replay detected)' })
+      }
+
+      // BRC-105 v2: Parse raw transaction and verify payment output
+      if (!transaction || typeof transaction !== 'string') {
+        return res.status(400).json({ error: 'Invalid payment transaction' })
+      }
+
+      // Parse the transaction hex
+      let tx
+      try {
+        tx = Transaction.fromHex(transaction)
+      } catch (parseErr) {
+        return res.status(400).json({ error: `Invalid transaction hex: ${parseErr.message}` })
+      }
+
+      // Build expected locking script for operator address
+      const p2pkh = new P2PKH()
+      const expectedScript = p2pkh.lock(operatorAddress).toHex()
+
+      // Find output(s) paying to operator address
+      let satoshisPaid = 0
+      for (const output of tx.outputs) {
+        if (output.lockingScript.toHex() === expectedScript) {
+          satoshisPaid += output.satoshis
+        }
+      }
+
+      if (satoshisPaid < price) {
+        return res.status(400).json({
+          error: `Insufficient payment: ${satoshisPaid} sats paid, ${price} required`,
+          satoshisPaid,
+          satoshisRequired: price
+        })
+      }
+
+      usedPrefixes.add(derivationPrefix)
+
+      // Clean up old prefixes (memory management)
+      if (usedPrefixes.size > 10000) {
+        const iterator = usedPrefixes.values()
+        for (let i = 0; i < 5000; i++) {
+          usedPrefixes.delete(iterator.next().value)
+        }
+      }
+
+      req.payment = {
+        satoshisPaid,
+        accepted: true,
+        derivationPrefix,
+        txid: tx.id('hex')
+      }
+
+      next()
+    } catch (err) {
+      res.status(400).json({ error: `Payment verification failed: ${err.message}` })
+    }
+  }
+}

package/src/signing.js

@@ -0,0 +1,65 @@
+/**
+ * Signed Messages (BRC-77)
+ *
+ * Agents cryptographically sign their actions (saves, loads, requests).
+ * Anyone can verify "agent X really did this" — not spoofable.
+ *
+ * Uses SignedMessage from @bsv/sdk which implements BRC-77.
+ */
+
+import { SignedMessage, PrivateKey, Utils } from '@bsv/sdk'
+
+/**
+ * Sign an agent action
+ *
+ * @param {object} config
+ * @param {string} config.privateKeyWif - Agent's private key (WIF)
+ * @param {string} config.action - Action name (e.g. 'save_context', 'load_context')
+ * @param {object} config.payload - Action payload to sign
+ * @returns {object} { signature: string (hex), publicKey: string, action, timestamp }
+ */
+export function signAction(config) {
+  const { privateKeyWif, action, payload } = config
+
+  if (!privateKeyWif) throw new Error('privateKeyWif required')
+  if (!action) throw new Error('action required')
+
+  const key = PrivateKey.fromWif(privateKeyWif)
+  const timestamp = new Date().toISOString()
+
+  // Build canonical message: action + timestamp + sorted payload JSON
+  const message = JSON.stringify({ action, timestamp, payload })
+  const messageBytes = Utils.toArray(message, 'utf8')
+
+  const sig = SignedMessage.sign(messageBytes, key)
+
+  return {
+    signature: Utils.toHex(sig),
+    publicKey: key.toPublicKey().toString(),
+    action,
+    timestamp
+  }
+}
+
+/**
+ * Verify a signed agent action
+ *
+ * @param {object} config
+ * @param {string} config.signature - Signature hex from signAction
+ * @param {string} config.action - Action name
+ * @param {string} config.timestamp - ISO timestamp from signAction
+ * @param {object} config.payload - Original payload
+ * @returns {boolean} true if signature is valid
+ */
+export function verifyAction(config) {
+  const { signature, action, timestamp, payload } = config
+
+  if (!signature) throw new Error('signature required')
+  if (!action) throw new Error('action required')
+
+  const message = JSON.stringify({ action, timestamp, payload })
+  const messageBytes = Utils.toArray(message, 'utf8')
+  const sigBytes = Utils.toArray(signature, 'hex')
+
+  return SignedMessage.verify(messageBytes, sigBytes)
+}