Struct SchedulerClient 

pub struct SchedulerClient<T> { /* private fields */ }

The scheduler service is the endpoint which allows users to register a new node with greenlight, recover access to an existing node if the owner lost its credentials, schedule the node to be run on greenlight’s infrastructure, and retrieve metadata about the node.

Node

A node is the basic object representing an account on greenlight. Each node corresponds to a c-lightning instance bound to a specific network that can be scheduled on greenlight, and must have a unique node_id.

Nodes are scheduled on-demand onto the infrastructure, but the time to schedule a node is almost instantaneous.

Authentication

Users are authenticated using mTLS authentication. Applications are provisioned with an anonymous keypair that is not bound to a node, allowing access only to the unauthenticated endpoints Scheduler.GetChallenge, Scheduler.Register and Scheduler.Recover. This allows them to register or recover a node, but doesn’t give access to the node itself. Upon registering or recovering an account the user receives a keypair that is bound to the specific node. Once the user receives their personal mTLS keypair they may use it to connect to greenlight, and thus get access to the node-specific functionality. Please refer to the documentation of your grpc library to learn how to configure grpc to use the node-specific mTLS keypair.

Implementations

impl SchedulerClient<Channel>

pub async fn connect<D>(dst: D) -> Result<Self, Error>

where D: TryInto<Endpoint>, D::Error: Into<StdError>,

Attempt to create a new client by connecting to a given endpoint.

impl<T> SchedulerClient<T>

where T: GrpcService<BoxBody>, T::Error: Into<StdError>, T::ResponseBody: Body<Data = Bytes> + Send + 'static, <T::ResponseBody as Body>::Error: Into<StdError> + Send,

pub fn new(inner: T) -> Self

pub fn with_origin(inner: T, origin: Uri) -> Self

pub fn with_interceptor<F>( inner: T, interceptor: F, ) -> SchedulerClient<InterceptedService<T, F>>

where F: Interceptor, T::ResponseBody: Default, T: Service<Request<BoxBody>, Response = Response<<T as GrpcService<BoxBody>>::ResponseBody>>, <T as Service<Request<BoxBody>>>::Error: Into<StdError> + Send + Sync,

pub fn send_compressed(self, encoding: CompressionEncoding) -> Self

Compress requests with the given encoding.

This requires the server to support it otherwise it might respond with an error.

pub fn accept_compressed(self, encoding: CompressionEncoding) -> Self

Enable decompressing responses.

pub fn max_decoding_message_size(self, limit: usize) -> Self

Limits the maximum size of a decoded message.

Default: 4MB

pub fn max_encoding_message_size(self, limit: usize) -> Self

Limits the maximum size of an encoded message.

Default: usize::MAX

pub async fn register( &mut self, request: impl IntoRequest<RegistrationRequest>, ) -> Result<Response<RegistrationResponse>, Status>

A user may register a new node with greenlight by providing some basic metadata and proving that they have access to the corresponding private key (see challenge-response mechanism below). This means that in order to register a new node the user must have access to the corresponding private keys to prove ownership, and prevent users from just registering arbitrary node_ids without actually knowing the corresponding secrets.

Upon successful registration an mTLS certificate and private key are returned. These can be used to authenticate future connections to the scheduler or the node.

Each node may be registered once, any later attempt will result in an error being returned. If the user lost its credentials it can make use of the Recover RPC method to recover the credentials. Notice that this also means that the same node_id cannot be reused for different networks.

pub async fn recover( &mut self, request: impl IntoRequest<RecoveryRequest>, ) -> Result<Response<RecoveryResponse>, Status>

Should a user have lost its credentials (mTLS keypair) for any reason, they may regain access to their node using the Recover RPC method. Similar to the initial registration the caller needs to authenticate the call by proving access to the node’s secret. This also uses the challenge-response mechanism.

Upon success a newly generated mTLS certificate and private key are returned, allowing the user to authenticate going forward. Existing keypairs are not revoked, in order to avoid locking out other authenticated applications.

pub async fn get_challenge( &mut self, request: impl IntoRequest<ChallengeRequest>, ) -> Result<Response<ChallengeResponse>, Status>

Challenges are one-time values issued by the server, used to authenticate a user/device against the server. A user or device can authenticate to the server by signing the challenge and returning the signed message as part of the request that is to be authenticated.

Challenges may not be reused, and are bound to the scope they have been issued for. Attempting to reuse a challenge or use a challenge with a different scope will result in an error being returned.

