@bsv/simple-mcp 0.0.1

package/dist/resources/gotchas.js

@@ -0,0 +1,188 @@
+"use strict";
+// Critical pitfalls and gotchas
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gotchasReference = void 0;
+exports.gotchasReference = `# @bsv/simple — Critical Gotchas
+
+## 1. basket insertion vs wallet payment are MUTUALLY EXCLUSIVE
+
+In \`internalizeAction\`, each output can use EITHER \`basket insertion\` OR \`wallet payment\`, never both.
+
+- **wallet payment** — provides derivation info for spending. Output is NOT in any app basket.
+- **basket insertion** — puts output in a named basket (visible via \`listOutputs\`). Derivation info must go in \`customInstructions\`.
+
+\`\`\`typescript
+// CORRECT: basket insertion
+await client.internalizeAction({
+  tx: txBytes,
+  outputs: [{
+    outputIndex: 0,
+    protocol: 'basket insertion',
+    insertionRemittance: {
+      basket: 'my-basket',
+      customInstructions: JSON.stringify({ derivationPrefix, derivationSuffix }),
+      tags: ['payment']
+    }
+  }]
+})
+
+// CORRECT: wallet payment
+await client.internalizeAction({
+  tx: txBytes,
+  outputs: [{
+    outputIndex: 0,
+    protocol: 'wallet payment',
+    paymentRemittance: {
+      senderIdentityKey,
+      derivationPrefix,
+      derivationSuffix
+    }
+  }]
+})
+
+// WRONG: both on same output — will fail
+\`\`\`
+
+## 2. PeerPayClient.acceptPayment() swallows errors
+
+Returns the string \`'Unable to receive payment!'\` instead of throwing an error.
+
+\`\`\`typescript
+// WRONG: silently fails
+await peerPay.acceptPayment(payment)
+
+// CORRECT: always check
+const result = await peerPay.acceptPayment(payment)
+if (typeof result === 'string') throw new Error(result)
+\`\`\`
+
+The simple library handles this internally, but be aware when using \`@bsv/message-box-client\` directly.
+
+## 3. result.tx from createAction may be undefined
+
+Always check before using:
+\`\`\`typescript
+const result = await client.createAction({ ... })
+if (!result.tx) {
+  console.warn('No tx bytes available')
+  return
+}
+// Now safe to use result.tx
+\`\`\`
+
+## 4. BRC-29 Payment Derivation Protocol ID
+
+Always use: \`[2, '3241645161d8']\`
+\`\`\`typescript
+const protocolID: [SecurityLevel, string] = [2, '3241645161d8']
+\`\`\`
+
+## 5. FileRevocationStore is server-only
+
+It uses Node.js \`fs\` module and will crash in the browser. It's isolated in \`file-revocation-store.ts\` to prevent Turbopack from bundling it.
+
+\`\`\`typescript
+// Browser: use MemoryRevocationStore
+import { MemoryRevocationStore } from '@bsv/simple/browser'
+
+// Server: use FileRevocationStore
+const { FileRevocationStore } = await import('@bsv/simple/server')
+\`\`\`
+
+## 6. Overlay topics must start with tm_, services with ls_
+
+The Overlay class enforces these prefixes and throws if violated:
+\`\`\`typescript
+// CORRECT
+await Overlay.create({ topics: ['tm_payments'] })
+await wallet.advertiseSLAP('domain.com', 'ls_payments')
+
+// WRONG — throws Error
+await Overlay.create({ topics: ['payments'] })
+await wallet.advertiseSLAP('domain.com', 'payments')
+\`\`\`
+
+## 7. Token send/redeem uses two-step signing
+
+Token transfers require: \`createAction\` → get \`signableTransaction\` → sign with PushDrop unlock → \`signAction\`. Don't try to do it in a single step.
+
+## 8. pay() uses PeerPayClient.sendPayment()
+
+Payments via \`wallet.pay()\` are routed through MessageBox P2P using PeerPayClient, not direct on-chain P2PKH. For direct on-chain payments, use \`wallet.send()\` with a P2PKH output:
+
+\`\`\`typescript
+// MessageBox P2P payment (via pay):
+await wallet.pay({ to: recipientKey, satoshis: 1000 })
+
+// Direct on-chain P2PKH (via send):
+await wallet.send({
+  outputs: [{ to: recipientKey, satoshis: 1000 }],
+  description: 'Direct payment'
+})
+\`\`\`
+
+## 9. Server exports not available from @bsv/simple
+
+Server-only utilities (ServerWallet, handler factories, FileRevocationStore, generatePrivateKey) must be imported from \`@bsv/simple/server\`, not from the main \`@bsv/simple\` entry point.
+
+\`\`\`typescript
+// WRONG
+import { ServerWallet } from '@bsv/simple'
+
+// CORRECT
+import { ServerWallet } from '@bsv/simple/server'
+\`\`\`
+
+## 10. Dynamic imports for server code in Next.js
+
+Always use \`await import()\` for server-only code in API routes:
+\`\`\`typescript
+// WRONG: static import at top of API route
+import { ServerWallet } from '@bsv/simple/server'
+
+// CORRECT: dynamic import inside handler
+const { ServerWallet } = await import('@bsv/simple/server')
+\`\`\`
+
+## 11. next.config.ts serverExternalPackages is required (updated for v2)
+
+Without this, Turbopack bundles \`@bsv/wallet-toolbox\`, \`knex\`, and database drivers for the browser:
+\`\`\`typescript
+const nextConfig: NextConfig = {
+  serverExternalPackages: [
+    "@bsv/wallet-toolbox", "knex", "better-sqlite3", "tedious",
+    "mysql", "mysql2", "pg", "pg-query-stream", "oracledb", "dotenv"
+  ]
+}
+\`\`\`
+
+## 12. Server wallet initialization — use handler factories
+
+The \`createServerWalletHandler()\` factory handles lazy-init singleton + key persistence automatically. No manual caching needed:
+\`\`\`typescript
+// OLD (manual caching pattern — no longer needed):
+// let serverWallet: any = null
+// let initPromise: Promise<any> | null = null
+// async function getServerWallet() { /* ... 50 lines of boilerplate ... */ }
+
+// NEW (3 lines):
+import { createServerWalletHandler } from '@bsv/simple/server'
+const handler = createServerWalletHandler()
+export const GET = handler.GET, POST = handler.POST
+\`\`\`
+
+Similarly, use \`createIdentityRegistryHandler()\`, \`createDIDResolverHandler()\`, and \`createCredentialIssuerHandler()\` — all handle lazy init and file persistence internally.
+
+## 13. No need to import @bsv/sdk
+
+Never import \`@bsv/sdk\` in consumer code. Use \`generatePrivateKey()\` from \`@bsv/simple/server\`:
+\`\`\`typescript
+// WRONG
+// import { PrivateKey } from '@bsv/sdk'
+// const key = PrivateKey.fromRandom().toHex()
+
+// CORRECT
+import { generatePrivateKey } from '@bsv/simple/server'
+const key = generatePrivateKey()
+\`\`\`
+`;

