@alleyboss/micropay-solana-x402-paywall 3.3.7 → 3.3.9

package/dist/index.d.cts

@@ -1,9 +1,101 @@
 export * from '@x402/core';
+import { PaymentPayload, PaymentRequirements, VerifyResponse, SettleResponse, SupportedResponse, Network } from '@x402/core/types';
 export * from '@x402/core/types';
 export * from '@x402/core/client';
 export * from '@x402/svm';
-export { PaymentFlowConfig, PaymentResult, PaymentStatus, PaywallConfig, PaywallState, SendPaymentParams, SolanaPayUrlParams, WalletAdapterInterface, buildSolanaPayUrl, createPaymentFlow, createPaymentReference, createX402AuthorizationHeader, sendSolanaPayment, useFormatPrice, useLamportsToUsd, useMicropay, usePaywallResource, usePricing } from './client/index.cjs';
 export { AgentPaymentResult, CreditSessionClaims, CreditSessionConfig, CreditSessionData, CreditValidation, ExecuteAgentPaymentParams, UseCreditResult, addCredits, createCreditSession, executeAgentPayment, generateAgentKeypair, getAgentBalance, getRemainingCredits, hasAgentSufficientBalance, keypairFromBase58, useCredit, validateCreditSession } from './agent/index.cjs';
 export { CustomPriceProvider, PriceConfig, PriceData, clearPriceCache, configurePricing, formatPriceDisplay, formatPriceSync, getProviders, getSolPrice, lamportsToSol, lamportsToUsd, usdToLamports } from './pricing/index.cjs';
 import '@solana/web3.js';
 import './types-BWYQMw03.cjs';
+
+interface FacilitatorClient {
+    verify(paymentPayload: PaymentPayload, paymentRequirements: PaymentRequirements): Promise<VerifyResponse>;
+    settle(paymentPayload: PaymentPayload, paymentRequirements: PaymentRequirements): Promise<SettleResponse>;
+    getSupported(extensionKeys?: string[]): Promise<SupportedResponse>;
+}
+/**
+ * Local SVM Facilitator
+ *
+ * Verifies and settles Solana payments locally using a direct RPC connection,
+ * bypassing the need for a hosted facilitator service.
+ */
+declare class LocalSvmFacilitator implements FacilitatorClient {
+    readonly scheme = "exact";
+    readonly caipFamily = "solana:*";
+    private connection;
+    constructor(rpcUrl: string);
+    /**
+     * Get supported payment kinds
+     * Mocking the response of the /supported endpoint
+     */
+    /**
+     * Network Constants - CAIP-2 format for x402 v2
+     * These match the official Solana chain IDs used by x402 protocol
+     */
+    private readonly NETWORKS;
+    /**
+     * DUMMY_FEE_PAYER Explanation (for auditors):
+     *
+     * In a HOSTED facilitator (like x402.org), the `feePayer` field in the
+     * SupportedResponse.extra specifies which address will pay transaction fees
+     * when the facilitator submits transactions on behalf of users.
+     *
+     * In LOCAL/SELF-SOVEREIGN mode (this implementation):
+     * - The USER pays their own transaction fees directly
+     * - The facilitator NEVER submits transactions - it only VERIFIES them
+     * - Therefore, no fee payer address is actually used
+     *
+     * However, the x402 protocol REQUIRES this field in the response schema.
+     * We use the System Program address (all 1s) as a placeholder because:
+     * 1. It's clearly not a real wallet (obvious placeholder)
+     * 2. It cannot receive funds or sign transactions
+     * 3. It signals to developers that fee paying is handled differently
+     *
+     * SECURITY NOTE: This is NOT a security risk because:
+     * - The fee payer is never used in verify() or settle() methods
+     * - Users sign and pay for their own transactions
+     * - The address is just a protocol-required placeholder
+     *
+     * @see https://docs.x402.org for protocol specification
+     */
+    private readonly DUMMY_FEE_PAYER;
+    /**
+     * Get supported payment kinds
+     * Returns x402 v2 compatible response with CAIP-2 network identifiers
+     *
+     * NOTE: The feePayer in extra.feePayer is a placeholder only.
+     * In self-sovereign mode, users pay their own transaction fees.
+     */
+    getSupported(_extensionKeys?: string[]): Promise<SupportedResponse>;
+    /**
+     * Get mechanism-specific extra data
+     */
+    getExtra(_network: Network): Record<string, unknown> | undefined;
+    /**
+     * Get default signers (not used for local verification usually, but required by interface)
+     */
+    getSigners(_network: string): string[];
+    /**
+     * Enable debug logging (disable in production)
+     */
+    private debug;
+    /**
+     * Verify a payment on-chain
+     */
+    verify(payload: PaymentPayload, requirements: PaymentRequirements): Promise<VerifyResponse>;
+    /**
+     * Fetch transaction with exponential backoff retry
+     */
+    private fetchTransactionWithRetry;
+    /**
+     * Sleep helper
+     */
+    private sleep;
+    /**
+     * Settle a payment (not applicable for direct chain verification, usually)
+     * But we must implement it. For 'exact', settlement is just verification + finality.
+     */
+    settle(payload: PaymentPayload, requirements: PaymentRequirements): Promise<SettleResponse>;
+}
+
+export { LocalSvmFacilitator };

