@vinaystwt/xmpp-wallet 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xMPP contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/config/src/index.d.ts

@@ -0,0 +1,49 @@
+export declare const config: {
+    readonly nodeEnv: string;
+    readonly network: string;
+    readonly paymentExecutionMode: "mock" | "testnet";
+    readonly rpcUrl: string;
+    readonly networkPassphrase: string;
+    readonly gatewayPort: number;
+    readonly dashboardPort: number;
+    readonly dashboardGatewayUrl: string | undefined;
+    readonly dailyBudgetUsd: number;
+    readonly facilitatorUrl: string;
+    readonly wallet: {
+        readonly agentSecretKey: string | undefined;
+        readonly smartAccountContractId: string | undefined;
+        readonly smartAccountWasmHash: string;
+        readonly webauthnVerifierAddress: string;
+        readonly ed25519VerifierAddress: string;
+        readonly spendingLimitPolicyAddress: string;
+        readonly thresholdPolicyAddress: string;
+    };
+    readonly x402: {
+        readonly facilitatorUrl: string;
+        readonly facilitatorApiKey: string | undefined;
+        readonly maxTransactionFeeStroops: number;
+        readonly facilitatorPrivateKey: string | undefined;
+        readonly recipientAddress: string | undefined;
+    };
+    readonly mpp: {
+        readonly secretKey: string | undefined;
+        readonly recipientAddress: string | undefined;
+        readonly channelContractId: string | undefined;
+        readonly feeSponsorshipEnabled: boolean;
+        readonly feeSponsorship: {
+            readonly chargeEnabled: boolean;
+            readonly sessionEnabled: boolean;
+        };
+        readonly feeSponsorSecretKey: string | undefined;
+        readonly feeBumpSecretKey: string | undefined;
+    };
+    readonly services: {
+        readonly research: string;
+        readonly market: string;
+        readonly stream: string;
+    };
+    readonly contracts: {
+        readonly policyContractId: string | undefined;
+        readonly sessionRegistryContractId: string | undefined;
+    };
+};

package/dist/config/src/index.js

