@elisym/sdk 0.22.0 → 0.24.0

package/dist/index.d.cts

@@ -1,9 +1,9 @@
 import { Address, TransactionSigner, Rpc, SolanaRpcApi, Signature } from '@solana/kit';
+import { z } from 'zod';
 import { Filter, Event } from 'nostr-tools';
 import { A as Asset } from './assets-C-nzSYD4.cjs';
 export { C as Chain, K as KNOWN_ASSETS, N as NATIVE_SOL, U as USDC_SOLANA_DEVNET, a as assetByKey, b as assetKey, f as formatAssetAmount, p as parseAssetAmount, r as resolveAssetFromPaymentRequest, c as resolveKnownAsset } from './assets-C-nzSYD4.cjs';
-import { z } from 'zod';
-export { G as GlobalConfig, a as GlobalConfigSchema, S as SessionSpendLimitEntry, b as SessionSpendLimitEntrySchema } from './global-schema-CddHP2nk.cjs';
+export { G as GlobalConfig, a as GlobalConfigSchema, S as SessionSpendLimitEntry, b as SessionSpendLimitEntrySchema } from './global-schema-BsVFDtkt.cjs';
 export { R as RateLimitDecision, S as SlidingWindowLimiter, a as SlidingWindowLimiterOptions, c as createSlidingWindowLimiter } from './rateLimiter-CoEmZkSX.cjs';
 
 declare class ElisymIdentity {
@@ -23,6 +23,170 @@ declare class ElisymIdentity {
     static fromHex(hex: string): ElisymIdentity;
 }
 
+/**
+ * Job file-attachment descriptor and the job-payload envelope (browser-safe).
+ *
+ * A file job carries its file out-of-band (P2P via iroh); the Nostr event's
+ * (NIP-44-encrypted) `content` carries only a small JSON envelope describing the
+ * file and how to fetch it. This module owns the envelope shape, its encode, and
+ * its strict decode. It deliberately does NOT construct an iroh `BlobTicket` - the
+ * `ticket` is validated only as a bounded opaque string so that decoding an
+ * untrusted, possibly pre-payment request never pulls in the native iroh addon.
+ *
+ * The transport is a discriminated union keyed on `kind`; Phase 1 ships only
+ * `iroh`. A future HTTP/Blossom transport is added as another union member without
+ * changing this contract.
+ */
+
+/** Current envelope version. Bumped only on a breaking envelope-shape change. */
+declare const ENVELOPE_VERSION = "elisym-job/1";
+declare const FileTransportSchema: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+    kind: z.ZodLiteral<"iroh">;
+    /** Opaque iroh `BlobTicket` string. Parsed into a real ticket only at fetch time. */
+    ticket: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    kind: "iroh";
+    ticket: string;
+}, {
+    kind: "iroh";
+    ticket: string;
+}>]>;
+declare const FileAttachmentSchema: z.ZodObject<{
+    /** Display name only. Never used to derive a filesystem path (callers sanitize). */
+    name: z.ZodString;
+    /** Declared size in bytes (display/hint only; enforcement is on actual streamed bytes). */
+    size: z.ZodNumber;
+    mime: z.ZodString;
+    /** Ordered by sender preference; at least one. */
+    transports: z.ZodArray<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+        kind: z.ZodLiteral<"iroh">;
+        /** Opaque iroh `BlobTicket` string. Parsed into a real ticket only at fetch time. */
+        ticket: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        kind: "iroh";
+        ticket: string;
+    }, {
+        kind: "iroh";
+        ticket: string;
+    }>]>, "many">;
+    /** Optional provider hint (unix seconds) for when seeding may stop. */
+    seedingExpiresAt: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    size: number;
+    mime: string;
+    transports: {
+        kind: "iroh";
+        ticket: string;
+    }[];
+    seedingExpiresAt?: number | undefined;
+}, {
+    name: string;
+    size: number;
+    mime: string;
+    transports: {
+        kind: "iroh";
+        ticket: string;
+    }[];
+    seedingExpiresAt?: number | undefined;
+}>;
+declare const JobPayloadEnvelopeSchema: z.ZodObject<{
+    v: z.ZodLiteral<"elisym-job/1">;
+    text: z.ZodOptional<z.ZodString>;
+    attachment: z.ZodOptional<z.ZodObject<{
+        /** Display name only. Never used to derive a filesystem path (callers sanitize). */
+        name: z.ZodString;
+        /** Declared size in bytes (display/hint only; enforcement is on actual streamed bytes). */
+        size: z.ZodNumber;
+        mime: z.ZodString;
+        /** Ordered by sender preference; at least one. */
+        transports: z.ZodArray<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+            kind: z.ZodLiteral<"iroh">;
+            /** Opaque iroh `BlobTicket` string. Parsed into a real ticket only at fetch time. */
+            ticket: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            kind: "iroh";
+            ticket: string;
+        }, {
+            kind: "iroh";
+            ticket: string;
+        }>]>, "many">;
+        /** Optional provider hint (unix seconds) for when seeding may stop. */
+        seedingExpiresAt: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        size: number;
+        mime: string;
+        transports: {
+            kind: "iroh";
+            ticket: string;
+        }[];
+        seedingExpiresAt?: number | undefined;
+    }, {
+        name: string;
+        size: number;
+        mime: string;
+        transports: {
+            kind: "iroh";
+            ticket: string;
+        }[];
+        seedingExpiresAt?: number | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    v: "elisym-job/1";
+    text?: string | undefined;
+    attachment?: {
+        name: string;
+        size: number;
+        mime: string;
+        transports: {
+            kind: "iroh";
+            ticket: string;
+        }[];
+        seedingExpiresAt?: number | undefined;
+    } | undefined;
+}, {
+    v: "elisym-job/1";
+    text?: string | undefined;
+    attachment?: {
+        name: string;
+        size: number;
+        mime: string;
+        transports: {
+            kind: "iroh";
+            ticket: string;
+        }[];
+        seedingExpiresAt?: number | undefined;
+    } | undefined;
+}>;
+type FileTransport = z.infer<typeof FileTransportSchema>;
+type FileAttachment = z.infer<typeof FileAttachmentSchema>;
+type JobPayloadEnvelope = z.infer<typeof JobPayloadEnvelopeSchema>;
+/** Decoded job payload: a free-text note and/or a file attachment. */
+interface DecodedJobPayload {
+    text?: string;
+    attachment?: FileAttachment;
+}
+/**
+ * Serialize a job payload into the envelope string that goes (encrypted) into a
+ * Nostr event's `content`. Used only when an attachment is present; plain-text
+ * jobs send their text directly and are never wrapped.
+ */
+declare function encodeJobPayload(payload: DecodedJobPayload): string;
+/**
+ * Decode decrypted `content` into a job payload.
+ *
+ * - Content longer than `MAX_INPUT_LENGTH` is treated as raw text without parsing
+ *   (a valid envelope is small and a valid text job is capped at submit time), so
+ *   untrusted, possibly-huge intake content is never `JSON.parse`d unbounded.
+ * - Non-JSON, non-object JSON, or a JSON object that does not carry our
+ *   `elisym-job/` version marker is returned as raw text.
+ * - A value that DOES carry an `elisym-job/` marker is validated strictly: an
+ *   unknown version or a malformed envelope throws (callers skip/surface it)
+ *   rather than being silently mistreated as text.
+ */
+declare function decodeJobPayload(content: string): DecodedJobPayload;
+
 interface SubCloser {
     close: (reason?: string) => void;
 }
