glclient

  1from . import scheduler_pb2 as schedpb
  2from . import greenlight_pb2 as nodepb
  3from pyln import grpc as clnpb  # type: ignore
  4from pyln.grpc import Amount, AmountOrAll, AmountOrAny  # noqa: F401
  5from . import glclient as native
  6from .glclient import backup_decrypt_with_seed  # noqa: F401
  7from .tls import TlsConfig
  8from google.protobuf.message import Message as PbMessage
  9from binascii import hexlify, unhexlify
 10from typing import Optional, List, Iterable, Any, Type, TypeVar
 11import logging
 12from glclient.lsps import LspClient
 13from glclient.glclient import Credentials
 14
 15
 16backup_decrypt_with_seed = native.backup_decrypt_with_seed
 17
 18
 19# Keep in sync with the libhsmd version, this is tested in unit tests.
 20__version__ = "v24.02"
 21
 22
 23E = TypeVar("E", bound=PbMessage)
 24
 25
 26def _convert(cls: Type[E], res: Iterable[Any]) -> E:
 27    return cls.FromString(bytes(res))
 28
 29
 30class Signer(object):
 31    def __init__(self, secret: bytes, network: str, creds: Credentials):
 32        self.inner = native.Signer(secret, network, creds)
 33        self.creds = creds
 34        self.handle: Optional[native.SignerHandle] = None
 35
 36    def run_in_thread(self) -> "native.SignerHandle":
 37        if self.handle is not None:
 38            raise ValueError(
 39                "This signer is already running, please shut it down before starting it again"
 40            )
 41        self.handle = self.inner.run_in_thread()
 42        return self.handle
 43
 44    def run_in_foreground(self) -> None:
 45        return self.inner.run_in_foreground()
 46
 47    def node_id(self) -> bytes:
 48        return bytes(self.inner.node_id())
 49
 50    def version(self) -> str:
 51        return self.inner.version()
 52
 53    def sign_challenge(self, message: bytes) -> bytes:
 54        return bytes(self.inner.sign_challenge(message))
 55
 56    def shutdown(self) -> None:
 57        if self.handle is None:
 58            raise ValueError("Attempted to shut down a signer that is not running")
 59        self.handle.shutdown()
 60        self.handle = None
 61
 62    def create_rune(
 63        self, restrictions: List[List[str]], rune: Optional[str] = None
 64    ) -> str:
 65        return self.inner.create_rune(restrictions, rune)
 66
 67    def is_running(self) -> bool:
 68        return self.handle is not None
 69
 70
 71class Scheduler(object):
 72
 73    def __init__(self, network: str, creds: Optional[Credentials] = None):
 74        self.network = network
 75        self.creds = creds if creds is not None else native.Credentials()
 76        self.inner = native.Scheduler(network, self.creds)
 77
 78    def schedule(self) -> schedpb.NodeInfoResponse:
 79        res = self.inner.schedule()
 80        return schedpb.NodeInfoResponse.FromString(bytes(res))
 81
 82    def get_node_info(self, wait: bool = False):
 83        res = self.inner.get_node_info(wait)
 84        return schedpb.NodeInfoResponse.FromString(bytes(res))
 85
 86    def register(self, signer: Signer, invite_code: Optional[str] = None) -> schedpb.RegistrationResponse:
 87        res = self.inner.register(signer.inner, invite_code)
 88        return schedpb.RegistrationResponse.FromString(bytes(res))
 89
 90    def recover(self, signer: Signer) -> schedpb.RecoveryResponse:
 91        res = self.inner.recover(signer.inner)
 92        return schedpb.RecoveryResponse.FromString(bytes(res))
 93
 94    def authenticate(self, creds: Credentials):
 95        self.creds = creds
 96        self.inner = self.inner.authenticate(creds)
 97        return self
 98
 99    def export_node(self) -> schedpb.ExportNodeResponse:
