@bsv/simple-mcp 0.0.1

package/dist/resources/api-reference.js

@@ -0,0 +1,614 @@
+"use strict";
+// API Reference resources for @bsv/simple
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.overlayApiReference = exports.credentialsApiReference = exports.didApiReference = exports.certificationApiReference = exports.messageboxApiReference = exports.inscriptionsApiReference = exports.tokensApiReference = exports.walletApiReference = void 0;
+exports.walletApiReference = `# @bsv/simple — Wallet API Reference
+
+## Initialization
+
+### Browser
+\`\`\`typescript
+import { createWallet } from '@bsv/simple/browser'
+const wallet = await createWallet()
+// Optional defaults:
+const wallet = await createWallet({ network: 'main' })
+\`\`\`
+
+### Server (Node.js)
+\`\`\`typescript
+const { ServerWallet } = await import('@bsv/simple/server')
+const wallet = await ServerWallet.create({
+  privateKey: 'hex_private_key',
+  network: 'main',
+  storageUrl: 'https://storage.babbage.systems'
+})
+\`\`\`
+
+## WalletCore Methods (shared by Browser + Server)
+
+### Wallet Info
+- \`getIdentityKey(): string\` — Compressed public key hex (66 chars)
+- \`getAddress(): string\` — P2PKH address from identity key
+- \`getStatus(): WalletStatus\` — { isConnected, identityKey, network }
+- \`getWalletInfo(): WalletInfo\` — { identityKey, address, network, isConnected }
+- \`getClient(): WalletInterface\` — Underlying SDK wallet client
+
+### Key Derivation
+- \`derivePublicKey(protocolID: [SecurityLevel, string], keyID: string, counterparty?: string, forSelf?: boolean): Promise<string>\` — Derive public key for any protocol
+- \`derivePaymentKey(counterparty: string, invoiceNumber?: string): Promise<string>\` — Derive BRC-29 payment key (protocol [2, '3241645161d8'])
+
+### Payments
+- \`pay(options: PaymentOptions): Promise<TransactionResult>\` — Payment via MessageBox P2P (PeerPayClient)
+- \`send(options: SendOptions): Promise<SendResult>\` — Multi-output: combine P2PKH + OP_RETURN + PushDrop in one tx
+- \`fundServerWallet(request: PaymentRequest, basket?: string): Promise<TransactionResult>\` — Fund a ServerWallet using BRC-29 derivation
+
+### PaymentOptions
+\`\`\`typescript
+interface PaymentOptions {
+  to: string              // recipient identity key
+  satoshis: number        // amount
+  memo?: string           // optional memo
+  description?: string    // tx description
+}
+\`\`\`
+
+### SendOptions (multi-output)
+\`\`\`typescript
+interface SendOptions {
+  outputs: SendOutputSpec[]
+  description?: string
+}
+
+interface SendOutputSpec {
+  to?: string                              // recipient key
+  satoshis?: number                        // amount
+  data?: Array<string | object | number[]> // data fields
+  description?: string
+  basket?: string
+  protocolID?: [number, string]            // for PushDrop
+  keyID?: string                           // for PushDrop
+}
+// Rules: to only → P2PKH | data only → OP_RETURN | to + data → PushDrop
+\`\`\`
+
+## ServerWallet-specific Methods
+- \`createPaymentRequest(options: { satoshis: number, memo?: string }): PaymentRequest\` — Generate BRC-29 payment request
+- \`receivePayment(payment: IncomingPayment): Promise<void>\` — Internalize payment using wallet payment protocol
+
+## Result Types
+\`\`\`typescript
+interface TransactionResult { txid: string; tx: any; outputs?: OutputInfo[] }
+interface SendResult extends TransactionResult { outputDetails: SendOutputDetail[] }
+interface SendOutputDetail { index: number; type: 'p2pkh' | 'op_return' | 'pushdrop'; satoshis: number; description: string }
+\`\`\`
+`;
+exports.tokensApiReference = `# @bsv/simple — Tokens API Reference
+
+## Methods (mixed into wallet via createTokenMethods)
+
+### createToken(options: TokenOptions): Promise<TokenResult>
+Create an encrypted PushDrop token.
+\`\`\`typescript
+interface TokenOptions {
+  to?: string                     // recipient key (default: self)
+  data: any                       // JSON-serializable data (encrypted)
+  basket?: string                 // default: 'tokens'
+  protocolID?: [number, string]   // default: [0, 'token']
+  keyID?: string                  // default: '1'
+  satoshis?: number               // default: 1
+}
+interface TokenResult extends TransactionResult {
+  basket: string
+  encrypted: boolean
+}
+\`\`\`
+Example:
+\`\`\`typescript
+const result = await wallet.createToken({
+  data: { type: 'loyalty', points: 100 },
+  basket: 'my-tokens'
+})
+\`\`\`
+
+### listTokenDetails(basket?: string): Promise<TokenDetail[]>
+List and decrypt all tokens in a basket.
+\`\`\`typescript
+interface TokenDetail {
+  outpoint: string     // txid.vout
+  satoshis: number
+  data: any            // decrypted payload
+  protocolID: any
+  keyID: string
+  counterparty: string
+}
+\`\`\`
+
+### sendToken(options: SendTokenOptions): Promise<TransactionResult>
+Transfer a token to another key (on-chain, two-step sign flow).
+\`\`\`typescript
+interface SendTokenOptions { basket: string; outpoint: string; to: string }
+\`\`\`
+
+### redeemToken(options: RedeemTokenOptions): Promise<TransactionResult>
+Spend/destroy a token (reclaims satoshis).
+\`\`\`typescript
+interface RedeemTokenOptions { basket: string; outpoint: string }
+\`\`\`
+
+### sendTokenViaMessageBox(options: SendTokenOptions): Promise<TransactionResult>
+Transfer a token via MessageBox P2P messaging (off-chain delivery).
+
+### listIncomingTokens(): Promise<any[]>
+List tokens waiting in the \`simple_token_inbox\` MessageBox.
+
+### acceptIncomingToken(token: any, basket?: string): Promise<any>
+Accept incoming token into a basket via \`basket insertion\` protocol.
+`;
+exports.inscriptionsApiReference = `# @bsv/simple — Inscriptions API Reference
+
+All inscriptions create OP_RETURN outputs (0 satoshis).
+
+## Methods
+
+### inscribeText(text: string, opts?): Promise<InscriptionResult>
+Create an OP_RETURN text inscription.
+- Default basket: \`'text'\`
+
+### inscribeJSON(data: object, opts?): Promise<InscriptionResult>
+Create an OP_RETURN JSON inscription.
+- Default basket: \`'json'\`
+
+### inscribeFileHash(hash: string, opts?): Promise<InscriptionResult>
+Create an OP_RETURN SHA-256 file hash inscription.
+- Default basket: \`'hash-document'\`
+- Validates: must be 64-char hex string
+
+### inscribeImageHash(hash: string, opts?): Promise<InscriptionResult>
+Create an OP_RETURN SHA-256 image hash inscription.
+- Default basket: \`'hash-image'\`
+- Validates: must be 64-char hex string
+
+## Shared Options
+\`\`\`typescript
+opts?: { basket?: string; description?: string }
+\`\`\`
+
+## Result Type
+\`\`\`typescript
+interface InscriptionResult extends TransactionResult {
+  type: 'text' | 'json' | 'file-hash' | 'image-hash'
+  dataSize: number
+  basket: string
+}
+\`\`\`
+
+## Example
+\`\`\`typescript
+const text = await wallet.inscribeText('Hello blockchain!')
+const json = await wallet.inscribeJSON({ title: 'Doc', created: Date.now() })
+const hash = await wallet.inscribeFileHash('a'.repeat(64))
+\`\`\`
+`;
+exports.messageboxApiReference = `# @bsv/simple — MessageBox API Reference
+
+## Identity & Certification
+
+### certifyForMessageBox(handle: string, registryUrl?: string, host?: string): Promise<{ txid, handle }>
+Register a handle on the identity registry and anoint the MessageBox host.
+
+### getMessageBoxHandle(registryUrl?: string): Promise<string | null>
+Check if wallet has a registered handle. Returns null if none found.
+
+### revokeMessageBoxCertification(registryUrl?: string): Promise<void>
+Remove all registered handles for this identity key.
+
+## Payments
+
+### sendMessageBoxPayment(to: string, satoshis: number): Promise<any>
+Send payment via MessageBox using \`createPaymentToken()\` + \`sendMessage()\`.
+Returns: \`{ txid, amount, recipient }\`
+
+### listIncomingPayments(): Promise<any[]>
+List payments in the \`payment_inbox\` MessageBox.
+
+### acceptIncomingPayment(payment: any, basket?: string): Promise<any>
+Accept a payment. If \`basket\` is provided, uses \`basket insertion\` protocol (recommended). Otherwise uses \`PeerPayClient.acceptPayment()\`.
+
+**IMPORTANT:** When not using a basket, PeerPayClient.acceptPayment() swallows errors. The library checks \`typeof result === 'string'\` and throws.
+
+## Identity Registry
+
+### registerIdentityTag(tag: string, registryUrl?: string): Promise<{ tag }>
+Register a tag in the identity registry.
+
+### lookupIdentityByTag(query: string, registryUrl?: string): Promise<{ tag, identityKey }[]>
+Search the identity registry by tag.
+
+### listMyTags(registryUrl?: string): Promise<{ tag, createdAt }[]>
+List all tags registered to this identity key.
+
+### revokeIdentityTag(tag: string, registryUrl?: string): Promise<void>
+Remove a registered tag.
+
+## Registry API Format
+The identity registry expects these API endpoints:
+- \`GET ?action=lookup&query=...\` → \`{ success, results: [{ tag, identityKey }] }\`
+- \`GET ?action=list&identityKey=...\` → \`{ success, tags: [{ tag, createdAt }] }\`
+- \`POST ?action=register\` body: \`{ tag, identityKey }\` → \`{ success }\`
+- \`POST ?action=revoke\` body: \`{ tag, identityKey }\` → \`{ success }\`
+
+## Server-side Setup (3 lines)
+\`\`\`typescript
+// app/api/identity-registry/route.ts
+import { createIdentityRegistryHandler } from '@bsv/simple/server'
+const handler = createIdentityRegistryHandler()
+export const GET = handler.GET, POST = handler.POST
+\`\`\`
+`;
+exports.certificationApiReference = `# @bsv/simple — Certification API Reference
+
+## Certifier Class (standalone)
+
+### Certifier.create(config?): Promise<Certifier>
+\`\`\`typescript
+const certifier = await Certifier.create()  // random key
+const certifier = await Certifier.create({
+  privateKey: 'hex',
+  certificateType: 'base64type',
+  defaultFields: { role: 'admin' },
+  includeTimestamp: true  // default: true
+})
+\`\`\`
+
+### certifier.getInfo(): { publicKey, certificateType }
+
+### certifier.certify(wallet: WalletCore, additionalFields?): Promise<CertificateData>
+Issues a certificate AND acquires it into the wallet in one call.
+
+## Wallet Methods
+
+### acquireCertificateFrom(config): Promise<CertificateData>
+\`\`\`typescript
+await wallet.acquireCertificateFrom({
+  serverUrl: 'https://certifier.example.com',
+  replaceExisting: true  // revoke old certs first (default: true)
+})
+\`\`\`
+Server must expose: \`GET ?action=info\` → \`{ certifierPublicKey, certificateType }\`, \`POST ?action=certify\` → CertificateData. Use \`createCredentialIssuerHandler()\` from \`@bsv/simple/server\` to set this up automatically.
+
+### listCertificatesFrom(config): Promise<{ totalCertificates, certificates }>
+\`\`\`typescript
+const result = await wallet.listCertificatesFrom({
+  certifiers: [certifierPubKey],
+  types: [certificateType],
+  limit: 100
+})
+\`\`\`
+
+### relinquishCert(args): Promise<void>
+\`\`\`typescript
+await wallet.relinquishCert({ type, serialNumber, certifier })
+\`\`\`
+
+## CertificateData Type
+\`\`\`typescript
+interface CertificateData {
+  type: string; serialNumber: string; subject: string; certifier: string
+  revocationOutpoint: string; fields: Record<string, string>
+  signature: string; keyringForSubject: Record<string, string>
+}
+\`\`\`
+`;
+exports.didApiReference = `# @bsv/simple — DID API Reference
+
+## Overview
+
+\`did:bsv:\` DIDs use UTXO chain-linking on the BSV blockchain. The DID identifier
+is the txid of the issuance transaction. The chain of output-0 spends carries
+the DID Document and its updates.
+
+## DID Class (standalone, no wallet needed)
+
+### DID.buildDocument(txid, subjectPubKeyHex, controllerDID?, services?): DIDDocumentV2
+Build a W3C DID Document with JsonWebKey2020 verification method.
+
+### DID.fromTxid(txid: string): string
+Create a DID string from a transaction ID: \`did:bsv:<txid>\`
+
+### DID.parse(didString: string): DIDParseResult
+Parse \`did:bsv:<txid>\` → \`{ method: 'bsv', identifier: '<txid>' }\`
+Also accepts legacy 66-char pubkey identifiers.
+
+### DID.isValid(didString: string): boolean
+Check if a DID string is valid \`did:bsv:\` format (64-char txid or 66-char pubkey).
+
+### DID.fromIdentityKey(identityKey: string): DIDDocument
+**Deprecated.** Generate a legacy DID Document from a compressed public key.
+
+### DID.getCertificateType(): string
+Returns the base64 certificate type for DID persistence.
+
+## Wallet Methods (V2 — UTXO Chain-Linked)
+
+### createDID(options?: DIDCreateOptions): Promise<DIDCreateResult>
+Create a new on-chain DID with UTXO chain linking.
+- TX0: Issuance (chain UTXO + OP_RETURN marker)
+- TX1: Document (spends TX0, new chain UTXO + OP_RETURN with DID Document)
+\`\`\`typescript
+interface DIDCreateOptions {
+  basket?: string           // default: 'did_v2'
+  identityCode?: string     // auto-generated if omitted
+  services?: DIDService[]   // optional services in document
+}
+interface DIDCreateResult {
+  did: string               // 'did:bsv:<txid>'
+  txid: string              // issuance txid
+  identityCode: string
+  document: DIDDocumentV2
+}
+\`\`\`
+
+### resolveDID(didString: string): Promise<DIDResolutionResult>
+Resolve any \`did:bsv:\` DID to its Document.
+
+**Resolution order:**
+1. Local basket (own DIDs — fastest)
+2. Server-side proxy (\`didProxyUrl\` — handles nChain + WoC fallback)
+3. Direct resolvers (server-side only — no proxy needed)
+
+**Important:** In browsers, set \`didProxyUrl\` for cross-wallet resolution:
+\`\`\`typescript
+const wallet = await createWallet({ didProxyUrl: '/api/resolve-did' })
+\`\`\`
+\`\`\`typescript
+interface DIDResolutionResult {
+  didDocument: DIDDocumentV2 | null
+  didDocumentMetadata: { created?: string; updated?: string; deactivated?: boolean; versionId?: string }
+  didResolutionMetadata: { contentType?: string; error?: string; message?: string }
+}
+\`\`\`
+
+### updateDID(options: DIDUpdateOptions): Promise<DIDCreateResult>
+Update a DID document by spending the current chain UTXO.
+\`\`\`typescript
+interface DIDUpdateOptions {
+  did: string                       // DID to update
+  services?: DIDService[]           // new services
+  additionalKeys?: string[]         // extra verification keys (compressed pubkey hex)
+}
+\`\`\`
+
+### deactivateDID(didString: string): Promise<{ txid: string }>
+Revoke a DID. Spends the chain UTXO with payload \`"3"\` (revocation marker).
+Chain terminates — resolvers will return \`deactivated: true\`.
+
+### listDIDs(): Promise<DIDChainState[]>
+List all DIDs owned by this wallet.
+\`\`\`typescript
+interface DIDChainState {
+  did: string; identityCode: string; issuanceTxid: string
+  currentOutpoint: string; status: 'active' | 'deactivated'
+  created: string; updated: string
+}
+\`\`\`
+
+## Legacy Wallet Methods (deprecated)
+
+### getDID(): DIDDocument
+Get legacy identity-key-based DID Document (synchronous).
+
+### registerDID(options?: { persist?: boolean }): Promise<DIDDocument>
+Persist legacy DID as a BSV certificate.
+
+## DID Document Structure (V2)
+\`\`\`typescript
+interface DIDDocumentV2 {
+  '@context': string                    // 'https://www.w3.org/ns/did/v1'
+  id: string                            // 'did:bsv:<txid>'
+  controller?: string
+  verificationMethod: DIDVerificationMethodV2[]
+  authentication: string[]
+  service?: DIDService[]
+}
+interface DIDVerificationMethodV2 {
+  id: string                            // 'did:bsv:<txid>#subject-key'
+  type: 'JsonWebKey2020'
+  controller: string
+  publicKeyJwk: { kty: 'EC'; crv: 'secp256k1'; x: string; y: string }
+}
+interface DIDService {
+  id: string; type: string; serviceEndpoint: string
+}
+\`\`\`
+
+## Cross-Wallet Resolution (Proxy Setup)
+
+Browser-side resolution of other wallets' DIDs requires a server-side proxy
+because:
+- nChain Universal Resolver is unreliable (returns HTTP 500)
+- WhatsOnChain API calls from browsers are blocked by CORS and rate-limited
+
+The proxy (\`/api/resolve-did\`) makes all external calls server-side:
+1. Try nChain resolver (10s timeout)
+2. On failure → WoC chain-following: fetch TX → parse OP_RETURN → follow output 0 spend → return last document
+
+See the DID guide (\`docs/guides/did.md\`) for the complete proxy implementation.
+
+## Example
+\`\`\`typescript
+import { createWallet, DID } from '@bsv/simple/browser'
+
+const wallet = await createWallet({ didProxyUrl: '/api/resolve-did' })
+
+// Create
+const { did, document } = await wallet.createDID()
+console.log(did)  // 'did:bsv:d803b04a...'
+
+// Resolve (cross-wallet, goes through proxy)
+const result = await wallet.resolveDID('did:bsv:<other-txid>')
+console.log(result.didDocument)
+
+// Update
+await wallet.updateDID({ did, services: [{ id: did + '#api', type: 'API', serviceEndpoint: 'https://...' }] })
+
+// List
+const dids = await wallet.listDIDs()
+
+// Deactivate
+await wallet.deactivateDID(did)
+
+// Static utilities
+DID.isValid('did:bsv:d803b04a...')  // true
+DID.parse('did:bsv:d803b04a...')    // { method: 'bsv', identifier: 'd803b04a...' }
+\`\`\`
+`;
+exports.credentialsApiReference = `# @bsv/simple — Credentials API Reference
+
+## CredentialSchema
+
+### Constructor
+\`\`\`typescript
+const schema = new CredentialSchema({
+  id: 'my-schema',
+  name: 'My Credential',
+  description: 'Optional',
+  fields: [
+    { key: 'name', label: 'Full Name', type: 'text', required: true },
+    { key: 'email', label: 'Email', type: 'email' },
+    { key: 'role', label: 'Role', type: 'select', options: [{ value: 'admin', label: 'Admin' }] }
+  ],
+  validate: (values) => values.name.length < 2 ? 'Name too short' : null,
+  computedFields: (values) => ({ verified: 'true', timestamp: Date.now().toString() })
+})
+\`\`\`
+
+### Methods
+- \`validate(values: Record<string, string>): string | null\`
+- \`computeFields(values: Record<string, string>): Record<string, string>\`
+- \`getInfo(): { id, name, description?, certificateTypeBase64, fieldCount }\`
+- \`getConfig(): CredentialSchemaConfig\`
+
+## CredentialIssuer
+
+### CredentialIssuer.create(config): Promise<CredentialIssuer>
+\`\`\`typescript
+const issuer = await CredentialIssuer.create({
+  privateKey: 'hex_key',
+  schemas: [schemaConfig],
+  revocation: {
+    enabled: true,
+    wallet: walletInstance,                // for creating revocation UTXOs
+    store: new MemoryRevocationStore()     // or FileRevocationStore
+  }
+})
+\`\`\`
+
+### Methods
+- \`issue(subjectIdentityKey, schemaId, fields): Promise<VerifiableCredential>\`
+- \`verify(vc: VerifiableCredential): Promise<VerificationResult>\`
+- \`revoke(serialNumber: string): Promise<{ txid }>\`
+- \`isRevoked(serialNumber: string): Promise<boolean>\`
+- \`getInfo(): { publicKey, did, schemas: [{ id, name }] }\`
+
+## Revocation Stores
+
+### MemoryRevocationStore (browser/tests)
+\`\`\`typescript
+import { MemoryRevocationStore } from '@bsv/simple/browser'
+const store = new MemoryRevocationStore()
+\`\`\`
+
+### FileRevocationStore (server only)
+\`\`\`typescript
+import { FileRevocationStore } from '@bsv/simple/server'
+const store = new FileRevocationStore()           // default: .revocation-secrets.json
+const store = new FileRevocationStore('/custom/path.json')
+\`\`\`
+
+### RevocationStore Interface
+\`\`\`typescript
+interface RevocationStore {
+  save(serialNumber: string, record: RevocationRecord): Promise<void>
+  load(serialNumber: string): Promise<RevocationRecord | undefined>
+  delete(serialNumber: string): Promise<void>
+  has(serialNumber: string): Promise<boolean>
+  findByOutpoint(outpoint: string): Promise<boolean>
+}
+\`\`\`
+
+## W3C VC/VP Utilities
+\`\`\`typescript
+import { toVerifiableCredential, toVerifiablePresentation } from '@bsv/simple/browser'
+
+const vc = toVerifiableCredential(certData, issuerPublicKey, { credentialType: 'MyType' })
+const vp = toVerifiablePresentation([vc1, vc2], holderKey)
+\`\`\`
+
+## Wallet Methods
+- \`acquireCredential(config): Promise<VerifiableCredential>\` — Acquire VC from remote issuer (uses \`?action=info\` and \`?action=certify\` query params)
+- \`listCredentials(config): Promise<VerifiableCredential[]>\` — List certs as W3C VCs
+- \`createPresentation(credentials): VerifiablePresentation\` — Wrap VCs into a VP
+
+## Server-Side Handler
+
+\`\`\`typescript
+// app/api/credential-issuer/route.ts  (no [[...path]] catch-all needed!)
+import { createCredentialIssuerHandler } from '@bsv/simple/server'
+const handler = createCredentialIssuerHandler({
+  schemas: [{ id: 'my-cred', name: 'MyCred', fields: [{ key: 'name', label: 'Name', type: 'text', required: true }] }]
+})
+export const GET = handler.GET, POST = handler.POST
+\`\`\`
+`;
+exports.overlayApiReference = `# @bsv/simple — Overlay API Reference
+
+## Overlay Class (standalone)
+
+### Overlay.create(config): Promise<Overlay>
+\`\`\`typescript
+const overlay = await Overlay.create({
+  topics: ['tm_my_topic'],              // MUST start with 'tm_'
+  network: 'mainnet',                   // 'mainnet' | 'testnet' | 'local'
+  slapTrackers: ['https://...'],        // optional
+  hostOverrides: { tm_topic: ['url'] }, // optional
+  additionalHosts: { tm_topic: ['url'] } // optional
+})
+\`\`\`
+
+### Instance Methods
+- \`getInfo(): OverlayInfo\` — { topics, network }
+- \`addTopic(topic: string): void\` — Add topic (must start with 'tm_')
+- \`removeTopic(topic: string): void\` — Remove topic
+- \`broadcast(tx: Transaction, topics?: string[]): Promise<OverlayBroadcastResult>\`
+- \`query(service: string, query: unknown, timeout?: number): Promise<LookupAnswer>\`
+- \`lookupOutputs(service: string, query: unknown): Promise<OverlayOutput[]>\`
+- \`getBroadcaster(): TopicBroadcaster\` — Raw SDK broadcaster
+- \`getResolver(): LookupResolver\` — Raw SDK resolver
+
+## Wallet Methods (overlay module)
+
+### advertiseSHIP(domain, topic, basket?): Promise<TransactionResult>
+Create a SHIP advertisement token. Topic must start with 'tm_'.
+
+### advertiseSLAP(domain, service, basket?): Promise<TransactionResult>
+Create a SLAP advertisement token. Service must start with 'ls_'.
+
+### broadcastAction(overlay, actionOptions, topics?): Promise<{ txid, broadcast }>
+Create an action and broadcast to overlay in one step.
+
+### withRetry<T>(operation, overlay, maxRetries?): Promise<T>
+Double-spend retry wrapper using \`withDoubleSpendRetry\`.
+
+## Types
+\`\`\`typescript
+interface OverlayConfig {
+  topics: string[]
+  network?: 'mainnet' | 'testnet' | 'local'
+  slapTrackers?: string[]
+  hostOverrides?: Record<string, string[]>
+  additionalHosts?: Record<string, string[]>
+}
+interface OverlayBroadcastResult { success: boolean; txid?: string; code?: string; description?: string }
+interface OverlayOutput { beef: number[]; outputIndex: number; context?: number[] }
+\`\`\`
+`;

package/dist/resources/gotchas.d.ts

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