@elisym/sdk 0.3.2 → 0.4.0

package/dist/index.d.cts

@@ -1,41 +1,75 @@
+import { Address, TransactionSigner, Rpc, SolanaRpcApi } from '@solana/kit';
 import { P as PaymentRequestData, a as PaymentValidationError, V as VerifyOptions, b as VerifyResult, S as SubCloser, N as Network, A as Agent, E as ElisymIdentity, C as CapabilityCard, c as SubmitJobOptions, J as JobSubscriptionOptions, d as Job, e as PingResult, f as ElisymClientConfig, g as AgentConfig } from './types-CII4k_8d.cjs';
 export { h as Capability, I as Identity, i as JobStatus, j as JobUpdateCallbacks, L as LlmConfig, k as NetworkStats, l as PaymentAddress, m as PaymentInfo, n as PaymentValidationCode, W as WalletConfig } from './types-CII4k_8d.cjs';
 import { Filter, Event } from 'nostr-tools';
-import { Transaction } from '@solana/web3.js';
 
+/**
+ * Protocol fee + treasury inputs for building a payment request.
+ *
+ * In Phase 2 the SDK no longer reads PROTOCOL_FEE_BPS / PROTOCOL_TREASURY
+ * from constants. Callers supply this config so they can either pass
+ * the bundled fallbacks or, in Phase 3, values fetched from the on-chain
+ * elisym-config program.
+ */
+interface ProtocolConfigInput {
+    /** Protocol fee in basis points (300 = 3%). Must be a non-negative integer. */
+    feeBps: number;
+    /** Solana address of the protocol treasury. */
+    treasury: Address;
+}
 /**
  * Pluggable payment strategy interface.
  * Implement this for each payment chain (Solana, Lightning, Cashu, EVM).
+ *
+ * The interface is intentionally generic about the on-chain transaction type
+ * (`unknown` for build/verify inputs) so future chains can plug in without
+ * pulling Solana types into shared code paths.
  */
 interface PaymentStrategy {
     readonly chain: string;
     /** Calculate protocol fee using basis-point math. */
-    calculateFee(amount: number): number;
+    calculateFee(amount: number, config: ProtocolConfigInput): number;
     /** Create a payment request with auto-calculated protocol fee. */
-    createPaymentRequest(recipientAddress: string, amount: number, expirySecs?: number): PaymentRequestData;
+    createPaymentRequest(recipientAddress: string, amount: number, config: ProtocolConfigInput, options?: {
+        expirySecs?: number;
+    }): PaymentRequestData;
     /**
      * 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, expectedRecipient?: string): PaymentValidationError | null;
+    validatePaymentRequest(requestJson: string, config: ProtocolConfigInput, expectedRecipient?: string): PaymentValidationError | null;
     /**
-     * Build an unsigned transaction from a payment request.
-     * Returns chain-specific transaction type. The caller is responsible for signing and sending.
-     * @example For Solana: `const tx = await strategy.buildTransaction(...) as Transaction;`
+     * 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()`).
      */
-    buildTransaction(payerAddress: string, paymentRequest: PaymentRequestData): Promise<unknown>;
+    buildTransaction(paymentRequest: PaymentRequestData, payerSigner: TransactionSigner, rpc: Rpc<SolanaRpcApi>, config: ProtocolConfigInput): Promise<unknown>;
     /**
      * Verify a payment on-chain.
-     * @param connection Chain-specific connection (e.g. Solana `Connection`).
      */
-    verifyPayment(connection: unknown, paymentRequest: PaymentRequestData, options?: VerifyOptions): Promise<VerifyResult>;
+    verifyPayment(rpc: Rpc<SolanaRpcApi>, paymentRequest: PaymentRequestData, config: ProtocolConfigInput, options?: VerifyOptions): Promise<VerifyResult>;
 }
 
 declare class NostrPool {
     private pool;
     private relays;
     private activeSubscriptions;
+    private resetListeners;
     constructor(relays?: string[]);
+    /**
+     * Register a callback to run after `reset()` completes (new SimplePool in place).
+     * Services that cache pool-derived state (e.g. ping results) must clear it here,
+     * otherwise stale values survive the reconnect. Returns an unsubscribe function.
+     *
+     * Contract:
+     * - Listeners are invoked **synchronously** at the end of `reset()`, in
+     *   registration order. Do not rely on async work inside a listener having
+     *   completed before `reset()` returns.
+     * - Listener exceptions are caught and swallowed so that one faulty listener
+     *   cannot prevent the others from running (or abort the reset itself).
+     *   If a listener needs to surface errors, it must do so out-of-band.
+     */
+    onReset(listener: () => void): () => void;
     /** Query relays synchronously. Returns `[]` on timeout (no error thrown). */
     querySync(filter: Filter): Promise<Event[]>;
     queryBatched(filter: Omit<Filter, 'authors'>, keys: string[], batchSize?: number, maxConcurrency?: number): Promise<Event[]>;
@@ -189,6 +223,20 @@ declare class MediaService {
  * this instance - recreating the service generates a new keypair.
  *
  * Requires `globalThis.crypto` (Node 20+, Bun, browsers).
+ *
+ * Lifetime / cleanup:
+ * - The constructor registers a listener on `pool.onReset()` and never
+ *   unsubscribes. This is intentional: PingService is expected to share its
+ *   lifetime with the NostrPool it is bound to (both live for the lifetime
+ *   of an ElisymClient). If you ever construct a PingService that outlives
+ *   its pool - or vice versa - add an explicit `dispose()` that calls the
+ *   unsubscribe function returned by `pool.onReset()` to avoid leaking a
+ *   reference to this instance through the pool's listener set.
+ * - `clearCache()` drops cached online results but does NOT cancel in-flight
+ *   pings in `pendingPings`. An in-flight ping started before a pool reset
+ *   may return `online: false` even if the new pool is healthy; the next
+ *   ping attempt will go through the fresh subscription and resolve
+ *   correctly.
  */
 declare class PingService {
     private pool;
@@ -197,6 +245,9 @@ declare class PingService {
     private pingCache;
     private pendingPings;
     constructor(pool: NostrPool);
+    /** Drop cached online results. In-flight pings are left alone - they'll
+     * resolve via their own timeouts and remove themselves from `pendingPings`. */
+    clearCache(): void;
     /**
      * Ping an agent via ephemeral Nostr events (kind 20200/20201).
      * Uses a persistent session identity to avoid relay rate-limiting.
@@ -233,33 +284,98 @@ declare class ElisymClient {
 
 declare class SolanaPaymentStrategy implements PaymentStrategy {
     readonly chain = "solana";
-    calculateFee(amount: number): number;
-    createPaymentRequest(recipientAddress: string, amount: number, expirySecs?: number): PaymentRequestData;
-    validatePaymentRequest(requestJson: string, expectedRecipient?: string): PaymentValidationError | null;
+    calculateFee(amount: number, config: ProtocolConfigInput): number;
+    createPaymentRequest(recipientAddress: string, amount: number, config: ProtocolConfigInput, options?: {
+        expirySecs?: number;
+    }): PaymentRequestData;
+    validatePaymentRequest(requestJson: string, config: ProtocolConfigInput, expectedRecipient?: string): PaymentValidationError | null;
     /**
-     * Build an unsigned transaction from a payment request.
-     * The caller must set `recentBlockhash` and `feePayer` on the
-     * returned Transaction before signing and sending.
+     * Build, sign, and return a transaction for the supplied payment request.
+     * The caller is responsible for sending it (e.g. via `rpc.sendTransaction`).
+     *
+     * The provider transfer instruction includes the payment reference as a
+     * read-only, non-signer account so providers can detect the payment via
+     * `getSignaturesForAddress(reference)`.
      */
-    buildTransaction(payerAddress: string, paymentRequest: PaymentRequestData): Promise<Transaction>;
-    verifyPayment(connection: unknown, paymentRequest: PaymentRequestData, options?: VerifyOptions): Promise<VerifyResult>;
+    buildTransaction(paymentRequest: PaymentRequestData, payerSigner: TransactionSigner, rpc: Rpc<SolanaRpcApi>, config: ProtocolConfigInput): Promise<Readonly<unknown>>;
+    verifyPayment(rpc: Rpc<SolanaRpcApi>, paymentRequest: PaymentRequestData, config: ProtocolConfigInput, options?: VerifyOptions): Promise<VerifyResult>;
     private _verifyBySignature;
     private _verifyByReference;
 }
+/**
+ * Build the System program transfer instructions for a payment request.
+ *
+ * Returns the provider-amount transfer (with the payment reference attached
+ * as a read-only, non-signer account) and, if present, the protocol-fee
+ * transfer. Exposed so callers and tests can inspect amounts before signing.
+ *
+ * Caller is responsible for validating `paymentRequest` upstream;
+ * `buildTransaction` already does that before invoking this helper.
+ */
+declare function buildPaymentInstructions(paymentRequest: PaymentRequestData, payerSigner: TransactionSigner): readonly unknown[];
+/**
+ * Convenience wrapper: fetch the on-chain protocol config first, then build a
+ * payment request using its current fee/treasury values.
+ *
+ * Suitable for callers that want to "do the right thing" without managing the
+ * config cache or the SolanaPaymentStrategy instance themselves. Uses the same
+ * cache as `getProtocolConfig`, so back-to-back calls within the TTL only hit
+ * RPC once.
+ */
+declare function createPaymentRequestWithOnchainConfig(rpc: Rpc<SolanaRpcApi>, programId: Address, recipient: string, amount: number, options?: {
+    expirySecs?: number;
+}): Promise<PaymentRequestData>;
 
 /** Assert that a value is a non-negative integer (lamports). */
 declare function assertLamports(value: number, field: string): void;
 /**
- * Calculate protocol fee using Decimal basis-point math (no floats).
- * Returns ceil(amount * PROTOCOL_FEE_BPS / 10000).
- * Safe for amounts up to Number.MAX_SAFE_INTEGER - Decimal handles intermediate values.
+ * Calculate the protocol fee using basis-point math (no floats).
+ * Returns ceil(amount * feeBps / 10000).
+ *
+ * The caller passes the current fee (in basis points). Phase 2 of the
+ * Solana Kit migration removes the implicit dependency on PROTOCOL_FEE_BPS
+ * so callers can supply on-chain or test values.
  */
-declare function calculateProtocolFee(amount: number): number;
+declare function calculateProtocolFee(amount: number, feeBps: number): number;
 /** Validate payment request timestamps. Returns error message or null if valid. */
 declare function validateExpiry(createdAt: number, expirySecs: number): string | null;
 /** Assert that payment request timestamps are valid and not expired. Throws on failure. */
 declare function assertExpiry(createdAt: number, expirySecs: number): void;
 
+/**
+ * Snapshot of the on-chain elisym-config program state.
+ *
+ * `source` reflects how this snapshot was obtained:
+ *   - `onchain`: fresh fetch via RPC.
+ *   - `cache`: served from in-memory cache (still within TTL or stale-while-error).
+ *
+ * If RPC fails and no cached value exists, `getProtocolConfig` throws instead of
+ * returning stale hardcoded defaults - callers must handle the error explicitly.
+ */
+interface ProtocolConfig {
+    programId: Address;
+    feeBps: number;
+    treasury: Address;
+    admin: Address;
+    pendingAdmin: Address | null;
+    paused: boolean;
+    version: number;
+    source: 'onchain' | 'cache';
+}
+declare function clearProtocolConfigCache(): void;
+interface GetProtocolConfigOptions {
+    ttlMs?: number;
+    forceRefresh?: boolean;
+}
+/**
+ * Fetch the protocol config from the on-chain `elisym-config` program.
+ *
+ * Caches per-program-id with a TTL (default 60s). On RPC error, returns the
+ * last known good snapshot from cache. If nothing is cached, throws - callers
+ * must handle the error (e.g. refuse the payment, show a warning).
+ */
+declare function getProtocolConfig(rpc: Rpc<SolanaRpcApi>, programId: Address, options?: GetProtocolConfigOptions): Promise<ProtocolConfig>;
+
 /** Encrypt plaintext using NIP-44 v2 (sender secret key + recipient public key). */
 declare function nip44Encrypt(plaintext: string, senderSk: Uint8Array, recipientPubkey: string): string;
 /** Decrypt ciphertext using NIP-44 v2 (receiver secret key + sender public key). */
@@ -309,10 +425,34 @@ declare function jobResultKind(offset: number): number;
 declare const KIND_PING = 20200;
 declare const KIND_PONG = 20201;
 declare const LAMPORTS_PER_SOL = 1000000000;
-/** Protocol fee in basis points (300 = 3%). */
+/**
+ * @deprecated Fallback only - use `getProtocolConfig(rpc, programId)` for live values.
+ *
+ * Protocol fee in basis points (300 = 3%). Bundled as a default for offline use
+ * and for first-call before the on-chain config has been fetched. The on-chain
+ * `elisym-config` program is the source of truth.
+ */
 declare const PROTOCOL_FEE_BPS = 300;
-/** Solana address of the protocol treasury. */
-declare const PROTOCOL_TREASURY = "GY7vnWMkKpftU4nQ16C2ATkj1JwrQpHhknkaBUn67VTy";
+/**
+ * @deprecated Fallback only - use `getProtocolConfig(rpc, programId)` for live values.
+ *
+ * Solana address of the protocol treasury. Bundled fallback; the on-chain
+ * `elisym-config` program is the source of truth and may rotate this address.
+ */
+declare const PROTOCOL_TREASURY: Address;
+/**
+ * Solana program ID for the elisym protocol config (devnet deployment).
+ *
+ * The Anchor program at this address is the source of truth for fee bps,
+ * treasury address, and admin rotation state. Read via `getProtocolConfig`.
+ */
+declare const PROTOCOL_PROGRAM_ID_DEVNET: Address;
+type ProtocolCluster = 'devnet' | 'mainnet' | 'localnet';
+/**
+ * Resolve the elisym-config program ID for a given Solana cluster.
+ * Mainnet is intentionally unsupported until the program ships there.
+ */
+declare function getProtocolProgramId(cluster: ProtocolCluster): Address;
 /** Default values for timeouts, retries, and batch sizes. */
 declare const DEFAULTS: {
     readonly SUBSCRIPTION_TIMEOUT_MS: 120000;
@@ -342,4 +482,4 @@ declare const LIMITS: {
     readonly MAX_CAPABILITY_LENGTH: 64;
 };
 
-export { Agent, AgentConfig, BoundedSet, CapabilityCard, DEFAULTS, DEFAULT_KIND_OFFSET, DiscoveryService, ElisymClient, ElisymClientConfig, type ElisymClientFullConfig, ElisymIdentity, Job, JobSubscriptionOptions, KIND_APP_HANDLER, KIND_JOB_FEEDBACK, KIND_JOB_REQUEST, KIND_JOB_REQUEST_BASE, KIND_JOB_RESULT, KIND_JOB_RESULT_BASE, KIND_PING, KIND_PONG, LAMPORTS_PER_SOL, LIMITS, MarketplaceService, MediaService, Network, NostrPool, PROTOCOL_FEE_BPS, PROTOCOL_TREASURY, PaymentRequestData, type PaymentStrategy, PaymentValidationError, PingResult, PingService, RELAYS, SolanaPaymentStrategy, SubCloser, SubmitJobOptions, VerifyOptions, VerifyResult, assertExpiry, assertLamports, calculateProtocolFee, formatSol, jobRequestKind, jobResultKind, nip44Decrypt, nip44Encrypt, serializeConfig, timeAgo, toDTag, truncateKey, validateAgentName, validateExpiry };
+export { Agent, AgentConfig, BoundedSet, CapabilityCard, DEFAULTS, DEFAULT_KIND_OFFSET, DiscoveryService, ElisymClient, ElisymClientConfig, type ElisymClientFullConfig, ElisymIdentity, type GetProtocolConfigOptions, Job, JobSubscriptionOptions, KIND_APP_HANDLER, KIND_JOB_FEEDBACK, KIND_JOB_REQUEST, KIND_JOB_REQUEST_BASE, KIND_JOB_RESULT, KIND_JOB_RESULT_BASE, KIND_PING, KIND_PONG, LAMPORTS_PER_SOL, LIMITS, MarketplaceService, MediaService, Network, NostrPool, PROTOCOL_FEE_BPS, PROTOCOL_PROGRAM_ID_DEVNET, PROTOCOL_TREASURY, PaymentRequestData, type PaymentStrategy, PaymentValidationError, PingResult, PingService, type ProtocolCluster, type ProtocolConfig, type ProtocolConfigInput, RELAYS, SolanaPaymentStrategy, SubCloser, SubmitJobOptions, VerifyOptions, VerifyResult, assertExpiry, assertLamports, buildPaymentInstructions, calculateProtocolFee, clearProtocolConfigCache, createPaymentRequestWithOnchainConfig, formatSol, getProtocolConfig, getProtocolProgramId, jobRequestKind, jobResultKind, nip44Decrypt, nip44Encrypt, serializeConfig, timeAgo, toDTag, truncateKey, validateAgentName, validateExpiry };

package/dist/index.d.ts

@@ -1,41 +1,75 @@
+import { Address, TransactionSigner, Rpc, SolanaRpcApi } from '@solana/kit';
 import { P as PaymentRequestData, a as PaymentValidationError, V as VerifyOptions, b as VerifyResult, S as SubCloser, N as Network, A as Agent, E as ElisymIdentity, C as CapabilityCard, c as SubmitJobOptions, J as JobSubscriptionOptions, d as Job, e as PingResult, f as ElisymClientConfig, g as AgentConfig } from './types-CII4k_8d.js';
 export { h as Capability, I as Identity, i as JobStatus, j as JobUpdateCallbacks, L as LlmConfig, k as NetworkStats, l as PaymentAddress, m as PaymentInfo, n as PaymentValidationCode, W as WalletConfig } from './types-CII4k_8d.js';
 import { Filter, Event } from 'nostr-tools';
-import { Transaction } from '@solana/web3.js';
 
+/**
+ * Protocol fee + treasury inputs for building a payment request.
+ *
+ * In Phase 2 the SDK no longer reads PROTOCOL_FEE_BPS / PROTOCOL_TREASURY
+ * from constants. Callers supply this config so they can either pass
+ * the bundled fallbacks or, in Phase 3, values fetched from the on-chain
+ * elisym-config program.
+ */
+interface ProtocolConfigInput {
+    /** Protocol fee in basis points (300 = 3%). Must be a non-negative integer. */
+    feeBps: number;
+    /** Solana address of the protocol treasury. */
+    treasury: Address;
+}
 /**
  * Pluggable payment strategy interface.
  * Implement this for each payment chain (Solana, Lightning, Cashu, EVM).
+ *
+ * The interface is intentionally generic about the on-chain transaction type
+ * (`unknown` for build/verify inputs) so future chains can plug in without
+ * pulling Solana types into shared code paths.
  */
 interface PaymentStrategy {
     readonly chain: string;
     /** Calculate protocol fee using basis-point math. */
-    calculateFee(amount: number): number;
+    calculateFee(amount: number, config: ProtocolConfigInput): number;
     /** Create a payment request with auto-calculated protocol fee. */
-    createPaymentRequest(recipientAddress: string, amount: number, expirySecs?: number): PaymentRequestData;
+    createPaymentRequest(recipientAddress: string, amount: number, config: ProtocolConfigInput, options?: {
+        expirySecs?: number;
+    }): PaymentRequestData;
     /**
      * 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, expectedRecipient?: string): PaymentValidationError | null;
+    validatePaymentRequest(requestJson: string, config: ProtocolConfigInput, expectedRecipient?: string): PaymentValidationError | null;
     /**
-     * Build an unsigned transaction from a payment request.
-     * Returns chain-specific transaction type. The caller is responsible for signing and sending.
-     * @example For Solana: `const tx = await strategy.buildTransaction(...) as Transaction;`
+     * 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()`).
      */
-    buildTransaction(payerAddress: string, paymentRequest: PaymentRequestData): Promise<unknown>;
+    buildTransaction(paymentRequest: PaymentRequestData, payerSigner: TransactionSigner, rpc: Rpc<SolanaRpcApi>, config: ProtocolConfigInput): Promise<unknown>;
     /**
      * Verify a payment on-chain.
-     * @param connection Chain-specific connection (e.g. Solana `Connection`).
      */
-    verifyPayment(connection: unknown, paymentRequest: PaymentRequestData, options?: VerifyOptions): Promise<VerifyResult>;
+    verifyPayment(rpc: Rpc<SolanaRpcApi>, paymentRequest: PaymentRequestData, config: ProtocolConfigInput, options?: VerifyOptions): Promise<VerifyResult>;
 }
 
 declare class NostrPool {
     private pool;
     private relays;
     private activeSubscriptions;
+    private resetListeners;
     constructor(relays?: string[]);
+    /**
+     * Register a callback to run after `reset()` completes (new SimplePool in place).
+     * Services that cache pool-derived state (e.g. ping results) must clear it here,
+     * otherwise stale values survive the reconnect. Returns an unsubscribe function.
+     *
+     * Contract:
+     * - Listeners are invoked **synchronously** at the end of `reset()`, in
+     *   registration order. Do not rely on async work inside a listener having
+     *   completed before `reset()` returns.
+     * - Listener exceptions are caught and swallowed so that one faulty listener
+     *   cannot prevent the others from running (or abort the reset itself).
+     *   If a listener needs to surface errors, it must do so out-of-band.
+     */
+    onReset(listener: () => void): () => void;
     /** Query relays synchronously. Returns `[]` on timeout (no error thrown). */
     querySync(filter: Filter): Promise<Event[]>;
     queryBatched(filter: Omit<Filter, 'authors'>, keys: string[], batchSize?: number, maxConcurrency?: number): Promise<Event[]>;
@@ -189,6 +223,20 @@ declare class MediaService {
  * this instance - recreating the service generates a new keypair.
  *
  * Requires `globalThis.crypto` (Node 20+, Bun, browsers).
+ *
+ * Lifetime / cleanup:
+ * - The constructor registers a listener on `pool.onReset()` and never
+ *   unsubscribes. This is intentional: PingService is expected to share its
+ *   lifetime with the NostrPool it is bound to (both live for the lifetime
+ *   of an ElisymClient). If you ever construct a PingService that outlives
+ *   its pool - or vice versa - add an explicit `dispose()` that calls the
+ *   unsubscribe function returned by `pool.onReset()` to avoid leaking a
+ *   reference to this instance through the pool's listener set.
+ * - `clearCache()` drops cached online results but does NOT cancel in-flight
+ *   pings in `pendingPings`. An in-flight ping started before a pool reset
+ *   may return `online: false` even if the new pool is healthy; the next
+ *   ping attempt will go through the fresh subscription and resolve
+ *   correctly.
  */
 declare class PingService {
     private pool;
@@ -197,6 +245,9 @@ declare class PingService {
     private pingCache;
     private pendingPings;
     constructor(pool: NostrPool);
+    /** Drop cached online results. In-flight pings are left alone - they'll
+     * resolve via their own timeouts and remove themselves from `pendingPings`. */
+    clearCache(): void;
     /**
      * Ping an agent via ephemeral Nostr events (kind 20200/20201).
      * Uses a persistent session identity to avoid relay rate-limiting.
@@ -233,33 +284,98 @@ declare class ElisymClient {
 
 declare class SolanaPaymentStrategy implements PaymentStrategy {
     readonly chain = "solana";
-    calculateFee(amount: number): number;
-    createPaymentRequest(recipientAddress: string, amount: number, expirySecs?: number): PaymentRequestData;
-    validatePaymentRequest(requestJson: string, expectedRecipient?: string): PaymentValidationError | null;
+    calculateFee(amount: number, config: ProtocolConfigInput): number;
+    createPaymentRequest(recipientAddress: string, amount: number, config: ProtocolConfigInput, options?: {
+        expirySecs?: number;
+    }): PaymentRequestData;
+    validatePaymentRequest(requestJson: string, config: ProtocolConfigInput, expectedRecipient?: string): PaymentValidationError | null;
     /**
-     * Build an unsigned transaction from a payment request.
-     * The caller must set `recentBlockhash` and `feePayer` on the
-     * returned Transaction before signing and sending.
+     * Build, sign, and return a transaction for the supplied payment request.
+     * The caller is responsible for sending it (e.g. via `rpc.sendTransaction`).
+     *
+     * The provider transfer instruction includes the payment reference as a
+     * read-only, non-signer account so providers can detect the payment via
+     * `getSignaturesForAddress(reference)`.
      */
-    buildTransaction(payerAddress: string, paymentRequest: PaymentRequestData): Promise<Transaction>;
-    verifyPayment(connection: unknown, paymentRequest: PaymentRequestData, options?: VerifyOptions): Promise<VerifyResult>;
+    buildTransaction(paymentRequest: PaymentRequestData, payerSigner: TransactionSigner, rpc: Rpc<SolanaRpcApi>, config: ProtocolConfigInput): Promise<Readonly<unknown>>;
+    verifyPayment(rpc: Rpc<SolanaRpcApi>, paymentRequest: PaymentRequestData, config: ProtocolConfigInput, options?: VerifyOptions): Promise<VerifyResult>;
     private _verifyBySignature;
     private _verifyByReference;
 }
+/**
+ * Build the System program transfer instructions for a payment request.
+ *
+ * Returns the provider-amount transfer (with the payment reference attached
+ * as a read-only, non-signer account) and, if present, the protocol-fee
+ * transfer. Exposed so callers and tests can inspect amounts before signing.
+ *
+ * Caller is responsible for validating `paymentRequest` upstream;
+ * `buildTransaction` already does that before invoking this helper.
+ */
+declare function buildPaymentInstructions(paymentRequest: PaymentRequestData, payerSigner: TransactionSigner): readonly unknown[];
+/**
+ * Convenience wrapper: fetch the on-chain protocol config first, then build a
+ * payment request using its current fee/treasury values.
+ *
+ * Suitable for callers that want to "do the right thing" without managing the
+ * config cache or the SolanaPaymentStrategy instance themselves. Uses the same
+ * cache as `getProtocolConfig`, so back-to-back calls within the TTL only hit
+ * RPC once.
+ */
+declare function createPaymentRequestWithOnchainConfig(rpc: Rpc<SolanaRpcApi>, programId: Address, recipient: string, amount: number, options?: {
+    expirySecs?: number;
+}): Promise<PaymentRequestData>;
 
 /** Assert that a value is a non-negative integer (lamports). */
 declare function assertLamports(value: number, field: string): void;
 /**
- * Calculate protocol fee using Decimal basis-point math (no floats).
- * Returns ceil(amount * PROTOCOL_FEE_BPS / 10000).
- * Safe for amounts up to Number.MAX_SAFE_INTEGER - Decimal handles intermediate values.
+ * Calculate the protocol fee using basis-point math (no floats).
+ * Returns ceil(amount * feeBps / 10000).
+ *
+ * The caller passes the current fee (in basis points). Phase 2 of the
+ * Solana Kit migration removes the implicit dependency on PROTOCOL_FEE_BPS
+ * so callers can supply on-chain or test values.
  */
-declare function calculateProtocolFee(amount: number): number;
+declare function calculateProtocolFee(amount: number, feeBps: number): number;
 /** Validate payment request timestamps. Returns error message or null if valid. */
 declare function validateExpiry(createdAt: number, expirySecs: number): string | null;
 /** Assert that payment request timestamps are valid and not expired. Throws on failure. */
 declare function assertExpiry(createdAt: number, expirySecs: number): void;
 
+/**
+ * Snapshot of the on-chain elisym-config program state.
+ *
+ * `source` reflects how this snapshot was obtained:
+ *   - `onchain`: fresh fetch via RPC.
+ *   - `cache`: served from in-memory cache (still within TTL or stale-while-error).
+ *
+ * If RPC fails and no cached value exists, `getProtocolConfig` throws instead of
+ * returning stale hardcoded defaults - callers must handle the error explicitly.
+ */
+interface ProtocolConfig {
+    programId: Address;
+    feeBps: number;
+    treasury: Address;
+    admin: Address;
+    pendingAdmin: Address | null;
+    paused: boolean;
+    version: number;
+    source: 'onchain' | 'cache';
+}
+declare function clearProtocolConfigCache(): void;
+interface GetProtocolConfigOptions {
+    ttlMs?: number;
+    forceRefresh?: boolean;
+}
+/**
+ * Fetch the protocol config from the on-chain `elisym-config` program.
+ *
+ * Caches per-program-id with a TTL (default 60s). On RPC error, returns the
+ * last known good snapshot from cache. If nothing is cached, throws - callers
+ * must handle the error (e.g. refuse the payment, show a warning).
+ */
+declare function getProtocolConfig(rpc: Rpc<SolanaRpcApi>, programId: Address, options?: GetProtocolConfigOptions): Promise<ProtocolConfig>;
+
 /** Encrypt plaintext using NIP-44 v2 (sender secret key + recipient public key). */
 declare function nip44Encrypt(plaintext: string, senderSk: Uint8Array, recipientPubkey: string): string;
 /** Decrypt ciphertext using NIP-44 v2 (receiver secret key + sender public key). */
@@ -309,10 +425,34 @@ declare function jobResultKind(offset: number): number;
 declare const KIND_PING = 20200;
 declare const KIND_PONG = 20201;
 declare const LAMPORTS_PER_SOL = 1000000000;
-/** Protocol fee in basis points (300 = 3%). */
+/**
+ * @deprecated Fallback only - use `getProtocolConfig(rpc, programId)` for live values.
+ *
+ * Protocol fee in basis points (300 = 3%). Bundled as a default for offline use
+ * and for first-call before the on-chain config has been fetched. The on-chain
+ * `elisym-config` program is the source of truth.
+ */
 declare const PROTOCOL_FEE_BPS = 300;
-/** Solana address of the protocol treasury. */
-declare const PROTOCOL_TREASURY = "GY7vnWMkKpftU4nQ16C2ATkj1JwrQpHhknkaBUn67VTy";
+/**
+ * @deprecated Fallback only - use `getProtocolConfig(rpc, programId)` for live values.
+ *
+ * Solana address of the protocol treasury. Bundled fallback; the on-chain
+ * `elisym-config` program is the source of truth and may rotate this address.
+ */
+declare const PROTOCOL_TREASURY: Address;
+/**
+ * Solana program ID for the elisym protocol config (devnet deployment).
+ *
+ * The Anchor program at this address is the source of truth for fee bps,
+ * treasury address, and admin rotation state. Read via `getProtocolConfig`.
+ */
+declare const PROTOCOL_PROGRAM_ID_DEVNET: Address;
+type ProtocolCluster = 'devnet' | 'mainnet' | 'localnet';
+/**
+ * Resolve the elisym-config program ID for a given Solana cluster.
+ * Mainnet is intentionally unsupported until the program ships there.
+ */
+declare function getProtocolProgramId(cluster: ProtocolCluster): Address;
 /** Default values for timeouts, retries, and batch sizes. */
 declare const DEFAULTS: {
     readonly SUBSCRIPTION_TIMEOUT_MS: 120000;
@@ -342,4 +482,4 @@ declare const LIMITS: {
     readonly MAX_CAPABILITY_LENGTH: 64;
 };
 
-export { Agent, AgentConfig, BoundedSet, CapabilityCard, DEFAULTS, DEFAULT_KIND_OFFSET, DiscoveryService, ElisymClient, ElisymClientConfig, type ElisymClientFullConfig, ElisymIdentity, Job, JobSubscriptionOptions, KIND_APP_HANDLER, KIND_JOB_FEEDBACK, KIND_JOB_REQUEST, KIND_JOB_REQUEST_BASE, KIND_JOB_RESULT, KIND_JOB_RESULT_BASE, KIND_PING, KIND_PONG, LAMPORTS_PER_SOL, LIMITS, MarketplaceService, MediaService, Network, NostrPool, PROTOCOL_FEE_BPS, PROTOCOL_TREASURY, PaymentRequestData, type PaymentStrategy, PaymentValidationError, PingResult, PingService, RELAYS, SolanaPaymentStrategy, SubCloser, SubmitJobOptions, VerifyOptions, VerifyResult, assertExpiry, assertLamports, calculateProtocolFee, formatSol, jobRequestKind, jobResultKind, nip44Decrypt, nip44Encrypt, serializeConfig, timeAgo, toDTag, truncateKey, validateAgentName, validateExpiry };
+export { Agent, AgentConfig, BoundedSet, CapabilityCard, DEFAULTS, DEFAULT_KIND_OFFSET, DiscoveryService, ElisymClient, ElisymClientConfig, type ElisymClientFullConfig, ElisymIdentity, type GetProtocolConfigOptions, Job, JobSubscriptionOptions, KIND_APP_HANDLER, KIND_JOB_FEEDBACK, KIND_JOB_REQUEST, KIND_JOB_REQUEST_BASE, KIND_JOB_RESULT, KIND_JOB_RESULT_BASE, KIND_PING, KIND_PONG, LAMPORTS_PER_SOL, LIMITS, MarketplaceService, MediaService, Network, NostrPool, PROTOCOL_FEE_BPS, PROTOCOL_PROGRAM_ID_DEVNET, PROTOCOL_TREASURY, PaymentRequestData, type PaymentStrategy, PaymentValidationError, PingResult, PingService, type ProtocolCluster, type ProtocolConfig, type ProtocolConfigInput, RELAYS, SolanaPaymentStrategy, SubCloser, SubmitJobOptions, VerifyOptions, VerifyResult, assertExpiry, assertLamports, buildPaymentInstructions, calculateProtocolFee, clearProtocolConfigCache, createPaymentRequestWithOnchainConfig, formatSol, getProtocolConfig, getProtocolProgramId, jobRequestKind, jobResultKind, nip44Decrypt, nip44Encrypt, serializeConfig, timeAgo, toDTag, truncateKey, validateAgentName, validateExpiry };