Package com.tnsai.tools.fintech

Class LightningTools

java.lang.Object

com.tnsai.tools.fintech.LightningTools

public class LightningTools
extends Object

Function-shape Bitcoin Lightning Network tools — the LangChain-style replacement for the Lightning half of the legacy LightningNetworkTool. Targets LND (Lightning Network Daemon) via its REST gateway (https://api.lightning.community/).

Three typed @Tool methods covering the BOLT11 invoice lifecycle:

Method	Endpoint	Idempotent
lightningCreateInvoice(long, java.lang.String, int)	POST /v1/invoices	✓
lightningPayInvoice(java.lang.String)	POST /v1/channels/transactions	✗ (real BTC moves)
lightningDecodeInvoice(java.lang.String)	GET /v1/payreq/{request}	✓

Units — satoshis

Lightning's native unit is the satoshi (1 BTC = 100,000,000 sat). The POJO exposes amountSats as a Java long — the LLM should not need to know the BTC↔sat conversion, but the parameter description spells it out for safety ("1000 sat ≈ $0.40 USD at $40k/BTC").

Auth

LND's REST gateway authenticates via a hex-encoded macaroon in the Grpc-Metadata-macaroon header. Generate one with lncli bakemacaroon or use the admin macaroon (full access). Admin macaroons can move funds — treat them like a private key.

CLN (Core Lightning) note

Core Lightning uses a different REST API + rune-based auth. Adding CLN support here would double the surface area; if a real consumer needs CLN, it lives in a separate POJO (CoreLightningTools) with the same method shape.

Since:

0.5.7 (Phase 2 batch 7d — built-in tool migration to function shape, see #188)

Constructor Summary

Constructors

Constructor	Description
LightningTools()	Default constructor — reads LIGHTNING_NODE_URL + LND_MACAROON from env.
LightningTools(String nodeUrl, String macaroonHex)	Explicit-credentials constructor.
LightningTools(String nodeUrl, String macaroonHex, okhttp3.OkHttpClient http, com.fasterxml.jackson.databind.ObjectMapper mapper)	Full constructor for tests / shared HTTP.

Method Summary

Modifier and Type	Method	Description
Map<String,Object>	lightningCreateInvoice(long amountSats, String memo, int expirySeconds)
Map<String,Object>	lightningDecodeInvoice(String bolt11)
Map<String,Object>	lightningPayInvoice(String bolt11)

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

LightningTools

public LightningTools()

Default constructor — reads LIGHTNING_NODE_URL + LND_MACAROON from env.

LightningTools

public LightningTools(String nodeUrl,
 String macaroonHex)

Explicit-credentials constructor.

LightningTools

public LightningTools(String nodeUrl,
 String macaroonHex,
 okhttp3.OkHttpClient http,
 com.fasterxml.jackson.databind.ObjectMapper mapper)

Full constructor for tests / shared HTTP.

Method Details

lightningCreateInvoice

@Tool(name="lightning_create_invoice",
      description="Create a BOLT11 Lightning invoice on the configured LND node. {amountSats} is the amount in satoshis (1 BTC = 100,000,000 sat; 1000 sat \u2248 $0.40 USD at $40k/BTC). {expirySeconds} clamps to [1, 30 days]; default 1 hour. Returns {paymentRequest, paymentHash, addIndex, expirySeconds, amountSats, memo}.",
      keywords={"lightning","bitcoin","btc","invoice","bolt11","lnd","satoshi"},
      idempotent=true)
public Map<String,Object> lightningCreateInvoice(@ToolParam(description="Amount in satoshis (long; 1 sat \u2248 0.00000001 BTC)")
 long amountSats,
 @ToolParam(description="Free-text memo embedded in the BOLT11 invoice (visible to the payer)",required=false,defaultValue="")
 String memo,
 @ToolParam(description="Invoice expiry in seconds (1..2592000, default 3600 = 1 hour)",required=false,defaultValue="3600")
 int expirySeconds)
                                          throws IOException

Throws:

IOException

lightningPayInvoice

@Tool(name="lightning_pay_invoice",
      description="DESTRUCTIVE: pay a BOLT11 Lightning invoice via the configured LND node. {bolt11} is the invoice string (starts with \"lnbc\" for mainnet, \"lntb\" for testnet, \"lnbcrt\" for regtest). This is a REAL Bitcoin spend; NOT idempotent at LND\'s side \u2014 the framework\'s retry layer must NOT re-issue this call on transient failures, or the same invoice may be paid twice (LND deduplicates by paymentHash but only within a short window). Returns {paymentHash, status, feeSats, paymentPreimage?}.",
      keywords={"lightning","bitcoin","btc","pay","send","bolt11","lnd"})
public Map<String,Object> lightningPayInvoice(@ToolParam(description="BOLT11 invoice string (starts with \"lnbc\" / \"lntb\" / \"lnbcrt\")")
 String bolt11)
                                       throws IOException

Throws:

IOException

lightningDecodeInvoice

@Tool(name="lightning_decode_invoice",
      description="Decode a BOLT11 Lightning invoice WITHOUT paying it. Returns {amountSats, description, paymentHash, expirySeconds, destinationPubkey, network}. Read-only; safe to call on any invoice the user pasted to inspect amount + memo before deciding whether to pay.",
      keywords={"lightning","bitcoin","btc","decode","inspect","bolt11"},
      idempotent=true)
public Map<String,Object> lightningDecodeInvoice(@ToolParam(description="BOLT11 invoice string to decode (no payment is made)")
 String bolt11)
                                          throws IOException

Throws:

IOException