@toon-protocol/sdk 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ToonError, HandlePacketAcceptResponse, HandlePacketRejectResponse, SkillDescriptor, EmbeddableConnectorLike, KnownPeer, SettlementConfig, ConnectorChannelClient, BootstrapEventListener, BootstrapResult, DvmJobStatus, IlpSendResult } from '@toon-protocol/core';
+import { ToonError, HandlePacketAcceptResponse, HandlePacketRejectResponse, ReputationScore, SkillDescriptor, EmbeddableConnectorLike, KnownPeer, SettlementConfig, ChainProviderConfigEntry, ConnectorChannelClient, BootstrapEventListener, BootstrapResult, DvmJobStatus, IlpSendResult, ParsedWorkflowDefinition } 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';
@@ -251,7 +251,6 @@ interface PaymentRequest {
 }
 interface PaymentResponse {
     accept: boolean;
-    fulfillment?: string;
     code?: string;
     message?: string;
     data?: string;
@@ -309,6 +308,15 @@ interface BuildSkillDescriptorConfig {
     inputSchema?: Record<string, unknown>;
     /** Available AI models. */
     models?: string[];
+    /** Pre-computed reputation score for the skill descriptor. */
+    reputation?: ReputationScore;
+    /** TEE attestation metadata for the skill descriptor. */
+    attestation?: {
+        /** 64-char hex event ID of the provider's latest kind:10033 attestation event. */
+        eventId: string;
+        /** Enclave image hash for the TEE environment. */
+        enclaveImageHash: string;
+    };
 }
 /**
  * Builds a SkillDescriptor from the handler registry and configuration.
@@ -387,7 +395,19 @@ interface NodeConfig {
      * If not set, the identity's secp256k1 key is used.
      */
     settlementPrivateKey?: string;
-    /** ILP address (default: 'g.toon.local') */
+    /**
+     * Upstream peer's ILP address prefix for address derivation.
+     * When set, the node derives its ILP address as
+     * `deriveChildAddress(upstreamPrefix, pubkey)` and ignores `ilpAddress`.
+     */
+    upstreamPrefix?: string;
+    /**
+     * Multiple upstream peer prefixes for multi-peered nodes (Story 7.3).
+     * When set, derives one ILP address per upstream prefix. Takes priority
+     * over `upstreamPrefix` (singular) when both are set.
+     */
+    upstreamPrefixes?: string[];
+    /** ILP address (default: derived from pubkey under ILP_ROOT_PREFIX) */
     ilpAddress?: string;
     /** BTP endpoint URL advertised in kind:10032 announcements */
     btpEndpoint?: string;
@@ -403,6 +423,11 @@ interface NodeConfig {
      * A 1KB event costs 10,240 micro-USDC = ~$0.01.
      */
     basePricePerByte?: bigint;
+    /**
+     * Routing fee per byte charged by this node as an intermediary (default: 0n = free routing).
+     * Advertised in kind:10032 peer info events as a non-negative integer string.
+     */
+    feePerByte?: bigint;
     /** Dev mode skips signature verification (default: false) */
     devMode?: boolean;
     /** TOON encoder function */
@@ -419,6 +444,28 @@ interface NodeConfig {
     ardriveEnabled?: boolean;
     /** Per-kind pricing overrides */
     kindPricing?: Record<number, bigint>;
+    /**
+     * Multi-chain provider configuration for the embedded connector.
+     * When provided, passed directly to ConnectorNode as `chainProviders`.
+     * Takes priority over the legacy `settlementInfra` auto-configuration.
+     * Only used when auto-creating an embedded connector.
+     */
+    chainProviders?: ChainProviderConfigEntry[];
+    /**
+     * NIP-59 transport privacy configuration for the embedded connector.
+     * When enabled, per-packet claims are wrapped in three-layer encryption.
+     * Only used when auto-creating an embedded connector.
+     */
+    nip59?: {
+        enabled: boolean;
+    };
+    /**
+     * Per-peer NIP-59 public keys for claim encryption.
+     * Map of peer ID to compressed secp256k1 public key (hex, 66 chars).
+     * Applied to peer configs when registering peers with the connector.
+     * Only used when auto-creating an embedded connector.
+     */
+    peerNip59PublicKeys?: Record<string, string>;
     /** Config-based handler registration (alternative to post-creation .on()) */
     handlers?: Record<number, Handler>;
     /** Config-based default handler (alternative to post-creation .onDefault()) */
@@ -447,7 +494,8 @@ interface StartResult {
 interface PublishEventResult {
     success: boolean;
     eventId: string;
-    fulfillment?: string;
+    /** Response data from the ILP FULFILL packet (e.g., Arweave tx ID for kind:5094). */
+    data?: string;
     code?: string;
     message?: string;
 }
@@ -482,11 +530,17 @@ interface ServiceNode {
      * ILP PREPARE packet via the runtime client.
      *
      * @param event - The Nostr event to publish
-     * @param options - Must include destination ILP address
+     * @param options - Must include destination ILP address. Optional `amount`
+     *   overrides the default basePricePerByte * toonData.length calculation
+     *   (prepaid model: send exact destination amount). Optional `bid` is a
+     *   client-side safety cap: if the destination amount exceeds `bid`, the
+     *   SDK throws before sending any ILP packet.
      * @returns Result with success/failure info and event ID
      */
     publishEvent(event: NostrEvent, options?: {
         destination: string;
+        amount?: bigint;
+        bid?: bigint;
     }): Promise<PublishEventResult>;
     /**
      * Publish a Kind 7000 DVM job feedback event via ILP PREPARE.
@@ -541,6 +595,10 @@ interface ServiceNode {
      * The payment routes through the ILP mesh using the same infrastructure
      * as relay write fees.
      *
+     * @deprecated Use publishEvent() with amount option instead. Prepaid model:
+     * send job request + payment in one packet via
+     * `publishEvent(event, { destination, amount: computePrice })`.
+     *
      * @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)
@@ -549,6 +607,40 @@ interface ServiceNode {
     settleCompute(resultEvent: NostrEvent, providerIlpAddress: string, options?: {
         originalBid?: string;
     }): Promise<IlpSendResult>;
+    /**
+     * Add a new upstream peer, deriving and registering its ILP address.
+     *
+     * Updates the AddressRegistry, registers a self-route in the embedded
+     * connector, and triggers kind:10032 republication via BootstrapService.
+     *
+     * @param upstreamPrefix - The upstream peer's ILP address prefix
+     */
+    addUpstreamPeer(upstreamPrefix: string): void;
+    /**
+     * Remove an upstream peer, unregistering its derived ILP address.
+     *
+     * Updates the AddressRegistry, removes the self-route from the embedded
+     * connector, and triggers kind:10032 republication via BootstrapService.
+     *
+     * @param upstreamPrefix - The upstream prefix to remove
+     */
+    removeUpstreamPeer(upstreamPrefix: string): void;
+    /**
+     * Claim a prefix from an upstream peer by sending a prefix claim event
+     * with payment via ILP.
+     *
+     * Builds a Kind 10034 prefix claim event, reads the upstream's prefix
+     * pricing from its kind:10032 advertisement, and calls publishEvent()
+     * with the appropriate amount.
+     *
+     * @param prefix - The prefix string to claim (e.g., 'useast')
+     * @param upstreamDestination - ILP address of the upstream node
+     * @param options - Optional prefixPrice override (defaults to upstream's prefixPricing.basePrice from discovery)
+     * @returns Result with success/failure info and event ID
+     */
+    claimPrefix(prefix: string, upstreamDestination: string, options?: {
+        prefixPrice?: bigint;
+    }): Promise<PublishEventResult>;
 }
 /**
  * Creates a fully wired ServiceNode from configuration.
@@ -570,4 +662,552 @@ interface ServiceNode {
  */
 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 };
+/**
+ * Workflow Orchestrator for multi-step DVM pipelines (Story 6.1).
+ *
+ * Manages the lifecycle of a workflow chain: creates step job requests,
+ * detects step completion/failure, advances to the next step, handles
+ * timeouts, and settles compute payments per step.
+ *
+ * The orchestrator uses the TOON relay as the orchestration layer --
+ * there is no separate workflow engine. Step completion is detected
+ * via relay event subscriptions (Kind 6xxx results, Kind 7000 feedback).
+ *
+ * State machine states:
+ *   - `pending`: Workflow created but not yet started
+ *   - `step_N_running`: Step N's job request published, waiting for result
+ *   - `step_N_failed`: Step N failed (error or timeout), workflow aborted
+ *   - `completed`: All steps finished successfully
+ *
+ * Settlement: Each step settles individually via settleCompute().
+ * The orchestrator validates sum(step_amounts) <= total_bid before settlement.
+ *
+ * Forward-compatible with Epic 7 prepaid protocol: settlement logic is
+ * isolated in handleStepResult() so swapping to prepaid per-step payment
+ * requires changes only in that method.
+ */
+
+/**
+ * Workflow state type. Uses template literal types for step-indexed states.
+ * Note: Timeout is represented as `step_N_failed` (timeout is a failure mode,
+ * not a separate terminal state). The timeout cause is communicated in the
+ * customer notification content.
+ */
+type WorkflowState = 'pending' | `step_${number}_running` | `step_${number}_failed` | 'completed';
+/**
+ * Event store interface for workflow state persistence.
+ * Minimal interface -- only store() and query() are needed.
+ */
+interface WorkflowEventStore {
+    store(event: NostrEvent): Promise<void>;
+    query(filter: {
+        kinds?: number[];
+        '#e'?: string[];
+    }): Promise<NostrEvent[]>;
+}
+/**
+ * Configuration options for the WorkflowOrchestrator.
+ */
+interface WorkflowOrchestratorOptions {
+    /** Secret key for signing step job request events (32-byte Uint8Array). */
+    secretKey?: Uint8Array;
+    /** Per-step timeout in milliseconds (default: 300000 = 5 minutes). */
+    stepTimeoutMs?: number;
+    /** Injectable time source for deterministic testing. */
+    now?: () => number;
+    /**
+     * Injectable timer factory for deterministic testing.
+     * Defaults to global setTimeout. Inject a custom implementation
+     * to control timer advancement in tests without vi.useFakeTimers().
+     */
+    setTimer?: (callback: () => void, ms: number) => ReturnType<typeof setTimeout>;
+    /**
+     * Injectable timer cancellation for deterministic testing.
+     * Defaults to global clearTimeout. Must pair with setTimer.
+     */
+    clearTimer?: (handle: ReturnType<typeof setTimeout>) => void;
+    /** Optional event store for workflow state persistence. */
+    eventStore?: WorkflowEventStore;
+    /** Default destination ILP address for publishing events. */
+    destination?: string;
+    /** Workflow definition event ID (for referencing in notifications). */
+    workflowEventId?: string;
+    /** Customer pubkey (for directing notifications). */
+    customerPubkey?: string;
+}
+/**
+ * Per-step state tracking.
+ */
+interface StepState {
+    /** Index of this step (0-based). */
+    index: number;
+    /** The job request event ID published for this step. */
+    requestEventId?: string;
+    /** The result event received for this step. */
+    resultEvent?: NostrEvent;
+    /** Whether this step has been settled. */
+    settled: boolean;
+}
+/**
+ * Orchestrates a multi-step DVM workflow chain.
+ *
+ * Each instance manages a single workflow. For concurrent workflows,
+ * create multiple WorkflowOrchestrator instances sharing the same
+ * ServiceNode.
+ */
+declare class WorkflowOrchestrator {
+    private readonly node;
+    private readonly options;
+    private state;
+    private definition;
+    private workflowEventId;
+    private customerPubkey;
+    private currentStepIndex;
+    private stepStates;
+    private timeoutHandle;
+    private processedResultIds;
+    constructor(node: ServiceNode, options?: WorkflowOrchestratorOptions);
+    /**
+     * Returns the current workflow state.
+     */
+    getState(): WorkflowState;
+    /**
+     * Returns per-step state tracking data (for testing/debugging).
+     */
+    getStepStates(): readonly Readonly<StepState>[];
+    /**
+     * Starts a workflow: parses the definition, creates and publishes
+     * the Kind 5xxx job request for step 1, sets state to step_1_running.
+     */
+    startWorkflow(definition: ParsedWorkflowDefinition): Promise<void>;
+    /**
+     * Handles a Kind 6xxx result event for the current step.
+     *
+     * If the current step matches, extracts the result content and either:
+     * - Advances to the next step (publishes Kind 5xxx for step N+1)
+     * - Marks workflow as completed (if this was the final step)
+     *
+     * Idempotent: re-processing a result for an already-advanced step is a no-op.
+     */
+    handleStepResult(resultEvent: NostrEvent): Promise<void>;
+    /**
+     * Handles a Kind 7000 feedback event for the current step.
+     *
+     * If the feedback status is 'error', marks the workflow as failed
+     * and notifies the customer.
+     */
+    handleStepFeedback(feedbackEvent: NostrEvent): Promise<void>;
+    /**
+     * Cleans up resources (timeout handles).
+     */
+    destroy(): void;
+    /**
+     * Publishes a Kind 5xxx job request for the given step.
+     */
+    private publishStepRequest;
+    /**
+     * Settles compute payment for a completed step.
+     */
+    private settleStep;
+    /**
+     * Returns the bid allocation for a specific step.
+     * Uses explicit bidAllocation if set, otherwise proportional split.
+     */
+    private getStepBid;
+    /**
+     * Publishes a Kind 7000 workflow notification to the customer.
+     */
+    private publishWorkflowNotification;
+    /**
+     * Starts a timeout timer for the current step.
+     */
+    private startStepTimeout;
+    /**
+     * Returns the secret key for signing step events.
+     * Falls back to a deterministic key derived from the node pubkey
+     * (for testing -- production should always pass secretKey in options).
+     */
+    private getSecretKey;
+    /**
+     * Clears the current step timeout.
+     */
+    private clearStepTimeout;
+}
+
+/**
+ * Swarm Coordinator for competitive DVM bidding (Story 6.2).
+ *
+ * Manages the lifecycle of a competitive swarm: collects provider
+ * submissions, handles timeout-based judging deadlines, validates
+ * winner selection, and settles compute payment to the winner only.
+ *
+ * The coordinator uses the TOON relay as the orchestration layer --
+ * there is no separate swarm engine. Submission arrival is detected
+ * via relay event subscriptions (Kind 6xxx results).
+ *
+ * State machine states:
+ *   - `collecting`: Waiting for provider submissions (Kind 6xxx results)
+ *   - `judging`: Timeout or max submissions reached; customer selects winner
+ *   - `settled`: Winner paid via settleCompute(); swarm complete
+ *   - `failed`: No submissions within timeout or error
+ *
+ * Settlement: Only the winning provider receives compute payment.
+ * Losing providers paid relay write fees (sunk cost) but receive
+ * no compute payment -- this is by design to incentivize quality.
+ *
+ * Forward-compatible with Epic 7 prepaid protocol: settlement logic
+ * is isolated in selectWinner() so swapping to prepaid per-winner
+ * payment requires changes only in that method.
+ */
+
+/**
+ * Swarm state type.
+ * - `collecting`: Waiting for provider submissions.
+ * - `judging`: Timeout or max submissions reached; awaiting winner selection.
+ * - `settled`: Winner paid; swarm complete.
+ * - `failed`: No submissions within timeout or error.
+ */
+type SwarmState = 'collecting' | 'judging' | 'settled' | 'failed';
+/**
+ * Configuration options for the SwarmCoordinator.
+ */
+interface SwarmCoordinatorOptions {
+    /** Secret key for signing events (32-byte Uint8Array). */
+    secretKey?: Uint8Array;
+    /** Swarm collection timeout in milliseconds (default: 600000 = 10 minutes). */
+    timeoutMs?: number;
+    /** Injectable time source for deterministic testing. */
+    now?: () => number;
+    /**
+     * Injectable timer factory for deterministic testing.
+     * Defaults to global setTimeout. Inject a custom implementation
+     * to control timer advancement in tests without vi.useFakeTimers().
+     */
+    setTimer?: (callback: () => void, ms: number) => ReturnType<typeof setTimeout>;
+    /**
+     * Injectable timer cancellation for deterministic testing.
+     * Defaults to global clearTimeout. Must pair with setTimer.
+     */
+    clearTimer?: (handle: ReturnType<typeof setTimeout>) => void;
+    /** Optional event store for swarm state persistence. */
+    eventStore?: WorkflowEventStore;
+    /** Default destination ILP address for publishing events. */
+    destination?: string;
+}
+/**
+ * Coordinates a competitive DVM swarm.
+ *
+ * Each instance manages a single swarm. For concurrent swarms,
+ * create multiple SwarmCoordinator instances sharing the same
+ * ServiceNode.
+ */
+declare class SwarmCoordinator {
+    private readonly node;
+    private readonly options;
+    private state;
+    private swarmRequestId;
+    private customerPubkey;
+    private maxProviders;
+    private submissions;
+    private timeoutHandle;
+    private started;
+    private settlementSucceeded;
+    private submissionIds;
+    constructor(node: ServiceNode, options?: SwarmCoordinatorOptions);
+    /**
+     * Returns the current swarm state.
+     */
+    getState(): SwarmState;
+    /**
+     * Returns whether settlement was successfully completed.
+     * Only meaningful when state is 'settled' (returns true).
+     * If settlement fails, the state remains 'judging' and this returns false.
+     */
+    isSettlementSucceeded(): boolean;
+    /**
+     * Returns the collected eligible submissions.
+     */
+    getSubmissions(): readonly NostrEvent[];
+    /**
+     * Starts a swarm: parses the swarm request, initializes collection,
+     * and starts the timeout timer.
+     */
+    startSwarm(swarmRequest: NostrEvent): Promise<void>;
+    /**
+     * Handles a Kind 6xxx result event (provider submission).
+     *
+     * Validates the `e` tag references the swarm request, adds to the
+     * submissions list, and checks if max providers is reached.
+     *
+     * Late submissions (after timeout or max reached) are ignored.
+     * Submissions before startSwarm() are silently ignored.
+     */
+    handleSubmission(resultEvent: NostrEvent): Promise<void>;
+    /**
+     * Selects the winner and settles compute payment.
+     *
+     * Validates:
+     * - Swarm is in `judging` state (not `collecting`, `settled`, or `failed`)
+     * - Selection references a submission in the collected set
+     * - Swarm has not already been settled (idempotency guard)
+     *
+     * @throws ToonError with code DVM_SWARM_ALREADY_SETTLED if already settled
+     * @throws ToonError with code DVM_SWARM_INVALID_SELECTION if winner not in submissions
+     */
+    selectWinner(selectionEvent: NostrEvent): Promise<void>;
+    /**
+     * Cleans up resources (timeout handles).
+     */
+    destroy(): void;
+    /**
+     * Starts the collection timeout timer.
+     */
+    private startTimeout;
+    /**
+     * Publishes a Kind 7000 feedback event indicating no submissions were received.
+     */
+    private publishNoSubmissionsFeedback;
+    /**
+     * Clears the current timeout timer.
+     */
+    private clearTimeout;
+}
+
+/**
+ * Prefix claim handler for the TOON prefix marketplace.
+ *
+ * Creates a handler that processes kind 10034 prefix claim events,
+ * validates payment and prefix availability, and publishes grant
+ * confirmations. Lives in SDK (not core) because it depends on
+ * the SDK's Handler type and HandlerContext interface.
+ */
+
+/**
+ * Options for creating a prefix claim handler.
+ */
+interface PrefixClaimHandlerOptions {
+    /** Pricing configuration for prefix claims. */
+    prefixPricing: {
+        basePrice: bigint;
+    };
+    /** Secret key for signing grant events. */
+    secretKey: Uint8Array;
+    /** Returns the current map of claimed prefixes (prefix -> claimer pubkey). */
+    getClaimedPrefixes: () => Map<string, string>;
+    /**
+     * Atomically claim a prefix for a pubkey. Returns true if the claim
+     * succeeded, false if the prefix was already taken. This is the
+     * serialization point for race condition defense.
+     */
+    claimPrefix: (prefix: string, claimerPubkey: string) => boolean;
+    /** Publish the grant event (e.g., to the local relay). */
+    publishGrant: (grantEvent: NostrEvent) => Promise<void>;
+    /** ILP address prefix to include in the grant event (default: 'g.toon'). */
+    ilpAddressPrefix?: string;
+}
+/**
+ * Creates a handler for kind 10034 prefix claim events.
+ *
+ * The handler validates payment, prefix availability, and prefix format,
+ * then atomically claims the prefix and publishes a grant confirmation.
+ *
+ * @param options - Handler configuration
+ * @returns A Handler function for kind 10034 events
+ */
+declare function createPrefixClaimHandler(options: PrefixClaimHandlerOptions): Handler;
+
+/**
+ * Arweave upload adapter wrapping @ardrive/turbo-sdk.
+ *
+ * This is the ONLY file that imports @ardrive/turbo-sdk, isolating the
+ * external dependency behind an interface (risk E8-R002).
+ */
+/**
+ * Interface for uploading data to Arweave.
+ * Implementations wrap a specific Arweave upload SDK.
+ */
+interface ArweaveUploadAdapter {
+    upload(data: Buffer, tags?: Record<string, string>): Promise<{
+        txId: string;
+    }>;
+}
+/**
+ * Turbo SDK upload adapter using @ardrive/turbo-sdk.
+ *
+ * - Dev/free tier (<=100KB): pass no turboClient, uses TurboFactory.unauthenticated()
+ * - Prod (paid, uncapped): pass a TurboAuthenticatedClient from TurboFactory.authenticated()
+ *
+ * The turboClient is typed as `unknown` to avoid importing @ardrive/turbo-sdk types
+ * in this interface. The actual TurboAuthenticatedClient or TurboUnauthenticatedClient
+ * is duck-typed at runtime.
+ */
+declare class TurboUploadAdapter implements ArweaveUploadAdapter {
+    private turboClient;
+    private initialized;
+    constructor(turboClient?: unknown);
+    private getClient;
+    upload(data: Buffer, tags?: Record<string, string>): Promise<{
+        txId: string;
+    }>;
+}
+
+/**
+ * Chunk state manager for multi-packet blob uploads.
+ *
+ * Accumulates chunks for a given uploadId, assembles them in order
+ * when all chunks have arrived, and enforces timeout and memory caps.
+ */
+interface ChunkManagerConfig {
+    /** Timeout in milliseconds before partial uploads are discarded (default: 300_000 = 5 min). */
+    timeoutMs?: number;
+    /** Maximum number of concurrent active uploads (default: 100). */
+    maxActiveUploads?: number;
+    /** Maximum total bytes accumulated per upload before rejection (default: 50MB). */
+    maxBytesPerUpload?: number;
+}
+interface AddChunkResult {
+    /** Whether all chunks have been received and the blob is fully assembled. */
+    complete: boolean;
+    /** The assembled blob (only present when complete is true). */
+    assembled?: Buffer;
+    /** Error message if the chunk was rejected. */
+    error?: string;
+}
+/**
+ * Manages chunked upload state for the Arweave DVM handler.
+ */
+declare class ChunkManager {
+    private uploads;
+    private readonly timeoutMs;
+    private readonly maxActiveUploads;
+    private readonly maxBytesPerUpload;
+    constructor(config?: ChunkManagerConfig);
+    /**
+     * Add a chunk for a given uploadId.
+     *
+     * @param uploadId - Unique identifier for the upload session.
+     * @param chunkIndex - Zero-based index of this chunk.
+     * @param totalChunks - Total number of chunks expected.
+     * @param data - The chunk data.
+     * @returns Result indicating completion status or error.
+     * @throws Error if memory cap reached or duplicate chunk.
+     */
+    addChunk(uploadId: string, chunkIndex: number, totalChunks: number, data: Buffer): AddChunkResult;
+    /**
+     * Check if an upload is complete (all chunks received).
+     * Returns false if the uploadId is unknown (cleaned up or never started).
+     */
+    isComplete(uploadId: string): boolean;
+    /**
+     * Clean up state for a given uploadId, clearing the timeout timer.
+     */
+    cleanup(uploadId: string): void;
+    /**
+     * Clean up all active uploads and their timers.
+     * Call this on node shutdown to prevent timer leaks.
+     */
+    destroyAll(): void;
+}
+
+/**
+ * Arweave DVM handler for kind:5094 blob storage requests.
+ *
+ * Creates a handler function that:
+ * 1. Parses the kind:5094 event from the HandlerContext
+ * 2. For single-packet uploads: uploads directly to Arweave via the adapter
+ * 3. For chunked uploads: accumulates via ChunkManager, uploads on completion
+ *
+ * The handler does NOT validate pricing -- the SDK pricing validator
+ * (packages/sdk/src/pricing-validator.ts) runs BEFORE the handler is invoked.
+ *
+ * Returns HandlePacketAcceptResponse with `data` field containing the Arweave
+ * tx ID -- NOT via ctx.accept() which only supports metadata.
+ */
+
+interface ArweaveDvmConfig {
+    /** Arweave upload adapter (wraps @ardrive/turbo-sdk). */
+    turboAdapter: ArweaveUploadAdapter;
+    /** Chunk state manager for multi-packet uploads. */
+    chunkManager: ChunkManager;
+    /** Optional default Arweave data item tags (e.g., Content-Type). */
+    arweaveTags?: Record<string, string>;
+}
+/**
+ * Creates an Arweave DVM handler for kind:5094 blob storage requests.
+ *
+ * @param config - Handler configuration with adapter and chunk manager.
+ * @returns A handler function compatible with HandlerRegistry.on().
+ */
+declare function createArweaveDvmHandler(config: ArweaveDvmConfig): (ctx: HandlerContext) => Promise<HandlerResponse>;
+
+/**
+ * Client-side helpers for uploading blobs to an Arweave DVM provider.
+ *
+ * - uploadBlob(): single-packet upload for blobs under the chunk threshold
+ * - uploadBlobChunked(): multi-packet upload that splits large blobs into chunks
+ *
+ * Both use publishEvent() with the amount override (Story 7.6, D7-007).
+ */
+
+/**
+ * Minimal interface for publishing events. Matches ServiceNode.publishEvent().
+ */
+interface PublishableNode {
+    publishEvent(event: NostrEvent, options?: {
+        destination: string;
+        amount?: bigint;
+    }): Promise<Pick<PublishEventResult, 'success' | 'eventId' | 'data' | 'message'>>;
+}
+/**
+ * Options for single-packet blob upload.
+ */
+interface UploadBlobOptions {
+    /** MIME type of the blob (default: 'application/octet-stream'). */
+    contentType?: string;
+    /** Secret key for signing the event. */
+    secretKey: Uint8Array;
+    /** Price per byte in USDC micro-units for amount calculation. */
+    pricePerByte?: bigint;
+}
+/**
+ * Options for chunked blob upload.
+ */
+interface UploadBlobChunkedOptions {
+    /** Chunk size in bytes (default: 500_000, under 512KB threshold). */
+    chunkSize?: number;
+    /** MIME type of the blob (default: 'application/octet-stream'). */
+    contentType?: string;
+    /** Secret key for signing events. */
+    secretKey: Uint8Array;
+    /** Price per byte in USDC micro-units for amount calculation. */
+    pricePerByte?: bigint;
+}
+/**
+ * Upload a blob to an Arweave DVM provider in a single ILP packet.
+ *
+ * Uses publishEvent() with amount override (D7-007) to send the blob
+ * and payment in one ILP PREPARE.
+ *
+ * @param node - The ServiceNode (or compatible) to publish through.
+ * @param blob - The raw blob data to upload.
+ * @param destination - The provider's ILP address.
+ * @param options - Upload options including secretKey for signing.
+ * @returns The Arweave transaction ID from the FULFILL data field.
+ */
+declare function uploadBlob(node: PublishableNode, blob: Buffer, destination: string, options: UploadBlobOptions): Promise<string>;
+/**
+ * Upload a large blob to an Arweave DVM provider using chunked uploads.
+ *
+ * Splits the blob into chunks, each sent as a separate kind:5094 ILP PREPARE
+ * with uploadId, chunkIndex, and totalChunks params. Each chunk carries its
+ * own payment. The final chunk's FULFILL data contains the Arweave tx ID.
+ *
+ * @param node - The ServiceNode (or compatible) to publish through.
+ * @param blob - The raw blob data to upload.
+ * @param destination - The provider's ILP address.
+ * @param options - Chunked upload options including secretKey for signing.
+ * @returns The Arweave transaction ID from the final chunk's FULFILL data.
+ */
+declare function uploadBlobChunked(node: PublishableNode, blob: Buffer, destination: string, options: UploadBlobChunkedOptions): Promise<string>;
+
+export { type AddChunkResult, type ArweaveDvmConfig, type ArweaveUploadAdapter, type BuildSkillDescriptorConfig, ChunkManager, type ChunkManagerConfig, type CreateHandlerContextOptions, type FromMnemonicOptions, type Handler, type HandlerContext, HandlerError, HandlerRegistry, type HandlerResponse, IdentityError, type NodeConfig, NodeError, type NodeIdentity, type PaymentHandlerBridgeConfig, type PaymentRequest, type PaymentResponse, type PrefixClaimHandlerOptions, PricingError, type PricingValidationResult, type PricingValidatorConfig, type PublishEventResult, type PublishableNode, type ServiceNode, type StartResult, SwarmCoordinator, type SwarmCoordinatorOptions, type SwarmState, TurboUploadAdapter, type UploadBlobChunkedOptions, type UploadBlobOptions, VerificationError, type VerificationPipelineConfig, type VerificationResult, type WorkflowEventStore, WorkflowOrchestrator, type WorkflowOrchestratorOptions, type WorkflowState, buildSkillDescriptor, createArweaveDvmHandler, createEventStorageHandler, createHandlerContext, createNode, createPaymentHandlerBridge, createPrefixClaimHandler, createPricingValidator, createVerificationPipeline, fromMnemonic, fromSecretKey, generateMnemonic, uploadBlob, uploadBlobChunked };