@toon-protocol/sdk 0.1.4

package/README.md

@@ -0,0 +1,115 @@
+# @toon-protocol/sdk
+
+The building blocks for creating services that participate in the TOON network.
+
+## What It Does
+
+The SDK provides a framework for processing ILP-paid Nostr events. You register handlers for specific event kinds, and the SDK handles everything else: identity derivation, Schnorr signature verification, payment validation, and handler dispatch.
+
+```
+Incoming ILP packet
+  → Size check (1MB max)
+    → TOON parse (extract metadata)
+      → Signature verification (Schnorr)
+        → Payment validation (per-byte pricing)
+          → Your handler (business logic)
+```
+
+## Install
+
+```bash
+npm install @toon-protocol/sdk
+```
+
+## Quick Example
+
+```typescript
+import { createNode, fromMnemonic } from '@toon-protocol/sdk';
+import { ConnectorNode } from '@toon-protocol/connector';
+
+// 1. Create an identity
+const identity = fromMnemonic('your twelve word mnemonic phrase here');
+
+// 2. Create an embedded ILP connector
+const connector = new ConnectorNode({
+  nodeId: 'my-node',
+  btpServerPort: 3000,
+  environment: 'development',
+  deploymentMode: 'embedded',
+  peers: [],
+  routes: [],
+});
+
+// 3. Create a node with the connector
+const node = createNode({
+  secretKey: identity.secretKey,
+  connector,
+  basePricePerByte: 10n,
+});
+
+// 4. Register handlers for specific event kinds
+node.on(1, async (ctx) => {
+  const event = ctx.decode();
+  console.log(`Received kind:${ctx.kind} from ${ctx.pubkey}`);
+  console.log(`Paid: ${ctx.amount} units`);
+  return ctx.accept({ eventId: event.id });
+});
+
+// 5. Start the node
+const result = await node.start();
+console.log(`Connected to ${result.peerCount} peers`);
+```
+
+> **Easier path:** If you just want to run a relay, use [`@toon-protocol/town`](../town) — it manages the connector externally so you don't need to embed one. The SDK is for building custom services where you control the full pipeline.
+
+## Where It Sits
+
+```
+┌─────────────────────────┐
+│  Your Application       │  ← You write this
+├─────────────────────────┤
+│  @toon-protocol/sdk         │  ← Identity, verification, pricing, handlers
+├─────────────────────────┤
+│  @toon-protocol/core        │  ← Bootstrap, discovery, peering
+├─────────────────────────┤
+│  ILP Connector          │  ← Payment routing
+└─────────────────────────┘
+```
+
+The SDK is the framework layer. You bring handlers; it handles the protocol.
+
+## API Overview
+
+| Export | Purpose |
+|--------|---------|
+| `createNode(config)` | Compose a full service node |
+| `fromMnemonic(phrase)` | Derive identity from BIP-39 mnemonic |
+| `fromSecretKey(key)` | Derive identity from raw secret key |
+| `generateMnemonic()` | Generate a new 12-word mnemonic |
+| `HandlerRegistry` | Kind-based handler routing |
+| `createHandlerContext()` | Build handler context objects |
+| `createVerificationPipeline()` | Schnorr signature verifier |
+| `createPricingValidator()` | Payment amount validator |
+
+## Key Concepts
+
+| Concept | Description |
+|---------|-------------|
+| **Unified identity** | One secp256k1 key produces both a Nostr pubkey and an EVM address |
+| **Handler pattern** | `ctx.accept()` / `ctx.reject()` — handlers respond, not return |
+| **Self-write bypass** | Events from your own pubkey skip pricing |
+| **Dev mode** | Skip verification and pricing for testing |
+| **TOON encoding** | Events encoded in compact text format, not JSON |
+
+## Full Documentation
+
+See the [SDK Guide](../../docs/sdk-guide.md) for the complete API reference, handler patterns, verification pipeline details, publishing events, and error handling.
+
+## Requirements
+
+- Node.js >= 20
+- `@toon-protocol/connector` >= 1.6.0 (peer dependency, optional)
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,557 @@
+import { ToonError, HandlePacketAcceptResponse, HandlePacketRejectResponse, SkillDescriptor, EmbeddableConnectorLike, KnownPeer, SettlementConfig, ConnectorChannelClient, BootstrapEventListener, BootstrapResult, DvmJobStatus, IlpSendResult } from '@toon-protocol/core';
+export { BootstrapEvent, BootstrapEventListener, HandlePacketAcceptResponse, HandlePacketRejectResponse, SkillDescriptor } from '@toon-protocol/core';
+import { NostrEvent } from 'nostr-tools/pure';
+import { ToonRoutingMeta } from '@toon-protocol/core/toon';
+
+/**
+ * Unified identity module for @toon-protocol/sdk.
+ *
+ * Derives both a Nostr pubkey (x-only Schnorr, BIP-340) and an EVM address
+ * (Keccak-256) from a single secp256k1 private key, following the NIP-06
+ * derivation standard.
+ *
+ * Both Nostr and EVM use the secp256k1 elliptic curve, so a single 12-word
+ * seed phrase can recover the complete identity across both layers.
+ */
+/**
+ * Represents a node's complete identity: secret key, Nostr pubkey, and EVM address.
+ */
+interface NodeIdentity {
+    /** The 32-byte secp256k1 secret key. */
+    secretKey: Uint8Array;
+    /** The x-only Schnorr public key (32 bytes, 64 lowercase hex characters). */
+    pubkey: string;
+    /** The EIP-55 checksummed EVM address (0x-prefixed, 42 characters). */
+    evmAddress: string;
+}
+/**
+ * Options for mnemonic-based key derivation.
+ */
+interface FromMnemonicOptions {
+    /** Key index in the NIP-06 derivation path. Defaults to 0. */
+    accountIndex?: number;
+}
+/**
+ * Generates a valid 12-word BIP-39 mnemonic using 128-bit entropy.
+ *
+ * @returns A space-separated string of 12 BIP-39 English words.
+ */
+declare function generateMnemonic(): string;
+/**
+ * Derives a complete NodeIdentity from a BIP-39 mnemonic phrase.
+ *
+ * Uses the NIP-06 derivation path: m/44'/1237'/0'/0/{accountIndex}
+ *
+ * @param mnemonic - A valid BIP-39 mnemonic (12 or 24 words).
+ * @param options - Optional derivation options (accountIndex defaults to 0).
+ * @returns The derived NodeIdentity with secretKey, pubkey, and evmAddress.
+ * @throws {IdentityError} If the mnemonic is invalid.
+ */
+declare function fromMnemonic(mnemonic: string, options?: FromMnemonicOptions): NodeIdentity;
+/**
+ * Derives a complete NodeIdentity from an existing 32-byte secret key.
+ *
+ * @param secretKey - A 32-byte secp256k1 secret key.
+ * @returns The derived NodeIdentity with secretKey, pubkey, and evmAddress.
+ * @throws {IdentityError} If the secret key is not exactly 32 bytes.
+ */
+declare function fromSecretKey(secretKey: Uint8Array): NodeIdentity;
+
+/**
+ * SDK-specific error classes for @toon-protocol/sdk.
+ * All errors extend ToonError from @toon-protocol/core for a consistent error hierarchy.
+ */
+
+/**
+ * Error thrown when identity operations fail.
+ * Used for invalid mnemonics, invalid secret keys, and key derivation failures.
+ */
+declare class IdentityError extends ToonError {
+    constructor(message: string, cause?: Error);
+}
+/**
+ * Error thrown when node lifecycle operations fail.
+ * Used for start/stop failures, configuration errors, etc.
+ */
+declare class NodeError extends ToonError {
+    constructor(message: string, cause?: Error);
+}
+/**
+ * Error thrown when handler dispatch operations fail.
+ * Used for handler registration conflicts, missing handlers, and dispatch errors.
+ */
+declare class HandlerError extends ToonError {
+    constructor(message: string, cause?: Error);
+}
+/**
+ * Error thrown when Schnorr signature verification fails.
+ * Used for invalid signatures, malformed events, and verification pipeline errors.
+ */
+declare class VerificationError extends ToonError {
+    constructor(message: string, cause?: Error);
+}
+/**
+ * Error thrown when payment validation fails.
+ * Used for pricing calculation errors, insufficient payment, and pricing policy violations.
+ */
+declare class PricingError extends ToonError {
+    constructor(message: string, cause?: Error);
+}
+
+/**
+ * Handler context for @toon-protocol/sdk.
+ *
+ * Provides a context object passed to kind-based handlers with methods
+ * for accessing TOON data, shallow-parsed metadata, and accept/reject actions.
+ */
+
+/**
+ * The handler context passed to each kind-based handler.
+ */
+interface HandlerContext {
+    /** Raw TOON string (base64-encoded). */
+    readonly toon: string;
+    /** Event kind from shallow parse. */
+    readonly kind: number;
+    /** Event pubkey from shallow parse. */
+    readonly pubkey: string;
+    /** Payment amount in the ILP packet. */
+    readonly amount: bigint;
+    /** ILP destination address. */
+    readonly destination: string;
+    /** Lazy-decode the TOON payload into a full NostrEvent. */
+    decode(): NostrEvent;
+    /** Accept the packet with optional metadata. */
+    accept(metadata?: Record<string, unknown>): HandlePacketAcceptResponse;
+    /** Reject the packet with an ILP error code and message. */
+    reject(code: string, message: string): HandlePacketRejectResponse;
+}
+interface CreateHandlerContextOptions {
+    toon: string;
+    meta: ToonRoutingMeta;
+    amount: bigint;
+    destination: string;
+    toonDecoder: (toon: string) => NostrEvent;
+}
+/**
+ * Creates a HandlerContext from the given options.
+ */
+declare function createHandlerContext(options: CreateHandlerContextOptions): HandlerContext;
+
+/**
+ * Handler registry for @toon-protocol/sdk.
+ *
+ * Maps event kinds to handler functions for dispatching incoming ILP packets.
+ */
+
+type HandlerResponse = HandlePacketAcceptResponse | HandlePacketRejectResponse;
+type Handler = (ctx: HandlerContext) => Promise<HandlerResponse>;
+/**
+ * Registry that maps Nostr event kinds to handler functions.
+ */
+declare class HandlerRegistry {
+    private handlers;
+    private defaultHandler;
+    /**
+     * Register a handler for a specific event kind.
+     * Replaces any existing handler for that kind.
+     */
+    on(kind: number, handler: Handler): this;
+    /**
+     * Register a default handler for unrecognized kinds.
+     */
+    onDefault(handler: Handler): this;
+    /**
+     * Returns all registered kind numbers, sorted ascending.
+     */
+    getRegisteredKinds(): number[];
+    /**
+     * Returns registered kinds in the DVM request range (5000-5999), sorted ascending.
+     * Uses JOB_REQUEST_KIND_BASE (5000) as the range start.
+     */
+    getDvmKinds(): number[];
+    /**
+     * Dispatch a context to the appropriate handler based on kind.
+     */
+    dispatch(ctx: HandlerContext): Promise<HandlerResponse>;
+}
+
+/**
+ * Pricing validator for @toon-protocol/sdk.
+ *
+ * Validates that incoming ILP payments meet the required price based on
+ * TOON payload size and configured price per byte.
+ */
+
+interface PricingValidatorConfig {
+    basePricePerByte?: bigint;
+    ownPubkey: string;
+    kindPricing?: Record<number, bigint>;
+}
+interface PricingValidationResult {
+    accepted: boolean;
+    rejection?: {
+        accept: false;
+        code: string;
+        message: string;
+        metadata?: Record<string, string>;
+    };
+}
+/**
+ * Creates a pricing validator that checks payment amounts against TOON size.
+ */
+declare function createPricingValidator(config: PricingValidatorConfig): {
+    validate(meta: ToonRoutingMeta, amount: bigint): PricingValidationResult;
+};
+
+/**
+ * Verification pipeline for @toon-protocol/sdk.
+ *
+ * Verifies Schnorr signatures on incoming TOON payloads before dispatching
+ * to handlers. In dev mode, verification is skipped.
+ */
+
+interface VerificationResult {
+    verified: boolean;
+    rejection?: {
+        accept: false;
+        code: string;
+        message: string;
+    };
+}
+interface VerificationPipelineConfig {
+    devMode: boolean;
+}
+/**
+ * Creates a verification pipeline that checks Schnorr signatures.
+ */
+declare function createVerificationPipeline(config: VerificationPipelineConfig): {
+    verify(meta: ToonRoutingMeta, _toonData: string): Promise<VerificationResult>;
+};
+
+/**
+ * Payment handler bridge for @toon-protocol/sdk.
+ *
+ * Bridges between ILP packet handling and the handler registry,
+ * using isTransit to distinguish fire-and-forget from await semantics.
+ */
+
+interface PaymentHandlerBridgeConfig {
+    registry: HandlerRegistry;
+    devMode: boolean;
+    ownPubkey: string;
+    basePricePerByte: bigint;
+}
+interface PaymentRequest {
+    paymentId: string;
+    destination: string;
+    amount: string;
+    data: string;
+    isTransit: boolean;
+}
+interface PaymentResponse {
+    accept: boolean;
+    fulfillment?: string;
+    code?: string;
+    message?: string;
+    data?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Creates a payment handler bridge that connects ILP packets to the handler registry.
+ */
+declare function createPaymentHandlerBridge(config: PaymentHandlerBridgeConfig): {
+    handlePayment(request: PaymentRequest): Promise<PaymentResponse>;
+};
+
+/**
+ * Event storage handler stub for @toon-protocol/sdk.
+ *
+ * This is a stub that throws. The real implementation lives in
+ * `@toon-protocol/town` -- see `createEventStorageHandler` from that package.
+ *
+ * The SDK is the framework; Town is the relay implementation. SDK consumers
+ * building relay functionality should use `@toon-protocol/town` directly.
+ */
+/**
+ * Creates an event storage handler.
+ *
+ * **Stub** -- throws "not yet implemented". See `@toon-protocol/town` for the
+ * real relay implementation of this handler.
+ *
+ * @see {@link https://github.com/ALLiDoizCode/toon/tree/main/packages/town | @toon-protocol/town}
+ */
+declare function createEventStorageHandler(_config: unknown): unknown;
+
+/**
+ * Skill descriptor builder for DVM service discovery.
+ *
+ * Computes a SkillDescriptor from the handler registry and node configuration.
+ * The descriptor is embedded in kind:10035 events to advertise DVM capabilities.
+ *
+ * Returns `undefined` when no DVM handlers are registered (backward compatible
+ * with pre-DVM kind:10035 events).
+ */
+
+/** Configuration for building a skill descriptor. */
+interface BuildSkillDescriptorConfig {
+    /** Base price per byte in USDC micro-units (default: 10n). */
+    basePricePerByte?: bigint;
+    /** Per-kind pricing overrides (kind number -> price in USDC micro-units). */
+    kindPricing?: Record<number, bigint>;
+    /** Service name override (default: 'toon-dvm'). */
+    name?: string;
+    /** Schema version override (default: '1.0'). */
+    version?: string;
+    /** Feature list override. */
+    features?: string[];
+    /** JSON Schema draft-07 object for job request parameters. */
+    inputSchema?: Record<string, unknown>;
+    /** Available AI models. */
+    models?: string[];
+}
+/**
+ * Builds a SkillDescriptor from the handler registry and configuration.
+ *
+ * Returns `undefined` when the registry has no DVM handlers (kinds 5000-5999).
+ * When DVM kinds exist, auto-populates the descriptor:
+ * - `kinds` from `registry.getDvmKinds()`
+ * - `pricing` from `config.kindPricing` overrides or `config.basePricePerByte` fallback
+ * - `name`, `version`, `features`, `inputSchema`, `models` from config or defaults
+ *
+ * @param registry - The handler registry to read DVM kinds from.
+ * @param config - Node configuration for pricing and optional overrides.
+ * @returns A SkillDescriptor, or undefined if no DVM handlers are registered.
+ */
+declare function buildSkillDescriptor(registry: HandlerRegistry, config?: BuildSkillDescriptorConfig): SkillDescriptor | undefined;
+
+/**
+ * createNode() composition for @toon-protocol/sdk.
+ *
+ * Wires the full ILP packet processing pipeline:
+ *   shallow TOON parse -> Schnorr signature verification -> pricing validation -> handler dispatch
+ *
+ * Provides start() / stop() lifecycle management by delegating to
+ * the core ToonNode composition (embedded mode) or manual HTTP
+ * composition (standalone mode).
+ *
+ * ## Deployment Modes
+ *
+ * - **Embedded** (`connector`): Pass an EmbeddableConnectorLike directly.
+ *   Zero-latency packet delivery via direct function calls.
+ * - **Standalone** (`connectorUrl` + `handlerPort`): Connect to an external
+ *   connector via HTTP. The SDK starts an HTTP server to receive packets.
+ */
+
+/**
+ * Configuration for creating a ServiceNode via createNode().
+ *
+ * Supports two deployment modes:
+ * - **Embedded** (`connector`): Pass an EmbeddableConnectorLike directly for
+ *   zero-latency packet delivery.
+ * - **Standalone** (`connectorUrl` + `handlerPort`): Connect to an external
+ *   connector via HTTP. The SDK starts an HTTP server to receive packets.
+ *
+ * Provide `connector` OR (`connectorUrl` + `handlerPort`), not both.
+ */
+interface NodeConfig {
+    /** 32-byte secp256k1 secret key */
+    secretKey: Uint8Array;
+    /** Chain preset name (default: 'anvil'). See resolveChainConfig(). */
+    chain?: string;
+    /** Embedded connector instance for zero-latency mode. */
+    connector?: EmbeddableConnectorLike;
+    /**
+     * External connector admin URL for standalone mode (e.g., "http://localhost:8081").
+     * Must be provided with `handlerPort`.
+     */
+    connectorUrl?: string;
+    /**
+     * Port for the HTTP server that receives ILP packets from the external connector.
+     * Must be provided with `connectorUrl`.
+     */
+    handlerPort?: number;
+    /** ILP address (default: 'g.toon.local') */
+    ilpAddress?: string;
+    /** BTP endpoint URL advertised in kind:10032 announcements */
+    btpEndpoint?: string;
+    /** Asset code (default: 'USD') */
+    assetCode?: string;
+    /** Asset scale (default: 6) */
+    assetScale?: number;
+    /**
+     * Base price per byte for pricing validation (default: 10n).
+     *
+     * Amounts are in USDC micro-units (6 decimals) for production.
+     * Default 10n = 10 micro-USDC per byte = $0.00001/byte.
+     * A 1KB event costs 10,240 micro-USDC = ~$0.01.
+     */
+    basePricePerByte?: bigint;
+    /** Dev mode skips signature verification (default: false) */
+    devMode?: boolean;
+    /** TOON encoder function */
+    toonEncoder?: (event: NostrEvent) => Uint8Array;
+    /** TOON decoder function */
+    toonDecoder?: (bytes: Uint8Array) => NostrEvent;
+    /** Initial known peers for bootstrap */
+    knownPeers?: KnownPeer[];
+    /** Relay WebSocket URL */
+    relayUrl?: string;
+    /** Settlement info for peer registration */
+    settlementInfo?: SettlementConfig;
+    /** Enable ArDrive peer lookup */
+    ardriveEnabled?: boolean;
+    /** Per-kind pricing overrides */
+    kindPricing?: Record<number, bigint>;
+    /** Config-based handler registration (alternative to post-creation .on()) */
+    handlers?: Record<number, Handler>;
+    /** Config-based default handler (alternative to post-creation .onDefault()) */
+    defaultHandler?: Handler;
+    /**
+     * Optional skill descriptor configuration overrides.
+     * When DVM handlers are registered, these values override the auto-derived
+     * defaults in the skill descriptor. See buildSkillDescriptor().
+     */
+    skillConfig?: Omit<BuildSkillDescriptorConfig, 'basePricePerByte' | 'kindPricing'>;
+}
+/**
+ * Result returned by ServiceNode.start().
+ */
+interface StartResult {
+    /** Number of peers successfully bootstrapped */
+    peerCount: number;
+    /** Number of payment channels opened */
+    channelCount: number;
+    /** Detailed results from the bootstrap phase */
+    bootstrapResults: BootstrapResult[];
+}
+/**
+ * Result returned by ServiceNode.publishEvent().
+ */
+interface PublishEventResult {
+    success: boolean;
+    eventId: string;
+    fulfillment?: string;
+    code?: string;
+    message?: string;
+}
+/**
+ * A fully wired TOON node with lifecycle management.
+ */
+interface ServiceNode {
+    /** Nostr x-only public key (32 bytes, 64 hex chars) */
+    readonly pubkey: string;
+    /** EVM address derived from the same secp256k1 key */
+    readonly evmAddress: string;
+    /** Pass-through to the underlying connector (null in standalone mode) */
+    readonly connector: EmbeddableConnectorLike | null;
+    /** Channel client (null if connector lacks channel support or in standalone mode) */
+    readonly channelClient: ConnectorChannelClient | null;
+    /** Register a handler for a specific event kind (builder pattern) */
+    on(kind: number, handler: Handler): ServiceNode;
+    /** Register a lifecycle event listener */
+    on(event: 'bootstrap', listener: BootstrapEventListener): ServiceNode;
+    /** Register a default handler for unrecognized kinds (builder pattern) */
+    onDefault(handler: Handler): ServiceNode;
+    /** Start the node: wire packet handler, run bootstrap, start discovery */
+    start(): Promise<StartResult>;
+    /** Stop the node: clean up lifecycle state */
+    stop(): Promise<void>;
+    /** Initiate peering with a discovered peer (register + settlement) */
+    peerWith(pubkey: string): Promise<void>;
+    /**
+     * Publish a Nostr event to a remote peer via the embedded connector.
+     *
+     * TOON-encodes the event, computes payment amount, and sends as an
+     * ILP PREPARE packet via the runtime client.
+     *
+     * @param event - The Nostr event to publish
+     * @param options - Must include destination ILP address
+     * @returns Result with success/failure info and event ID
+     */
+    publishEvent(event: NostrEvent, options?: {
+        destination: string;
+    }): Promise<PublishEventResult>;
+    /**
+     * Publish a Kind 7000 DVM job feedback event via ILP PREPARE.
+     *
+     * Builds a signed Kind 7000 feedback event with NIP-90 tags (e, p, status)
+     * and delegates to publishEvent() for TOON encoding and ILP delivery.
+     * Standard relay write fee applies: basePricePerByte * toonData.length.
+     *
+     * @param requestEventId - 64-char hex event ID of the original Kind 5xxx request
+     * @param customerPubkey - 64-char hex pubkey of the customer who posted the request
+     * @param status - Job status value ('processing', 'error', 'success', 'partial')
+     * @param content - Optional status details or error message
+     * @param options - Must include destination ILP address
+     * @returns Result with success/failure info and event ID
+     */
+    publishFeedback(requestEventId: string, customerPubkey: string, status: DvmJobStatus, content?: string, options?: {
+        destination: string;
+    }): Promise<PublishEventResult>;
+    /**
+     * Publish a Kind 6xxx DVM job result event via ILP PREPARE.
+     *
+     * Builds a signed Kind 6xxx result event with NIP-90 tags (e, p, amount)
+     * and delegates to publishEvent() for TOON encoding and ILP delivery.
+     * Standard relay write fee applies: basePricePerByte * toonData.length.
+     *
+     * @param requestEventId - 64-char hex event ID of the original Kind 5xxx request
+     * @param customerPubkey - 64-char hex pubkey of the customer who posted the request
+     * @param amount - Compute cost in USDC micro-units as string
+     * @param content - Result data (text, URL, etc.)
+     * @param options - Must include destination; optional kind (default: 6100)
+     * @returns Result with success/failure info and event ID
+     */
+    publishResult(requestEventId: string, customerPubkey: string, amount: string, content: string, options?: {
+        destination: string;
+        kind?: number;
+    }): Promise<PublishEventResult>;
+    /**
+     * Returns the computed skill descriptor for this node's DVM capabilities.
+     * Returns `undefined` if no DVM handlers (kinds 5000-5999) are registered.
+     * The descriptor is computed from the handler registry and node config.
+     */
+    getSkillDescriptor(): SkillDescriptor | undefined;
+    /**
+     * Send an ILP payment to a provider for compute settlement.
+     *
+     * Extracts the compute cost from the result event's `amount` tag via
+     * parseJobResult(), optionally validates against the original bid amount
+     * (E5-R005 bid validation), and sends a pure ILP value transfer
+     * (empty data field) to the provider's ILP address.
+     *
+     * This is a payment-only operation -- no TOON encoding, no relay write.
+     * The payment routes through the ILP mesh using the same infrastructure
+     * as relay write fees.
+     *
+     * @param resultEvent - Kind 6xxx result event with amount tag
+     * @param providerIlpAddress - Provider's ILP address from kind:10035
+     * @param options - Optional originalBid for bid validation (E5-R005)
+     * @returns ILP send result with accepted/rejected status
+     */
+    settleCompute(resultEvent: NostrEvent, providerIlpAddress: string, options?: {
+        originalBid?: string;
+    }): Promise<IlpSendResult>;
+}
+/**
+ * Creates a fully wired ServiceNode from configuration.
+ *
+ * The returned node has the full ILP packet processing pipeline wired in the
+ * correct order:
+ *   1. Shallow TOON parse (extract routing metadata)
+ *   2. Schnorr signature verification (reject with F06 if invalid)
+ *   3. Pricing validation (reject with F04 if underpaid)
+ *   4. Handler dispatch (route to kind-specific or default handler)
+ *
+ * Supports two deployment modes:
+ * - **Embedded** (`connector`): Uses createToonNode for zero-latency
+ *   packet delivery via direct function calls.
+ * - **Standalone** (`connectorUrl` + `handlerPort`): Starts an HTTP server
+ *   to receive packets and uses HTTP clients for the connector API.
+ *
+ * Handlers can be registered via config or post-creation .on()/.onDefault().
+ */
+declare function createNode(config: NodeConfig): ServiceNode;
+
+export { type BuildSkillDescriptorConfig, type CreateHandlerContextOptions, type FromMnemonicOptions, type Handler, type HandlerContext, HandlerError, HandlerRegistry, type HandlerResponse, IdentityError, type NodeConfig, NodeError, type NodeIdentity, type PaymentHandlerBridgeConfig, type PaymentRequest, type PaymentResponse, PricingError, type PricingValidationResult, type PricingValidatorConfig, type PublishEventResult, type ServiceNode, type StartResult, VerificationError, type VerificationPipelineConfig, type VerificationResult, buildSkillDescriptor, createEventStorageHandler, createHandlerContext, createNode, createPaymentHandlerBridge, createPricingValidator, createVerificationPipeline, fromMnemonic, fromSecretKey, generateMnemonic };