@elisym/sdk 0.9.0 → 0.10.0

package/dist/index.d.cts

@@ -62,7 +62,16 @@ interface Agent {
     cards: CapabilityCard[];
     eventId: string;
     supportedKinds: number[];
+    /** Newest network signal of any kind: capability publish, result event, or feedback event. */
     lastSeen: number;
+    /** Unix seconds of the agent's most recent on-chain-verified paid job. Undefined if none. */
+    lastPaidJobAt?: number;
+    /** Solana tx signature of the verified paid job referenced by `lastPaidJobAt`. */
+    lastPaidJobTx?: string;
+    /** Count of `rating=1` feedback events targeting this agent (last 30 days). */
+    positiveCount?: number;
+    /** Count of all rated feedback events targeting this agent (last 30 days). */
+    totalRatingCount?: number;
     picture?: string;
     name?: string;
     about?: string;
@@ -325,9 +334,25 @@ declare class NostrPool {
 
 /** Convert a capability name to its Nostr d-tag form (ASCII-only, lowercase, hyphen-separated). */
 declare function toDTag(name: string): string;
+/** Sort key derived from an Agent. Higher bucket / rate / lastPaidJobAt = ranks higher. */
+interface RankKey {
+    /** Floor-to-minute timestamp of the agent's last verified paid job. `-Infinity` for cold start. */
+    bucket: number;
+    /** Positive review rate in `[0, 1]`. 0 when the agent has no rated feedback. */
+    rate: number;
+    /** Raw `lastPaidJobAt` (Unix sec) for tiebreak inside a bucket. 0 for cold start. */
+    lastPaidJobAt: number;
+    /** Final tiebreak; orders cold-start agents by NIP-89 freshness. */
+    lastSeen: number;
+}
+declare function computeRankKey(agent: Agent): RankKey;
+declare function compareAgentsByRank(a: Agent, b: Agent): number;
 declare class DiscoveryService {
     private pool;
-    constructor(pool: NostrPool);
+    private defaultRpc?;
+    constructor(pool: NostrPool, defaultRpc?: Rpc<SolanaRpcApi> | undefined);
+    /** Configure the Solana RPC used for on-chain payment verification in `fetchAgents`. */
+    setRpc(rpc: Rpc<SolanaRpcApi> | undefined): void;
     /** Count elisym agents (kind:31990 with "elisym" tag). */
     fetchAllAgentCount(): Promise<number>;
     /**
@@ -345,8 +370,21 @@ declare class DiscoveryService {
     }>;
     /** Enrich agents with kind:0 metadata (name, picture, about). Mutates in place and returns the same array. */
     enrichWithMetadata(agents: Agent[]): Promise<Agent[]>;
-    /** Fetch elisym agents filtered by network. */
-    fetchAgents(network?: Network, limit?: number): Promise<Agent[]>;
+    /**
+     * Fetch elisym agents filtered by network, ranked by verified paid-job recency.
+     *
+     * Ranking algorithm:
+     * 1. Bucket each agent into 1-minute slots by `lastPaidJobAt` (last on-chain
+     *    verified payment). Cold-start agents (no verified paid job) go into a
+     *    sentinel bucket below all populated buckets.
+     * 2. Within a bucket, sort by positive review rate descending.
+     * 3. Tiebreak by raw `lastPaidJobAt`, then `lastSeen` (NIP-89 freshness).
+     *
+     * On-chain verification uses {@link verifyJobPaymentQuick} - one-shot, cached.
+     * If `rpc` is not configured, all agents fall through to cold-start and order
+     * is determined by `lastSeen` only.
+     */
+    fetchAgents(network?: Network, limit?: number, rpcOverride?: Rpc<SolanaRpcApi>): Promise<Agent[]>;
     /**
      * Publish a capability card (kind:31990) as a provider.
      * Solana address is validated for Base58 format only - full decode
@@ -490,6 +528,11 @@ interface ElisymClientFullConfig extends ElisymClientConfig {
     payment?: PaymentStrategy;
     /** Custom upload URL for file uploads (defaults to nostr.build). */
     uploadUrl?: string;
+    /**
+     * Solana RPC used by `discovery.fetchAgents` for on-chain payment verification.
+     * If omitted, ranking falls back to NIP-89 freshness only (no paid-job promotion).
+     */
+    rpc?: Rpc<SolanaRpcApi>;
 }
 declare class ElisymClient {
     readonly pool: NostrPool;
@@ -766,6 +809,27 @@ type ParseResult = {
  */
 declare function parsePaymentRequest(input: string, options?: ParseOptions): ParseResult;
 
+/**
+ * Lightweight payment verifier used by discovery ranking.
+ *
+ * Unlike `SolanaPaymentStrategy.verifyPayment`, this is a single-shot check
+ * with no retries: discovery cannot afford the 30-second confirmation budget
+ * the customer-side verifier uses. If the RPC has not seen the transaction
+ * yet, we treat the agent as "no verified paid job" rather than blocking.
+ *
+ * Positive results are cached forever (Solana txs are immutable once
+ * confirmed). Negative results expire after `NEGATIVE_CACHE_TTL_MS` so a
+ * just-confirmed tx will be picked up on the next discovery refresh.
+ */
+type QuickVerifyReason = 'not_found' | 'tx_failed' | 'recipient_mismatch' | 'rpc_error' | 'invalid_input';
+interface QuickVerifyResult {
+    verified: boolean;
+    txSignature: string;
+    reason?: QuickVerifyReason;
+}
+declare function clearQuickVerifyCache(): void;
+declare function verifyJobPaymentQuick(rpc: Rpc<SolanaRpcApi>, txSignature: string, expectedRecipient: Address): Promise<QuickVerifyResult>;
+
 /**
  * Snapshot of the on-chain elisym-config program state.
  *
@@ -952,7 +1016,7 @@ declare function getProtocolProgramId(cluster: ProtocolCluster): Address;
 /** Default values for timeouts, retries, and batch sizes. */
 declare const DEFAULTS: {
     readonly SUBSCRIPTION_TIMEOUT_MS: 120000;
-    readonly PING_TIMEOUT_MS: 15000;
+    readonly PING_TIMEOUT_MS: 3000;
     readonly PING_RETRIES: 2;
     readonly PING_CACHE_TTL_MS: 30000;
     readonly PAYMENT_EXPIRY_SECS: 600;
@@ -978,4 +1042,4 @@ declare const LIMITS: {
     readonly MAX_CAPABILITY_LENGTH: 64;
 };
 
-export { type Agent, Asset, BoundedSet, type BuildTransactionOptions, type CapabilityCard, DEFAULTS, DEFAULT_KIND_OFFSET, DEFAULT_REDACT_PATHS, DiscoveryService, ElisymClient, type ElisymClientConfig, type ElisymClientFullConfig, ElisymIdentity, type EstimatePriorityFeeOptions, type EstimateSolFeeOptions, 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 PaymentAssetRef, 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, type SolFeeEstimate, SolanaPaymentStrategy, type SubCloser, type SubmitJobOptions, type VerifyOptions, type VerifyResult, assertExpiry, assertLamports, buildPaymentInstructions, calculateProtocolFee, clearPriorityFeeCache, clearProtocolConfigCache, createPaymentRequestWithOnchainConfig, createSlidingWindowLimiter, estimatePriorityFeeMicroLamports, estimateSolFeeLamports, formatFeeBreakdown, formatSol, getProtocolConfig, getProtocolProgramId, jobRequestKind, jobResultKind, makeCensor, nip44Decrypt, nip44Encrypt, parsePaymentRequest, pickPercentileFee, timeAgo, toDTag, truncateKey, validateAgentName, validateExpiry };
+export { type Agent, Asset, BoundedSet, type BuildTransactionOptions, type CapabilityCard, DEFAULTS, DEFAULT_KIND_OFFSET, DEFAULT_REDACT_PATHS, DiscoveryService, ElisymClient, type ElisymClientConfig, type ElisymClientFullConfig, ElisymIdentity, type EstimatePriorityFeeOptions, type EstimateSolFeeOptions, 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 PaymentAssetRef, type PaymentInfo, type PaymentRequestData, PaymentRequestSchema, type PaymentStrategy, type PaymentValidationCode, type PaymentValidationError, type PingResult, PingService, type ProtocolCluster, type ProtocolConfig, type ProtocolConfigInput, type QuickVerifyReason, type QuickVerifyResult, RELAYS, type RankKey, type RateLimitDecision, SECRET_REDACT_PATHS, type Signer, type SlidingWindowLimiter, type SlidingWindowLimiterOptions, type SolFeeEstimate, SolanaPaymentStrategy, type SubCloser, type SubmitJobOptions, type VerifyOptions, type VerifyResult, assertExpiry, assertLamports, buildPaymentInstructions, calculateProtocolFee, clearPriorityFeeCache, clearProtocolConfigCache, clearQuickVerifyCache, compareAgentsByRank, computeRankKey, createPaymentRequestWithOnchainConfig, createSlidingWindowLimiter, estimatePriorityFeeMicroLamports, estimateSolFeeLamports, formatFeeBreakdown, formatSol, getProtocolConfig, getProtocolProgramId, jobRequestKind, jobResultKind, makeCensor, nip44Decrypt, nip44Encrypt, parsePaymentRequest, pickPercentileFee, timeAgo, toDTag, truncateKey, validateAgentName, validateExpiry, verifyJobPaymentQuick };

package/dist/index.d.ts

@@ -62,7 +62,16 @@ interface Agent {
     cards: CapabilityCard[];
     eventId: string;
     supportedKinds: number[];
+    /** Newest network signal of any kind: capability publish, result event, or feedback event. */
     lastSeen: number;
+    /** Unix seconds of the agent's most recent on-chain-verified paid job. Undefined if none. */
+    lastPaidJobAt?: number;
+    /** Solana tx signature of the verified paid job referenced by `lastPaidJobAt`. */
+    lastPaidJobTx?: string;
+    /** Count of `rating=1` feedback events targeting this agent (last 30 days). */
+    positiveCount?: number;
+    /** Count of all rated feedback events targeting this agent (last 30 days). */
+    totalRatingCount?: number;
     picture?: string;
     name?: string;
     about?: string;
@@ -325,9 +334,25 @@ declare class NostrPool {
 
 /** Convert a capability name to its Nostr d-tag form (ASCII-only, lowercase, hyphen-separated). */
 declare function toDTag(name: string): string;
+/** Sort key derived from an Agent. Higher bucket / rate / lastPaidJobAt = ranks higher. */
+interface RankKey {
+    /** Floor-to-minute timestamp of the agent's last verified paid job. `-Infinity` for cold start. */
+    bucket: number;
+    /** Positive review rate in `[0, 1]`. 0 when the agent has no rated feedback. */
+    rate: number;
+    /** Raw `lastPaidJobAt` (Unix sec) for tiebreak inside a bucket. 0 for cold start. */
+    lastPaidJobAt: number;
+    /** Final tiebreak; orders cold-start agents by NIP-89 freshness. */
+    lastSeen: number;
+}
+declare function computeRankKey(agent: Agent): RankKey;
+declare function compareAgentsByRank(a: Agent, b: Agent): number;
 declare class DiscoveryService {
     private pool;
-    constructor(pool: NostrPool);
+    private defaultRpc?;
+    constructor(pool: NostrPool, defaultRpc?: Rpc<SolanaRpcApi> | undefined);
+    /** Configure the Solana RPC used for on-chain payment verification in `fetchAgents`. */
+    setRpc(rpc: Rpc<SolanaRpcApi> | undefined): void;
     /** Count elisym agents (kind:31990 with "elisym" tag). */
     fetchAllAgentCount(): Promise<number>;
     /**
@@ -345,8 +370,21 @@ declare class DiscoveryService {
     }>;
     /** Enrich agents with kind:0 metadata (name, picture, about). Mutates in place and returns the same array. */
     enrichWithMetadata(agents: Agent[]): Promise<Agent[]>;
-    /** Fetch elisym agents filtered by network. */
-    fetchAgents(network?: Network, limit?: number): Promise<Agent[]>;
+    /**
+     * Fetch elisym agents filtered by network, ranked by verified paid-job recency.
+     *
+     * Ranking algorithm:
+     * 1. Bucket each agent into 1-minute slots by `lastPaidJobAt` (last on-chain
+     *    verified payment). Cold-start agents (no verified paid job) go into a
+     *    sentinel bucket below all populated buckets.
+     * 2. Within a bucket, sort by positive review rate descending.
+     * 3. Tiebreak by raw `lastPaidJobAt`, then `lastSeen` (NIP-89 freshness).
+     *
+     * On-chain verification uses {@link verifyJobPaymentQuick} - one-shot, cached.
+     * If `rpc` is not configured, all agents fall through to cold-start and order
+     * is determined by `lastSeen` only.
+     */
+    fetchAgents(network?: Network, limit?: number, rpcOverride?: Rpc<SolanaRpcApi>): Promise<Agent[]>;
     /**
      * Publish a capability card (kind:31990) as a provider.
      * Solana address is validated for Base58 format only - full decode
@@ -490,6 +528,11 @@ interface ElisymClientFullConfig extends ElisymClientConfig {
     payment?: PaymentStrategy;
     /** Custom upload URL for file uploads (defaults to nostr.build). */
     uploadUrl?: string;
+    /**
+     * Solana RPC used by `discovery.fetchAgents` for on-chain payment verification.
+     * If omitted, ranking falls back to NIP-89 freshness only (no paid-job promotion).
+     */
+    rpc?: Rpc<SolanaRpcApi>;
 }
 declare class ElisymClient {
     readonly pool: NostrPool;
@@ -766,6 +809,27 @@ type ParseResult = {
  */
 declare function parsePaymentRequest(input: string, options?: ParseOptions): ParseResult;
 
+/**
+ * Lightweight payment verifier used by discovery ranking.
+ *
+ * Unlike `SolanaPaymentStrategy.verifyPayment`, this is a single-shot check
+ * with no retries: discovery cannot afford the 30-second confirmation budget
+ * the customer-side verifier uses. If the RPC has not seen the transaction
+ * yet, we treat the agent as "no verified paid job" rather than blocking.
+ *
+ * Positive results are cached forever (Solana txs are immutable once
+ * confirmed). Negative results expire after `NEGATIVE_CACHE_TTL_MS` so a
+ * just-confirmed tx will be picked up on the next discovery refresh.
+ */
+type QuickVerifyReason = 'not_found' | 'tx_failed' | 'recipient_mismatch' | 'rpc_error' | 'invalid_input';
+interface QuickVerifyResult {
+    verified: boolean;
+    txSignature: string;
+    reason?: QuickVerifyReason;
+}
+declare function clearQuickVerifyCache(): void;
+declare function verifyJobPaymentQuick(rpc: Rpc<SolanaRpcApi>, txSignature: string, expectedRecipient: Address): Promise<QuickVerifyResult>;
+
 /**
  * Snapshot of the on-chain elisym-config program state.
  *
@@ -952,7 +1016,7 @@ declare function getProtocolProgramId(cluster: ProtocolCluster): Address;
 /** Default values for timeouts, retries, and batch sizes. */
 declare const DEFAULTS: {
     readonly SUBSCRIPTION_TIMEOUT_MS: 120000;
-    readonly PING_TIMEOUT_MS: 15000;
+    readonly PING_TIMEOUT_MS: 3000;
     readonly PING_RETRIES: 2;
     readonly PING_CACHE_TTL_MS: 30000;
     readonly PAYMENT_EXPIRY_SECS: 600;
@@ -978,4 +1042,4 @@ declare const LIMITS: {
     readonly MAX_CAPABILITY_LENGTH: 64;
 };
 
-export { type Agent, Asset, BoundedSet, type BuildTransactionOptions, type CapabilityCard, DEFAULTS, DEFAULT_KIND_OFFSET, DEFAULT_REDACT_PATHS, DiscoveryService, ElisymClient, type ElisymClientConfig, type ElisymClientFullConfig, ElisymIdentity, type EstimatePriorityFeeOptions, type EstimateSolFeeOptions, 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 PaymentAssetRef, 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, type SolFeeEstimate, SolanaPaymentStrategy, type SubCloser, type SubmitJobOptions, type VerifyOptions, type VerifyResult, assertExpiry, assertLamports, buildPaymentInstructions, calculateProtocolFee, clearPriorityFeeCache, clearProtocolConfigCache, createPaymentRequestWithOnchainConfig, createSlidingWindowLimiter, estimatePriorityFeeMicroLamports, estimateSolFeeLamports, formatFeeBreakdown, formatSol, getProtocolConfig, getProtocolProgramId, jobRequestKind, jobResultKind, makeCensor, nip44Decrypt, nip44Encrypt, parsePaymentRequest, pickPercentileFee, timeAgo, toDTag, truncateKey, validateAgentName, validateExpiry };
+export { type Agent, Asset, BoundedSet, type BuildTransactionOptions, type CapabilityCard, DEFAULTS, DEFAULT_KIND_OFFSET, DEFAULT_REDACT_PATHS, DiscoveryService, ElisymClient, type ElisymClientConfig, type ElisymClientFullConfig, ElisymIdentity, type EstimatePriorityFeeOptions, type EstimateSolFeeOptions, 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 PaymentAssetRef, type PaymentInfo, type PaymentRequestData, PaymentRequestSchema, type PaymentStrategy, type PaymentValidationCode, type PaymentValidationError, type PingResult, PingService, type ProtocolCluster, type ProtocolConfig, type ProtocolConfigInput, type QuickVerifyReason, type QuickVerifyResult, RELAYS, type RankKey, type RateLimitDecision, SECRET_REDACT_PATHS, type Signer, type SlidingWindowLimiter, type SlidingWindowLimiterOptions, type SolFeeEstimate, SolanaPaymentStrategy, type SubCloser, type SubmitJobOptions, type VerifyOptions, type VerifyResult, assertExpiry, assertLamports, buildPaymentInstructions, calculateProtocolFee, clearPriorityFeeCache, clearProtocolConfigCache, clearQuickVerifyCache, compareAgentsByRank, computeRankKey, createPaymentRequestWithOnchainConfig, createSlidingWindowLimiter, estimatePriorityFeeMicroLamports, estimateSolFeeLamports, formatFeeBreakdown, formatSol, getProtocolConfig, getProtocolProgramId, jobRequestKind, jobResultKind, makeCensor, nip44Decrypt, nip44Encrypt, parsePaymentRequest, pickPercentileFee, timeAgo, toDTag, truncateKey, validateAgentName, validateExpiry, verifyJobPaymentQuick };

package/dist/index.js

@@ -1,6 +1,6 @@
 import { getTransferSolInstruction } from '@solana-program/system';
 import { findAssociatedTokenPda, TOKEN_PROGRAM_ADDRESS, getCreateAssociatedTokenIdempotentInstruction, ASSOCIATED_TOKEN_PROGRAM_ADDRESS, getTransferCheckedInstruction } from '@solana-program/token';
-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 { pipe, createTransactionMessage, setTransactionMessageFeePayerSigner, setTransactionMessageLifetimeUsingBlockhash, setTransactionMessageComputeUnitLimit, setTransactionMessageComputeUnitPrice, appendTransactionMessageInstructions, signTransactionMessageWithSigners, address, AccountRole, isAddress, getProgramDerivedAddress, assertAccountExists, 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';
@@ -50,7 +50,7 @@ function getProtocolProgramId(cluster) {
 }
 var DEFAULTS = {
   SUBSCRIPTION_TIMEOUT_MS: 12e4,
-  PING_TIMEOUT_MS: 15e3,
+  PING_TIMEOUT_MS: 3e3,
   PING_RETRIES: 2,
   PING_CACHE_TTL_MS: 3e4,
   PAYMENT_EXPIRY_SECS: 600,
@@ -994,6 +994,95 @@ async function createPaymentRequestWithOnchainConfig(rpc, programId, recipient,
     options
   );
 }
+var NEGATIVE_CACHE_TTL_MS = 6e4;
+var verifyCache = /* @__PURE__ */ new Map();
+function clearQuickVerifyCache() {
+  verifyCache.clear();
+}
+async function verifyJobPaymentQuick(rpc, txSignature, expectedRecipient) {
+  if (!txSignature) {
+    return { verified: false, txSignature: "", reason: "invalid_input" };
+  }
+  if (!expectedRecipient || !isAddress(expectedRecipient)) {
+    return { verified: false, txSignature, reason: "invalid_input" };
+  }
+  const cacheKey2 = `${txSignature}:${expectedRecipient}`;
+  const cached = verifyCache.get(cacheKey2);
+  if (cached) {
+    if (cached.result.verified) {
+      return cached.result;
+    }
+    if (Date.now() - cached.cachedAt < NEGATIVE_CACHE_TTL_MS) {
+      return cached.result;
+    }
+  }
+  const result = await doVerifyOnce(rpc, txSignature, expectedRecipient);
+  verifyCache.set(cacheKey2, { result, cachedAt: Date.now() });
+  return result;
+}
+async function doVerifyOnce(rpc, txSignature, expectedRecipient) {
+  const sigStr = txSignature;
+  if (!rpc || typeof rpc.getTransaction !== "function") {
+    return { verified: false, txSignature: sigStr, reason: "rpc_error" };
+  }
+  let tx;
+  try {
+    tx = await rpc.getTransaction(txSignature, {
+      commitment: "confirmed",
+      encoding: "json",
+      maxSupportedTransactionVersion: 0
+    }).send();
+  } catch {
+    return { verified: false, txSignature: sigStr, reason: "rpc_error" };
+  }
+  if (!tx) {
+    return { verified: false, txSignature: sigStr, reason: "not_found" };
+  }
+  if (!tx.meta || tx.meta.err) {
+    return { verified: false, txSignature: sigStr, reason: "tx_failed" };
+  }
+  const accountKeys = tx.transaction.message.accountKeys;
+  const recipientStr = expectedRecipient;
+  const recipientIdx = accountKeys.indexOf(recipientStr);
+  if (recipientIdx !== -1) {
+    const preBalances = tx.meta.preBalances;
+    const postBalances = tx.meta.postBalances;
+    if (preBalances && postBalances) {
+      const pre = preBalances[recipientIdx];
+      const post = postBalances[recipientIdx];
+      if (pre !== void 0 && post !== void 0) {
+        const delta = BigInt(post) - BigInt(pre);
+        if (delta > 0n) {
+          return { verified: true, txSignature: sigStr };
+        }
+      }
+    }
+  }
+  const postTokenBalances = tx.meta.postTokenBalances;
+  const preTokenBalances = tx.meta.preTokenBalances;
+  if (postTokenBalances) {
+    for (const post of postTokenBalances) {
+      if (post.owner !== recipientStr) {
+        continue;
+      }
+      const pre = preTokenBalances?.find(
+        (entry) => entry.owner === recipientStr && entry.mint === post.mint
+      );
+      const preAmount = pre ? BigInt(pre.uiTokenAmount.amount) : 0n;
+      const postAmount = BigInt(post.uiTokenAmount.amount);
+      if (postAmount > preAmount) {
+        return { verified: true, txSignature: sigStr };
+      }
+    }
+  }
+  return { verified: false, txSignature: sigStr, reason: "recipient_mismatch" };
+}
+
+// src/services/discovery.ts
+var RANKING_ACTIVITY_WINDOW_SECS = 30 * 24 * 60 * 60;
+var RANKING_BUCKET_SIZE_SECS = 60;
+var COLD_START_BUCKET = -Infinity;
+var MAX_PAID_CANDIDATES_PER_AGENT = 5;
 function toDTag(name) {
   const tag = name.toLowerCase().replace(/[^a-z0-9\s-]/g, (ch) => "_" + ch.charCodeAt(0).toString(16).padStart(2, "0")).replace(/\s+/g, "-").replace(/^-+|-+$/g, "");
   if (!tag) {
@@ -1001,6 +1090,28 @@ function toDTag(name) {
   }
   return tag;
 }
+function computeRankKey(agent) {
+  const lastPaidJobAt = agent.lastPaidJobAt ?? 0;
+  const total = agent.totalRatingCount ?? 0;
+  const positive = agent.positiveCount ?? 0;
+  const rate = total > 0 ? positive / total : 0;
+  const bucket = lastPaidJobAt > 0 ? Math.floor(lastPaidJobAt / RANKING_BUCKET_SIZE_SECS) * RANKING_BUCKET_SIZE_SECS : COLD_START_BUCKET;
+  return { bucket, rate, lastPaidJobAt, lastSeen: agent.lastSeen };
+}
+function compareAgentsByRank(a, b) {
+  const ka = computeRankKey(a);
+  const kb = computeRankKey(b);
+  if (kb.bucket !== ka.bucket) {
+    return kb.bucket - ka.bucket;
+  }
+  if (kb.rate !== ka.rate) {
+    return kb.rate - ka.rate;
+  }
+  if (kb.lastPaidJobAt !== ka.lastPaidJobAt) {
+    return kb.lastPaidJobAt - ka.lastPaidJobAt;
+  }
+  return kb.lastSeen - ka.lastSeen;
+}
 function buildAgentsFromEvents(events, network) {
   const latestByDTag = /* @__PURE__ */ new Map();
   for (const event of events) {
@@ -1095,9 +1206,37 @@ function buildAgentsFromEvents(events, network) {
   }
   return agentMap;
 }
+function pickSolanaAddress(agent) {
+  for (const card of agent.cards) {
+    const addr = card.payment?.address;
+    if (card.payment?.chain === "solana" && typeof addr === "string" && addr.length > 0) {
+      return addr;
+    }
+  }
+  return null;
+}
+async function verifyNewestPaidCandidate(rpc, recipient, candidatesNewestFirst) {
+  const settled = await Promise.allSettled(
+    candidatesNewestFirst.map(
+      (candidate) => verifyJobPaymentQuick(rpc, candidate.txSignature, recipient)
+    )
+  );
+  for (let i = 0; i < settled.length; i++) {
+    const entry = settled[i];
+    if (entry?.status === "fulfilled" && entry.value.verified) {
+      return candidatesNewestFirst[i] ?? null;
+    }
+  }
+  return null;
+}
 var DiscoveryService = class {
-  constructor(pool) {
+  constructor(pool, defaultRpc) {
     this.pool = pool;
+    this.defaultRpc = defaultRpc;
+  }
+  /** Configure the Solana RPC used for on-chain payment verification in `fetchAgents`. */
+  setRpc(rpc) {
+    this.defaultRpc = rpc;
   }
   /** Count elisym agents (kind:31990 with "elisym" tag). */
   async fetchAllAgentCount() {
@@ -1185,8 +1324,21 @@ var DiscoveryService = class {
     }
     return agents;
   }
-  /** Fetch elisym agents filtered by network. */
-  async fetchAgents(network = "devnet", limit) {
+  /**
+   * Fetch elisym agents filtered by network, ranked by verified paid-job recency.
+   *
+   * Ranking algorithm:
+   * 1. Bucket each agent into 1-minute slots by `lastPaidJobAt` (last on-chain
+   *    verified payment). Cold-start agents (no verified paid job) go into a
+   *    sentinel bucket below all populated buckets.
+   * 2. Within a bucket, sort by positive review rate descending.
+   * 3. Tiebreak by raw `lastPaidJobAt`, then `lastSeen` (NIP-89 freshness).
+   *
+   * On-chain verification uses {@link verifyJobPaymentQuick} - one-shot, cached.
+   * If `rpc` is not configured, all agents fall through to cold-start and order
+   * is determined by `lastSeen` only.
+   */
+  async fetchAgents(network = "devnet", limit, rpcOverride) {
     const filter = {
       kinds: [KIND_APP_HANDLER],
       "#t": ["elisym"]
@@ -1196,40 +1348,100 @@ var DiscoveryService = class {
     }
     const events = await this.pool.querySync(filter);
     const agentMap = buildAgentsFromEvents(events, network);
-    const agents = Array.from(agentMap.values()).sort((a, b) => b.lastSeen - a.lastSeen);
+    const agents = Array.from(agentMap.values());
     const agentPubkeys = Array.from(agentMap.keys());
-    if (agentPubkeys.length > 0) {
-      const activitySince = Math.floor(Date.now() / 1e3) - 24 * 60 * 60;
-      const resultKinds = /* @__PURE__ */ new Set();
-      for (const agent of agentMap.values()) {
-        for (const k of agent.supportedKinds) {
-          if (k >= KIND_JOB_REQUEST_BASE && k < KIND_JOB_RESULT_BASE) {
-            resultKinds.add(KIND_JOB_RESULT_BASE + (k - KIND_JOB_REQUEST_BASE));
-          }
+    if (agentPubkeys.length === 0) {
+      return agents;
+    }
+    const activitySince = Math.floor(Date.now() / 1e3) - RANKING_ACTIVITY_WINDOW_SECS;
+    const resultKinds = /* @__PURE__ */ new Set();
+    for (const agent of agentMap.values()) {
+      for (const k of agent.supportedKinds) {
+        if (k >= KIND_JOB_REQUEST_BASE && k < KIND_JOB_RESULT_BASE) {
+          resultKinds.add(KIND_JOB_RESULT_BASE + (k - KIND_JOB_REQUEST_BASE));
         }
       }
-      resultKinds.add(jobResultKind(DEFAULT_KIND_OFFSET));
-      const [activityEvents] = await Promise.all([
-        this.pool.queryBatched(
-          {
-            kinds: [...resultKinds, KIND_JOB_FEEDBACK],
-            since: activitySince
-          },
-          agentPubkeys
-        ),
-        this.enrichWithMetadata(agents)
-      ]);
-      for (const ev of activityEvents) {
-        if (!verifyEvent(ev)) {
-          continue;
+    }
+    resultKinds.add(jobResultKind(DEFAULT_KIND_OFFSET));
+    const [resultEvents, feedbackEvents] = await Promise.all([
+      this.pool.queryBatched(
+        {
+          kinds: [...resultKinds],
+          since: activitySince
+        },
+        agentPubkeys
+      ),
+      this.pool.queryBatchedByTag(
+        { kinds: [KIND_JOB_FEEDBACK], since: activitySince },
+        "p",
+        agentPubkeys
+      ),
+      this.enrichWithMetadata(agents)
+    ]);
+    for (const ev of resultEvents) {
+      if (!verifyEvent(ev)) {
+        continue;
+      }
+      const agent = agentMap.get(ev.pubkey);
+      if (agent && ev.created_at > agent.lastSeen) {
+        agent.lastSeen = ev.created_at;
+      }
+    }
+    const paidCandidates = /* @__PURE__ */ new Map();
+    for (const ev of feedbackEvents) {
+      if (!verifyEvent(ev)) {
+        continue;
+      }
+      const targetPubkey = ev.tags.find((t) => t[0] === "p")?.[1];
+      if (!targetPubkey) {
+        continue;
+      }
+      const agent = agentMap.get(targetPubkey);
+      if (!agent) {
+        continue;
+      }
+      if (ev.created_at > agent.lastSeen) {
+        agent.lastSeen = ev.created_at;
+      }
+      const rating = ev.tags.find((t) => t[0] === "rating")?.[1];
+      if (rating === "1" || rating === "0") {
+        agent.totalRatingCount = (agent.totalRatingCount ?? 0) + 1;
+        if (rating === "1") {
+          agent.positiveCount = (agent.positiveCount ?? 0) + 1;
         }
-        const agent = agentMap.get(ev.pubkey);
-        if (agent && ev.created_at > agent.lastSeen) {
-          agent.lastSeen = ev.created_at;
+      }
+      const status = ev.tags.find((t) => t[0] === "status")?.[1];
+      const txTag = ev.tags.find((t) => t[0] === "tx");
+      const txSignature = txTag?.[1];
+      if (status === "payment-completed" && typeof txSignature === "string" && txSignature) {
+        const list = paidCandidates.get(targetPubkey);
+        const candidate = { txSignature, createdAt: ev.created_at };
+        if (list) {
+          list.push(candidate);
+        } else {
+          paidCandidates.set(targetPubkey, [candidate]);
         }
       }
-      agents.sort((a, b) => b.lastSeen - a.lastSeen);
     }
+    const rpc = rpcOverride ?? this.defaultRpc;
+    if (rpc && paidCandidates.size > 0) {
+      const perAgent = Array.from(paidCandidates.entries()).map(([agentPubkey, list]) => {
+        const agent = agentMap.get(agentPubkey);
+        const recipient = agent ? pickSolanaAddress(agent) : null;
+        if (!agent || !recipient) {
+          return Promise.resolve();
+        }
+        const ordered = [...list].sort((a, b) => b.createdAt - a.createdAt).slice(0, MAX_PAID_CANDIDATES_PER_AGENT);
+        return verifyNewestPaidCandidate(rpc, recipient, ordered).then((winner) => {
+          if (winner) {
+            agent.lastPaidJobAt = winner.createdAt;
+            agent.lastPaidJobTx = winner.txSignature;
+          }
+        });
+      });
+      await Promise.all(perAgent);
+    }
+    agents.sort(compareAgentsByRank);
     return agents;
   }
   /**
@@ -2577,7 +2789,7 @@ var ElisymClient = class {
   payment;
   constructor(config = {}) {
     this.pool = new NostrPool(config.relays ?? RELAYS);
-    this.discovery = new DiscoveryService(this.pool);
+    this.discovery = new DiscoveryService(this.pool, config.rpc);
     this.marketplace = new MarketplaceService(this.pool);
     this.ping = new PingService(this.pool);
     this.media = new MediaService(config.uploadUrl);
@@ -2905,6 +3117,6 @@ function makeCensor() {
   };
 }
 
-export { BoundedSet, DEFAULTS, DEFAULT_KIND_OFFSET, DEFAULT_REDACT_PATHS, DiscoveryService, ElisymClient, ElisymIdentity, GlobalConfigSchema, INPUT_REDACT_PATHS, KIND_APP_HANDLER, KIND_JOB_FEEDBACK, KIND_JOB_REQUEST, KIND_JOB_REQUEST_BASE, KIND_JOB_RESULT, KIND_JOB_RESULT_BASE, KIND_PING, KIND_PONG, KNOWN_ASSETS, LAMPORTS_PER_SOL, LIMITS, MarketplaceService, MediaService, NATIVE_SOL, NostrPool, PROTOCOL_FEE_BPS, PROTOCOL_PROGRAM_ID_DEVNET, PROTOCOL_TREASURY, PaymentRequestSchema, PingService, RELAYS, SECRET_REDACT_PATHS, SessionSpendLimitEntrySchema, SolanaPaymentStrategy, USDC_SOLANA_DEVNET, assertExpiry, assertLamports, assetByKey, assetKey, buildPaymentInstructions, calculateProtocolFee, clearPriorityFeeCache, clearProtocolConfigCache, createPaymentRequestWithOnchainConfig, createSlidingWindowLimiter, estimatePriorityFeeMicroLamports, estimateSolFeeLamports, formatAssetAmount, formatFeeBreakdown, formatSol, getProtocolConfig, getProtocolProgramId, jobRequestKind, jobResultKind, makeCensor, nip44Decrypt, nip44Encrypt, parseAssetAmount, parsePaymentRequest, pickPercentileFee, resolveAssetFromPaymentRequest, resolveKnownAsset, timeAgo, toDTag, truncateKey, validateAgentName, validateExpiry };
+export { BoundedSet, DEFAULTS, DEFAULT_KIND_OFFSET, DEFAULT_REDACT_PATHS, DiscoveryService, ElisymClient, ElisymIdentity, GlobalConfigSchema, INPUT_REDACT_PATHS, KIND_APP_HANDLER, KIND_JOB_FEEDBACK, KIND_JOB_REQUEST, KIND_JOB_REQUEST_BASE, KIND_JOB_RESULT, KIND_JOB_RESULT_BASE, KIND_PING, KIND_PONG, KNOWN_ASSETS, LAMPORTS_PER_SOL, LIMITS, MarketplaceService, MediaService, NATIVE_SOL, NostrPool, PROTOCOL_FEE_BPS, PROTOCOL_PROGRAM_ID_DEVNET, PROTOCOL_TREASURY, PaymentRequestSchema, PingService, RELAYS, SECRET_REDACT_PATHS, SessionSpendLimitEntrySchema, SolanaPaymentStrategy, USDC_SOLANA_DEVNET, assertExpiry, assertLamports, assetByKey, assetKey, buildPaymentInstructions, calculateProtocolFee, clearPriorityFeeCache, clearProtocolConfigCache, clearQuickVerifyCache, compareAgentsByRank, computeRankKey, createPaymentRequestWithOnchainConfig, createSlidingWindowLimiter, estimatePriorityFeeMicroLamports, estimateSolFeeLamports, formatAssetAmount, formatFeeBreakdown, formatSol, getProtocolConfig, getProtocolProgramId, jobRequestKind, jobResultKind, makeCensor, nip44Decrypt, nip44Encrypt, parseAssetAmount, parsePaymentRequest, pickPercentileFee, resolveAssetFromPaymentRequest, resolveKnownAsset, timeAgo, toDTag, truncateKey, validateAgentName, validateExpiry, verifyJobPaymentQuick };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map