@elisym/sdk 0.10.3 → 0.11.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { Address, TransactionSigner, Rpc, SolanaRpcApi } from '@solana/kit';
+import { Address, TransactionSigner, Rpc, SolanaRpcApi, Signature } from '@solana/kit';
 import { Filter, Event } from 'nostr-tools';
 import { A as Asset } from './assets-C-nzSYD4.cjs';
 export { C as Chain, K as KNOWN_ASSETS, N as NATIVE_SOL, U as USDC_SOLANA_DEVNET, a as assetByKey, b as assetKey, f as formatAssetAmount, p as parseAssetAmount, r as resolveAssetFromPaymentRequest, c as resolveKnownAsset } from './assets-C-nzSYD4.cjs';
@@ -183,8 +183,6 @@ interface PaymentValidationError {
     message: string;
 }
 interface NetworkStats {
-    totalAgentCount: number;
-    agentCount: number;
     jobCount: number;
     totalLamports: number;
 }
@@ -285,6 +283,14 @@ interface BuildTransactionOptions {
      * quartile (default), 90 = aggressive.
      */
     priorityFeePercentile?: number;
+    /**
+     * Nostr job request event id (hex) to embed in an SPL Memo instruction
+     * with payload `elisym:v1:<jobEventId>`. Off-chain indexers join the memo
+     * back to the originating job for per-provider/per-capability analytics.
+     * Memo is omitted when this option is absent; the protocol tag is still
+     * attached either way.
+     */
+    jobEventId?: string;
 }
 
 declare class NostrPool {
@@ -358,8 +364,6 @@ declare function compareAgentsByRank(a: Agent, b: Agent): number;
 declare class DiscoveryService {
     private pool;
     constructor(pool: NostrPool);
-    /** Count elisym agents (kind:31990 with "elisym" tag). */
-    fetchAllAgentCount(): Promise<number>;
     /**
      * Fetch a single page of elisym agents with relay-side pagination.
      * Uses `until` cursor for Nostr cursor-based pagination.
@@ -381,18 +385,20 @@ declare class DiscoveryService {
      *
      * Ranking algorithm:
      * 1. Bucket each agent into 1-minute slots by `lastPaidJobAt` (newest
-     *    `payment-completed` feedback timestamp). Cold-start agents go into a
-     *    sentinel bucket below all populated buckets.
+     *    `payment-completed` feedback timestamp, gated by a matching kind:6xxx
+     *    result from the provider on the same job event). Cold-start agents 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).
      *
-     * NOTE: We trust the `payment-completed` feedback timestamp directly; we do
-     * not verify the embedded `tx` signature on-chain. Public Solana devnet RPC
-     * rate-limits trivially exceed what discovery needs (N agents * up-to-5
-     * candidates), and the resulting 429s blocked discovery entirely. This
-     * means a malicious customer can publish a fake `payment-completed` to lift
-     * an agent's ranking. Acceptable trade-off for devnet / MVP; tighten via
-     * recipient-tied checks when the network moves to mainnet with a paid RPC
+     * NOTE: We do not verify the `tx` signature on-chain - public Solana devnet
+     * RPC rate-limits trivially exceed what discovery needs (N agents * up-to-5
+     * candidates), and the resulting 429s blocked discovery entirely. As a
+     * lighter sybil mitigation we cross-check `payment-completed` feedback
+     * against a kind:6xxx result event authored by the provider on the same
+     * job: a customer can publish a fake `payment-completed`, but they cannot
+     * forge a result event signed by the provider. Tighten with recipient-tied
+     * on-chain checks when the network moves to mainnet with a paid RPC
      * provider.
      */
     fetchAgents(network?: Network, limit?: number): Promise<Agent[]>;
@@ -589,12 +595,24 @@ declare class SolanaPaymentStrategy implements PaymentStrategy {
  *      extra read-only account (canonical Solana Pay pattern);
  *   4. `TransferChecked` from payer ATA to treasury ATA if a fee applies.
  *
+ * Every provider transfer instruction also carries `ELISYM_PROTOCOL_TAG` as a
+ * read-only marker account so off-chain indexers can enumerate every elisym
+ * transaction with a single `getSignaturesForAddress(ELISYM_PROTOCOL_TAG)`
+ * call, regardless of fee size.
+ *
+ * If `options.jobEventId` is provided, an SPL Memo instruction with payload
+ * `elisym:v1:<jobEventId>` is prepended so explorers display the originating
+ * Nostr job id and indexers can join on-chain payments back to off-chain
+ * job context.
+ *
  * Async because SPL ATAs are PDAs and `findAssociatedTokenPda` is async.
  *
  * Caller is responsible for validating `paymentRequest` upstream;
  * `buildTransaction` already does that before invoking this helper.
  */
-declare function buildPaymentInstructions(paymentRequest: PaymentRequestData, payerSigner: Signer): Promise<readonly unknown[]>;
+declare function buildPaymentInstructions(paymentRequest: PaymentRequestData, payerSigner: Signer, options?: {
+    jobEventId?: string;
+}): Promise<readonly unknown[]>;
 /**
  * Convenience wrapper: fetch the on-chain protocol config first, then build a
  * payment request using its current fee/treasury values.
@@ -836,6 +854,40 @@ interface QuickVerifyResult {
 declare function clearQuickVerifyCache(): void;
 declare function verifyJobPaymentQuick(rpc: Rpc<SolanaRpcApi>, txSignature: string, expectedRecipient: Address): Promise<QuickVerifyResult>;
 
+/**
+ * Aggregated on-chain stats across the entire elisym network. Volume is
+ * keyed by `'native'` for SOL or by SPL mint address; values are subunits
+ * (lamports for native, raw token units for SPL).
+ */
+interface NetworkStatsResult {
+    jobCount: number;
+    volumeByAsset: Record<string, bigint>;
+    /** Most-recent signature returned by the RPC (use as cursor for forward sync). */
+    latestSignature?: string;
+    /** Oldest signature scanned in this batch (use as `before` for next page). */
+    oldestSignature?: string;
+}
+interface AggregateNetworkStatsOptions {
+    /** Cap on signatures fetched in one call. Defaults to 1000 (RPC max). */
+    limit?: number;
+    /** Page backwards from this signature for historical scans. */
+    before?: Signature;
+    /** Parallel `getTransaction` calls. Defaults to `DEFAULTS.QUERY_MAX_CONCURRENCY`. */
+    concurrency?: number;
+}
+/**
+ * Enumerate every elisym payment transaction reachable from the protocol tag
+ * pubkey and aggregate gross volume + count.
+ *
+ * Implementation detail: for SPL txs we sum positive token-balance deltas per
+ * mint (ignores ATA rent that would inflate native lamport deltas in the same
+ * tx). For native SOL txs we sum positive lamport deltas across all non-payer
+ * accounts - elisym native txs only emit provider + optional fee transfers,
+ * so this equals gross volume. The `tx_fee` paid by the fee-payer never shows
+ * up as a positive delta, so it is naturally excluded.
+ */
+declare function aggregateNetworkStats(rpc: Rpc<SolanaRpcApi>, options?: AggregateNetworkStatsOptions): Promise<NetworkStatsResult>;
+
 /**
  * Snapshot of the on-chain elisym-config program state.
  *
@@ -1013,6 +1065,18 @@ declare const PROTOCOL_TREASURY: Address;
  * treasury address, and admin rotation state. Read via `getProtocolConfig`.
  */
 declare const PROTOCOL_PROGRAM_ID_DEVNET: Address;
+/**
+ * Read-only marker pubkey attached as a non-signer account to every elisym
+ * payment transaction. Lets indexers enumerate every elisym tx network-wide
+ * via a single `getSignaturesForAddress(ELISYM_PROTOCOL_TAG)` call,
+ * independent of fee size or recipient.
+ *
+ * The account does not need to exist on-chain; including its pubkey as an
+ * extra read-only account in the provider transfer instruction is enough for
+ * Solana's tx-by-account index to pick it up. The corresponding secret key
+ * was generated and discarded - the tag never signs and never holds funds.
+ */
+declare const ELISYM_PROTOCOL_TAG: Address;
 type ProtocolCluster = 'devnet' | 'mainnet' | 'localnet';
 /**
  * Resolve the elisym-config program ID for a given Solana cluster.
@@ -1048,4 +1112,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, 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 };
+export { type Agent, type AggregateNetworkStatsOptions, Asset, BoundedSet, type BuildTransactionOptions, type CapabilityCard, DEFAULTS, DEFAULT_KIND_OFFSET, DEFAULT_REDACT_PATHS, DiscoveryService, ELISYM_PROTOCOL_TAG, ElisymClient, type ElisymClientConfig, type ElisymClientFullConfig, ElisymIdentity, type EstimatePriorityFeeOptions, type EstimateSolFeeOptions, type GetProtocolConfigOptions, INPUT_REDACT_PATHS, type Job, type 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, type NetworkStatsResult, 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, aggregateNetworkStats, 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

@@ -1,4 +1,4 @@
-import { Address, TransactionSigner, Rpc, SolanaRpcApi } from '@solana/kit';
+import { Address, TransactionSigner, Rpc, SolanaRpcApi, Signature } from '@solana/kit';
 import { Filter, Event } from 'nostr-tools';
 import { A as Asset } from './assets-C-nzSYD4.js';
 export { C as Chain, K as KNOWN_ASSETS, N as NATIVE_SOL, U as USDC_SOLANA_DEVNET, a as assetByKey, b as assetKey, f as formatAssetAmount, p as parseAssetAmount, r as resolveAssetFromPaymentRequest, c as resolveKnownAsset } from './assets-C-nzSYD4.js';
@@ -183,8 +183,6 @@ interface PaymentValidationError {
     message: string;
 }
 interface NetworkStats {
-    totalAgentCount: number;
-    agentCount: number;
     jobCount: number;
     totalLamports: number;
 }
@@ -285,6 +283,14 @@ interface BuildTransactionOptions {
      * quartile (default), 90 = aggressive.
      */
     priorityFeePercentile?: number;
+    /**
+     * Nostr job request event id (hex) to embed in an SPL Memo instruction
+     * with payload `elisym:v1:<jobEventId>`. Off-chain indexers join the memo
+     * back to the originating job for per-provider/per-capability analytics.
+     * Memo is omitted when this option is absent; the protocol tag is still
+     * attached either way.
+     */
+    jobEventId?: string;
 }
 
 declare class NostrPool {
@@ -358,8 +364,6 @@ declare function compareAgentsByRank(a: Agent, b: Agent): number;
 declare class DiscoveryService {
     private pool;
     constructor(pool: NostrPool);
-    /** Count elisym agents (kind:31990 with "elisym" tag). */
-    fetchAllAgentCount(): Promise<number>;
     /**
      * Fetch a single page of elisym agents with relay-side pagination.
      * Uses `until` cursor for Nostr cursor-based pagination.
@@ -381,18 +385,20 @@ declare class DiscoveryService {
      *
      * Ranking algorithm:
      * 1. Bucket each agent into 1-minute slots by `lastPaidJobAt` (newest
-     *    `payment-completed` feedback timestamp). Cold-start agents go into a
-     *    sentinel bucket below all populated buckets.
+     *    `payment-completed` feedback timestamp, gated by a matching kind:6xxx
+     *    result from the provider on the same job event). Cold-start agents 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).
      *
-     * NOTE: We trust the `payment-completed` feedback timestamp directly; we do
-     * not verify the embedded `tx` signature on-chain. Public Solana devnet RPC
-     * rate-limits trivially exceed what discovery needs (N agents * up-to-5
-     * candidates), and the resulting 429s blocked discovery entirely. This
-     * means a malicious customer can publish a fake `payment-completed` to lift
-     * an agent's ranking. Acceptable trade-off for devnet / MVP; tighten via
-     * recipient-tied checks when the network moves to mainnet with a paid RPC
+     * NOTE: We do not verify the `tx` signature on-chain - public Solana devnet
+     * RPC rate-limits trivially exceed what discovery needs (N agents * up-to-5
+     * candidates), and the resulting 429s blocked discovery entirely. As a
+     * lighter sybil mitigation we cross-check `payment-completed` feedback
+     * against a kind:6xxx result event authored by the provider on the same
+     * job: a customer can publish a fake `payment-completed`, but they cannot
+     * forge a result event signed by the provider. Tighten with recipient-tied
+     * on-chain checks when the network moves to mainnet with a paid RPC
      * provider.
      */
     fetchAgents(network?: Network, limit?: number): Promise<Agent[]>;
@@ -589,12 +595,24 @@ declare class SolanaPaymentStrategy implements PaymentStrategy {
  *      extra read-only account (canonical Solana Pay pattern);
  *   4. `TransferChecked` from payer ATA to treasury ATA if a fee applies.
  *
+ * Every provider transfer instruction also carries `ELISYM_PROTOCOL_TAG` as a
+ * read-only marker account so off-chain indexers can enumerate every elisym
+ * transaction with a single `getSignaturesForAddress(ELISYM_PROTOCOL_TAG)`
+ * call, regardless of fee size.
+ *
+ * If `options.jobEventId` is provided, an SPL Memo instruction with payload
+ * `elisym:v1:<jobEventId>` is prepended so explorers display the originating
+ * Nostr job id and indexers can join on-chain payments back to off-chain
+ * job context.
+ *
  * Async because SPL ATAs are PDAs and `findAssociatedTokenPda` is async.
  *
  * Caller is responsible for validating `paymentRequest` upstream;
  * `buildTransaction` already does that before invoking this helper.
  */
-declare function buildPaymentInstructions(paymentRequest: PaymentRequestData, payerSigner: Signer): Promise<readonly unknown[]>;
+declare function buildPaymentInstructions(paymentRequest: PaymentRequestData, payerSigner: Signer, options?: {
+    jobEventId?: string;
+}): Promise<readonly unknown[]>;
 /**
  * Convenience wrapper: fetch the on-chain protocol config first, then build a
  * payment request using its current fee/treasury values.
@@ -836,6 +854,40 @@ interface QuickVerifyResult {
 declare function clearQuickVerifyCache(): void;
 declare function verifyJobPaymentQuick(rpc: Rpc<SolanaRpcApi>, txSignature: string, expectedRecipient: Address): Promise<QuickVerifyResult>;
 
+/**
+ * Aggregated on-chain stats across the entire elisym network. Volume is
+ * keyed by `'native'` for SOL or by SPL mint address; values are subunits
+ * (lamports for native, raw token units for SPL).
+ */
+interface NetworkStatsResult {
+    jobCount: number;
+    volumeByAsset: Record<string, bigint>;
+    /** Most-recent signature returned by the RPC (use as cursor for forward sync). */
+    latestSignature?: string;
+    /** Oldest signature scanned in this batch (use as `before` for next page). */
+    oldestSignature?: string;
+}
+interface AggregateNetworkStatsOptions {
+    /** Cap on signatures fetched in one call. Defaults to 1000 (RPC max). */
+    limit?: number;
+    /** Page backwards from this signature for historical scans. */
+    before?: Signature;
+    /** Parallel `getTransaction` calls. Defaults to `DEFAULTS.QUERY_MAX_CONCURRENCY`. */
+    concurrency?: number;
+}
+/**
+ * Enumerate every elisym payment transaction reachable from the protocol tag
+ * pubkey and aggregate gross volume + count.
+ *
+ * Implementation detail: for SPL txs we sum positive token-balance deltas per
+ * mint (ignores ATA rent that would inflate native lamport deltas in the same
+ * tx). For native SOL txs we sum positive lamport deltas across all non-payer
+ * accounts - elisym native txs only emit provider + optional fee transfers,
+ * so this equals gross volume. The `tx_fee` paid by the fee-payer never shows
+ * up as a positive delta, so it is naturally excluded.
+ */
+declare function aggregateNetworkStats(rpc: Rpc<SolanaRpcApi>, options?: AggregateNetworkStatsOptions): Promise<NetworkStatsResult>;
+
 /**
  * Snapshot of the on-chain elisym-config program state.
  *
@@ -1013,6 +1065,18 @@ declare const PROTOCOL_TREASURY: Address;
  * treasury address, and admin rotation state. Read via `getProtocolConfig`.
  */
 declare const PROTOCOL_PROGRAM_ID_DEVNET: Address;
+/**
+ * Read-only marker pubkey attached as a non-signer account to every elisym
+ * payment transaction. Lets indexers enumerate every elisym tx network-wide
+ * via a single `getSignaturesForAddress(ELISYM_PROTOCOL_TAG)` call,
+ * independent of fee size or recipient.
+ *
+ * The account does not need to exist on-chain; including its pubkey as an
+ * extra read-only account in the provider transfer instruction is enough for
+ * Solana's tx-by-account index to pick it up. The corresponding secret key
+ * was generated and discarded - the tag never signs and never holds funds.
+ */
+declare const ELISYM_PROTOCOL_TAG: Address;
 type ProtocolCluster = 'devnet' | 'mainnet' | 'localnet';
 /**
  * Resolve the elisym-config program ID for a given Solana cluster.
@@ -1048,4 +1112,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, 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 };
+export { type Agent, type AggregateNetworkStatsOptions, Asset, BoundedSet, type BuildTransactionOptions, type CapabilityCard, DEFAULTS, DEFAULT_KIND_OFFSET, DEFAULT_REDACT_PATHS, DiscoveryService, ELISYM_PROTOCOL_TAG, ElisymClient, type ElisymClientConfig, type ElisymClientFullConfig, ElisymIdentity, type EstimatePriorityFeeOptions, type EstimateSolFeeOptions, type GetProtocolConfigOptions, INPUT_REDACT_PATHS, type Job, type 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, type NetworkStatsResult, 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, aggregateNetworkStats, 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,3 +1,4 @@
+import { getAddMemoInstruction } from '@solana-program/memo';
 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, isAddress, getProgramDerivedAddress, assertAccountExists, getAddressDecoder, fetchEncodedAccount, decodeAccount, getStructDecoder, fixDecoderSize, getBytesDecoder, getU8Decoder, getOptionDecoder, getU16Decoder, getBooleanDecoder, getI64Decoder } from '@solana/kit';
@@ -39,6 +40,7 @@ var LAMPORTS_PER_SOL = 1e9;
 var PROTOCOL_FEE_BPS = 300;
 var PROTOCOL_TREASURY = "GY7vnWMkKpftU4nQ16C2ATkj1JwrQpHhknkaBUn67VTy";
 var PROTOCOL_PROGRAM_ID_DEVNET = "BrX1CRkSgvcjxBvc2bgc3QqgWjinusofDmeP7ZVxvwrE";
+var ELISYM_PROTOCOL_TAG = "ELiZksgwDt41LaeuPDLkUfWgFXhGgVayTMP7L5nTSEL8";
 function getProtocolProgramId(cluster) {
   switch (cluster) {
     case "devnet":
@@ -94,13 +96,13 @@ function decodeConfig(encodedAccount) {
     getConfigDecoder()
   );
 }
-async function fetchConfig(rpc, address3, config) {
-  const maybeAccount = await fetchMaybeConfig(rpc, address3, config);
+async function fetchConfig(rpc, address4, config) {
+  const maybeAccount = await fetchMaybeConfig(rpc, address4, config);
   assertAccountExists(maybeAccount);
   return maybeAccount;
 }
-async function fetchMaybeConfig(rpc, address3, config) {
-  const maybeAccount = await fetchEncodedAccount(rpc, address3, config);
+async function fetchMaybeConfig(rpc, address4, config) {
+  const maybeAccount = await fetchEncodedAccount(rpc, address4, config);
   return decodeConfig(maybeAccount);
 }
 if (process.env.NODE_ENV !== "production") ;
@@ -572,7 +574,9 @@ var SolanaPaymentStrategy = class {
     if (!Number.isInteger(computeUnitLimit) || computeUnitLimit <= 0) {
       throw new Error(`Invalid computeUnitLimit: ${computeUnitLimit}. Must be a positive integer.`);
     }
-    const paymentInstructions = await buildPaymentInstructions(paymentRequest, payerSigner);
+    const paymentInstructions = await buildPaymentInstructions(paymentRequest, payerSigner, {
+      jobEventId: options?.jobEventId
+    });
     const priorityFeeMicroLamports = options?.priorityFeeMicroLamports ?? await estimatePriorityFeeMicroLamports(rpc, {
       percentile: options?.priorityFeePercentile ?? DEFAULT_PRIORITY_FEE_PERCENTILE
     });
@@ -869,9 +873,10 @@ function bigIntDelta(post, pre) {
 function waitMs(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
-async function buildPaymentInstructions(paymentRequest, payerSigner) {
+async function buildPaymentInstructions(paymentRequest, payerSigner, options) {
   const recipient = address(paymentRequest.recipient);
   const reference = address(paymentRequest.reference);
+  const protocolTag = address(ELISYM_PROTOCOL_TAG);
   const feeAmount = paymentRequest.fee_amount ?? 0;
   const providerAmount = paymentRequest.fee_address && feeAmount > 0 ? paymentRequest.amount - feeAmount : paymentRequest.amount;
   if (providerAmount <= 0) {
@@ -879,6 +884,7 @@ async function buildPaymentInstructions(paymentRequest, payerSigner) {
       `Fee amount (${feeAmount}) exceeds or equals total amount (${paymentRequest.amount}). Cannot create transaction with non-positive provider amount.`
     );
   }
+  const memoInstruction = options?.jobEventId ? getAddMemoInstruction({ memo: `elisym:v1:${options.jobEventId}` }) : null;
   const asset = resolveAssetFromPaymentRequest(paymentRequest);
   if (!asset.mint) {
     const providerTransferIx2 = getTransferSolInstruction({
@@ -886,14 +892,19 @@ async function buildPaymentInstructions(paymentRequest, payerSigner) {
       destination: recipient,
       amount: BigInt(providerAmount)
     });
-    const providerTransferIxWithReference2 = {
+    const providerTransferIxWithMarkers2 = {
       ...providerTransferIx2,
       accounts: [
         ...providerTransferIx2.accounts,
-        { address: reference, role: AccountRole.READONLY }
+        { address: reference, role: AccountRole.READONLY },
+        { address: protocolTag, role: AccountRole.READONLY }
       ]
     };
-    const instructions2 = [providerTransferIxWithReference2];
+    const instructions2 = [];
+    if (memoInstruction) {
+      instructions2.push(memoInstruction);
+    }
+    instructions2.push(providerTransferIxWithMarkers2);
     if (paymentRequest.fee_address && feeAmount > 0) {
       instructions2.push(
         getTransferSolInstruction({
@@ -918,6 +929,9 @@ async function buildPaymentInstructions(paymentRequest, payerSigner) {
     mint
   });
   const instructions = [];
+  if (memoInstruction) {
+    instructions.push(memoInstruction);
+  }
   instructions.push(
     getCreateAssociatedTokenIdempotentInstruction(
       {
@@ -957,11 +971,15 @@ async function buildPaymentInstructions(paymentRequest, payerSigner) {
     amount: BigInt(providerAmount),
     decimals: asset.decimals
   });
-  const providerTransferIxWithReference = {
+  const providerTransferIxWithMarkers = {
     ...providerTransferIx,
-    accounts: [...providerTransferIx.accounts, { address: reference, role: AccountRole.READONLY }]
+    accounts: [
+      ...providerTransferIx.accounts,
+      { address: reference, role: AccountRole.READONLY },
+      { address: protocolTag, role: AccountRole.READONLY }
+    ]
   };
-  instructions.push(providerTransferIxWithReference);
+  instructions.push(providerTransferIxWithMarkers);
   if (treasuryAta && paymentRequest.fee_address && feeAmount > 0) {
     instructions.push(
       getTransferCheckedInstruction({
@@ -1116,21 +1134,6 @@ var DiscoveryService = class {
   constructor(pool) {
     this.pool = pool;
   }
-  /** Count elisym agents (kind:31990 with "elisym" tag). */
-  async fetchAllAgentCount() {
-    const events = await this.pool.querySync({
-      kinds: [KIND_APP_HANDLER],
-      "#t": ["elisym"]
-    });
-    const uniquePubkeys = /* @__PURE__ */ new Set();
-    for (const event of events) {
-      if (!verifyEvent(event)) {
-        continue;
-      }
-      uniquePubkeys.add(event.pubkey);
-    }
-    return uniquePubkeys.size;
-  }
   /**
    * Fetch a single page of elisym agents with relay-side pagination.
    * Uses `until` cursor for Nostr cursor-based pagination.
@@ -1211,18 +1214,20 @@ var DiscoveryService = class {
    *
    * Ranking algorithm:
    * 1. Bucket each agent into 1-minute slots by `lastPaidJobAt` (newest
-   *    `payment-completed` feedback timestamp). Cold-start agents go into a
-   *    sentinel bucket below all populated buckets.
+   *    `payment-completed` feedback timestamp, gated by a matching kind:6xxx
+   *    result from the provider on the same job event). Cold-start agents 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).
    *
-   * NOTE: We trust the `payment-completed` feedback timestamp directly; we do
-   * not verify the embedded `tx` signature on-chain. Public Solana devnet RPC
-   * rate-limits trivially exceed what discovery needs (N agents * up-to-5
-   * candidates), and the resulting 429s blocked discovery entirely. This
-   * means a malicious customer can publish a fake `payment-completed` to lift
-   * an agent's ranking. Acceptable trade-off for devnet / MVP; tighten via
-   * recipient-tied checks when the network moves to mainnet with a paid RPC
+   * NOTE: We do not verify the `tx` signature on-chain - public Solana devnet
+   * RPC rate-limits trivially exceed what discovery needs (N agents * up-to-5
+   * candidates), and the resulting 429s blocked discovery entirely. As a
+   * lighter sybil mitigation we cross-check `payment-completed` feedback
+   * against a kind:6xxx result event authored by the provider on the same
+   * job: a customer can publish a fake `payment-completed`, but they cannot
+   * forge a result event signed by the provider. Tighten with recipient-tied
+   * on-chain checks when the network moves to mainnet with a paid RPC
    * provider.
    */
   async fetchAgents(network = "devnet", limit) {
@@ -1265,14 +1270,27 @@ var DiscoveryService = class {
       ),
       this.enrichWithMetadata(agents)
     ]);
+    const deliveredJobsByProvider = /* @__PURE__ */ new Map();
     for (const ev of resultEvents) {
       if (!verifyEvent(ev)) {
         continue;
       }
       const agent = agentMap.get(ev.pubkey);
-      if (agent && ev.created_at > agent.lastSeen) {
+      if (!agent) {
+        continue;
+      }
+      if (ev.created_at > agent.lastSeen) {
         agent.lastSeen = ev.created_at;
       }
+      const jobEventId = ev.tags.find((t) => t[0] === "e")?.[1];
+      if (jobEventId) {
+        let delivered = deliveredJobsByProvider.get(ev.pubkey);
+        if (!delivered) {
+          delivered = /* @__PURE__ */ new Set();
+          deliveredJobsByProvider.set(ev.pubkey, delivered);
+        }
+        delivered.add(jobEventId);
+      }
     }
     for (const ev of feedbackEvents) {
       if (!verifyEvent(ev)) {
@@ -1299,7 +1317,9 @@ var DiscoveryService = class {
       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 jobEventId = ev.tags.find((t) => t[0] === "e")?.[1];
+      const hasDeliveredResult = jobEventId !== void 0 && deliveredJobsByProvider.get(targetPubkey)?.has(jobEventId) === true;
+      if (status === "payment-completed" && typeof txSignature === "string" && txSignature && hasDeliveredResult) {
         if (!agent.lastPaidJobAt || ev.created_at > agent.lastPaidJobAt) {
           agent.lastPaidJobAt = ev.created_at;
           agent.lastPaidJobTx = txSignature;
@@ -2876,6 +2896,83 @@ async function doVerifyOnce(rpc, txSignature, expectedRecipient) {
   }
   return { verified: false, txSignature: sigStr, reason: "recipient_mismatch" };
 }
+var DEFAULT_LIMIT = 1e3;
+var NATIVE_KEY = "native";
+async function aggregateNetworkStats(rpc, options) {
+  const limit = options?.limit ?? DEFAULT_LIMIT;
+  const concurrency = options?.concurrency ?? DEFAULTS.QUERY_MAX_CONCURRENCY;
+  const tag = address(ELISYM_PROTOCOL_TAG);
+  const signatures = await rpc.getSignaturesForAddress(tag, { limit, before: options?.before }).send();
+  const validSigs = signatures.filter((entry) => entry.err === null);
+  if (validSigs.length === 0) {
+    return { jobCount: 0, volumeByAsset: {} };
+  }
+  const volumeByAsset = {};
+  let jobCount = 0;
+  for (let start = 0; start < validSigs.length; start += concurrency) {
+    const batch = validSigs.slice(start, start + concurrency);
+    const txResults = await Promise.all(
+      batch.map(
+        (entry) => rpc.getTransaction(entry.signature, {
+          commitment: "confirmed",
+          encoding: "json",
+          maxSupportedTransactionVersion: 0
+        }).send().catch(() => null)
+      )
+    );
+    for (const tx of txResults) {
+      if (!tx?.meta || tx.meta.err) {
+        continue;
+      }
+      jobCount += 1;
+      accumulateTransfers(tx, volumeByAsset);
+    }
+  }
+  const latest = validSigs[0]?.signature;
+  const oldest = validSigs.at(-1)?.signature;
+  return {
+    jobCount,
+    volumeByAsset,
+    latestSignature: latest,
+    oldestSignature: oldest
+  };
+}
+function accumulateTransfers(tx, volumeByAsset) {
+  const raw = tx;
+  const meta = raw.meta;
+  if (!meta) {
+    return;
+  }
+  const preTokens = meta.preTokenBalances ?? [];
+  const postTokens = meta.postTokenBalances ?? [];
+  const isSpl = postTokens.length > 0 || preTokens.length > 0;
+  if (isSpl) {
+    accumulateSplDeltas(preTokens, postTokens, volumeByAsset);
+    return;
+  }
+  accumulateNativeDeltas(meta.preBalances, meta.postBalances, volumeByAsset);
+}
+function accumulateSplDeltas(pre, post, volumeByAsset) {
+  for (const postEntry of post) {
+    const preEntry = pre.find((entry) => entry.accountIndex === postEntry.accountIndex);
+    const preAmount = preEntry ? BigInt(preEntry.uiTokenAmount.amount) : 0n;
+    const postAmount = BigInt(postEntry.uiTokenAmount.amount);
+    const delta = postAmount - preAmount;
+    if (delta > 0n) {
+      volumeByAsset[postEntry.mint] = (volumeByAsset[postEntry.mint] ?? 0n) + delta;
+    }
+  }
+}
+function accumulateNativeDeltas(pre, post, volumeByAsset) {
+  for (let i = 1; i < post.length; i++) {
+    const preValue = pre[i] ?? 0n;
+    const postValue = post[i] ?? 0n;
+    const delta = BigInt(postValue) - BigInt(preValue);
+    if (delta > 0n) {
+      volumeByAsset[NATIVE_KEY] = (volumeByAsset[NATIVE_KEY] ?? 0n) + delta;
+    }
+  }
+}
 var SessionSpendLimitEntrySchema = z.object({
   chain: z.enum(["solana"]),
   token: z.string().min(1).max(16).regex(/^[a-z0-9]+$/, "token must be lowercase alphanumeric"),
@@ -3076,6 +3173,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, 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 };
+export { BoundedSet, DEFAULTS, DEFAULT_KIND_OFFSET, DEFAULT_REDACT_PATHS, DiscoveryService, ELISYM_PROTOCOL_TAG, 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, aggregateNetworkStats, 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