pub async fn schedule( &mut self, request: impl IntoRequest<ScheduleRequest>, ) -> Result<Response<NodeInfoResponse>, Status>

Scheduling takes a previously registered node, locates a free slot in greenlight’s infrastructure and allocates it to run the node. The node then goes through the startup sequence, synchronizing with the blockchain, and finally binding its grpc interface (see Node service below) to a public IP address and port. Access is authenticated via the mTLS keypair the user received from registering or recovering the node.

Upon success a NodeInfoResponse containing the grpc connection details and some metadata is returned. The application must use the grpc details and its node-specific mTLS keypair to interact with the node directly.

pub async fn get_node_info( &mut self, request: impl IntoRequest<NodeInfoRequest>, ) -> Result<Response<NodeInfoResponse>, Status>

Much like Schedule this call is used to retrieve the metadata and grpc details of a node. Unlike the other call however it is passive, and will not result in the node being scheduled if it isn’t already running. This can be used to check if a node is already scheduled, or to wait for it to be scheduled (e.g., if the caller is an hsmd that signs off on changes, but doesn’t want to keep the node itself scheduled).

pub async fn maybe_upgrade( &mut self, request: impl IntoRequest<UpgradeRequest>, ) -> Result<Response<UpgradeResponse>, Status>

The signer may want to trigger an upgrade of the node before waiting for the node to be scheduled. This ensures that the signer version is in sync with the node version. The scheduler may decide to defer upgrading if the protocols are compatible. Please do not use this directly, rather use the Signer in the client library to trigger this automatically when required. Posting an incomplete or non-functional UpgradeRequest may result in unschedulable nodes.

pub async fn list_invite_codes( &mut self, request: impl IntoRequest<ListInviteCodesRequest>, ) -> Result<Response<ListInviteCodesResponse>, Status>

This call is used to fetch a list of invite codes associated with the node id of the client. These invite codes can be used for further registration of new nodes.

pub async fn export_node( &mut self, request: impl IntoRequest<ExportNodeRequest>, ) -> Result<Response<ExportNodeResponse>, Status>

Exporting a node allows users to take control of their node

This method initiates the node export on Greenlight, allowing users to offboard from GL into their own infrastructure. After calling this method the node will no longer be schedulable on Greenlight, since it is never safe to assume there haven’t been changes in the node’s state (see CLN Backups documentation for details). ExportNode marks the node as Exporting, then generates an encryption secret which is then used to encrypt a database backup. This encrypted database backup is then made accessible through an HTTP server, and a link to it is returned as a response to ExportNode. After the export completes the node is marked as Exported. The encryption key can then be derived using the signer, using ECDH, allowing only users with the node secret to decrypt it.

ExportNode is idempotent and may be called multiple times, without causing the node to be re-exported multiple times, should the call or the download be interrupted. DO NOT import the backup multiple times into your infrastructure, as that can lead to dataloss (old state being replayed) and loss of funds (see CLN Backups documentation for more information)

pub async fn add_outgoing_webhook( &mut self, request: impl IntoRequest<AddOutgoingWebhookRequest>, ) -> Result<Response<AddOutgoingWebhookResponse>, Status>

pub async fn list_outgoing_webhooks( &mut self, request: impl IntoRequest<ListOutgoingWebhooksRequest>, ) -> Result<Response<ListOutgoingWebhooksResponse>, Status>

pub async fn delete_webhooks( &mut self, request: impl IntoRequest<DeleteOutgoingWebhooksRequest>, ) -> Result<Response<Empty>, Status>

pub async fn rotate_outgoing_webhook_secret( &mut self, request: impl IntoRequest<RotateOutgoingWebhookSecretRequest>, ) -> Result<Response<WebhookSecretResponse>, Status>

pub async fn signer_requests_stream( &mut self, request: impl IntoStreamingRequest<Message = SignerResponse>, ) -> Result<Response<Streaming<SignerRequest>>, Status>

Attaches a Signer via a bidirectional stream to the scheduler. This is a communication channel between greenlight and the signing device that is used for requests that are not part of the node api.

The stream is used to hand out the ApprovePairingRequests that the signer answers with a ApprovePairingResponse.

Trait Implementations

impl<T: Clone> Clone for SchedulerClient<T>

fn clone(&self) -> SchedulerClient<T>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Debug> Debug for SchedulerClient<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.