@elisym/sdk 0.8.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.
  *
- * 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.
+ * 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.
+ *
+ * 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 {
@@ -624,48 +766,6 @@ type ParseResult = {
  */
 declare function parsePaymentRequest(input: string, options?: ParseOptions): ParseResult;
 
-/**
- * Multi-asset / multi-chain payment model.
- *
- * `Asset` describes a currency a customer can spend: native coins (SOL, ETH, BTC)
- * or tokens (SPL, ERC-20). `assetKey` produces a stable string id for Map lookups.
- *
- * Today only `NATIVE_SOL` is in `KNOWN_ASSETS`. SPL (USDC) and other chains are
- * extended by adding entries to `KNOWN_ASSETS` and, where relevant, to the
- * MCP `DEFAULT_SESSION_LIMITS` catalogue.
- */
-type Chain = 'solana';
-interface Asset {
-    chain: Chain;
-    /** Lowercase token id: 'sol', 'usdc', 'btc', 'eth'. */
-    token: string;
-    /** SPL mint / ERC-20 contract. Undefined for a native coin. */
-    mint?: string;
-    /** Subunits per whole (9 SOL, 6 USDC, 8 BTC, 18 ETH). */
-    decimals: number;
-    /** Display symbol: 'SOL', 'USDC'. */
-    symbol: string;
-}
-declare const NATIVE_SOL: Asset;
-declare const KNOWN_ASSETS: readonly Asset[];
-/** Stable Map key for `Asset`. Same shape regardless of Asset identity. */
-declare function assetKey(a: Pick<Asset, 'chain' | 'token' | 'mint'>): string;
-/** Find a known asset by (chain, token, mint). Returns undefined if unknown. */
-declare function resolveKnownAsset(chain: string, token: string, mint?: string): Asset | undefined;
-/** Reverse lookup: given an assetKey string, return the known asset or undefined. */
-declare function assetByKey(key: string): Asset | undefined;
-/**
- * Parse a human amount string ("0.5", "1", "0.000001") into raw subunits (BigInt).
- * Uses integer math to avoid float precision issues.
- *
- * Throws on: empty, negative, zero, malformed, too many fractional digits, or
- * a value exceeding `Number.MAX_SAFE_INTEGER` (to keep downstream `Number(...)`
- * call-sites safe).
- */
-declare function parseAssetAmount(asset: Asset, human: string): bigint;
-/** Format raw subunits back to `"<whole>.<frac> <SYMBOL>"`. Keeps all `decimals` digits. */
-declare function formatAssetAmount(asset: Asset, raw: bigint): string;
-
 /**
  * Snapshot of the on-chain elisym-config program state.
  *
@@ -700,73 +800,6 @@ interface GetProtocolConfigOptions {
  */
 declare function getProtocolConfig(rpc: Rpc<SolanaRpcApi>, programId: Address, options?: GetProtocolConfigOptions): Promise<ProtocolConfig>;
 
-/**
- * Global (not per-agent) config stored at `~/.elisym/config.yaml`.
- *
- * Currently holds only session-spend-limit overrides; other top-level fields
- * may be added later. The loader tolerates a missing file (returns `{}`), but
- * fails fast on malformed YAML or schema violations.
- */
-
-declare const SessionSpendLimitEntrySchema: z.ZodObject<{
-    chain: z.ZodEnum<["solana"]>;
-    token: z.ZodString;
-    mint: z.ZodOptional<z.ZodString>;
-    amount: z.ZodNumber;
-}, "strict", z.ZodTypeAny, {
-    amount: number;
-    chain: "solana";
-    token: string;
-    mint?: string | undefined;
-}, {
-    amount: number;
-    chain: "solana";
-    token: string;
-    mint?: string | undefined;
-}>;
-declare const GlobalConfigSchema: z.ZodObject<{
-    session_spend_limits: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        chain: z.ZodEnum<["solana"]>;
-        token: z.ZodString;
-        mint: z.ZodOptional<z.ZodString>;
-        amount: z.ZodNumber;
-    }, "strict", z.ZodTypeAny, {
-        amount: number;
-        chain: "solana";
-        token: string;
-        mint?: string | undefined;
-    }, {
-        amount: number;
-        chain: "solana";
-        token: string;
-        mint?: string | undefined;
-    }>, "many">>;
-}, "strict", z.ZodTypeAny, {
-    session_spend_limits?: {
-        amount: number;
-        chain: "solana";
-        token: string;
-        mint?: string | undefined;
-    }[] | undefined;
-}, {
-    session_spend_limits?: {
-        amount: number;
-        chain: "solana";
-        token: string;
-        mint?: string | undefined;
-    }[] | undefined;
-}>;
-type SessionSpendLimitEntry = z.infer<typeof SessionSpendLimitEntrySchema>;
-type GlobalConfig = z.infer<typeof GlobalConfigSchema>;
-/**
- * Read and validate `~/.elisym/config.yaml`. Returns `{}` if missing. Throws
- * on malformed YAML or schema violations — the MCP server treats these as fatal
- * at startup rather than silently ignoring bad overrides.
- */
-declare function loadGlobalConfig(path: string): Promise<GlobalConfig>;
-/** Write the config YAML atomically. Validates via Zod before writing. */
-declare function writeGlobalConfig(path: string, config: GlobalConfig): Promise<void>;
-
 /** 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). */
@@ -945,4 +978,4 @@ declare const LIMITS: {
     readonly MAX_CAPABILITY_LENGTH: 64;
 };
 
-export { type Agent, type Asset, BoundedSet, type BuildTransactionOptions, type CapabilityCard, type Chain, DEFAULTS, DEFAULT_KIND_OFFSET, DEFAULT_REDACT_PATHS, DiscoveryService, ElisymClient, type ElisymClientConfig, type ElisymClientFullConfig, ElisymIdentity, type EstimatePriorityFeeOptions, type GetProtocolConfigOptions, type GlobalConfig, GlobalConfigSchema, 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, KNOWN_ASSETS, LAMPORTS_PER_SOL, LIMITS, MarketplaceService, MediaService, NATIVE_SOL, 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 SessionSpendLimitEntry, SessionSpendLimitEntrySchema, type Signer, type SlidingWindowLimiter, type SlidingWindowLimiterOptions, SolanaPaymentStrategy, type SubCloser, type SubmitJobOptions, type VerifyOptions, type VerifyResult, assertExpiry, assertLamports, assetByKey, assetKey, buildPaymentInstructions, calculateProtocolFee, clearPriorityFeeCache, clearProtocolConfigCache, createPaymentRequestWithOnchainConfig, createSlidingWindowLimiter, estimatePriorityFeeMicroLamports, formatAssetAmount, formatSol, getProtocolConfig, getProtocolProgramId, jobRequestKind, jobResultKind, loadGlobalConfig, makeCensor, nip44Decrypt, nip44Encrypt, parseAssetAmount, parsePaymentRequest, pickPercentileFee, resolveKnownAsset, timeAgo, toDTag, truncateKey, validateAgentName, validateExpiry, writeGlobalConfig };
+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 };