package/dist/resources/integration.d.ts

@@ -0,0 +1 @@
+export declare const nextjsIntegrationGuide = "# @bsv/simple \u2014 Next.js Integration Guide\n\n## 1. Installation\n\n```bash\nnpm install @bsv/simple\n```\n\nNote: `@bsv/sdk` is NOT needed as a direct dependency \u2014 `@bsv/simple` wraps it entirely.\n\n## 2. next.config.ts (CRITICAL)\n\nThis is required for Turbopack to work. Without it, `@bsv/wallet-toolbox` and its database drivers will be bundled for the browser, causing build failures.\n\n```typescript\nimport type { NextConfig } from \"next\";\n\nconst nextConfig: NextConfig = {\n  serverExternalPackages: [\n    \"@bsv/wallet-toolbox\",\n    \"knex\",\n    \"better-sqlite3\",\n    \"tedious\",\n    \"mysql\",\n    \"mysql2\",\n    \"pg\",\n    \"pg-query-stream\",\n    \"oracledb\",\n    \"dotenv\"\n  ]\n};\n\nexport default nextConfig;\n```\n\n## 3. Import Patterns\n\n### Browser components (`'use client'`)\n```typescript\nimport { createWallet, Certifier, DID, Overlay } from '@bsv/simple/browser'\nimport { CredentialSchema, CredentialIssuer, MemoryRevocationStore } from '@bsv/simple/browser'\nimport type { BrowserWallet } from '@bsv/simple/browser'\n```\n\n### Server API routes (handler factories \u2014 preferred)\n```typescript\nimport { createIdentityRegistryHandler } from '@bsv/simple/server'\nimport { createDIDResolverHandler } from '@bsv/simple/server'\nimport { createServerWalletHandler } from '@bsv/simple/server'\nimport { createCredentialIssuerHandler } from '@bsv/simple/server'\n```\n\n### Server utilities (lower-level access)\n```typescript\nconst { ServerWallet, generatePrivateKey } = await import('@bsv/simple/server')\nconst { FileRevocationStore } = await import('@bsv/simple/server')\n```\n\n## 4. Browser Wallet Setup\n\n```typescript\n'use client'\nimport { useState } from 'react'\nimport { createWallet, type BrowserWallet } from '@bsv/simple/browser'\n\nexport default function Page() {\n  const [wallet, setWallet] = useState<BrowserWallet | null>(null)\n  const [status, setStatus] = useState('')\n\n  const connect = async () => {\n    try {\n      const w = await createWallet()\n      setWallet(w)\n      setStatus(`Connected: ${w.getIdentityKey()}`)\n    } catch (e) {\n      setStatus(`Error: ${(e as Error).message}`)\n    }\n  }\n\n  return (\n    <div>\n      <button onClick={connect}>Connect Wallet</button>\n      <p>{status}</p>\n    </div>\n  )\n}\n```\n\n## 5. Server API Routes (Simplified)\n\nAll server routes use handler factories \u2014 no boilerplate needed:\n\n```typescript\n// app/api/identity-registry/route.ts\nimport { createIdentityRegistryHandler } from '@bsv/simple/server'\nconst handler = createIdentityRegistryHandler()\nexport const GET = handler.GET, POST = handler.POST\n```\n\n```typescript\n// app/api/resolve-did/route.ts\nimport { createDIDResolverHandler } from '@bsv/simple/server'\nconst handler = createDIDResolverHandler()\nexport const GET = handler.GET\n```\n\n```typescript\n// app/api/server-wallet/route.ts\nimport { createServerWalletHandler } from '@bsv/simple/server'\nconst handler = createServerWalletHandler()\nexport const GET = handler.GET, POST = handler.POST\n```\n\n```typescript\n// app/api/credential-issuer/route.ts  (no [[...path]] needed!)\nimport { createCredentialIssuerHandler } from '@bsv/simple/server'\nconst handler = createCredentialIssuerHandler({\n  schemas: [{\n    id: 'my-credential',\n    name: 'MyCredential',\n    fields: [\n      { key: 'name', label: 'Full Name', type: 'text', required: true },\n    ]\n  }]\n})\nexport const GET = handler.GET, POST = handler.POST\n```\n\n## 6. Server Wallet Key Persistence\n\nKey persistence is handled automatically by `createServerWalletHandler()`:\n1. `process.env.SERVER_PRIVATE_KEY` \u2014 Environment variable (production)\n2. `.server-wallet.json` file \u2014 Persisted from previous run (development)\n3. Auto-generated via `generatePrivateKey()` \u2014 Fresh key (first run)\n\nNo `@bsv/sdk` import needed. Add `.server-wallet.json` to `.gitignore`.\n\n## 7. Basket Naming Conventions\n\nUse descriptive, hyphenated names:\n- `my-app-payments` \u2014 Payment outputs\n- `my-app-tokens` \u2014 PushDrop tokens\n- `text` \u2014 Text inscriptions\n- `json` \u2014 JSON inscriptions\n- `did-chain` \u2014 DID chain UTXOs\n- `revocation-utxos` \u2014 Credential revocation\n\n## 8. Common Patterns\n\n### Auto-connect on page load\n```typescript\nuseEffect(() => {\n  createWallet()\n    .then(setWallet)\n    .catch(() => {}) // User may not have wallet extension\n}, [])\n```\n\n### Check MessageBox handle on connect\n```typescript\nuseEffect(() => {\n  if (!wallet) return\n  wallet.getMessageBoxHandle('/api/identity-registry')\n    .then(h => setHandle(h))\n}, [wallet])\n```\n\n### Error handling pattern\n```typescript\ntry {\n  const result = await wallet.pay({ to: key, satoshis: 1000 })\n  setResult(JSON.stringify(result, null, 2))\n} catch (e) {\n  setError((e as Error).message)\n}\n```\n";

