@nullpay/mcp 1.0.1 → 1.0.4

package/README.md

@@ -1,60 +1,216 @@
-# NullPay MCP
+# @nullpay/mcp
 
-NullPay MCP installs a local MCP server for Claude and lets users connect with only their wallet credentials.
+NullPay MCP is a local Model Context Protocol server for Claude that lets users create invoices, pay invoices, and inspect transactions through chat.
 
-## Install
+The package is designed so the user only needs to provide their own wallet credentials:
+
+- `NULLPAY_MAIN_ADDRESS`
+- `NULLPAY_MAIN_PRIVATE_KEY`
+- `NULLPAY_MAIN_PASSWORD`
+
+NullPay-owned infrastructure stays inside the package or on the backend:
+
+- default backend API: `https://nullpay-backend-ib5q4.ondigitalocean.app/api`
+- default public app URL: `https://nullpay.app`
+- relayer private key: backend only
+
+## How It Works
+
+1. The user runs the setup wizard.
+2. The wizard asks whether to install into Claude Code or Claude Desktop.
+3. The wizard asks for the user's address, private key, and password.
+4. The wizard writes the MCP config file automatically on the user's machine.
+5. Claude starts the local NullPay MCP server with `@nullpay/mcp server`.
+6. The MCP server talks to the NullPay backend and keeps the user's private-key operations local.
+
+## Install For End Users
+
+Run the setup wizard:
 
 ```bash
 npx -y @nullpay/mcp
 ```
 
-The setup wizard asks whether to install into Claude Code or Claude Desktop, then writes the required MCP config automatically on the user's machine.
+You can also call the setup command explicitly:
 
-## User-provided env
+```bash
+npx -y @nullpay/mcp setup
+```
 
-Users only need to provide:
+The wizard writes the required MCP config entry automatically.
 
-- `NULLPAY_MAIN_ADDRESS`
-- `NULLPAY_MAIN_PRIVATE_KEY`
-- `NULLPAY_MAIN_PASSWORD`
+## Manual Claude Configuration
 
