Lightning Wallet MCP

Instructions

Implementation Reference

• src/lightning-faucet.ts:898-936 (handler)

  The actual implementation of decodeInvoice that makes the API request to decode a BOLT11 invoice.

  async decodeInvoice(bolt11: string): Promise<{
    amountSats: number;
    description: string;
    paymentHash: string;
    destination: string;
    expiresAt: string;
    isExpired: boolean;
    createdAt?: string;
    rawResponse: ApiResponse;
  }> {
    const result = await this.request<ApiResponse & {
      amount_sats?: number;
      num_satoshis?: string;
      description?: string;
      payment_hash?: string;
      destination?: string;
      timestamp?: string;
      expiry?: string;
      expires_at?: string;
      is_expired?: boolean;
    }>('decode_invoice', { invoice: bolt11 });
  
    const amountSats = result.amount_sats || parseInt(result.num_satoshis || '0', 10);
    const timestamp = result.timestamp ? parseInt(result.timestamp, 10) : 0;
    const expiry = result.expiry ? parseInt(result.expiry, 10) : 3600;
    const expiresAt = result.expires_at || new Date((timestamp + expiry) * 1000).toISOString();
    const isExpired = result.is_expired ?? (timestamp + expiry < Date.now() / 1000);
  
    return {
      amountSats,
      description: result.description || '',
      paymentHash: result.payment_hash || '',
      destination: result.destination || '',
      expiresAt,
      isExpired,
      createdAt: timestamp ? new Date(timestamp * 1000).toISOString() : undefined,
      rawResponse: result,
    };
  }

• src/index.ts:1376-1396 (registration)

  The MCP tool handler that invokes decodeInvoice when the 'decode_invoice' tool is called.

  case 'decode_invoice': {
    const parsed = DecodeInvoiceSchema.parse(args);
    const result = await session.requireClient().decodeInvoice(parsed.bolt11);
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify({
            success: true,
            amount_sats: result.amountSats,
            description: result.description,
            payment_hash: result.paymentHash,
            destination: result.destination,
            expires_at: result.expiresAt,
            is_expired: result.isExpired,
            created_at: result.createdAt,
          }, null, 2),
        },
      ],
    };
  }

• src/index.ts:208-211 (schema)

  Input validation schema for the decode_invoice tool.

  const DecodeInvoiceSchema = z.object({
    bolt11: z.string().regex(/^ln(bc|tb|bcrt)1[a-z0-9]+$/i, 'Invalid BOLT11 invoice format')
      .describe('BOLT11 invoice string to decode'),
  });