package/dist/resources/integration.js

@@ -0,0 +1,181 @@
+"use strict";
+// Next.js integration guide resource
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nextjsIntegrationGuide = void 0;
+exports.nextjsIntegrationGuide = `# @bsv/simple — Next.js Integration Guide
+
+## 1. Installation
+
+\`\`\`bash
+npm install @bsv/simple
+\`\`\`
+
+Note: \`@bsv/sdk\` is NOT needed as a direct dependency — \`@bsv/simple\` wraps it entirely.
+
+## 2. next.config.ts (CRITICAL)
+
+This is required for Turbopack to work. Without it, \`@bsv/wallet-toolbox\` and its database drivers will be bundled for the browser, causing build failures.
+
+\`\`\`typescript
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  serverExternalPackages: [
+    "@bsv/wallet-toolbox",
+    "knex",
+    "better-sqlite3",
+    "tedious",
+    "mysql",
+    "mysql2",
+    "pg",
+    "pg-query-stream",
+    "oracledb",
+    "dotenv"
+  ]
+};
+
+export default nextConfig;
+\`\`\`
+
+## 3. Import Patterns
+
+### Browser components (\`'use client'\`)
+\`\`\`typescript
+import { createWallet, Certifier, DID, Overlay } from '@bsv/simple/browser'
+import { CredentialSchema, CredentialIssuer, MemoryRevocationStore } from '@bsv/simple/browser'
+import type { BrowserWallet } from '@bsv/simple/browser'
+\`\`\`
+
+### Server API routes (handler factories — preferred)
+\`\`\`typescript
+import { createIdentityRegistryHandler } from '@bsv/simple/server'
+import { createDIDResolverHandler } from '@bsv/simple/server'
+import { createServerWalletHandler } from '@bsv/simple/server'
+import { createCredentialIssuerHandler } from '@bsv/simple/server'
+\`\`\`
+
+### Server utilities (lower-level access)
+\`\`\`typescript
+const { ServerWallet, generatePrivateKey } = await import('@bsv/simple/server')
+const { FileRevocationStore } = await import('@bsv/simple/server')
+\`\`\`
+
+## 4. Browser Wallet Setup
+
+\`\`\`typescript
+'use client'
+import { useState } from 'react'
+import { createWallet, type BrowserWallet } from '@bsv/simple/browser'
+
+export default function Page() {
+  const [wallet, setWallet] = useState<BrowserWallet | null>(null)
+  const [status, setStatus] = useState('')
+
+  const connect = async () => {
+    try {
+      const w = await createWallet()
+      setWallet(w)
+      setStatus(\`Connected: \${w.getIdentityKey()}\`)
+    } catch (e) {
+      setStatus(\`Error: \${(e as Error).message}\`)
+    }
+  }
+
+  return (
+    <div>
+      <button onClick={connect}>Connect Wallet</button>
+      <p>{status}</p>
+    </div>
+  )
+}
+\`\`\`
+
+## 5. Server API Routes (Simplified)
+
+All server routes use handler factories — no boilerplate needed:
+
+\`\`\`typescript
+// app/api/identity-registry/route.ts
+import { createIdentityRegistryHandler } from '@bsv/simple/server'
+const handler = createIdentityRegistryHandler()
+export const GET = handler.GET, POST = handler.POST
+\`\`\`
+
+\`\`\`typescript
+// app/api/resolve-did/route.ts
+import { createDIDResolverHandler } from '@bsv/simple/server'
+const handler = createDIDResolverHandler()
+export const GET = handler.GET
+\`\`\`
+
+\`\`\`typescript
+// app/api/server-wallet/route.ts
+import { createServerWalletHandler } from '@bsv/simple/server'
+const handler = createServerWalletHandler()
+export const GET = handler.GET, POST = handler.POST
+\`\`\`
+
+\`\`\`typescript
+// app/api/credential-issuer/route.ts  (no [[...path]] needed!)
+import { createCredentialIssuerHandler } from '@bsv/simple/server'
+const handler = createCredentialIssuerHandler({
+  schemas: [{
+    id: 'my-credential',
+    name: 'MyCredential',
+    fields: [
+      { key: 'name', label: 'Full Name', type: 'text', required: true },
+    ]
+  }]
+})
+export const GET = handler.GET, POST = handler.POST
+\`\`\`
+
+## 6. Server Wallet Key Persistence
+
+Key persistence is handled automatically by \`createServerWalletHandler()\`:
+1. \`process.env.SERVER_PRIVATE_KEY\` — Environment variable (production)
+2. \`.server-wallet.json\` file — Persisted from previous run (development)
+3. Auto-generated via \`generatePrivateKey()\` — Fresh key (first run)
+
+No \`@bsv/sdk\` import needed. Add \`.server-wallet.json\` to \`.gitignore\`.
+
+## 7. Basket Naming Conventions
+
+Use descriptive, hyphenated names:
+- \`my-app-payments\` — Payment outputs
+- \`my-app-tokens\` — PushDrop tokens
+- \`text\` — Text inscriptions
+- \`json\` — JSON inscriptions
+- \`did-chain\` — DID chain UTXOs
+- \`revocation-utxos\` — Credential revocation
+
+## 8. Common Patterns
+
+### Auto-connect on page load
+\`\`\`typescript
+useEffect(() => {
+  createWallet()
+    .then(setWallet)
+    .catch(() => {}) // User may not have wallet extension
+}, [])
+\`\`\`
+
+### Check MessageBox handle on connect
+\`\`\`typescript
+useEffect(() => {
+  if (!wallet) return
+  wallet.getMessageBoxHandle('/api/identity-registry')
+    .then(h => setHandle(h))
+}, [wallet])
+\`\`\`
+
+### Error handling pattern
+\`\`\`typescript
+try {
+  const result = await wallet.pay({ to: key, satoshis: 1000 })
+  setResult(JSON.stringify(result, null, 2))
+} catch (e) {
+  setError((e as Error).message)
+}
+\`\`\`
+`;

