@elisym/sdk 0.5.0 → 0.7.0

package/dist/index.d.cts

@@ -1,5 +1,6 @@
 import { Address, TransactionSigner, Rpc, SolanaRpcApi } from '@solana/kit';
 import { Filter, Event } from 'nostr-tools';
+import { z } from 'zod';
 
 declare class ElisymIdentity {
     private _secretKey;
@@ -139,6 +140,18 @@ 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.
  *
@@ -173,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;
@@ -424,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`).
@@ -433,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;
@@ -448,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.
@@ -478,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.
  *
@@ -539,6 +685,82 @@ declare class BoundedSet<T> {
     add(item: T): void;
 }
 
+/**
+ * Sliding-window rate limiter keyed by an arbitrary string (typically a
+ * customer pubkey). Each key gets at most `maxPerWindow` requests inside a
+ * rolling `windowMs`. Stale timestamps are pruned lazily on every `check`.
+ * When the tracked-key set grows past `maxKeys`, the least-recently-used
+ * key is evicted so an attacker cannot exhaust memory by cycling keys.
+ *
+ * Thread-safety: not required. Designed for single-threaded JS consumers
+ * (Node/Bun event loops, browser main thread). No timers - pruning happens
+ * inside `check` and `prune`.
+ */
+interface SlidingWindowLimiterOptions {
+    /** Rolling window width, in ms. */
+    windowMs: number;
+    /** Max hits allowed per key inside the window. */
+    maxPerWindow: number;
+    /** Cap on total tracked keys. LRU-evicted past this cap. */
+    maxKeys: number;
+}
+interface RateLimitDecision {
+    allowed: boolean;
+    /** Wall-clock timestamp (ms) when the limit window will reset for this key. */
+    resetAt: number;
+    /** Number of hits inside the current window after this call (or the attempted hit if denied). */
+    count: number;
+}
+interface SlidingWindowLimiter {
+    /** Record a hit against `key`; return whether it was allowed. */
+    check(key: string, now?: number): RateLimitDecision;
+    /**
+     * Inspect the current state for `key` without recording a hit. Useful
+     * when a single request must clear multiple limiters and callers want
+     * to avoid double-counting against one limiter after another denies.
+     */
+    peek(key: string, now?: number): RateLimitDecision;
+    /** Drop entries whose windows have fully elapsed. Bounded memory hygiene. */
+    prune(now?: number): void;
+    /** Current number of tracked keys. */
+    size(): number;
+    /** Clear all state. */
+    reset(): void;
+}
+declare function createSlidingWindowLimiter(options: SlidingWindowLimiterOptions): SlidingWindowLimiter;
+
+/**
+ * Canonical pino redact paths for the elisym stack. Plugin, CLI, MCP, and
+ * any downstream integrator should consume these arrays directly - one
+ * source of truth for "fields that carry user input or secrets".
+ *
+ * Wire them into a pino instance like:
+ *
+ *   import pino from 'pino';
+ *   import { DEFAULT_REDACT_PATHS, makeCensor } from '@elisym/sdk';
+ *   const logger = pino({
+ *     redact: { paths: DEFAULT_REDACT_PATHS, censor: makeCensor() },
+ *   });
+ */
+/**
+ * Field paths that carry Nostr / Solana secret keys or operator secrets.
+ * Censored as `[REDACTED]`.
+ */
+declare const SECRET_REDACT_PATHS: string[];
+/**
+ * Field paths that carry customer-confidential text (LLM prompts, raw
+ * event content, job input). Censored as `[INPUT REDACTED]` so log
+ * readers can distinguish redacted input from redacted secrets.
+ */
+declare const INPUT_REDACT_PATHS: string[];
+/**
+ * Union of the two arrays, in the order pino's redact engine should
+ * visit them. Prefer this when wiring a new logger so no downstream
+ * consumer forgets half the set.
+ */
+declare const DEFAULT_REDACT_PATHS: string[];
+declare function makeCensor(): (value: unknown, path: string[]) => string;
+
 declare const RELAYS: string[];
 declare const KIND_APP_HANDLER = 31990;
 declare const KIND_JOB_REQUEST_BASE = 5000;
@@ -614,4 +836,4 @@ declare const LIMITS: {
     readonly MAX_CAPABILITY_LENGTH: 64;
 };
 
-export { type Agent, BoundedSet, type CapabilityCard, DEFAULTS, DEFAULT_KIND_OFFSET, DiscoveryService, ElisymClient, type ElisymClientConfig, type ElisymClientFullConfig, ElisymIdentity, 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 PaymentInfo, type PaymentRequestData, type PaymentStrategy, type PaymentValidationCode, type PaymentValidationError, type PingResult, PingService, type ProtocolCluster, type ProtocolConfig, type ProtocolConfigInput, RELAYS, SolanaPaymentStrategy, type SubCloser, type SubmitJobOptions, type VerifyOptions, type VerifyResult, assertExpiry, assertLamports, buildPaymentInstructions, calculateProtocolFee, clearProtocolConfigCache, createPaymentRequestWithOnchainConfig, formatSol, getProtocolConfig, getProtocolProgramId, jobRequestKind, jobResultKind, nip44Decrypt, nip44Encrypt, timeAgo, toDTag, truncateKey, validateAgentName, validateExpiry };
+export { type Agent, BoundedSet, type BuildTransactionOptions, type CapabilityCard, DEFAULTS, DEFAULT_KIND_OFFSET, DEFAULT_REDACT_PATHS, DiscoveryService, ElisymClient, type ElisymClientConfig, type ElisymClientFullConfig, ElisymIdentity, type EstimatePriorityFeeOptions, type GetProtocolConfigOptions, INPUT_REDACT_PATHS, 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 RateLimitDecision, SECRET_REDACT_PATHS, type Signer, type SlidingWindowLimiter, type SlidingWindowLimiterOptions, SolanaPaymentStrategy, type SubCloser, type SubmitJobOptions, type VerifyOptions, type VerifyResult, assertExpiry, assertLamports, buildPaymentInstructions, calculateProtocolFee, clearPriorityFeeCache, clearProtocolConfigCache, createPaymentRequestWithOnchainConfig, createSlidingWindowLimiter, estimatePriorityFeeMicroLamports, formatSol, getProtocolConfig, getProtocolProgramId, jobRequestKind, jobResultKind, makeCensor, nip44Decrypt, nip44Encrypt, parsePaymentRequest, pickPercentileFee, timeAgo, toDTag, truncateKey, validateAgentName, validateExpiry };

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { Address, TransactionSigner, Rpc, SolanaRpcApi } from '@solana/kit';
 import { Filter, Event } from 'nostr-tools';
+import { z } from 'zod';
 
 declare class ElisymIdentity {
     private _secretKey;
@@ -139,6 +140,18 @@ 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.
  *
@@ -173,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;
@@ -424,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`).
@@ -433,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;
@@ -448,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.
@@ -478,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.
  *
