@elisym/sdk 0.5.0 → 0.6.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.
  *
@@ -614,4 +760,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, 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 };

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.
  *
@@ -614,4 +760,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, 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 };

package/dist/index.js

@@ -1,6 +1,7 @@
 import { getTransferSolInstruction } from '@solana-program/system';
-import { pipe, createTransactionMessage, setTransactionMessageFeePayerSigner, setTransactionMessageLifetimeUsingBlockhash, appendTransactionMessageInstructions, signTransactionMessageWithSigners, address, AccountRole, getProgramDerivedAddress, assertAccountExists, isAddress, getAddressDecoder, fetchEncodedAccount, decodeAccount, getStructDecoder, fixDecoderSize, getBytesDecoder, getU8Decoder, getOptionDecoder, getU16Decoder, getBooleanDecoder, getI64Decoder } from '@solana/kit';
+import { pipe, createTransactionMessage, setTransactionMessageFeePayerSigner, setTransactionMessageLifetimeUsingBlockhash, setTransactionMessageComputeUnitLimit, setTransactionMessageComputeUnitPrice, appendTransactionMessageInstructions, signTransactionMessageWithSigners, address, AccountRole, getProgramDerivedAddress, assertAccountExists, isAddress, getAddressDecoder, fetchEncodedAccount, decodeAccount, getStructDecoder, fixDecoderSize, getBytesDecoder, getU8Decoder, getOptionDecoder, getU16Decoder, getBooleanDecoder, getI64Decoder } from '@solana/kit';
 import Decimal2 from 'decimal.js-light';
+import { z } from 'zod';
 import { verifyEvent, finalizeEvent, getPublicKey, nip19, generateSecretKey, SimplePool } from 'nostr-tools';
 import * as nip44 from 'nostr-tools/nip44';
 
@@ -190,7 +191,118 @@ function assertExpiry(createdAt, expirySecs) {
   }
 }
 
