@elisym/sdk 0.7.0 → 0.9.0

package/dist/index.d.cts

@@ -1,6 +1,9 @@
 import { Address, TransactionSigner, Rpc, SolanaRpcApi } from '@solana/kit';
 import { Filter, Event } from 'nostr-tools';
+import { A as Asset } from './assets-CMf-v55Z.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-CMf-v55Z.cjs';
 import { z } from 'zod';
+export { G as GlobalConfig, a as GlobalConfigSchema, S as SessionSpendLimitEntry, b as SessionSpendLimitEntrySchema } from './global-schema-CddHP2nk.cjs';
 
 declare class ElisymIdentity {
     private _secretKey;
@@ -36,8 +39,21 @@ interface PaymentInfo {
     chain: string;
     network: string;
     address: string;
-    /** Price in lamports (must be non-negative integer). */
+    /**
+     * Price in subunits of the payment asset (non-negative integer).
+     *
+     * Subunit = smallest indivisible unit: 1 lamport for SOL, 1 "cent" (1e-6 USDC)
+     * for USDC. When `token` is omitted, subunits are lamports (back-compat).
+     */
     job_price?: number;
+    /** Lowercase token id (e.g. 'sol', 'usdc'). Absent => native SOL. */
+    token?: string;
+    /** SPL mint / ERC-20 contract. Undefined for native coin. */
+    mint?: string;
+    /** Subunits per whole (9 for SOL, 6 for USDC). */
+    decimals?: number;
+    /** Display symbol (e.g. 'SOL', 'USDC'). */
+    symbol?: string;
 }
 /** Agent discovered from the network. */
 interface Agent {
@@ -102,9 +118,26 @@ interface PingResult {
     /** The identity used for the ping session - reuse for job submission so pubkeys match. */
     identity: ElisymIdentity | null;
 }
+/**
+ * Wire-shape reference to an asset inside a payment request.
+ *
+ * Same shape as `Asset` minus the display-only `symbol` field. Absent = native
+ * SOL (back-compat for payment requests published before multi-asset support).
+ */
+interface PaymentAssetRef {
+    chain: string;
+    token: string;
+    mint?: string;
+    decimals: number;
+}
 interface PaymentRequestData {
     recipient: string;
-    /** Total amount in lamports (must be positive integer). */
+    /**
+     * Total amount in subunits of the payment asset (must be positive integer).
+     *
+     * - For native SOL (asset absent / `token: 'sol'`): lamports (1e-9 SOL).
+     * - For SPL USDC: 1e-6 USDC.
+     */
     amount: number;
     reference: string;
     description?: string;
@@ -114,6 +147,8 @@ interface PaymentRequestData {
     created_at: number;
     /** Expiry duration in seconds. */
     expiry_secs: number;
+    /** Optional asset identifier. Absent => native SOL (back-compat). */
+    asset?: PaymentAssetRef;
 }
 interface VerifyResult {
     verified: boolean;
@@ -125,7 +160,7 @@ interface VerifyOptions {
     intervalMs?: number;
     txSignature?: string;
 }
-type PaymentValidationCode = 'invalid_json' | 'invalid_amount' | 'missing_recipient' | 'invalid_recipient_address' | 'missing_reference' | 'invalid_reference_address' | 'recipient_mismatch' | 'expired' | 'future_timestamp' | 'fee_address_mismatch' | 'fee_amount_mismatch' | 'missing_fee' | 'invalid_fee_params';
+type PaymentValidationCode = 'invalid_json' | 'invalid_amount' | 'missing_recipient' | 'invalid_recipient_address' | 'missing_reference' | 'invalid_reference_address' | 'recipient_mismatch' | 'expired' | 'future_timestamp' | 'fee_address_mismatch' | 'fee_amount_mismatch' | 'missing_fee' | 'invalid_fee_params' | 'invalid_asset';
 interface PaymentValidationError {
     code: PaymentValidationCode;
     message: string;
@@ -472,6 +507,7 @@ declare class SolanaPaymentStrategy implements PaymentStrategy {
     calculateFee(amount: number, config: ProtocolConfigInput): number;
     createPaymentRequest(recipientAddress: string, amount: number, config: ProtocolConfigInput, options?: {
         expirySecs?: number;
+        asset?: Asset;
     }): PaymentRequestData;
     validatePaymentRequest(requestJson: string, config: ProtocolConfigInput, expectedRecipient?: string, options?: {
         maxAmountLamports?: bigint;
@@ -490,16 +526,26 @@ declare class SolanaPaymentStrategy implements PaymentStrategy {
     private _verifyByReference;
 }
 /**
- * Build the System program transfer instructions for a payment request.
+ * Build the transfer instructions for a payment request.
+ *
+ * For native SOL (no `paymentRequest.asset` or asset=NATIVE_SOL), emits System
+ * program `TransferSol` instructions with the payment reference attached as a
+ * read-only, non-signer account so providers can detect the payment via
+ * `getSignaturesForAddress(reference)`.
+ *
+ * For SPL assets (USDC on Solana), emits:
+ *   1. `CreateAssociatedTokenIdempotent` for the recipient ATA (funded by payer);
+ *   2. `CreateAssociatedTokenIdempotent` for the treasury ATA if a protocol fee applies;
+ *   3. `TransferChecked` from payer ATA to recipient ATA, with `reference` as an
+ *      extra read-only account (canonical Solana Pay pattern);
+ *   4. `TransferChecked` from payer ATA to treasury ATA if a fee applies.
  *
- * 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.
+ * 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): readonly unknown[];
+declare function buildPaymentInstructions(paymentRequest: PaymentRequestData, payerSigner: Signer): Promise<readonly unknown[]>;
 /**
  * Convenience wrapper: fetch the on-chain protocol config first, then build a
  * payment request using its current fee/treasury values.
@@ -565,6 +611,74 @@ interface RecentPrioritizationFeeLike {
 }
 declare function pickPercentileFee(samples: readonly RecentPrioritizationFeeLike[], percentile: number): bigint;
 
+/**
+ * SOL-denominated fee estimator for payment requests.
+ *
+ * For a USDC payment the user still spends SOL to cover the base signature fee,
+ * the priority fee, and (for first-time recipients) the ATA rent-exemption
+ * deposit. Before calling `send_payment` the customer wants to know whether
+ * their SOL balance is sufficient - that's what this helper answers.
+ *
+ * Browser-safe: no Node-specific imports. The web dashboard will use the same
+ * function.
+ */
+
+interface SolFeeEstimate {
+    /** Base per-signature fee. Currently 5000 lamports * 1 signature. */
+    baseFeeLamports: bigint;
+    /**
+     * Priority fee in lamports: `ceil(priorityFeeMicroLamports * computeUnitLimit
+     * / 1_000_000)`. Rounded up so we don't underestimate.
+     */
+    priorityFeeLamports: bigint;
+    /**
+     * Rent-exemption deposit for ATAs that the tx creates.
+     *
+     * 0 for native SOL. For SPL, `rentPerAta * (# of missing ATAs)`: recipient
+     * ATA is missing iff the recipient has never received this token; treasury
+     * ATA is missing only on the first-ever protocol fee into this mint.
+     */
+    rentLamports: bigint;
+    /** `baseFeeLamports + priorityFeeLamports + rentLamports`. */
+    totalLamports: bigint;
+    breakdown: {
+        numSignatures: number;
+        priorityFeeMicroLamports: bigint;
+        computeUnitLimit: number;
+        rentPerAtaLamports: bigint;
+        missingAtaCount: number;
+    };
+}
+interface EstimateSolFeeOptions {
+    /** Override the compute-unit limit used by `buildTransaction`. */
+    computeUnitLimit?: number;
+    /** Override the priority fee directly (skips RPC). */
+    priorityFeeMicroLamports?: bigint;
+    /**
+     * Percentile of the recent priority-fee distribution to charge when
+     * `priorityFeeMicroLamports` is not supplied. Defaults to 75.
+     */
+    priorityFeePercentile?: number;
+    /** Override the number of signatures. Defaults to 1. */
+    numSignatures?: number;
+}
+/**
+ * Estimate the SOL cost (in lamports) to submit the transaction that would pay
+ * this payment request from `payerAddress`.
+ *
+ * Returns a breakdown and a total. Does not submit anything on-chain.
+ */
+declare function estimateSolFeeLamports(rpc: Rpc<SolanaRpcApi>, paymentRequest: PaymentRequestData, _payerAddress: string, options?: EstimateSolFeeOptions): Promise<SolFeeEstimate>;
+/**
+ * Multi-line human-readable breakdown. Used by the MCP `estimate_payment_cost`
+ * tool and (in a future PR) by the web dashboard's pre-payment panel.
+ *
+ * We render lamports as raw integers and also show a SOL decimal with 9 places.
+ * The `@elisym/sdk` `formatAssetAmount` helper lives in assets.ts, but the
+ * formatter does not need to be identical; this stays dependency-free.
+ */
+declare function formatFeeBreakdown(estimate: SolFeeEstimate): string;
+
 /**
  * Wire-shape for a NIP-90 payment_request blob, as parsed via JSON.parse.
  *
@@ -582,6 +696,22 @@ declare const PaymentRequestSchema: z.ZodObject<{
     fee_amount: z.ZodOptional<z.ZodNumber>;
     created_at: z.ZodNumber;
     expiry_secs: z.ZodNumber;
+    asset: z.ZodOptional<z.ZodObject<{
+        chain: z.ZodString;
+        token: z.ZodString;
+        mint: z.ZodOptional<z.ZodString>;
+        decimals: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        chain: string;
+        token: string;
+        decimals: number;
+        mint?: string | undefined;
+    }, {
+        chain: string;
+        token: string;
+        decimals: number;
+        mint?: string | undefined;
+    }>>;
 }, "strip", z.ZodTypeAny, {
     recipient: string;
     amount: number;
@@ -591,6 +721,12 @@ declare const PaymentRequestSchema: z.ZodObject<{
     description?: string | undefined;
     fee_address?: string | undefined;
     fee_amount?: number | undefined;
+    asset?: {
+        chain: string;
+        token: string;
+        decimals: number;
+        mint?: string | undefined;
+    } | undefined;
 }, {
     recipient: string;
     amount: number;
@@ -600,6 +736,12 @@ declare const PaymentRequestSchema: z.ZodObject<{
     description?: string | undefined;
     fee_address?: string | undefined;
     fee_amount?: number | undefined;
+    asset?: {
+        chain: string;
+        token: string;
+        decimals: number;
+        mint?: string | undefined;
+    } | undefined;
 }>;
 type ParsedPaymentRequest = z.infer<typeof PaymentRequestSchema>;
 interface ParseOptions {
@@ -836,4 +978,4 @@ declare const LIMITS: {
     readonly MAX_CAPABILITY_LENGTH: 64;
 };
 
-export { type Agent, BoundedSet, type BuildTransactionOptions, type CapabilityCard, DEFAULTS, DEFAULT_KIND_OFFSET, DEFAULT_REDACT_PATHS, DiscoveryService, ElisymClient, type ElisymClientConfig, type ElisymClientFullConfig, ElisymIdentity, type EstimatePriorityFeeOptions, type GetProtocolConfigOptions, INPUT_REDACT_PATHS, type Job, type JobStatus, type JobSubscriptionOptions, type JobUpdateCallbacks, KIND_APP_HANDLER, KIND_JOB_FEEDBACK, KIND_JOB_REQUEST, KIND_JOB_REQUEST_BASE, KIND_JOB_RESULT, KIND_JOB_RESULT_BASE, KIND_PING, KIND_PONG, LAMPORTS_PER_SOL, LIMITS, MarketplaceService, MediaService, type Network, type NetworkStats, NostrPool, PROTOCOL_FEE_BPS, PROTOCOL_PROGRAM_ID_DEVNET, PROTOCOL_TREASURY, type ParseOptions, type ParseResult, type ParsedPaymentRequest, type PaymentInfo, type PaymentRequestData, PaymentRequestSchema, type PaymentStrategy, type PaymentValidationCode, type PaymentValidationError, type PingResult, PingService, type ProtocolCluster, type ProtocolConfig, type ProtocolConfigInput, RELAYS, type RateLimitDecision, SECRET_REDACT_PATHS, type Signer, type SlidingWindowLimiter, type SlidingWindowLimiterOptions, SolanaPaymentStrategy, type SubCloser, type SubmitJobOptions, type VerifyOptions, type VerifyResult, assertExpiry, assertLamports, buildPaymentInstructions, calculateProtocolFee, clearPriorityFeeCache, clearProtocolConfigCache, createPaymentRequestWithOnchainConfig, createSlidingWindowLimiter, estimatePriorityFeeMicroLamports, formatSol, getProtocolConfig, getProtocolProgramId, jobRequestKind, jobResultKind, makeCensor, nip44Decrypt, nip44Encrypt, parsePaymentRequest, pickPercentileFee, timeAgo, toDTag, truncateKey, validateAgentName, validateExpiry };
+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 };

package/dist/index.d.ts

@@ -1,6 +1,9 @@
 import { Address, TransactionSigner, Rpc, SolanaRpcApi } from '@solana/kit';
 import { Filter, Event } from 'nostr-tools';
+import { A as Asset } from './assets-CMf-v55Z.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-CMf-v55Z.js';
 import { z } from 'zod';
+export { G as GlobalConfig, a as GlobalConfigSchema, S as SessionSpendLimitEntry, b as SessionSpendLimitEntrySchema } from './global-schema-CddHP2nk.js';
 
 declare class ElisymIdentity {
     private _secretKey;
@@ -36,8 +39,21 @@ interface PaymentInfo {
     chain: string;
     network: string;
     address: string;
-    /** Price in lamports (must be non-negative integer). */
+    /**
+     * Price in subunits of the payment asset (non-negative integer).
+     *
+     * Subunit = smallest indivisible unit: 1 lamport for SOL, 1 "cent" (1e-6 USDC)
+     * for USDC. When `token` is omitted, subunits are lamports (back-compat).
+     */
     job_price?: number;
+    /** Lowercase token id (e.g. 'sol', 'usdc'). Absent => native SOL. */
+    token?: string;
+    /** SPL mint / ERC-20 contract. Undefined for native coin. */
+    mint?: string;
+    /** Subunits per whole (9 for SOL, 6 for USDC). */
+    decimals?: number;
+    /** Display symbol (e.g. 'SOL', 'USDC'). */
+    symbol?: string;
 }
 /** Agent discovered from the network. */
 interface Agent {
@@ -102,9 +118,26 @@ interface PingResult {
     /** The identity used for the ping session - reuse for job submission so pubkeys match. */
     identity: ElisymIdentity | null;
 }
+/**
+ * Wire-shape reference to an asset inside a payment request.
+ *
+ * Same shape as `Asset` minus the display-only `symbol` field. Absent = native
+ * SOL (back-compat for payment requests published before multi-asset support).
+ */
+interface PaymentAssetRef {
+    chain: string;
+    token: string;
+    mint?: string;
+    decimals: number;
+}
 interface PaymentRequestData {
     recipient: string;
-    /** Total amount in lamports (must be positive integer). */
+    /**
+     * Total amount in subunits of the payment asset (must be positive integer).
+     *
+     * - For native SOL (asset absent / `token: 'sol'`): lamports (1e-9 SOL).
+     * - For SPL USDC: 1e-6 USDC.
+     */
     amount: number;
     reference: string;
     description?: string;
@@ -114,6 +147,8 @@ interface PaymentRequestData {
     created_at: number;
     /** Expiry duration in seconds. */
     expiry_secs: number;
+    /** Optional asset identifier. Absent => native SOL (back-compat). */
+    asset?: PaymentAssetRef;
 }
 interface VerifyResult {
     verified: boolean;
@@ -125,7 +160,7 @@ interface VerifyOptions {
     intervalMs?: number;
     txSignature?: string;
 }
-type PaymentValidationCode = 'invalid_json' | 'invalid_amount' | 'missing_recipient' | 'invalid_recipient_address' | 'missing_reference' | 'invalid_reference_address' | 'recipient_mismatch' | 'expired' | 'future_timestamp' | 'fee_address_mismatch' | 'fee_amount_mismatch' | 'missing_fee' | 'invalid_fee_params';
+type PaymentValidationCode = 'invalid_json' | 'invalid_amount' | 'missing_recipient' | 'invalid_recipient_address' | 'missing_reference' | 'invalid_reference_address' | 'recipient_mismatch' | 'expired' | 'future_timestamp' | 'fee_address_mismatch' | 'fee_amount_mismatch' | 'missing_fee' | 'invalid_fee_params' | 'invalid_asset';
 interface PaymentValidationError {
     code: PaymentValidationCode;
     message: string;
@@ -472,6 +507,7 @@ declare class SolanaPaymentStrategy implements PaymentStrategy {
     calculateFee(amount: number, config: ProtocolConfigInput): number;
     createPaymentRequest(recipientAddress: string, amount: number, config: ProtocolConfigInput, options?: {
         expirySecs?: number;
+        asset?: Asset;
     }): PaymentRequestData;
     validatePaymentRequest(requestJson: string, config: ProtocolConfigInput, expectedRecipient?: string, options?: {
         maxAmountLamports?: bigint;
@@ -490,16 +526,26 @@ declare class SolanaPaymentStrategy implements PaymentStrategy {
     private _verifyByReference;
 }
 /**
- * Build the System program transfer instructions for a payment request.
+ * Build the transfer instructions for a payment request.
+ *
+ * For native SOL (no `paymentRequest.asset` or asset=NATIVE_SOL), emits System
+ * program `TransferSol` instructions with the payment reference attached as a
+ * read-only, non-signer account so providers can detect the payment via
+ * `getSignaturesForAddress(reference)`.
+ *
+ * For SPL assets (USDC on Solana), emits:
+ *   1. `CreateAssociatedTokenIdempotent` for the recipient ATA (funded by payer);
+ *   2. `CreateAssociatedTokenIdempotent` for the treasury ATA if a protocol fee applies;
+ *   3. `TransferChecked` from payer ATA to recipient ATA, with `reference` as an
+ *      extra read-only account (canonical Solana Pay pattern);
+ *   4. `TransferChecked` from payer ATA to treasury ATA if a fee applies.
  *
- * 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.
+ * 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): readonly unknown[];
+declare function buildPaymentInstructions(paymentRequest: PaymentRequestData, payerSigner: Signer): Promise<readonly unknown[]>;
 /**
  * Convenience wrapper: fetch the on-chain protocol config first, then build a
  * payment request using its current fee/treasury values.
@@ -565,6 +611,74 @@ interface RecentPrioritizationFeeLike {
 }
 declare function pickPercentileFee(samples: readonly RecentPrioritizationFeeLike[], percentile: number): bigint;
 
+/**
+ * SOL-denominated fee estimator for payment requests.
+ *
+ * For a USDC payment the user still spends SOL to cover the base signature fee,
+ * the priority fee, and (for first-time recipients) the ATA rent-exemption
+ * deposit. Before calling `send_payment` the customer wants to know whether
+ * their SOL balance is sufficient - that's what this helper answers.
+ *
+ * Browser-safe: no Node-specific imports. The web dashboard will use the same
+ * function.
+ */
+
+interface SolFeeEstimate {
+    /** Base per-signature fee. Currently 5000 lamports * 1 signature. */
+    baseFeeLamports: bigint;
+    /**
+     * Priority fee in lamports: `ceil(priorityFeeMicroLamports * computeUnitLimit
+     * / 1_000_000)`. Rounded up so we don't underestimate.
+     */
+    priorityFeeLamports: bigint;
+    /**
+     * Rent-exemption deposit for ATAs that the tx creates.
+     *
+     * 0 for native SOL. For SPL, `rentPerAta * (# of missing ATAs)`: recipient
+     * ATA is missing iff the recipient has never received this token; treasury
+     * ATA is missing only on the first-ever protocol fee into this mint.
+     */
+    rentLamports: bigint;
+    /** `baseFeeLamports + priorityFeeLamports + rentLamports`. */
+    totalLamports: bigint;
+    breakdown: {
+        numSignatures: number;
+        priorityFeeMicroLamports: bigint;
+        computeUnitLimit: number;
+        rentPerAtaLamports: bigint;
+        missingAtaCount: number;
+    };
+}
+interface EstimateSolFeeOptions {
+    /** Override the compute-unit limit used by `buildTransaction`. */
+    computeUnitLimit?: number;
+    /** Override the priority fee directly (skips RPC). */
+    priorityFeeMicroLamports?: bigint;
+    /**
+     * Percentile of the recent priority-fee distribution to charge when
+     * `priorityFeeMicroLamports` is not supplied. Defaults to 75.
+     */
+    priorityFeePercentile?: number;
+    /** Override the number of signatures. Defaults to 1. */
+    numSignatures?: number;
+}
+/**
+ * Estimate the SOL cost (in lamports) to submit the transaction that would pay
+ * this payment request from `payerAddress`.
+ *
+ * Returns a breakdown and a total. Does not submit anything on-chain.
+ */
+declare function estimateSolFeeLamports(rpc: Rpc<SolanaRpcApi>, paymentRequest: PaymentRequestData, _payerAddress: string, options?: EstimateSolFeeOptions): Promise<SolFeeEstimate>;
+/**
+ * Multi-line human-readable breakdown. Used by the MCP `estimate_payment_cost`
+ * tool and (in a future PR) by the web dashboard's pre-payment panel.
+ *
+ * We render lamports as raw integers and also show a SOL decimal with 9 places.
+ * The `@elisym/sdk` `formatAssetAmount` helper lives in assets.ts, but the
+ * formatter does not need to be identical; this stays dependency-free.
+ */
+declare function formatFeeBreakdown(estimate: SolFeeEstimate): string;
+
 /**
  * Wire-shape for a NIP-90 payment_request blob, as parsed via JSON.parse.
  *
@@ -582,6 +696,22 @@ declare const PaymentRequestSchema: z.ZodObject<{
     fee_amount: z.ZodOptional<z.ZodNumber>;
     created_at: z.ZodNumber;
     expiry_secs: z.ZodNumber;
+    asset: z.ZodOptional<z.ZodObject<{
+        chain: z.ZodString;
+        token: z.ZodString;
+        mint: z.ZodOptional<z.ZodString>;
+        decimals: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        chain: string;
+        token: string;
+        decimals: number;
+        mint?: string | undefined;
+    }, {
+        chain: string;
+        token: string;
+        decimals: number;
+        mint?: string | undefined;
+    }>>;
 }, "strip", z.ZodTypeAny, {
     recipient: string;
     amount: number;
@@ -591,6 +721,12 @@ declare const PaymentRequestSchema: z.ZodObject<{
     description?: string | undefined;
     fee_address?: string | undefined;
     fee_amount?: number | undefined;
+    asset?: {
+        chain: string;
+        token: string;
+        decimals: number;
+        mint?: string | undefined;
+    } | undefined;
 }, {
     recipient: string;
     amount: number;
@@ -600,6 +736,12 @@ declare const PaymentRequestSchema: z.ZodObject<{
     description?: string | undefined;
     fee_address?: string | undefined;
     fee_amount?: number | undefined;
+    asset?: {
+        chain: string;
+        token: string;
+        decimals: number;
+        mint?: string | undefined;
+    } | undefined;
 }>;
 type ParsedPaymentRequest = z.infer<typeof PaymentRequestSchema>;
 interface ParseOptions {
@@ -836,4 +978,4 @@ declare const LIMITS: {
     readonly MAX_CAPABILITY_LENGTH: 64;
 };
 
-export { type Agent, BoundedSet, type BuildTransactionOptions, type CapabilityCard, DEFAULTS, DEFAULT_KIND_OFFSET, DEFAULT_REDACT_PATHS, DiscoveryService, ElisymClient, type ElisymClientConfig, type ElisymClientFullConfig, ElisymIdentity, type EstimatePriorityFeeOptions, type GetProtocolConfigOptions, INPUT_REDACT_PATHS, type Job, type JobStatus, type JobSubscriptionOptions, type JobUpdateCallbacks, KIND_APP_HANDLER, KIND_JOB_FEEDBACK, KIND_JOB_REQUEST, KIND_JOB_REQUEST_BASE, KIND_JOB_RESULT, KIND_JOB_RESULT_BASE, KIND_PING, KIND_PONG, LAMPORTS_PER_SOL, LIMITS, MarketplaceService, MediaService, type Network, type NetworkStats, NostrPool, PROTOCOL_FEE_BPS, PROTOCOL_PROGRAM_ID_DEVNET, PROTOCOL_TREASURY, type ParseOptions, type ParseResult, type ParsedPaymentRequest, type PaymentInfo, type PaymentRequestData, PaymentRequestSchema, type PaymentStrategy, type PaymentValidationCode, type PaymentValidationError, type PingResult, PingService, type ProtocolCluster, type ProtocolConfig, type ProtocolConfigInput, RELAYS, type RateLimitDecision, SECRET_REDACT_PATHS, type Signer, type SlidingWindowLimiter, type SlidingWindowLimiterOptions, SolanaPaymentStrategy, type SubCloser, type SubmitJobOptions, type VerifyOptions, type VerifyResult, assertExpiry, assertLamports, buildPaymentInstructions, calculateProtocolFee, clearPriorityFeeCache, clearProtocolConfigCache, createPaymentRequestWithOnchainConfig, createSlidingWindowLimiter, estimatePriorityFeeMicroLamports, formatSol, getProtocolConfig, getProtocolProgramId, jobRequestKind, jobResultKind, makeCensor, nip44Decrypt, nip44Encrypt, parsePaymentRequest, pickPercentileFee, timeAgo, toDTag, truncateKey, validateAgentName, validateExpiry };
+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 };