100        res = schedpb.ExportNodeResponse
101        return res.FromString(bytes(self.inner.export_node()))
102
103    def node(self) -> "Node":
104        res = self.inner.node()
105        info = schedpb.NodeInfoResponse.FromString(bytes(res))
106        return Node(
107            node_id=self.creds.node_id(),
108            grpc_uri=info.grpc_uri,
109            creds=self.creds,
110        )
111
112    def get_invite_codes(self) -> schedpb.ListInviteCodesResponse:
113        cls = schedpb.ListInviteCodesResponse
114        return cls.FromString(bytes(self.inner.get_invite_codes()))
115
116    def add_outgoing_webhook(self, uri: str) -> schedpb.AddOutgoingWebhookResponse:
117        res = self.inner.add_outgoing_webhook(uri)
118        return schedpb.AddOutgoingWebhookResponse.FromString(bytes(res))
119
120    def list_outgoing_webhooks(self) -> schedpb.ListOutgoingWebhooksResponse:
121        res = self.inner.list_outgoing_webhooks()
122        return schedpb.ListOutgoingWebhooksResponse.FromString(bytes(res))
123
124    def delete_outgoing_webhook(self, webhook_id: int) -> None:
125        res = self.inner.delete_outgoing_webhooks([webhook_id])
126
127    def delete_outgoing_webhooks(self, webhook_ids: List[int]) -> None:
128        res = self.inner.delete_outgoing_webhooks(webhook_ids)
129
130    def rotate_outgoing_webhook_secret(self, webhook_id: int) -> schedpb.WebhookSecretResponse:
131        res = self.inner.rotate_outgoing_webhook_secret(webhook_id)
132        return schedpb.WebhookSecretResponse.FromString(bytes(res))
133
134
135class Node(object):
136
137    def __init__(
138        self, node_id: bytes, grpc_uri: str, creds: Credentials
139    ) -> None:
140        self.creds = creds
141        self.grpc_uri = grpc_uri
142        self.inner = native.Node(
143            node_id=node_id, grpc_uri=grpc_uri, creds=creds
144        )
145        self.logger = logging.getLogger("glclient.Node")
146
147    def get_info(self) -> clnpb.GetinfoResponse:
148        uri = "/cln.Node/Getinfo"
149        req = clnpb.GetinfoRequest().SerializeToString()
150        res = clnpb.GetinfoResponse
151
152        return res.FromString(bytes(self.inner.call(uri, bytes(req))))
153
154    def stop(self) -> None:
155        uri = "/cln.Node/Stop"
156        req = clnpb.StopRequest().SerializeToString()
157
158        try:
159            # This fails, since we just get disconnected, but that's
160            # on purpose, so drop the error silently.
161            self.inner.call(uri, bytes(req))
162        except ValueError as e:
163            self.logger.debug(
164                f"Caught an expected exception: {e}. Don't worry it's expected."
165            )
166
167    def list_funds(
168        self,
169        spent: Optional[bool] = None,
170    ) -> clnpb.ListfundsResponse:
171        uri = "/cln.Node/ListFunds"
172        res = clnpb.ListfundsResponse
173        req = clnpb.ListfundsRequest(
174            spent=spent,
175        ).SerializeToString()
176
177        return res.FromString(bytes(self.inner.call(uri, bytes(req))))
178
179    def list_peers(self) -> clnpb.ListpeersResponse:
180        uri = "/cln.Node/ListPeers"
181        req = clnpb.ListpeersRequest().SerializeToString()
182        res = clnpb.ListpeersResponse
183
184        return res.FromString(
185            bytes(self.inner.call(uri, bytes(req)))
186        )
187
188    def list_peer_channels(
189            self,
190            node_id: Optional[bytes] = None
191    ) -> clnpb.ListpeerchannelsResponse:
192        uri = "/cln.Node/ListPeerChannels"
193        req = clnpb.ListpeerchannelsRequest(
194            id=node_id,
195        ).SerializeToString()
196        res = clnpb.ListpeerchannelsResponse
197        return res.FromString(
198            bytes(self.inner.call(uri, bytes(req)))
199        )
200
201    def list_closed_channels(self) -> clnpb.ListclosedchannelsResponse:
202        uri = "/cln.Node/ListClosedChannels"
203        req = clnpb.ListclosedchannelsRequest().SerializeToString()
204        res = clnpb.ListclosedchannelsResponse
205
206        return res.FromString(bytes(self.inner.call(uri, bytes(req))))
207
208    def list_channels(
209        self,
210        short_channel_id: Optional[str] = None,
211        source: Optional[bytes] = None,
212        destination: Optional[bytes] = None,
213    ) -> clnpb.ListchannelsResponse:
214        uri = "/cln.Node/ListChannels"
215        req = clnpb.ListchannelsRequest(
216            short_channel_id=short_channel_id, source=source, destination=destination
217        ).SerializeToString()
218        res = clnpb.ListchannelsResponse
219
220        return res.FromString(bytes(self.inner.call(uri, bytes(req))))
221
222    def listpays(
223        self,
224        bolt11: Optional[str] = None,
225        payment_hash: Optional[bytes] = None,
226        status: Optional[clnpb.ListpaysRequest.ListpaysStatus.ValueType] = None,
227    ) -> clnpb.ListpaysResponse:
228        uri = "/cln.Node/ListPays"
229        req = clnpb.ListpaysRequest(
230            bolt11=bolt11,
231            payment_hash=payment_hash,
232            status=status,
233        ).SerializeToString()
234        res = clnpb.ListpaysResponse
235
236        return res.FromString(bytes(self.inner.call(uri, req)))
237
238    def list_invoices(
239        self,
240        label: Optional[str] = None,
241        invstring: Optional[str] = None,
242        payment_hash: Optional[bytes] = None,
243        offer_id: Optional[str] = None,
244        index: Optional[clnpb.ListinvoicesRequest.ListinvoicesIndex.ValueType] = None,
245        start: Optional[int] = None,
246        limit: Optional[int] = None,
247    ) -> clnpb.ListinvoicesResponse:
248        uri = "/cln.Node/ListInvoices"
249        res = clnpb.ListinvoicesResponse
250        req = clnpb.ListinvoicesRequest(
251            label=label,
252            invstring=invstring,
253            payment_hash=payment_hash,
254            offer_id=offer_id,
255            index=index,
256            start=start,
257            limit=limit,
258        ).SerializeToString()
259        return res.FromString(bytes(self.inner.call(uri, bytes(req))))
260
261    def connect_peer(
262        self, node_id, host: Optional[str] = None, port: Optional[int] = None
263    ) -> clnpb.ConnectResponse:
264        if len(node_id) == 33:
265            node_id = hexlify(node_id)
266
267        if isinstance(node_id, bytes):
268            node_id = node_id.decode("ASCII")
269
270        uri = "/cln.Node/ConnectPeer"
271        res = clnpb.ConnectResponse
272        req = clnpb.ConnectRequest(
273            id=node_id,
274            host=host,
275            port=port,
276        ).SerializeToString()
277
278        return res.FromString(bytes(self.inner.call(uri, bytes(req))))
279
280    def decode(self, string: str) -> clnpb.DecodeResponse:
281        uri = "/cln.Node/Decode"
282        res = clnpb.DecodeResponse
283        req = clnpb.DecodeRequest(
284            string=string,
285        ).SerializeToString()
286
287        return res.FromString(bytes(self.inner.call(uri, bytes(req))))
288
289    def decodepay(
290        self, bolt11: str, description: Optional[str]
291    ) -> clnpb.DecodepayResponse:
292        uri = "/cln.Node/DecodePay"
293        res = clnpb.DecodepayResponse
294        req = clnpb.DecodepayRequest(
295            bolt11=bolt11,
296            description=description,
297        ).SerializeToString()
298
299        return res.FromString(bytes(self.inner.call(uri, bytes(req))))
300
301    def disconnect_peer(self, peer_id: str, force=False) -> clnpb.DisconnectResponse:
302        uri = "/cln.Node/Disconnect"
303        res = clnpb.DisconnectResponse
304        req = clnpb.DisconnectRequest(
305            id=bytes.fromhex(peer_id),
306            force=force,
307        ).SerializeToString()
308
309        return res.FromString(bytes(self.inner.call(uri, bytes(req))))
310
311    def new_address(self) -> clnpb.NewaddrResponse:
312        uri = "/cln.Node/NewAddr"
313        req = clnpb.NewaddrRequest().SerializeToString()
314        res = clnpb.NewaddrResponse
315
316        return res.FromString(bytes(self.inner.call(uri, req)))
317
318    def withdraw(
319        self, destination, amount: AmountOrAll, minconf: int = 0
320    ) -> clnpb.WithdrawResponse:
321        uri = "/cln.Node/Withdraw"
322        res = clnpb.WithdrawResponse
323        req = clnpb.WithdrawRequest(
324            destination=destination, satoshi=amount, minconf=minconf
325        ).SerializeToString()
326
327        return res.FromString(bytes(self.inner.call(uri, bytes(req))))
328
329    def fund_channel(
330        self,
331        id: bytes,
332        amount,
333        announce: Optional[bool] = False,
334        minconf: Optional[int] = 1,
335    ) -> clnpb.FundchannelResponse:
336
337        if len(id) != 33:
338            raise ValueError("id is not 33 bytes long")
339
340        uri = "/cln.Node/FundChannel"
341        res = clnpb.FundchannelResponse
342        req = clnpb.FundchannelRequest(
343            id=id,
344            amount=amount,
345            announce=announce,
346            minconf=minconf,
347        ).SerializeToString()
348
349        return res.FromString(bytes(self.inner.call(uri, bytes(req))))
350
351    def close(
352        self, id: bytes, unilateraltimeout=None, destination=None
353    ) -> clnpb.CloseResponse:
354        if len(id) != 33:
355            raise ValueError("node_id is not 33 bytes long")
356
357        uri = "/cln.Node/Close"
358        res = clnpb.CloseResponse
359        req = clnpb.CloseRequest(
360            id=id.hex(),
361            unilateraltimeout=unilateraltimeout,
362            destination=destination,
363        ).SerializeToString()
364
365        return res.FromString(bytes(self.inner.call(uri, bytes(req))))
366
367    def invoice(
368        self,
369        amount_msat: clnpb.AmountOrAny,
370        label: str,
371        description: str,
372        expiry: Optional[int] = None,
373        fallbacks: Optional[List[str]] = None,
374        preimage: Optional[bytes] = None,
375        cltv: Optional[int] = None,
376        deschashonly: Optional[bool] = None,
377    ) -> clnpb.InvoiceResponse:
378        if preimage and len(preimage) != 32:
379            raise ValueError("Preimage must be 32 bytes in length")
380
381        uri = "/cln.Node/Invoice"
382        res = clnpb.InvoiceResponse
383        req = clnpb.InvoiceRequest(
384            amount_msat=amount_msat,
385            label=label,
386            description=description,
387            preimage=preimage,
388            expiry=expiry,
389            fallbacks=fallbacks,
390            cltv=cltv,
391            deschashonly=deschashonly,
392        ).SerializeToString()
393
394        return res.FromString(bytes(self.inner.call(uri, bytes(req))))
395
396    def pay(
397        self,
398        bolt11: str,
399        amount_msat: Optional[clnpb.Amount] = None,
400        retry_for: int = 0,
401        maxfee: Optional[clnpb.Amount] = None,
402        maxfeepercent: Optional[float] = None,
403    ) -> clnpb.PayResponse:
404        uri = "/cln.Node/Pay"
405        res = clnpb.PayResponse
406        req = clnpb.PayRequest(
407            bolt11=bolt11,
408            amount_msat=amount_msat,
409            retry_for=retry_for,
410            maxfeepercent=maxfeepercent,
411            maxfee=maxfee,
412        ).SerializeToString()
413
414        return res.FromString(bytes(self.inner.call(uri, bytes(req))))
415
416    def trampoline_pay(
417            self,
418            bolt11: str,
419            trampoline_node_id: bytes,
420            amount_msat: Optional[int] = None,
421            label: Optional[str] = None
422    ):
423        res = self.inner.trampoline_pay(
424            bolt11=bolt11,
425            trampoline_node_id=trampoline_node_id,
426            amount_msat=amount_msat,
427            label=label,
428        )
429        return nodepb.TrampolinePayResponse.FromString(bytes(res))
430
431    def keysend(
432        self,
433        destination: bytes,
434        amount: clnpb.Amount,
435        label: Optional[str] = None,
436        routehints: Optional[clnpb.RoutehintList] = None,
437        extratlvs: Optional[clnpb.TlvStream] = None,
438    ) -> clnpb.KeysendResponse:
439        uri = "/cln.Node/KeySend"
440        res = clnpb.KeysendResponse
441        req = clnpb.KeysendRequest(
442            destination=normalize_node_id(destination, string=False),
443            amount_msat=amount,
444            label=label if label else "",
445            routehints=routehints,
446            extratlvs=extratlvs,
447        ).SerializeToString()
448
449        return res.FromString(bytes(self.inner.call(uri, bytes(req))))
450
451    def stream_log(self):
452        """Stream logs as they get generated on the server side."""
453        stream = self.inner.stream_log(b"")
454        while True:
455            n = stream.next()
456            if n is None:
457                break
458            yield nodepb.LogEntry.FromString(bytes(n))
459
460    def stream_incoming(self):
461        stream = self.inner.stream_incoming(b"")
462        while True:
463            n = stream.next()
464            if n is None:
465                break
466            yield nodepb.IncomingPayment.FromString(bytes(n))
467
468    def stream_custommsg(self):
469        stream = self.inner.stream_custommsg(b"")
470        while True:
471            n = stream.next()
472            if n is None:
473                break
474            yield nodepb.Custommsg.FromString(bytes(n))
475
476    def send_custommsg(self, node_id: str, msg: bytes) -> clnpb.SendcustommsgResponse:
477        uri = "/cln.Node/SendCustomMsg"
478        res = clnpb.SendcustommsgResponse
479        req = clnpb.SendcustommsgRequest(
480            node_id=normalize_node_id(node_id),
481            msg=msg,
482        ).SerializeToString()
483
484        return res.FromString(bytes(self.inner.call(uri, bytes(req))))
485
486    def datastore(self, key, string=None, hex=None, mode=None, generation=None):
487        uri = "/cln.Node/Datastore"
488        req = clnpb.DatastoreRequest(
489            key=key, string=string, hex=hex, mode=mode, generation=generation
490        ).SerializeToString()
491        res = clnpb.DatastoreResponse
492        return res.FromString(bytes(self.inner.call(uri, bytes(req))))
493
494    def del_datastore(self, key, generation=None):
495        uri = "/cln.Node/DelDatastore"
496        req = clnpb.DeldatastoreRequest(
497            key=key, generation=generation
498        ).SerializeToString()
499        res = clnpb.DeldatastoreResponse
500        return res.FromString(bytes(self.inner.call(uri, bytes(req))))
501
502    def list_datastore(self, key=None):
503        uri = "/cln.Node/ListDatastore"
504        req = clnpb.ListdatastoreRequest(key=key).SerializeToString()
505        res = clnpb.ListdatastoreResponse
506        return res.FromString(bytes(self.inner.call(uri, bytes(req))))
507
508    def get_lsp_client(
509        self,
510    ) -> LspClient:
511        native_lsps = self.inner.get_lsp_client()
512        return LspClient(native_lsps)
513
514    def configure(self, close_to_addr: str) -> None:
515        req = nodepb.GlConfig(close_to_addr=close_to_addr).SerializeToString()
516
517        return self.inner.configure(req)
518
519    def wait_blockheight(
520        self,
521        blockheight: int,
522        timeout: Optional[int] = None,
523    ):
524        """Wait until the blockchain has reached the specified blockheight."""
525        uri = "/cln.Node/WaitBlockheight"
526        req = clnpb.WaitblockheightRequest(
527            blockheight=blockheight, timeout=timeout
528        ).SerializeToString()
529        res = clnpb.WaitblockheightResponse
530        return res.FromString(bytes(self.inner.call(uri, bytes(req))))
531
532    def fetch_invoice(
533        self,
534        offer: str,
535        amount_msat: Optional[Amount] = None,
536        quantity: Optional[int] = None,
537        recurrence_counter: Optional[int] = None,
538        recurrence_start: Optional[int] = None,
539        recurrence_label: Optional[str] = None,
540        timeout: Optional[int] = None,
541        payer_note: Optional[str] = None,
542    ) -> clnpb.FetchinvoiceResponse:
543        """Fetch an invoice based on an offer.
544
545        Contact the issuer of an offer to get an actual invoice that
546        can be paid. It highlights any changes between the offer and
547        the returned invoice.
548
549        """
550        uri = "/cln.Node/FetchInvoice"
551        req = clnpb.FetchinvoiceRequest(
552            offer=offer,
553            amount_msat=amount_msat,
554            quantity=quantity,
555            recurrence_counter=recurrence_counter,
556            recurrence_start=recurrence_start,
557            recurrence_label=recurrence_label,
558            timeout=timeout,
559            payer_note=payer_note,
560        ).SerializeToString()
561        res = clnpb.FetchinvoiceResponse
562        return res.FromString(bytes(self.inner.call(uri, bytes(req))))
563
564    def wait(self, subsystem, indexname, nextvalue: int) -> clnpb.WaitResponse:
565        """Wait for the next event in the provided subsystem.
566
567        Returns once the index given by indexname in subsystem reaches
568        or exceeds nextvalue.
569
570        """
571        uri = "/cln.Node/Wait"
572        req = clnpb.WaitRequest(
573            subsystem=subsystem,
574            indexname=indexname,
575            nextvalue=nextvalue,
576        ).SerializeToString()
577        res = clnpb.WaitResponse
578        return res.FromString(bytes(self.inner.call(uri, bytes(req))))
579
580
581def normalize_node_id(node_id, string=False):
582    if len(node_id) == 66:
583        node_id = unhexlify(node_id)
584
585    if len(node_id) != 33:
586        raise ValueError("node_id is not 33 (binary) or 66 (hex) bytes long")
587
588    if isinstance(node_id, str):
589        node_id = node_id.encode("ASCII")
590    return node_id if not string else hexlify(node_id).encode("ASCII")