+// src/payment/priorityFee.ts
+var PRIORITY_FEE_FLOOR_MICROLAMPORTS = 1000n;
+var DEFAULT_PERCENTILE = 75;
+var DEFAULT_CACHE_TTL_MS = 1e4;
+var cache2 = /* @__PURE__ */ new Map();
+async function estimatePriorityFeeMicroLamports(rpc, options) {
+  const percentile = clampPercentile(options?.percentile ?? DEFAULT_PERCENTILE);
+  const ttl = options?.ttlMs ?? DEFAULT_CACHE_TTL_MS;
+  const accounts = options?.accounts ?? [];
+  const key = cacheKey(percentile, accounts);
+  const now = Date.now();
+  const cached = cache2.get(key);
+  if (cached && now < cached.expires) {
+    return cached.microLamports;
+  }
+  const samples = await rpc.getRecentPrioritizationFees(accounts).send();
+  const fee = pickPercentileFee(samples, percentile);
+  cache2.set(key, { microLamports: fee, expires: now + ttl });
+  return fee;
+}
+function clearPriorityFeeCache() {
+  cache2.clear();
+}
+function pickPercentileFee(samples, percentile) {
+  if (samples.length === 0) {
+    return PRIORITY_FEE_FLOOR_MICROLAMPORTS;
+  }
+  const sorted = samples.map((sample) => BigInt(sample.prioritizationFee)).sort(compareBigInt);
+  const clamped = clampPercentile(percentile);
+  const indexFloat = clamped / 100 * (sorted.length - 1) | 0;
+  const value = sorted[indexFloat];
+  return value > PRIORITY_FEE_FLOOR_MICROLAMPORTS ? value : PRIORITY_FEE_FLOOR_MICROLAMPORTS;
+}
+function clampPercentile(value) {
+  if (!Number.isFinite(value)) {
+    return DEFAULT_PERCENTILE;
+  }
+  if (value < 0) {
+    return 0;
+  }
+  if (value > 100) {
+    return 100;
+  }
+  return value;
+}
+function compareBigInt(left, right) {
+  if (left < right) {
+    return -1;
+  }
+  if (left > right) {
+    return 1;
+  }
+  return 0;
+}
+function cacheKey(percentile, accounts) {
+  if (accounts.length === 0) {
+    return `p:${percentile}`;
+  }
+  return `p:${percentile}:${[...accounts].sort().join(",")}`;
+}
+var MAX_DESCRIPTION_LENGTH = LIMITS.MAX_DESCRIPTION_LENGTH;
+var MAX_SAFE_LAMPORTS = Number.MAX_SAFE_INTEGER;
+var MAX_EXPIRY_SECS_SCHEMA = 86400;
+var BASE58_RE = /^[1-9A-HJ-NP-Za-km-z]+$/;
+var SOLANA_ADDRESS_LENGTH_RE = /^.{32,44}$/;
+var lamportsSchema = z.number().int().positive().max(MAX_SAFE_LAMPORTS, `amount must be <= ${MAX_SAFE_LAMPORTS}`);
+var feeAmountSchema = z.number().int().nonnegative().max(MAX_SAFE_LAMPORTS, `fee_amount must be <= ${MAX_SAFE_LAMPORTS}`);
+var solanaAddressSchema = z.string().regex(BASE58_RE, "must be base58").regex(SOLANA_ADDRESS_LENGTH_RE, "must be 32-44 base58 chars");
+var PaymentRequestSchema = z.object({
+  recipient: solanaAddressSchema,
+  amount: lamportsSchema,
+  reference: solanaAddressSchema,
+  description: z.string().max(MAX_DESCRIPTION_LENGTH).optional(),
+  fee_address: solanaAddressSchema.optional(),
+  fee_amount: feeAmountSchema.optional(),
+  created_at: z.number().int().positive(),
+  expiry_secs: z.number().int().positive().max(MAX_EXPIRY_SECS_SCHEMA, `expiry_secs must be <= ${MAX_EXPIRY_SECS_SCHEMA}`)
+});
+function parsePaymentRequest(input, options) {
+  let parsed;
+  try {
+    parsed = JSON.parse(input);
+  } catch (e) {
+    return {
+      ok: false,
+      error: { code: "invalid_json", message: `Invalid payment request JSON: ${e}` }
+    };
+  }
+  const result = PaymentRequestSchema.safeParse(parsed);
+  if (!result.success) {
+    return {
+      ok: false,
+      error: { code: "schema", message: result.error.message }
+    };
+  }
+  if (options?.maxAmountLamports !== void 0) {
+    if (BigInt(result.data.amount) > options.maxAmountLamports) {
+      return {
+        ok: false,
+        error: {
+          code: "amount_exceeds_max",
+          message: `Payment amount ${result.data.amount} lamports exceeds approved max ${options.maxAmountLamports}.`
+        }
+      };
+    }
+  }
+  return { ok: true, data: result.data };
+}
+
 // src/payment/solana.ts
+var DEFAULT_COMPUTE_UNIT_LIMIT = 2e5;
+var DEFAULT_PRIORITY_FEE_PERCENTILE = 75;
 var REFERENCE_BYTE_LENGTH = 32;
 function isValidSolanaAddress(value) {
   return isAddress(value);
@@ -247,32 +359,27 @@ var SolanaPaymentStrategy = class {
       expiry_secs: expirySecs
     };
   }