@@ -0,0 +1,117 @@
+import { config as loadEnv } from 'dotenv';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { z } from 'zod';
+const moduleDir = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(moduleDir, '../../../');
+loadEnv({ path: resolve(repoRoot, '.env') });
+loadEnv({ path: resolve(repoRoot, '.env.local'), override: true });
+loadEnv();
+const envSchema = z.object({
+    NODE_ENV: z.string().default('development'),
+    XMPP_NETWORK: z.string().default('stellar:testnet'),
+    XMPP_PAYMENT_EXECUTION_MODE: z.enum(['mock', 'testnet']).default('mock'),
+    XMPP_RPC_URL: z.string().default('https://soroban-testnet.stellar.org'),
+    XMPP_NETWORK_PASSPHRASE: z.string().default('Test SDF Network ; September 2015'),
+    XMPP_GATEWAY_PORT: z.coerce.number().default(4300),
+    XMPP_DASHBOARD_PORT: z.coerce.number().default(4310),
+    XMPP_DASHBOARD_GATEWAY_URL: z.string().optional(),
+    XMPP_DAILY_BUDGET_USD: z.coerce.number().default(0.5),
+    XMPP_AGENT_SECRET_KEY: z.string().optional(),
+    XMPP_SMART_ACCOUNT_CONTRACT_ID: z.string().optional(),
+    XMPP_SMART_ACCOUNT_WASM_HASH: z
+        .string()
+        .default('3e51f5b222dec74650f0b33367acb42a41ce497f72639230463070e666abba2c'),
+    XMPP_WEBAUTHN_VERIFIER_ADDRESS: z
+        .string()
+        .default('CATPTBRWVMH5ZCIKO5HN2F4FMPXVZEXC56RKGHRXCM7EEZGGXK7PICEH'),
+    XMPP_ED25519_VERIFIER_ADDRESS: z
+        .string()
+        .default('CAIKK32K3BZJYTWVTXHZFPIEEDBR6YCVTGPABH4UQUQ4XFA3OLYXG27G'),
+    XMPP_SPENDING_LIMIT_POLICY_ADDRESS: z
+        .string()
+        .default('CBYLPYZGLQ6JVY2IQ5P23QLQPR3KAMMKMZLNWG6RUUKJDNYGPLVHK7U4'),
+    XMPP_THRESHOLD_POLICY_ADDRESS: z
+        .string()
+        .default('CDDQLFG7CV74QHWPSP6NZIPNBR2PPCMTUVYCJF4P3ONDYHODRFGR7LWC'),
+    X402_FACILITATOR_URL: z.string().default('http://localhost:4022'),
+    X402_FACILITATOR_API_KEY: z.string().optional(),
+    X402_MAX_TRANSACTION_FEE_STROOPS: z.coerce.number().default(2000000),
+    X402_RECIPIENT_ADDRESS: z.string().optional(),
+    FACILITATOR_STELLAR_PRIVATE_KEY: z.string().optional(),
+    MPP_SECRET_KEY: z.string().optional(),
+    MPP_RECIPIENT_ADDRESS: z.string().optional(),
+    MPP_CHANNEL_CONTRACT_ID: z.string().optional(),
+    XMPP_ENABLE_MPP_FEE_SPONSORSHIP: z
+        .enum(['true', 'false'])
+        .default('false')
+        .transform((value) => value === 'true'),
+    XMPP_ENABLE_MPP_CHARGE_FEE_SPONSORSHIP: z
+        .enum(['true', 'false'])
+        .optional()
+        .transform((value) => value === 'true'),
+    XMPP_ENABLE_MPP_SESSION_FEE_SPONSORSHIP: z
+        .enum(['true', 'false'])
+        .optional()
+        .transform((value) => value === 'true'),
+    XMPP_MPP_FEE_SPONSOR_SECRET_KEY: z.string().optional(),
+    XMPP_MPP_FEE_BUMP_SECRET_KEY: z.string().optional(),
+    XMPP_RESEARCH_API_URL: z.string().default('http://localhost:4101'),
+    XMPP_MARKET_API_URL: z.string().default('http://localhost:4102'),
+    XMPP_STREAM_API_URL: z.string().default('http://localhost:4103'),
+    XMPP_POLICY_CONTRACT_ID: z.string().optional(),
+    XMPP_SESSION_REGISTRY_CONTRACT_ID: z.string().optional(),
+});
+const env = envSchema.parse(process.env);
+const mppFeeSponsorshipEnabled = env.XMPP_ENABLE_MPP_FEE_SPONSORSHIP;
+const mppChargeFeeSponsorshipEnabled = env.XMPP_ENABLE_MPP_CHARGE_FEE_SPONSORSHIP ?? mppFeeSponsorshipEnabled;
+const mppSessionFeeSponsorshipEnabled = env.XMPP_ENABLE_MPP_SESSION_FEE_SPONSORSHIP ?? mppFeeSponsorshipEnabled;
+export const config = {
+    nodeEnv: env.NODE_ENV,
+    network: env.XMPP_NETWORK,
+    paymentExecutionMode: env.XMPP_PAYMENT_EXECUTION_MODE,
+    rpcUrl: env.XMPP_RPC_URL,
+    networkPassphrase: env.XMPP_NETWORK_PASSPHRASE,
+    gatewayPort: env.XMPP_GATEWAY_PORT,
+    dashboardPort: env.XMPP_DASHBOARD_PORT,
+    dashboardGatewayUrl: env.XMPP_DASHBOARD_GATEWAY_URL,
+    dailyBudgetUsd: env.XMPP_DAILY_BUDGET_USD,
+    facilitatorUrl: env.X402_FACILITATOR_URL,
+    wallet: {
+        agentSecretKey: env.XMPP_AGENT_SECRET_KEY,
+        smartAccountContractId: env.XMPP_SMART_ACCOUNT_CONTRACT_ID,
+        smartAccountWasmHash: env.XMPP_SMART_ACCOUNT_WASM_HASH,
+        webauthnVerifierAddress: env.XMPP_WEBAUTHN_VERIFIER_ADDRESS,
+        ed25519VerifierAddress: env.XMPP_ED25519_VERIFIER_ADDRESS,
+        spendingLimitPolicyAddress: env.XMPP_SPENDING_LIMIT_POLICY_ADDRESS,
+        thresholdPolicyAddress: env.XMPP_THRESHOLD_POLICY_ADDRESS,
+    },
+    x402: {
+        facilitatorUrl: env.X402_FACILITATOR_URL,
+        facilitatorApiKey: env.X402_FACILITATOR_API_KEY,
+        maxTransactionFeeStroops: env.X402_MAX_TRANSACTION_FEE_STROOPS,
+        facilitatorPrivateKey: env.FACILITATOR_STELLAR_PRIVATE_KEY,
+        recipientAddress: env.X402_RECIPIENT_ADDRESS,
+    },
+    mpp: {
+        secretKey: env.MPP_SECRET_KEY,
+        recipientAddress: env.MPP_RECIPIENT_ADDRESS,
+        channelContractId: env.MPP_CHANNEL_CONTRACT_ID,
+        feeSponsorshipEnabled: mppFeeSponsorshipEnabled,
+        feeSponsorship: {
+            chargeEnabled: mppChargeFeeSponsorshipEnabled,
+            sessionEnabled: mppSessionFeeSponsorshipEnabled,
+        },
+        feeSponsorSecretKey: env.XMPP_MPP_FEE_SPONSOR_SECRET_KEY,
+        feeBumpSecretKey: env.XMPP_MPP_FEE_BUMP_SECRET_KEY,
+    },
+    services: {
+        research: env.XMPP_RESEARCH_API_URL,
+        market: env.XMPP_MARKET_API_URL,
+        stream: env.XMPP_STREAM_API_URL,
+    },
+    contracts: {
+        policyContractId: env.XMPP_POLICY_CONTRACT_ID,
+        sessionRegistryContractId: env.XMPP_SESSION_REGISTRY_CONTRACT_ID,
+    },
+};

package/dist/types/src/index.d.ts