package/dist/resources/patterns.d.ts

@@ -0,0 +1 @@
+export declare const codePatterns = "# @bsv/simple \u2014 Common Code Patterns\n\n## Pattern 1: Connect Wallet + Auto-check MessageBox\n```typescript\n'use client'\nimport { useState, useEffect } from 'react'\nimport { createWallet, type BrowserWallet } from '@bsv/simple/browser'\n\nexport default function Page() {\n  const [wallet, setWallet] = useState<BrowserWallet | null>(null)\n  const [handle, setHandle] = useState<string | null>(null)\n\n  const connect = async () => {\n    const w = await createWallet()\n    setWallet(w)\n    const h = await w.getMessageBoxHandle('/api/identity-registry')\n    setHandle(h)\n  }\n\n  return (\n    <div>\n      {!wallet ? (\n        <button onClick={connect}>Connect Wallet</button>\n      ) : (\n        <div>\n          <p>Connected: {wallet.getIdentityKey().substring(0, 20)}...</p>\n          {handle && <p>Handle: {handle}</p>}\n        </div>\n      )}\n    </div>\n  )\n}\n```\n\n## Pattern 2: Simple Payment via MessageBox P2P\n```typescript\nconst result = await wallet.pay({\n  to: recipientKey,\n  satoshis: 1000\n})\n\nconsole.log('TXID:', result.txid)\n```\n\n## Pattern 3: Multi-Output Send\n```typescript\nconst result = await wallet.send({\n  outputs: [\n    { to: recipientKey, satoshis: 1000, basket: 'payments' },\n    { data: ['Hello blockchain!'], basket: 'text' },\n    { to: wallet.getIdentityKey(), data: [{ value: 42 }], satoshis: 1, basket: 'tokens' }\n  ],\n  description: 'Multi-output transaction'\n})\n```\n\n## Pattern 4: Token CRUD\n```typescript\n// Create\nconst token = await wallet.createToken({\n  data: { type: 'loyalty', points: 100 },\n  basket: 'my-tokens',\n  satoshis: 1\n})\n\n// List (decrypts automatically)\nconst tokens = await wallet.listTokenDetails('my-tokens')\n\n// Send\nawait wallet.sendToken({ basket: 'my-tokens', outpoint: tokens[0].outpoint, to: recipientKey })\n\n// Redeem\nawait wallet.redeemToken({ basket: 'my-tokens', outpoint: tokens[0].outpoint })\n```\n\n## Pattern 5: Token Transfer via MessageBox\n```typescript\n// Sender\nawait wallet.sendTokenViaMessageBox({ basket: 'my-tokens', outpoint: '...', to: recipientKey })\n\n// Recipient\nconst incoming = await wallet.listIncomingTokens()\nfor (const token of incoming) {\n  await wallet.acceptIncomingToken(token, 'received-tokens')\n}\n```\n\n## Pattern 6: Inscriptions\n```typescript\nconst text = await wallet.inscribeText('Hello blockchain!')\nconst json = await wallet.inscribeJSON({ title: 'Document', created: Date.now() })\nconst hash = await wallet.inscribeFileHash('a'.repeat(64))\n```\n\n## Pattern 7: MessageBox Payments\n```typescript\n// Register identity\nawait wallet.certifyForMessageBox('@alice', '/api/identity-registry')\n\n// Find recipient\nconst results = await wallet.lookupIdentityByTag('bob', '/api/identity-registry')\n\n// Send payment\nawait wallet.sendMessageBoxPayment(results[0].identityKey, 1000)\n\n// Receive payments\nconst incoming = await wallet.listIncomingPayments()\nfor (const payment of incoming) {\n  await wallet.acceptIncomingPayment(payment, 'received-payments')\n}\n```\n\n## Pattern 8: Server Wallet Funding Flow\n```typescript\n// Server side: 3-line handler (app/api/server-wallet/route.ts)\n// import { createServerWalletHandler } from '@bsv/simple/server'\n// const handler = createServerWalletHandler()\n// export const GET = handler.GET, POST = handler.POST\n\n// Client side:\n// 1. Get payment request from server\nconst res = await fetch('/api/server-wallet?action=request')\nconst { paymentRequest } = await res.json()\n\n// 2. Fund server wallet\nconst result = await wallet.fundServerWallet(paymentRequest, 'server-funding')\n\n// 3. Send tx to server\nawait fetch('/api/server-wallet?action=receive', {\n  method: 'POST',\n  headers: { 'Content-Type': 'application/json' },\n  body: JSON.stringify({\n    tx: Array.from(result.tx),\n    senderIdentityKey: wallet.getIdentityKey(),\n    derivationPrefix: paymentRequest.derivationPrefix,\n    derivationSuffix: paymentRequest.derivationSuffix,\n    outputIndex: 0\n  })\n})\n```\n\n## Pattern 9: DID Operations (V2 \u2014 UTXO Chain-Linked)\n```typescript\nimport { createWallet, DID } from '@bsv/simple/browser'\n\n// Initialize with proxy for cross-wallet resolution\nconst wallet = await createWallet({ didProxyUrl: '/api/resolve-did' })\n\n// Create a DID (on-chain, UTXO chain-linked)\nconst { did, document } = await wallet.createDID()\nconsole.log(did)  // 'did:bsv:<txid>'\n\n// Resolve any DID (own \u2192 local basket, others \u2192 proxy \u2192 WoC chain-following)\nconst result = await wallet.resolveDID('did:bsv:<txid>')\nif (result.didDocument) {\n  console.log('Subject key:', result.didDocument.verificationMethod[0].publicKeyJwk)\n}\nif (result.didDocumentMetadata?.deactivated) {\n  console.log('DID is deactivated')\n}\n\n// Update DID (adds services, extra keys)\nawait wallet.updateDID({\n  did,\n  services: [{ id: did + '#api', type: 'API', serviceEndpoint: 'https://...' }]\n})\n\n// List all wallet DIDs\nconst dids = await wallet.listDIDs()\ndids.forEach(d => console.log(d.did, d.status))  // 'active' or 'deactivated'\n\n// Deactivate\nawait wallet.deactivateDID(did)\n\n// Static utilities\nDID.isValid('did:bsv:<txid>')   // true (64-char txid)\nDID.isValid('did:bsv:02abc...') // true (66-char legacy pubkey)\n```\n\n## Pattern 10: Issue Verifiable Credentials\n```typescript\nimport { CredentialIssuer, CredentialSchema, MemoryRevocationStore } from '@bsv/simple/browser'\n\nconst schema = new CredentialSchema({\n  id: 'age-verification',\n  name: 'AgeVerification',\n  fields: [\n    { key: 'name', label: 'Name', type: 'text', required: true },\n    { key: 'over18', label: 'Over 18', type: 'checkbox', required: true }\n  ]\n})\n\nconst issuer = await CredentialIssuer.create({\n  privateKey: 'hex_key',\n  schemas: [schema.getConfig()],\n  revocation: { enabled: false }\n})\n\n// Issue\nconst vc = await issuer.issue(subjectKey, 'age-verification', { name: 'Alice', over18: 'true' })\n\n// List from wallet\nconst vcs = await wallet.listCredentials({\n  certifiers: [issuer.getInfo().publicKey],\n  types: [schema.getInfo().certificateTypeBase64]\n})\n\n// Create verifiable presentation\nconst vp = wallet.createPresentation(vcs)\n```\n\n## Pattern 11: Overlay Operations\n```typescript\nimport { Overlay } from '@bsv/simple/browser'\n\nconst overlay = await Overlay.create({ topics: ['tm_payments'], network: 'mainnet' })\n\n// Advertise\nawait wallet.advertiseSHIP('https://myserver.com', 'tm_payments')\nawait wallet.advertiseSLAP('https://myserver.com', 'ls_payments')\n\n// Broadcast action to overlay\nconst { txid, broadcast } = await wallet.broadcastAction(overlay, {\n  outputs: [{ lockingScript: '...', satoshis: 1, outputDescription: 'Overlay output' }]\n}, ['tm_payments'])\n\n// Query\nconst results = await overlay.lookupOutputs('ls_payments', { tag: 'recent' })\n```\n\n## Pattern 12: Server API Routes (Handler Factories)\nAll server routes use handler factories \u2014 no boilerplate, no `@bsv/sdk` import needed:\n```typescript\n// app/api/identity-registry/route.ts\nimport { createIdentityRegistryHandler } from '@bsv/simple/server'\nconst handler = createIdentityRegistryHandler()\nexport const GET = handler.GET, POST = handler.POST\n\n// app/api/resolve-did/route.ts\nimport { createDIDResolverHandler } from '@bsv/simple/server'\nconst handler = createDIDResolverHandler()\nexport const GET = handler.GET\n\n// app/api/server-wallet/route.ts\nimport { createServerWalletHandler } from '@bsv/simple/server'\nconst handler = createServerWalletHandler()\nexport const GET = handler.GET, POST = handler.POST\n\n// app/api/credential-issuer/route.ts  (no [[...path]] needed!)\nimport { createCredentialIssuerHandler } from '@bsv/simple/server'\nconst handler = createCredentialIssuerHandler({\n  schemas: [{\n    id: 'my-credential',\n    name: 'MyCredential',\n    fields: [\n      { key: 'name', label: 'Full Name', type: 'text', required: true },\n    ]\n  }]\n})\nexport const GET = handler.GET, POST = handler.POST\n```\n";