-  validatePaymentRequest(requestJson, config, expectedRecipient) {
+  validatePaymentRequest(requestJson, config, expectedRecipient, options) {
     assertConfig(config);
-    let data;
-    try {
-      data = JSON.parse(requestJson);
-    } catch (e) {
-      return { code: "invalid_json", message: `Invalid payment request JSON: ${e}` };
-    }
-    if (typeof data.amount !== "number" || !Number.isInteger(data.amount) || data.amount <= 0) {
-      return {
-        code: "invalid_amount",
-        message: `Invalid amount in payment request: ${data.amount}`
-      };
-    }
-    if (typeof data.recipient !== "string" || !data.recipient) {
-      return { code: "missing_recipient", message: "Missing recipient in payment request" };
+    const parsed = parsePaymentRequest(requestJson, {
+      maxAmountLamports: options?.maxAmountLamports
+    });
+    if (!parsed.ok) {
+      if (parsed.error.code === "invalid_json") {
+        return { code: "invalid_json", message: parsed.error.message };
+      }
+      if (parsed.error.code === "amount_exceeds_max") {
+        return { code: "invalid_amount", message: parsed.error.message };
+      }
+      return { code: "invalid_amount", message: parsed.error.message };
     }
+    const data = parsed.data;
     if (!isValidSolanaAddress(data.recipient)) {
       return {
         code: "invalid_recipient_address",
         message: `Invalid Solana address for recipient: ${data.recipient}`
       };
     }
-    if (typeof data.reference !== "string" || !data.reference) {
-      return { code: "missing_reference", message: "Missing reference in payment request" };
-    }
     if (!isValidSolanaAddress(data.reference)) {
       return {
         code: "invalid_reference_address",
@@ -332,7 +439,7 @@ var SolanaPaymentStrategy = class {
    * read-only, non-signer account so providers can detect the payment via
    * `getSignaturesForAddress(reference)`.
    */
-  async buildTransaction(paymentRequest, payerSigner, rpc, config) {
+  async buildTransaction(paymentRequest, payerSigner, rpc, config, options) {
     assertConfig(config);
     assertLamports(paymentRequest.amount, "payment amount");
     if (paymentRequest.amount === 0) {
@@ -351,14 +458,23 @@ var SolanaPaymentStrategy = class {
         `Invalid fee address: expected ${treasury}, got ${paymentRequest.fee_address}. Cannot build transaction with redirected fees.`
       );
     }
-    const instructions = buildPaymentInstructions(paymentRequest, payerSigner);
+    const computeUnitLimit = options?.computeUnitLimit ?? DEFAULT_COMPUTE_UNIT_LIMIT;
+    if (!Number.isInteger(computeUnitLimit) || computeUnitLimit <= 0) {
+      throw new Error(`Invalid computeUnitLimit: ${computeUnitLimit}. Must be a positive integer.`);
+    }
+    const paymentInstructions = buildPaymentInstructions(paymentRequest, payerSigner);
+    const priorityFeeMicroLamports = options?.priorityFeeMicroLamports ?? await estimatePriorityFeeMicroLamports(rpc, {
+      percentile: options?.priorityFeePercentile ?? DEFAULT_PRIORITY_FEE_PERCENTILE
+    });
     const { value: latestBlockhash } = await rpc.getLatestBlockhash().send();
     const message = pipe(
       createTransactionMessage({ version: 0 }),
       (m) => setTransactionMessageFeePayerSigner(payerSigner, m),
       (m) => setTransactionMessageLifetimeUsingBlockhash(latestBlockhash, m),
+      (m) => setTransactionMessageComputeUnitLimit(computeUnitLimit, m),
+      (m) => setTransactionMessageComputeUnitPrice(priorityFeeMicroLamports, m),
       (m) => appendTransactionMessageInstructions(
-        instructions,
+        paymentInstructions,
         m
       )
     );
@@ -2271,6 +2387,6 @@ function validateAgentName(name) {
   }
 }
 
-export { BoundedSet, DEFAULTS, DEFAULT_KIND_OFFSET, DiscoveryService, ElisymClient, ElisymIdentity, 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, NostrPool, PROTOCOL_FEE_BPS, PROTOCOL_PROGRAM_ID_DEVNET, PROTOCOL_TREASURY, PingService, RELAYS, SolanaPaymentStrategy, assertExpiry, assertLamports, buildPaymentInstructions, calculateProtocolFee, clearProtocolConfigCache, createPaymentRequestWithOnchainConfig, formatSol, getProtocolConfig, getProtocolProgramId, jobRequestKind, jobResultKind, nip44Decrypt, nip44Encrypt, timeAgo, toDTag, truncateKey, validateAgentName, validateExpiry };
+export { BoundedSet, DEFAULTS, DEFAULT_KIND_OFFSET, DiscoveryService, ElisymClient, ElisymIdentity, 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, NostrPool, PROTOCOL_FEE_BPS, PROTOCOL_PROGRAM_ID_DEVNET, PROTOCOL_TREASURY, PaymentRequestSchema, PingService, RELAYS, SolanaPaymentStrategy, assertExpiry, assertLamports, buildPaymentInstructions, calculateProtocolFee, clearPriorityFeeCache, clearProtocolConfigCache, createPaymentRequestWithOnchainConfig, estimatePriorityFeeMicroLamports, formatSol, getProtocolConfig, getProtocolProgramId, jobRequestKind, jobResultKind, nip44Decrypt, nip44Encrypt, parsePaymentRequest, pickPercentileFee, timeAgo, toDTag, truncateKey, validateAgentName, validateExpiry };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map