@@ -0,0 +1,343 @@
+export type RouteKind = 'x402' | 'mpp-charge' | 'mpp-session-open' | 'mpp-session-reuse';
+export type PaymentExecutionMode = 'mock' | 'testnet';
+export type PaymentExecutionStatus = 'mock-paid' | 'ready-for-testnet' | 'settled-testnet' | 'missing-config';
+export type RouteContext = {
+    url: string;
+    method: string;
+    serviceId?: string;
+    projectedRequests?: number;
+    streaming?: boolean;
+};
+export type ServiceCatalogEntry = {
+    serviceId: string;
+    displayName: string;
+    description: string;
+    baseUrl: string;
+    source?: 'static' | 'discovered' | 'hybrid' | 'fallback';
+    capabilities: {
+        x402: boolean;
+        mppCharge: boolean;
+        mppSession: boolean;
+    };
+    pricing: {
+        x402PerCallUsd: number;
+        mppChargePerCallUsd: number;
+        mppSessionOpenUsd: number;
+        mppSessionPerCallUsd: number;
+    };
+    routingHints: {
+        breakEvenCalls: number;
+        streamingPreferred: boolean;
+        preferredSingleCall: Extract<RouteKind, 'x402' | 'mpp-charge'>;
+    };
+};
+export type RouteScoreBreakdown = {
+    route: RouteKind;
+    supported: boolean;
+    estimatedTotalUsd: number;
+    savingsVsNaiveUsd: number;
+    totalScore: number;
+    reasons: string[];
+};
+export type RouteDecision = {
+    route: RouteKind;
+    reason: string;
+    score: number;
+    projectedRequests?: number;
+    estimatedTotalUsd?: number;
+    savingsVsNaiveUsd?: number;
+    service?: ServiceCatalogEntry;
+    breakdown?: RouteScoreBreakdown[];
+};
+export type ChallengeKind = 'x402' | 'mpp-charge' | 'mpp-session';
+export type PaymentChallenge = {
+    kind: ChallengeKind;
+    service: string;
+    amountUsd: number;
+    asset: 'USDC_TESTNET';
+    retryHeaderName: string;
+    retryHeaderValue: string;
+    sessionId?: string;
+};
+export type XmppFetchOptions = Omit<RouteContext, 'url' | 'method'> & {
+    agentId?: string;
+    maxAutoPayUsd?: number;
+    idempotencyKey?: string;
+};
+export type XmppAgentProfile = {
+    agentId: string;
+    displayName: string;
+    role: 'shared' | 'research' | 'market';
+    description: string;
+    dailyBudgetUsd: number;
+    allowedServices: string[];
+    preferredRoutes: RouteKind[];
+    autopayMethods: string[];
+    enabled?: boolean;
+    policySource?: 'local' | 'contract' | 'fallback' | 'merged';
+};
+export type XmppSignedReceipt = {
+    receiptId: string;
+    issuedAt: string;
+    network: string;
+    agent: string;
+    serviceId: string;
+    url: string;
+    method: string;
+    route: RouteKind;
+    amountUsd: number;
+    txHash?: string;
+    explorerUrl?: string;
+    paymentReference?: string;
+    signature: string;
+};
+export type XmppSmartAccountExecution = {
+    configured: boolean;
+    preferred: boolean;
+    supported: boolean;
+    used: boolean;
+    contractId?: string | null;
+    fallbackReason?: string;
+};
+export type PaymentExecutionMetadata = {
+    mode: PaymentExecutionMode;
+    status: PaymentExecutionStatus;
+    route: RouteKind;
+    receiptId: string;
+    missingConfig?: string[];
+    evidenceHeaders?: Record<string, string>;
+    signedReceipt?: XmppSignedReceipt;
+    settlementStrategy?: 'keypair' | 'smart-account' | 'keypair-fallback';
+    executionNote?: string;
+    feeSponsored?: boolean;
+    feeSponsorPublicKey?: string;
+    feeBumpPublicKey?: string;
+    smartAccount?: XmppSmartAccountExecution;
+};
+export type PolicyDecision = {
+    allowed: boolean;
+    reason: string;
+    code: 'allowed' | 'blocked-domain' | 'blocked-path' | 'blocked-method' | 'blocked-service' | 'blocked-agent' | 'blocked-budget' | 'blocked-idempotency' | 'paused';
+    source?: 'local' | 'contract' | 'fallback';
+};
+export type PaymentExecutionResult = {
+    response: Response;
+    metadata: PaymentExecutionMetadata;
+};
+export type XmppFetchMetadata = {
+    route: RouteKind;
+    challenge?: PaymentChallenge;
+    retried: boolean;
+    execution?: PaymentExecutionMetadata;
+    policy?: PolicyDecision;
+    budget?: XmppBudgetSnapshot;
+    idempotentReplay?: boolean;
+};
+export type XmppSessionRecord = {
+    sessionId: string;
+    serviceId: string;
+    agent: string;
+    channelContractId: string;
+    route: string;
+    status: string;
+    totalAmountUsdCents: number;
+    callCount: number;
+    lastReceiptId: string;
+    updatedAtLedger: number;
+};
+export type WorkflowEstimateStep = {
+    url: string;
+    method?: string;
+    serviceId?: string;
+    projectedRequests: number;
+    streaming?: boolean;
+};
+export type WorkflowEstimateLineItem = {
+    serviceId: string;
+    displayName: string;
+    route: RouteKind;
+    projectedRequests: number;
+    estimatedCostUsd: number;
+    savingsVsNaiveUsd: number;
+    reason: string;
+};
+export type WorkflowEstimateResult = {
+    totalEstimatedCostUsd: number;
+    naiveX402CostUsd: number;
+    savingsVsNaiveUsd: number;
+    breakdown: WorkflowEstimateLineItem[];
+};
+export type XmppBudgetSnapshot = {
+    agentId: string;
+    agentDisplayName: string;
+    agentSpentThisSessionUsd: number;
+    agentRemainingDailyBudgetUsd: number;
+    spentThisSessionUsd: number;
+    remainingDailyBudgetUsd: number;
+    callsThisService: number;
+    projectedCostIfRepeated5xUsd: number;
+    recommendation: string;
+};
+export type XmppRouteEvent = {
+    id: string;
+    timestamp: string;
+    agentId: string;
+    url: string;
+    method: string;
+    serviceId: string;
+    route: RouteKind;
+    status: 'settled' | 'denied' | 'preview';
+    amountUsd: number;
+    projectedRequests: number;
+    policyCode?: PolicyDecision['code'];
+    receiptId?: string;
+    txHash?: string;
+    explorerUrl?: string;
+    sessionId?: string;
+    signedReceipt?: XmppSignedReceipt;
+    feeSponsored?: boolean;
+    feeSponsorPublicKey?: string;
+    settlementStrategy?: PaymentExecutionMetadata['settlementStrategy'];
+    executionNote?: string;
+};
+export type XmppAgentStateSummary = {
+    agentId: string;
+    displayName: string;
+    role: XmppAgentProfile['role'];
+    description: string;
+    dailyBudgetUsd: number;
+    spentThisSessionUsd: number;
+    remainingDailyBudgetUsd: number;
+    routeCounts: Record<RouteKind, number>;
+    allowedServices: string[];
+    preferredRoutes: RouteKind[];
+    enabled?: boolean;
+    policySource?: XmppAgentProfile['policySource'];
+    autopayMethods?: string[];
+};
+export type XmppAgentPolicySnapshot = {
+    agentId: string;
+    enabled: boolean;
+    dailyBudgetUsd: number;
+    allowedServices: string[];
+    preferredRoutes: RouteKind[];
+    autopayMethods: string[];
+    source: 'contract' | 'local' | 'fallback';
+};
+export type XmppContractTreasurySnapshot = {
+    sharedTreasuryUsd: number;
+    totalSpentUsd: number;
+    remainingUsd: number;
+    paymentCount: number;
+    source: 'contract' | 'local' | 'fallback';
+};
+export type XmppContractAgentTreasuryState = {
+    agentId: string;
+    spentUsd: number;
+    paymentCount: number;
+    lastServiceId: string;
+    lastRoute: string;
+    source: 'contract' | 'local' | 'fallback';
+};
+export type XmppOperatorState = {
+    sharedTreasuryUsd: number;
+    sharedTreasuryRemainingUsd: number;
+    dailyBudgetUsd: number;
+    spentThisSessionUsd: number;
+    remainingDailyBudgetUsd: number;
+    sessionSavingsUsd: number;
+    routeCounts: Record<RouteKind, number>;
+    serviceSpendUsd: Record<string, number>;
+    serviceCallCounts: Record<string, number>;
+    agentProfiles: XmppAgentProfile[];
+    agentStates: XmppAgentStateSummary[];
+    contractAgentPolicies?: XmppAgentPolicySnapshot[];
+    contractTreasury?: XmppContractTreasurySnapshot | null;
+    contractAgentTreasuryStates?: XmppContractAgentTreasuryState[];
+    openSessions: Array<Pick<XmppSessionRecord, 'sessionId' | 'serviceId' | 'callCount'>>;
+    recentEvents: XmppRouteEvent[];
+};
+export type XmppReceiptVerificationResult = {
+    valid: boolean;
+    agent: string;
+    receiptId: string;
+};
+export type XmppWalletInfo = {
+    connected: boolean;
+    paymentExecutionMode: PaymentExecutionMode;
+    network: string;
+    rpcUrl: string;
+    agentPublicKey: string | null;
+    settlementStrategy: 'smart-account-ready' | 'smart-account-x402-preferred' | 'smart-account-partial-fallback' | 'keypair-live';
+    smartAccount: {
+        ready: boolean;
+        mode: 'inactive' | 'x402-only' | 'full';
+        routeCoverage: 'inactive' | 'x402-only';
+        demoReady: boolean;
+        guardedFallback: boolean;
+        contractId: string | null;
+        wasmHash: string;
+        webauthnVerifierAddress: string;
+        ed25519VerifierAddress: string;
+        spendingLimitPolicyAddress: string;
+        thresholdPolicyAddress: string;
+        preferredRoutes: RouteKind[];
+        fallbackRoutes: RouteKind[];
+        supportedRoutes: RouteKind[];
+        unsupportedRoutes: RouteKind[];
+        unsupportedReason: string | null;
+        configuredMaxTransactionFeeStroops: number;
+        effectiveMaxTransactionFeeStroops: number;
+        feeFloorApplied: boolean;
+        preflightFailures: string[];
+        coverageMessage: string;
+        message: string;
+        operatorNotes: string[];
+    };
+    feeSponsorship: {
+        enabled: boolean;
+        available: boolean;
+        mppChargeEnabled: boolean;
+        mppSessionEnabled: boolean;
+        sponsorPublicKey: string | null;
+        feeBumpPublicKey: string | null;
+        message: string;
+    };
+    missingSecrets: string[];
+    message: string;
+};
+export type XmppHealthStatus = {
+    ok: boolean;
+    service: string;
+    network: string;
+    paymentExecutionMode: PaymentExecutionMode;
+    services: Record<string, string>;
+    smartAccount: {
+        configured: boolean;
+        routeCoverage: 'inactive' | 'x402-only';
+        x402Preferred: boolean;
+        mppFallback: boolean;
+        demoReady: boolean;
+        guardedFallback: boolean;
+        unsupportedRoutes: RouteKind[];
+        unsupportedReason: string | null;
+        configuredMaxTransactionFeeStroops: number;
+        effectiveMaxTransactionFeeStroops: number;
+        feeFloorApplied: boolean;
+        preflightFailures: string[];
+    };
+};
+export type XmppCatalogResponse = {
+    services: ServiceCatalogEntry[];
+};
+export type XmppPolicyPreviewResponse = {
+    policy: PolicyDecision;
+    routePreview: RouteDecision;
+};
+export type XmppGatewayFetchResponse = {
+    status: number;
+    routePreview: RouteDecision;
+    payment?: XmppFetchMetadata;
+    responseHeaders: Record<string, string>;
+    body: unknown;
+};