package/dist/index.d.ts

@@ -1,9 +1,101 @@
 export * from '@x402/core';
+import { PaymentPayload, PaymentRequirements, VerifyResponse, SettleResponse, SupportedResponse, Network } from '@x402/core/types';
 export * from '@x402/core/types';
 export * from '@x402/core/client';
 export * from '@x402/svm';
-export { PaymentFlowConfig, PaymentResult, PaymentStatus, PaywallConfig, PaywallState, SendPaymentParams, SolanaPayUrlParams, WalletAdapterInterface, buildSolanaPayUrl, createPaymentFlow, createPaymentReference, createX402AuthorizationHeader, sendSolanaPayment, useFormatPrice, useLamportsToUsd, useMicropay, usePaywallResource, usePricing } from './client/index.js';
 export { AgentPaymentResult, CreditSessionClaims, CreditSessionConfig, CreditSessionData, CreditValidation, ExecuteAgentPaymentParams, UseCreditResult, addCredits, createCreditSession, executeAgentPayment, generateAgentKeypair, getAgentBalance, getRemainingCredits, hasAgentSufficientBalance, keypairFromBase58, useCredit, validateCreditSession } from './agent/index.js';
 export { CustomPriceProvider, PriceConfig, PriceData, clearPriceCache, configurePricing, formatPriceDisplay, formatPriceSync, getProviders, getSolPrice, lamportsToSol, lamportsToUsd, usdToLamports } from './pricing/index.js';
 import '@solana/web3.js';
 import './types-BWYQMw03.js';
+
+interface FacilitatorClient {
+    verify(paymentPayload: PaymentPayload, paymentRequirements: PaymentRequirements): Promise<VerifyResponse>;
+    settle(paymentPayload: PaymentPayload, paymentRequirements: PaymentRequirements): Promise<SettleResponse>;
+    getSupported(extensionKeys?: string[]): Promise<SupportedResponse>;
+}
+/**
+ * Local SVM Facilitator
+ *
+ * Verifies and settles Solana payments locally using a direct RPC connection,
+ * bypassing the need for a hosted facilitator service.
+ */
+declare class LocalSvmFacilitator implements FacilitatorClient {
+    readonly scheme = "exact";
+    readonly caipFamily = "solana:*";
+    private connection;
+    constructor(rpcUrl: string);
+    /**
+     * Get supported payment kinds
+     * Mocking the response of the /supported endpoint
+     */
+    /**
+     * Network Constants - CAIP-2 format for x402 v2
+     * These match the official Solana chain IDs used by x402 protocol
+     */
+    private readonly NETWORKS;
+    /**
+     * DUMMY_FEE_PAYER Explanation (for auditors):
+     *
+     * In a HOSTED facilitator (like x402.org), the `feePayer` field in the
+     * SupportedResponse.extra specifies which address will pay transaction fees
+     * when the facilitator submits transactions on behalf of users.
+     *
+     * In LOCAL/SELF-SOVEREIGN mode (this implementation):
+     * - The USER pays their own transaction fees directly
+     * - The facilitator NEVER submits transactions - it only VERIFIES them
+     * - Therefore, no fee payer address is actually used
+     *
+     * However, the x402 protocol REQUIRES this field in the response schema.
+     * We use the System Program address (all 1s) as a placeholder because:
+     * 1. It's clearly not a real wallet (obvious placeholder)
+     * 2. It cannot receive funds or sign transactions
+     * 3. It signals to developers that fee paying is handled differently
+     *
+     * SECURITY NOTE: This is NOT a security risk because:
+     * - The fee payer is never used in verify() or settle() methods
+     * - Users sign and pay for their own transactions
+     * - The address is just a protocol-required placeholder
+     *
+     * @see https://docs.x402.org for protocol specification
+     */
+    private readonly DUMMY_FEE_PAYER;
+    /**
+     * Get supported payment kinds
+     * Returns x402 v2 compatible response with CAIP-2 network identifiers
+     *
+     * NOTE: The feePayer in extra.feePayer is a placeholder only.
+     * In self-sovereign mode, users pay their own transaction fees.
+     */
+    getSupported(_extensionKeys?: string[]): Promise<SupportedResponse>;
+    /**
+     * Get mechanism-specific extra data
+     */
+    getExtra(_network: Network): Record<string, unknown> | undefined;
+    /**
+     * Get default signers (not used for local verification usually, but required by interface)
+     */
+    getSigners(_network: string): string[];
+    /**
+     * Enable debug logging (disable in production)
+     */
+    private debug;
+    /**
+     * Verify a payment on-chain
+     */
+    verify(payload: PaymentPayload, requirements: PaymentRequirements): Promise<VerifyResponse>;
+    /**
+     * Fetch transaction with exponential backoff retry
+     */
+    private fetchTransactionWithRetry;
+    /**
+     * Sleep helper
+     */
+    private sleep;
+    /**
+     * Settle a payment (not applicable for direct chain verification, usually)
+     * But we must implement it. For 'exact', settlement is just verification + finality.
+     */
+    settle(payload: PaymentPayload, requirements: PaymentRequirements): Promise<SettleResponse>;
+}
+
+export { LocalSvmFacilitator };