@@ -539,6 +685,82 @@ declare class BoundedSet<T> {
     add(item: T): void;
 }
 
+/**
+ * Sliding-window rate limiter keyed by an arbitrary string (typically a
+ * customer pubkey). Each key gets at most `maxPerWindow` requests inside a
+ * rolling `windowMs`. Stale timestamps are pruned lazily on every `check`.
+ * When the tracked-key set grows past `maxKeys`, the least-recently-used
+ * key is evicted so an attacker cannot exhaust memory by cycling keys.
+ *
+ * Thread-safety: not required. Designed for single-threaded JS consumers
+ * (Node/Bun event loops, browser main thread). No timers - pruning happens
+ * inside `check` and `prune`.
+ */
+interface SlidingWindowLimiterOptions {
+    /** Rolling window width, in ms. */
+    windowMs: number;
+    /** Max hits allowed per key inside the window. */
+    maxPerWindow: number;
+    /** Cap on total tracked keys. LRU-evicted past this cap. */
+    maxKeys: number;
+}
+interface RateLimitDecision {
+    allowed: boolean;
+    /** Wall-clock timestamp (ms) when the limit window will reset for this key. */
+    resetAt: number;
+    /** Number of hits inside the current window after this call (or the attempted hit if denied). */
+    count: number;
+}
+interface SlidingWindowLimiter {
+    /** Record a hit against `key`; return whether it was allowed. */
+    check(key: string, now?: number): RateLimitDecision;
+    /**
+     * Inspect the current state for `key` without recording a hit. Useful
+     * when a single request must clear multiple limiters and callers want
+     * to avoid double-counting against one limiter after another denies.
+     */
+    peek(key: string, now?: number): RateLimitDecision;
+    /** Drop entries whose windows have fully elapsed. Bounded memory hygiene. */
+    prune(now?: number): void;
+    /** Current number of tracked keys. */
+    size(): number;
+    /** Clear all state. */
+    reset(): void;
+}
+declare function createSlidingWindowLimiter(options: SlidingWindowLimiterOptions): SlidingWindowLimiter;
+
+/**
+ * Canonical pino redact paths for the elisym stack. Plugin, CLI, MCP, and
+ * any downstream integrator should consume these arrays directly - one
+ * source of truth for "fields that carry user input or secrets".
+ *
+ * Wire them into a pino instance like:
+ *
+ *   import pino from 'pino';
+ *   import { DEFAULT_REDACT_PATHS, makeCensor } from '@elisym/sdk';
+ *   const logger = pino({
+ *     redact: { paths: DEFAULT_REDACT_PATHS, censor: makeCensor() },
+ *   });
+ */
+/**
+ * Field paths that carry Nostr / Solana secret keys or operator secrets.
+ * Censored as `[REDACTED]`.
+ */
+declare const SECRET_REDACT_PATHS: string[];
+/**
+ * Field paths that carry customer-confidential text (LLM prompts, raw
+ * event content, job input). Censored as `[INPUT REDACTED]` so log
+ * readers can distinguish redacted input from redacted secrets.
+ */
+declare const INPUT_REDACT_PATHS: string[];
+/**
+ * Union of the two arrays, in the order pino's redact engine should
+ * visit them. Prefer this when wiring a new logger so no downstream
+ * consumer forgets half the set.
+ */
+declare const DEFAULT_REDACT_PATHS: string[];
+declare function makeCensor(): (value: unknown, path: string[]) => string;
+
 declare const RELAYS: string[];
 declare const KIND_APP_HANDLER = 31990;
 declare const KIND_JOB_REQUEST_BASE = 5000;