package/dist/types/src/index.js

@@ -0,0 +1 @@
+export {};

package/dist/wallet/src/index.d.ts

@@ -0,0 +1,14 @@
+import type { PaymentExecutionMetadata, RouteKind, XmppReceiptVerificationResult, XmppSignedReceipt, XmppSmartAccountExecution, XmppWalletInfo } from '@xmpp/types';
+export declare const SMART_ACCOUNT_MIN_TRANSACTION_FEE_STROOPS = 2000000;
+export declare function signXmppReceipt(input: Omit<XmppSignedReceipt, 'signature' | 'agent' | 'issuedAt' | 'network'> & {
+    issuedAt?: string;
+    network?: string;
+}): XmppSignedReceipt | null;
+export declare function verifyXmppReceipt(receipt: XmppSignedReceipt): XmppReceiptVerificationResult;
+export declare function getEffectiveSmartAccountFeeCeiling(): number;
+export declare function getRouteExecutionPlan(route: RouteKind): {
+    settlementStrategy: PaymentExecutionMetadata['settlementStrategy'];
+    executionNote: string;
+    smartAccount: XmppSmartAccountExecution;
+};
+export declare function getWalletInfo(): Promise<XmppWalletInfo>;

package/dist/wallet/src/index.js

@@ -0,0 +1,250 @@
+import { config } from '@xmpp/config';
+import { Keypair } from '@stellar/stellar-sdk';
+export const SMART_ACCOUNT_MIN_TRANSACTION_FEE_STROOPS = 2_000_000;
+function stableReceiptPayload(receipt) {
+    return JSON.stringify({
+        receiptId: receipt.receiptId,
+        issuedAt: receipt.issuedAt,
+        network: receipt.network,
+        agent: receipt.agent,
+        serviceId: receipt.serviceId,
+        url: receipt.url,
+        method: receipt.method,
+        route: receipt.route,
+        amountUsd: receipt.amountUsd,
+        txHash: receipt.txHash ?? null,
+        explorerUrl: receipt.explorerUrl ?? null,
+        paymentReference: receipt.paymentReference ?? null,
+    });
+}
+export function signXmppReceipt(input) {
+    if (!config.wallet.agentSecretKey) {
+        return null;
+    }
+    const keypair = Keypair.fromSecret(config.wallet.agentSecretKey);
+    const receipt = {
+        ...input,
+        issuedAt: input.issuedAt ?? new Date().toISOString(),
+        network: input.network ?? config.network,
+        agent: keypair.publicKey(),
+    };
+    const payload = Buffer.from(stableReceiptPayload(receipt), 'utf8');
+    const signature = keypair.sign(payload).toString('base64');
+    return {
+        ...receipt,
+        signature,
+    };
+}
+export function verifyXmppReceipt(receipt) {
+    const keypair = Keypair.fromPublicKey(receipt.agent);
+    const payload = Buffer.from(stableReceiptPayload({
+        receiptId: receipt.receiptId,
+        issuedAt: receipt.issuedAt,
+        network: receipt.network,
+        agent: receipt.agent,
+        serviceId: receipt.serviceId,
+        url: receipt.url,
+        method: receipt.method,
+        route: receipt.route,
+        amountUsd: receipt.amountUsd,
+        txHash: receipt.txHash,
+        explorerUrl: receipt.explorerUrl,
+        paymentReference: receipt.paymentReference,
+    }), 'utf8');
+    return {
+        valid: keypair.verify(payload, Buffer.from(receipt.signature, 'base64')),
+        agent: receipt.agent,
+        receiptId: receipt.receiptId,
+    };
+}
+function smartAccountConfigured() {
+    return Boolean(config.wallet.smartAccountContractId);
+}
+export function getEffectiveSmartAccountFeeCeiling() {
+    if (!smartAccountConfigured()) {
+        return config.x402.maxTransactionFeeStroops;
+    }
+    return Math.max(config.x402.maxTransactionFeeStroops, SMART_ACCOUNT_MIN_TRANSACTION_FEE_STROOPS);
+}
+function smartAccountFeeFloorApplied() {
+    return smartAccountConfigured() &&
+        config.x402.maxTransactionFeeStroops < SMART_ACCOUNT_MIN_TRANSACTION_FEE_STROOPS;
+}
+function getSmartAccountPreflightFailures() {
+    if (!smartAccountConfigured()) {
+        return ['XMPP_SMART_ACCOUNT_CONTRACT_ID'];
+    }
+    return [
+        !config.wallet.agentSecretKey ? 'XMPP_AGENT_SECRET_KEY' : null,
+        !config.x402.facilitatorPrivateKey ? 'FACILITATOR_STELLAR_PRIVATE_KEY' : null,
+    ].filter((value) => value !== null);
+}
+function smartAccountPrimaryReady() {
+    return Boolean(config.wallet.smartAccountContractId &&
+        config.wallet.agentSecretKey &&
+        config.x402.facilitatorPrivateKey);
+}
+export function getRouteExecutionPlan(route) {
+    const configured = smartAccountConfigured();
+    const liveReady = smartAccountPrimaryReady();
+    if (route === 'x402') {
+        if (liveReady) {
+            return {
+                settlementStrategy: 'smart-account',
+                executionNote: 'x402 prefers the configured smart account, with an automatic fallback to keypair settlement if delegated auth becomes unavailable.',
+                smartAccount: {
+                    configured: true,
+                    preferred: true,
+                    supported: true,
+                    used: true,
+                    contractId: config.wallet.smartAccountContractId ?? null,
+                },
+            };
+        }
+        return {
+            settlementStrategy: 'keypair',
+            executionNote: configured
+                ? 'Smart account is configured, but x402 is staying on the agent keypair until the smart-account demo preconditions are fully satisfied.'
+                : 'x402 is executing with the agent keypair.',
+            smartAccount: {
+                configured,
+                preferred: configured,
+                supported: true,
+                used: false,
+                contractId: config.wallet.smartAccountContractId ?? null,
+                fallbackReason: configured
+                    ? 'Smart-account x402 is guarded until the delegated signer, facilitator, and fee-cap preconditions are all ready.'
+                    : 'No smart account is configured.',
+            },
+        };
+    }
+    return {
+        settlementStrategy: configured ? 'keypair-fallback' : 'keypair',
+        executionNote: configured
+            ? 'MPP is using explicit keypair execution because the current MPP SDK requires Keypair signers.'
+            : 'MPP is executing with the configured keypair signer.',
+        smartAccount: {
+            configured,
+            preferred: configured,
+            supported: false,
+            used: false,
+            contractId: config.wallet.smartAccountContractId ?? null,
+            fallbackReason: configured
+                ? 'Current MPP client flows require Keypair signers.'
+                : 'No smart account is configured.',
+        },
+    };
+}
+export async function getWalletInfo() {
+    const agentKeypair = config.wallet.agentSecretKey
+        ? Keypair.fromSecret(config.wallet.agentSecretKey)
+        : null;
+    const feeSponsorSecret = config.mpp.feeSponsorSecretKey ??
+        ((config.mpp.feeSponsorship.chargeEnabled || config.mpp.feeSponsorship.sessionEnabled)
+            ? config.mpp.secretKey
+            : undefined);
+    const feeSponsorKeypair = feeSponsorSecret ? Keypair.fromSecret(feeSponsorSecret) : null;
+    const feeBumpKeypair = config.mpp.feeBumpSecretKey
+        ? Keypair.fromSecret(config.mpp.feeBumpSecretKey)
+        : null;
+    const smartAccountReady = smartAccountConfigured();
+    const smartAccountActive = smartAccountPrimaryReady();
+    const smartAccountPreflightFailures = getSmartAccountPreflightFailures();
+    const smartAccountEffectiveFeeCeiling = getEffectiveSmartAccountFeeCeiling();
+    const smartAccountFeeFloorWasApplied = smartAccountFeeFloorApplied();
+    const smartAccountMode = smartAccountActive
+        ? 'x402-only'
+        : smartAccountReady
+            ? 'x402-only'
+            : 'inactive';
+    const smartAccountRouteCoverage = smartAccountReady
+        ? 'x402-only'
+        : 'inactive';
+    const smartAccountOperatorNotes = smartAccountActive
+        ? [
+            'Smart-account execution is enabled for x402 only.',
+            'If delegated x402 settlement becomes unavailable, xMPP falls back to the stable keypair path instead of surfacing a smart-account-specific failure.',
+            'MPP charge and session flows still use keypair execution because the current MPP client requires Keypair signers.',
+            smartAccountFeeFloorWasApplied
+                ? `The facilitator is enforcing a safe x402 fee ceiling of at least ${SMART_ACCOUNT_MIN_TRANSACTION_FEE_STROOPS.toLocaleString()} stroops for smart-account execution.`
+                : `The facilitator fee ceiling is set to ${smartAccountEffectiveFeeCeiling.toLocaleString()} stroops for smart-account x402 execution.`,
+        ]
+        : smartAccountReady
+            ? [
+                'A smart-account contract id is configured, but x402 is still guarded behind the stable keypair path until all demo preconditions are satisfied.',
+                'MPP charge and session flows remain explicit keypair routes.',
+            ]
+            : ['Smart-account execution is not configured yet.'];
+    const missingSecrets = [
+        !config.wallet.agentSecretKey ? 'XMPP_AGENT_SECRET_KEY' : null,
+        !config.x402.facilitatorPrivateKey ? 'FACILITATOR_STELLAR_PRIVATE_KEY' : null,
+        !config.mpp.secretKey ? 'MPP_SECRET_KEY' : null,
+    ].filter((value) => value !== null);
+    return {
+        connected: missingSecrets.length === 0,
+        paymentExecutionMode: config.paymentExecutionMode,
+        network: config.network,
+        rpcUrl: config.rpcUrl,
+        agentPublicKey: agentKeypair?.publicKey() ?? null,
+        settlementStrategy: smartAccountActive
+            ? 'smart-account-x402-preferred'
+            : smartAccountReady
+                ? 'smart-account-partial-fallback'
+                : 'keypair-live',
+        smartAccount: {
+            ready: smartAccountReady,
+            mode: smartAccountMode,
+            routeCoverage: smartAccountRouteCoverage,
+            demoReady: smartAccountActive,
+            guardedFallback: smartAccountReady,
+            contractId: config.wallet.smartAccountContractId ?? null,
+            wasmHash: config.wallet.smartAccountWasmHash,
+            webauthnVerifierAddress: config.wallet.webauthnVerifierAddress,
+            ed25519VerifierAddress: config.wallet.ed25519VerifierAddress,
+            spendingLimitPolicyAddress: config.wallet.spendingLimitPolicyAddress,
+            thresholdPolicyAddress: config.wallet.thresholdPolicyAddress,
+            preferredRoutes: smartAccountActive ? ['x402'] : [],
+            fallbackRoutes: smartAccountReady ? ['mpp-charge', 'mpp-session-open', 'mpp-session-reuse'] : [],
+            supportedRoutes: ['x402'],
+            unsupportedRoutes: ['mpp-charge', 'mpp-session-open', 'mpp-session-reuse'],
+            unsupportedReason: smartAccountReady
+                ? 'MPP charge and MPP session routes still require explicit Keypair signers in the current client stack.'
+                : null,
+            configuredMaxTransactionFeeStroops: config.x402.maxTransactionFeeStroops,
+            effectiveMaxTransactionFeeStroops: smartAccountEffectiveFeeCeiling,
+            feeFloorApplied: smartAccountFeeFloorWasApplied,
+            preflightFailures: smartAccountPreflightFailures,
+            coverageMessage: smartAccountReady
+                ? 'Smart-account execution is intentionally limited to x402. All MPP routes remain keypair-backed.'
+                : 'Smart-account execution is not configured.',
+            message: smartAccountActive
+                ? 'Smart-account execution is enabled for x402 only, with guarded fallback to the stable keypair path if the delegated route becomes unavailable.'
+                : smartAccountReady
+                    ? 'Smart-account identifiers are configured, but x402 stays on the stable keypair path until the delegated flow is fully demo-ready.'
+                    : 'Smart account execution is not configured yet.',
+            operatorNotes: smartAccountOperatorNotes,
+        },
+        feeSponsorship: {
+            enabled: config.mpp.feeSponsorship.chargeEnabled || config.mpp.feeSponsorship.sessionEnabled,
+            available: (config.mpp.feeSponsorship.chargeEnabled || config.mpp.feeSponsorship.sessionEnabled) &&
+                Boolean(feeSponsorKeypair),
+            mppChargeEnabled: config.mpp.feeSponsorship.chargeEnabled,
+            mppSessionEnabled: config.mpp.feeSponsorship.sessionEnabled,
+            sponsorPublicKey: feeSponsorKeypair?.publicKey() ?? null,
+            feeBumpPublicKey: feeBumpKeypair?.publicKey() ?? null,
+            message: feeSponsorKeypair
+                ? config.mpp.feeSponsorship.chargeEnabled && config.mpp.feeSponsorship.sessionEnabled
+                    ? 'MPP charge and session services can sponsor gas for agent-side flows.'
+                    : config.mpp.feeSponsorship.sessionEnabled
+                        ? 'MPP session services can sponsor gas for agent-side flows; charge stays agent-funded.'
+                        : config.mpp.feeSponsorship.chargeEnabled
+                            ? 'MPP charge services can sponsor gas for agent-side flows; sessions stay agent-funded.'
+                            : 'Fee sponsorship is disabled; the agent pays its own network fees.'
+                : 'Fee sponsorship is disabled; the agent pays its own network fees.',
+        },
+        missingSecrets,
+        message: missingSecrets.length === 0
+            ? 'xMPP has the core Stellar testnet secrets required to continue live payment integration.'
+            : 'xMPP is still missing the three core Stellar testnet secrets required for live payment execution.',
+    };
+}