package/dist/resources/patterns.js

@@ -0,0 +1,266 @@
+"use strict";
+// Common code patterns
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.codePatterns = void 0;
+exports.codePatterns = `# @bsv/simple — Common Code Patterns
+
+## Pattern 1: Connect Wallet + Auto-check MessageBox
+\`\`\`typescript
+'use client'
+import { useState, useEffect } from 'react'
+import { createWallet, type BrowserWallet } from '@bsv/simple/browser'
+
+export default function Page() {
+  const [wallet, setWallet] = useState<BrowserWallet | null>(null)
+  const [handle, setHandle] = useState<string | null>(null)
+
+  const connect = async () => {
+    const w = await createWallet()
+    setWallet(w)
+    const h = await w.getMessageBoxHandle('/api/identity-registry')
+    setHandle(h)
+  }
+
+  return (
+    <div>
+      {!wallet ? (
+        <button onClick={connect}>Connect Wallet</button>
+      ) : (
+        <div>
+          <p>Connected: {wallet.getIdentityKey().substring(0, 20)}...</p>
+          {handle && <p>Handle: {handle}</p>}
+        </div>
+      )}
+    </div>
+  )
+}
+\`\`\`
+
+## Pattern 2: Simple Payment via MessageBox P2P
+\`\`\`typescript
+const result = await wallet.pay({
+  to: recipientKey,
+  satoshis: 1000
+})
+
+console.log('TXID:', result.txid)
+\`\`\`
+
+## Pattern 3: Multi-Output Send
+\`\`\`typescript
+const result = await wallet.send({
+  outputs: [
+    { to: recipientKey, satoshis: 1000, basket: 'payments' },
+    { data: ['Hello blockchain!'], basket: 'text' },
+    { to: wallet.getIdentityKey(), data: [{ value: 42 }], satoshis: 1, basket: 'tokens' }
+  ],
+  description: 'Multi-output transaction'
+})
+\`\`\`
+
+## Pattern 4: Token CRUD
+\`\`\`typescript
+// Create
+const token = await wallet.createToken({
+  data: { type: 'loyalty', points: 100 },
+  basket: 'my-tokens',
+  satoshis: 1
+})
+
+// List (decrypts automatically)
+const tokens = await wallet.listTokenDetails('my-tokens')
+
+// Send
+await wallet.sendToken({ basket: 'my-tokens', outpoint: tokens[0].outpoint, to: recipientKey })
+
+// Redeem
+await wallet.redeemToken({ basket: 'my-tokens', outpoint: tokens[0].outpoint })
+\`\`\`
+
+## Pattern 5: Token Transfer via MessageBox
+\`\`\`typescript
+// Sender
+await wallet.sendTokenViaMessageBox({ basket: 'my-tokens', outpoint: '...', to: recipientKey })
+
+// Recipient
+const incoming = await wallet.listIncomingTokens()
+for (const token of incoming) {
+  await wallet.acceptIncomingToken(token, 'received-tokens')
+}
+\`\`\`
+
+## Pattern 6: Inscriptions
+\`\`\`typescript
+const text = await wallet.inscribeText('Hello blockchain!')
+const json = await wallet.inscribeJSON({ title: 'Document', created: Date.now() })
+const hash = await wallet.inscribeFileHash('a'.repeat(64))
+\`\`\`
+
+## Pattern 7: MessageBox Payments
+\`\`\`typescript
+// Register identity
+await wallet.certifyForMessageBox('@alice', '/api/identity-registry')
+
+// Find recipient
+const results = await wallet.lookupIdentityByTag('bob', '/api/identity-registry')
+
+// Send payment
+await wallet.sendMessageBoxPayment(results[0].identityKey, 1000)
+
+// Receive payments
+const incoming = await wallet.listIncomingPayments()
+for (const payment of incoming) {
+  await wallet.acceptIncomingPayment(payment, 'received-payments')
+}
+\`\`\`
+
+## Pattern 8: Server Wallet Funding Flow
+\`\`\`typescript
+// Server side: 3-line handler (app/api/server-wallet/route.ts)
+// import { createServerWalletHandler } from '@bsv/simple/server'
+// const handler = createServerWalletHandler()
+// export const GET = handler.GET, POST = handler.POST
+
+// Client side:
+// 1. Get payment request from server
+const res = await fetch('/api/server-wallet?action=request')
+const { paymentRequest } = await res.json()
+
+// 2. Fund server wallet
+const result = await wallet.fundServerWallet(paymentRequest, 'server-funding')
+
+// 3. Send tx to server
+await fetch('/api/server-wallet?action=receive', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    tx: Array.from(result.tx),
+    senderIdentityKey: wallet.getIdentityKey(),
+    derivationPrefix: paymentRequest.derivationPrefix,
+    derivationSuffix: paymentRequest.derivationSuffix,
+    outputIndex: 0
+  })
+})
+\`\`\`
+
+## Pattern 9: DID Operations (V2 — UTXO Chain-Linked)
+\`\`\`typescript
+import { createWallet, DID } from '@bsv/simple/browser'
+
+// Initialize with proxy for cross-wallet resolution
+const wallet = await createWallet({ didProxyUrl: '/api/resolve-did' })
+
+// Create a DID (on-chain, UTXO chain-linked)
+const { did, document } = await wallet.createDID()
+console.log(did)  // 'did:bsv:<txid>'
+
+// Resolve any DID (own → local basket, others → proxy → WoC chain-following)
+const result = await wallet.resolveDID('did:bsv:<txid>')
+if (result.didDocument) {
+  console.log('Subject key:', result.didDocument.verificationMethod[0].publicKeyJwk)
+}
+if (result.didDocumentMetadata?.deactivated) {
+  console.log('DID is deactivated')
+}
+
+// Update DID (adds services, extra keys)
+await wallet.updateDID({
+  did,
+  services: [{ id: did + '#api', type: 'API', serviceEndpoint: 'https://...' }]
+})
+
+// List all wallet DIDs
+const dids = await wallet.listDIDs()
+dids.forEach(d => console.log(d.did, d.status))  // 'active' or 'deactivated'
+
+// Deactivate
+await wallet.deactivateDID(did)
+
+// Static utilities
+DID.isValid('did:bsv:<txid>')   // true (64-char txid)
+DID.isValid('did:bsv:02abc...') // true (66-char legacy pubkey)
+\`\`\`
+
+## Pattern 10: Issue Verifiable Credentials
+\`\`\`typescript
+import { CredentialIssuer, CredentialSchema, MemoryRevocationStore } from '@bsv/simple/browser'
+
+const schema = new CredentialSchema({
+  id: 'age-verification',
+  name: 'AgeVerification',
+  fields: [
+    { key: 'name', label: 'Name', type: 'text', required: true },
+    { key: 'over18', label: 'Over 18', type: 'checkbox', required: true }
+  ]
+})
+
+const issuer = await CredentialIssuer.create({
+  privateKey: 'hex_key',
+  schemas: [schema.getConfig()],
+  revocation: { enabled: false }
+})
+
+// Issue
+const vc = await issuer.issue(subjectKey, 'age-verification', { name: 'Alice', over18: 'true' })
+
+// List from wallet
+const vcs = await wallet.listCredentials({
+  certifiers: [issuer.getInfo().publicKey],
+  types: [schema.getInfo().certificateTypeBase64]
+})
+
+// Create verifiable presentation
+const vp = wallet.createPresentation(vcs)
+\`\`\`
+
+## Pattern 11: Overlay Operations
+\`\`\`typescript
+import { Overlay } from '@bsv/simple/browser'
+
+const overlay = await Overlay.create({ topics: ['tm_payments'], network: 'mainnet' })
+
+// Advertise
+await wallet.advertiseSHIP('https://myserver.com', 'tm_payments')
+await wallet.advertiseSLAP('https://myserver.com', 'ls_payments')
+
+// Broadcast action to overlay
+const { txid, broadcast } = await wallet.broadcastAction(overlay, {
+  outputs: [{ lockingScript: '...', satoshis: 1, outputDescription: 'Overlay output' }]
+}, ['tm_payments'])
+
+// Query
+const results = await overlay.lookupOutputs('ls_payments', { tag: 'recent' })
+\`\`\`
+
+## Pattern 12: Server API Routes (Handler Factories)
+All server routes use handler factories — no boilerplate, no \`@bsv/sdk\` import needed:
+\`\`\`typescript
+// app/api/identity-registry/route.ts
+import { createIdentityRegistryHandler } from '@bsv/simple/server'
+const handler = createIdentityRegistryHandler()
+export const GET = handler.GET, POST = handler.POST
+
+// app/api/resolve-did/route.ts
+import { createDIDResolverHandler } from '@bsv/simple/server'
+const handler = createDIDResolverHandler()
+export const GET = handler.GET
+
+// app/api/server-wallet/route.ts
+import { createServerWalletHandler } from '@bsv/simple/server'
+const handler = createServerWalletHandler()
+export const GET = handler.GET, POST = handler.POST
+
+// app/api/credential-issuer/route.ts  (no [[...path]] needed!)
+import { createCredentialIssuerHandler } from '@bsv/simple/server'
+const handler = createCredentialIssuerHandler({
+  schemas: [{
+    id: 'my-credential',
+    name: 'MyCredential',
+    fields: [
+      { key: 'name', label: 'Full Name', type: 'text', required: true },
+    ]
+  }]
+})
+export const GET = handler.GET, POST = handler.POST
+\`\`\`
+`;

package/dist/tools/credential.d.ts

@@ -0,0 +1,6 @@
+export declare function generateCredentialIssuer(schemaFields: Array<{
+    key: string;
+    label: string;
+    type: string;
+    required?: boolean;
+}>, revocation: boolean): string;