@elisym/sdk 0.4.1 → 0.6.0

package/dist/index.d.cts

@@ -1,8 +1,157 @@
 import { Address, TransactionSigner, Rpc, SolanaRpcApi } from '@solana/kit';
-import { P as PaymentRequestData, a as PaymentValidationError, V as VerifyOptions, b as VerifyResult, S as SubCloser, N as Network, A as Agent, E as ElisymIdentity, C as CapabilityCard, c as SubmitJobOptions, J as JobSubscriptionOptions, d as Job, e as PingResult, f as ElisymClientConfig, g as AgentConfig } from './types-CII4k_8d.cjs';
-export { h as Capability, I as Identity, i as JobStatus, j as JobUpdateCallbacks, L as LlmConfig, k as NetworkStats, l as PaymentAddress, m as PaymentInfo, n as PaymentValidationCode, W as WalletConfig } from './types-CII4k_8d.cjs';
 import { Filter, Event } from 'nostr-tools';
+import { z } from 'zod';
+
+declare class ElisymIdentity {
+    private _secretKey;
+    readonly publicKey: string;
+    readonly npub: string;
+    get secretKey(): Uint8Array;
+    private constructor();
+    static generate(): ElisymIdentity;
+    static fromSecretKey(sk: Uint8Array): ElisymIdentity;
+    toJSON(): {
+        publicKey: string;
+        npub: string;
+    };
+    /** Best-effort scrub of the secret key bytes in memory. */
+    scrub(): void;
+    static fromHex(hex: string): ElisymIdentity;
+}
+
+interface SubCloser {
+    close: (reason?: string) => void;
+}
+/** Capability card published to Nostr (NIP-89). */
+interface CapabilityCard {
+    name: string;
+    description: string;
+    capabilities: string[];
+    payment?: PaymentInfo;
+    image?: string;
+    static?: boolean;
+}
+/** Payment info embedded in capability card (legacy format for on-network events). */
+interface PaymentInfo {
+    chain: string;
+    network: string;
+    address: string;
+    /** Price in lamports (must be non-negative integer). */
+    job_price?: number;
+}
+/** Agent discovered from the network. */
+interface Agent {
+    pubkey: string;
+    npub: string;
+    cards: CapabilityCard[];
+    eventId: string;
+    supportedKinds: number[];
+    lastSeen: number;
+    picture?: string;
+    name?: string;
+    about?: string;
+}
+type Network = 'mainnet' | 'devnet';
+/**
+ * Job lifecycle status.
+ * Note: for broadcast jobs (no providerPubkey, no bid), fetchRecentJobs() keeps
+ * status as 'processing' even if a provider sent 'payment-required' feedback,
+ * because the customer hasn't committed to that provider yet. The real-time
+ * payment-required transition is handled by subscribeToJobUpdates().
+ */
+type JobStatus = 'payment-required' | 'payment-completed' | 'processing' | 'error' | 'success' | 'partial' | 'unknown';
+interface Job {
+    eventId: string;
+    customer: string;
+    agentPubkey?: string;
+    capability?: string;
+    bid?: number;
+    status: JobStatus;
+    result?: string;
+    resultEventId?: string;
+    amount?: number;
+    txHash?: string;
+    createdAt: number;
+}
+interface SubmitJobOptions {
+    /** Job input text. Sent unencrypted if providerPubkey is not set. */
+    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;
+}
+interface JobUpdateCallbacks {
+    onFeedback?: (status: string, amount?: number, paymentRequest?: string, senderPubkey?: string) => void;
+    onResult?: (content: string, eventId: string) => void;
+    onError?: (error: string) => void;
+}
+interface JobSubscriptionOptions {
+    jobEventId: string;
+    providerPubkey?: string;
+    customerPublicKey: string;
+    callbacks: JobUpdateCallbacks;
+    timeoutMs?: number;
+    customerSecretKey?: Uint8Array;
+    kindOffsets?: number[];
+    sinceOverride?: number;
+}
+interface PingResult {
+    online: boolean;
+    /** The identity used for the ping session - reuse for job submission so pubkeys match. */
+    identity: ElisymIdentity | null;
+}
+interface PaymentRequestData {
+    recipient: string;
+    /** Total amount in lamports (must be positive integer). */
+    amount: number;
+    reference: string;
+    description?: string;
+    fee_address?: string;
+    fee_amount?: number;
+    /** Creation timestamp (Unix seconds). */
+    created_at: number;
+    /** Expiry duration in seconds. */
+    expiry_secs: number;
+}
+interface VerifyResult {
+    verified: boolean;
+    txSignature?: string;
+    error?: string;
+}
+interface VerifyOptions {
+    retries?: number;
+    intervalMs?: number;
+    txSignature?: string;
+}
+type PaymentValidationCode = 'invalid_json' | 'invalid_amount' | 'missing_recipient' | 'invalid_recipient_address' | 'missing_reference' | 'invalid_reference_address' | 'recipient_mismatch' | 'expired' | 'future_timestamp' | 'fee_address_mismatch' | 'fee_amount_mismatch' | 'missing_fee' | 'invalid_fee_params';
+interface PaymentValidationError {
+    code: PaymentValidationCode;
+    message: string;
+}
+interface NetworkStats {
+    totalAgentCount: number;
+    agentCount: number;
+    jobCount: number;
+    totalLamports: number;
+}
+interface ElisymClientConfig {
+    relays?: string[];
+}
 