@@ -34,6 +198,16 @@ interface CapabilityCard {
     payment?: PaymentInfo;
     image?: string;
     static?: boolean;
+    /**
+     * MIME the capability expects as a file input (from a dynamic-script skill's
+     * `input_mime`). Discovery hint only; the provider still content-sniffs the
+     * actual file. Its presence means the capability needs a file input - which
+     * the web app cannot send (no iroh transport), so the web app blocks the Buy
+     * button. `*` = any file, `image/*` = any image, `image/png` = exact.
+     */
+    inputMime?: string;
+    /** MIME of a file result the capability produces (from `output_mime`). */
+    outputMime?: string;
 }
 /** Payment info embedded in capability card (legacy format for on-network events). */
 interface PaymentInfo {
@@ -139,17 +313,32 @@ interface Job {
     asset?: PaymentAssetRef;
 }
 interface SubmitJobOptions {
-    /** Job input text. Sent unencrypted if providerPubkey is not set. */
+    /**
+     * Job input text. Sent unencrypted if providerPubkey is not set. May be empty
+     * when `attachment` is set (a file-only job carries no text note).
+     */
     input: string;
     capability: string;
     /** Target provider pubkey. If omitted, job is broadcast unencrypted and visible to all relays. */
     providerPubkey?: string;
     /** Kind offset (default 100 - kind 5100). */
     kindOffset?: number;
+    /**
+     * Optional file attachment. When set, `input` (as the text note) and the
+     * attachment are wrapped in a job-payload envelope before encryption. The file
+     * itself travels out-of-band (P2P via iroh), not in the Nostr event.
+     */
+    attachment?: FileAttachment;
 }
 interface JobUpdateCallbacks {
     onFeedback?: (status: string, amount?: number, paymentRequest?: string, senderPubkey?: string) => void;
-    onResult?: (content: string, eventId: string) => void;
+    /**
+     * Fired on a job result. `content` is the result text (for a file result, the
+     * envelope's text note, or `''`); `attachment` is the file descriptor when the
+     * result carries a file. The file is fetched separately (P2P via iroh), never
+     * inlined here.
+     */
+    onResult?: (content: string, eventId: string, attachment?: FileAttachment) => void;
     onError?: (error: string) => void;
     /**
      * Fired when the result wait window expires without a result - a distinct,
@@ -536,14 +725,14 @@ declare class MarketplaceService {
      */
     subscribeToJobRequests(identity: ElisymIdentity, kinds: number[], onRequest: (event: Event) => void): SubCloser;
     /** Submit a job result with NIP-44 encrypted content. Result kind is derived from the request kind. */
-    submitJobResult(identity: ElisymIdentity, requestEvent: Event, content: string, amount?: number): Promise<string>;
+    submitJobResult(identity: ElisymIdentity, requestEvent: Event, content: string, amount?: number, attachment?: FileAttachment): Promise<string>;
     /**
      * Submit a job result with retry and exponential backoff.
      * Retries on publish failures (e.g. relay disconnects).
      * With maxAttempts=3: try, ~1s, try, ~2s, try, throw.
      * Jitter: 0.5x-1.0x of calculated delay.
      */
-    submitJobResultWithRetry(identity: ElisymIdentity, requestEvent: Event, content: string, amount?: number, maxAttempts?: number, baseDelayMs?: number): Promise<string>;
+    submitJobResultWithRetry(identity: ElisymIdentity, requestEvent: Event, content: string, amount?: number, maxAttempts?: number, baseDelayMs?: number, attachment?: FileAttachment): Promise<string>;
     /** Submit payment-required feedback with a payment request. */
     submitPaymentRequiredFeedback(identity: ElisymIdentity, requestEvent: Event, amount: number, paymentRequestJson: string): Promise<void>;
     /** Submit processing feedback to notify customer that work has started. */
@@ -1053,7 +1242,16 @@ declare function parsePaymentRequest(input: string, options?: ParseOptions): Par
  */
 type QuickVerifyReason = 'not_found' | 'tx_failed' | 'recipient_mismatch' | 'rpc_error' | 'invalid_input';
 interface QuickVerifyResult {
-    verified: boolean;
+    /**
+     * True when the recipient address received funds in this transaction.
+     *
+     * NOTE: this is NOT proof of a valid elisym job payment. It does not check
+     * the payment `reference` key or that the amount matches the job price - it
+     * is a best-effort signal for the fast discovery-ranking path, where the
+     * original payment request is unavailable. For an authoritative check
+     * (amount + reference) use `SolanaPaymentStrategy.verifyPayment`.
+     */
+    receivedFunds: boolean;
     txSignature: string;
     reason?: QuickVerifyReason;
 }
@@ -1105,6 +1303,12 @@ declare function aggregateNetworkStats(rpc: Rpc<SolanaRpcApi>, options?: Aggrega
  * Returns `null` when the PDA has not been initialized yet (admin must call
  * `initialize_stats` once after program upgrade).
  */
+/**
+ * Best-effort network counters read from the on-chain PDA. These are NOT bound
+ * to verified transfers and can be inflated by a malicious caller, so present
+ * them as approximate/unverified, never as authoritative proof of activity. For
+ * a transfer-derived figure use `aggregateNetworkStats`.
+ */
 interface OnchainNetworkStats {
     jobCount: number;
     volumeNative: bigint;
@@ -1273,10 +1477,15 @@ declare const DEFAULTS: {
     readonly RESULT_RETRY_BASE_MS: 1000;
     readonly QUERY_MAX_CONCURRENCY: 6;
     readonly VERIFY_SIGNATURE_LIMIT: 25;
+    readonly IROH_FETCH_TIMEOUT_MS: 300000;
 };
 /** Protocol limits for input validation. */
 declare const LIMITS: {
     readonly MAX_INPUT_LENGTH: 100000;
+    readonly NIP44_MAX_PLAINTEXT_BYTES: 65535;
+    readonly MAX_ENCRYPTED_INLINE_BYTES: 60000;
+    readonly MAX_REINLINE_TEXT_BYTES: 4194304;
+    readonly MAX_FILE_SIZE: 1073741824;
     readonly MAX_TIMEOUT_SECS: 600;
     readonly MAX_EXECUTION_SECS: 2147483;
     readonly MAX_CAPABILITIES: 20;
@@ -1290,5 +1499,11 @@ declare const LIMITS: {
     readonly MAX_POLICY_SUMMARY_LENGTH: 280;
     readonly MAX_POLICY_VERSION_LENGTH: 32;
 };
+/**
+ * UTF-8 byte length of a string. All size guards on encrypted content measure
+ * BYTES, not `String.length` (UTF-16 code units): NIP-44's plaintext cap is a
+ * byte cap, so a multibyte string under the char cap can still exceed it.
+ */
+declare function utf8ByteLength(value: string): number;
 
-export { type Agent, type AgentPolicy, type AggregateNetworkStatsOptions, Asset, BoundedSet, type BuildTransactionOptions, type CapabilityCard, DEFAULTS, DEFAULT_KIND_OFFSET, DEFAULT_REDACT_PATHS, DiscoveryService, ELISYM_PROTOCOL_TAG, ElisymClient, type ElisymClientConfig, type ElisymClientFullConfig, ElisymIdentity, type EstimatePriorityFeeOptions, type EstimateSolFeeOptions, type GetProtocolConfigOptions, INPUT_REDACT_PATHS, type Job, type JobErrorKind, type JobStatus, type JobSubscriptionOptions, type JobUpdateCallbacks, JobWaitTimeoutError, KIND_APP_HANDLER, KIND_JOB_FEEDBACK, KIND_JOB_REQUEST, KIND_JOB_REQUEST_BASE, KIND_JOB_RESULT, KIND_JOB_RESULT_BASE, KIND_LONG_FORM_ARTICLE, KIND_PING, KIND_PONG, LAMPORTS_PER_SOL, LIMITS, MarketplaceService, MediaService, type Network, type NetworkBaselineEstimate, type NetworkBaselineOptions, type NetworkStats, type NetworkStatsResult, NostrPool, type OnchainNetworkStats, POLICY_D_TAG_PREFIX, POLICY_TYPE_REGEX, POLICY_T_TAG, PROTOCOL_PROGRAM_ID_DEVNET, type ParseOptions, type ParseResult, type ParsedPaymentRequest, type PaymentAssetRef, type PaymentInfo, type PaymentRequestData, PaymentRequestSchema, type PaymentStrategy, type PaymentValidationCode, type PaymentValidationError, type PingResult, PingService, PoliciesService, type PolicyInput, type ProtocolCluster, type ProtocolConfig, type ProtocolConfigInput, type QuickVerifyReason, type QuickVerifyResult, RELAYS, type RankKey, SECRET_REDACT_PATHS, type Signer, type SolFeeEstimate, SolanaPaymentStrategy, type SubCloser, type SubmitJobOptions, type VerifyOptions, type VerifyResult, aggregateNetworkStats, assertExpiry, assertLamports, buildPaymentInstructions, calculateProtocolFee, classifyJobError, clearPriorityFeeCache, clearProtocolConfigCache, clearQuickVerifyCache, compareAgentsByRank, computeRankKey, createPaymentRequestWithOnchainConfig, estimateNetworkBaseline, estimatePriorityFeeMicroLamports, estimateSolFeeLamports, formatFeeBreakdown, formatNetworkBaseline, formatSol, getNetworkStats, getProtocolConfig, getProtocolProgramId, jobRequestKind, jobResultKind, makeCensor, nip44Decrypt, nip44Encrypt, parsePaymentRequest, pickPercentileFee, timeAgo, toDTag, truncateKey, validateAgentName, validateExpiry, verifyJobPaymentQuick };
+export { type Agent, type AgentPolicy, type AggregateNetworkStatsOptions, Asset, BoundedSet, type BuildTransactionOptions, type CapabilityCard, DEFAULTS, DEFAULT_KIND_OFFSET, DEFAULT_REDACT_PATHS, type DecodedJobPayload, DiscoveryService, ELISYM_PROTOCOL_TAG, ENVELOPE_VERSION, ElisymClient, type ElisymClientConfig, type ElisymClientFullConfig, ElisymIdentity, type EstimatePriorityFeeOptions, type EstimateSolFeeOptions, type FileAttachment, type FileTransport, type GetProtocolConfigOptions, INPUT_REDACT_PATHS, type Job, type JobErrorKind, type JobPayloadEnvelope, type JobStatus, type JobSubscriptionOptions, type JobUpdateCallbacks, JobWaitTimeoutError, KIND_APP_HANDLER, KIND_JOB_FEEDBACK, KIND_JOB_REQUEST, KIND_JOB_REQUEST_BASE, KIND_JOB_RESULT, KIND_JOB_RESULT_BASE, KIND_LONG_FORM_ARTICLE, KIND_PING, KIND_PONG, LAMPORTS_PER_SOL, LIMITS, MarketplaceService, MediaService, type Network, type NetworkBaselineEstimate, type NetworkBaselineOptions, type NetworkStats, type NetworkStatsResult, NostrPool, type OnchainNetworkStats, POLICY_D_TAG_PREFIX, POLICY_TYPE_REGEX, POLICY_T_TAG, PROTOCOL_PROGRAM_ID_DEVNET, type ParseOptions, type ParseResult, type ParsedPaymentRequest, type PaymentAssetRef, type PaymentInfo, type PaymentRequestData, PaymentRequestSchema, type PaymentStrategy, type PaymentValidationCode, type PaymentValidationError, type PingResult, PingService, PoliciesService, type PolicyInput, type ProtocolCluster, type ProtocolConfig, type ProtocolConfigInput, type QuickVerifyReason, type QuickVerifyResult, RELAYS, type RankKey, SECRET_REDACT_PATHS, type Signer, type SolFeeEstimate, SolanaPaymentStrategy, type SubCloser, type SubmitJobOptions, type VerifyOptions, type VerifyResult, aggregateNetworkStats, assertExpiry, assertLamports, buildPaymentInstructions, calculateProtocolFee, classifyJobError, clearPriorityFeeCache, clearProtocolConfigCache, clearQuickVerifyCache, compareAgentsByRank, computeRankKey, createPaymentRequestWithOnchainConfig, decodeJobPayload, encodeJobPayload, estimateNetworkBaseline, estimatePriorityFeeMicroLamports, estimateSolFeeLamports, formatFeeBreakdown, formatNetworkBaseline, formatSol, getNetworkStats, getProtocolConfig, getProtocolProgramId, jobRequestKind, jobResultKind, makeCensor, nip44Decrypt, nip44Encrypt, parsePaymentRequest, pickPercentileFee, timeAgo, toDTag, truncateKey, utf8ByteLength, validateAgentName, validateExpiry, verifyJobPaymentQuick };

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 import { Address, TransactionSigner, Rpc, SolanaRpcApi, Signature } from '@solana/kit';
+import { z } from 'zod';
 import { Filter, Event } from 'nostr-tools';
 import { A as Asset } from './assets-C-nzSYD4.js';
 export { C as Chain, K as KNOWN_ASSETS, N as NATIVE_SOL, U as USDC_SOLANA_DEVNET, a as assetByKey, b as assetKey, f as formatAssetAmount, p as parseAssetAmount, r as resolveAssetFromPaymentRequest, c as resolveKnownAsset } from './assets-C-nzSYD4.js';
-import { z } from 'zod';
-export { G as GlobalConfig, a as GlobalConfigSchema, S as SessionSpendLimitEntry, b as SessionSpendLimitEntrySchema } from './global-schema-CddHP2nk.js';
+export { G as GlobalConfig, a as GlobalConfigSchema, S as SessionSpendLimitEntry, b as SessionSpendLimitEntrySchema } from './global-schema-BsVFDtkt.js';
 export { R as RateLimitDecision, S as SlidingWindowLimiter, a as SlidingWindowLimiterOptions, c as createSlidingWindowLimiter } from './rateLimiter-CoEmZkSX.js';
 
 declare class ElisymIdentity {
@@ -23,6 +23,170 @@ declare class ElisymIdentity {
     static fromHex(hex: string): ElisymIdentity;
 }
 
+/**
+ * Job file-attachment descriptor and the job-payload envelope (browser-safe).
+ *
+ * A file job carries its file out-of-band (P2P via iroh); the Nostr event's
+ * (NIP-44-encrypted) `content` carries only a small JSON envelope describing the
+ * file and how to fetch it. This module owns the envelope shape, its encode, and
+ * its strict decode. It deliberately does NOT construct an iroh `BlobTicket` - the
+ * `ticket` is validated only as a bounded opaque string so that decoding an
+ * untrusted, possibly pre-payment request never pulls in the native iroh addon.
+ *
+ * The transport is a discriminated union keyed on `kind`; Phase 1 ships only
+ * `iroh`. A future HTTP/Blossom transport is added as another union member without
+ * changing this contract.
+ */
+
+/** Current envelope version. Bumped only on a breaking envelope-shape change. */
+declare const ENVELOPE_VERSION = "elisym-job/1";
+declare const FileTransportSchema: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+    kind: z.ZodLiteral<"iroh">;
+    /** Opaque iroh `BlobTicket` string. Parsed into a real ticket only at fetch time. */
+    ticket: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    kind: "iroh";
+    ticket: string;
+}, {
+    kind: "iroh";
+    ticket: string;
+}>]>;
+declare const FileAttachmentSchema: z.ZodObject<{
+    /** Display name only. Never used to derive a filesystem path (callers sanitize). */
+    name: z.ZodString;
+    /** Declared size in bytes (display/hint only; enforcement is on actual streamed bytes). */
+    size: z.ZodNumber;
+    mime: z.ZodString;
+    /** Ordered by sender preference; at least one. */
+    transports: z.ZodArray<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+        kind: z.ZodLiteral<"iroh">;
+        /** Opaque iroh `BlobTicket` string. Parsed into a real ticket only at fetch time. */
+        ticket: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        kind: "iroh";
+        ticket: string;
+    }, {
+        kind: "iroh";
+        ticket: string;
+    }>]>, "many">;
+    /** Optional provider hint (unix seconds) for when seeding may stop. */
+    seedingExpiresAt: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    size: number;
+    mime: string;
+    transports: {
+        kind: "iroh";
+        ticket: string;
+    }[];
+    seedingExpiresAt?: number | undefined;
+}, {
+    name: string;
+    size: number;
+    mime: string;
+    transports: {
+        kind: "iroh";
+        ticket: string;
+    }[];
+    seedingExpiresAt?: number | undefined;
+}>;
+declare const JobPayloadEnvelopeSchema: z.ZodObject<{
+    v: z.ZodLiteral<"elisym-job/1">;
+    text: z.ZodOptional<z.ZodString>;
+    attachment: z.ZodOptional<z.ZodObject<{
+        /** Display name only. Never used to derive a filesystem path (callers sanitize). */
+        name: z.ZodString;
+        /** Declared size in bytes (display/hint only; enforcement is on actual streamed bytes). */
+        size: z.ZodNumber;
+        mime: z.ZodString;
+        /** Ordered by sender preference; at least one. */
+        transports: z.ZodArray<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+            kind: z.ZodLiteral<"iroh">;
+            /** Opaque iroh `BlobTicket` string. Parsed into a real ticket only at fetch time. */
+            ticket: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            kind: "iroh";
+            ticket: string;
+        }, {
+            kind: "iroh";
+            ticket: string;
+        }>]>, "many">;
+        /** Optional provider hint (unix seconds) for when seeding may stop. */
+        seedingExpiresAt: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        size: number;
+        mime: string;
+        transports: {
+            kind: "iroh";
+            ticket: string;
+        }[];
+        seedingExpiresAt?: number | undefined;
+    }, {
+        name: string;
+        size: number;
+        mime: string;
+        transports: {
+            kind: "iroh";
+            ticket: string;
+        }[];
+        seedingExpiresAt?: number | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    v: "elisym-job/1";
+    text?: string | undefined;
+    attachment?: {
+        name: string;
+        size: number;
+        mime: string;
+        transports: {
+            kind: "iroh";
+            ticket: string;
+        }[];
+        seedingExpiresAt?: number | undefined;
+    } | undefined;
+}, {
+    v: "elisym-job/1";
+    text?: string | undefined;
+    attachment?: {
+        name: string;
+        size: number;
+        mime: string;
+        transports: {
+            kind: "iroh";
+            ticket: string;
+        }[];
+        seedingExpiresAt?: number | undefined;
+    } | undefined;
+}>;
+type FileTransport = z.infer<typeof FileTransportSchema>;
+type FileAttachment = z.infer<typeof FileAttachmentSchema>;
+type JobPayloadEnvelope = z.infer<typeof JobPayloadEnvelopeSchema>;
+/** Decoded job payload: a free-text note and/or a file attachment. */
+interface DecodedJobPayload {
+    text?: string;
+    attachment?: FileAttachment;
+}
+/**
+ * Serialize a job payload into the envelope string that goes (encrypted) into a
+ * Nostr event's `content`. Used only when an attachment is present; plain-text
+ * jobs send their text directly and are never wrapped.
+ */
+declare function encodeJobPayload(payload: DecodedJobPayload): string;
+/**
+ * Decode decrypted `content` into a job payload.
+ *
+ * - Content longer than `MAX_INPUT_LENGTH` is treated as raw text without parsing
+ *   (a valid envelope is small and a valid text job is capped at submit time), so
+ *   untrusted, possibly-huge intake content is never `JSON.parse`d unbounded.
+ * - Non-JSON, non-object JSON, or a JSON object that does not carry our
+ *   `elisym-job/` version marker is returned as raw text.
+ * - A value that DOES carry an `elisym-job/` marker is validated strictly: an
+ *   unknown version or a malformed envelope throws (callers skip/surface it)
+ *   rather than being silently mistreated as text.
+ */
+declare function decodeJobPayload(content: string): DecodedJobPayload;
+
 interface SubCloser {
     close: (reason?: string) => void;
 }
@@ -34,6 +198,16 @@ interface CapabilityCard {
     payment?: PaymentInfo;
     image?: string;
     static?: boolean;
+    /**
+     * MIME the capability expects as a file input (from a dynamic-script skill's
+     * `input_mime`). Discovery hint only; the provider still content-sniffs the
+     * actual file. Its presence means the capability needs a file input - which
+     * the web app cannot send (no iroh transport), so the web app blocks the Buy
+     * button. `*` = any file, `image/*` = any image, `image/png` = exact.
+     */
+    inputMime?: string;
+    /** MIME of a file result the capability produces (from `output_mime`). */
+    outputMime?: string;
 }
 /** Payment info embedded in capability card (legacy format for on-network events). */
 interface PaymentInfo {
@@ -139,17 +313,32 @@ interface Job {
     asset?: PaymentAssetRef;
 }
 interface SubmitJobOptions {
-    /** Job input text. Sent unencrypted if providerPubkey is not set. */
+    /**
+     * Job input text. Sent unencrypted if providerPubkey is not set. May be empty
+     * when `attachment` is set (a file-only job carries no text note).
+     */
     input: string;
     capability: string;
     /** Target provider pubkey. If omitted, job is broadcast unencrypted and visible to all relays. */
     providerPubkey?: string;
     /** Kind offset (default 100 - kind 5100). */
     kindOffset?: number;
+    /**
+     * Optional file attachment. When set, `input` (as the text note) and the
+     * attachment are wrapped in a job-payload envelope before encryption. The file
+     * itself travels out-of-band (P2P via iroh), not in the Nostr event.
+     */
+    attachment?: FileAttachment;
 }
 interface JobUpdateCallbacks {
     onFeedback?: (status: string, amount?: number, paymentRequest?: string, senderPubkey?: string) => void;
-    onResult?: (content: string, eventId: string) => void;
+    /**
+     * Fired on a job result. `content` is the result text (for a file result, the
+     * envelope's text note, or `''`); `attachment` is the file descriptor when the
+     * result carries a file. The file is fetched separately (P2P via iroh), never
+     * inlined here.
+     */
+    onResult?: (content: string, eventId: string, attachment?: FileAttachment) => void;
     onError?: (error: string) => void;
     /**
      * Fired when the result wait window expires without a result - a distinct,
@@ -536,14 +725,14 @@ declare class MarketplaceService {
      */
     subscribeToJobRequests(identity: ElisymIdentity, kinds: number[], onRequest: (event: Event) => void): SubCloser;
     /** Submit a job result with NIP-44 encrypted content. Result kind is derived from the request kind. */
-    submitJobResult(identity: ElisymIdentity, requestEvent: Event, content: string, amount?: number): Promise<string>;
+    submitJobResult(identity: ElisymIdentity, requestEvent: Event, content: string, amount?: number, attachment?: FileAttachment): Promise<string>;
     /**
      * Submit a job result with retry and exponential backoff.
      * Retries on publish failures (e.g. relay disconnects).
      * With maxAttempts=3: try, ~1s, try, ~2s, try, throw.
      * Jitter: 0.5x-1.0x of calculated delay.
      */
-    submitJobResultWithRetry(identity: ElisymIdentity, requestEvent: Event, content: string, amount?: number, maxAttempts?: number, baseDelayMs?: number): Promise<string>;
+    submitJobResultWithRetry(identity: ElisymIdentity, requestEvent: Event, content: string, amount?: number, maxAttempts?: number, baseDelayMs?: number, attachment?: FileAttachment): Promise<string>;
     /** Submit payment-required feedback with a payment request. */
     submitPaymentRequiredFeedback(identity: ElisymIdentity, requestEvent: Event, amount: number, paymentRequestJson: string): Promise<void>;
     /** Submit processing feedback to notify customer that work has started. */
@@ -1053,7 +1242,16 @@ declare function parsePaymentRequest(input: string, options?: ParseOptions): Par
  */
 type QuickVerifyReason = 'not_found' | 'tx_failed' | 'recipient_mismatch' | 'rpc_error' | 'invalid_input';
 interface QuickVerifyResult {
-    verified: boolean;
+    /**
+     * True when the recipient address received funds in this transaction.
+     *
+     * NOTE: this is NOT proof of a valid elisym job payment. It does not check
+     * the payment `reference` key or that the amount matches the job price - it
+     * is a best-effort signal for the fast discovery-ranking path, where the
+     * original payment request is unavailable. For an authoritative check
+     * (amount + reference) use `SolanaPaymentStrategy.verifyPayment`.
+     */
+    receivedFunds: boolean;
     txSignature: string;
     reason?: QuickVerifyReason;
 }
@@ -1105,6 +1303,12 @@ declare function aggregateNetworkStats(rpc: Rpc<SolanaRpcApi>, options?: Aggrega
  * Returns `null` when the PDA has not been initialized yet (admin must call
  * `initialize_stats` once after program upgrade).
  */
+/**
+ * Best-effort network counters read from the on-chain PDA. These are NOT bound
+ * to verified transfers and can be inflated by a malicious caller, so present
+ * them as approximate/unverified, never as authoritative proof of activity. For
+ * a transfer-derived figure use `aggregateNetworkStats`.
+ */
 interface OnchainNetworkStats {
     jobCount: number;
     volumeNative: bigint;
@@ -1273,10 +1477,15 @@ declare const DEFAULTS: {
     readonly RESULT_RETRY_BASE_MS: 1000;
     readonly QUERY_MAX_CONCURRENCY: 6;
     readonly VERIFY_SIGNATURE_LIMIT: 25;
+    readonly IROH_FETCH_TIMEOUT_MS: 300000;
 };
 /** Protocol limits for input validation. */
 declare const LIMITS: {
     readonly MAX_INPUT_LENGTH: 100000;
+    readonly NIP44_MAX_PLAINTEXT_BYTES: 65535;
+    readonly MAX_ENCRYPTED_INLINE_BYTES: 60000;
+    readonly MAX_REINLINE_TEXT_BYTES: 4194304;
+    readonly MAX_FILE_SIZE: 1073741824;
     readonly MAX_TIMEOUT_SECS: 600;
     readonly MAX_EXECUTION_SECS: 2147483;
     readonly MAX_CAPABILITIES: 20;
@@ -1290,5 +1499,11 @@ declare const LIMITS: {
     readonly MAX_POLICY_SUMMARY_LENGTH: 280;
     readonly MAX_POLICY_VERSION_LENGTH: 32;
 };
+/**
+ * UTF-8 byte length of a string. All size guards on encrypted content measure
+ * BYTES, not `String.length` (UTF-16 code units): NIP-44's plaintext cap is a
+ * byte cap, so a multibyte string under the char cap can still exceed it.
+ */
+declare function utf8ByteLength(value: string): number;
 
-export { type Agent, type AgentPolicy, type AggregateNetworkStatsOptions, Asset, BoundedSet, type BuildTransactionOptions, type CapabilityCard, DEFAULTS, DEFAULT_KIND_OFFSET, DEFAULT_REDACT_PATHS, DiscoveryService, ELISYM_PROTOCOL_TAG, ElisymClient, type ElisymClientConfig, type ElisymClientFullConfig, ElisymIdentity, type EstimatePriorityFeeOptions, type EstimateSolFeeOptions, type GetProtocolConfigOptions, INPUT_REDACT_PATHS, type Job, type JobErrorKind, type JobStatus, type JobSubscriptionOptions, type JobUpdateCallbacks, JobWaitTimeoutError, KIND_APP_HANDLER, KIND_JOB_FEEDBACK, KIND_JOB_REQUEST, KIND_JOB_REQUEST_BASE, KIND_JOB_RESULT, KIND_JOB_RESULT_BASE, KIND_LONG_FORM_ARTICLE, KIND_PING, KIND_PONG, LAMPORTS_PER_SOL, LIMITS, MarketplaceService, MediaService, type Network, type NetworkBaselineEstimate, type NetworkBaselineOptions, type NetworkStats, type NetworkStatsResult, NostrPool, type OnchainNetworkStats, POLICY_D_TAG_PREFIX, POLICY_TYPE_REGEX, POLICY_T_TAG, PROTOCOL_PROGRAM_ID_DEVNET, type ParseOptions, type ParseResult, type ParsedPaymentRequest, type PaymentAssetRef, type PaymentInfo, type PaymentRequestData, PaymentRequestSchema, type PaymentStrategy, type PaymentValidationCode, type PaymentValidationError, type PingResult, PingService, PoliciesService, type PolicyInput, type ProtocolCluster, type ProtocolConfig, type ProtocolConfigInput, type QuickVerifyReason, type QuickVerifyResult, RELAYS, type RankKey, SECRET_REDACT_PATHS, type Signer, type SolFeeEstimate, SolanaPaymentStrategy, type SubCloser, type SubmitJobOptions, type VerifyOptions, type VerifyResult, aggregateNetworkStats, assertExpiry, assertLamports, buildPaymentInstructions, calculateProtocolFee, classifyJobError, clearPriorityFeeCache, clearProtocolConfigCache, clearQuickVerifyCache, compareAgentsByRank, computeRankKey, createPaymentRequestWithOnchainConfig, estimateNetworkBaseline, estimatePriorityFeeMicroLamports, estimateSolFeeLamports, formatFeeBreakdown, formatNetworkBaseline, formatSol, getNetworkStats, getProtocolConfig, getProtocolProgramId, jobRequestKind, jobResultKind, makeCensor, nip44Decrypt, nip44Encrypt, parsePaymentRequest, pickPercentileFee, timeAgo, toDTag, truncateKey, validateAgentName, validateExpiry, verifyJobPaymentQuick };
+export { type Agent, type AgentPolicy, type AggregateNetworkStatsOptions, Asset, BoundedSet, type BuildTransactionOptions, type CapabilityCard, DEFAULTS, DEFAULT_KIND_OFFSET, DEFAULT_REDACT_PATHS, type DecodedJobPayload, DiscoveryService, ELISYM_PROTOCOL_TAG, ENVELOPE_VERSION, ElisymClient, type ElisymClientConfig, type ElisymClientFullConfig, ElisymIdentity, type EstimatePriorityFeeOptions, type EstimateSolFeeOptions, type FileAttachment, type FileTransport, type GetProtocolConfigOptions, INPUT_REDACT_PATHS, type Job, type JobErrorKind, type JobPayloadEnvelope, type JobStatus, type JobSubscriptionOptions, type JobUpdateCallbacks, JobWaitTimeoutError, KIND_APP_HANDLER, KIND_JOB_FEEDBACK, KIND_JOB_REQUEST, KIND_JOB_REQUEST_BASE, KIND_JOB_RESULT, KIND_JOB_RESULT_BASE, KIND_LONG_FORM_ARTICLE, KIND_PING, KIND_PONG, LAMPORTS_PER_SOL, LIMITS, MarketplaceService, MediaService, type Network, type NetworkBaselineEstimate, type NetworkBaselineOptions, type NetworkStats, type NetworkStatsResult, NostrPool, type OnchainNetworkStats, POLICY_D_TAG_PREFIX, POLICY_TYPE_REGEX, POLICY_T_TAG, PROTOCOL_PROGRAM_ID_DEVNET, type ParseOptions, type ParseResult, type ParsedPaymentRequest, type PaymentAssetRef, type PaymentInfo, type PaymentRequestData, PaymentRequestSchema, type PaymentStrategy, type PaymentValidationCode, type PaymentValidationError, type PingResult, PingService, PoliciesService, type PolicyInput, type ProtocolCluster, type ProtocolConfig, type ProtocolConfigInput, type QuickVerifyReason, type QuickVerifyResult, RELAYS, type RankKey, SECRET_REDACT_PATHS, type Signer, type SolFeeEstimate, SolanaPaymentStrategy, type SubCloser, type SubmitJobOptions, type VerifyOptions, type VerifyResult, aggregateNetworkStats, assertExpiry, assertLamports, buildPaymentInstructions, calculateProtocolFee, classifyJobError, clearPriorityFeeCache, clearProtocolConfigCache, clearQuickVerifyCache, compareAgentsByRank, computeRankKey, createPaymentRequestWithOnchainConfig, decodeJobPayload, encodeJobPayload, estimateNetworkBaseline, estimatePriorityFeeMicroLamports, estimateSolFeeLamports, formatFeeBreakdown, formatNetworkBaseline, formatSol, getNetworkStats, getProtocolConfig, getProtocolProgramId, jobRequestKind, jobResultKind, makeCensor, nip44Decrypt, nip44Encrypt, parsePaymentRequest, pickPercentileFee, timeAgo, toDTag, truncateKey, utf8ByteLength, validateAgentName, validateExpiry, verifyJobPaymentQuick };