-## Tools
+The setup wizard is the recommended path, but you can also add the MCP server manually.
+
+### Claude Desktop
+
+```json
+{
+  "mcpServers": {
+    "nullpay": {
+      "command": "npx",
+      "args": ["-y", "@nullpay/mcp", "server"],
+      "env": {
+        "NULLPAY_MAIN_ADDRESS": "aleo1...",
+        "NULLPAY_MAIN_PRIVATE_KEY": "APrivateKey1...",
+        "NULLPAY_MAIN_PASSWORD": "your-password"
+      }
+    }
+  }
+}
+```
+
+On Windows, Claude Desktop may need:
+
+```json
+{
+  "mcpServers": {
+    "nullpay": {
+      "command": "cmd",
+      "args": ["/c", "npx", "-y", "@nullpay/mcp", "server"],
+      "env": {
+        "NULLPAY_MAIN_ADDRESS": "aleo1...",
+        "NULLPAY_MAIN_PRIVATE_KEY": "APrivateKey1...",
+        "NULLPAY_MAIN_PASSWORD": "your-password"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+The setup wizard can also write the Claude Code config automatically. If needed, the same `server` command is used there too.
+
+After setup, restart Claude and verify the MCP server is available.
+
+## Commands
+
+### Published package
+
+Start the interactive installer:
+
+```bash
+npx -y @nullpay/mcp
+```
+
+Run the MCP server directly:
+
+```bash
+npx -y @nullpay/mcp server
+```
+
+Show help:
+
+```bash
+npx -y @nullpay/mcp --help
+```
+
+### Local development
+
+From `packages/nullpay-mcp`:
+
+```bash
+npm install
+npm run build
+node dist/cli.js
+```
+
+Run the local MCP server directly:
+
+```bash
+node dist/cli.js server
+```
+
+Run in TypeScript during development:
+
+```bash
+npm run dev
+```
+
+## Tooling And Login Model
+
+The MCP server exposes four tools:
 
 - `login`
 - `create_invoice`
 - `pay_invoice`
 - `get_transaction_info`
 
-## Environment
+### `login`
+
+`login` creates or resumes the NullPay session inside the MCP process.
+
+Normal path:
 
-Bundled by NullPay inside the package:
+- uses address + password from tool input or env
+- loads the backend profile
+- validates the password by decrypting stored wallet data
+- restores burner wallet metadata when present
 
-- production backend URL
-- public NullPay base URL
-- Provable API key
-- Provable consumer ID
+Recovery path:
 
-Optional main-wallet credentials for record-backed transaction lookup and automated main-wallet payments:
+- if password is missing but `NULLPAY_MAIN_PRIVATE_KEY` is available
+- the server can recover the backed-up password from on-chain backup records
+- if a full burner backup exists on-chain, it restores the burner wallet automatically
+
+### `create_invoice`
+
+- uses the active wallet address
+- calls the NullPay backend relayer endpoint
+- waits for the invoice hash to resolve from Aleo mapping
+- stores the invoice row in the backend
+- returns a payment link
+
+### `pay_invoice`
+
+- accepts either a full NullPay payment link or an invoice hash
+- prefers the full payment link so merchant address, amount, salt, token, and session id are available immediately
+- builds the payment authorization locally with the user's wallet key
+- sends the authorization to the backend sponsor endpoint
+
+### `get_transaction_info`
+
+- fetches invoice rows from the backend
+- enriches private record-backed data locally when the main private key is available
+
+## Credential Model
+
+User-provided values:
 
 - `NULLPAY_MAIN_ADDRESS`
-- `NULLPAY_MAIN_PASSWORD`
 - `NULLPAY_MAIN_PRIVATE_KEY`
+- `NULLPAY_MAIN_PASSWORD`
+
+Bundled or backend-side values:
+
+- `NULLPAY_BACKEND_URL` defaults internally to production
+- `NULLPAY_PUBLIC_BASE_URL` defaults internally to production
+- relayer secrets stay on the backend
 
-`NULLPAY_MAIN_PVT_KEY` is also accepted as a legacy alias for the private key.
+## Security Notes
 
-When Claude launches the MCP server, it also loads env values from these files if present:
+- The user's private key is intended to stay local to the MCP process.
+- The config file used by Claude contains sensitive wallet credentials and should be treated like a secret file.
+- The MCP server never returns decrypted private keys in tool output.
+- Password recovery from on-chain records only works when the main private key is available locally.
 
-- `packages/nullpay-mcp/.env`
-- repo-root `.env`
-- `backend/.env`
+## Publishing
 
-For relayed invoice creation and sponsored execution, the backend still needs:
+From `packages/nullpay-mcp`:
 
-- `RELAYER_PRIVATE_KEY`
+```bash
+npm run build
+npm publish --access public
+```
+
+If npm 2FA is enabled:
+
+```bash
+npm publish --access public --otp=123456
+```
 
-## Notes
+## License
 
-- Burner wallet private keys remain encrypted at rest in the existing `users` table.
-- The MCP server decrypts burner keys only in memory during payment execution.
-- If `NULLPAY_MAIN_PRIVATE_KEY` is available, the MCP server can fetch invoice amounts from main-wallet records and pay invoices from the main wallet without exposing that key to the model.
-- If the main private key is not available, the MCP server still allows login and invoice creation, and it prompts the user to add the env var for record-backed amount lookup and automated main-wallet payments.
+MIT

package/dist/aleo.d.ts

@@ -53,8 +53,24 @@ export declare function createInvoiceDbRecord(args: {
     }[] | null;
     for_sdk: boolean;
 };
+export interface ParsedBurnerBackupRecord {
+    owner: string;
+    burnerAddress: string;
+    passwordPart: string;
+    pkParts: string[];
+    plaintext: string;
+}
+export interface RecoveredOnChainWalletBackup {
+    password: string;
+    burnerAddress?: string;
+    encryptedBurnerKey?: string;
+    source: 'password_only' | 'full_burner';
+}
 export declare function parseOwnedInvoiceRecord(plaintext: string): ParsedOwnedInvoiceRecord | null;
+export declare function parseBurnerBackupRecord(plaintext: string): ParsedBurnerBackupRecord | null;
 export declare function fetchOwnedInvoiceRecords(privateKey: string): Promise<ParsedOwnedInvoiceRecord[]>;
+export declare function fetchOwnedBurnerBackupRecords(privateKey: string): Promise<ParsedBurnerBackupRecord[]>;
+export declare function recoverOnChainWalletBackup(privateKey: string, ownerAddress: string): Promise<RecoveredOnChainWalletBackup | null>;
 export declare function fetchOwnedInvoiceRecordByHash(privateKey: string, invoiceHash: string): Promise<ParsedOwnedInvoiceRecord | null>;
 export declare function enrichInvoiceWithRecordAmount(invoice: InvoiceRecord, privateKey?: string | null): Promise<InvoiceRecord>;
 export declare function createSponsoredPaymentAuthorization(args: {

package/dist/aleo.js

@@ -13,7 +13,10 @@ exports.invoiceTypeToNumber = invoiceTypeToNumber;
 exports.buildPaymentLink = buildPaymentLink;
 exports.createInvoiceDbRecord = createInvoiceDbRecord;
 exports.parseOwnedInvoiceRecord = parseOwnedInvoiceRecord;
+exports.parseBurnerBackupRecord = parseBurnerBackupRecord;
 exports.fetchOwnedInvoiceRecords = fetchOwnedInvoiceRecords;
+exports.fetchOwnedBurnerBackupRecords = fetchOwnedBurnerBackupRecords;
+exports.recoverOnChainWalletBackup = recoverOnChainWalletBackup;
 exports.fetchOwnedInvoiceRecordByHash = fetchOwnedInvoiceRecordByHash;
 exports.enrichInvoiceWithRecordAmount = enrichInvoiceWithRecordAmount;
 exports.createSponsoredPaymentAuthorization = createSponsoredPaymentAuthorization;
@@ -52,6 +55,30 @@ function fieldToString(fieldVal) {
         return '';
     }
 }
+function fieldChunksToString(chunks) {
+    let result = '';
+    for (const chunk of chunks) {
+        if (!chunk || chunk === '0field' || chunk === '0') {
+            continue;
+        }
+        const numeric = chunk.replace('field', '').replace('u128', '').replace('u64', '');
+        let value;
+        try {
+            value = BigInt(numeric);
+        }
+        catch {
+            continue;
+        }
+        let hex = value.toString(16);
+        if (hex.length % 2 !== 0) {
+            hex = '0' + hex;
+        }
+        for (let i = 0; i < hex.length; i += 2) {
+            result += String.fromCharCode(Number.parseInt(hex.slice(i, i + 2), 16));
+        }
+    }
+    return result;
+}
 function parseNumericValue(value) {
     if (!value) {
         return 0;
@@ -305,6 +332,41 @@ function parseOwnedInvoiceRecord(plaintext) {
         return null;
     }
 }
+function parseBurnerBackupRecord(plaintext) {
+    try {
+        const getVal = (key) => {
+            const regex = new RegExp(`(?:${key}|"${key}"):\\s*([\\w\\d\\.]+)`);
+            const match = plaintext.match(regex);
+            if (match && match[1]) {
+                return match[1].replace('.private', '').replace('.public', '');
+            }
+            return null;
+        };
+        const owner = getVal('owner');
+        const burnerAddress = getVal('burner_address');
+        const passwordPart = getVal('password_part');
+        if (!burnerAddress || !passwordPart) {
+            return null;
+        }
+        const pkParts = [];
+        for (let i = 1; i <= 10; i += 1) {
+            const part = getVal(`pk_part_${i}`);
+            if (part && part !== '0field' && part !== '0') {
+                pkParts.push(part);
+            }
+        }
+        return {
+            owner: owner || '',
+            burnerAddress,
+            passwordPart,
+            pkParts,
+            plaintext,
+        };
+    }
+    catch {
+        return null;
+    }
+}
 async function fetchOwnedInvoiceRecords(privateKey) {
     const session = await getScannerSession(privateKey);
     const records = await fetchOwnedProgramRecords(session, exports.PROGRAM_ID);
@@ -325,6 +387,67 @@ async function fetchOwnedInvoiceRecords(privateKey) {
     }
     return parsed;
 }
+async function fetchOwnedBurnerBackupRecords(privateKey) {
+    const session = await getScannerSession(privateKey);
+    const records = await fetchOwnedProgramRecords(session, exports.PROGRAM_ID);
+    const parsed = [];
+    for (const record of records) {
+        let plaintext = record.record_plaintext || record.plaintext || '';
+        if (!plaintext && record.record_ciphertext) {
+            const { RecordCiphertext } = await (0, esm_1.dynamicImport)('@provablehq/sdk');
+            const ciphertext = RecordCiphertext.fromString(record.record_ciphertext);
+            plaintext = ciphertext.decrypt(session.account.viewKey()).toString();
+        }
+        if (!plaintext)
+            continue;
+        const burnerRecord = parseBurnerBackupRecord(plaintext);
+        if (burnerRecord) {
+            parsed.push(burnerRecord);
+        }
+    }
+    return parsed;
+}
+async function recoverOnChainWalletBackup(privateKey, ownerAddress) {
+    const records = await fetchOwnedBurnerBackupRecords(privateKey);
+    let passwordOnlyMatch = null;
+    let fullBurnerMatch = null;
+    for (const record of records) {
+        const ownerMatches = record.owner === ownerAddress;
+        const passwordOnlyMatches = record.burnerAddress === ownerAddress;
+        if (!ownerMatches && !passwordOnlyMatches) {
+            continue;
+        }
+        const encryptedPayload = fieldChunksToString(record.pkParts);
+        const hasRealPayload = Boolean(encryptedPayload && !encryptedPayload.startsWith('0'));
+        if (hasRealPayload) {
+            fullBurnerMatch = record;
+        }
+        else if (!passwordOnlyMatch) {
+            passwordOnlyMatch = record;
+        }
+    }
+    const bestMatch = fullBurnerMatch || passwordOnlyMatch;
+    if (!bestMatch) {
+        return null;
+    }
+    const password = fieldChunksToString([bestMatch.passwordPart]);
+    if (!password) {
+        return null;
+    }
+    if (fullBurnerMatch) {
+        const encryptedBurnerKey = fieldChunksToString(fullBurnerMatch.pkParts);
+        return {
+            password,
+            burnerAddress: fullBurnerMatch.burnerAddress,
+            encryptedBurnerKey: encryptedBurnerKey || undefined,
+            source: 'full_burner',
+        };
+    }
+    return {
+        password,
+        source: 'password_only',
+    };
+}
 async function fetchOwnedInvoiceRecordByHash(privateKey, invoiceHash) {
     const normalized = normalizeInvoiceHash(invoiceHash);
     const records = await fetchOwnedInvoiceRecords(privateKey);
@@ -432,14 +555,18 @@ async function getFreezeListIndex(index) {
     return value ? value.replace(/"/g, '') : null;
 }
 async function generateFreezeListProof(targetIndex = 1, occupiedLeafValue) {
-    const { Field, Poseidon4 } = await (0, esm_1.dynamicImport)('@provablehq/wasm');
+    const { Plaintext } = await (0, esm_1.dynamicImport)('@provablehq/sdk');
+    const { Poseidon4 } = await (0, esm_1.dynamicImport)('@provablehq/wasm');
     const hasher = new Poseidon4();
     const emptyHashes = [];
     let currentEmpty = '0field';
+    const hashFields = (values) => {
+        const plaintext = Plaintext.fromString(`[${values.join(', ')}]`);
+        return hasher.hash(plaintext.toFields()).toString();
+    };
     for (let level = 0; level < 16; level += 1) {
         emptyHashes.push(currentEmpty);
-        const field = Field.fromString(currentEmpty);
-        currentEmpty = hasher.hash([field, field]).toString();
+        currentEmpty = hashFields([currentEmpty, currentEmpty]);
     }
     let currentHash = '0field';
     let currentIndex = targetIndex;
@@ -452,12 +579,12 @@ async function generateFreezeListProof(targetIndex = 1, occupiedLeafValue) {
             siblingHash = occupiedLeafValue;
         }
         proofSiblings.push(siblingHash);
-        const left = Field.fromString(isLeft ? currentHash : siblingHash);
-        const right = Field.fromString(isLeft ? siblingHash : currentHash);
-        currentHash = hasher.hash([left, right]).toString();
+        currentHash = isLeft
+            ? hashFields([currentHash, siblingHash])
+            : hashFields([siblingHash, currentHash]);
         currentIndex = Math.floor(currentIndex / 2);
     }
-    return `[${proofSiblings.join(', ')}]`;
+    return `{ siblings: [${proofSiblings.join(', ')}], leaf_index: ${targetIndex}u32 }`;
 }
 async function createSponsoredPaymentAuthorization(args) {
     const session = await getScannerSession(args.walletPrivateKey);

package/dist/env.d.ts

@@ -1,4 +1,4 @@
-export declare const DEFAULT_BACKEND_URL = "http://localhost:3000/api";
+export declare const DEFAULT_BACKEND_URL = "https://nullpay-backend-ib5q4.ondigitalocean.app/api";
 export declare const DEFAULT_PUBLIC_BASE_URL = "https://nullpay.app";
 export declare function parseDotEnv(content: string): Record<string, string>;
 export declare function loadEnvFiles(): void;

package/dist/env.js

@@ -10,7 +10,7 @@ exports.getRuntimeConfig = getRuntimeConfig;
 exports.getProvableConfig = getProvableConfig;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
-exports.DEFAULT_BACKEND_URL = 'http://localhost:3000/api';
+exports.DEFAULT_BACKEND_URL = 'https://nullpay-backend-ib5q4.ondigitalocean.app/api';
 exports.DEFAULT_PUBLIC_BASE_URL = 'https://nullpay.app';
 const DEFAULT_PROVABLE_API_KEY = 'tWR9YWkM5SVmx1u3m7My8S4p4e2s84Oe';
 const DEFAULT_PROVABLE_CONSUMER_ID = '73ba1b21-d8f7-4d7f-bfd9-0408a4e183f3';

package/dist/service.js

@@ -142,7 +142,7 @@ class NullPayMcpService {
         return [
             {
                 name: 'login',
-                description: 'Login to NullPay, validate password, create burner wallet, or switch active wallet. If NULLPAY_MAIN_ADDRESS and NULLPAY_MAIN_PASSWORD are configured, call this tool with empty arguments and do not ask the user to share secrets in chat. The MCP server can also read NULLPAY_MAIN_PRIVATE_KEY from env without exposing it to the model.',
+                description: 'Login to NullPay, validate password, create burner wallet, recover a backed-up password or burner wallet from on-chain records, or switch active wallet. If NULLPAY_MAIN_ADDRESS and NULLPAY_MAIN_PASSWORD are configured, call this tool with empty arguments and do not ask the user to share secrets in chat. The MCP server can also read NULLPAY_MAIN_PRIVATE_KEY from env without exposing it to the model.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -222,21 +222,79 @@ class NullPayMcpService {
     async login(args) {
         const envMain = getMainWalletEnv();
         const address = (args.address || envMain.address || '').trim();
-        const password = args.password || envMain.password || '';
+        let password = args.password || envMain.password || '';
         const mainPrivateKey = args.main_private_key || envMain.privateKey || null;
-        if (!address || !password) {
-            throw new Error('Address and password are required. You can pass them directly or set NULLPAY_MAIN_ADDRESS and NULLPAY_MAIN_PASSWORD in env.');
+        if (!address) {
+            throw new Error('Address is required. You can pass it directly or set NULLPAY_MAIN_ADDRESS in env.');
         }
         const addressHash = (0, crypto_1.hashAddress)(address);
         const existingProfile = await this.backend.getUserProfile(addressHash);
         let encryptedMainAddress = existingProfile?.main_address || null;
+        let recoveredBackupSource = null;
+        let recoveredBurnerAddress = null;
+        let recoveredEncryptedBurnerKey = null;
+        let usedRecoveredPassword = false;
+        let restoredBurnerFromChain = false;
+        let chainBackupLoaded = false;
+        const loadChainBackup = async () => {
+            if (chainBackupLoaded || !mainPrivateKey) {
+                return null;
+            }
+            chainBackupLoaded = true;
+            const recovered = await (0, aleo_1.recoverOnChainWalletBackup)(mainPrivateKey, address);
+            if (!recovered) {
+                return null;
+            }
+            recoveredBackupSource = recovered.source;
+            recoveredBurnerAddress = recovered.burnerAddress || null;
+            recoveredEncryptedBurnerKey = recovered.encryptedBurnerKey || null;
+            return recovered;
+        };
+        const attemptRecovery = async () => {
+            const recovered = await loadChainBackup();
+            if (!recovered?.password) {
+                return false;
+            }
+            password = recovered.password;
+            usedRecoveredPassword = true;
+            return true;
+        };
         if (encryptedMainAddress) {
-            const decrypted = await (0, crypto_1.decryptWithPassword)(encryptedMainAddress, password);
+            if (!password) {
+                const recovered = await attemptRecovery();
+                if (!recovered) {
+                    throw new Error('Password is required for this NullPay account. Set NULLPAY_MAIN_PASSWORD, pass password directly, or provide NULLPAY_MAIN_PRIVATE_KEY so the MCP can recover a backed-up password from on-chain records.');
+                }
+            }
+            let decrypted;
+            try {
+                decrypted = await (0, crypto_1.decryptWithPassword)(encryptedMainAddress, password);
+            }
+            catch {
+                const recovered = await attemptRecovery();
+                if (!recovered) {
+                    throw new Error('Password is incorrect for this NullPay account, and no recoverable on-chain password backup was found for the provided main private key.');
+                }
+                decrypted = await (0, crypto_1.decryptWithPassword)(encryptedMainAddress, password);
+            }
             if (decrypted !== address) {
-                throw new Error('Password is incorrect for this NullPay account.');
+                const recovered = await attemptRecovery();
+                if (!recovered) {
+                    throw new Error('Password is incorrect for this NullPay account.');
+                }
+                const recoveredAddress = await (0, crypto_1.decryptWithPassword)(encryptedMainAddress, password);
+                if (recoveredAddress !== address) {
+                    throw new Error('Recovered password does not match the provided address.');
+                }
             }
         }
         else {
+            if (!password) {
+                const recovered = await attemptRecovery();
+                if (!recovered) {
+                    throw new Error('Password is required to create a new NullPay account unless the MCP can recover it from on-chain backup records using NULLPAY_MAIN_PRIVATE_KEY.');
+                }
+            }
             encryptedMainAddress = await (0, crypto_1.encryptWithPassword)(address, password);
         }
         if (!encryptedMainAddress) {
@@ -246,7 +304,21 @@ class NullPayMcpService {
         let encryptedBurnerKey = existingProfile?.encrypted_burner_key || null;
         let burnerAddress = null;
         if (encryptedBurnerAddress) {
-            burnerAddress = await (0, crypto_1.decryptWithPassword)(encryptedBurnerAddress, password);
+            try {
+                burnerAddress = await (0, crypto_1.decryptWithPassword)(encryptedBurnerAddress, password);
+            }
+            catch {
+                burnerAddress = null;
+            }
+        }
+        if (!encryptedBurnerKey || !burnerAddress || !encryptedBurnerAddress) {
+            await loadChainBackup();
+        }
+        if ((!encryptedBurnerAddress || !encryptedBurnerKey || !burnerAddress) && recoveredBurnerAddress && recoveredEncryptedBurnerKey) {
+            burnerAddress = recoveredBurnerAddress;
+            encryptedBurnerAddress = await (0, crypto_1.encryptWithPassword)(recoveredBurnerAddress, password);
+            encryptedBurnerKey = recoveredEncryptedBurnerKey;
+            restoredBurnerFromChain = true;
         }
         if (args.create_burner_wallet && !encryptedBurnerKey) {
             const { PrivateKey } = await (0, esm_1.dynamicImport)('@provablehq/sdk');
@@ -282,11 +354,17 @@ class NullPayMcpService {
         });
         const usedEnvCredentials = Boolean(envMain.address && envMain.password && !args.address && !args.password);
         const lines = [
-            usedEnvCredentials ? 'Used main-wallet address and password from MCP env.' : `Logged in as ${address}.`,
+            usedEnvCredentials ? 'Used main-wallet address and password from MCP env.' : 'Logged in as ' + address + '.',
             encryptedBurnerKey
-                ? `Active wallet: ${preferredWallet}. Burner wallet is available${burnerAddress ? ` at ${burnerAddress}` : ''}.`
+                ? 'Active wallet: ' + preferredWallet + '. Burner wallet is available' + (burnerAddress ? ' at ' + burnerAddress : '') + '.'
                 : 'Active wallet: main. No burner wallet is stored yet.',
         ];
+        if (usedRecoveredPassword) {
+            lines.push('Recovered your NullPay password from on-chain backup records using the main wallet private key (' + (recoveredBackupSource === 'full_burner' ? 'full burner backup' : 'password backup') + ').');
+        }
+        if (restoredBurnerFromChain) {
+            lines.push('Recovered your backed-up burner wallet from on-chain records and restored it into the MCP session.');
+        }
         if (mainPrivateKey) {
             lines.push('Main wallet private key is available for record-backed amount lookup and main-wallet payments. Active wallet is set to main by default, and you can switch to burner anytime by logging in again with wallet_preference set to burner. Invoice lookup will prefer the main wallet records even when you pay from burner.');
         }
@@ -306,6 +384,9 @@ class NullPayMcpService {
                 has_main_private_key: Boolean(mainPrivateKey),
                 main_private_key_from_env: Boolean(envMain.privateKey),
                 used_env_credentials: usedEnvCredentials,
+                used_recovered_password: usedRecoveredPassword,
+                recovery_source: recoveredBackupSource,
+                restored_burner_from_chain: restoredBurnerFromChain,
             },
         };
     }

package/package.json

@@ -1,34 +1,34 @@
 {
-    "name":  "@nullpay/mcp",
-    "version":  "1.0.1",
-    "description":  "NullPay MCP server and Claude setup wizard for conversational payment flows",
-    "type":  "commonjs",
-    "main":  "dist/server.js",
-    "types":  "dist/server.d.ts",
-    "bin":  {
-                "nullpay-mcp":  "./dist/cli.js"
-            },
-    "files":  [
-                  "dist",
-                  "README.md"
-              ],
-    "scripts":  {
-                    "build":  "tsc -p tsconfig.json",
-                    "start":  "node dist/cli.js server",
-                    "dev":  "ts-node src/cli.ts server",
-                    "setup":  "ts-node src/cli.ts setup",
-                    "prepublishOnly":  "npm run build"
-                },
-    "publishConfig":  {
-                          "access":  "public"
-                      },
-    "dependencies":  {
-                         "@provablehq/sdk":  "^0.9.18",
-                         "@provablehq/wasm":  "^0.9.18"
-                     },
-    "devDependencies":  {
-                            "@types/node":  "^25.4.0",
-                            "ts-node":  "^10.9.2",
-                            "typescript":  "^5.9.3"
-                        }
+    "name": "@nullpay/mcp",
+    "version": "1.0.4",
+    "description": "NullPay MCP server and Claude setup wizard for conversational payment flows",
+    "type": "commonjs",
+    "main": "dist/server.js",
+    "types": "dist/server.d.ts",
+    "bin": {
+        "nullpay-mcp": "./dist/cli.js"
+    },
+    "files": [
+        "dist",
+        "README.md"
+    ],
+    "scripts": {
+        "build": "tsc -p tsconfig.json",
+        "start": "node dist/cli.js server",
+        "dev": "ts-node src/cli.ts server",
+        "setup": "ts-node src/cli.ts setup",
+        "prepublishOnly": "npm run build"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "dependencies": {
+        "@provablehq/sdk": "^0.9.18",
+        "@provablehq/wasm": "^0.9.18"
+    },
+    "devDependencies": {
+        "@types/node": "^25.4.0",
+        "ts-node": "^10.9.2",
+        "typescript": "^5.9.3"
+    }
 }