+/**
+ * Pluggable signer used by `PaymentStrategy.buildTransaction`.
+ *
+ * Aliased to Solana Kit's `TransactionSigner` so callers can pass a hot
+ * `KeyPairSigner`, an external KMS-backed signer, a hardware-wallet adapter,
+ * or any other implementation that conforms to the Solana Kit signer contract
+ * (TransactionPartialSigner / TransactionSendingSigner / TransactionModifyingSigner).
+ *
+ * Exposing the alias here lets downstream packages depend on `@elisym/sdk`'s
+ * abstraction instead of importing Kit directly when wiring custom signers.
+ */
+type Signer = TransactionSigner;
 /**
  * Protocol fee + treasury inputs for building a payment request.
  *
@@ -37,18 +186,54 @@ interface PaymentStrategy {
      * Validate that a payment request has the correct recipient and protocol fee.
      * Returns a typed validation error if invalid, null if OK.
      */
-    validatePaymentRequest(requestJson: string, config: ProtocolConfigInput, expectedRecipient?: string): PaymentValidationError | null;
+    validatePaymentRequest(requestJson: string, config: ProtocolConfigInput, expectedRecipient?: string, options?: {
+        maxAmountLamports?: bigint;
+    }): PaymentValidationError | null;
     /**
-     * Build and sign a transaction from a payment request using a TransactionSigner.
-     * Returns a chain-specific signed transaction value. The caller is responsible
-     * for sending it (e.g. via `rpc.sendTransaction(...).send()`).
+     * Build and sign a transaction from a payment request using a `Signer`.
+     *
+     * The `Signer` parameter is intentionally the abstract interface, not a
+     * concrete `KeyPairSigner`, so callers can plug in external signers
+     * (KMS, hardware wallet, ElizaOS approval Action) without holding the
+     * raw secret key in process memory.
+     *
+     * Returns a chain-specific signed transaction value. The caller is
+     * responsible for sending it (e.g. via `rpc.sendTransaction(...).send()`).
      */
-    buildTransaction(paymentRequest: PaymentRequestData, payerSigner: TransactionSigner, rpc: Rpc<SolanaRpcApi>, config: ProtocolConfigInput): Promise<unknown>;
+    buildTransaction(paymentRequest: PaymentRequestData, payerSigner: Signer, rpc: Rpc<SolanaRpcApi>, config: ProtocolConfigInput, options?: BuildTransactionOptions): Promise<unknown>;
     /**
      * Verify a payment on-chain.
      */
     verifyPayment(rpc: Rpc<SolanaRpcApi>, paymentRequest: PaymentRequestData, config: ProtocolConfigInput, options?: VerifyOptions): Promise<VerifyResult>;
 }