package/dist/wallet/src/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/wallet/src/index.test.js

@@ -0,0 +1,140 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { Keypair } from '@stellar/stellar-sdk';
+async function loadWalletModule(secret, smartAccountContractId, maxTransactionFeeStroops = 2_000_000) {
+    vi.resetModules();
+    vi.doMock('@xmpp/config', () => ({
+        config: {
+            paymentExecutionMode: 'testnet',
+            rpcUrl: 'https://soroban-testnet.stellar.org',
+            network: 'stellar:testnet',
+            x402: {
+                facilitatorPrivateKey: 'SFACILITATOR',
+                maxTransactionFeeStroops,
+            },
+            mpp: {
+                secretKey: undefined,
+                feeSponsorSecretKey: undefined,
+                feeBumpSecretKey: undefined,
+                feeSponsorship: {
+                    chargeEnabled: false,
+                    sessionEnabled: false,
+                },
+            },
+            wallet: {
+                agentSecretKey: secret,
+                smartAccountContractId,
+                smartAccountWasmHash: 'wasm-hash',
+                webauthnVerifierAddress: 'CWEBAUTHN',
+                ed25519VerifierAddress: 'CED25519',
+                spendingLimitPolicyAddress: 'CSPEND',
+                thresholdPolicyAddress: 'CTHRESH',
+            },
+        },
+    }));
+    return import('./index.js');
+}
+describe('wallet receipt signing', () => {
+    afterEach(() => {
+        vi.restoreAllMocks();
+        vi.resetModules();
+    });
+    it('signs and verifies an xMPP receipt', async () => {
+        const secret = Keypair.random().secret();
+        const { signXmppReceipt, verifyXmppReceipt } = await loadWalletModule(secret);
+        const receipt = signXmppReceipt({
+            receiptId: 'xmpp_x402_test',
+            serviceId: 'research-api',
+            url: 'http://localhost:4101/research?q=stellar',
+            method: 'GET',
+            route: 'x402',
+            amountUsd: 0.01,
+            txHash: 'abc123',
+            explorerUrl: 'https://stellar.expert/explorer/testnet/tx/abc123',
+            paymentReference: 'abc123',
+            issuedAt: '2026-04-03T00:00:00.000Z',
+            network: 'stellar:testnet',
+        });
+        expect(receipt).not.toBeNull();
+        expect(receipt?.agent).toBe(Keypair.fromSecret(secret).publicKey());
+        expect(verifyXmppReceipt(receipt)).toMatchObject({
+            valid: true,
+            receiptId: 'xmpp_x402_test',
+        });
+    });
+    it('returns null when the agent key is unavailable', async () => {
+        const { signXmppReceipt } = await loadWalletModule(undefined);
+        expect(signXmppReceipt({
+            receiptId: 'xmpp_x402_test',
+            serviceId: 'research-api',
+            url: 'http://localhost:4101/research?q=stellar',
+            method: 'GET',
+            route: 'x402',
+            amountUsd: 0.01,
+        })).toBeNull();
+    });
+    it('prefers smart-account execution for x402 when configured', async () => {
+        const secret = Keypair.random().secret();
+        const { getRouteExecutionPlan, getWalletInfo } = await loadWalletModule(secret, 'CSMARTACCOUNT');
+        expect(getRouteExecutionPlan('x402')).toMatchObject({
+            settlementStrategy: 'smart-account',
+            smartAccount: {
+                configured: true,
+                supported: true,
+                used: true,
+            },
+        });
+        expect(getRouteExecutionPlan('mpp-charge')).toMatchObject({
+            settlementStrategy: 'keypair-fallback',
+            smartAccount: {
+                configured: true,
+                supported: false,
+                used: false,
+            },
+        });
+        await expect(getWalletInfo()).resolves.toMatchObject({
+            settlementStrategy: 'smart-account-x402-preferred',
+            smartAccount: {
+                ready: true,
+                mode: 'x402-only',
+                routeCoverage: 'x402-only',
+                demoReady: true,
+                guardedFallback: true,
+                preferredRoutes: ['x402'],
+                fallbackRoutes: ['mpp-charge', 'mpp-session-open', 'mpp-session-reuse'],
+                supportedRoutes: ['x402'],
+                unsupportedRoutes: ['mpp-charge', 'mpp-session-open', 'mpp-session-reuse'],
+                unsupportedReason: 'MPP charge and MPP session routes still require explicit Keypair signers in the current client stack.',
+                feeFloorApplied: false,
+                preflightFailures: [],
+            },
+        });
+    });
+    it('exposes honest smart-account fallback messaging when only the contract id is configured', async () => {
+        const { getWalletInfo } = await loadWalletModule(undefined, 'CSMARTACCOUNT');
+        await expect(getWalletInfo()).resolves.toMatchObject({
+            settlementStrategy: 'smart-account-partial-fallback',
+            smartAccount: {
+                ready: true,
+                mode: 'x402-only',
+                routeCoverage: 'x402-only',
+                demoReady: false,
+                guardedFallback: true,
+                preflightFailures: ['XMPP_AGENT_SECRET_KEY'],
+                message: 'Smart-account identifiers are configured, but x402 stays on the stable keypair path until the delegated flow is fully demo-ready.',
+            },
+        });
+    });
+    it('enforces the smart-account fee floor in readiness output', async () => {
+        const secret = Keypair.random().secret();
+        const { getWalletInfo, getEffectiveSmartAccountFeeCeiling } = await loadWalletModule(secret, 'CSMARTACCOUNT', 500_000);
+        expect(getEffectiveSmartAccountFeeCeiling()).toBe(2_000_000);
+        await expect(getWalletInfo()).resolves.toMatchObject({
+            smartAccount: {
+                demoReady: true,
+                feeFloorApplied: true,
+                configuredMaxTransactionFeeStroops: 500_000,
+                effectiveMaxTransactionFeeStroops: 2_000_000,
+            },
+        });
+    });
+});

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@vinaystwt/xmpp-wallet",
+  "version": "0.1.0",
+  "description": "Wallet, receipt-signing, and execution-planning helpers for xMPP on Stellar.",
+  "type": "module",
+  "license": "MIT",
+  "main": "dist/wallet/src/index.js",
+  "types": "dist/wallet/src/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "homepage": "https://github.com/Vinaystwt/xMPP#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Vinaystwt/xMPP.git",
+    "directory": "packages/wallet"
+  },
+  "bugs": {
+    "url": "https://github.com/Vinaystwt/xMPP/issues"
+  },
+  "keywords": [
+    "xmpp",
+    "wallet",
+    "stellar",
+    "receipts",
+    "agents"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/wallet/src/index.d.ts",
+      "import": "./dist/wallet/src/index.js",
+      "default": "./dist/wallet/src/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "lint": "eslint src",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run src --passWithNoTests"
+  },
+  "dependencies": {
+    "@stellar/stellar-sdk": "^14.6.1",
+    "@vinaystwt/xmpp-config": "0.1.0",
+    "@vinaystwt/xmpp-types": "0.1.0",
+    "smart-account-kit": "0.2.10"
+  }
+}