@@ -614,4 +836,4 @@ declare const LIMITS: {
     readonly MAX_CAPABILITY_LENGTH: 64;
 };
 
-export { type Agent, BoundedSet, type CapabilityCard, DEFAULTS, DEFAULT_KIND_OFFSET, DiscoveryService, ElisymClient, type ElisymClientConfig, type ElisymClientFullConfig, ElisymIdentity, 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 PaymentInfo, type PaymentRequestData, type PaymentStrategy, type PaymentValidationCode, type PaymentValidationError, type PingResult, PingService, type ProtocolCluster, type ProtocolConfig, type ProtocolConfigInput, RELAYS, SolanaPaymentStrategy, type SubCloser, type SubmitJobOptions, type VerifyOptions, type VerifyResult, assertExpiry, assertLamports, buildPaymentInstructions, calculateProtocolFee, clearProtocolConfigCache, createPaymentRequestWithOnchainConfig, formatSol, getProtocolConfig, getProtocolProgramId, jobRequestKind, jobResultKind, nip44Decrypt, nip44Encrypt, timeAgo, toDTag, truncateKey, validateAgentName, validateExpiry };
+export { type Agent, BoundedSet, type BuildTransactionOptions, type CapabilityCard, DEFAULTS, DEFAULT_KIND_OFFSET, DEFAULT_REDACT_PATHS, DiscoveryService, ElisymClient, type ElisymClientConfig, type ElisymClientFullConfig, ElisymIdentity, type EstimatePriorityFeeOptions, type GetProtocolConfigOptions, INPUT_REDACT_PATHS, 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 RateLimitDecision, SECRET_REDACT_PATHS, type Signer, type SlidingWindowLimiter, type SlidingWindowLimiterOptions, SolanaPaymentStrategy, type SubCloser, type SubmitJobOptions, type VerifyOptions, type VerifyResult, assertExpiry, assertLamports, buildPaymentInstructions, calculateProtocolFee, clearPriorityFeeCache, clearProtocolConfigCache, createPaymentRequestWithOnchainConfig, createSlidingWindowLimiter, estimatePriorityFeeMicroLamports, formatSol, getProtocolConfig, getProtocolProgramId, jobRequestKind, jobResultKind, makeCensor, nip44Decrypt, nip44Encrypt, parsePaymentRequest, pickPercentileFee, timeAgo, toDTag, truncateKey, validateAgentName, validateExpiry };