+/**
+ * Optional knobs for `PaymentStrategy.buildTransaction`.
+ *
+ * Defaults are chosen for typical Solana mainnet conditions; override these
+ * when the caller knows peak fees are elevated, when running against a
+ * private cluster with no priority-fee samples, or when bundling multiple
+ * payment instructions.
+ */
+interface BuildTransactionOptions {
+    /**
+     * Compute-unit limit attached to the transaction. Defaults to 200 000 -
+     * comfortable headroom for two SystemProgram transfers + a few extra ops.
+     */
+    computeUnitLimit?: number;
+    /**
+     * Per-CU priority-fee override in microLamports. When omitted, the
+     * strategy queries `getRecentPrioritizationFees`, sorts by percentile, and
+     * uses that value (cached for 10s). Pass an explicit value to skip the
+     * RPC call or override the percentile heuristic during traffic spikes.
+     */
+    priorityFeeMicroLamports?: bigint;
+    /**
+     * Percentile of the recent priority-fee distribution to charge when
+     * `priorityFeeMicroLamports` is not supplied. 50 = median, 75 = upper
+     * quartile (default), 90 = aggressive.
+     */
+    priorityFeePercentile?: number;
+}
 
 declare class NostrPool {
     private pool;
@@ -288,7 +473,9 @@ declare class SolanaPaymentStrategy implements PaymentStrategy {
     createPaymentRequest(recipientAddress: string, amount: number, config: ProtocolConfigInput, options?: {
         expirySecs?: number;
     }): PaymentRequestData;
-    validatePaymentRequest(requestJson: string, config: ProtocolConfigInput, expectedRecipient?: string): PaymentValidationError | null;
+    validatePaymentRequest(requestJson: string, config: ProtocolConfigInput, expectedRecipient?: string, options?: {
+        maxAmountLamports?: bigint;
+    }): PaymentValidationError | null;
     /**
      * Build, sign, and return a transaction for the supplied payment request.
      * The caller is responsible for sending it (e.g. via `rpc.sendTransaction`).
@@ -297,7 +484,7 @@ declare class SolanaPaymentStrategy implements PaymentStrategy {
      * read-only, non-signer account so providers can detect the payment via
      * `getSignaturesForAddress(reference)`.
      */
-    buildTransaction(paymentRequest: PaymentRequestData, payerSigner: TransactionSigner, rpc: Rpc<SolanaRpcApi>, config: ProtocolConfigInput): Promise<Readonly<unknown>>;
+    buildTransaction(paymentRequest: PaymentRequestData, payerSigner: Signer, rpc: Rpc<SolanaRpcApi>, config: ProtocolConfigInput, options?: BuildTransactionOptions): Promise<Readonly<unknown>>;
     verifyPayment(rpc: Rpc<SolanaRpcApi>, paymentRequest: PaymentRequestData, config: ProtocolConfigInput, options?: VerifyOptions): Promise<VerifyResult>;
     private _verifyBySignature;
     private _verifyByReference;
@@ -312,7 +499,7 @@ declare class SolanaPaymentStrategy implements PaymentStrategy {
  * Caller is responsible for validating `paymentRequest` upstream;
  * `buildTransaction` already does that before invoking this helper.
  */
-declare function buildPaymentInstructions(paymentRequest: PaymentRequestData, payerSigner: TransactionSigner): readonly unknown[];
+declare function buildPaymentInstructions(paymentRequest: PaymentRequestData, payerSigner: Signer): readonly unknown[];
 /**
  * Convenience wrapper: fetch the on-chain protocol config first, then build a
  * payment request using its current fee/treasury values.
@@ -342,6 +529,101 @@ declare function validateExpiry(createdAt: number, expirySecs: number): string |
 /** Assert that payment request timestamps are valid and not expired. Throws on failure. */
 declare function assertExpiry(createdAt: number, expirySecs: number): void;
 
+interface EstimatePriorityFeeOptions {
+    /**
+     * Percentile of the recent prioritization-fee distribution to charge.
+     * 50 = median, 75 = upper quartile, 90 = aggressive. Defaults to 75.
+     */
+    percentile?: number;
+    /**
+     * Cache window in milliseconds. Subsequent calls within this window with the
+     * same accounts will return the cached value. Defaults to 10s.
+     */
+    ttlMs?: number;
+    /**
+     * Optional account list passed to `getRecentPrioritizationFees` so the node
+     * returns fees observed on writes touching these accounts. Empty = global.
+     */
+    accounts?: readonly Address[];
+}
+/**
+ * Estimate a per-compute-unit priority fee from recent blocks, in
+ * microLamports (1 microLamport = 0.000001 Lamports).
+ *
+ * Falls back to a 1000 microLamport floor when the RPC returns no samples
+ * (typical on private clusters or under maintenance). Negative percentiles
+ * are clamped to the median.
+ *
+ * Cached per accounts-key for `ttlMs` (default 10s) using the same
+ * in-process cache pattern as `getProtocolConfig`.
+ */
+declare function estimatePriorityFeeMicroLamports(rpc: Rpc<SolanaRpcApi>, options?: EstimatePriorityFeeOptions): Promise<bigint>;
+declare function clearPriorityFeeCache(): void;
+interface RecentPrioritizationFeeLike {
+    prioritizationFee: bigint | number;
+    slot?: bigint | number;
+}
+declare function pickPercentileFee(samples: readonly RecentPrioritizationFeeLike[], percentile: number): bigint;
+
+/**
+ * Wire-shape for a NIP-90 payment_request blob, as parsed via JSON.parse.
+ *
+ * Stricter than the loose TypeScript interface: rejects negative amounts,
+ * floats, NaN/Infinity, mistyped recipient/reference, and any expiry
+ * outside `[1, LIMITS.MAX_TIMEOUT_SECS]`. The strategy applies semantic
+ * checks (recipient match, fee amount, expiry-vs-now) on top of this.
+ */
+declare const PaymentRequestSchema: z.ZodObject<{
+    recipient: z.ZodString;
+    amount: z.ZodNumber;
+    reference: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    fee_address: z.ZodOptional<z.ZodString>;
+    fee_amount: z.ZodOptional<z.ZodNumber>;
+    created_at: z.ZodNumber;
+    expiry_secs: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    recipient: string;
+    amount: number;
+    reference: string;
+    created_at: number;
+    expiry_secs: number;
+    description?: string | undefined;
+    fee_address?: string | undefined;
+    fee_amount?: number | undefined;
+}, {
+    recipient: string;
+    amount: number;
+    reference: string;
+    created_at: number;
+    expiry_secs: number;
+    description?: string | undefined;
+    fee_address?: string | undefined;
+    fee_amount?: number | undefined;
+}>;
+type ParsedPaymentRequest = z.infer<typeof PaymentRequestSchema>;
+interface ParseOptions {
+    /** Optional max amount cap (lamports). Rejects requests that exceed it. */
+    maxAmountLamports?: bigint;
+}
+interface ParseError {
+    code: 'invalid_json' | 'schema' | 'amount_exceeds_max';
+    message: string;
+}
+type ParseResult = {
+    ok: true;
+    data: ParsedPaymentRequest;
+} | {
+    ok: false;
+    error: ParseError;
+};
+/**
+ * Parse a JSON-encoded payment request through the Zod schema, optionally
+ * enforcing a `maxAmountLamports` ceiling supplied by the caller (e.g. the
+ * customer's per-job spending cap).
+ */
+declare function parsePaymentRequest(input: string, options?: ParseOptions): ParseResult;
+
 /**
  * Snapshot of the on-chain elisym-config program state.
  *
@@ -386,14 +668,10 @@ declare function timeAgo(unix: number): string;
 declare function truncateKey(hex: string, chars?: number): string;
 
 /**
- * Shared agent config - validation and serialization.
+ * Agent-name validation shared between CLI and MCP.
  * Browser-safe - no Node.js imports.
- * parseConfig lives in config-node.ts (exported from @elisym/sdk/node).
  */
-
 declare function validateAgentName(name: string): void;
-/** Serialize an AgentConfig to JSON string. */
-declare function serializeConfig(config: AgentConfig): string;
 
 /** A Set that evicts the oldest entries when it exceeds maxSize. Uses a ring buffer for O(1) eviction. */
 declare class BoundedSet<T> {
@@ -482,4 +760,4 @@ declare const LIMITS: {
     readonly MAX_CAPABILITY_LENGTH: 64;
 };
 
-export { Agent, AgentConfig, BoundedSet, CapabilityCard, DEFAULTS, DEFAULT_KIND_OFFSET, DiscoveryService, ElisymClient, ElisymClientConfig, type ElisymClientFullConfig, ElisymIdentity, type GetProtocolConfigOptions, Job, JobSubscriptionOptions, KIND_APP_HANDLER, KIND_JOB_FEEDBACK, KIND_JOB_REQUEST, KIND_JOB_REQUEST_BASE, KIND_JOB_RESULT, KIND_JOB_RESULT_BASE, KIND_PING, KIND_PONG, LAMPORTS_PER_SOL, LIMITS, MarketplaceService, MediaService, Network, NostrPool, PROTOCOL_FEE_BPS, PROTOCOL_PROGRAM_ID_DEVNET, PROTOCOL_TREASURY, PaymentRequestData, type PaymentStrategy, PaymentValidationError, PingResult, PingService, type ProtocolCluster, type ProtocolConfig, type ProtocolConfigInput, RELAYS, SolanaPaymentStrategy, SubCloser, SubmitJobOptions, VerifyOptions, VerifyResult, assertExpiry, assertLamports, buildPaymentInstructions, calculateProtocolFee, clearProtocolConfigCache, createPaymentRequestWithOnchainConfig, formatSol, getProtocolConfig, getProtocolProgramId, jobRequestKind, jobResultKind, nip44Decrypt, nip44Encrypt, serializeConfig, timeAgo, toDTag, truncateKey, validateAgentName, validateExpiry };
+export { type Agent, BoundedSet, type BuildTransactionOptions, type CapabilityCard, DEFAULTS, DEFAULT_KIND_OFFSET, DiscoveryService, ElisymClient, type ElisymClientConfig, type ElisymClientFullConfig, ElisymIdentity, type EstimatePriorityFeeOptions, type GetProtocolConfigOptions, type Job, type JobStatus, type JobSubscriptionOptions, type JobUpdateCallbacks, KIND_APP_HANDLER, KIND_JOB_FEEDBACK, KIND_JOB_REQUEST, KIND_JOB_REQUEST_BASE, KIND_JOB_RESULT, KIND_JOB_RESULT_BASE, KIND_PING, KIND_PONG, LAMPORTS_PER_SOL, LIMITS, MarketplaceService, MediaService, type Network, type NetworkStats, NostrPool, PROTOCOL_FEE_BPS, PROTOCOL_PROGRAM_ID_DEVNET, PROTOCOL_TREASURY, type ParseOptions, type ParseResult, type ParsedPaymentRequest, type PaymentInfo, type PaymentRequestData, PaymentRequestSchema, type PaymentStrategy, type PaymentValidationCode, type PaymentValidationError, type PingResult, PingService, type ProtocolCluster, type ProtocolConfig, type ProtocolConfigInput, RELAYS, type Signer, SolanaPaymentStrategy, type SubCloser, type SubmitJobOptions, type VerifyOptions, type VerifyResult, assertExpiry, assertLamports, buildPaymentInstructions, calculateProtocolFee, clearPriorityFeeCache, clearProtocolConfigCache, createPaymentRequestWithOnchainConfig, estimatePriorityFeeMicroLamports, formatSol, getProtocolConfig, getProtocolProgramId, jobRequestKind, jobResultKind, nip44Decrypt, nip44Encrypt, parsePaymentRequest, pickPercentileFee, timeAgo, toDTag, truncateKey, validateAgentName, validateExpiry };