diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 21f3fa92d8..6520dcfd63 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -14,6 +14,7 @@ Steps for reviewers to follow to test the change. - [ ] The change obeys the [Code Documentation and Commenting](https://github.com/lightningnetwork/lnd/blob/master/docs/code_contribution_guidelines.md#CodeDocumentation) guidelines, and lines wrap at 80. - [ ] Commits follow the [Ideal Git Commit Structure](https://github.com/lightningnetwork/lnd/blob/master/docs/code_contribution_guidelines.md#IdealGitCommitStructure). - [ ] Any new logging statements use an appropriate subsystem and logging level. +- [ ] Any new lncli commands have appropriate tags in the comments for the rpc in the proto file. - [ ] [There is a change description in the release notes](https://github.com/lightningnetwork/lnd/tree/master/docs/release-notes), or `[skip ci]` in the commit message for small changes. -📝 Please see our [Contribution Guidelines](https://github.com/lightningnetwork/lnd/blob/master/docs/code_contribution_guidelines.md) for further guidance. \ No newline at end of file +📝 Please see our [Contribution Guidelines](https://github.com/lightningnetwork/lnd/blob/master/docs/code_contribution_guidelines.md) for further guidance. diff --git a/.vscode/settings.json b/.vscode/settings.json index 2e30ce048c..84e81e0325 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -1,4 +1,7 @@ { "editor.tabSize": 8, - "editor.rulers": [80] + "editor.rulers": [ + 80 + ], + "go.buildTags": "autopilotrpc chainrpc dev invoicesrpc neutrinorpc peersrpc signrpc walletrpc watchtowerrpc" } \ No newline at end of file diff --git a/cmd/lncli/commands.go b/cmd/lncli/commands.go index b4d2f318fc..3ef2eec6cf 100644 --- a/cmd/lncli/commands.go +++ b/cmd/lncli/commands.go @@ -2480,7 +2480,7 @@ var verifyChanBackupCommand = cli.Command{ * A packed multi-channel SCB, which couples several individual static channel backups in single blob. - + * A file path which points to a packed single-channel backup within a file, using the same format that lnd does in its channel.backup file. diff --git a/docs/release-notes/release-notes-0.18.0.md b/docs/release-notes/release-notes-0.18.0.md index b146861df8..bbc0e37106 100644 --- a/docs/release-notes/release-notes-0.18.0.md +++ b/docs/release-notes/release-notes-0.18.0.md @@ -101,6 +101,12 @@ considered failed, thus there's no such thing as temp error for a non-MPP. ## lncli Updates + +* [Documented all available lncli commands](https://github.com/lightningnetwork/lnd/pull/8181). + This change makes all existing lncli commands have the appropriate doc tag + in the rpc definition to ensure that the autogenerated API documentation + properly specifies how to use the lncli command. + ## Code Health * [Remove Litecoin code](https://github.com/lightningnetwork/lnd/pull/7867). diff --git a/lnrpc/autopilotrpc/autopilot.proto b/lnrpc/autopilotrpc/autopilot.proto index 67d0f9e381..40e871d4e5 100644 --- a/lnrpc/autopilotrpc/autopilot.proto +++ b/lnrpc/autopilotrpc/autopilot.proto @@ -4,11 +4,29 @@ package autopilotrpc; option go_package = "github.com/lightningnetwork/lnd/lnrpc/autopilotrpc"; +/* + * Comments in this file will be directly parsed into the API + * Documentation as descriptions of the associated method, message, or field. + * These descriptions should go right above the definition of the object, and + * can be in either block or // comment format. + * + * An RPC method can be matched to an lncli command by placing a line in the + * beginning of the description in exactly the following format: + * lncli: `methodname` + * + * Failure to specify the exact name of the command will cause documentation + * generation to fail. + * + * More information on how exactly the gRPC documentation is generated from + * this proto file can be found here: + * https://github.com/lightninglabs/lightning-api + */ + // Autopilot is a service that can be used to get information about the current // state of the daemon's autopilot agent, and also supply it with information // that can be used when deciding where to open channels. service Autopilot { - /* + /* lncli: `autopilot status` Status returns whether the daemon's autopilot agent is active. */ rpc Status (StatusRequest) returns (StatusResponse); @@ -19,7 +37,7 @@ service Autopilot { */ rpc ModifyStatus (ModifyStatusRequest) returns (ModifyStatusResponse); - /* + /* lncli: `autopilot query` QueryScores queries all available autopilot heuristics, in addition to any active combination of these heruristics, for the scores they would give to the given nodes. diff --git a/lnrpc/autopilotrpc/autopilot.swagger.json b/lnrpc/autopilotrpc/autopilot.swagger.json index 5462f9dfcb..ab4e796c45 100644 --- a/lnrpc/autopilotrpc/autopilot.swagger.json +++ b/lnrpc/autopilotrpc/autopilot.swagger.json @@ -51,7 +51,7 @@ }, "/v2/autopilot/scores": { "get": { - "summary": "QueryScores queries all available autopilot heuristics, in addition to any\nactive combination of these heruristics, for the scores they would give to\nthe given nodes.", + "summary": "lncli: `autopilot query`\nQueryScores queries all available autopilot heuristics, in addition to any\nactive combination of these heruristics, for the scores they would give to\nthe given nodes.", "operationId": "Autopilot_QueryScores", "responses": { "200": { @@ -124,7 +124,7 @@ }, "/v2/autopilot/status": { "get": { - "summary": "Status returns whether the daemon's autopilot agent is active.", + "summary": "lncli: `autopilot status`\nStatus returns whether the daemon's autopilot agent is active.", "operationId": "Autopilot_Status", "responses": { "200": { diff --git a/lnrpc/autopilotrpc/autopilot_grpc.pb.go b/lnrpc/autopilotrpc/autopilot_grpc.pb.go index 67694b94f4..f2339f01de 100644 --- a/lnrpc/autopilotrpc/autopilot_grpc.pb.go +++ b/lnrpc/autopilotrpc/autopilot_grpc.pb.go @@ -18,11 +18,13 @@ const _ = grpc.SupportPackageIsVersion7 // // For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream. type AutopilotClient interface { + // lncli: `autopilot status` // Status returns whether the daemon's autopilot agent is active. Status(ctx context.Context, in *StatusRequest, opts ...grpc.CallOption) (*StatusResponse, error) // ModifyStatus is used to modify the status of the autopilot agent, like // enabling or disabling it. ModifyStatus(ctx context.Context, in *ModifyStatusRequest, opts ...grpc.CallOption) (*ModifyStatusResponse, error) + // lncli: `autopilot query` // QueryScores queries all available autopilot heuristics, in addition to any // active combination of these heruristics, for the scores they would give to // the given nodes. @@ -80,11 +82,13 @@ func (c *autopilotClient) SetScores(ctx context.Context, in *SetScoresRequest, o // All implementations must embed UnimplementedAutopilotServer // for forward compatibility type AutopilotServer interface { + // lncli: `autopilot status` // Status returns whether the daemon's autopilot agent is active. Status(context.Context, *StatusRequest) (*StatusResponse, error) // ModifyStatus is used to modify the status of the autopilot agent, like // enabling or disabling it. ModifyStatus(context.Context, *ModifyStatusRequest) (*ModifyStatusResponse, error) + // lncli: `autopilot query` // QueryScores queries all available autopilot heuristics, in addition to any // active combination of these heruristics, for the scores they would give to // the given nodes. diff --git a/lnrpc/devrpc/dev.proto b/lnrpc/devrpc/dev.proto index 50ed70fddb..2a43d74904 100644 --- a/lnrpc/devrpc/dev.proto +++ b/lnrpc/devrpc/dev.proto @@ -6,8 +6,26 @@ package devrpc; option go_package = "github.com/lightningnetwork/lnd/lnrpc/devrpc"; +/* + * Comments in this file will be directly parsed into the API + * Documentation as descriptions of the associated method, message, or field. + * These descriptions should go right above the definition of the object, and + * can be in either block or // comment format. + * + * An RPC method can be matched to an lncli command by placing a line in the + * beginning of the description in exactly the following format: + * lncli: `methodname` + * + * Failure to specify the exact name of the command will cause documentation + * generation to fail. + * + * More information on how exactly the gRPC documentation is generated from + * this proto file can be found here: + * https://github.com/lightninglabs/lightning-api + */ + service Dev { - /* + /* lncli: `importgraph` ImportGraph imports a ChannelGraph into the graph database. Should only be used for development. */ diff --git a/lnrpc/devrpc/dev.swagger.json b/lnrpc/devrpc/dev.swagger.json index df7bb7dda9..effd9d18a3 100644 --- a/lnrpc/devrpc/dev.swagger.json +++ b/lnrpc/devrpc/dev.swagger.json @@ -18,7 +18,7 @@ "paths": { "/v2/dev/importgraph": { "post": { - "summary": "ImportGraph imports a ChannelGraph into the graph database. Should only be\nused for development.", + "summary": "lncli: `importgraph`\nImportGraph imports a ChannelGraph into the graph database. Should only be\nused for development.", "operationId": "Dev_ImportGraph", "responses": { "200": { diff --git a/lnrpc/devrpc/dev_grpc.pb.go b/lnrpc/devrpc/dev_grpc.pb.go index fc6b509d43..1744c12a3b 100644 --- a/lnrpc/devrpc/dev_grpc.pb.go +++ b/lnrpc/devrpc/dev_grpc.pb.go @@ -19,6 +19,7 @@ const _ = grpc.SupportPackageIsVersion7 // // For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream. type DevClient interface { + // lncli: `importgraph` // ImportGraph imports a ChannelGraph into the graph database. Should only be // used for development. ImportGraph(ctx context.Context, in *lnrpc.ChannelGraph, opts ...grpc.CallOption) (*ImportGraphResponse, error) @@ -45,6 +46,7 @@ func (c *devClient) ImportGraph(ctx context.Context, in *lnrpc.ChannelGraph, opt // All implementations must embed UnimplementedDevServer // for forward compatibility type DevServer interface { + // lncli: `importgraph` // ImportGraph imports a ChannelGraph into the graph database. Should only be // used for development. ImportGraph(context.Context, *lnrpc.ChannelGraph) (*ImportGraphResponse, error) diff --git a/lnrpc/invoicesrpc/invoices.proto b/lnrpc/invoicesrpc/invoices.proto index 12317d02c2..db9907a60e 100644 --- a/lnrpc/invoicesrpc/invoices.proto +++ b/lnrpc/invoicesrpc/invoices.proto @@ -6,6 +6,24 @@ package invoicesrpc; option go_package = "github.com/lightningnetwork/lnd/lnrpc/invoicesrpc"; +/* + * Comments in this file will be directly parsed into the API + * Documentation as descriptions of the associated method, message, or field. + * These descriptions should go right above the definition of the object, and + * can be in either block or // comment format. + * + * An RPC method can be matched to an lncli command by placing a line in the + * beginning of the description in exactly the following format: + * lncli: `methodname` + * + * Failure to specify the exact name of the command will cause documentation + * generation to fail. + * + * More information on how exactly the gRPC documentation is generated from + * this proto file can be found here: + * https://github.com/lightninglabs/lightning-api + */ + // Invoices is a service that can be used to create, accept, settle and cancel // invoices. service Invoices { @@ -17,20 +35,20 @@ service Invoices { rpc SubscribeSingleInvoice (SubscribeSingleInvoiceRequest) returns (stream lnrpc.Invoice); - /* + /* lncli: `cancelinvoice` CancelInvoice cancels a currently open invoice. If the invoice is already canceled, this call will succeed. If the invoice is already settled, it will fail. */ rpc CancelInvoice (CancelInvoiceMsg) returns (CancelInvoiceResp); - /* + /* lncli: `addholdinvoice` AddHoldInvoice creates a hold invoice. It ties the invoice to the hash supplied in the request. */ rpc AddHoldInvoice (AddHoldInvoiceRequest) returns (AddHoldInvoiceResp); - /* + /* lncli: `settleinvoice` SettleInvoice settles an accepted invoice. If the invoice is already settled, this call will succeed. */ diff --git a/lnrpc/invoicesrpc/invoices.swagger.json b/lnrpc/invoicesrpc/invoices.swagger.json index 8452e99720..eaf51fd896 100644 --- a/lnrpc/invoicesrpc/invoices.swagger.json +++ b/lnrpc/invoicesrpc/invoices.swagger.json @@ -18,7 +18,7 @@ "paths": { "/v2/invoices/cancel": { "post": { - "summary": "CancelInvoice cancels a currently open invoice. If the invoice is already\ncanceled, this call will succeed. If the invoice is already settled, it will\nfail.", + "summary": "lncli: `cancelinvoice`\nCancelInvoice cancels a currently open invoice. If the invoice is already\ncanceled, this call will succeed. If the invoice is already settled, it will\nfail.", "operationId": "Invoices_CancelInvoice", "responses": { "200": { @@ -51,7 +51,7 @@ }, "/v2/invoices/hodl": { "post": { - "summary": "AddHoldInvoice creates a hold invoice. It ties the invoice to the hash\nsupplied in the request.", + "summary": "lncli: `addholdinvoice`\nAddHoldInvoice creates a hold invoice. It ties the invoice to the hash\nsupplied in the request.", "operationId": "Invoices_AddHoldInvoice", "responses": { "200": { @@ -144,7 +144,7 @@ }, "/v2/invoices/settle": { "post": { - "summary": "SettleInvoice settles an accepted invoice. If the invoice is already\nsettled, this call will succeed.", + "summary": "lncli: `settleinvoice`\nSettleInvoice settles an accepted invoice. If the invoice is already\nsettled, this call will succeed.", "operationId": "Invoices_SettleInvoice", "responses": { "200": { diff --git a/lnrpc/invoicesrpc/invoices_grpc.pb.go b/lnrpc/invoicesrpc/invoices_grpc.pb.go index 9284d4b0b8..bc2f24ac10 100644 --- a/lnrpc/invoicesrpc/invoices_grpc.pb.go +++ b/lnrpc/invoicesrpc/invoices_grpc.pb.go @@ -23,13 +23,16 @@ type InvoicesClient interface { // to notify the client of state transitions of the specified invoice. // Initially the current invoice state is always sent out. SubscribeSingleInvoice(ctx context.Context, in *SubscribeSingleInvoiceRequest, opts ...grpc.CallOption) (Invoices_SubscribeSingleInvoiceClient, error) + // lncli: `cancelinvoice` // CancelInvoice cancels a currently open invoice. If the invoice is already // canceled, this call will succeed. If the invoice is already settled, it will // fail. CancelInvoice(ctx context.Context, in *CancelInvoiceMsg, opts ...grpc.CallOption) (*CancelInvoiceResp, error) + // lncli: `addholdinvoice` // AddHoldInvoice creates a hold invoice. It ties the invoice to the hash // supplied in the request. AddHoldInvoice(ctx context.Context, in *AddHoldInvoiceRequest, opts ...grpc.CallOption) (*AddHoldInvoiceResp, error) + // lncli: `settleinvoice` // SettleInvoice settles an accepted invoice. If the invoice is already // settled, this call will succeed. SettleInvoice(ctx context.Context, in *SettleInvoiceMsg, opts ...grpc.CallOption) (*SettleInvoiceResp, error) @@ -122,13 +125,16 @@ type InvoicesServer interface { // to notify the client of state transitions of the specified invoice. // Initially the current invoice state is always sent out. SubscribeSingleInvoice(*SubscribeSingleInvoiceRequest, Invoices_SubscribeSingleInvoiceServer) error + // lncli: `cancelinvoice` // CancelInvoice cancels a currently open invoice. If the invoice is already // canceled, this call will succeed. If the invoice is already settled, it will // fail. CancelInvoice(context.Context, *CancelInvoiceMsg) (*CancelInvoiceResp, error) + // lncli: `addholdinvoice` // AddHoldInvoice creates a hold invoice. It ties the invoice to the hash // supplied in the request. AddHoldInvoice(context.Context, *AddHoldInvoiceRequest) (*AddHoldInvoiceResp, error) + // lncli: `settleinvoice` // SettleInvoice settles an accepted invoice. If the invoice is already // settled, this call will succeed. SettleInvoice(context.Context, *SettleInvoiceMsg) (*SettleInvoiceResp, error) diff --git a/lnrpc/lightning.proto b/lnrpc/lightning.proto index 8a41a5a2e5..358b421ab1 100644 --- a/lnrpc/lightning.proto +++ b/lnrpc/lightning.proto @@ -341,13 +341,13 @@ service Lightning { */ rpc ListPayments (ListPaymentsRequest) returns (ListPaymentsResponse); - /* + /* lncli: `deletepayments` DeletePayment deletes an outgoing payment from DB. Note that it will not attempt to delete an In-Flight payment, since that would be unsafe. */ rpc DeletePayment (DeletePaymentRequest) returns (DeletePaymentResponse); - /* + /* lncli: `deletepayments --all` DeleteAllPayments deletes all outgoing payments from DB. Note that it will not attempt to delete In-Flight payments, since that would be unsafe. */ @@ -479,7 +479,7 @@ service Lightning { rpc ExportAllChannelBackups (ChanBackupExportRequest) returns (ChanBackupSnapshot); - /* + /* lncli: `verifychanbackup` VerifyChanBackup allows a caller to verify the integrity of a channel backup snapshot. This method will accept either a packed Single or a packed Multi. Specifying both will result in an error. diff --git a/lnrpc/lightning.swagger.json b/lnrpc/lightning.swagger.json index 99bd01e13a..09ac788c45 100644 --- a/lnrpc/lightning.swagger.json +++ b/lnrpc/lightning.swagger.json @@ -383,7 +383,7 @@ }, "/v1/channels/backup/verify": { "post": { - "summary": "VerifyChanBackup allows a caller to verify the integrity of a channel backup\nsnapshot. This method will accept either a packed Single or a packed Multi.\nSpecifying both will result in an error.", + "summary": "lncli: `verifychanbackup`\nVerifyChanBackup allows a caller to verify the integrity of a channel backup\nsnapshot. This method will accept either a packed Single or a packed Multi.\nSpecifying both will result in an error.", "operationId": "Lightning_VerifyChanBackup", "responses": { "200": { @@ -2075,7 +2075,7 @@ }, "/v1/payment": { "delete": { - "summary": "DeletePayment deletes an outgoing payment from DB. Note that it will not\nattempt to delete an In-Flight payment, since that would be unsafe.", + "summary": "lncli: `deletepayments`\nDeletePayment deletes an outgoing payment from DB. Note that it will not\nattempt to delete an In-Flight payment, since that would be unsafe.", "operationId": "Lightning_DeletePayment", "responses": { "200": { @@ -2191,7 +2191,7 @@ ] }, "delete": { - "summary": "DeleteAllPayments deletes all outgoing payments from DB. Note that it will\nnot attempt to delete In-Flight payments, since that would be unsafe.", + "summary": "lncli: `deletepayments --all`\nDeleteAllPayments deletes all outgoing payments from DB. Note that it will\nnot attempt to delete In-Flight payments, since that would be unsafe.", "operationId": "Lightning_DeleteAllPayments", "responses": { "200": { diff --git a/lnrpc/lightning_grpc.pb.go b/lnrpc/lightning_grpc.pb.go index 229cb64c49..78e6c430ee 100644 --- a/lnrpc/lightning_grpc.pb.go +++ b/lnrpc/lightning_grpc.pb.go @@ -241,9 +241,11 @@ type LightningClient interface { // lncli: `listpayments` // ListPayments returns a list of all outgoing payments. ListPayments(ctx context.Context, in *ListPaymentsRequest, opts ...grpc.CallOption) (*ListPaymentsResponse, error) + // lncli: `deletepayments` // DeletePayment deletes an outgoing payment from DB. Note that it will not // attempt to delete an In-Flight payment, since that would be unsafe. DeletePayment(ctx context.Context, in *DeletePaymentRequest, opts ...grpc.CallOption) (*DeletePaymentResponse, error) + // lncli: `deletepayments --all` // DeleteAllPayments deletes all outgoing payments from DB. Note that it will // not attempt to delete In-Flight payments, since that would be unsafe. DeleteAllPayments(ctx context.Context, in *DeleteAllPaymentsRequest, opts ...grpc.CallOption) (*DeleteAllPaymentsResponse, error) @@ -337,6 +339,7 @@ type LightningClient interface { // as well, which contains a single encrypted blob containing the backups of // each channel. ExportAllChannelBackups(ctx context.Context, in *ChanBackupExportRequest, opts ...grpc.CallOption) (*ChanBackupSnapshot, error) + // lncli: `verifychanbackup` // VerifyChanBackup allows a caller to verify the integrity of a channel backup // snapshot. This method will accept either a packed Single or a packed Multi. // Specifying both will result in an error. @@ -1545,9 +1548,11 @@ type LightningServer interface { // lncli: `listpayments` // ListPayments returns a list of all outgoing payments. ListPayments(context.Context, *ListPaymentsRequest) (*ListPaymentsResponse, error) + // lncli: `deletepayments` // DeletePayment deletes an outgoing payment from DB. Note that it will not // attempt to delete an In-Flight payment, since that would be unsafe. DeletePayment(context.Context, *DeletePaymentRequest) (*DeletePaymentResponse, error) + // lncli: `deletepayments --all` // DeleteAllPayments deletes all outgoing payments from DB. Note that it will // not attempt to delete In-Flight payments, since that would be unsafe. DeleteAllPayments(context.Context, *DeleteAllPaymentsRequest) (*DeleteAllPaymentsResponse, error) @@ -1641,6 +1646,7 @@ type LightningServer interface { // as well, which contains a single encrypted blob containing the backups of // each channel. ExportAllChannelBackups(context.Context, *ChanBackupExportRequest) (*ChanBackupSnapshot, error) + // lncli: `verifychanbackup` // VerifyChanBackup allows a caller to verify the integrity of a channel backup // snapshot. This method will accept either a packed Single or a packed Multi. // Specifying both will result in an error. diff --git a/lnrpc/neutrinorpc/neutrino.proto b/lnrpc/neutrinorpc/neutrino.proto index 5a61feaadc..52d3364828 100644 --- a/lnrpc/neutrinorpc/neutrino.proto +++ b/lnrpc/neutrinorpc/neutrino.proto @@ -4,34 +4,52 @@ package neutrinorpc; option go_package = "github.com/lightningnetwork/lnd/lnrpc/neutrinorpc"; +/* + * Comments in this file will be directly parsed into the API + * Documentation as descriptions of the associated method, message, or field. + * These descriptions should go right above the definition of the object, and + * can be in either block or // comment format. + * + * An RPC method can be matched to an lncli command by placing a line in the + * beginning of the description in exactly the following format: + * lncli: `methodname` + * + * Failure to specify the exact name of the command will cause documentation + * generation to fail. + * + * More information on how exactly the gRPC documentation is generated from + * this proto file can be found here: + * https://github.com/lightninglabs/lightning-api + */ + // NeutrinoKit is a service that can be used to get information about the // current state of the neutrino instance, fetch blocks and add/remove peers. service NeutrinoKit { - /* + /* lncli: `neutrino status` Status returns the status of the light client neutrino instance, along with height and hash of the best block, and a list of connected peers. */ rpc Status (StatusRequest) returns (StatusResponse); - /* + /* lncli: `neutrino addpeer` AddPeer adds a new peer that has already been connected to the server. */ rpc AddPeer (AddPeerRequest) returns (AddPeerResponse); - /* + /* lncli: `neutrino disconnectpeer` DisconnectPeer disconnects a peer by target address. Both outbound and inbound nodes will be searched for the target node. An error message will be returned if the peer was not found. */ rpc DisconnectPeer (DisconnectPeerRequest) returns (DisconnectPeerResponse); - /* + /* lncli: `neutrino isbanned` IsBanned returns true if the peer is banned, otherwise false. */ rpc IsBanned (IsBannedRequest) returns (IsBannedResponse); - /* + /* lncli: `neutrino getblockheader` GetBlockHeader returns a block header with a particular block hash. */ rpc GetBlockHeader (GetBlockHeaderRequest) returns (GetBlockHeaderResponse); @@ -41,7 +59,7 @@ service NeutrinoKit { */ rpc GetBlock (GetBlockRequest) returns (GetBlockResponse); - /* + /* lncli: `neutrino getcfilter` GetCFilter returns a compact filter from a block. */ rpc GetCFilter (GetCFilterRequest) returns (GetCFilterResponse); diff --git a/lnrpc/neutrinorpc/neutrino.swagger.json b/lnrpc/neutrinorpc/neutrino.swagger.json index 21a2b7788a..a0f0c01903 100644 --- a/lnrpc/neutrinorpc/neutrino.swagger.json +++ b/lnrpc/neutrinorpc/neutrino.swagger.json @@ -18,7 +18,7 @@ "paths": { "/v2/neutrino/addpeer": { "post": { - "summary": "AddPeer adds a new peer that has already been connected to the server.", + "summary": "lncli: `neutrino addpeer`\nAddPeer adds a new peer that has already been connected to the server.", "operationId": "NeutrinoKit_AddPeer", "responses": { "200": { @@ -116,7 +116,7 @@ }, "/v2/neutrino/blockheader/{hash}": { "get": { - "summary": "GetBlockHeader returns a block header with a particular block hash.", + "summary": "lncli: `neutrino getblockheader`\nGetBlockHeader returns a block header with a particular block hash.", "operationId": "NeutrinoKit_GetBlockHeader", "responses": { "200": { @@ -148,7 +148,7 @@ }, "/v2/neutrino/cfilter/{hash}": { "get": { - "summary": "GetCFilter returns a compact filter from a block.", + "summary": "lncli: `neutrino getcfilter`\nGetCFilter returns a compact filter from a block.", "operationId": "NeutrinoKit_GetCFilter", "responses": { "200": { @@ -180,7 +180,7 @@ }, "/v2/neutrino/disconnect": { "post": { - "summary": "DisconnectPeer disconnects a peer by target address. Both outbound and\ninbound nodes will be searched for the target node. An error message will\nbe returned if the peer was not found.", + "summary": "lncli: `neutrino disconnectpeer`\nDisconnectPeer disconnects a peer by target address. Both outbound and\ninbound nodes will be searched for the target node. An error message will\nbe returned if the peer was not found.", "operationId": "NeutrinoKit_DisconnectPeer", "responses": { "200": { @@ -213,7 +213,7 @@ }, "/v2/neutrino/isbanned": { "get": { - "summary": "IsBanned returns true if the peer is banned, otherwise false.", + "summary": "lncli: `neutrino isbanned`\nIsBanned returns true if the peer is banned, otherwise false.", "operationId": "NeutrinoKit_IsBanned", "responses": { "200": { @@ -245,7 +245,7 @@ }, "/v2/neutrino/status": { "get": { - "summary": "Status returns the status of the light client neutrino instance,\nalong with height and hash of the best block, and a list of connected\npeers.", + "summary": "lncli: `neutrino status`\nStatus returns the status of the light client neutrino instance,\nalong with height and hash of the best block, and a list of connected\npeers.", "operationId": "NeutrinoKit_Status", "responses": { "200": { diff --git a/lnrpc/neutrinorpc/neutrino_grpc.pb.go b/lnrpc/neutrinorpc/neutrino_grpc.pb.go index cb9a2c5e97..567d10316f 100644 --- a/lnrpc/neutrinorpc/neutrino_grpc.pb.go +++ b/lnrpc/neutrinorpc/neutrino_grpc.pb.go @@ -18,22 +18,28 @@ const _ = grpc.SupportPackageIsVersion7 // // For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream. type NeutrinoKitClient interface { + // lncli: `neutrino status` // Status returns the status of the light client neutrino instance, // along with height and hash of the best block, and a list of connected // peers. Status(ctx context.Context, in *StatusRequest, opts ...grpc.CallOption) (*StatusResponse, error) + // lncli: `neutrino addpeer` // AddPeer adds a new peer that has already been connected to the server. AddPeer(ctx context.Context, in *AddPeerRequest, opts ...grpc.CallOption) (*AddPeerResponse, error) + // lncli: `neutrino disconnectpeer` // DisconnectPeer disconnects a peer by target address. Both outbound and // inbound nodes will be searched for the target node. An error message will // be returned if the peer was not found. DisconnectPeer(ctx context.Context, in *DisconnectPeerRequest, opts ...grpc.CallOption) (*DisconnectPeerResponse, error) + // lncli: `neutrino isbanned` // IsBanned returns true if the peer is banned, otherwise false. IsBanned(ctx context.Context, in *IsBannedRequest, opts ...grpc.CallOption) (*IsBannedResponse, error) + // lncli: `neutrino getblockheader` // GetBlockHeader returns a block header with a particular block hash. GetBlockHeader(ctx context.Context, in *GetBlockHeaderRequest, opts ...grpc.CallOption) (*GetBlockHeaderResponse, error) // GetBlock returns a block with a particular block hash. GetBlock(ctx context.Context, in *GetBlockRequest, opts ...grpc.CallOption) (*GetBlockResponse, error) + // lncli: `neutrino getcfilter` // GetCFilter returns a compact filter from a block. GetCFilter(ctx context.Context, in *GetCFilterRequest, opts ...grpc.CallOption) (*GetCFilterResponse, error) // Deprecated: Do not use. @@ -128,22 +134,28 @@ func (c *neutrinoKitClient) GetBlockHash(ctx context.Context, in *GetBlockHashRe // All implementations must embed UnimplementedNeutrinoKitServer // for forward compatibility type NeutrinoKitServer interface { + // lncli: `neutrino status` // Status returns the status of the light client neutrino instance, // along with height and hash of the best block, and a list of connected // peers. Status(context.Context, *StatusRequest) (*StatusResponse, error) + // lncli: `neutrino addpeer` // AddPeer adds a new peer that has already been connected to the server. AddPeer(context.Context, *AddPeerRequest) (*AddPeerResponse, error) + // lncli: `neutrino disconnectpeer` // DisconnectPeer disconnects a peer by target address. Both outbound and // inbound nodes will be searched for the target node. An error message will // be returned if the peer was not found. DisconnectPeer(context.Context, *DisconnectPeerRequest) (*DisconnectPeerResponse, error) + // lncli: `neutrino isbanned` // IsBanned returns true if the peer is banned, otherwise false. IsBanned(context.Context, *IsBannedRequest) (*IsBannedResponse, error) + // lncli: `neutrino getblockheader` // GetBlockHeader returns a block header with a particular block hash. GetBlockHeader(context.Context, *GetBlockHeaderRequest) (*GetBlockHeaderResponse, error) // GetBlock returns a block with a particular block hash. GetBlock(context.Context, *GetBlockRequest) (*GetBlockResponse, error) + // lncli: `neutrino getcfilter` // GetCFilter returns a compact filter from a block. GetCFilter(context.Context, *GetCFilterRequest) (*GetCFilterResponse, error) // Deprecated: Do not use. diff --git a/lnrpc/routerrpc/router.proto b/lnrpc/routerrpc/router.proto index d591cc485c..62b3f3a77a 100644 --- a/lnrpc/routerrpc/router.proto +++ b/lnrpc/routerrpc/router.proto @@ -6,6 +6,24 @@ package routerrpc; option go_package = "github.com/lightningnetwork/lnd/lnrpc/routerrpc"; +/* + * Comments in this file will be directly parsed into the API + * Documentation as descriptions of the associated method, message, or field. + * These descriptions should go right above the definition of the object, and + * can be in either block or // comment format. + * + * An RPC method can be matched to an lncli command by placing a line in the + * beginning of the description in exactly the following format: + * lncli: `methodname` + * + * Failure to specify the exact name of the command will cause documentation + * generation to fail. + * + * More information on how exactly the gRPC documentation is generated from + * this proto file can be found here: + * https://github.com/lightninglabs/lightning-api + */ + // Router is a service that offers advanced interaction with the router // subsystem of the daemon. service Router { @@ -16,7 +34,7 @@ service Router { */ rpc SendPaymentV2 (SendPaymentRequest) returns (stream lnrpc.Payment); - /* + /* lncli: `trackpayment` TrackPaymentV2 returns an update stream for the payment identified by the payment hash. */ @@ -57,21 +75,21 @@ service Router { */ rpc SendToRouteV2 (SendToRouteRequest) returns (lnrpc.HTLCAttempt); - /* + /* lncli: `resetmc` ResetMissionControl clears all mission control state and starts with a clean slate. */ rpc ResetMissionControl (ResetMissionControlRequest) returns (ResetMissionControlResponse); - /* + /* lncli: `querymc` QueryMissionControl exposes the internal mission control state to callers. It is a development feature. */ rpc QueryMissionControl (QueryMissionControlRequest) returns (QueryMissionControlResponse); - /* + /* lncli: `importmc` XImportMissionControl is an experimental API that imports the state provided to the internal mission control's state, using all results which are more recent than our existing values. These values will only be imported @@ -80,20 +98,20 @@ service Router { rpc XImportMissionControl (XImportMissionControlRequest) returns (XImportMissionControlResponse); - /* + /* lncli: `getmccfg` GetMissionControlConfig returns mission control's current config. */ rpc GetMissionControlConfig (GetMissionControlConfigRequest) returns (GetMissionControlConfigResponse); - /* + /* lncli: `setmccfg` SetMissionControlConfig will set mission control's config, if the config provided is valid. */ rpc SetMissionControlConfig (SetMissionControlConfigRequest) returns (SetMissionControlConfigResponse); - /* + /* lncli: `queryprob` Deprecated. QueryProbability returns the current success probability estimate for a given node pair and amount. The call returns a zero success probability if no channel is available or if the amount violates min/max @@ -102,7 +120,7 @@ service Router { rpc QueryProbability (QueryProbabilityRequest) returns (QueryProbabilityResponse); - /* + /* lncli: `buildroute` BuildRoute builds a fully specified route based on a list of hop public keys. It retrieves the relevant channel policies from the graph in order to calculate the correct fees and time locks. @@ -143,7 +161,7 @@ service Router { rpc HtlcInterceptor (stream ForwardHtlcInterceptResponse) returns (stream ForwardHtlcInterceptRequest); - /* + /* lncli: `updatechanstatus` UpdateChanStatus attempts to manually set the state of a channel (enabled, disabled, or auto). A manual "disable" request will cause the channel to stay disabled until a subsequent manual request of either diff --git a/lnrpc/routerrpc/router.swagger.json b/lnrpc/routerrpc/router.swagger.json index ff0cfb1cd5..8c42de8938 100644 --- a/lnrpc/routerrpc/router.swagger.json +++ b/lnrpc/routerrpc/router.swagger.json @@ -93,7 +93,7 @@ }, "/v2/router/mc": { "get": { - "summary": "QueryMissionControl exposes the internal mission control state to callers.\nIt is a development feature.", + "summary": "lncli: `querymc`\nQueryMissionControl exposes the internal mission control state to callers.\nIt is a development feature.", "operationId": "Router_QueryMissionControl", "responses": { "200": { @@ -116,7 +116,7 @@ }, "/v2/router/mc/probability/{from_node}/{to_node}/{amt_msat}": { "get": { - "summary": "Deprecated. QueryProbability returns the current success probability\nestimate for a given node pair and amount. The call returns a zero success\nprobability if no channel is available or if the amount violates min/max\nHTLC constraints.", + "summary": "lncli: `queryprob`\nDeprecated. QueryProbability returns the current success probability\nestimate for a given node pair and amount. The call returns a zero success\nprobability if no channel is available or if the amount violates min/max\nHTLC constraints.", "operationId": "Router_QueryProbability", "responses": { "200": { @@ -165,7 +165,7 @@ }, "/v2/router/mc/reset": { "post": { - "summary": "ResetMissionControl clears all mission control state and starts with a clean\nslate.", + "summary": "lncli: `resetmc`\nResetMissionControl clears all mission control state and starts with a clean\nslate.", "operationId": "Router_ResetMissionControl", "responses": { "200": { @@ -198,7 +198,7 @@ }, "/v2/router/mccfg": { "get": { - "summary": "GetMissionControlConfig returns mission control's current config.", + "summary": "lncli: `getmccfg`\nGetMissionControlConfig returns mission control's current config.", "operationId": "Router_GetMissionControlConfig", "responses": { "200": { @@ -219,7 +219,7 @@ ] }, "post": { - "summary": "SetMissionControlConfig will set mission control's config, if the config\nprovided is valid.", + "summary": "lncli: `setmccfg`\nSetMissionControlConfig will set mission control's config, if the config\nprovided is valid.", "operationId": "Router_SetMissionControlConfig", "responses": { "200": { @@ -293,7 +293,7 @@ }, "/v2/router/route": { "post": { - "summary": "BuildRoute builds a fully specified route based on a list of hop public\nkeys. It retrieves the relevant channel policies from the graph in order to\ncalculate the correct fees and time locks.", + "summary": "lncli: `buildroute`\nBuildRoute builds a fully specified route based on a list of hop public\nkeys. It retrieves the relevant channel policies from the graph in order to\ncalculate the correct fees and time locks.", "operationId": "Router_BuildRoute", "responses": { "200": { @@ -434,7 +434,7 @@ }, "/v2/router/track/{payment_hash}": { "get": { - "summary": "TrackPaymentV2 returns an update stream for the payment identified by the\npayment hash.", + "summary": "lncli: `trackpayment`\nTrackPaymentV2 returns an update stream for the payment identified by the\npayment hash.", "operationId": "Router_TrackPaymentV2", "responses": { "200": { @@ -483,7 +483,7 @@ }, "/v2/router/updatechanstatus": { "post": { - "summary": "UpdateChanStatus attempts to manually set the state of a channel\n(enabled, disabled, or auto). A manual \"disable\" request will cause the\nchannel to stay disabled until a subsequent manual request of either\n\"enable\" or \"auto\".", + "summary": "lncli: `updatechanstatus`\nUpdateChanStatus attempts to manually set the state of a channel\n(enabled, disabled, or auto). A manual \"disable\" request will cause the\nchannel to stay disabled until a subsequent manual request of either\n\"enable\" or \"auto\".", "operationId": "Router_UpdateChanStatus", "responses": { "200": { @@ -516,7 +516,7 @@ }, "/v2/router/x/importhistory": { "post": { - "summary": "XImportMissionControl is an experimental API that imports the state provided\nto the internal mission control's state, using all results which are more\nrecent than our existing values. These values will only be imported\nin-memory, and will not be persisted across restarts.", + "summary": "lncli: `importmc`\nXImportMissionControl is an experimental API that imports the state provided\nto the internal mission control's state, using all results which are more\nrecent than our existing values. These values will only be imported\nin-memory, and will not be persisted across restarts.", "operationId": "Router_XImportMissionControl", "responses": { "200": { diff --git a/lnrpc/routerrpc/router_grpc.pb.go b/lnrpc/routerrpc/router_grpc.pb.go index 3cc753ad74..2e61b5f85a 100644 --- a/lnrpc/routerrpc/router_grpc.pb.go +++ b/lnrpc/routerrpc/router_grpc.pb.go @@ -23,6 +23,7 @@ type RouterClient interface { // PaymentRequest to the final destination. The call returns a stream of // payment updates. SendPaymentV2(ctx context.Context, in *SendPaymentRequest, opts ...grpc.CallOption) (Router_SendPaymentV2Client, error) + // lncli: `trackpayment` // TrackPaymentV2 returns an update stream for the payment identified by the // payment hash. TrackPaymentV2(ctx context.Context, in *TrackPaymentRequest, opts ...grpc.CallOption) (Router_TrackPaymentV2Client, error) @@ -49,27 +50,34 @@ type RouterClient interface { // route manually. This can be used for things like rebalancing, and atomic // swaps. SendToRouteV2(ctx context.Context, in *SendToRouteRequest, opts ...grpc.CallOption) (*lnrpc.HTLCAttempt, error) + // lncli: `resetmc` // ResetMissionControl clears all mission control state and starts with a clean // slate. ResetMissionControl(ctx context.Context, in *ResetMissionControlRequest, opts ...grpc.CallOption) (*ResetMissionControlResponse, error) + // lncli: `querymc` // QueryMissionControl exposes the internal mission control state to callers. // It is a development feature. QueryMissionControl(ctx context.Context, in *QueryMissionControlRequest, opts ...grpc.CallOption) (*QueryMissionControlResponse, error) + // lncli: `importmc` // XImportMissionControl is an experimental API that imports the state provided // to the internal mission control's state, using all results which are more // recent than our existing values. These values will only be imported // in-memory, and will not be persisted across restarts. XImportMissionControl(ctx context.Context, in *XImportMissionControlRequest, opts ...grpc.CallOption) (*XImportMissionControlResponse, error) + // lncli: `getmccfg` // GetMissionControlConfig returns mission control's current config. GetMissionControlConfig(ctx context.Context, in *GetMissionControlConfigRequest, opts ...grpc.CallOption) (*GetMissionControlConfigResponse, error) + // lncli: `setmccfg` // SetMissionControlConfig will set mission control's config, if the config // provided is valid. SetMissionControlConfig(ctx context.Context, in *SetMissionControlConfigRequest, opts ...grpc.CallOption) (*SetMissionControlConfigResponse, error) + // lncli: `queryprob` // Deprecated. QueryProbability returns the current success probability // estimate for a given node pair and amount. The call returns a zero success // probability if no channel is available or if the amount violates min/max // HTLC constraints. QueryProbability(ctx context.Context, in *QueryProbabilityRequest, opts ...grpc.CallOption) (*QueryProbabilityResponse, error) + // lncli: `buildroute` // BuildRoute builds a fully specified route based on a list of hop public // keys. It retrieves the relevant channel policies from the graph in order to // calculate the correct fees and time locks. @@ -95,6 +103,7 @@ type RouterClient interface { // In case of interception, the htlc can be either settled, cancelled or // resumed later by using the ResolveHoldForward endpoint. HtlcInterceptor(ctx context.Context, opts ...grpc.CallOption) (Router_HtlcInterceptorClient, error) + // lncli: `updatechanstatus` // UpdateChanStatus attempts to manually set the state of a channel // (enabled, disabled, or auto). A manual "disable" request will cause the // channel to stay disabled until a subsequent manual request of either @@ -443,6 +452,7 @@ type RouterServer interface { // PaymentRequest to the final destination. The call returns a stream of // payment updates. SendPaymentV2(*SendPaymentRequest, Router_SendPaymentV2Server) error + // lncli: `trackpayment` // TrackPaymentV2 returns an update stream for the payment identified by the // payment hash. TrackPaymentV2(*TrackPaymentRequest, Router_TrackPaymentV2Server) error @@ -469,27 +479,34 @@ type RouterServer interface { // route manually. This can be used for things like rebalancing, and atomic // swaps. SendToRouteV2(context.Context, *SendToRouteRequest) (*lnrpc.HTLCAttempt, error) + // lncli: `resetmc` // ResetMissionControl clears all mission control state and starts with a clean // slate. ResetMissionControl(context.Context, *ResetMissionControlRequest) (*ResetMissionControlResponse, error) + // lncli: `querymc` // QueryMissionControl exposes the internal mission control state to callers. // It is a development feature. QueryMissionControl(context.Context, *QueryMissionControlRequest) (*QueryMissionControlResponse, error) + // lncli: `importmc` // XImportMissionControl is an experimental API that imports the state provided // to the internal mission control's state, using all results which are more // recent than our existing values. These values will only be imported // in-memory, and will not be persisted across restarts. XImportMissionControl(context.Context, *XImportMissionControlRequest) (*XImportMissionControlResponse, error) + // lncli: `getmccfg` // GetMissionControlConfig returns mission control's current config. GetMissionControlConfig(context.Context, *GetMissionControlConfigRequest) (*GetMissionControlConfigResponse, error) + // lncli: `setmccfg` // SetMissionControlConfig will set mission control's config, if the config // provided is valid. SetMissionControlConfig(context.Context, *SetMissionControlConfigRequest) (*SetMissionControlConfigResponse, error) + // lncli: `queryprob` // Deprecated. QueryProbability returns the current success probability // estimate for a given node pair and amount. The call returns a zero success // probability if no channel is available or if the amount violates min/max // HTLC constraints. QueryProbability(context.Context, *QueryProbabilityRequest) (*QueryProbabilityResponse, error) + // lncli: `buildroute` // BuildRoute builds a fully specified route based on a list of hop public // keys. It retrieves the relevant channel policies from the graph in order to // calculate the correct fees and time locks. @@ -515,6 +532,7 @@ type RouterServer interface { // In case of interception, the htlc can be either settled, cancelled or // resumed later by using the ResolveHoldForward endpoint. HtlcInterceptor(Router_HtlcInterceptorServer) error + // lncli: `updatechanstatus` // UpdateChanStatus attempts to manually set the state of a channel // (enabled, disabled, or auto). A manual "disable" request will cause the // channel to stay disabled until a subsequent manual request of either diff --git a/lnrpc/walletrpc/walletkit.proto b/lnrpc/walletrpc/walletkit.proto index 0d3fd95126..9a7025387c 100644 --- a/lnrpc/walletrpc/walletkit.proto +++ b/lnrpc/walletrpc/walletkit.proto @@ -7,6 +7,24 @@ package walletrpc; option go_package = "github.com/lightningnetwork/lnd/lnrpc/walletrpc"; +/* + * Comments in this file will be directly parsed into the API + * Documentation as descriptions of the associated method, message, or field. + * These descriptions should go right above the definition of the object, and + * can be in either block or // comment format. + * + * An RPC method can be matched to an lncli command by placing a line in the + * beginning of the description in exactly the following format: + * lncli: `methodname` + * + * Failure to specify the exact name of the command will cause documentation + * generation to fail. + * + * More information on how exactly the gRPC documentation is generated from + * this proto file can be found here: + * https://github.com/lightninglabs/lightning-api + */ + // WalletKit is a service that gives access to the core functionalities of the // daemon's wallet. service WalletKit { @@ -18,7 +36,7 @@ service WalletKit { */ rpc ListUnspent (ListUnspentRequest) returns (ListUnspentResponse); - /* + /* lncli: `wallet leaseoutput` LeaseOutput locks an output to the given ID, preventing it from being available for any future coin selection attempts. The absolute time of the lock's expiration is returned. The expiration of the lock can be extended by @@ -27,14 +45,14 @@ service WalletKit { */ rpc LeaseOutput (LeaseOutputRequest) returns (LeaseOutputResponse); - /* + /* lncli: `wallet releaseoutput` ReleaseOutput unlocks an output, allowing it to be available for coin selection if it remains unspent. The ID should match the one used to originally lock the output. */ rpc ReleaseOutput (ReleaseOutputRequest) returns (ReleaseOutputResponse); - /* + /* lncli: `wallet listleases` ListLeases lists all currently locked utxos. */ rpc ListLeases (ListLeasesRequest) returns (ListLeasesResponse); @@ -57,14 +75,14 @@ service WalletKit { */ rpc NextAddr (AddrRequest) returns (AddrResponse); - /* + /* lncli: `wallet accounts list` ListAccounts retrieves all accounts belonging to the wallet by default. A name and key scope filter can be provided to filter through all of the wallet accounts and return only those matching. */ rpc ListAccounts (ListAccountsRequest) returns (ListAccountsResponse); - /* + /* lncli: `wallet requiredreserve` RequiredReserve returns the minimum amount of satoshis that should be kept in the wallet in order to fee bump anchor channels if necessary. The value scales with the number of public anchor channels but is capped at a maximum. @@ -72,14 +90,14 @@ service WalletKit { rpc RequiredReserve (RequiredReserveRequest) returns (RequiredReserveResponse); - /* + /* lncli: `wallet addresses list` ListAddresses retrieves all the addresses along with their balance. An account name filter can be provided to filter through all of the wallet accounts and return the addresses of only those matching. */ rpc ListAddresses (ListAddressesRequest) returns (ListAddressesResponse); - /* + /* lncli: `wallet addresses signmessage` SignMessageWithAddr returns the compact signature (base64 encoded) created with the private key of the provided address. This requires the address to be solely based on a public key lock (no scripts). Obviously the internal @@ -96,7 +114,7 @@ service WalletKit { rpc SignMessageWithAddr (SignMessageWithAddrRequest) returns (SignMessageWithAddrResponse); - /* + /* lncli: `wallet addresses verifymessage` VerifyMessageWithAddr returns the validity and the recovered public key of the provided compact signature (base64 encoded). The verification is twofold. First the validity of the signature itself is checked and then @@ -120,7 +138,7 @@ service WalletKit { rpc VerifyMessageWithAddr (VerifyMessageWithAddrRequest) returns (VerifyMessageWithAddrResponse); - /* + /* lncli: `wallet accounts import` ImportAccount imports an account backed by an account extended public key. The master key fingerprint denotes the fingerprint of the root key corresponding to the account public key (also known as the key with @@ -147,7 +165,7 @@ service WalletKit { */ rpc ImportAccount (ImportAccountRequest) returns (ImportAccountResponse); - /* + /* lncli: `wallet accounts import-pubkey` ImportPublicKey imports a public key as watch-only into the wallet. The public key is converted into a simple address of the given type and that address script is watched on chain. For Taproot keys, this will only watch @@ -177,7 +195,7 @@ service WalletKit { rpc ImportTapscript (ImportTapscriptRequest) returns (ImportTapscriptResponse); - /* + /* lncli: `wallet publishtx` PublishTransaction attempts to publish the passed transaction to the network. Once this returns without an error, the wallet will continually attempt to re-broadcast the transaction on start up, until it enters the @@ -199,7 +217,7 @@ service WalletKit { */ rpc EstimateFee (EstimateFeeRequest) returns (EstimateFeeResponse); - /* + /* lncli: `pendingsweeps` PendingSweeps returns lists of on-chain outputs that lnd is currently attempting to sweep within its central batching engine. Outputs with similar fee rates are batched together in order to sweep them within a single @@ -211,7 +229,7 @@ service WalletKit { */ rpc PendingSweeps (PendingSweepsRequest) returns (PendingSweepsResponse); - /* + /* lncli: `wallet bumpfee` BumpFee bumps the fee of an arbitrary input within a transaction. This RPC takes a different approach than bitcoind's bumpfee command. lnd has a central batching engine in which inputs with similar fee rates are batched @@ -240,14 +258,14 @@ service WalletKit { */ rpc BumpFee (BumpFeeRequest) returns (BumpFeeResponse); - /* + /* lncli: `wallet listsweeps` ListSweeps returns a list of the sweep transactions our node has produced. Note that these sweeps may not be confirmed yet, as we record sweeps on broadcast, not confirmation. */ rpc ListSweeps (ListSweepsRequest) returns (ListSweepsResponse); - /* + /* lncli: `wallet labeltx` LabelTransaction adds a label to a transaction. If the transaction already has a label the call will fail unless the overwrite bool is set. This will overwrite the exiting transaction label. Labels must not be empty, and @@ -256,7 +274,7 @@ service WalletKit { rpc LabelTransaction (LabelTransactionRequest) returns (LabelTransactionResponse); - /* + /* lncli: `wallet psbt fund` FundPsbt creates a fully populated PSBT that contains enough inputs to fund the outputs specified in the template. There are two ways of specifying a template: Either by passing in a PSBT with at least one output declared or @@ -293,7 +311,7 @@ service WalletKit { */ rpc SignPsbt (SignPsbtRequest) returns (SignPsbtResponse); - /* + /* lncli: `wallet psbt finalize` FinalizePsbt expects a partial transaction with all inputs and outputs fully declared and tries to sign all inputs that belong to the wallet. Lnd must be the last signer of the transaction. That means, if there are any unsigned diff --git a/lnrpc/walletrpc/walletkit.swagger.json b/lnrpc/walletrpc/walletkit.swagger.json index 5297ec23b1..7165273455 100644 --- a/lnrpc/walletrpc/walletkit.swagger.json +++ b/lnrpc/walletrpc/walletkit.swagger.json @@ -18,7 +18,7 @@ "paths": { "/v2/wallet/accounts": { "get": { - "summary": "ListAccounts retrieves all accounts belonging to the wallet by default. A\nname and key scope filter can be provided to filter through all of the\nwallet accounts and return only those matching.", + "summary": "lncli: `wallet accounts list`\nListAccounts retrieves all accounts belonging to the wallet by default. A\nname and key scope filter can be provided to filter through all of the\nwallet accounts and return only those matching.", "operationId": "WalletKit_ListAccounts", "responses": { "200": { @@ -65,7 +65,7 @@ }, "/v2/wallet/accounts/import": { "post": { - "summary": "ImportAccount imports an account backed by an account extended public key.\nThe master key fingerprint denotes the fingerprint of the root key\ncorresponding to the account public key (also known as the key with\nderivation path m/). This may be required by some hardware wallets for\nproper identification and signing.", + "summary": "lncli: `wallet accounts import`\nImportAccount imports an account backed by an account extended public key.\nThe master key fingerprint denotes the fingerprint of the root key\ncorresponding to the account public key (also known as the key with\nderivation path m/). This may be required by some hardware wallets for\nproper identification and signing.", "description": "The address type can usually be inferred from the key's version, but may be\nrequired for certain keys to map them into the proper scope.\n\nFor BIP-0044 keys, an address type must be specified as we intend to not\nsupport importing BIP-0044 keys into the wallet using the legacy\npay-to-pubkey-hash (P2PKH) scheme. A nested witness address type will force\nthe standard BIP-0049 derivation scheme, while a witness address type will\nforce the standard BIP-0084 derivation scheme.\n\nFor BIP-0049 keys, an address type must also be specified to make a\ndistinction between the standard BIP-0049 address schema (nested witness\npubkeys everywhere) and our own BIP-0049Plus address schema (nested pubkeys\nexternally, witness pubkeys internally).\n\nNOTE: Events (deposits/spends) for keys derived from an account will only be\ndetected by lnd if they happen after the import. Rescans to detect past\nevents will be supported later on.", "operationId": "WalletKit_ImportAccount", "responses": { @@ -132,7 +132,7 @@ }, "/v2/wallet/address/signmessage": { "post": { - "summary": "SignMessageWithAddr returns the compact signature (base64 encoded) created\nwith the private key of the provided address. This requires the address\nto be solely based on a public key lock (no scripts). Obviously the internal\nlnd wallet has to possess the private key of the address otherwise\nan error is returned.", + "summary": "lncli: `wallet addresses signmessage`\nSignMessageWithAddr returns the compact signature (base64 encoded) created\nwith the private key of the provided address. This requires the address\nto be solely based on a public key lock (no scripts). Obviously the internal\nlnd wallet has to possess the private key of the address otherwise\nan error is returned.", "description": "This method aims to provide full compatibility with the bitcoin-core and\nbtcd implementation. Bitcoin-core's algorithm is not specified in a\nBIP and only applicable for legacy addresses. This method enhances the\nsigning for additional address types: P2WKH, NP2WKH, P2TR.\nFor P2TR addresses this represents a special case. ECDSA is used to create\na compact signature which makes the public key of the signature recoverable.", "operationId": "WalletKit_SignMessageWithAddr", "responses": { @@ -166,7 +166,7 @@ }, "/v2/wallet/address/verifymessage": { "post": { - "summary": "VerifyMessageWithAddr returns the validity and the recovered public key of\nthe provided compact signature (base64 encoded). The verification is\ntwofold. First the validity of the signature itself is checked and then\nit is verified that the recovered public key of the signature equals\nthe public key of the provided address. There is no dependence on the\nprivate key of the address therefore also external addresses are allowed\nto verify signatures.\nSupported address types are P2PKH, P2WKH, NP2WKH, P2TR.", + "summary": "lncli: `wallet addresses verifymessage`\nVerifyMessageWithAddr returns the validity and the recovered public key of\nthe provided compact signature (base64 encoded). The verification is\ntwofold. First the validity of the signature itself is checked and then\nit is verified that the recovered public key of the signature equals\nthe public key of the provided address. There is no dependence on the\nprivate key of the address therefore also external addresses are allowed\nto verify signatures.\nSupported address types are P2PKH, P2WKH, NP2WKH, P2TR.", "description": "This method is the counterpart of the related signing method\n(SignMessageWithAddr) and aims to provide full compatibility to\nbitcoin-core's implementation. Although bitcoin-core/btcd only provide\nthis functionality for legacy addresses this function enhances it to\nthe address types: P2PKH, P2WKH, NP2WKH, P2TR.\n\nThe verification for P2TR addresses is a special case and requires the\nECDSA compact signature to compare the reovered public key to the internal\ntaproot key. The compact ECDSA signature format was used because there\nare still no known compact signature schemes for schnorr signatures.", "operationId": "WalletKit_VerifyMessageWithAddr", "responses": { @@ -200,7 +200,7 @@ }, "/v2/wallet/addresses": { "get": { - "summary": "ListAddresses retrieves all the addresses along with their balance. An\naccount name filter can be provided to filter through all of the\nwallet accounts and return the addresses of only those matching.", + "summary": "lncli: `wallet addresses list`\nListAddresses retrieves all the addresses along with their balance. An\naccount name filter can be provided to filter through all of the\nwallet accounts and return the addresses of only those matching.", "operationId": "WalletKit_ListAddresses", "responses": { "200": { @@ -239,7 +239,7 @@ }, "/v2/wallet/bumpfee": { "post": { - "summary": "BumpFee bumps the fee of an arbitrary input within a transaction. This RPC\ntakes a different approach than bitcoind's bumpfee command. lnd has a\ncentral batching engine in which inputs with similar fee rates are batched\ntogether to save on transaction fees. Due to this, we cannot rely on\nbumping the fee on a specific transaction, since transactions can change at\nany point with the addition of new inputs. The list of inputs that\ncurrently exist within lnd's central batching engine can be retrieved\nthrough the PendingSweeps RPC.", + "summary": "lncli: `wallet bumpfee`\nBumpFee bumps the fee of an arbitrary input within a transaction. This RPC\ntakes a different approach than bitcoind's bumpfee command. lnd has a\ncentral batching engine in which inputs with similar fee rates are batched\ntogether to save on transaction fees. Due to this, we cannot rely on\nbumping the fee on a specific transaction, since transactions can change at\nany point with the addition of new inputs. The list of inputs that\ncurrently exist within lnd's central batching engine can be retrieved\nthrough the PendingSweeps RPC.", "description": "When bumping the fee of an input that currently exists within lnd's central\nbatching engine, a higher fee transaction will be created that replaces the\nlower fee transaction through the Replace-By-Fee (RBF) policy. If it\n\nThis RPC also serves useful when wanting to perform a Child-Pays-For-Parent\n(CPFP), where the child transaction pays for its parent's fee. This can be\ndone by specifying an outpoint within the low fee transaction that is under\nthe control of the wallet.\n\nThe fee preference can be expressed either as a specific fee rate or a delta\nof blocks in which the output should be swept on-chain within. If a fee\npreference is not explicitly specified, then an error is returned.\n\nNote that this RPC currently doesn't perform any validation checks on the\nfee preference being provided. For now, the responsibility of ensuring that\nthe new fee preference is sufficient is delegated to the user.", "operationId": "WalletKit_BumpFee", "responses": { @@ -339,7 +339,7 @@ }, "/v2/wallet/key/import": { "post": { - "summary": "ImportPublicKey imports a public key as watch-only into the wallet. The\npublic key is converted into a simple address of the given type and that\naddress script is watched on chain. For Taproot keys, this will only watch\nthe BIP-0086 style output script. Use ImportTapscript for more advanced key\nspend or script spend outputs.", + "summary": "lncli: `wallet accounts import-pubkey`\nImportPublicKey imports a public key as watch-only into the wallet. The\npublic key is converted into a simple address of the given type and that\naddress script is watched on chain. For Taproot keys, this will only watch\nthe BIP-0086 style output script. Use ImportTapscript for more advanced key\nspend or script spend outputs.", "description": "NOTE: Events (deposits/spends) for a key will only be detected by lnd if\nthey happen after the import. Rescans to detect past events will be\nsupported later on.", "operationId": "WalletKit_ImportPublicKey", "responses": { @@ -406,7 +406,7 @@ }, "/v2/wallet/psbt/finalize": { "post": { - "summary": "FinalizePsbt expects a partial transaction with all inputs and outputs fully\ndeclared and tries to sign all inputs that belong to the wallet. Lnd must be\nthe last signer of the transaction. That means, if there are any unsigned\nnon-witness inputs or inputs without UTXO information attached or inputs\nwithout witness data that do not belong to lnd's wallet, this method will\nfail. If no error is returned, the PSBT is ready to be extracted and the\nfinal TX within to be broadcast.", + "summary": "lncli: `wallet psbt finalize`\nFinalizePsbt expects a partial transaction with all inputs and outputs fully\ndeclared and tries to sign all inputs that belong to the wallet. Lnd must be\nthe last signer of the transaction. That means, if there are any unsigned\nnon-witness inputs or inputs without UTXO information attached or inputs\nwithout witness data that do not belong to lnd's wallet, this method will\nfail. If no error is returned, the PSBT is ready to be extracted and the\nfinal TX within to be broadcast.", "description": "NOTE: This method does NOT publish the transaction once finalized. It is the\ncaller's responsibility to either publish the transaction on success or\nunlock/release any locked UTXOs in case of an error in this method.", "operationId": "WalletKit_FinalizePsbt", "responses": { @@ -440,7 +440,7 @@ }, "/v2/wallet/psbt/fund": { "post": { - "summary": "FundPsbt creates a fully populated PSBT that contains enough inputs to fund\nthe outputs specified in the template. There are two ways of specifying a\ntemplate: Either by passing in a PSBT with at least one output declared or\nby passing in a raw TxTemplate message.", + "summary": "lncli: `wallet psbt fund`\nFundPsbt creates a fully populated PSBT that contains enough inputs to fund\nthe outputs specified in the template. There are two ways of specifying a\ntemplate: Either by passing in a PSBT with at least one output declared or\nby passing in a raw TxTemplate message.", "description": "If there are no inputs specified in the template, coin selection is\nperformed automatically. If the template does contain any inputs, it is\nassumed that full coin selection happened externally and no additional\ninputs are added. If the specified inputs aren't enough to fund the outputs\nwith the given fee rate, an error is returned.\n\nAfter either selecting or verifying the inputs, all input UTXOs are locked\nwith an internal app ID.\n\nNOTE: If this method returns without an error, it is the caller's\nresponsibility to either spend the locked UTXOs (by finalizing and then\npublishing the transaction) or to unlock/release the locked UTXOs in case of\nan error on the caller's side.", "operationId": "WalletKit_FundPsbt", "responses": { @@ -508,7 +508,7 @@ }, "/v2/wallet/reserve": { "get": { - "summary": "RequiredReserve returns the minimum amount of satoshis that should be kept\nin the wallet in order to fee bump anchor channels if necessary. The value\nscales with the number of public anchor channels but is capped at a maximum.", + "summary": "lncli: `wallet requiredreserve`\nRequiredReserve returns the minimum amount of satoshis that should be kept\nin the wallet in order to fee bump anchor channels if necessary. The value\nscales with the number of public anchor channels but is capped at a maximum.", "operationId": "WalletKit_RequiredReserve", "responses": { "200": { @@ -574,7 +574,7 @@ }, "/v2/wallet/sweeps": { "get": { - "summary": "ListSweeps returns a list of the sweep transactions our node has produced.\nNote that these sweeps may not be confirmed yet, as we record sweeps on\nbroadcast, not confirmation.", + "summary": "lncli: `wallet listsweeps`\nListSweeps returns a list of the sweep transactions our node has produced.\nNote that these sweeps may not be confirmed yet, as we record sweeps on\nbroadcast, not confirmation.", "operationId": "WalletKit_ListSweeps", "responses": { "200": { @@ -606,7 +606,7 @@ }, "/v2/wallet/sweeps/pending": { "get": { - "summary": "PendingSweeps returns lists of on-chain outputs that lnd is currently\nattempting to sweep within its central batching engine. Outputs with similar\nfee rates are batched together in order to sweep them within a single\ntransaction.", + "summary": "lncli: `pendingsweeps`\nPendingSweeps returns lists of on-chain outputs that lnd is currently\nattempting to sweep within its central batching engine. Outputs with similar\nfee rates are batched together in order to sweep them within a single\ntransaction.", "description": "NOTE: Some of the fields within PendingSweepsRequest are not guaranteed to\nremain supported. This is an advanced API that depends on the internals of\nthe UtxoSweeper, so things may change.", "operationId": "WalletKit_PendingSweeps", "responses": { @@ -664,7 +664,7 @@ }, "/v2/wallet/tx": { "post": { - "summary": "PublishTransaction attempts to publish the passed transaction to the\nnetwork. Once this returns without an error, the wallet will continually\nattempt to re-broadcast the transaction on start up, until it enters the\nchain.", + "summary": "lncli: `wallet publishtx`\nPublishTransaction attempts to publish the passed transaction to the\nnetwork. Once this returns without an error, the wallet will continually\nattempt to re-broadcast the transaction on start up, until it enters the\nchain.", "operationId": "WalletKit_PublishTransaction", "responses": { "200": { @@ -697,7 +697,7 @@ }, "/v2/wallet/tx/label": { "post": { - "summary": "LabelTransaction adds a label to a transaction. If the transaction already\nhas a label the call will fail unless the overwrite bool is set. This will\noverwrite the exiting transaction label. Labels must not be empty, and\ncannot exceed 500 characters.", + "summary": "lncli: `wallet labeltx`\nLabelTransaction adds a label to a transaction. If the transaction already\nhas a label the call will fail unless the overwrite bool is set. This will\noverwrite the exiting transaction label. Labels must not be empty, and\ncannot exceed 500 characters.", "operationId": "WalletKit_LabelTransaction", "responses": { "200": { @@ -763,7 +763,7 @@ }, "/v2/wallet/utxos/lease": { "post": { - "summary": "LeaseOutput locks an output to the given ID, preventing it from being\navailable for any future coin selection attempts. The absolute time of the\nlock's expiration is returned. The expiration of the lock can be extended by\nsuccessive invocations of this RPC. Outputs can be unlocked before their\nexpiration through `ReleaseOutput`.", + "summary": "lncli: `wallet leaseoutput`\nLeaseOutput locks an output to the given ID, preventing it from being\navailable for any future coin selection attempts. The absolute time of the\nlock's expiration is returned. The expiration of the lock can be extended by\nsuccessive invocations of this RPC. Outputs can be unlocked before their\nexpiration through `ReleaseOutput`.", "operationId": "WalletKit_LeaseOutput", "responses": { "200": { @@ -796,7 +796,7 @@ }, "/v2/wallet/utxos/leases": { "post": { - "summary": "ListLeases lists all currently locked utxos.", + "summary": "lncli: `wallet listleases`\nListLeases lists all currently locked utxos.", "operationId": "WalletKit_ListLeases", "responses": { "200": { @@ -819,7 +819,7 @@ }, "/v2/wallet/utxos/release": { "post": { - "summary": "ReleaseOutput unlocks an output, allowing it to be available for coin\nselection if it remains unspent. The ID should match the one used to\noriginally lock the output.", + "summary": "lncli: `wallet releaseoutput`\nReleaseOutput unlocks an output, allowing it to be available for coin\nselection if it remains unspent. The ID should match the one used to\noriginally lock the output.", "operationId": "WalletKit_ReleaseOutput", "responses": { "200": { diff --git a/lnrpc/walletrpc/walletkit_grpc.pb.go b/lnrpc/walletrpc/walletkit_grpc.pb.go index 605ffd7e65..156456d1ad 100644 --- a/lnrpc/walletrpc/walletkit_grpc.pb.go +++ b/lnrpc/walletrpc/walletkit_grpc.pb.go @@ -24,16 +24,19 @@ type WalletKitClient interface { // default, all utxos are listed. To list only the unconfirmed utxos, set // the unconfirmed_only to true. ListUnspent(ctx context.Context, in *ListUnspentRequest, opts ...grpc.CallOption) (*ListUnspentResponse, error) + // lncli: `wallet leaseoutput` // LeaseOutput locks an output to the given ID, preventing it from being // available for any future coin selection attempts. The absolute time of the // lock's expiration is returned. The expiration of the lock can be extended by // successive invocations of this RPC. Outputs can be unlocked before their // expiration through `ReleaseOutput`. LeaseOutput(ctx context.Context, in *LeaseOutputRequest, opts ...grpc.CallOption) (*LeaseOutputResponse, error) + // lncli: `wallet releaseoutput` // ReleaseOutput unlocks an output, allowing it to be available for coin // selection if it remains unspent. The ID should match the one used to // originally lock the output. ReleaseOutput(ctx context.Context, in *ReleaseOutputRequest, opts ...grpc.CallOption) (*ReleaseOutputResponse, error) + // lncli: `wallet listleases` // ListLeases lists all currently locked utxos. ListLeases(ctx context.Context, in *ListLeasesRequest, opts ...grpc.CallOption) (*ListLeasesResponse, error) // DeriveNextKey attempts to derive the *next* key within the key family @@ -45,18 +48,22 @@ type WalletKitClient interface { DeriveKey(ctx context.Context, in *signrpc.KeyLocator, opts ...grpc.CallOption) (*signrpc.KeyDescriptor, error) // NextAddr returns the next unused address within the wallet. NextAddr(ctx context.Context, in *AddrRequest, opts ...grpc.CallOption) (*AddrResponse, error) + // lncli: `wallet accounts list` // ListAccounts retrieves all accounts belonging to the wallet by default. A // name and key scope filter can be provided to filter through all of the // wallet accounts and return only those matching. ListAccounts(ctx context.Context, in *ListAccountsRequest, opts ...grpc.CallOption) (*ListAccountsResponse, error) + // lncli: `wallet requiredreserve` // RequiredReserve returns the minimum amount of satoshis that should be kept // in the wallet in order to fee bump anchor channels if necessary. The value // scales with the number of public anchor channels but is capped at a maximum. RequiredReserve(ctx context.Context, in *RequiredReserveRequest, opts ...grpc.CallOption) (*RequiredReserveResponse, error) + // lncli: `wallet addresses list` // ListAddresses retrieves all the addresses along with their balance. An // account name filter can be provided to filter through all of the // wallet accounts and return the addresses of only those matching. ListAddresses(ctx context.Context, in *ListAddressesRequest, opts ...grpc.CallOption) (*ListAddressesResponse, error) + // lncli: `wallet addresses signmessage` // SignMessageWithAddr returns the compact signature (base64 encoded) created // with the private key of the provided address. This requires the address // to be solely based on a public key lock (no scripts). Obviously the internal @@ -70,6 +77,7 @@ type WalletKitClient interface { // For P2TR addresses this represents a special case. ECDSA is used to create // a compact signature which makes the public key of the signature recoverable. SignMessageWithAddr(ctx context.Context, in *SignMessageWithAddrRequest, opts ...grpc.CallOption) (*SignMessageWithAddrResponse, error) + // lncli: `wallet addresses verifymessage` // VerifyMessageWithAddr returns the validity and the recovered public key of // the provided compact signature (base64 encoded). The verification is // twofold. First the validity of the signature itself is checked and then @@ -90,6 +98,7 @@ type WalletKitClient interface { // taproot key. The compact ECDSA signature format was used because there // are still no known compact signature schemes for schnorr signatures. VerifyMessageWithAddr(ctx context.Context, in *VerifyMessageWithAddrRequest, opts ...grpc.CallOption) (*VerifyMessageWithAddrResponse, error) + // lncli: `wallet accounts import` // ImportAccount imports an account backed by an account extended public key. // The master key fingerprint denotes the fingerprint of the root key // corresponding to the account public key (also known as the key with @@ -114,6 +123,7 @@ type WalletKitClient interface { // detected by lnd if they happen after the import. Rescans to detect past // events will be supported later on. ImportAccount(ctx context.Context, in *ImportAccountRequest, opts ...grpc.CallOption) (*ImportAccountResponse, error) + // lncli: `wallet accounts import-pubkey` // ImportPublicKey imports a public key as watch-only into the wallet. The // public key is converted into a simple address of the given type and that // address script is watched on chain. For Taproot keys, this will only watch @@ -136,6 +146,7 @@ type WalletKitClient interface { // NOTE: Taproot keys imported through this RPC currently _cannot_ be used for // funding PSBTs. Only tracking the balance and UTXOs is currently supported. ImportTapscript(ctx context.Context, in *ImportTapscriptRequest, opts ...grpc.CallOption) (*ImportTapscriptResponse, error) + // lncli: `wallet publishtx` // PublishTransaction attempts to publish the passed transaction to the // network. Once this returns without an error, the wallet will continually // attempt to re-broadcast the transaction on start up, until it enters the @@ -149,6 +160,7 @@ type WalletKitClient interface { // determine the fee (in sat/kw) to attach to a transaction in order to // achieve the confirmation target. EstimateFee(ctx context.Context, in *EstimateFeeRequest, opts ...grpc.CallOption) (*EstimateFeeResponse, error) + // lncli: `pendingsweeps` // PendingSweeps returns lists of on-chain outputs that lnd is currently // attempting to sweep within its central batching engine. Outputs with similar // fee rates are batched together in order to sweep them within a single @@ -158,6 +170,7 @@ type WalletKitClient interface { // remain supported. This is an advanced API that depends on the internals of // the UtxoSweeper, so things may change. PendingSweeps(ctx context.Context, in *PendingSweepsRequest, opts ...grpc.CallOption) (*PendingSweepsResponse, error) + // lncli: `wallet bumpfee` // BumpFee bumps the fee of an arbitrary input within a transaction. This RPC // takes a different approach than bitcoind's bumpfee command. lnd has a // central batching engine in which inputs with similar fee rates are batched @@ -184,15 +197,18 @@ type WalletKitClient interface { // fee preference being provided. For now, the responsibility of ensuring that // the new fee preference is sufficient is delegated to the user. BumpFee(ctx context.Context, in *BumpFeeRequest, opts ...grpc.CallOption) (*BumpFeeResponse, error) + // lncli: `wallet listsweeps` // ListSweeps returns a list of the sweep transactions our node has produced. // Note that these sweeps may not be confirmed yet, as we record sweeps on // broadcast, not confirmation. ListSweeps(ctx context.Context, in *ListSweepsRequest, opts ...grpc.CallOption) (*ListSweepsResponse, error) + // lncli: `wallet labeltx` // LabelTransaction adds a label to a transaction. If the transaction already // has a label the call will fail unless the overwrite bool is set. This will // overwrite the exiting transaction label. Labels must not be empty, and // cannot exceed 500 characters. LabelTransaction(ctx context.Context, in *LabelTransactionRequest, opts ...grpc.CallOption) (*LabelTransactionResponse, error) + // lncli: `wallet psbt fund` // FundPsbt creates a fully populated PSBT that contains enough inputs to fund // the outputs specified in the template. There are two ways of specifying a // template: Either by passing in a PSBT with at least one output declared or @@ -224,6 +240,7 @@ type WalletKitClient interface { // input/output/fee value validation, PSBT finalization). Any input that is // incomplete will be skipped. SignPsbt(ctx context.Context, in *SignPsbtRequest, opts ...grpc.CallOption) (*SignPsbtResponse, error) + // lncli: `wallet psbt finalize` // FinalizePsbt expects a partial transaction with all inputs and outputs fully // declared and tries to sign all inputs that belong to the wallet. Lnd must be // the last signer of the transaction. That means, if there are any unsigned @@ -480,16 +497,19 @@ type WalletKitServer interface { // default, all utxos are listed. To list only the unconfirmed utxos, set // the unconfirmed_only to true. ListUnspent(context.Context, *ListUnspentRequest) (*ListUnspentResponse, error) + // lncli: `wallet leaseoutput` // LeaseOutput locks an output to the given ID, preventing it from being // available for any future coin selection attempts. The absolute time of the // lock's expiration is returned. The expiration of the lock can be extended by // successive invocations of this RPC. Outputs can be unlocked before their // expiration through `ReleaseOutput`. LeaseOutput(context.Context, *LeaseOutputRequest) (*LeaseOutputResponse, error) + // lncli: `wallet releaseoutput` // ReleaseOutput unlocks an output, allowing it to be available for coin // selection if it remains unspent. The ID should match the one used to // originally lock the output. ReleaseOutput(context.Context, *ReleaseOutputRequest) (*ReleaseOutputResponse, error) + // lncli: `wallet listleases` // ListLeases lists all currently locked utxos. ListLeases(context.Context, *ListLeasesRequest) (*ListLeasesResponse, error) // DeriveNextKey attempts to derive the *next* key within the key family @@ -501,18 +521,22 @@ type WalletKitServer interface { DeriveKey(context.Context, *signrpc.KeyLocator) (*signrpc.KeyDescriptor, error) // NextAddr returns the next unused address within the wallet. NextAddr(context.Context, *AddrRequest) (*AddrResponse, error) + // lncli: `wallet accounts list` // ListAccounts retrieves all accounts belonging to the wallet by default. A // name and key scope filter can be provided to filter through all of the // wallet accounts and return only those matching. ListAccounts(context.Context, *ListAccountsRequest) (*ListAccountsResponse, error) + // lncli: `wallet requiredreserve` // RequiredReserve returns the minimum amount of satoshis that should be kept // in the wallet in order to fee bump anchor channels if necessary. The value // scales with the number of public anchor channels but is capped at a maximum. RequiredReserve(context.Context, *RequiredReserveRequest) (*RequiredReserveResponse, error) + // lncli: `wallet addresses list` // ListAddresses retrieves all the addresses along with their balance. An // account name filter can be provided to filter through all of the // wallet accounts and return the addresses of only those matching. ListAddresses(context.Context, *ListAddressesRequest) (*ListAddressesResponse, error) + // lncli: `wallet addresses signmessage` // SignMessageWithAddr returns the compact signature (base64 encoded) created // with the private key of the provided address. This requires the address // to be solely based on a public key lock (no scripts). Obviously the internal @@ -526,6 +550,7 @@ type WalletKitServer interface { // For P2TR addresses this represents a special case. ECDSA is used to create // a compact signature which makes the public key of the signature recoverable. SignMessageWithAddr(context.Context, *SignMessageWithAddrRequest) (*SignMessageWithAddrResponse, error) + // lncli: `wallet addresses verifymessage` // VerifyMessageWithAddr returns the validity and the recovered public key of // the provided compact signature (base64 encoded). The verification is // twofold. First the validity of the signature itself is checked and then @@ -546,6 +571,7 @@ type WalletKitServer interface { // taproot key. The compact ECDSA signature format was used because there // are still no known compact signature schemes for schnorr signatures. VerifyMessageWithAddr(context.Context, *VerifyMessageWithAddrRequest) (*VerifyMessageWithAddrResponse, error) + // lncli: `wallet accounts import` // ImportAccount imports an account backed by an account extended public key. // The master key fingerprint denotes the fingerprint of the root key // corresponding to the account public key (also known as the key with @@ -570,6 +596,7 @@ type WalletKitServer interface { // detected by lnd if they happen after the import. Rescans to detect past // events will be supported later on. ImportAccount(context.Context, *ImportAccountRequest) (*ImportAccountResponse, error) + // lncli: `wallet accounts import-pubkey` // ImportPublicKey imports a public key as watch-only into the wallet. The // public key is converted into a simple address of the given type and that // address script is watched on chain. For Taproot keys, this will only watch @@ -592,6 +619,7 @@ type WalletKitServer interface { // NOTE: Taproot keys imported through this RPC currently _cannot_ be used for // funding PSBTs. Only tracking the balance and UTXOs is currently supported. ImportTapscript(context.Context, *ImportTapscriptRequest) (*ImportTapscriptResponse, error) + // lncli: `wallet publishtx` // PublishTransaction attempts to publish the passed transaction to the // network. Once this returns without an error, the wallet will continually // attempt to re-broadcast the transaction on start up, until it enters the @@ -605,6 +633,7 @@ type WalletKitServer interface { // determine the fee (in sat/kw) to attach to a transaction in order to // achieve the confirmation target. EstimateFee(context.Context, *EstimateFeeRequest) (*EstimateFeeResponse, error) + // lncli: `pendingsweeps` // PendingSweeps returns lists of on-chain outputs that lnd is currently // attempting to sweep within its central batching engine. Outputs with similar // fee rates are batched together in order to sweep them within a single @@ -614,6 +643,7 @@ type WalletKitServer interface { // remain supported. This is an advanced API that depends on the internals of // the UtxoSweeper, so things may change. PendingSweeps(context.Context, *PendingSweepsRequest) (*PendingSweepsResponse, error) + // lncli: `wallet bumpfee` // BumpFee bumps the fee of an arbitrary input within a transaction. This RPC // takes a different approach than bitcoind's bumpfee command. lnd has a // central batching engine in which inputs with similar fee rates are batched @@ -640,15 +670,18 @@ type WalletKitServer interface { // fee preference being provided. For now, the responsibility of ensuring that // the new fee preference is sufficient is delegated to the user. BumpFee(context.Context, *BumpFeeRequest) (*BumpFeeResponse, error) + // lncli: `wallet listsweeps` // ListSweeps returns a list of the sweep transactions our node has produced. // Note that these sweeps may not be confirmed yet, as we record sweeps on // broadcast, not confirmation. ListSweeps(context.Context, *ListSweepsRequest) (*ListSweepsResponse, error) + // lncli: `wallet labeltx` // LabelTransaction adds a label to a transaction. If the transaction already // has a label the call will fail unless the overwrite bool is set. This will // overwrite the exiting transaction label. Labels must not be empty, and // cannot exceed 500 characters. LabelTransaction(context.Context, *LabelTransactionRequest) (*LabelTransactionResponse, error) + // lncli: `wallet psbt fund` // FundPsbt creates a fully populated PSBT that contains enough inputs to fund // the outputs specified in the template. There are two ways of specifying a // template: Either by passing in a PSBT with at least one output declared or @@ -680,6 +713,7 @@ type WalletKitServer interface { // input/output/fee value validation, PSBT finalization). Any input that is // incomplete will be skipped. SignPsbt(context.Context, *SignPsbtRequest) (*SignPsbtResponse, error) + // lncli: `wallet psbt finalize` // FinalizePsbt expects a partial transaction with all inputs and outputs fully // declared and tries to sign all inputs that belong to the wallet. Lnd must be // the last signer of the transaction. That means, if there are any unsigned diff --git a/lnrpc/watchtowerrpc/watchtower.proto b/lnrpc/watchtowerrpc/watchtower.proto index f3be621637..f4308d569d 100644 --- a/lnrpc/watchtowerrpc/watchtower.proto +++ b/lnrpc/watchtowerrpc/watchtower.proto @@ -4,10 +4,28 @@ package watchtowerrpc; option go_package = "github.com/lightningnetwork/lnd/lnrpc/watchtowerrpc"; +/* + * Comments in this file will be directly parsed into the API + * Documentation as descriptions of the associated method, message, or field. + * These descriptions should go right above the definition of the object, and + * can be in either block or // comment format. + * + * An RPC method can be matched to an lncli command by placing a line in the + * beginning of the description in exactly the following format: + * lncli: `methodname` + * + * Failure to specify the exact name of the command will cause documentation + * generation to fail. + * + * More information on how exactly the gRPC documentation is generated from + * this proto file can be found here: + * https://github.com/lightninglabs/lightning-api + */ + // Watchtower is a service that grants access to the watchtower server // functionality of the daemon. service Watchtower { - /* lncli: tower info + /* lncli: `tower info` GetInfo returns general information concerning the companion watchtower including its public key and URIs where the server is currently listening for clients. diff --git a/lnrpc/watchtowerrpc/watchtower.swagger.json b/lnrpc/watchtowerrpc/watchtower.swagger.json index 4c50729f70..702198972d 100644 --- a/lnrpc/watchtowerrpc/watchtower.swagger.json +++ b/lnrpc/watchtowerrpc/watchtower.swagger.json @@ -18,7 +18,7 @@ "paths": { "/v2/watchtower/server": { "get": { - "summary": "lncli: tower info\nGetInfo returns general information concerning the companion watchtower\nincluding its public key and URIs where the server is currently\nlistening for clients.", + "summary": "lncli: `tower info`\nGetInfo returns general information concerning the companion watchtower\nincluding its public key and URIs where the server is currently\nlistening for clients.", "operationId": "Watchtower_GetInfo", "responses": { "200": { diff --git a/lnrpc/watchtowerrpc/watchtower_grpc.pb.go b/lnrpc/watchtowerrpc/watchtower_grpc.pb.go index 0587450477..d948e58b59 100644 --- a/lnrpc/watchtowerrpc/watchtower_grpc.pb.go +++ b/lnrpc/watchtowerrpc/watchtower_grpc.pb.go @@ -18,7 +18,7 @@ const _ = grpc.SupportPackageIsVersion7 // // For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream. type WatchtowerClient interface { - // lncli: tower info + // lncli: `tower info` // GetInfo returns general information concerning the companion watchtower // including its public key and URIs where the server is currently // listening for clients. @@ -46,7 +46,7 @@ func (c *watchtowerClient) GetInfo(ctx context.Context, in *GetInfoRequest, opts // All implementations must embed UnimplementedWatchtowerServer // for forward compatibility type WatchtowerServer interface { - // lncli: tower info + // lncli: `tower info` // GetInfo returns general information concerning the companion watchtower // including its public key and URIs where the server is currently // listening for clients. diff --git a/lnrpc/wtclientrpc/wtclient.proto b/lnrpc/wtclientrpc/wtclient.proto index 413f61afa5..b152279c96 100644 --- a/lnrpc/wtclientrpc/wtclient.proto +++ b/lnrpc/wtclientrpc/wtclient.proto @@ -4,10 +4,28 @@ package wtclientrpc; option go_package = "github.com/lightningnetwork/lnd/lnrpc/wtclientrpc"; +/* + * Comments in this file will be directly parsed into the API + * Documentation as descriptions of the associated method, message, or field. + * These descriptions should go right above the definition of the object, and + * can be in either block or // comment format. + * + * An RPC method can be matched to an lncli command by placing a line in the + * beginning of the description in exactly the following format: + * lncli: `methodname` + * + * Failure to specify the exact name of the command will cause documentation + * generation to fail. + * + * More information on how exactly the gRPC documentation is generated from + * this proto file can be found here: + * https://github.com/lightninglabs/lightning-api + */ + // WatchtowerClient is a service that grants access to the watchtower client // functionality of the daemon. service WatchtowerClient { - /* + /* lncli: `wtclient add` AddTower adds a new watchtower reachable at the given address and considers it for new sessions. If the watchtower already exists, then any new addresses included will be considered when dialing it for @@ -15,7 +33,7 @@ service WatchtowerClient { */ rpc AddTower (AddTowerRequest) returns (AddTowerResponse); - /* + /* lncli: `wtclient remove` RemoveTower removes a watchtower from being considered for future session negotiations and from being used for any subsequent backups until it's added again. If an address is provided, then this RPC only serves as a way of @@ -23,16 +41,24 @@ service WatchtowerClient { */ rpc RemoveTower (RemoveTowerRequest) returns (RemoveTowerResponse); - // ListTowers returns the list of watchtowers registered with the client. + /* lncli: `wtclient towers` + ListTowers returns the list of watchtowers registered with the client. + */ rpc ListTowers (ListTowersRequest) returns (ListTowersResponse); - // GetTowerInfo retrieves information for a registered watchtower. + /* lncli: `wtclient tower` + GetTowerInfo retrieves information for a registered watchtower. + */ rpc GetTowerInfo (GetTowerInfoRequest) returns (Tower); - // Stats returns the in-memory statistics of the client since startup. + /* lncli: `wtclient stats` + Stats returns the in-memory statistics of the client since startup. + */ rpc Stats (StatsRequest) returns (StatsResponse); - // Policy returns the active watchtower client policy configuration. + /* lncli: `wtclient policy` + Policy returns the active watchtower client policy configuration. + */ rpc Policy (PolicyRequest) returns (PolicyResponse); } diff --git a/lnrpc/wtclientrpc/wtclient.swagger.json b/lnrpc/wtclientrpc/wtclient.swagger.json index 47c2c396a1..1d0468dd68 100644 --- a/lnrpc/wtclientrpc/wtclient.swagger.json +++ b/lnrpc/wtclientrpc/wtclient.swagger.json @@ -18,7 +18,7 @@ "paths": { "/v2/watchtower/client": { "get": { - "summary": "ListTowers returns the list of watchtowers registered with the client.", + "summary": "lncli: `wtclient towers`\nListTowers returns the list of watchtowers registered with the client.", "operationId": "WatchtowerClient_ListTowers", "responses": { "200": { @@ -55,7 +55,7 @@ ] }, "post": { - "summary": "AddTower adds a new watchtower reachable at the given address and\nconsiders it for new sessions. If the watchtower already exists, then\nany new addresses included will be considered when dialing it for\nsession negotiations and backups.", + "summary": "lncli: `wtclient add`\nAddTower adds a new watchtower reachable at the given address and\nconsiders it for new sessions. If the watchtower already exists, then\nany new addresses included will be considered when dialing it for\nsession negotiations and backups.", "operationId": "WatchtowerClient_AddTower", "responses": { "200": { @@ -88,7 +88,7 @@ }, "/v2/watchtower/client/info/{pubkey}": { "get": { - "summary": "GetTowerInfo retrieves information for a registered watchtower.", + "summary": "lncli: `wtclient tower`\nGetTowerInfo retrieves information for a registered watchtower.", "operationId": "WatchtowerClient_GetTowerInfo", "responses": { "200": { @@ -135,7 +135,7 @@ }, "/v2/watchtower/client/policy": { "get": { - "summary": "Policy returns the active watchtower client policy configuration.", + "summary": "lncli: `wtclient policy`\nPolicy returns the active watchtower client policy configuration.", "operationId": "WatchtowerClient_Policy", "responses": { "200": { @@ -172,7 +172,7 @@ }, "/v2/watchtower/client/stats": { "get": { - "summary": "Stats returns the in-memory statistics of the client since startup.", + "summary": "lncli: `wtclient stats`\nStats returns the in-memory statistics of the client since startup.", "operationId": "WatchtowerClient_Stats", "responses": { "200": { @@ -195,7 +195,7 @@ }, "/v2/watchtower/client/{pubkey}": { "delete": { - "summary": "RemoveTower removes a watchtower from being considered for future session\nnegotiations and from being used for any subsequent backups until it's added\nagain. If an address is provided, then this RPC only serves as a way of\nremoving the address from the watchtower instead.", + "summary": "lncli: `wtclient remove`\nRemoveTower removes a watchtower from being considered for future session\nnegotiations and from being used for any subsequent backups until it's added\nagain. If an address is provided, then this RPC only serves as a way of\nremoving the address from the watchtower instead.", "operationId": "WatchtowerClient_RemoveTower", "responses": { "200": { diff --git a/lnrpc/wtclientrpc/wtclient_grpc.pb.go b/lnrpc/wtclientrpc/wtclient_grpc.pb.go index 169fc4e53a..cbae01fee4 100644 --- a/lnrpc/wtclientrpc/wtclient_grpc.pb.go +++ b/lnrpc/wtclientrpc/wtclient_grpc.pb.go @@ -18,22 +18,28 @@ const _ = grpc.SupportPackageIsVersion7 // // For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream. type WatchtowerClientClient interface { + // lncli: `wtclient add` // AddTower adds a new watchtower reachable at the given address and // considers it for new sessions. If the watchtower already exists, then // any new addresses included will be considered when dialing it for // session negotiations and backups. AddTower(ctx context.Context, in *AddTowerRequest, opts ...grpc.CallOption) (*AddTowerResponse, error) + // lncli: `wtclient remove` // RemoveTower removes a watchtower from being considered for future session // negotiations and from being used for any subsequent backups until it's added // again. If an address is provided, then this RPC only serves as a way of // removing the address from the watchtower instead. RemoveTower(ctx context.Context, in *RemoveTowerRequest, opts ...grpc.CallOption) (*RemoveTowerResponse, error) + // lncli: `wtclient towers` // ListTowers returns the list of watchtowers registered with the client. ListTowers(ctx context.Context, in *ListTowersRequest, opts ...grpc.CallOption) (*ListTowersResponse, error) + // lncli: `wtclient tower` // GetTowerInfo retrieves information for a registered watchtower. GetTowerInfo(ctx context.Context, in *GetTowerInfoRequest, opts ...grpc.CallOption) (*Tower, error) + // lncli: `wtclient stats` // Stats returns the in-memory statistics of the client since startup. Stats(ctx context.Context, in *StatsRequest, opts ...grpc.CallOption) (*StatsResponse, error) + // lncli: `wtclient policy` // Policy returns the active watchtower client policy configuration. Policy(ctx context.Context, in *PolicyRequest, opts ...grpc.CallOption) (*PolicyResponse, error) } @@ -104,22 +110,28 @@ func (c *watchtowerClientClient) Policy(ctx context.Context, in *PolicyRequest, // All implementations must embed UnimplementedWatchtowerClientServer // for forward compatibility type WatchtowerClientServer interface { + // lncli: `wtclient add` // AddTower adds a new watchtower reachable at the given address and // considers it for new sessions. If the watchtower already exists, then // any new addresses included will be considered when dialing it for // session negotiations and backups. AddTower(context.Context, *AddTowerRequest) (*AddTowerResponse, error) + // lncli: `wtclient remove` // RemoveTower removes a watchtower from being considered for future session // negotiations and from being used for any subsequent backups until it's added // again. If an address is provided, then this RPC only serves as a way of // removing the address from the watchtower instead. RemoveTower(context.Context, *RemoveTowerRequest) (*RemoveTowerResponse, error) + // lncli: `wtclient towers` // ListTowers returns the list of watchtowers registered with the client. ListTowers(context.Context, *ListTowersRequest) (*ListTowersResponse, error) + // lncli: `wtclient tower` // GetTowerInfo retrieves information for a registered watchtower. GetTowerInfo(context.Context, *GetTowerInfoRequest) (*Tower, error) + // lncli: `wtclient stats` // Stats returns the in-memory statistics of the client since startup. Stats(context.Context, *StatsRequest) (*StatsResponse, error) + // lncli: `wtclient policy` // Policy returns the active watchtower client policy configuration. Policy(context.Context, *PolicyRequest) (*PolicyResponse, error) mustEmbedUnimplementedWatchtowerClientServer()