diff --git a/.github/workflows/rust.yml b/.github/workflows/rust.yml index 5bc00bd..994cf33 100644 --- a/.github/workflows/rust.yml +++ b/.github/workflows/rust.yml @@ -1,31 +1,31 @@ -name: Rust - -on: - push: - branches: [ "master" ] - pull_request: - branches: [ "master" ] - -env: - CARGO_TERM_COLOR: always - -jobs: - build: - - runs-on: ubuntu-latest - - steps: - - uses: actions/checkout@v3 - - name: download protoc - run: sudo apt-get install -y protobuf-compiler - - name: Show cargo version - run: cargo --version - - name: Fetch - run: | - cargo fetch --locked - - name: Build - run: | - cargo build --release --frozen - - name: Test - run: | - cargo test --release --frozen --workspace +name: Rust + +on: + push: + branches: [ "master" ] + pull_request: + branches: [ "master" ] + +env: + CARGO_TERM_COLOR: always + +jobs: + build: + + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v3 + - name: download protoc + run: sudo apt-get install -y protobuf-compiler + - name: Show cargo version + run: cargo --version + - name: Fetch + run: | + cargo fetch --locked + - name: Build + run: | + cargo build --release --frozen + - name: Test + run: | + cargo test --release --frozen --workspace diff --git a/Cargo.lock b/Cargo.lock index 41eb05b..4fe9960 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -4,9 +4,9 @@ version = 3 [[package]] name = "addr2line" -version = "0.21.0" +version = "0.22.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "8a30b2e23b9e17a9f90641c7ab1549cd9b44f296d3ccbf309d2863cfe398a0cb" +checksum = "6e4503c46a5c0c7844e948c9a4d6acd9f50cccb4de1c48eb9e291ea17470c678" dependencies = [ "gimli", ] @@ -19,18 +19,18 @@ checksum = "f26201604c87b1e01bd3d98f8d5d9a8fcbb815e8cedb41ffccbeb4bf593a35fe" [[package]] name = "aho-corasick" -version = "1.1.2" +version = "1.1.3" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "b2969dcb958b36655471fc61f7e416fa76033bdd4bfed0678d8fee1e2d07a1f0" +checksum = "8e60d3430d3a69478ad0993f19238d2df97c507009a52b3c10addcd7f6bcb916" dependencies = [ "memchr", ] [[package]] name = "anyhow" -version = "1.0.75" +version = "1.0.86" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "a4668cab20f66d8d020e1fbc0ebe47217433c1b6c8f2040faf858554e394ace6" +checksum = "b3d1d046238990b9cf5bcde22a3fb3584ee5cf65fb2765f454ed428c7a0063da" [[package]] name = "async-stream" @@ -56,35 +56,40 @@ dependencies = [ [[package]] name = "async-trait" -version = "0.1.74" +version = "0.1.81" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "a66537f1bb974b254c98ed142ff995236e81b9d0fe4db0575f46612cb15eb0f9" +checksum = "6e0c28dcc82d7c8ead5cb13beb15405b57b8546e93215673ff8ca0349a028107" dependencies = [ "proc-macro2", "quote", "syn", ] +[[package]] +name = "atomic-waker" +version = "1.1.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1505bd5d3d116872e7271a6d4e16d81d0c8570876c8de68093a09ac269d8aac0" + [[package]] name = "autocfg" -version = "1.1.0" +version = "1.3.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "d468802bab17cbc0cc575e9b053f41e72aa36bfa6b7f55e3529ffa43161b97fa" +checksum = "0c4b4d0bd25bd0b74681c0ad21497610ce1b7c91b1022cd21c80c6fbdd9476b0" [[package]] name = "axum" -version = "0.6.20" +version = "0.7.5" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "3b829e4e32b91e643de6eafe82b1d90675f5874230191a4ffbc1b336dec4d6bf" +checksum = "3a6c9af12842a67734c9a2e355436e5d03b22383ed60cf13cd0c18fbfe3dcbcf" dependencies = [ "async-trait", "axum-core", - "bitflags 1.3.2", "bytes", "futures-util", "http", "http-body", - "hyper", + "http-body-util", "itoa", "matchit", "memchr", @@ -93,34 +98,37 @@ dependencies = [ "pin-project-lite", "rustversion", "serde", - "sync_wrapper", - "tower", + "sync_wrapper 1.0.1", + "tower 0.4.13", "tower-layer", "tower-service", ] [[package]] name = "axum-core" -version = "0.3.4" +version = "0.4.3" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "759fa577a247914fd3f7f76d62972792636412fbfd634cd452f6a385a74d2d2c" +checksum = "a15c63fd72d41492dc4f497196f5da1fb04fb7529e631d73630d1b491e47a2e3" dependencies = [ "async-trait", "bytes", "futures-util", "http", "http-body", + "http-body-util", "mime", + "pin-project-lite", "rustversion", + "sync_wrapper 0.1.2", "tower-layer", "tower-service", ] [[package]] name = "backtrace" -version = "0.3.69" +version = "0.3.73" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "2089b7e3f35b9dd2d0ed921ead4f6d318c27680d4a5bd167b3ee120edb105837" +checksum = "5cc23269a4f8976d0a4d2e7109211a419fe30e8d88d677cd60b6bc79c5732e0a" dependencies = [ "addr2line", "cc", @@ -133,35 +141,35 @@ dependencies = [ [[package]] name = "base64" -version = "0.21.5" +version = "0.22.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "35636a1494ede3b646cc98f74f8e62c773a38a659ebc777a2cf26b9b74171df9" +checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6" [[package]] name = "bitflags" -version = "1.3.2" +version = "2.6.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "bef38d45163c2f1dde094a7dfd33ccf595c92905c8f8f4fdc18d06fb1037718a" +checksum = "b048fb63fd8b5923fc5aa7b340d8e156aec7ec02f0c78fa8a6ddc2613f6f71de" [[package]] -name = "bitflags" -version = "2.4.1" +name = "byteorder" +version = "1.5.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "327762f6e5a765692301e5bb513e0d9fef63be86bbc14528052b1cd3e6f03e07" +checksum = "1fd0f2584146f6f2ef48085050886acf353beff7305ebd1ae69500e27c67f64b" [[package]] name = "bytes" -version = "1.5.0" +version = "1.7.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "a2bd12c1caf447e69cd4528f47f94d203fd2582878ecb9e9465484c4148a8223" +checksum = "8318a53db07bb3f8dca91a600466bdb3f2eaadeedfdbcf02e1accbad9271ba50" [[package]] name = "cc" -version = "1.0.83" +version = "1.1.15" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "f1174fb0b6ec23863f8b971027804a42614e347eafb0a95bf0b12cdae21fc4d0" +checksum = "57b6a275aa2903740dc87da01c62040406b8812552e97129a63ea8850a17c6e6" dependencies = [ - "libc", + "shlex", ] [[package]] @@ -172,9 +180,9 @@ checksum = "baf1de4339761588bc0619e3cbc0120ee582ebb74b53b4efbf79117bd2da40fd" [[package]] name = "either" -version = "1.9.0" +version = "1.13.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "a26ae43d7bcc3b814de94796a5e736d4029efb0ee900c12e2d54c993ad1a1e07" +checksum = "60b1af1c220855b6ceac025d3f6ecdd2b7c4894bfe9cd9bda4fbb4bc7c0d4cf0" [[package]] name = "equivalent" @@ -184,19 +192,19 @@ checksum = "5443807d6dff69373d433ab9ef5378ad8df50ca6298caf15de6e52e24aaf54d5" [[package]] name = "errno" -version = "0.3.5" +version = "0.3.9" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "ac3e13f66a2f95e32a39eaa81f6b95d42878ca0e1db0c7543723dfe12557e860" +checksum = "534c5cf6194dfab3db3242765c03bbe257cf92f22b38f6bc0c58d59108a820ba" dependencies = [ "libc", - "windows-sys", + "windows-sys 0.52.0", ] [[package]] name = "fastrand" -version = "2.0.1" +version = "2.1.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "25cbce373ec4653f1a01a31e8a5e5ec0c622dc27ff9c4e6606eefef5cbbed4a5" +checksum = "e8c02a5121d4ea3eb16a80748c74f5549a5665e4c21333c6098f283870fbdea6" [[package]] name = "fedimint-tonic-lnd" @@ -204,6 +212,7 @@ version = "0.2.0" dependencies = [ "hex", "http-body", + "http-body-util", "hyper", "hyper-rustls", "prost", @@ -213,7 +222,7 @@ dependencies = [ "tokio-stream", "tonic", "tonic-build", - "tower", + "tower 0.5.0", ] [[package]] @@ -230,36 +239,36 @@ checksum = "3f9eec918d3f24069decb9af1554cad7c880e2da24a9afd88aca000531ab82c1" [[package]] name = "futures-channel" -version = "0.3.29" +version = "0.3.30" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "ff4dd66668b557604244583e3e1e1eada8c5c2e96a6d0d6653ede395b78bbacb" +checksum = "eac8f7d7865dcb88bd4373ab671c8cf4508703796caa2b1985a9ca867b3fcb78" dependencies = [ "futures-core", ] [[package]] name = "futures-core" -version = "0.3.29" +version = "0.3.30" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "eb1d22c66e66d9d72e1758f0bd7d4fd0bee04cad842ee34587d68c07e45d088c" +checksum = "dfc6580bb841c5a68e9ef15c77ccc837b40a7504914d52e47b8b0e9bbda25a1d" [[package]] name = "futures-sink" -version = "0.3.29" +version = "0.3.30" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "e36d3378ee38c2a36ad710c5d30c2911d752cb941c00c72dbabfb786a7970817" +checksum = "9fb8e00e87438d937621c1c6269e53f536c14d3fbd6a042bb24879e57d474fb5" [[package]] name = "futures-task" -version = "0.3.29" +version = "0.3.30" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "efd193069b0ddadc69c46389b740bbccdd97203899b48d09c5f7969591d6bae2" +checksum = "38d84fa142264698cdce1a9f9172cf383a0c82de1bddcf3092901442c4097004" [[package]] name = "futures-util" -version = "0.3.29" +version = "0.3.30" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "a19526d624e703a3179b3d322efec918b6246ea0fa51d41124525f00f1cc8104" +checksum = "3d6401deb83407ab3da39eba7e33987a73c3df0c82b4bb5813ee871c19c41d48" dependencies = [ "futures-core", "futures-task", @@ -269,9 +278,9 @@ dependencies = [ [[package]] name = "getrandom" -version = "0.2.10" +version = "0.2.15" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "be4136b2a15dd319360be1c07d9933517ccf0be8f16bf62a3bee4f0d618df427" +checksum = "c4567c8db10ae91089c99af84c68c38da3ec2f087c3f82960bcdbf3656b6f4d7" dependencies = [ "cfg-if", "libc", @@ -280,23 +289,23 @@ dependencies = [ [[package]] name = "gimli" -version = "0.28.0" +version = "0.29.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "6fb8d784f27acf97159b40fc4db5ecd8aa23b9ad5ef69cdd136d3bc80665f0c0" +checksum = "40ecd4077b5ae9fd2e9e169b102c6c330d0605168eb0e8bf79952b256dbefffd" [[package]] name = "h2" -version = "0.3.21" +version = "0.4.6" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "91fc23aa11be92976ef4729127f1a74adf36d8436f7816b185d18df956790833" +checksum = "524e8ac6999421f49a846c2d4411f337e53497d8ec55d67753beffa43c5d9205" dependencies = [ + "atomic-waker", "bytes", "fnv", "futures-core", "futures-sink", - "futures-util", "http", - "indexmap 1.9.3", + "indexmap 2.4.0", "slab", "tokio", "tokio-util", @@ -311,21 +320,21 @@ checksum = "8a9ee70c43aaf417c914396645a0fa852624801b24ebb7ae78fe8272889ac888" [[package]] name = "hashbrown" -version = "0.14.2" +version = "0.14.5" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "f93e7192158dbcda357bdec5fb5788eebf8bbac027f3f33e719d29135ae84156" +checksum = "e5274423e17b7c9fc20b6e7e208532f9b19825d82dfd615708b70edd83df41f1" [[package]] name = "heck" -version = "0.4.1" +version = "0.5.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "95505c38b4572b2d910cecb0281560f54b440a19336cbbcb27bf6ce6adc6f5a8" +checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea" [[package]] name = "hermit-abi" -version = "0.3.3" +version = "0.3.9" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "d77f7ec81a6d05a3abb01ab6eb7590f6083d08449fe5a1c8b1e620283546ccb7" +checksum = "d231dfb89cfffdbc30e7fc41579ed6066ad03abda9e567ccafae602b97ec5024" [[package]] name = "hex" @@ -334,41 +343,44 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "7f24254aa9a54b5c858eaee2f5bccdb46aaf0e486a595ed5fd8f86ba55232a70" [[package]] -name = "home" -version = "0.5.5" +name = "http" +version = "1.1.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "5444c27eef6923071f7ebcc33e3444508466a76f7a2b93da00ed6e19f30c1ddb" +checksum = "21b9ddb458710bc376481b842f5da65cdf31522de232c1ca8146abce2a358258" dependencies = [ - "windows-sys", + "bytes", + "fnv", + "itoa", ] [[package]] -name = "http" -version = "0.2.9" +name = "http-body" +version = "1.0.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "bd6effc99afb63425aff9b05836f029929e345a6148a14b7ecd5ab67af944482" +checksum = "1efedce1fb8e6913f23e0c92de8e62cd5b772a67e7b3946df930a62566c93184" dependencies = [ "bytes", - "fnv", - "itoa", + "http", ] [[package]] -name = "http-body" -version = "0.4.5" +name = "http-body-util" +version = "0.1.2" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "d5f38f16d184e36f2408a55281cd658ecbd3ca05cce6d6510a176eca393e26d1" +checksum = "793429d76616a256bcb62c2a2ec2bed781c8307e797e2598c50010f2bee2544f" dependencies = [ "bytes", + "futures-util", "http", + "http-body", "pin-project-lite", ] [[package]] name = "httparse" -version = "1.8.0" +version = "1.9.4" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "d897f394bad6a705d5f4104762e116a75639e470d80901eed05a860a95cb1904" +checksum = "0fcc0b4a115bf80b728eb8ea024ad5bd707b615bfed49e0665b6e0f86fd082d9" [[package]] name = "httpdate" @@ -378,13 +390,12 @@ checksum = "df3b46402a9d5adb4c86a0cf463f42e19994e3ee891101b1841f30a545cb49a9" [[package]] name = "hyper" -version = "0.14.27" +version = "1.4.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "ffb1cfd654a8219eaef89881fdb3bb3b1cdc5fa75ded05d6933b2b382e395468" +checksum = "50dfd22e0e76d0f662d429a5f80fcaf3855009297eab6a0a9f8543834744ba05" dependencies = [ "bytes", "futures-channel", - "futures-core", "futures-util", "h2", "http", @@ -393,37 +404,59 @@ dependencies = [ "httpdate", "itoa", "pin-project-lite", - "socket2 0.4.10", + "smallvec", "tokio", - "tower-service", - "tracing", "want", ] [[package]] name = "hyper-rustls" -version = "0.24.2" +version = "0.27.2" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "ec3efd23720e2049821a693cbc7e65ea87c72f1c58ff2f9522ff332b1491e590" +checksum = "5ee4be2c948921a1a5320b629c4193916ed787a7f7f293fd3f7f5a6c9de74155" dependencies = [ "futures-util", "http", "hyper", + "hyper-util", "rustls", + "rustls-pki-types", "tokio", "tokio-rustls", + "tower-service", ] [[package]] name = "hyper-timeout" -version = "0.4.1" +version = "0.5.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "bbb958482e8c7be4bc3cf272a766a2b0bf1a6755e7a6ae777f017a31d11b13b1" +checksum = "3203a961e5c83b6f5498933e78b6b263e208c197b63e9c6c53cc82ffd3f63793" dependencies = [ "hyper", + "hyper-util", "pin-project-lite", "tokio", - "tokio-io-timeout", + "tower-service", +] + +[[package]] +name = "hyper-util" +version = "0.1.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cde7055719c54e36e95e8719f95883f22072a48ede39db7fc17a4e1d5281e9b9" +dependencies = [ + "bytes", + "futures-channel", + "futures-util", + "http", + "http-body", + "hyper", + "pin-project-lite", + "socket2", + "tokio", + "tower 0.4.13", + "tower-service", + "tracing", ] [[package]] @@ -438,46 +471,56 @@ dependencies = [ [[package]] name = "indexmap" -version = "2.0.2" +version = "2.4.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "8adf3ddd720272c6ea8bf59463c04e0f93d0bbf7c5439b691bca2987e0270897" +checksum = "93ead53efc7ea8ed3cfb0c79fc8023fbb782a5432b52830b6518941cebe6505c" dependencies = [ "equivalent", - "hashbrown 0.14.2", + "hashbrown 0.14.5", ] [[package]] name = "itertools" -version = "0.11.0" +version = "0.13.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "b1c173a5686ce8bfa551b3563d0c2170bf24ca44da99c7ca4bfdab5418c3fe57" +checksum = "413ee7dfc52ee1a4949ceeb7dbc8a33f2d6c088194d9f922fb8318faf1f01186" dependencies = [ "either", ] [[package]] name = "itoa" -version = "1.0.9" +version = "1.0.11" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "af150ab688ff2122fcef229be89cb50dd66af9e01a4ff320cc137eecc9bacc38" +checksum = "49f1f14873335454500d59611f1cf4a4b0f786f9ac11f4312a78e4cf2566695b" [[package]] name = "libc" -version = "0.2.149" +version = "0.2.158" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "a08173bc88b7955d1b3145aa561539096c421ac8debde8cbc3612ec635fee29b" +checksum = "d8adc4bb1803a324070e64a98ae98f38934d91957a99cfb3a43dcbc01bc56439" [[package]] name = "linux-raw-sys" -version = "0.4.10" +version = "0.4.14" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "da2479e8c062e40bf0066ffa0bc823de0a9368974af99c9f6df941d2c231e03f" +checksum = "78b3ae25bc7c8c38cec158d1f2757ee79e9b3740fbc7ccf0e59e4b08d793fa89" + +[[package]] +name = "lock_api" +version = "0.4.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "07af8b9cdd281b7915f413fa73f29ebd5d55d0d3f0155584dade1ff18cea1b17" +dependencies = [ + "autocfg", + "scopeguard", +] [[package]] name = "log" -version = "0.4.20" +version = "0.4.22" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "b5e6163cb8c49088c2c36f57875e58ccd8c87c7427f7fbd50ea6710b2f3f2e8f" +checksum = "a7a70ba024b9dc04c27ea2f0c0548feb474ec5c54bba33a7f72f873a39d07b24" [[package]] name = "matchit" @@ -487,9 +530,9 @@ checksum = "0e7465ac9959cc2b1404e8e2367b43684a6d13790fe23056cc8c6c5a6b7bcb94" [[package]] name = "memchr" -version = "2.6.4" +version = "2.7.4" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "f665ee40bc4a3c5590afb1e9677db74a508659dfd71e126420da8274909a0167" +checksum = "78ca9ab1a0babb1e7d5695e3530886289c18cf2f87ec19a575a0abdce112e3a3" [[package]] name = "mime" @@ -499,85 +542,99 @@ checksum = "6877bb514081ee2a7ff5ef9de3281f14a4dd4bceac4c09388074a6b5df8a139a" [[package]] name = "miniz_oxide" -version = "0.7.1" +version = "0.7.4" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "e7810e0be55b428ada41041c41f32c9f1a42817901b4ccf45fa3d4b6561e74c7" +checksum = "b8a240ddb74feaf34a79a7add65a741f3167852fba007066dcac1ca548d89c08" dependencies = [ "adler", ] [[package]] name = "mio" -version = "0.8.9" +version = "1.0.2" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "3dce281c5e46beae905d4de1870d8b1509a9142b62eedf18b443b011ca8343d0" +checksum = "80e04d1dcff3aae0704555fe5fee3bcfaf3d1fdf8a7e521d5b9d2b42acb52cec" dependencies = [ + "hermit-abi", "libc", "wasi", - "windows-sys", + "windows-sys 0.52.0", ] [[package]] name = "multimap" -version = "0.8.3" +version = "0.10.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "e5ce46fe64a9d73be07dcbe690a38ce1b293be448fd8ce1e6c1b8062c9f72c6a" +checksum = "defc4c55412d89136f966bbb339008b474350e5e6e78d2714439c386b3137a03" [[package]] -name = "num_cpus" -version = "1.16.0" +name = "object" +version = "0.36.3" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "4161fcb6d602d4d2081af7c3a45852d875a03dd337a6bfdd6e06407b61342a43" +checksum = "27b64972346851a39438c60b341ebc01bba47464ae329e55cf343eb93964efd9" dependencies = [ - "hermit-abi", - "libc", + "memchr", ] [[package]] -name = "object" -version = "0.32.1" +name = "once_cell" +version = "1.19.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3fdb12b2476b595f9358c5161aa467c2438859caa136dec86c26fdd2efe17b92" + +[[package]] +name = "parking_lot" +version = "0.12.3" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "9cf5f9dd3933bd50a9e1f149ec995f39ae2c496d31fd772c1fd45ebc27e902b0" +checksum = "f1bf18183cf54e8d6059647fc3063646a1801cf30896933ec2311622cc4b9a27" dependencies = [ - "memchr", + "lock_api", + "parking_lot_core", ] [[package]] -name = "once_cell" -version = "1.18.0" +name = "parking_lot_core" +version = "0.9.10" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "dd8b5dd2ae5ed71462c540258bedcb51965123ad7e7ccf4b9a8cafaa4a63576d" +checksum = "1e401f977ab385c9e4e3ab30627d6f26d00e2c73eef317493c4ec6d468726cf8" +dependencies = [ + "cfg-if", + "libc", + "redox_syscall", + "smallvec", + "windows-targets", +] [[package]] name = "percent-encoding" -version = "2.3.0" +version = "2.3.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "9b2a4787296e9989611394c33f193f676704af1686e70b8f8033ab5ba9a35a94" +checksum = "e3148f5046208a5d56bcfc03053e3ca6334e51da8dfb19b6cdc8b306fae3283e" [[package]] name = "petgraph" -version = "0.6.4" +version = "0.6.5" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "e1d3afd2628e69da2be385eb6f2fd57c8ac7977ceeff6dc166ff1657b0e386a9" +checksum = "b4c5cc86750666a3ed20bdaf5ca2a0344f9c67674cae0515bec2da16fbaa47db" dependencies = [ "fixedbitset", - "indexmap 2.0.2", + "indexmap 2.4.0", ] [[package]] name = "pin-project" -version = "1.1.3" +version = "1.1.5" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "fda4ed1c6c173e3fc7a83629421152e01d7b1f9b7f65fb301e490e8cfc656422" +checksum = "b6bf43b791c5b9e34c3d182969b4abb522f9343702850a2e57f460d00d09b4b3" dependencies = [ "pin-project-internal", ] [[package]] name = "pin-project-internal" -version = "1.1.3" +version = "1.1.5" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "4359fd9c9171ec6e8c62926d6faaf553a8dc3f64e1507e76da7911b4f6a04405" +checksum = "2f38a4412a78282e09a2cf38d195ea5420d15ba0602cb375210efbc877243965" dependencies = [ "proc-macro2", "quote", @@ -586,9 +643,9 @@ dependencies = [ [[package]] name = "pin-project-lite" -version = "0.2.13" +version = "0.2.14" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "8afb450f006bf6385ca15ef45d71d2288452bc3683ce2e2cacc0d18e4be60b58" +checksum = "bda66fc9667c18cb2758a2ac84d1167245054bcf85d5d1aaa6923f45801bdd02" [[package]] name = "pin-utils" @@ -598,15 +655,18 @@ checksum = "8b870d8c151b6f2fb93e84a13146138f05d02ed11c7e7c54f8826aaaf7c9f184" [[package]] name = "ppv-lite86" -version = "0.2.17" +version = "0.2.20" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "5b40af805b3121feab8a3c29f04d8ad262fa8e0561883e7653e024ae4479e6de" +checksum = "77957b295656769bb8ad2b6a6b09d897d94f05c41b069aede1fcdaa675eaea04" +dependencies = [ + "zerocopy", +] [[package]] name = "prettyplease" -version = "0.2.15" +version = "0.2.22" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "ae005bd773ab59b4725093fd7df83fd7892f7d8eafb48dbd7de6e024e4215f9d" +checksum = "479cf940fbbb3426c32c5d5176f62ad57549a0bb84773423ba8be9d089f5faba" dependencies = [ "proc-macro2", "syn", @@ -614,18 +674,18 @@ dependencies = [ [[package]] name = "proc-macro2" -version = "1.0.69" +version = "1.0.86" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "134c189feb4956b20f6f547d2cf727d4c0fe06722b20a0eec87ed445a97f92da" +checksum = "5e719e8df665df0d1c8fbfd238015744736151d4445ec0836b8e628aae103b77" dependencies = [ "unicode-ident", ] [[package]] name = "prost" -version = "0.12.1" +version = "0.13.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "f4fdd22f3b9c31b53c060df4a0613a1c7f062d4115a2b984dd15b1858f7e340d" +checksum = "e13db3d3fde688c61e2446b4d843bc27a7e8af269a69440c0308021dc92333cc" dependencies = [ "bytes", "prost-derive", @@ -633,9 +693,9 @@ dependencies = [ [[package]] name = "prost-build" -version = "0.12.1" +version = "0.13.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "8bdf592881d821b83d471f8af290226c8d51402259e9bb5be7f9f8bdebbb11ac" +checksum = "5bb182580f71dd070f88d01ce3de9f4da5021db7115d2e1c3605a754153b77c1" dependencies = [ "bytes", "heck", @@ -650,14 +710,13 @@ dependencies = [ "regex", "syn", "tempfile", - "which", ] [[package]] name = "prost-derive" -version = "0.12.1" +version = "0.13.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "265baba7fabd416cf5078179f7d2cbeca4ce7a9041111900675ea7c4cb8a4c32" +checksum = "18bec9b0adc4eba778b33684b7ba3e7137789434769ee3ce3930463ef904cfca" dependencies = [ "anyhow", "itertools", @@ -668,18 +727,18 @@ dependencies = [ [[package]] name = "prost-types" -version = "0.12.1" +version = "0.13.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "e081b29f63d83a4bc75cfc9f3fe424f9156cf92d8a4f0c9407cce9a1b67327cf" +checksum = "cee5168b05f49d4b0ca581206eb14a7b22fafd963efe729ac48eb03266e25cc2" dependencies = [ "prost", ] [[package]] name = "quote" -version = "1.0.33" +version = "1.0.37" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "5267fca4496028628a95160fc423a33e8b2e6af8a5302579e322e4b520293cae" +checksum = "b5b9d34b8991d19d98081b46eacdd8eb58c6f2b201139f7c5f643cc155a633af" dependencies = [ "proc-macro2", ] @@ -716,18 +775,18 @@ dependencies = [ [[package]] name = "redox_syscall" -version = "0.4.1" +version = "0.5.3" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "4722d768eff46b75989dd134e5c353f0d6296e5aaa3132e776cbdb56be7731aa" +checksum = "2a908a6e00f1fdd0dfd9c0eb08ce85126f6d8bbda50017e74bc4a4b7d4a926a4" dependencies = [ - "bitflags 1.3.2", + "bitflags", ] [[package]] name = "regex" -version = "1.10.2" +version = "1.10.6" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "380b951a9c5e80ddfd6136919eef32310721aa4aacd4889a8d39124b026ab343" +checksum = "4219d74c6b67a3654a9fbebc4b419e22126d13d2f3c4a07ee0cb61ff79a79619" dependencies = [ "aho-corasick", "memchr", @@ -737,9 +796,9 @@ dependencies = [ [[package]] name = "regex-automata" -version = "0.4.3" +version = "0.4.7" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "5f804c7828047e88b2d32e2d7fe5a105da8ee3264f01902f796c8e067dc2483f" +checksum = "38caf58cc5ef2fed281f89292ef23f6365465ed9a41b7a7754eb4e26496c92df" dependencies = [ "aho-corasick", "memchr", @@ -748,110 +807,133 @@ dependencies = [ [[package]] name = "regex-syntax" -version = "0.8.2" +version = "0.8.4" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "c08c74e62047bb2de4ff487b251e4a92e24f48745648451635cec7d591162d9f" +checksum = "7a66a03ae7c801facd77a29370b4faec201768915ac14a721ba36f20bc9c209b" [[package]] name = "ring" -version = "0.17.5" +version = "0.17.8" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "fb0205304757e5d899b9c2e448b867ffd03ae7f988002e47cd24954391394d0b" +checksum = "c17fa4cb658e3583423e915b9f3acc01cceaee1860e33d59ebae66adc3a2dc0d" dependencies = [ "cc", + "cfg-if", "getrandom", "libc", "spin", "untrusted", - "windows-sys", + "windows-sys 0.52.0", ] [[package]] name = "rustc-demangle" -version = "0.1.23" +version = "0.1.24" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "d626bb9dae77e28219937af045c257c28bfd3f69333c512553507f5f9798cb76" +checksum = "719b953e2095829ee67db738b3bfa9fa368c94900df327b3f07fe6e794d2fe1f" [[package]] name = "rustix" -version = "0.38.21" +version = "0.38.35" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "2b426b0506e5d50a7d8dafcf2e81471400deb602392c7dd110815afb4eaf02a3" +checksum = "a85d50532239da68e9addb745ba38ff4612a242c1c7ceea689c4bc7c2f43c36f" dependencies = [ - "bitflags 2.4.1", + "bitflags", "errno", "libc", "linux-raw-sys", - "windows-sys", + "windows-sys 0.52.0", ] [[package]] name = "rustls" -version = "0.21.8" +version = "0.23.12" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "446e14c5cda4f3f30fe71863c34ec70f5ac79d6087097ad0bb433e1be5edf04c" +checksum = "c58f8c84392efc0a126acce10fa59ff7b3d2ac06ab451a33f2741989b806b044" dependencies = [ "log", + "once_cell", "ring", + "rustls-pki-types", "rustls-webpki", - "sct", + "subtle", + "zeroize", ] [[package]] name = "rustls-pemfile" -version = "1.0.3" +version = "2.1.3" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "2d3987094b1d07b653b7dfdc3f70ce9a1da9c51ac18c1b06b662e4f9a0e9f4b2" +checksum = "196fe16b00e106300d3e45ecfcb764fa292a535d7326a29a5875c579c7417425" dependencies = [ "base64", + "rustls-pki-types", ] +[[package]] +name = "rustls-pki-types" +version = "1.8.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fc0a2ce646f8655401bb81e7927b812614bd5d91dbc968696be50603510fcaf0" + [[package]] name = "rustls-webpki" -version = "0.101.7" +version = "0.102.7" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "8b6275d1ee7a1cd780b64aca7726599a1dbc893b1e64144529e55c3c2f745765" +checksum = "84678086bd54edf2b415183ed7a94d0efb049f1b646a33e22a36f3794be6ae56" dependencies = [ "ring", + "rustls-pki-types", "untrusted", ] [[package]] name = "rustversion" -version = "1.0.14" +version = "1.0.17" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "7ffc183a10b4478d04cbbbfc96d0873219d962dd5accaff2ffbd4ceb7df837f4" +checksum = "955d28af4278de8121b7ebeb796b6a45735dc01436d898801014aced2773a3d6" [[package]] -name = "sct" -version = "0.7.1" +name = "scopeguard" +version = "1.2.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "da046153aa2352493d6cb7da4b6e5c0c057d8a1d0a9aa8560baffdd945acd414" -dependencies = [ - "ring", - "untrusted", -] +checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49" [[package]] name = "serde" -version = "1.0.190" +version = "1.0.209" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "91d3c334ca1ee894a2c6f6ad698fe8c435b76d504b13d436f0685d648d6d96f7" +checksum = "99fce0ffe7310761ca6bf9faf5115afbc19688edd00171d81b1bb1b116c63e09" dependencies = [ "serde_derive", ] [[package]] name = "serde_derive" -version = "1.0.190" +version = "1.0.209" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "67c5609f394e5c2bd7fc51efda478004ea80ef42fee983d5c67a65e34f32c0e3" +checksum = "a5831b979fd7b5439637af1752d535ff49f4860c0f341d1baeb6faf0f4242170" dependencies = [ "proc-macro2", "quote", "syn", ] +[[package]] +name = "shlex" +version = "1.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64" + +[[package]] +name = "signal-hook-registry" +version = "1.4.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a9e9e0b4211b72e7b8b6e85c807d36c212bdb33ea8587f7569562a84df5465b1" +dependencies = [ + "libc", +] + [[package]] name = "slab" version = "0.4.9" @@ -862,23 +944,19 @@ dependencies = [ ] [[package]] -name = "socket2" -version = "0.4.10" +name = "smallvec" +version = "1.13.2" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "9f7916fc008ca5542385b89a3d3ce689953c143e9304a9bf8beec1de48994c0d" -dependencies = [ - "libc", - "winapi", -] +checksum = "3c5e1a9a646d36c3599cd173a41282daf47c44583ad367b8e6837255952e5c67" [[package]] name = "socket2" -version = "0.5.5" +version = "0.5.7" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "7b5fac59a5cb5dd637972e5fca70daf0523c9067fcdc4842f053dae04a18f8e9" +checksum = "ce305eb0b4296696835b71df73eb912e0f1ffd2556a501fcede6e0c50349191c" dependencies = [ "libc", - "windows-sys", + "windows-sys 0.52.0", ] [[package]] @@ -887,11 +965,17 @@ version = "0.9.8" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "6980e8d7511241f8acf4aebddbb1ff938df5eebe98691418c4468d0b72a96a67" +[[package]] +name = "subtle" +version = "2.6.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "13c2bddecc57b384dee18652358fb23172facb8a2c51ccc10d74c157bdea3292" + [[package]] name = "syn" -version = "2.0.38" +version = "2.0.76" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "e96b79aaa137db8f61e26363a0c9b47d8b4ec75da28b7d1d614c2303e232408b" +checksum = "578e081a14e0cefc3279b0472138c513f37b41a08d5a3cca9b6e4e8ceb6cd525" dependencies = [ "proc-macro2", "quote", @@ -904,51 +988,48 @@ version = "0.1.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "2047c6ded9c721764247e62cd3b03c09ffc529b2ba5b10ec482ae507a4a70160" +[[package]] +name = "sync_wrapper" +version = "1.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a7065abeca94b6a8a577f9bd45aa0867a2238b74e8eb67cf10d492bc39351394" + [[package]] name = "tempfile" -version = "3.8.1" +version = "3.12.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "7ef1adac450ad7f4b3c28589471ade84f25f731a7a0fe30d71dfa9f60fd808e5" +checksum = "04cbcdd0c794ebb0d4cf35e88edd2f7d2c4c3e9a5a6dab322839b321c6a87a64" dependencies = [ "cfg-if", "fastrand", - "redox_syscall", + "once_cell", "rustix", - "windows-sys", + "windows-sys 0.59.0", ] [[package]] name = "tokio" -version = "1.33.0" +version = "1.39.3" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "4f38200e3ef7995e5ef13baec2f432a6da0aa9ac495b2c0e8f3b7eec2c92d653" +checksum = "9babc99b9923bfa4804bd74722ff02c0381021eafa4db9949217e3be8e84fff5" dependencies = [ "backtrace", "bytes", "libc", "mio", - "num_cpus", + "parking_lot", "pin-project-lite", - "socket2 0.5.5", + "signal-hook-registry", + "socket2", "tokio-macros", - "windows-sys", -] - -[[package]] -name = "tokio-io-timeout" -version = "1.2.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "30b74022ada614a1b4834de765f9bb43877f910cc8ce4be40e89042c9223a8bf" -dependencies = [ - "pin-project-lite", - "tokio", + "windows-sys 0.52.0", ] [[package]] name = "tokio-macros" -version = "2.1.0" +version = "2.4.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "630bdcf245f78637c13ec01ffae6187cca34625e8c63150d424b59e55af2675e" +checksum = "693d596312e88961bc67d7f1f97af8a70227d9f90c31bba5806eec004978d752" dependencies = [ "proc-macro2", "quote", @@ -957,19 +1038,20 @@ dependencies = [ [[package]] name = "tokio-rustls" -version = "0.24.1" +version = "0.26.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "c28327cf380ac148141087fbfb9de9d7bd4e84ab5d2c28fbc911d753de8a7081" +checksum = "0c7bc40d0e5a97695bb96e27995cd3a08538541b0a846f65bba7a359f36700d4" dependencies = [ "rustls", + "rustls-pki-types", "tokio", ] [[package]] name = "tokio-stream" -version = "0.1.14" +version = "0.1.15" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "397c988d37662c7dda6d2208364a706264bf3d6138b11d436cbac0ad38832842" +checksum = "267ac89e0bec6e691e5813911606935d77c476ff49024f98abcea3e7b15e37af" dependencies = [ "futures-core", "pin-project-lite", @@ -978,23 +1060,22 @@ dependencies = [ [[package]] name = "tokio-util" -version = "0.7.10" +version = "0.7.11" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "5419f34732d9eb6ee4c3578b7989078579b7f039cbbb9ca2c4da015749371e15" +checksum = "9cf6b47b3771c49ac75ad09a6162f53ad4b8088b76ac60e8ec1455b31a189fe1" dependencies = [ "bytes", "futures-core", "futures-sink", "pin-project-lite", "tokio", - "tracing", ] [[package]] name = "tonic" -version = "0.10.2" +version = "0.12.2" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "d560933a0de61cf715926b9cac824d4c883c2c43142f787595e48280c40a1d0e" +checksum = "c6f6ba989e4b2c58ae83d862d3a3e27690b6e3ae630d0deb59f3697f32aa88ad" dependencies = [ "async-stream", "async-trait", @@ -1004,17 +1085,19 @@ dependencies = [ "h2", "http", "http-body", + "http-body-util", "hyper", "hyper-timeout", + "hyper-util", "percent-encoding", "pin-project", "prost", - "rustls", "rustls-pemfile", + "socket2", "tokio", "tokio-rustls", "tokio-stream", - "tower", + "tower 0.4.13", "tower-layer", "tower-service", "tracing", @@ -1022,9 +1105,9 @@ dependencies = [ [[package]] name = "tonic-build" -version = "0.10.2" +version = "0.12.2" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "9d021fc044c18582b9a2408cd0dd05b1596e3ecdb5c4df822bb0183545683889" +checksum = "fe4ee8877250136bd7e3d2331632810a4df4ea5e004656990d8d66d2f5ee8a67" dependencies = [ "prettyplease", "proc-macro2", @@ -1053,17 +1136,27 @@ dependencies = [ "tracing", ] +[[package]] +name = "tower" +version = "0.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "36b837f86b25d7c0d7988f00a54e74739be6477f2aac6201b8f429a7569991b7" +dependencies = [ + "tower-layer", + "tower-service", +] + [[package]] name = "tower-layer" -version = "0.3.2" +version = "0.3.3" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "c20c8dbed6283a09604c3e69b4b7eeb54e298b8a600d4d5ecb5ad39de609f1d0" +checksum = "121c2a6cda46980bb0fcd1647ffaf6cd3fc79a013de288782836f6df9c48780e" [[package]] name = "tower-service" -version = "0.3.2" +version = "0.3.3" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "b6bc1c9ce2b5135ac7f93c72918fc37feb872bdc6a5533a8b85eb4b86bfdae52" +checksum = "8df9b6e13f2d32c91b9bd719c00d1958837bc7dec474d94952798cc8e69eeec3" [[package]] name = "tracing" @@ -1071,7 +1164,6 @@ version = "0.1.40" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "c3523ab5a71916ccf420eebdf5521fcef02141234bbc0b8a49f2fdc4544364ef" dependencies = [ - "log", "pin-project-lite", "tracing-attributes", "tracing-core", @@ -1099,9 +1191,9 @@ dependencies = [ [[package]] name = "try-lock" -version = "0.2.4" +version = "0.2.5" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "3528ecfd12c466c6f163363caf2d02a71161dd5e1cc6ae7b34207ea2d42d81ed" +checksum = "e421abadd41a4225275504ea4d6566923418b7f05506fbc9c0fe86ba7396114b" [[package]] name = "unicode-ident" @@ -1131,57 +1223,33 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "9c8d87e72b64a3b4db28d11ce29237c246188f4f51057d65a7eab63b7987e423" [[package]] -name = "which" -version = "4.4.2" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "87ba24419a2078cd2b0f2ede2691b6c66d8e47836da3b6db8265ebad47afbfc7" -dependencies = [ - "either", - "home", - "once_cell", - "rustix", -] - -[[package]] -name = "winapi" -version = "0.3.9" +name = "windows-sys" +version = "0.52.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "5c839a674fcd7a98952e593242ea400abe93992746761e38641405d28b00f419" +checksum = "282be5f36a8ce781fad8c8ae18fa3f9beff57ec1b52cb3de0789201425d9a33d" dependencies = [ - "winapi-i686-pc-windows-gnu", - "winapi-x86_64-pc-windows-gnu", + "windows-targets", ] -[[package]] -name = "winapi-i686-pc-windows-gnu" -version = "0.4.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "ac3b87c63620426dd9b991e5ce0329eff545bccbbb34f3be09ff6fb6ab51b7b6" - -[[package]] -name = "winapi-x86_64-pc-windows-gnu" -version = "0.4.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f" - [[package]] name = "windows-sys" -version = "0.48.0" +version = "0.59.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "677d2418bec65e3338edb076e806bc1ec15693c5d0104683f2efe857f61056a9" +checksum = "1e38bc4d79ed67fd075bcc251a1c39b32a1776bbe92e5bef1f0bf1f8c531853b" dependencies = [ "windows-targets", ] [[package]] name = "windows-targets" -version = "0.48.5" +version = "0.52.6" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "9a2fa6e2155d7247be68c096456083145c183cbbbc2764150dda45a87197940c" +checksum = "9b724f72796e036ab90c1021d4780d4d3d648aca59e491e6b98e725b84e99973" dependencies = [ "windows_aarch64_gnullvm", "windows_aarch64_msvc", "windows_i686_gnu", + "windows_i686_gnullvm", "windows_i686_msvc", "windows_x86_64_gnu", "windows_x86_64_gnullvm", @@ -1190,42 +1258,75 @@ dependencies = [ [[package]] name = "windows_aarch64_gnullvm" -version = "0.48.5" +version = "0.52.6" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "2b38e32f0abccf9987a4e3079dfb67dcd799fb61361e53e2882c3cbaf0d905d8" +checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3" [[package]] name = "windows_aarch64_msvc" -version = "0.48.5" +version = "0.52.6" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "dc35310971f3b2dbbf3f0690a219f40e2d9afcf64f9ab7cc1be722937c26b4bc" +checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469" [[package]] name = "windows_i686_gnu" -version = "0.48.5" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b" + +[[package]] +name = "windows_i686_gnullvm" +version = "0.52.6" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "a75915e7def60c94dcef72200b9a8e58e5091744960da64ec734a6c6e9b3743e" +checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66" [[package]] name = "windows_i686_msvc" -version = "0.48.5" +version = "0.52.6" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "8f55c233f70c4b27f66c523580f78f1004e8b5a8b659e05a4eb49d4166cca406" +checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66" [[package]] name = "windows_x86_64_gnu" -version = "0.48.5" +version = "0.52.6" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "53d40abd2583d23e4718fddf1ebec84dbff8381c07cae67ff7768bbf19c6718e" +checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78" [[package]] name = "windows_x86_64_gnullvm" -version = "0.48.5" +version = "0.52.6" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "0b7b52767868a23d5bab768e390dc5f5c55825b6d30b86c844ff2dc7414044cc" +checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d" [[package]] name = "windows_x86_64_msvc" -version = "0.48.5" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec" + +[[package]] +name = "zerocopy" +version = "0.7.35" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1b9b4fd18abc82b8136838da5d50bae7bdea537c574d8dc1a34ed098d6c166f0" +dependencies = [ + "byteorder", + "zerocopy-derive", +] + +[[package]] +name = "zerocopy-derive" +version = "0.7.35" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fa4f8080344d4671fb4e831a13ad1e68092748387dfc4f55e356242fae12ce3e" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "zeroize" +version = "1.8.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "ed94fce61571a4006852b7389a063ab983c02eb1bb37b47f8272ce92d06d9538" +checksum = "ced3678a2879b30306d323f4542626697a464a97c0a07c9aebf7ebca65cd4dde" diff --git a/Cargo.toml b/Cargo.toml index e22632d..4bc9264 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,73 +1,74 @@ -[package] -name = "fedimint-tonic-lnd" -version = "0.2.0" -edition = "2021" -rust-version = "1.65.0" -description = "An async library implementing LND RPC via tonic and prost. Forked from https://github.com/Kixunil/tonic_lnd" -homepage = "https://github.com/fedimint/tonic_lnd" -repository = "https://github.com/fedimint/tonic_lnd" -readme = "README.md" -keywords = ["LND", "rpc", "grpc", "tonic", "async"] -categories = ["api-bindings", "asynchronous", "cryptography::cryptocurrencies", "network-programming"] -license = "MITNFA" - -[features] -lightningrpc = [] -signrpc = [] -walletrpc = ["signrpc"] -peersrpc = [] -versionrpc = [] -routerrpc = ["lightningrpc"] -invoicesrpc = ["lightningrpc"] -staterpc = ["lightningrpc"] -all = ["lightningrpc", "walletrpc", "peersrpc", "versionrpc", "routerrpc", "invoicesrpc", "staterpc"] -default = ["all"] - -[dependencies] -hex = "0.4.3" -http-body = "0.4.5" -hyper = { version = "0.14.27", features = ["client"], default-features = false } -prost = "0.12.0" -rustls = { version = "0.21.0", features = ["dangerous_configuration"], default-features = false } -rustls-pemfile = "1.0.0" -hyper-rustls = { version = "0.24.1", features = ["acceptor", "http2", "tls12"], default-features = false } -tonic = { version = "0.10.0", features = ["transport", "tls"] } -tokio = { version = "1.32.0", features = ["fs"] } -tokio-stream = { version = "0.1", features = ["net"] } -tower = "0.4.13" - -[build-dependencies] -tonic-build = "0.10.0" - -[dev-dependencies] -tokio = { version = "1.7.1", features = ["rt-multi-thread"] } - -[[example]] -name = "get_info" -path = "examples/get_info.rs" -required-features = ["lightningrpc"] - -[[example]] -name = "get_version" -path = "examples/get_version.rs" -required-features = ["versionrpc"] - -[[example]] -name = "track_payment" -path = "examples/track_payment.rs" -required-features = ["routerrpc"] - -[[example]] -name = "cancel_invoice" -path = "examples/cancel_invoice.rs" -required-features = ["invoicesrpc"] - -[[example]] -name = "subscribe_invoices" -path = "examples/subscribe_invoices.rs" -required-features = ["invoicesrpc"] - -[[example]] -name = "intercept_htlcs" -path = "examples/intercept_htlcs.rs" -required-features = ["routerrpc"] +[package] +name = "fedimint-tonic-lnd" +version = "0.2.0" +edition = "2021" +rust-version = "1.80.1" +description = "An async library implementing LND RPC via tonic and prost. Forked from https://github.com/Kixunil/tonic_lnd" +homepage = "https://github.com/fedimint/tonic_lnd" +repository = "https://github.com/fedimint/tonic_lnd" +readme = "README.md" +keywords = ["LND", "rpc", "grpc", "tonic", "async"] +categories = ["api-bindings", "asynchronous", "cryptography::cryptocurrencies", "network-programming"] +license = "MITNFA" + +[features] +lightningrpc = [] +signrpc = [] +walletrpc = ["signrpc"] +peersrpc = [] +versionrpc = [] +routerrpc = ["lightningrpc"] +invoicesrpc = ["lightningrpc"] +staterpc = ["lightningrpc"] +all = ["lightningrpc", "walletrpc", "peersrpc", "versionrpc", "routerrpc", "invoicesrpc", "staterpc"] +default = ["all"] + +[dependencies] +hex = "0.4.3" +http-body = "1.0.1" +http-body-util = "0.1.2" +hyper = { version = "1.4.1", features = ["client"], default-features = false } +prost = "0.13.1" +rustls = { version = "0.23.12", default-features = false } +rustls-pemfile = "2.1.3" +hyper-rustls = { version = "0.27.2", features = [ "http2", "tls12"], default-features = false } +tonic = { version = "0.12.2", features = ["transport", "tls"] } +tokio = { version = "1.39.3", features = ["full"] } +tokio-stream = { version = "0.1.15", features = ["net"] } +tower = "0.5.0" + +[build-dependencies] +tonic-build = "0.12.2" + +[dev-dependencies] +tokio = { version = "1.39.3", features = ["rt-multi-thread"] } + +[[example]] +name = "get_info" +path = "examples/get_info.rs" +required-features = ["lightningrpc"] + +[[example]] +name = "get_version" +path = "examples/get_version.rs" +required-features = ["versionrpc"] + +[[example]] +name = "track_payment" +path = "examples/track_payment.rs" +required-features = ["routerrpc"] + +[[example]] +name = "cancel_invoice" +path = "examples/cancel_invoice.rs" +required-features = ["invoicesrpc"] + +[[example]] +name = "subscribe_invoices" +path = "examples/subscribe_invoices.rs" +required-features = ["invoicesrpc"] + +[[example]] +name = "intercept_htlcs" +path = "examples/intercept_htlcs.rs" +required-features = ["routerrpc"] diff --git a/README.md b/README.md index fb6d4c0..9d3f584 100644 --- a/README.md +++ b/README.md @@ -1,73 +1,73 @@ -# Tonic LND client - -[![Crate](https://img.shields.io/crates/v/fedimint-tonic-lnd.svg?logo=rust)](https://crates.io/crates/fedimint-tonic-lnd) -[![Documentation](https://img.shields.io/static/v1?logo=read-the-docs&label=docs.rs&message=fedimint-tonic-lnd&color=informational)](https://docs.rs/fedimint-tonic-lnd/) - -Rust implementation of LND RPC client using async gRPC library `tonic`. - -## About - -**Warning: this crate is in early development and may have unknown problems! -Review it before using with mainnet funds!** - -This crate supports *[Lightning](https://lightning.engineering/api-docs/category/lightning-service)*, *[WalletKit](https://lightning.engineering/api-docs/category/walletkit-service)*, *[Signer](https://lightning.engineering/api-docs/category/signer-service)*, and *[Peer](https://lightning.engineering/api-docs/category/peers-service)* RPC APIs from LND [v0.15.4-beta](https://github.com/lightningnetwork/lnd/tree/v0.15.4-beta) - -This crate implements LND GRPC using [`tonic`](https://docs.rs/tonic/) and [`prost`](https://docs.rs/prost/). -Apart from being up-to-date at the time of writing (:D) it also allows `async` usage. -It contains vendored `*.proto` files so LND source code is not *required* -but accepts an environment variable `LND_REPO_DIR` which overrides the vendored `*.proto` files. -This can be used to test new features in non-released `lnd`. -(Actually, the motivating project using this library was that case. :)) - -## Features - -Since most of the LND RPCs supported by this crate can be used in isolation, and your project likely only needs a subset of these RPCs, we expose each RPC under [Cargo feature gates](https://doc.rust-lang.org/cargo/reference/features.html). See the Cargo manifest for the [latest supported features](https://github.com/Kixunil/tonic_lnd/blob/master/Cargo.toml) - -All features are included by default, but you can explicitly select the features you want for a [slimmer dependency and faster compilations](https://github.com/Kixunil/tonic_lnd/pull/29#issuecomment-1352385426). - -## Usage - -There's no setup needed beyond adding the crate to your `Cargo.toml`. -If you need to change the `*.proto` files from which the client is generated, set the environment variable `LND_REPO_DIR` to a directory with cloned [`lnd`](https://github.com/lightningnetwork/lnd.git) during build. - -Here's an example of retrieving information from LND (`[getinfo](https://api.lightning.community/#getinfo)` call). -You can find this and more [examples in crate root](https://github.com/Kixunil/tonic_lnd/tree/master/examples) for your convenience. - -```rust -// This program accepts three arguments: address, cert file, macaroon file -// The address must start with `https://`! - -#[tokio::main] -async fn main() { - let mut args = std::env::args_os(); - args.next().expect("not even zeroth arg given"); - let address = args.next().expect("missing arguments: address, cert file, macaroon file"); - let cert_file = args.next().expect("missing arguments: cert file, macaroon file"); - let macaroon_file = args.next().expect("missing argument: macaroon file"); - let address = address.into_string().expect("address is not UTF-8"); - - // Connecting to LND requires only address, cert file, and macaroon file - let mut client = fedimint_tonic_lnd::connect(address, cert_file, macaroon_file) - .await - .expect("failed to connect"); - - let info = client - .lightning() - // All calls require at least empty parameter - .get_info(fedimint_tonic_lnd::lnrpc::GetInfoRequest {}) - .await - .expect("failed to get info"); - - // We only print it here, note that in real-life code you may want to call `.into_inner()` on - // the response to get the message. - println!("{:#?}", info); -} -``` - -## MSRV - -1.65.0 - -## License - -MITNFA +# Tonic LND client + +[![Crate](https://img.shields.io/crates/v/fedimint-tonic-lnd.svg?logo=rust)](https://crates.io/crates/fedimint-tonic-lnd) +[![Documentation](https://img.shields.io/static/v1?logo=read-the-docs&label=docs.rs&message=fedimint-tonic-lnd&color=informational)](https://docs.rs/fedimint-tonic-lnd/) + +Rust implementation of LND RPC client using async gRPC library `tonic`. + +## About + +**Warning: this crate is in early development and may have unknown problems! +Review it before using with mainnet funds!** + +This crate supports *[Lightning](https://lightning.engineering/api-docs/category/lightning-service)*, *[WalletKit](https://lightning.engineering/api-docs/category/walletkit-service)*, *[Signer](https://lightning.engineering/api-docs/category/signer-service)*, and *[Peer](https://lightning.engineering/api-docs/category/peers-service)* RPC APIs from LND [v0.15.4-beta](https://github.com/lightningnetwork/lnd/tree/v0.15.4-beta) + +This crate implements LND GRPC using [`tonic`](https://docs.rs/tonic/) and [`prost`](https://docs.rs/prost/). +Apart from being up-to-date at the time of writing (:D) it also allows `async` usage. +It contains vendored `*.proto` files so LND source code is not *required* +but accepts an environment variable `LND_REPO_DIR` which overrides the vendored `*.proto` files. +This can be used to test new features in non-released `lnd`. +(Actually, the motivating project using this library was that case. :)) + +## Features + +Since most of the LND RPCs supported by this crate can be used in isolation, and your project likely only needs a subset of these RPCs, we expose each RPC under [Cargo feature gates](https://doc.rust-lang.org/cargo/reference/features.html). See the Cargo manifest for the [latest supported features](https://github.com/Kixunil/tonic_lnd/blob/master/Cargo.toml) + +All features are included by default, but you can explicitly select the features you want for a [slimmer dependency and faster compilations](https://github.com/Kixunil/tonic_lnd/pull/29#issuecomment-1352385426). + +## Usage + +There's no setup needed beyond adding the crate to your `Cargo.toml`. +If you need to change the `*.proto` files from which the client is generated, set the environment variable `LND_REPO_DIR` to a directory with cloned [`lnd`](https://github.com/lightningnetwork/lnd.git) during build. + +Here's an example of retrieving information from LND (`[getinfo](https://api.lightning.community/#getinfo)` call). +You can find this and more [examples in crate root](https://github.com/Kixunil/tonic_lnd/tree/master/examples) for your convenience. + +```rust +// This program accepts three arguments: address, cert file, macaroon file +// The address must start with `https://`! + +#[tokio::main] +async fn main() { + let mut args = std::env::args_os(); + args.next().expect("not even zeroth arg given"); + let address = args.next().expect("missing arguments: address, cert file, macaroon file"); + let cert_file = args.next().expect("missing arguments: cert file, macaroon file"); + let macaroon_file = args.next().expect("missing argument: macaroon file"); + let address = address.into_string().expect("address is not UTF-8"); + + // Connecting to LND requires only address, cert file, and macaroon file + let mut client = fedimint_tonic_lnd::connect(address, cert_file, macaroon_file) + .await + .expect("failed to connect"); + + let info = client + .lightning() + // All calls require at least empty parameter + .get_info(fedimint_tonic_lnd::lnrpc::GetInfoRequest {}) + .await + .expect("failed to get info"); + + // We only print it here, note that in real-life code you may want to call `.into_inner()` on + // the response to get the message. + println!("{:#?}", info); +} +``` + +## MSRV + +1.65.0 + +## License + +MITNFA diff --git a/build.rs b/build.rs index 4a39ce5..f6fea7c 100644 --- a/build.rs +++ b/build.rs @@ -1,35 +1,35 @@ -use std::path::PathBuf; - -fn main() -> std::io::Result<()> { - println!("cargo:rerun-if-env-changed=LND_REPO_DIR"); - let dir = match std::env::var_os("LND_REPO_DIR") { - Some(lnd_repo_path) => { - let mut lnd_rpc_dir = PathBuf::from(lnd_repo_path); - lnd_rpc_dir.push("lnrpc"); - lnd_rpc_dir - } - None => PathBuf::from("vendor"), - }; - - let lnd_rpc_proto_file = dir.join("lightning.proto"); - println!("cargo:rerun-if-changed={}", lnd_rpc_proto_file.display()); - - let protos = [ - "signrpc/signer.proto", - "walletrpc/walletkit.proto", - "lightning.proto", - "peersrpc/peers.proto", - "verrpc/verrpc.proto", - "routerrpc/router.proto", - "invoicesrpc/invoices.proto", - "staterpc/state.proto", - ]; - - let proto_paths: Vec<_> = protos.iter().map(|proto| dir.join(proto)).collect(); - - tonic_build::configure() - .build_client(true) - .build_server(false) - .compile(&proto_paths, &[dir])?; - Ok(()) -} +use std::path::PathBuf; + +fn main() -> std::io::Result<()> { + println!("cargo:rerun-if-env-changed=LND_REPO_DIR"); + let dir = match std::env::var_os("LND_REPO_DIR") { + Some(lnd_repo_path) => { + let mut lnd_rpc_dir = PathBuf::from(lnd_repo_path); + lnd_rpc_dir.push("lnrpc"); + lnd_rpc_dir + } + None => PathBuf::from("vendor"), + }; + + let lnd_rpc_proto_file = dir.join("lightning.proto"); + println!("cargo:rerun-if-changed={}", lnd_rpc_proto_file.display()); + + let protos = [ + "signrpc/signer.proto", + "walletrpc/walletkit.proto", + "lightning.proto", + "peersrpc/peers.proto", + "verrpc/verrpc.proto", + "routerrpc/router.proto", + "invoicesrpc/invoices.proto", + "staterpc/state.proto", + ]; + + let proto_paths: Vec<_> = protos.iter().map(|proto| dir.join(proto)).collect(); + + tonic_build::configure() + .build_client(true) + .build_server(false) + .compile(&proto_paths, &[dir])?; + Ok(()) +} diff --git a/examples/cancel_invoice.rs b/examples/cancel_invoice.rs index 359f645..d68c92f 100644 --- a/examples/cancel_invoice.rs +++ b/examples/cancel_invoice.rs @@ -1,48 +1,48 @@ -// This example connects to LND and uses invoices rpc to cancel an existing invoice -// -// The program accepts four arguments: address, cert file, macaroon file, payment hash -// The address must start with `https://`! -// -// Example run: `cargo run --features=invoicesrpc --example cancel_invoice
` - -#[tokio::main] -#[cfg(feature = "invoicesrpc")] -async fn main() { - let mut args = std::env::args_os(); - args.next().expect("not even zeroth arg given"); - let address: String = args - .next() - .expect("missing arguments: address, macaroon file, payment hash") - .into_string() - .expect("address is not UTF-8"); - let cert_file: String = args - .next() - .expect("missing arguments: cert file, macaroon file, payment hash") - .into_string() - .expect("cert_file is not UTF-8"); - let macaroon_file: String = args - .next() - .expect("missing argument: macaroon file, payment hash") - .into_string() - .expect("macaroon_file is not UTF-8"); - let payment_hash: Vec = hex::decode( - args.next() - .expect("missing argument: payment hash") - .into_string() - .expect("payment_hash is not UTF-8"), - ) - .expect("payment_hash is not a valid hex"); - - // Connecting to LND requires only address, cert file, and macaroon file - let mut client = fedimint_tonic_lnd::connect(address, cert_file, macaroon_file) - .await - .expect("failed to connect"); - - client - .invoices() - .cancel_invoice(fedimint_tonic_lnd::invoicesrpc::CancelInvoiceMsg { payment_hash }) - .await - .expect("Failed to cancel invoice"); - - println!("Invoice canceled"); -} +// This example connects to LND and uses invoices rpc to cancel an existing invoice +// +// The program accepts four arguments: address, cert file, macaroon file, payment hash +// The address must start with `https://`! +// +// Example run: `cargo run --features=invoicesrpc --example cancel_invoice
` + +#[tokio::main] +#[cfg(feature = "invoicesrpc")] +async fn main() { + let mut args = std::env::args_os(); + args.next().expect("not even zeroth arg given"); + let address: String = args + .next() + .expect("missing arguments: address, macaroon file, payment hash") + .into_string() + .expect("address is not UTF-8"); + let cert_file: String = args + .next() + .expect("missing arguments: cert file, macaroon file, payment hash") + .into_string() + .expect("cert_file is not UTF-8"); + let macaroon_file: String = args + .next() + .expect("missing argument: macaroon file, payment hash") + .into_string() + .expect("macaroon_file is not UTF-8"); + let payment_hash: Vec = hex::decode( + args.next() + .expect("missing argument: payment hash") + .into_string() + .expect("payment_hash is not UTF-8"), + ) + .expect("payment_hash is not a valid hex"); + + // Connecting to LND requires only address, cert file, and macaroon file + let mut client = fedimint_tonic_lnd::connect(address, cert_file, macaroon_file) + .await + .expect("failed to connect"); + + client + .invoices() + .cancel_invoice(fedimint_tonic_lnd::invoicesrpc::CancelInvoiceMsg { payment_hash }) + .await + .expect("Failed to cancel invoice"); + + println!("Invoice canceled"); +} diff --git a/examples/get_info.rs b/examples/get_info.rs index 34043b4..4274258 100644 --- a/examples/get_info.rs +++ b/examples/get_info.rs @@ -1,38 +1,38 @@ -// This example only fetches and prints the node info to the standard output similarly to -// `lncli getinfo`. -// -// The program accepts three arguments: address, cert file, macaroon file -// The address must start with `https://`! -// -// Example run: `cargo run --features=lightningrpc --example get_info
` - -#[tokio::main] -#[cfg(feature = "lightningrpc")] -async fn main() { - let mut args = std::env::args_os(); - args.next().expect("not even zeroth arg given"); - let address = args - .next() - .expect("missing arguments: address, cert file, macaroon file"); - let cert_file = args - .next() - .expect("missing arguments: cert file, macaroon file"); - let macaroon_file = args.next().expect("missing argument: macaroon file"); - let address = address.into_string().expect("address is not UTF-8"); - - // Connecting to LND requires only address, cert file, and macaroon file - let mut client = fedimint_tonic_lnd::connect(address, cert_file, macaroon_file) - .await - .expect("failed to connect"); - - let info = client - .lightning() - // All calls require at least empty parameter - .get_info(fedimint_tonic_lnd::lnrpc::GetInfoRequest {}) - .await - .expect("failed to get info"); - - // We only print it here, note that in real-life code you may want to call `.into_inner()` on - // the response to get the message. - println!("{:#?}", info); -} +// This example only fetches and prints the node info to the standard output similarly to +// `lncli getinfo`. +// +// The program accepts three arguments: address, cert file, macaroon file +// The address must start with `https://`! +// +// Example run: `cargo run --features=lightningrpc --example get_info
` + +#[tokio::main] +#[cfg(feature = "lightningrpc")] +async fn main() { + let mut args = std::env::args_os(); + args.next().expect("not even zeroth arg given"); + let address = args + .next() + .expect("missing arguments: address, cert file, macaroon file"); + let cert_file = args + .next() + .expect("missing arguments: cert file, macaroon file"); + let macaroon_file = args.next().expect("missing argument: macaroon file"); + let address = address.into_string().expect("address is not UTF-8"); + + // Connecting to LND requires only address, cert file, and macaroon file + let mut client = fedimint_tonic_lnd::connect(address, cert_file, macaroon_file) + .await + .expect("failed to connect"); + + let info = client + .lightning() + // All calls require at least empty parameter + .get_info(fedimint_tonic_lnd::lnrpc::GetInfoRequest {}) + .await + .expect("failed to get info"); + + // We only print it here, note that in real-life code you may want to call `.into_inner()` on + // the response to get the message. + println!("{:#?}", info); +} diff --git a/examples/get_version.rs b/examples/get_version.rs index 2bb028f..fc539b9 100644 --- a/examples/get_version.rs +++ b/examples/get_version.rs @@ -1,35 +1,35 @@ -// This example fetches and prints the version info of the running lnd daemon -// -// The program accepts three arguments: address, cert file, macaroon file -// The address must start with `https://`! -// -// Example run: `cargo run --features=versionrpc --example get_version
` - -#[tokio::main] -#[cfg(feature = "versionrpc")] -async fn main() { - let mut args = std::env::args_os(); - args.next().expect("not even zeroth arg given"); - let address = args - .next() - .expect("missing arguments: address, cert file, macaroon file"); - let cert_file = args - .next() - .expect("missing arguments: cert file, macaroon file"); - let macaroon_file = args.next().expect("missing argument: macaroon file"); - let address = address.into_string().expect("address is not UTF-8"); - - // Connecting to LND requires only address, cert file, and macaroon file - let mut client = fedimint_tonic_lnd::connect(address, cert_file, macaroon_file) - .await - .expect("failed to connect"); - - let version = client - .versioner() - .get_version(fedimint_tonic_lnd::verrpc::VersionRequest {}) - .await - .expect("failed to get version"); - // We only print it here, note that in real-life code you may want to call `.into_inner()` on - // the response to get the message. - println!("{:#?}", version); -} +// This example fetches and prints the version info of the running lnd daemon +// +// The program accepts three arguments: address, cert file, macaroon file +// The address must start with `https://`! +// +// Example run: `cargo run --features=versionrpc --example get_version
` + +#[tokio::main] +#[cfg(feature = "versionrpc")] +async fn main() { + let mut args = std::env::args_os(); + args.next().expect("not even zeroth arg given"); + let address = args + .next() + .expect("missing arguments: address, cert file, macaroon file"); + let cert_file = args + .next() + .expect("missing arguments: cert file, macaroon file"); + let macaroon_file = args.next().expect("missing argument: macaroon file"); + let address = address.into_string().expect("address is not UTF-8"); + + // Connecting to LND requires only address, cert file, and macaroon file + let mut client = fedimint_tonic_lnd::connect(address, cert_file, macaroon_file) + .await + .expect("failed to connect"); + + let version = client + .versioner() + .get_version(fedimint_tonic_lnd::verrpc::VersionRequest {}) + .await + .expect("failed to get version"); + // We only print it here, note that in real-life code you may want to call `.into_inner()` on + // the response to get the message. + println!("{:#?}", version); +} diff --git a/examples/intercept_htlcs.rs b/examples/intercept_htlcs.rs index 1155536..e467bcd 100644 --- a/examples/intercept_htlcs.rs +++ b/examples/intercept_htlcs.rs @@ -1,66 +1,66 @@ -// This example connects to LND and uses router rpc to intercept htlcs, inspect the details, then resume forwarding them -// -// The program accepts three arguments: address, cert file, macaroon file -// The address must start with `https://`! -// -// Example run: `cargo run --features=routerrpc --example intercept_htlcs
` - -#[tokio::main] -#[cfg(feature = "routerrpc")] -async fn main() { - let mut args = std::env::args_os(); - args.next().expect("not even zeroth arg given"); - let address: String = args - .next() - .expect("missing arguments: address, macaroon file, payment hash") - .into_string() - .expect("address is not UTF-8"); - let cert_file: String = args - .next() - .expect("missing arguments: cert file, macaroon file") - .into_string() - .expect("cert_file is not UTF-8"); - let macaroon_file: String = args - .next() - .expect("missing argument: macaroon file") - .into_string() - .expect("macaroon_file is not UTF-8"); - - // Connecting to LND requires only address, cert file, and macaroon file - let mut client = fedimint_tonic_lnd::connect(address, cert_file, macaroon_file) - .await - .expect("failed to connect"); - - let (tx, rx) = tokio::sync::mpsc::channel::< - fedimint_tonic_lnd::routerrpc::ForwardHtlcInterceptResponse, - >(1024); - let stream = tokio_stream::wrappers::ReceiverStream::new(rx); - - let mut htlc_stream = client - .router() - .htlc_interceptor(stream) - .await - .expect("Failed to call subscribe_invoices") - .into_inner(); - - while let Some(htlc) = htlc_stream - .message() - .await - .expect("Failed to receive invoices") - { - println!("HTLC Intercepted------------"); - println!( - "incoming_circuit_key: {:?}\nincoming_amount_msat: {}\noutgoing_amount_msat: {}\npayment_hash: {:?}\n", - htlc.incoming_circuit_key, htlc.incoming_amount_msat, htlc.outgoing_amount_msat, htlc.payment_hash - ); - - let response = fedimint_tonic_lnd::routerrpc::ForwardHtlcInterceptResponse { - incoming_circuit_key: htlc.incoming_circuit_key, - action: 2, // Resume fordwarding of intercepted HTLC - preimage: vec![], - failure_message: vec![], - failure_code: 0, - }; - tx.send(response).await.unwrap(); - } -} +// This example connects to LND and uses router rpc to intercept htlcs, inspect the details, then resume forwarding them +// +// The program accepts three arguments: address, cert file, macaroon file +// The address must start with `https://`! +// +// Example run: `cargo run --features=routerrpc --example intercept_htlcs
` + +#[tokio::main] +#[cfg(feature = "routerrpc")] +async fn main() { + let mut args = std::env::args_os(); + args.next().expect("not even zeroth arg given"); + let address: String = args + .next() + .expect("missing arguments: address, macaroon file, payment hash") + .into_string() + .expect("address is not UTF-8"); + let cert_file: String = args + .next() + .expect("missing arguments: cert file, macaroon file") + .into_string() + .expect("cert_file is not UTF-8"); + let macaroon_file: String = args + .next() + .expect("missing argument: macaroon file") + .into_string() + .expect("macaroon_file is not UTF-8"); + + // Connecting to LND requires only address, cert file, and macaroon file + let mut client = fedimint_tonic_lnd::connect(address, cert_file, macaroon_file) + .await + .expect("failed to connect"); + + let (tx, rx) = tokio::sync::mpsc::channel::< + fedimint_tonic_lnd::routerrpc::ForwardHtlcInterceptResponse, + >(1024); + let stream = tokio_stream::wrappers::ReceiverStream::new(rx); + + let mut htlc_stream = client + .router() + .htlc_interceptor(stream) + .await + .expect("Failed to call subscribe_invoices") + .into_inner(); + + while let Some(htlc) = htlc_stream + .message() + .await + .expect("Failed to receive invoices") + { + println!("HTLC Intercepted------------"); + println!( + "incoming_circuit_key: {:?}\nincoming_amount_msat: {}\noutgoing_amount_msat: {}\npayment_hash: {:?}\n", + htlc.incoming_circuit_key, htlc.incoming_amount_msat, htlc.outgoing_amount_msat, htlc.payment_hash + ); + + let response = fedimint_tonic_lnd::routerrpc::ForwardHtlcInterceptResponse { + incoming_circuit_key: htlc.incoming_circuit_key, + action: 2, // Resume fordwarding of intercepted HTLC + preimage: vec![], + failure_message: vec![], + failure_code: 0, + }; + tx.send(response).await.unwrap(); + } +} diff --git a/examples/subscribe_invoices.rs b/examples/subscribe_invoices.rs index b821f2e..eca48f2 100644 --- a/examples/subscribe_invoices.rs +++ b/examples/subscribe_invoices.rs @@ -1,52 +1,52 @@ -// This example connects to LND and prints out all incoming invoices as they settle. -// -// The program accepts three arguments: address, cert file, macaroon file -// The address must start with `https://`! -// -// Example run: `cargo run --features=lightningrpc --example subscribe_invoices
` - -#[tokio::main] -#[cfg(feature = "lightningrpc")] -async fn main() { - let mut args = std::env::args_os(); - args.next().expect("not even zeroth arg given"); - let address = args - .next() - .expect("missing arguments: address, cert file, macaroon file"); - let cert_file = args - .next() - .expect("missing arguments: cert file, macaroon file"); - let macaroon_file = args.next().expect("missing argument: macaroon file"); - let address = address.into_string().expect("address is not UTF-8"); - - // Connecting to LND requires only address, cert file, and macaroon file - let mut client = fedimint_tonic_lnd::connect(address, cert_file, macaroon_file) - .await - .expect("failed to connect"); - - let mut invoice_stream = client - .lightning() - .subscribe_invoices(fedimint_tonic_lnd::lnrpc::InvoiceSubscription { - add_index: 0, - settle_index: 0, - }) - .await - .expect("Failed to call subscribe_invoices") - .into_inner(); - - while let Some(invoice) = invoice_stream - .message() - .await - .expect("Failed to receive invoices") - { - let state: fedimint_tonic_lnd::lnrpc::invoice::InvoiceState = invoice - .state - .try_into() - .expect("Failed to parse invoice state"); - - // If this invoice was Settled we can do something with it - if state == fedimint_tonic_lnd::lnrpc::invoice::InvoiceState::Settled { - println!("{:?}", invoice); - } - } -} +// This example connects to LND and prints out all incoming invoices as they settle. +// +// The program accepts three arguments: address, cert file, macaroon file +// The address must start with `https://`! +// +// Example run: `cargo run --features=lightningrpc --example subscribe_invoices
` + +#[tokio::main] +#[cfg(feature = "lightningrpc")] +async fn main() { + let mut args = std::env::args_os(); + args.next().expect("not even zeroth arg given"); + let address = args + .next() + .expect("missing arguments: address, cert file, macaroon file"); + let cert_file = args + .next() + .expect("missing arguments: cert file, macaroon file"); + let macaroon_file = args.next().expect("missing argument: macaroon file"); + let address = address.into_string().expect("address is not UTF-8"); + + // Connecting to LND requires only address, cert file, and macaroon file + let mut client = fedimint_tonic_lnd::connect(address, cert_file, macaroon_file) + .await + .expect("failed to connect"); + + let mut invoice_stream = client + .lightning() + .subscribe_invoices(fedimint_tonic_lnd::lnrpc::InvoiceSubscription { + add_index: 0, + settle_index: 0, + }) + .await + .expect("Failed to call subscribe_invoices") + .into_inner(); + + while let Some(invoice) = invoice_stream + .message() + .await + .expect("Failed to receive invoices") + { + let state: fedimint_tonic_lnd::lnrpc::invoice::InvoiceState = invoice + .state + .try_into() + .expect("Failed to parse invoice state"); + + // If this invoice was Settled we can do something with it + if state == fedimint_tonic_lnd::lnrpc::invoice::InvoiceState::Settled { + println!("{:?}", invoice); + } + } +} diff --git a/examples/track_payment.rs b/examples/track_payment.rs index 07c31f4..5c2161b 100644 --- a/examples/track_payment.rs +++ b/examples/track_payment.rs @@ -1,60 +1,60 @@ -// This example connects to LND and uses router rpc to track a payment. -// -// The program accepts four arguments: address, cert file, macaroon file, payment hash -// The address must start with `https://`! -// -// Example run: `cargo run --features=routerrpc --example track_payment
` - -#[tokio::main] -#[cfg(feature = "routerrpc")] -async fn main() { - let mut args = std::env::args_os(); - args.next().expect("not even zeroth arg given"); - let address: String = args - .next() - .expect("missing arguments: address, macaroon file, payment hash") - .into_string() - .expect("address is not UTF-8"); - let cert_file: String = args - .next() - .expect("missing arguments: cert file, macaroon file, payment hash") - .into_string() - .expect("cert_file is not UTF-8"); - let macaroon_file: String = args - .next() - .expect("missing argument: macaroon file, payment hash") - .into_string() - .expect("macaroon_file is not UTF-8"); - let payment_hash: Vec = hex::decode( - args.next() - .expect("missing argument: payment hash") - .into_string() - .expect("payment_hash is not UTF-8"), - ) - .expect("payment_hash is not a valid hex"); - - // Connecting to LND requires only address, cert file, and macaroon file - let mut client = fedimint_tonic_lnd::connect(address, cert_file, macaroon_file) - .await - .expect("failed to connect"); - - let response = client - .router() - .track_payment(fedimint_tonic_lnd::routerrpc::TrackPaymentRequest { - payment_hash, - no_inflight_updates: false, - }) - .await - .expect("Failed to call track_payment"); - - if let Some(payment) = response - .into_inner() - .message() - .await - .expect("Failed to get payment") - { - println!("{:?}", payment); - } else { - println!("Payment not found"); - } -} +// This example connects to LND and uses router rpc to track a payment. +// +// The program accepts four arguments: address, cert file, macaroon file, payment hash +// The address must start with `https://`! +// +// Example run: `cargo run --features=routerrpc --example track_payment
` + +#[tokio::main] +#[cfg(feature = "routerrpc")] +async fn main() { + let mut args = std::env::args_os(); + args.next().expect("not even zeroth arg given"); + let address: String = args + .next() + .expect("missing arguments: address, macaroon file, payment hash") + .into_string() + .expect("address is not UTF-8"); + let cert_file: String = args + .next() + .expect("missing arguments: cert file, macaroon file, payment hash") + .into_string() + .expect("cert_file is not UTF-8"); + let macaroon_file: String = args + .next() + .expect("missing argument: macaroon file, payment hash") + .into_string() + .expect("macaroon_file is not UTF-8"); + let payment_hash: Vec = hex::decode( + args.next() + .expect("missing argument: payment hash") + .into_string() + .expect("payment_hash is not UTF-8"), + ) + .expect("payment_hash is not a valid hex"); + + // Connecting to LND requires only address, cert file, and macaroon file + let mut client = fedimint_tonic_lnd::connect(address, cert_file, macaroon_file) + .await + .expect("failed to connect"); + + let response = client + .router() + .track_payment(fedimint_tonic_lnd::routerrpc::TrackPaymentRequest { + payment_hash, + no_inflight_updates: false, + }) + .await + .expect("Failed to call track_payment"); + + if let Some(payment) = response + .into_inner() + .message() + .await + .expect("Failed to get payment") + { + println!("{:?}", payment); + } else { + println!("Payment not found"); + } +} diff --git a/src/error.rs b/src/error.rs index 36e6533..ca59f67 100644 --- a/src/error.rs +++ b/src/error.rs @@ -1,58 +1,58 @@ -use std::fmt; -use std::path::PathBuf; - -/// Error that could happen during connecting to LND -/// -/// This error may be returned by the `connect()` function if connecting failed. -/// It is currently opaque because it's unclear how the variants will look long-term. -/// Thus you probably only want to display it. -#[derive(Debug)] -pub struct ConnectError { - internal: InternalConnectError, -} - -impl From for ConnectError { - fn from(value: InternalConnectError) -> Self { - ConnectError { internal: value } - } -} - -#[derive(Debug)] -pub(crate) enum InternalConnectError { - ReadFile { - file: PathBuf, - error: std::io::Error, - }, - ParseCert { - file: PathBuf, - error: std::io::Error, - }, - InvalidAddress { - address: String, - error: Box, - }, -} - -impl fmt::Display for ConnectError { - fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { - use InternalConnectError::*; - - match &self.internal { - ReadFile { file, .. } => write!(f, "failed to read file {}", file.display()), - ParseCert { file, .. } => write!(f, "failed to parse certificate {}", file.display()), - InvalidAddress { address, .. } => write!(f, "invalid address {}", address), - } - } -} - -impl std::error::Error for ConnectError { - fn source(&self) -> Option<&(dyn std::error::Error + 'static)> { - use InternalConnectError::*; - - match &self.internal { - ReadFile { error, .. } => Some(error), - ParseCert { error, .. } => Some(error), - InvalidAddress { error, .. } => Some(&**error), - } - } -} +use std::fmt; +use std::path::PathBuf; + +/// Error that could happen during connecting to LND +/// +/// This error may be returned by the `connect()` function if connecting failed. +/// It is currently opaque because it's unclear how the variants will look long-term. +/// Thus you probably only want to display it. +#[derive(Debug)] +pub struct ConnectError { + internal: InternalConnectError, +} + +impl From for ConnectError { + fn from(value: InternalConnectError) -> Self { + ConnectError { internal: value } + } +} + +#[derive(Debug)] +pub(crate) enum InternalConnectError { + ReadFile { + file: PathBuf, + error: std::io::Error, + }, + ParseCert { + file: PathBuf, + error: std::io::Error, + }, + InvalidAddress { + address: String, + error: Box, + }, +} + +impl fmt::Display for ConnectError { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + use InternalConnectError::*; + + match &self.internal { + ReadFile { file, .. } => write!(f, "failed to read file {}", file.display()), + ParseCert { file, .. } => write!(f, "failed to parse certificate {}", file.display()), + InvalidAddress { address, .. } => write!(f, "invalid address {}", address), + } + } +} + +impl std::error::Error for ConnectError { + fn source(&self) -> Option<&(dyn std::error::Error + 'static)> { + use InternalConnectError::*; + + match &self.internal { + ReadFile { error, .. } => Some(error), + ParseCert { error, .. } => Some(error), + InvalidAddress { error, .. } => Some(&**error), + } + } +} diff --git a/src/lib.rs b/src/lib.rs index 932956d..8f17ded 100755 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,363 +1,363 @@ -/// This is part of public interface so it's re-exported. -pub extern crate tonic; - -pub use error::ConnectError; -use error::InternalConnectError; -use http_body::combinators::UnsyncBoxBody; -use hyper::client::HttpConnector; -use hyper::Uri; -use hyper_rustls::HttpsConnector; -use std::path::{Path, PathBuf}; -use std::str::FromStr; -use tonic::codegen::{Bytes, InterceptedService}; -use tonic::Status; - -type Service = InterceptedService< - hyper::Client, UnsyncBoxBody>, - MacaroonInterceptor, ->; - -/// Convenience type alias for lightning client. -#[cfg(feature = "lightningrpc")] -pub type LightningClient = lnrpc::lightning_client::LightningClient; - -/// Convenience type alias for wallet client. -#[cfg(feature = "walletrpc")] -pub type WalletKitClient = walletrpc::wallet_kit_client::WalletKitClient; - -/// Convenience type alias for peers service client. -#[cfg(feature = "peersrpc")] -pub type PeersClient = peersrpc::peers_client::PeersClient; - -/// Convenience type alias for versioner service client. -#[cfg(feature = "versionrpc")] -pub type VersionerClient = verrpc::versioner_client::VersionerClient; - -/// Convenience type alias for signer client. -#[cfg(feature = "signrpc")] -pub type SignerClient = signrpc::signer_client::SignerClient; - -/// Convenience type alias for router client. -#[cfg(feature = "routerrpc")] -pub type RouterClient = routerrpc::router_client::RouterClient; - -/// Convenience type alias for invoices client. -#[cfg(feature = "invoicesrpc")] -pub type InvoicesClient = invoicesrpc::invoices_client::InvoicesClient; - -/// Convenience type alias for state service client. -#[cfg(feature = "staterpc")] -pub type StateClient = staterpc::state_client::StateClient; - -/// The client returned by `connect` function -/// -/// This is a convenience type which you most likely want to use instead of raw client. -#[derive(Clone)] -pub struct Client { - #[cfg(feature = "lightningrpc")] - lightning: LightningClient, - #[cfg(feature = "walletrpc")] - wallet: WalletKitClient, - #[cfg(feature = "signrpc")] - signer: SignerClient, - #[cfg(feature = "peersrpc")] - peers: PeersClient, - #[cfg(feature = "versionrpc")] - version: VersionerClient, - #[cfg(feature = "routerrpc")] - router: RouterClient, - #[cfg(feature = "invoicesrpc")] - invoices: InvoicesClient, - #[cfg(feature = "staterpc")] - state: StateClient, -} - -impl Client { - /// Returns the lightning client. - #[cfg(feature = "lightningrpc")] - pub fn lightning(&mut self) -> &mut LightningClient { - &mut self.lightning - } - - /// Returns the wallet client. - #[cfg(feature = "walletrpc")] - pub fn wallet(&mut self) -> &mut WalletKitClient { - &mut self.wallet - } - - /// Returns the signer client. - #[cfg(feature = "signrpc")] - pub fn signer(&mut self) -> &mut SignerClient { - &mut self.signer - } - - /// Returns the versioner client. - #[cfg(feature = "versionrpc")] - pub fn versioner(&mut self) -> &mut VersionerClient { - &mut self.version - } - - /// Returns the peers client. - #[cfg(feature = "peersrpc")] - pub fn peers(&mut self) -> &mut PeersClient { - &mut self.peers - } - - /// Returns the router client. - #[cfg(feature = "routerrpc")] - pub fn router(&mut self) -> &mut RouterClient { - &mut self.router - } - - /// Returns the invoices client. - #[cfg(feature = "invoicesrpc")] - pub fn invoices(&mut self) -> &mut InvoicesClient { - &mut self.invoices - } - - /// Returns the state service client. - #[cfg(feature = "staterpc")] - pub fn state(&mut self) -> &mut StateClient { - &mut self.state - } -} - -/// [`tonic::Status`] is re-exported as `Error` for convenience. -pub type Error = tonic::Status; - -mod error; - -macro_rules! try_map_err { - ($result:expr, $mapfn:expr) => { - match $result { - Ok(value) => value, - Err(error) => return Err($mapfn(error).into()), - } - }; -} - -/// Messages and other types generated by `tonic`/`prost` -/// -/// This is the go-to module you will need to look in to find documentation on various message -/// types. However it may be better to start from methods on the [`LightningClient`](lnrpc::lightning_client::LightningClient) type. -#[cfg(feature = "lightningrpc")] -pub mod lnrpc { - tonic::include_proto!("lnrpc"); -} - -#[cfg(feature = "walletrpc")] -pub mod walletrpc { - tonic::include_proto!("walletrpc"); -} - -#[cfg(feature = "signrpc")] -pub mod signrpc { - tonic::include_proto!("signrpc"); -} - -#[cfg(feature = "peersrpc")] -pub mod peersrpc { - tonic::include_proto!("peersrpc"); -} - -#[cfg(feature = "routerrpc")] -pub mod routerrpc { - tonic::include_proto!("routerrpc"); -} - -#[cfg(feature = "versionrpc")] -pub mod verrpc { - tonic::include_proto!("verrpc"); -} - -#[cfg(feature = "invoicesrpc")] -pub mod invoicesrpc { - tonic::include_proto!("invoicesrpc"); -} - -#[cfg(feature = "staterpc")] -pub mod staterpc { - tonic::include_proto!("staterpc"); -} - -/// Supplies requests with macaroon -#[derive(Clone)] -pub struct MacaroonInterceptor { - macaroon: String, -} - -impl tonic::service::Interceptor for MacaroonInterceptor { - fn call(&mut self, mut request: tonic::Request<()>) -> Result, Error> { - request.metadata_mut().insert( - "macaroon", - tonic::metadata::MetadataValue::from_str(&self.macaroon) - .expect("hex produced non-ascii"), - ); - Ok(request) - } -} - -async fn load_macaroon( - path: impl AsRef + Into, -) -> Result { - let macaroon = - tokio::fs::read(&path) - .await - .map_err(|error| InternalConnectError::ReadFile { - file: path.into(), - error, - })?; - Ok(hex::encode(macaroon)) -} - -/// Connects to LND using given address and credentials -/// -/// This function does all required processing of the cert file and macaroon file, so that you -/// don't have to. The address must begin with "https://", though. -/// -/// This is considered the recommended way to connect to LND. An alternative function to use -/// already-read certificate or macaroon data is currently **not** provided to discourage such use. -/// LND occasionally changes that data which would lead to errors and in turn in worse application. -/// -/// If you have a motivating use case for use of direct data feel free to open an issue and -/// explain. -#[cfg_attr(feature = "tracing", tracing::instrument(name = "Connecting to LND"))] -pub async fn connect( - address: String, - cert_file: CP, - macaroon_file: MP, -) -> Result -where - CP: AsRef + Into + std::fmt::Debug, - MP: AsRef + Into + std::fmt::Debug, -{ - let connector = hyper_rustls::HttpsConnectorBuilder::new() - .with_tls_config(tls::config(cert_file).await?) - .https_or_http() - .enable_http2() - .build(); - let macaroon = load_macaroon(macaroon_file).await?; - - let svc = InterceptedService::new( - hyper::Client::builder().build(connector), - MacaroonInterceptor { macaroon }, - ); - let uri = - Uri::from_str(address.as_str()).map_err(|error| InternalConnectError::InvalidAddress { - address, - error: Box::new(error), - })?; - - let client = Client { - #[cfg(feature = "lightningrpc")] - lightning: lnrpc::lightning_client::LightningClient::with_origin(svc.clone(), uri.clone()), - #[cfg(feature = "walletrpc")] - wallet: walletrpc::wallet_kit_client::WalletKitClient::with_origin( - svc.clone(), - uri.clone(), - ), - #[cfg(feature = "peersrpc")] - peers: peersrpc::peers_client::PeersClient::with_origin(svc.clone(), uri.clone()), - #[cfg(feature = "signrpc")] - signer: signrpc::signer_client::SignerClient::with_origin(svc.clone(), uri.clone()), - #[cfg(feature = "versionrpc")] - version: verrpc::versioner_client::VersionerClient::with_origin(svc.clone(), uri.clone()), - #[cfg(feature = "routerrpc")] - router: routerrpc::router_client::RouterClient::with_origin(svc.clone(), uri.clone()), - #[cfg(feature = "invoicesrpc")] - invoices: invoicesrpc::invoices_client::InvoicesClient::with_origin( - svc.clone(), - uri.clone(), - ), - #[cfg(feature = "staterpc")] - state: staterpc::state_client::StateClient::with_origin(svc.clone(), uri.clone()), - }; - Ok(client) -} - -mod tls { - use crate::error::{ConnectError, InternalConnectError}; - use rustls::{ - client::{ClientConfig, ServerCertVerified, ServerCertVerifier}, - Certificate, Error as TLSError, ServerName, - }; - use std::{ - path::{Path, PathBuf}, - sync::Arc, - time::SystemTime, - }; - - pub(crate) async fn config( - path: impl AsRef + Into, - ) -> Result { - Ok(ClientConfig::builder() - .with_safe_defaults() - .with_custom_certificate_verifier(Arc::new(CertVerifier::load(path).await?)) - .with_no_client_auth()) - } - - pub(crate) struct CertVerifier { - certs: Vec>, - } - - impl CertVerifier { - pub(crate) async fn load( - path: impl AsRef + Into, - ) -> Result { - let contents = try_map_err!(tokio::fs::read(&path).await, |error| { - InternalConnectError::ReadFile { - file: path.into(), - error, - } - }); - let mut reader = &*contents; - - let certs = try_map_err!(rustls_pemfile::certs(&mut reader), |error| { - InternalConnectError::ParseCert { - file: path.into(), - error, - } - }); - - Ok(CertVerifier { certs }) - } - } - - impl ServerCertVerifier for CertVerifier { - fn verify_server_cert( - &self, - end_entity: &Certificate, - intermediates: &[Certificate], - _server_name: &ServerName, - _scts: &mut dyn Iterator, - _ocsp_response: &[u8], - _now: SystemTime, - ) -> Result { - let mut certs = intermediates - .iter() - .map(|c| c.0.clone()) - .collect::>>(); - certs.push(end_entity.0.clone()); - certs.sort(); - - let mut our_certs = self.certs.clone(); - our_certs.sort(); - - if self.certs.len() != certs.len() { - return Err(TLSError::General(format!( - "Mismatched number of certificates (Expected: {}, Presented: {})", - self.certs.len(), - certs.len() - ))); - } - for (c, p) in our_certs.iter().zip(certs.iter()) { - if *p != *c { - return Err(TLSError::General( - "Server certificates do not match ours".to_string(), - )); - } - } - Ok(ServerCertVerified::assertion()) - } - } -} +/// This is part of public interface so it's re-exported. +pub extern crate tonic; + +pub use error::ConnectError; +use error::InternalConnectError; +use http_body_util::combinators::UnsyncBoxBody; +use hyper::client::HttpConnector; +use hyper::Uri; +use hyper_rustls::HttpsConnector; +use std::path::{Path, PathBuf}; +use std::str::FromStr; +use tonic::codegen::{Bytes, InterceptedService}; +use tonic::Status; + +type Service = InterceptedService< + hyper::Client, UnsyncBoxBody>, + MacaroonInterceptor, +>; + +/// Convenience type alias for lightning client. +#[cfg(feature = "lightningrpc")] +pub type LightningClient = lnrpc::lightning_client::LightningClient; + +/// Convenience type alias for wallet client. +#[cfg(feature = "walletrpc")] +pub type WalletKitClient = walletrpc::wallet_kit_client::WalletKitClient; + +/// Convenience type alias for peers service client. +#[cfg(feature = "peersrpc")] +pub type PeersClient = peersrpc::peers_client::PeersClient; + +/// Convenience type alias for versioner service client. +#[cfg(feature = "versionrpc")] +pub type VersionerClient = verrpc::versioner_client::VersionerClient; + +/// Convenience type alias for signer client. +#[cfg(feature = "signrpc")] +pub type SignerClient = signrpc::signer_client::SignerClient; + +/// Convenience type alias for router client. +#[cfg(feature = "routerrpc")] +pub type RouterClient = routerrpc::router_client::RouterClient; + +/// Convenience type alias for invoices client. +#[cfg(feature = "invoicesrpc")] +pub type InvoicesClient = invoicesrpc::invoices_client::InvoicesClient; + +/// Convenience type alias for state service client. +#[cfg(feature = "staterpc")] +pub type StateClient = staterpc::state_client::StateClient; + +/// The client returned by `connect` function +/// +/// This is a convenience type which you most likely want to use instead of raw client. +#[derive(Clone)] +pub struct Client { + #[cfg(feature = "lightningrpc")] + lightning: LightningClient, + #[cfg(feature = "walletrpc")] + wallet: WalletKitClient, + #[cfg(feature = "signrpc")] + signer: SignerClient, + #[cfg(feature = "peersrpc")] + peers: PeersClient, + #[cfg(feature = "versionrpc")] + version: VersionerClient, + #[cfg(feature = "routerrpc")] + router: RouterClient, + #[cfg(feature = "invoicesrpc")] + invoices: InvoicesClient, + #[cfg(feature = "staterpc")] + state: StateClient, +} + +impl Client { + /// Returns the lightning client. + #[cfg(feature = "lightningrpc")] + pub fn lightning(&mut self) -> &mut LightningClient { + &mut self.lightning + } + + /// Returns the wallet client. + #[cfg(feature = "walletrpc")] + pub fn wallet(&mut self) -> &mut WalletKitClient { + &mut self.wallet + } + + /// Returns the signer client. + #[cfg(feature = "signrpc")] + pub fn signer(&mut self) -> &mut SignerClient { + &mut self.signer + } + + /// Returns the versioner client. + #[cfg(feature = "versionrpc")] + pub fn versioner(&mut self) -> &mut VersionerClient { + &mut self.version + } + + /// Returns the peers client. + #[cfg(feature = "peersrpc")] + pub fn peers(&mut self) -> &mut PeersClient { + &mut self.peers + } + + /// Returns the router client. + #[cfg(feature = "routerrpc")] + pub fn router(&mut self) -> &mut RouterClient { + &mut self.router + } + + /// Returns the invoices client. + #[cfg(feature = "invoicesrpc")] + pub fn invoices(&mut self) -> &mut InvoicesClient { + &mut self.invoices + } + + /// Returns the state service client. + #[cfg(feature = "staterpc")] + pub fn state(&mut self) -> &mut StateClient { + &mut self.state + } +} + +/// [`tonic::Status`] is re-exported as `Error` for convenience. +pub type Error = tonic::Status; + +mod error; + +macro_rules! try_map_err { + ($result:expr, $mapfn:expr) => { + match $result { + Ok(value) => value, + Err(error) => return Err($mapfn(error).into()), + } + }; +} + +/// Messages and other types generated by `tonic`/`prost` +/// +/// This is the go-to module you will need to look in to find documentation on various message +/// types. However it may be better to start from methods on the [`LightningClient`](lnrpc::lightning_client::LightningClient) type. +#[cfg(feature = "lightningrpc")] +pub mod lnrpc { + tonic::include_proto!("lnrpc"); +} + +#[cfg(feature = "walletrpc")] +pub mod walletrpc { + tonic::include_proto!("walletrpc"); +} + +#[cfg(feature = "signrpc")] +pub mod signrpc { + tonic::include_proto!("signrpc"); +} + +#[cfg(feature = "peersrpc")] +pub mod peersrpc { + tonic::include_proto!("peersrpc"); +} + +#[cfg(feature = "routerrpc")] +pub mod routerrpc { + tonic::include_proto!("routerrpc"); +} + +#[cfg(feature = "versionrpc")] +pub mod verrpc { + tonic::include_proto!("verrpc"); +} + +#[cfg(feature = "invoicesrpc")] +pub mod invoicesrpc { + tonic::include_proto!("invoicesrpc"); +} + +#[cfg(feature = "staterpc")] +pub mod staterpc { + tonic::include_proto!("staterpc"); +} + +/// Supplies requests with macaroon +#[derive(Clone)] +pub struct MacaroonInterceptor { + macaroon: String, +} + +impl tonic::service::Interceptor for MacaroonInterceptor { + fn call(&mut self, mut request: tonic::Request<()>) -> Result, Error> { + request.metadata_mut().insert( + "macaroon", + tonic::metadata::MetadataValue::from_str(&self.macaroon) + .expect("hex produced non-ascii"), + ); + Ok(request) + } +} + +async fn load_macaroon( + path: impl AsRef + Into, +) -> Result { + let macaroon = + tokio::fs::read(&path) + .await + .map_err(|error| InternalConnectError::ReadFile { + file: path.into(), + error, + })?; + Ok(hex::encode(macaroon)) +} + +/// Connects to LND using given address and credentials +/// +/// This function does all required processing of the cert file and macaroon file, so that you +/// don't have to. The address must begin with "https://", though. +/// +/// This is considered the recommended way to connect to LND. An alternative function to use +/// already-read certificate or macaroon data is currently **not** provided to discourage such use. +/// LND occasionally changes that data which would lead to errors and in turn in worse application. +/// +/// If you have a motivating use case for use of direct data feel free to open an issue and +/// explain. +#[cfg_attr(feature = "tracing", tracing::instrument(name = "Connecting to LND"))] +pub async fn connect( + address: String, + cert_file: CP, + macaroon_file: MP, +) -> Result +where + CP: AsRef + Into + std::fmt::Debug, + MP: AsRef + Into + std::fmt::Debug, +{ + let connector = hyper_rustls::HttpsConnectorBuilder::new() + .with_tls_config(tls::config(cert_file).await?) + .https_or_http() + .enable_http2() + .build(); + let macaroon = load_macaroon(macaroon_file).await?; + + let svc = InterceptedService::new( + hyper::Client::builder().build(connector), + MacaroonInterceptor { macaroon }, + ); + let uri = + Uri::from_str(address.as_str()).map_err(|error| InternalConnectError::InvalidAddress { + address, + error: Box::new(error), + })?; + + let client = Client { + #[cfg(feature = "lightningrpc")] + lightning: lnrpc::lightning_client::LightningClient::with_origin(svc.clone(), uri.clone()), + #[cfg(feature = "walletrpc")] + wallet: walletrpc::wallet_kit_client::WalletKitClient::with_origin( + svc.clone(), + uri.clone(), + ), + #[cfg(feature = "peersrpc")] + peers: peersrpc::peers_client::PeersClient::with_origin(svc.clone(), uri.clone()), + #[cfg(feature = "signrpc")] + signer: signrpc::signer_client::SignerClient::with_origin(svc.clone(), uri.clone()), + #[cfg(feature = "versionrpc")] + version: verrpc::versioner_client::VersionerClient::with_origin(svc.clone(), uri.clone()), + #[cfg(feature = "routerrpc")] + router: routerrpc::router_client::RouterClient::with_origin(svc.clone(), uri.clone()), + #[cfg(feature = "invoicesrpc")] + invoices: invoicesrpc::invoices_client::InvoicesClient::with_origin( + svc.clone(), + uri.clone(), + ), + #[cfg(feature = "staterpc")] + state: staterpc::state_client::StateClient::with_origin(svc.clone(), uri.clone()), + }; + Ok(client) +} + +mod tls { + use crate::error::{ConnectError, InternalConnectError}; + use rustls::{ ClientConfig, Error as TLSError}; + use rustls::client::danger::{ServerCertVerified, ServerCertVerifier}; + use rustls::pki_types::ServerName; + + use std::{ + path::{Path, PathBuf}, + sync::Arc, + time::SystemTime, + }; + + pub(crate) async fn config( + path: impl AsRef + Into, + ) -> Result { + Ok(ClientConfig::builder() + .with_safe_defaults() + .with_custom_certificate_verifier(Arc::new(CertVerifier::load(path).await?)) + .with_no_client_auth()) + } + + pub(crate) struct CertVerifier { + certs: Vec>, + } + + impl CertVerifier { + pub(crate) async fn load( + path: impl AsRef + Into, + ) -> Result { + let contents = try_map_err!(tokio::fs::read(&path).await, |error| { + InternalConnectError::ReadFile { + file: path.into(), + error, + } + }); + let mut reader = &*contents; + + let certs = try_map_err!(rustls_pemfile::certs(&mut reader), |error| { + InternalConnectError::ParseCert { + file: path.into(), + error, + } + }); + + Ok(CertVerifier { certs }) + } + } + + impl ServerCertVerifier for CertVerifier { + fn verify_server_cert( + &self, + end_entity: &Certificate, + intermediates: &[Certificate], + _server_name: &ServerName, + _scts: &mut dyn Iterator, + _ocsp_response: &[u8], + _now: SystemTime, + ) -> Result { + let mut certs = intermediates + .iter() + .map(|c| c.0.clone()) + .collect::>>(); + certs.push(end_entity.0.clone()); + certs.sort(); + + let mut our_certs = self.certs.clone(); + our_certs.sort(); + + if self.certs.len() != certs.len() { + return Err(TLSError::General(format!( + "Mismatched number of certificates (Expected: {}, Presented: {})", + self.certs.len(), + certs.len() + ))); + } + for (c, p) in our_certs.iter().zip(certs.iter()) { + if *p != *c { + return Err(TLSError::General( + "Server certificates do not match ours".to_string(), + )); + } + } + Ok(ServerCertVerified::assertion()) + } + } +} diff --git a/vendor/invoicesrpc/invoices.proto b/vendor/invoicesrpc/invoices.proto index d5f327d..7d1ada2 100644 --- a/vendor/invoicesrpc/invoices.proto +++ b/vendor/invoicesrpc/invoices.proto @@ -1,175 +1,175 @@ -syntax = "proto3"; - -import "lightning.proto"; - -package invoicesrpc; - -option go_package = "github.com/lightningnetwork/lnd/lnrpc/invoicesrpc"; - -// Invoices is a service that can be used to create, accept, settle and cancel -// invoices. -service Invoices { - /* - SubscribeSingleInvoice returns a uni-directional stream (server -> client) - to notify the client of state transitions of the specified invoice. - Initially the current invoice state is always sent out. - */ - rpc SubscribeSingleInvoice (SubscribeSingleInvoiceRequest) - returns (stream lnrpc.Invoice); - - /* - 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); - - /* - AddHoldInvoice creates a hold invoice. It ties the invoice to the hash - supplied in the request. - */ - rpc AddHoldInvoice (AddHoldInvoiceRequest) returns (AddHoldInvoiceResp); - - /* - SettleInvoice settles an accepted invoice. If the invoice is already - settled, this call will succeed. - */ - rpc SettleInvoice (SettleInvoiceMsg) returns (SettleInvoiceResp); - - /* - LookupInvoiceV2 attempts to look up at invoice. An invoice can be refrenced - using either its payment hash, payment address, or set ID. - */ - rpc LookupInvoiceV2 (LookupInvoiceMsg) returns (lnrpc.Invoice); -} - -message CancelInvoiceMsg { - // Hash corresponding to the (hold) invoice to cancel. When using - // REST, this field must be encoded as base64. - bytes payment_hash = 1; -} -message CancelInvoiceResp { -} - -message AddHoldInvoiceRequest { - /* - An optional memo to attach along with the invoice. Used for record keeping - purposes for the invoice's creator, and will also be set in the description - field of the encoded payment request if the description_hash field is not - being used. - */ - string memo = 1; - - // The hash of the preimage - bytes hash = 2; - - /* - The value of this invoice in satoshis - - The fields value and value_msat are mutually exclusive. - */ - int64 value = 3; - - /* - The value of this invoice in millisatoshis - - The fields value and value_msat are mutually exclusive. - */ - int64 value_msat = 10; - - /* - Hash (SHA-256) of a description of the payment. Used if the description of - payment (memo) is too long to naturally fit within the description field - of an encoded payment request. - */ - bytes description_hash = 4; - - // Payment request expiry time in seconds. Default is 86400 (24 hours). - int64 expiry = 5; - - // Fallback on-chain address. - string fallback_addr = 6; - - // Delta to use for the time-lock of the CLTV extended to the final hop. - uint64 cltv_expiry = 7; - - /* - Route hints that can each be individually used to assist in reaching the - invoice's destination. - */ - repeated lnrpc.RouteHint route_hints = 8; - - // Whether this invoice should include routing hints for private channels. - bool private = 9; -} - -message AddHoldInvoiceResp { - /* - A bare-bones invoice for a payment within the Lightning Network. With the - details of the invoice, the sender has all the data necessary to send a - payment to the recipient. - */ - string payment_request = 1; - - /* - The "add" index of this invoice. Each newly created invoice will increment - this index making it monotonically increasing. Callers to the - SubscribeInvoices call can use this to instantly get notified of all added - invoices with an add_index greater than this one. - */ - uint64 add_index = 2; - - /* - The payment address of the generated invoice. This value should be used - in all payments for this invoice as we require it for end to end - security. - */ - bytes payment_addr = 3; -} - -message SettleInvoiceMsg { - // Externally discovered pre-image that should be used to settle the hold - // invoice. - bytes preimage = 1; -} - -message SettleInvoiceResp { -} - -message SubscribeSingleInvoiceRequest { - reserved 1; - - // Hash corresponding to the (hold) invoice to subscribe to. When using - // REST, this field must be encoded as base64url. - bytes r_hash = 2; -} - -enum LookupModifier { - // The default look up modifier, no look up behavior is changed. - DEFAULT = 0; - - /* - Indicates that when a look up is done based on a set_id, then only that set - of HTLCs related to that set ID should be returned. - */ - HTLC_SET_ONLY = 1; - - /* - Indicates that when a look up is done using a payment_addr, then no HTLCs - related to the payment_addr should be returned. This is useful when one - wants to be able to obtain the set of associated setIDs with a given - invoice, then look up the sub-invoices "projected" by that set ID. - */ - HTLC_SET_BLANK = 2; -} - -message LookupInvoiceMsg { - oneof invoice_ref { - // When using REST, this field must be encoded as base64. - bytes payment_hash = 1; - bytes payment_addr = 2; - bytes set_id = 3; - } - - LookupModifier lookup_modifier = 4; +syntax = "proto3"; + +import "lightning.proto"; + +package invoicesrpc; + +option go_package = "github.com/lightningnetwork/lnd/lnrpc/invoicesrpc"; + +// Invoices is a service that can be used to create, accept, settle and cancel +// invoices. +service Invoices { + /* + SubscribeSingleInvoice returns a uni-directional stream (server -> client) + to notify the client of state transitions of the specified invoice. + Initially the current invoice state is always sent out. + */ + rpc SubscribeSingleInvoice (SubscribeSingleInvoiceRequest) + returns (stream lnrpc.Invoice); + + /* + 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); + + /* + AddHoldInvoice creates a hold invoice. It ties the invoice to the hash + supplied in the request. + */ + rpc AddHoldInvoice (AddHoldInvoiceRequest) returns (AddHoldInvoiceResp); + + /* + SettleInvoice settles an accepted invoice. If the invoice is already + settled, this call will succeed. + */ + rpc SettleInvoice (SettleInvoiceMsg) returns (SettleInvoiceResp); + + /* + LookupInvoiceV2 attempts to look up at invoice. An invoice can be refrenced + using either its payment hash, payment address, or set ID. + */ + rpc LookupInvoiceV2 (LookupInvoiceMsg) returns (lnrpc.Invoice); +} + +message CancelInvoiceMsg { + // Hash corresponding to the (hold) invoice to cancel. When using + // REST, this field must be encoded as base64. + bytes payment_hash = 1; +} +message CancelInvoiceResp { +} + +message AddHoldInvoiceRequest { + /* + An optional memo to attach along with the invoice. Used for record keeping + purposes for the invoice's creator, and will also be set in the description + field of the encoded payment request if the description_hash field is not + being used. + */ + string memo = 1; + + // The hash of the preimage + bytes hash = 2; + + /* + The value of this invoice in satoshis + + The fields value and value_msat are mutually exclusive. + */ + int64 value = 3; + + /* + The value of this invoice in millisatoshis + + The fields value and value_msat are mutually exclusive. + */ + int64 value_msat = 10; + + /* + Hash (SHA-256) of a description of the payment. Used if the description of + payment (memo) is too long to naturally fit within the description field + of an encoded payment request. + */ + bytes description_hash = 4; + + // Payment request expiry time in seconds. Default is 86400 (24 hours). + int64 expiry = 5; + + // Fallback on-chain address. + string fallback_addr = 6; + + // Delta to use for the time-lock of the CLTV extended to the final hop. + uint64 cltv_expiry = 7; + + /* + Route hints that can each be individually used to assist in reaching the + invoice's destination. + */ + repeated lnrpc.RouteHint route_hints = 8; + + // Whether this invoice should include routing hints for private channels. + bool private = 9; +} + +message AddHoldInvoiceResp { + /* + A bare-bones invoice for a payment within the Lightning Network. With the + details of the invoice, the sender has all the data necessary to send a + payment to the recipient. + */ + string payment_request = 1; + + /* + The "add" index of this invoice. Each newly created invoice will increment + this index making it monotonically increasing. Callers to the + SubscribeInvoices call can use this to instantly get notified of all added + invoices with an add_index greater than this one. + */ + uint64 add_index = 2; + + /* + The payment address of the generated invoice. This value should be used + in all payments for this invoice as we require it for end to end + security. + */ + bytes payment_addr = 3; +} + +message SettleInvoiceMsg { + // Externally discovered pre-image that should be used to settle the hold + // invoice. + bytes preimage = 1; +} + +message SettleInvoiceResp { +} + +message SubscribeSingleInvoiceRequest { + reserved 1; + + // Hash corresponding to the (hold) invoice to subscribe to. When using + // REST, this field must be encoded as base64url. + bytes r_hash = 2; +} + +enum LookupModifier { + // The default look up modifier, no look up behavior is changed. + DEFAULT = 0; + + /* + Indicates that when a look up is done based on a set_id, then only that set + of HTLCs related to that set ID should be returned. + */ + HTLC_SET_ONLY = 1; + + /* + Indicates that when a look up is done using a payment_addr, then no HTLCs + related to the payment_addr should be returned. This is useful when one + wants to be able to obtain the set of associated setIDs with a given + invoice, then look up the sub-invoices "projected" by that set ID. + */ + HTLC_SET_BLANK = 2; +} + +message LookupInvoiceMsg { + oneof invoice_ref { + // When using REST, this field must be encoded as base64. + bytes payment_hash = 1; + bytes payment_addr = 2; + bytes set_id = 3; + } + + LookupModifier lookup_modifier = 4; } \ No newline at end of file diff --git a/vendor/lightning.proto b/vendor/lightning.proto index b1716e3..85fac36 100644 --- a/vendor/lightning.proto +++ b/vendor/lightning.proto @@ -1,4593 +1,4593 @@ -syntax = "proto3"; - -package lnrpc; - -option go_package = "github.com/lightningnetwork/lnd/lnrpc"; - -/* - * 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 - */ - -// Lightning is the main RPC server of the daemon. -service Lightning { - /* lncli: `walletbalance` - WalletBalance returns total unspent outputs(confirmed and unconfirmed), all - confirmed unspent outputs and all unconfirmed unspent outputs under control - of the wallet. - */ - rpc WalletBalance (WalletBalanceRequest) returns (WalletBalanceResponse); - - /* lncli: `channelbalance` - ChannelBalance returns a report on the total funds across all open channels, - categorized in local/remote, pending local/remote and unsettled local/remote - balances. - */ - rpc ChannelBalance (ChannelBalanceRequest) returns (ChannelBalanceResponse); - - /* lncli: `listchaintxns` - GetTransactions returns a list describing all the known transactions - relevant to the wallet. - */ - rpc GetTransactions (GetTransactionsRequest) returns (TransactionDetails); - - /* lncli: `estimatefee` - EstimateFee asks the chain backend to estimate the fee rate and total fees - for a transaction that pays to multiple specified outputs. - - When using REST, the `AddrToAmount` map type can be set by appending - `&AddrToAmount[
]=` to the URL. Unfortunately this - map type doesn't appear in the REST API documentation because of a bug in - the grpc-gateway library. - */ - rpc EstimateFee (EstimateFeeRequest) returns (EstimateFeeResponse); - - /* lncli: `sendcoins` - SendCoins executes a request to send coins to a particular address. Unlike - SendMany, this RPC call only allows creating a single output at a time. If - neither target_conf, or sat_per_vbyte are set, then the internal wallet will - consult its fee model to determine a fee for the default confirmation - target. - */ - rpc SendCoins (SendCoinsRequest) returns (SendCoinsResponse); - - /* lncli: `listunspent` - Deprecated, use walletrpc.ListUnspent instead. - - ListUnspent returns a list of all utxos spendable by the wallet with a - number of confirmations between the specified minimum and maximum. - */ - rpc ListUnspent (ListUnspentRequest) returns (ListUnspentResponse); - - /* - SubscribeTransactions creates a uni-directional stream from the server to - the client in which any newly discovered transactions relevant to the - wallet are sent over. - */ - rpc SubscribeTransactions (GetTransactionsRequest) - returns (stream Transaction); - - /* lncli: `sendmany` - SendMany handles a request for a transaction that creates multiple specified - outputs in parallel. If neither target_conf, or sat_per_vbyte are set, then - the internal wallet will consult its fee model to determine a fee for the - default confirmation target. - */ - rpc SendMany (SendManyRequest) returns (SendManyResponse); - - /* lncli: `newaddress` - NewAddress creates a new address under control of the local wallet. - */ - rpc NewAddress (NewAddressRequest) returns (NewAddressResponse); - - /* lncli: `signmessage` - SignMessage signs a message with this node's private key. The returned - signature string is `zbase32` encoded and pubkey recoverable, meaning that - only the message digest and signature are needed for verification. - */ - rpc SignMessage (SignMessageRequest) returns (SignMessageResponse); - - /* lncli: `verifymessage` - VerifyMessage verifies a signature over a msg. The signature must be - zbase32 encoded and signed by an active node in the resident node's - channel database. In addition to returning the validity of the signature, - VerifyMessage also returns the recovered pubkey from the signature. - */ - rpc VerifyMessage (VerifyMessageRequest) returns (VerifyMessageResponse); - - /* lncli: `connect` - ConnectPeer attempts to establish a connection to a remote peer. This is at - the networking level, and is used for communication between nodes. This is - distinct from establishing a channel with a peer. - */ - rpc ConnectPeer (ConnectPeerRequest) returns (ConnectPeerResponse); - - /* lncli: `disconnect` - DisconnectPeer attempts to disconnect one peer from another identified by a - given pubKey. In the case that we currently have a pending or active channel - with the target peer, then this action will be not be allowed. - */ - rpc DisconnectPeer (DisconnectPeerRequest) returns (DisconnectPeerResponse); - - /* lncli: `listpeers` - ListPeers returns a verbose listing of all currently active peers. - */ - rpc ListPeers (ListPeersRequest) returns (ListPeersResponse); - - /* - SubscribePeerEvents creates a uni-directional stream from the server to - the client in which any events relevant to the state of peers are sent - over. Events include peers going online and offline. - */ - rpc SubscribePeerEvents (PeerEventSubscription) returns (stream PeerEvent); - - /* lncli: `getinfo` - GetInfo returns general information concerning the lightning node including - it's identity pubkey, alias, the chains it is connected to, and information - concerning the number of open+pending channels. - */ - rpc GetInfo (GetInfoRequest) returns (GetInfoResponse); - - /** lncli: `getrecoveryinfo` - GetRecoveryInfo returns information concerning the recovery mode including - whether it's in a recovery mode, whether the recovery is finished, and the - progress made so far. - */ - rpc GetRecoveryInfo (GetRecoveryInfoRequest) - returns (GetRecoveryInfoResponse); - - // TODO(roasbeef): merge with below with bool? - /* lncli: `pendingchannels` - PendingChannels returns a list of all the channels that are currently - considered "pending". A channel is pending if it has finished the funding - workflow and is waiting for confirmations for the funding txn, or is in the - process of closure, either initiated cooperatively or non-cooperatively. - */ - rpc PendingChannels (PendingChannelsRequest) - returns (PendingChannelsResponse); - - /* lncli: `listchannels` - ListChannels returns a description of all the open channels that this node - is a participant in. - */ - rpc ListChannels (ListChannelsRequest) returns (ListChannelsResponse); - - /* - SubscribeChannelEvents creates a uni-directional stream from the server to - the client in which any updates relevant to the state of the channels are - sent over. Events include new active channels, inactive channels, and closed - channels. - */ - rpc SubscribeChannelEvents (ChannelEventSubscription) - returns (stream ChannelEventUpdate); - - /* lncli: `closedchannels` - ClosedChannels returns a description of all the closed channels that - this node was a participant in. - */ - rpc ClosedChannels (ClosedChannelsRequest) returns (ClosedChannelsResponse); - - /* - OpenChannelSync is a synchronous version of the OpenChannel RPC call. This - call is meant to be consumed by clients to the REST proxy. As with all - other sync calls, all byte slices are intended to be populated as hex - encoded strings. - */ - rpc OpenChannelSync (OpenChannelRequest) returns (ChannelPoint); - - /* lncli: `openchannel` - OpenChannel attempts to open a singly funded channel specified in the - request to a remote peer. Users are able to specify a target number of - blocks that the funding transaction should be confirmed in, or a manual fee - rate to us for the funding transaction. If neither are specified, then a - lax block confirmation target is used. Each OpenStatusUpdate will return - the pending channel ID of the in-progress channel. Depending on the - arguments specified in the OpenChannelRequest, this pending channel ID can - then be used to manually progress the channel funding flow. - */ - rpc OpenChannel (OpenChannelRequest) returns (stream OpenStatusUpdate); - - /* lncli: `batchopenchannel` - BatchOpenChannel attempts to open multiple single-funded channels in a - single transaction in an atomic way. This means either all channel open - requests succeed at once or all attempts are aborted if any of them fail. - This is the safer variant of using PSBTs to manually fund a batch of - channels through the OpenChannel RPC. - */ - rpc BatchOpenChannel (BatchOpenChannelRequest) - returns (BatchOpenChannelResponse); - - /* - FundingStateStep is an advanced funding related call that allows the caller - to either execute some preparatory steps for a funding workflow, or - manually progress a funding workflow. The primary way a funding flow is - identified is via its pending channel ID. As an example, this method can be - used to specify that we're expecting a funding flow for a particular - pending channel ID, for which we need to use specific parameters. - Alternatively, this can be used to interactively drive PSBT signing for - funding for partially complete funding transactions. - */ - rpc FundingStateStep (FundingTransitionMsg) returns (FundingStateStepResp); - - /* - ChannelAcceptor dispatches a bi-directional streaming RPC in which - OpenChannel requests are sent to the client and the client responds with - a boolean that tells LND whether or not to accept the channel. This allows - node operators to specify their own criteria for accepting inbound channels - through a single persistent connection. - */ - rpc ChannelAcceptor (stream ChannelAcceptResponse) - returns (stream ChannelAcceptRequest); - - /* lncli: `closechannel` - CloseChannel attempts to close an active channel identified by its channel - outpoint (ChannelPoint). The actions of this method can additionally be - augmented to attempt a force close after a timeout period in the case of an - inactive peer. If a non-force close (cooperative closure) is requested, - then the user can specify either a target number of blocks until the - closure transaction is confirmed, or a manual fee rate. If neither are - specified, then a default lax, block confirmation target is used. - */ - rpc CloseChannel (CloseChannelRequest) returns (stream CloseStatusUpdate); - - /* lncli: `abandonchannel` - AbandonChannel removes all channel state from the database except for a - close summary. This method can be used to get rid of permanently unusable - channels due to bugs fixed in newer versions of lnd. This method can also be - used to remove externally funded channels where the funding transaction was - never broadcast. Only available for non-externally funded channels in dev - build. - */ - rpc AbandonChannel (AbandonChannelRequest) returns (AbandonChannelResponse); - - /* lncli: `sendpayment` - Deprecated, use routerrpc.SendPaymentV2. SendPayment dispatches a - bi-directional streaming RPC for sending payments through the Lightning - Network. A single RPC invocation creates a persistent bi-directional - stream allowing clients to rapidly send payments through the Lightning - Network with a single persistent connection. - */ - rpc SendPayment (stream SendRequest) returns (stream SendResponse) { - option deprecated = true; - } - - /* - SendPaymentSync is the synchronous non-streaming version of SendPayment. - This RPC is intended to be consumed by clients of the REST proxy. - Additionally, this RPC expects the destination's public key and the payment - hash (if any) to be encoded as hex strings. - */ - rpc SendPaymentSync (SendRequest) returns (SendResponse); - - /* lncli: `sendtoroute` - Deprecated, use routerrpc.SendToRouteV2. SendToRoute is a bi-directional - streaming RPC for sending payment through the Lightning Network. This - method differs from SendPayment in that it allows users to specify a full - route manually. This can be used for things like rebalancing, and atomic - swaps. - */ - rpc SendToRoute (stream SendToRouteRequest) returns (stream SendResponse) { - option deprecated = true; - } - - /* - SendToRouteSync is a synchronous version of SendToRoute. It Will block - until the payment either fails or succeeds. - */ - rpc SendToRouteSync (SendToRouteRequest) returns (SendResponse); - - /* lncli: `addinvoice` - AddInvoice attempts to add a new invoice to the invoice database. Any - duplicated invoices are rejected, therefore all invoices *must* have a - unique payment preimage. - */ - rpc AddInvoice (Invoice) returns (AddInvoiceResponse); - - /* lncli: `listinvoices` - ListInvoices returns a list of all the invoices currently stored within the - database. Any active debug invoices are ignored. It has full support for - paginated responses, allowing users to query for specific invoices through - their add_index. This can be done by using either the first_index_offset or - last_index_offset fields included in the response as the index_offset of the - next request. By default, the first 100 invoices created will be returned. - Backwards pagination is also supported through the Reversed flag. - */ - rpc ListInvoices (ListInvoiceRequest) returns (ListInvoiceResponse); - - /* lncli: `lookupinvoice` - LookupInvoice attempts to look up an invoice according to its payment hash. - The passed payment hash *must* be exactly 32 bytes, if not, an error is - returned. - */ - rpc LookupInvoice (PaymentHash) returns (Invoice); - - /* - SubscribeInvoices returns a uni-directional stream (server -> client) for - notifying the client of newly added/settled invoices. The caller can - optionally specify the add_index and/or the settle_index. If the add_index - is specified, then we'll first start by sending add invoice events for all - invoices with an add_index greater than the specified value. If the - settle_index is specified, the next, we'll send out all settle events for - invoices with a settle_index greater than the specified value. One or both - of these fields can be set. If no fields are set, then we'll only send out - the latest add/settle events. - */ - rpc SubscribeInvoices (InvoiceSubscription) returns (stream Invoice); - - /* lncli: `decodepayreq` - DecodePayReq takes an encoded payment request string and attempts to decode - it, returning a full description of the conditions encoded within the - payment request. - */ - rpc DecodePayReq (PayReqString) returns (PayReq); - - /* lncli: `listpayments` - ListPayments returns a list of all outgoing payments. - */ - rpc ListPayments (ListPaymentsRequest) returns (ListPaymentsResponse); - - /* - 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); - - /* - DeleteAllPayments deletes all outgoing payments from DB. Note that it will - not attempt to delete In-Flight payments, since that would be unsafe. - */ - rpc DeleteAllPayments (DeleteAllPaymentsRequest) - returns (DeleteAllPaymentsResponse); - - /* lncli: `describegraph` - DescribeGraph returns a description of the latest graph state from the - point of view of the node. The graph information is partitioned into two - components: all the nodes/vertexes, and all the edges that connect the - vertexes themselves. As this is a directed graph, the edges also contain - the node directional specific routing policy which includes: the time lock - delta, fee information, etc. - */ - rpc DescribeGraph (ChannelGraphRequest) returns (ChannelGraph); - - /* lncli: `getnodemetrics` - GetNodeMetrics returns node metrics calculated from the graph. Currently - the only supported metric is betweenness centrality of individual nodes. - */ - rpc GetNodeMetrics (NodeMetricsRequest) returns (NodeMetricsResponse); - - /* lncli: `getchaninfo` - GetChanInfo returns the latest authenticated network announcement for the - given channel identified by its channel ID: an 8-byte integer which - uniquely identifies the location of transaction's funding output within the - blockchain. - */ - rpc GetChanInfo (ChanInfoRequest) returns (ChannelEdge); - - /* lncli: `getnodeinfo` - GetNodeInfo returns the latest advertised, aggregated, and authenticated - channel information for the specified node identified by its public key. - */ - rpc GetNodeInfo (NodeInfoRequest) returns (NodeInfo); - - /* lncli: `queryroutes` - QueryRoutes attempts to query the daemon's Channel Router for a possible - route to a target destination capable of carrying a specific amount of - satoshis. The returned route contains the full details required to craft and - send an HTLC, also including the necessary information that should be - present within the Sphinx packet encapsulated within the HTLC. - - When using REST, the `dest_custom_records` map type can be set by appending - `&dest_custom_records[]=` - to the URL. Unfortunately this map type doesn't appear in the REST API - documentation because of a bug in the grpc-gateway library. - */ - rpc QueryRoutes (QueryRoutesRequest) returns (QueryRoutesResponse); - - /* lncli: `getnetworkinfo` - GetNetworkInfo returns some basic stats about the known channel graph from - the point of view of the node. - */ - rpc GetNetworkInfo (NetworkInfoRequest) returns (NetworkInfo); - - /* lncli: `stop` - StopDaemon will send a shutdown request to the interrupt handler, triggering - a graceful shutdown of the daemon. - */ - rpc StopDaemon (StopRequest) returns (StopResponse); - - /* - SubscribeChannelGraph launches a streaming RPC that allows the caller to - receive notifications upon any changes to the channel graph topology from - the point of view of the responding node. Events notified include: new - nodes coming online, nodes updating their authenticated attributes, new - channels being advertised, updates in the routing policy for a directional - channel edge, and when channels are closed on-chain. - */ - rpc SubscribeChannelGraph (GraphTopologySubscription) - returns (stream GraphTopologyUpdate); - - /* lncli: `debuglevel` - DebugLevel allows a caller to programmatically set the logging verbosity of - lnd. The logging can be targeted according to a coarse daemon-wide logging - level, or in a granular fashion to specify the logging for a target - sub-system. - */ - rpc DebugLevel (DebugLevelRequest) returns (DebugLevelResponse); - - /* lncli: `feereport` - FeeReport allows the caller to obtain a report detailing the current fee - schedule enforced by the node globally for each channel. - */ - rpc FeeReport (FeeReportRequest) returns (FeeReportResponse); - - /* lncli: `updatechanpolicy` - UpdateChannelPolicy allows the caller to update the fee schedule and - channel policies for all channels globally, or a particular channel. - */ - rpc UpdateChannelPolicy (PolicyUpdateRequest) - returns (PolicyUpdateResponse); - - /* lncli: `fwdinghistory` - ForwardingHistory allows the caller to query the htlcswitch for a record of - all HTLCs forwarded within the target time range, and integer offset - within that time range, for a maximum number of events. If no maximum number - of events is specified, up to 100 events will be returned. If no time-range - is specified, then events will be returned in the order that they occured. - - A list of forwarding events are returned. The size of each forwarding event - is 40 bytes, and the max message size able to be returned in gRPC is 4 MiB. - As a result each message can only contain 50k entries. Each response has - the index offset of the last entry. The index offset can be provided to the - request to allow the caller to skip a series of records. - */ - rpc ForwardingHistory (ForwardingHistoryRequest) - returns (ForwardingHistoryResponse); - - /* lncli: `exportchanbackup` - ExportChannelBackup attempts to return an encrypted static channel backup - for the target channel identified by it channel point. The backup is - encrypted with a key generated from the aezeed seed of the user. The - returned backup can either be restored using the RestoreChannelBackup - method once lnd is running, or via the InitWallet and UnlockWallet methods - from the WalletUnlocker service. - */ - rpc ExportChannelBackup (ExportChannelBackupRequest) - returns (ChannelBackup); - - /* - ExportAllChannelBackups returns static channel backups for all existing - channels known to lnd. A set of regular singular static channel backups for - each channel are returned. Additionally, a multi-channel backup is returned - as well, which contains a single encrypted blob containing the backups of - each channel. - */ - rpc ExportAllChannelBackups (ChanBackupExportRequest) - returns (ChanBackupSnapshot); - - /* - 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. - */ - rpc VerifyChanBackup (ChanBackupSnapshot) - returns (VerifyChanBackupResponse); - - /* lncli: `restorechanbackup` - RestoreChannelBackups accepts a set of singular channel backups, or a - single encrypted multi-chan backup and attempts to recover any funds - remaining within the channel. If we are able to unpack the backup, then the - new channel will be shown under listchannels, as well as pending channels. - */ - rpc RestoreChannelBackups (RestoreChanBackupRequest) - returns (RestoreBackupResponse); - - /* - SubscribeChannelBackups allows a client to sub-subscribe to the most up to - date information concerning the state of all channel backups. Each time a - new channel is added, we return the new set of channels, along with a - multi-chan backup containing the backup info for all channels. Each time a - channel is closed, we send a new update, which contains new new chan back - ups, but the updated set of encrypted multi-chan backups with the closed - channel(s) removed. - */ - rpc SubscribeChannelBackups (ChannelBackupSubscription) - returns (stream ChanBackupSnapshot); - - /* lncli: `bakemacaroon` - BakeMacaroon allows the creation of a new macaroon with custom read and - write permissions. No first-party caveats are added since this can be done - offline. - */ - rpc BakeMacaroon (BakeMacaroonRequest) returns (BakeMacaroonResponse); - - /* lncli: `listmacaroonids` - ListMacaroonIDs returns all root key IDs that are in use. - */ - rpc ListMacaroonIDs (ListMacaroonIDsRequest) - returns (ListMacaroonIDsResponse); - - /* lncli: `deletemacaroonid` - DeleteMacaroonID deletes the specified macaroon ID and invalidates all - macaroons derived from that ID. - */ - rpc DeleteMacaroonID (DeleteMacaroonIDRequest) - returns (DeleteMacaroonIDResponse); - - /* lncli: `listpermissions` - ListPermissions lists all RPC method URIs and their required macaroon - permissions to access them. - */ - rpc ListPermissions (ListPermissionsRequest) - returns (ListPermissionsResponse); - - /* - CheckMacaroonPermissions checks whether a request follows the constraints - imposed on the macaroon and that the macaroon is authorized to follow the - provided permissions. - */ - rpc CheckMacaroonPermissions (CheckMacPermRequest) - returns (CheckMacPermResponse); - - /* - RegisterRPCMiddleware adds a new gRPC middleware to the interceptor chain. A - gRPC middleware is software component external to lnd that aims to add - additional business logic to lnd by observing/intercepting/validating - incoming gRPC client requests and (if needed) replacing/overwriting outgoing - messages before they're sent to the client. When registering the middleware - must identify itself and indicate what custom macaroon caveats it wants to - be responsible for. Only requests that contain a macaroon with that specific - custom caveat are then sent to the middleware for inspection. The other - option is to register for the read-only mode in which all requests/responses - are forwarded for interception to the middleware but the middleware is not - allowed to modify any responses. As a security measure, _no_ middleware can - modify responses for requests made with _unencumbered_ macaroons! - */ - rpc RegisterRPCMiddleware (stream RPCMiddlewareResponse) - returns (stream RPCMiddlewareRequest); - - /* lncli: `sendcustom` - SendCustomMessage sends a custom peer message. - */ - rpc SendCustomMessage (SendCustomMessageRequest) - returns (SendCustomMessageResponse); - - /* lncli: `subscribecustom` - SubscribeCustomMessages subscribes to a stream of incoming custom peer - messages. - */ - rpc SubscribeCustomMessages (SubscribeCustomMessagesRequest) - returns (stream CustomMessage); - - /* lncli: `listaliases` - ListAliases returns the set of all aliases that have ever existed with - their confirmed SCID (if it exists) and/or the base SCID (in the case of - zero conf). - */ - rpc ListAliases (ListAliasesRequest) returns (ListAliasesResponse); -} - -message SubscribeCustomMessagesRequest { -} - -message CustomMessage { - // Peer from which the message originates - bytes peer = 1; - - // Message type. This value will be in the custom range (>= 32768). - uint32 type = 2; - - // Raw message data - bytes data = 3; -} - -message SendCustomMessageRequest { - // Peer to send the message to - bytes peer = 1; - - // Message type. This value needs to be in the custom range (>= 32768). - uint32 type = 2; - - // Raw message data. - bytes data = 3; -} - -message SendCustomMessageResponse { -} - -message Utxo { - // The type of address - AddressType address_type = 1; - - // The address - string address = 2; - - // The value of the unspent coin in satoshis - int64 amount_sat = 3; - - // The pkscript in hex - string pk_script = 4; - - // The outpoint in format txid:n - OutPoint outpoint = 5; - - // The number of confirmations for the Utxo - int64 confirmations = 6; -} - -enum OutputScriptType { - SCRIPT_TYPE_PUBKEY_HASH = 0; - SCRIPT_TYPE_SCRIPT_HASH = 1; - SCRIPT_TYPE_WITNESS_V0_PUBKEY_HASH = 2; - SCRIPT_TYPE_WITNESS_V0_SCRIPT_HASH = 3; - SCRIPT_TYPE_PUBKEY = 4; - SCRIPT_TYPE_MULTISIG = 5; - SCRIPT_TYPE_NULLDATA = 6; - SCRIPT_TYPE_NON_STANDARD = 7; - SCRIPT_TYPE_WITNESS_UNKNOWN = 8; -} - -message OutputDetail { - // The type of the output - OutputScriptType output_type = 1; - - // The address - string address = 2; - - // The pkscript in hex - string pk_script = 3; - - // The output index used in the raw transaction - int64 output_index = 4; - - // The value of the output coin in satoshis - int64 amount = 5; - - // Denotes if the output is controlled by the internal wallet - bool is_our_address = 6; -} - -message Transaction { - // The transaction hash - string tx_hash = 1; - - // The transaction amount, denominated in satoshis - int64 amount = 2; - - // The number of confirmations - int32 num_confirmations = 3; - - // The hash of the block this transaction was included in - string block_hash = 4; - - // The height of the block this transaction was included in - int32 block_height = 5; - - // Timestamp of this transaction - int64 time_stamp = 6; - - // Fees paid for this transaction - int64 total_fees = 7; - - // Addresses that received funds for this transaction. Deprecated as it is - // now incorporated in the output_details field. - repeated string dest_addresses = 8 [deprecated = true]; - - // Outputs that received funds for this transaction - repeated OutputDetail output_details = 11; - - // The raw transaction hex. - string raw_tx_hex = 9; - - // A label that was optionally set on transaction broadcast. - string label = 10; - - // PreviousOutpoints/Inputs of this transaction. - repeated PreviousOutPoint previous_outpoints = 12; -} - -message GetTransactionsRequest { - /* - The height from which to list transactions, inclusive. If this value is - greater than end_height, transactions will be read in reverse. - */ - int32 start_height = 1; - - /* - The height until which to list transactions, inclusive. To include - unconfirmed transactions, this value should be set to -1, which will - return transactions from start_height until the current chain tip and - unconfirmed transactions. If no end_height is provided, the call will - default to this option. - */ - int32 end_height = 2; - - // An optional filter to only include transactions relevant to an account. - string account = 3; -} - -message TransactionDetails { - // The list of transactions relevant to the wallet. - repeated Transaction transactions = 1; -} - -message FeeLimit { - oneof limit { - /* - The fee limit expressed as a fixed amount of satoshis. - - The fields fixed and fixed_msat are mutually exclusive. - */ - int64 fixed = 1; - - /* - The fee limit expressed as a fixed amount of millisatoshis. - - The fields fixed and fixed_msat are mutually exclusive. - */ - int64 fixed_msat = 3; - - // The fee limit expressed as a percentage of the payment amount. - int64 percent = 2; - } -} - -message SendRequest { - /* - The identity pubkey of the payment recipient. When using REST, this field - must be encoded as base64. - */ - bytes dest = 1; - - /* - The hex-encoded identity pubkey of the payment recipient. Deprecated now - that the REST gateway supports base64 encoding of bytes fields. - */ - string dest_string = 2 [deprecated = true]; - - /* - The amount to send expressed in satoshis. - - The fields amt and amt_msat are mutually exclusive. - */ - int64 amt = 3; - - /* - The amount to send expressed in millisatoshis. - - The fields amt and amt_msat are mutually exclusive. - */ - int64 amt_msat = 12; - - /* - The hash to use within the payment's HTLC. When using REST, this field - must be encoded as base64. - */ - bytes payment_hash = 4; - - /* - The hex-encoded hash to use within the payment's HTLC. Deprecated now - that the REST gateway supports base64 encoding of bytes fields. - */ - string payment_hash_string = 5 [deprecated = true]; - - /* - A bare-bones invoice for a payment within the Lightning Network. With the - details of the invoice, the sender has all the data necessary to send a - payment to the recipient. - */ - string payment_request = 6; - - /* - The CLTV delta from the current height that should be used to set the - timelock for the final hop. - */ - int32 final_cltv_delta = 7; - - /* - The maximum number of satoshis that will be paid as a fee of the payment. - This value can be represented either as a percentage of the amount being - sent, or as a fixed amount of the maximum fee the user is willing the pay to - send the payment. If not specified, lnd will use a default value of 100% - fees for small amounts (<=1k sat) or 5% fees for larger amounts. - */ - FeeLimit fee_limit = 8; - - /* - The channel id of the channel that must be taken to the first hop. If zero, - any channel may be used. - */ - uint64 outgoing_chan_id = 9 [jstype = JS_STRING]; - - /* - The pubkey of the last hop of the route. If empty, any hop may be used. - */ - bytes last_hop_pubkey = 13; - - /* - An optional maximum total time lock for the route. This should not exceed - lnd's `--max-cltv-expiry` setting. If zero, then the value of - `--max-cltv-expiry` is enforced. - */ - uint32 cltv_limit = 10; - - /* - An optional field that can be used to pass an arbitrary set of TLV records - to a peer which understands the new records. This can be used to pass - application specific data during the payment attempt. Record types are - required to be in the custom range >= 65536. When using REST, the values - must be encoded as base64. - */ - map dest_custom_records = 11; - - // If set, circular payments to self are permitted. - bool allow_self_payment = 14; - - /* - Features assumed to be supported by the final node. All transitive feature - dependencies must also be set properly. For a given feature bit pair, either - optional or remote may be set, but not both. If this field is nil or empty, - the router will try to load destination features from the graph as a - fallback. - */ - repeated FeatureBit dest_features = 15; - - /* - The payment address of the generated invoice. - */ - bytes payment_addr = 16; -} - -message SendResponse { - string payment_error = 1; - bytes payment_preimage = 2; - Route payment_route = 3; - bytes payment_hash = 4; -} - -message SendToRouteRequest { - /* - The payment hash to use for the HTLC. When using REST, this field must be - encoded as base64. - */ - bytes payment_hash = 1; - - /* - An optional hex-encoded payment hash to be used for the HTLC. Deprecated now - that the REST gateway supports base64 encoding of bytes fields. - */ - string payment_hash_string = 2 [deprecated = true]; - - reserved 3; - - // Route that should be used to attempt to complete the payment. - Route route = 4; -} - -message ChannelAcceptRequest { - // The pubkey of the node that wishes to open an inbound channel. - bytes node_pubkey = 1; - - // The hash of the genesis block that the proposed channel resides in. - bytes chain_hash = 2; - - // The pending channel id. - bytes pending_chan_id = 3; - - // The funding amount in satoshis that initiator wishes to use in the - // channel. - uint64 funding_amt = 4; - - // The push amount of the proposed channel in millisatoshis. - uint64 push_amt = 5; - - // The dust limit of the initiator's commitment tx. - uint64 dust_limit = 6; - - // The maximum amount of coins in millisatoshis that can be pending in this - // channel. - uint64 max_value_in_flight = 7; - - // The minimum amount of satoshis the initiator requires us to have at all - // times. - uint64 channel_reserve = 8; - - // The smallest HTLC in millisatoshis that the initiator will accept. - uint64 min_htlc = 9; - - // The initial fee rate that the initiator suggests for both commitment - // transactions. - uint64 fee_per_kw = 10; - - /* - The number of blocks to use for the relative time lock in the pay-to-self - output of both commitment transactions. - */ - uint32 csv_delay = 11; - - // The total number of incoming HTLC's that the initiator will accept. - uint32 max_accepted_htlcs = 12; - - // A bit-field which the initiator uses to specify proposed channel - // behavior. - uint32 channel_flags = 13; - - // The commitment type the initiator wishes to use for the proposed channel. - CommitmentType commitment_type = 14; - - // Whether the initiator wants to open a zero-conf channel via the channel - // type. - bool wants_zero_conf = 15; - - // Whether the initiator wants to use the scid-alias channel type. This is - // separate from the feature bit. - bool wants_scid_alias = 16; -} - -message ChannelAcceptResponse { - // Whether or not the client accepts the channel. - bool accept = 1; - - // The pending channel id to which this response applies. - bytes pending_chan_id = 2; - - /* - An optional error to send the initiating party to indicate why the channel - was rejected. This field *should not* contain sensitive information, it will - be sent to the initiating party. This field should only be set if accept is - false, the channel will be rejected if an error is set with accept=true - because the meaning of this response is ambiguous. Limited to 500 - characters. - */ - string error = 3; - - /* - The upfront shutdown address to use if the initiating peer supports option - upfront shutdown script (see ListPeers for the features supported). Note - that the channel open will fail if this value is set for a peer that does - not support this feature bit. - */ - string upfront_shutdown = 4; - - /* - The csv delay (in blocks) that we require for the remote party. - */ - uint32 csv_delay = 5; - - /* - The reserve amount in satoshis that we require the remote peer to adhere to. - We require that the remote peer always have some reserve amount allocated to - them so that there is always a disincentive to broadcast old state (if they - hold 0 sats on their side of the channel, there is nothing to lose). - */ - uint64 reserve_sat = 6; - - /* - The maximum amount of funds in millisatoshis that we allow the remote peer - to have in outstanding htlcs. - */ - uint64 in_flight_max_msat = 7; - - /* - The maximum number of htlcs that the remote peer can offer us. - */ - uint32 max_htlc_count = 8; - - /* - The minimum value in millisatoshis for incoming htlcs on the channel. - */ - uint64 min_htlc_in = 9; - - /* - The number of confirmations we require before we consider the channel open. - */ - uint32 min_accept_depth = 10; - - /* - Whether the responder wants this to be a zero-conf channel. This will fail - if either side does not have the scid-alias feature bit set. The minimum - depth field must be zero if this is true. - */ - bool zero_conf = 11; -} - -message ChannelPoint { - oneof funding_txid { - /* - Txid of the funding transaction. When using REST, this field must be - encoded as base64. - */ - bytes funding_txid_bytes = 1; - - /* - Hex-encoded string representing the byte-reversed hash of the funding - transaction. - */ - string funding_txid_str = 2; - } - - // The index of the output of the funding transaction - uint32 output_index = 3; -} - -message OutPoint { - // Raw bytes representing the transaction id. - bytes txid_bytes = 1; - - // Reversed, hex-encoded string representing the transaction id. - string txid_str = 2; - - // The index of the output on the transaction. - uint32 output_index = 3; -} - -message PreviousOutPoint { - // The outpoint in format txid:n. - string outpoint = 1; - - // Denotes if the outpoint is controlled by the internal wallet. - // The flag will only detect p2wkh, np2wkh and p2tr inputs as its own. - bool is_our_output = 2; -} - -message LightningAddress { - // The identity pubkey of the Lightning node. - string pubkey = 1; - - // The network location of the lightning node, e.g. `69.69.69.69:1337` or - // `localhost:10011`. - string host = 2; -} - -message EstimateFeeRequest { - // The map from addresses to amounts for the transaction. - map AddrToAmount = 1; - - // The target number of blocks that this transaction should be confirmed - // by. - int32 target_conf = 2; - - // The minimum number of confirmations each one of your outputs used for - // the transaction must satisfy. - int32 min_confs = 3; - - // Whether unconfirmed outputs should be used as inputs for the transaction. - bool spend_unconfirmed = 4; -} - -message EstimateFeeResponse { - // The total fee in satoshis. - int64 fee_sat = 1; - - // Deprecated, use sat_per_vbyte. - // The fee rate in satoshi/vbyte. - int64 feerate_sat_per_byte = 2 [deprecated = true]; - - // The fee rate in satoshi/vbyte. - uint64 sat_per_vbyte = 3; -} - -message SendManyRequest { - // The map from addresses to amounts - map AddrToAmount = 1; - - // The target number of blocks that this transaction should be confirmed - // by. - int32 target_conf = 3; - - // A manual fee rate set in sat/vbyte that should be used when crafting the - // transaction. - uint64 sat_per_vbyte = 4; - - // Deprecated, use sat_per_vbyte. - // A manual fee rate set in sat/vbyte that should be used when crafting the - // transaction. - int64 sat_per_byte = 5 [deprecated = true]; - - // An optional label for the transaction, limited to 500 characters. - string label = 6; - - // The minimum number of confirmations each one of your outputs used for - // the transaction must satisfy. - int32 min_confs = 7; - - // Whether unconfirmed outputs should be used as inputs for the transaction. - bool spend_unconfirmed = 8; -} -message SendManyResponse { - // The id of the transaction - string txid = 1; -} - -message SendCoinsRequest { - // The address to send coins to - string addr = 1; - - // The amount in satoshis to send - int64 amount = 2; - - // The target number of blocks that this transaction should be confirmed - // by. - int32 target_conf = 3; - - // A manual fee rate set in sat/vbyte that should be used when crafting the - // transaction. - uint64 sat_per_vbyte = 4; - - // Deprecated, use sat_per_vbyte. - // A manual fee rate set in sat/vbyte that should be used when crafting the - // transaction. - int64 sat_per_byte = 5 [deprecated = true]; - - /* - If set, then the amount field will be ignored, and lnd will attempt to - send all the coins under control of the internal wallet to the specified - address. - */ - bool send_all = 6; - - // An optional label for the transaction, limited to 500 characters. - string label = 7; - - // The minimum number of confirmations each one of your outputs used for - // the transaction must satisfy. - int32 min_confs = 8; - - // Whether unconfirmed outputs should be used as inputs for the transaction. - bool spend_unconfirmed = 9; -} -message SendCoinsResponse { - // The transaction ID of the transaction - string txid = 1; -} - -message ListUnspentRequest { - // The minimum number of confirmations to be included. - int32 min_confs = 1; - - // The maximum number of confirmations to be included. - int32 max_confs = 2; - - // An optional filter to only include outputs belonging to an account. - string account = 3; -} -message ListUnspentResponse { - // A list of utxos - repeated Utxo utxos = 1; -} - -/* -`AddressType` has to be one of: - -- `p2wkh`: Pay to witness key hash (`WITNESS_PUBKEY_HASH` = 0) -- `np2wkh`: Pay to nested witness key hash (`NESTED_PUBKEY_HASH` = 1) -- `p2tr`: Pay to taproot pubkey (`TAPROOT_PUBKEY` = 4) -*/ -enum AddressType { - WITNESS_PUBKEY_HASH = 0; - NESTED_PUBKEY_HASH = 1; - UNUSED_WITNESS_PUBKEY_HASH = 2; - UNUSED_NESTED_PUBKEY_HASH = 3; - TAPROOT_PUBKEY = 4; - UNUSED_TAPROOT_PUBKEY = 5; -} - -message NewAddressRequest { - // The type of address to generate. - AddressType type = 1; - - /* - The name of the account to generate a new address for. If empty, the - default wallet account is used. - */ - string account = 2; -} -message NewAddressResponse { - // The newly generated wallet address - string address = 1; -} - -message SignMessageRequest { - /* - The message to be signed. When using REST, this field must be encoded as - base64. - */ - bytes msg = 1; - - /* - Instead of the default double-SHA256 hashing of the message before signing, - only use one round of hashing instead. - */ - bool single_hash = 2; -} -message SignMessageResponse { - // The signature for the given message - string signature = 1; -} - -message VerifyMessageRequest { - /* - The message over which the signature is to be verified. When using REST, - this field must be encoded as base64. - */ - bytes msg = 1; - - // The signature to be verified over the given message - string signature = 2; -} -message VerifyMessageResponse { - // Whether the signature was valid over the given message - bool valid = 1; - - // The pubkey recovered from the signature - string pubkey = 2; -} - -message ConnectPeerRequest { - /* - Lightning address of the peer to connect to. - */ - LightningAddress addr = 1; - - /* - If set, the daemon will attempt to persistently connect to the target - peer. Otherwise, the call will be synchronous. - */ - bool perm = 2; - - /* - The connection timeout value (in seconds) for this request. It won't affect - other requests. - */ - uint64 timeout = 3; -} -message ConnectPeerResponse { -} - -message DisconnectPeerRequest { - // The pubkey of the node to disconnect from - string pub_key = 1; -} -message DisconnectPeerResponse { -} - -message HTLC { - bool incoming = 1; - int64 amount = 2; - bytes hash_lock = 3; - uint32 expiration_height = 4; - - // Index identifying the htlc on the channel. - uint64 htlc_index = 5; - - // If this HTLC is involved in a forwarding operation, this field indicates - // the forwarding channel. For an outgoing htlc, it is the incoming channel. - // For an incoming htlc, it is the outgoing channel. When the htlc - // originates from this node or this node is the final destination, - // forwarding_channel will be zero. The forwarding channel will also be zero - // for htlcs that need to be forwarded but don't have a forwarding decision - // persisted yet. - uint64 forwarding_channel = 6; - - // Index identifying the htlc on the forwarding channel. - uint64 forwarding_htlc_index = 7; -} - -enum CommitmentType { - /* - Returned when the commitment type isn't known or unavailable. - */ - UNKNOWN_COMMITMENT_TYPE = 0; - - /* - A channel using the legacy commitment format having tweaked to_remote - keys. - */ - LEGACY = 1; - - /* - A channel that uses the modern commitment format where the key in the - output of the remote party does not change each state. This makes back - up and recovery easier as when the channel is closed, the funds go - directly to that key. - */ - STATIC_REMOTE_KEY = 2; - - /* - A channel that uses a commitment format that has anchor outputs on the - commitments, allowing fee bumping after a force close transaction has - been broadcast. - */ - ANCHORS = 3; - - /* - A channel that uses a commitment type that builds upon the anchors - commitment format, but in addition requires a CLTV clause to spend outputs - paying to the channel initiator. This is intended for use on leased channels - to guarantee that the channel initiator has no incentives to close a leased - channel before its maturity date. - */ - SCRIPT_ENFORCED_LEASE = 4; -} - -message ChannelConstraints { - /* - The CSV delay expressed in relative blocks. If the channel is force closed, - we will need to wait for this many blocks before we can regain our funds. - */ - uint32 csv_delay = 1; - - // The minimum satoshis this node is required to reserve in its balance. - uint64 chan_reserve_sat = 2; - - // The dust limit (in satoshis) of the initiator's commitment tx. - uint64 dust_limit_sat = 3; - - // The maximum amount of coins in millisatoshis that can be pending in this - // channel. - uint64 max_pending_amt_msat = 4; - - // The smallest HTLC in millisatoshis that the initiator will accept. - uint64 min_htlc_msat = 5; - - // The total number of incoming HTLC's that the initiator will accept. - uint32 max_accepted_htlcs = 6; -} - -message Channel { - // Whether this channel is active or not - bool active = 1; - - // The identity pubkey of the remote node - string remote_pubkey = 2; - - /* - The outpoint (txid:index) of the funding transaction. With this value, Bob - will be able to generate a signature for Alice's version of the commitment - transaction. - */ - string channel_point = 3; - - /* - The unique channel ID for the channel. The first 3 bytes are the block - height, the next 3 the index within the block, and the last 2 bytes are the - output index for the channel. - */ - uint64 chan_id = 4 [jstype = JS_STRING]; - - // The total amount of funds held in this channel - int64 capacity = 5; - - // This node's current balance in this channel - int64 local_balance = 6; - - // The counterparty's current balance in this channel - int64 remote_balance = 7; - - /* - The amount calculated to be paid in fees for the current set of commitment - transactions. The fee amount is persisted with the channel in order to - allow the fee amount to be removed and recalculated with each channel state - update, including updates that happen after a system restart. - */ - int64 commit_fee = 8; - - // The weight of the commitment transaction - int64 commit_weight = 9; - - /* - The required number of satoshis per kilo-weight that the requester will pay - at all times, for both the funding transaction and commitment transaction. - This value can later be updated once the channel is open. - */ - int64 fee_per_kw = 10; - - // The unsettled balance in this channel - int64 unsettled_balance = 11; - - /* - The total number of satoshis we've sent within this channel. - */ - int64 total_satoshis_sent = 12; - - /* - The total number of satoshis we've received within this channel. - */ - int64 total_satoshis_received = 13; - - /* - The total number of updates conducted within this channel. - */ - uint64 num_updates = 14; - - /* - The list of active, uncleared HTLCs currently pending within the channel. - */ - repeated HTLC pending_htlcs = 15; - - /* - Deprecated. The CSV delay expressed in relative blocks. If the channel is - force closed, we will need to wait for this many blocks before we can regain - our funds. - */ - uint32 csv_delay = 16 [deprecated = true]; - - // Whether this channel is advertised to the network or not. - bool private = 17; - - // True if we were the ones that created the channel. - bool initiator = 18; - - // A set of flags showing the current state of the channel. - string chan_status_flags = 19; - - // Deprecated. The minimum satoshis this node is required to reserve in its - // balance. - int64 local_chan_reserve_sat = 20 [deprecated = true]; - - /* - Deprecated. The minimum satoshis the other node is required to reserve in - its balance. - */ - int64 remote_chan_reserve_sat = 21 [deprecated = true]; - - // Deprecated. Use commitment_type. - bool static_remote_key = 22 [deprecated = true]; - - // The commitment type used by this channel. - CommitmentType commitment_type = 26; - - /* - The number of seconds that the channel has been monitored by the channel - scoring system. Scores are currently not persisted, so this value may be - less than the lifetime of the channel [EXPERIMENTAL]. - */ - int64 lifetime = 23; - - /* - The number of seconds that the remote peer has been observed as being online - by the channel scoring system over the lifetime of the channel - [EXPERIMENTAL]. - */ - int64 uptime = 24; - - /* - Close address is the address that we will enforce payout to on cooperative - close if the channel was opened utilizing option upfront shutdown. This - value can be set on channel open by setting close_address in an open channel - request. If this value is not set, you can still choose a payout address by - cooperatively closing with the delivery_address field set. - */ - string close_address = 25; - - /* - The amount that the initiator of the channel optionally pushed to the remote - party on channel open. This amount will be zero if the channel initiator did - not push any funds to the remote peer. If the initiator field is true, we - pushed this amount to our peer, if it is false, the remote peer pushed this - amount to us. - */ - uint64 push_amount_sat = 27; - - /* - This uint32 indicates if this channel is to be considered 'frozen'. A - frozen channel doest not allow a cooperative channel close by the - initiator. The thaw_height is the height that this restriction stops - applying to the channel. This field is optional, not setting it or using a - value of zero will mean the channel has no additional restrictions. The - height can be interpreted in two ways: as a relative height if the value is - less than 500,000, or as an absolute height otherwise. - */ - uint32 thaw_height = 28; - - // List constraints for the local node. - ChannelConstraints local_constraints = 29; - - // List constraints for the remote node. - ChannelConstraints remote_constraints = 30; - - /* - This lists out the set of alias short channel ids that exist for a channel. - This may be empty. - */ - repeated uint64 alias_scids = 31; - - // Whether or not this is a zero-conf channel. - bool zero_conf = 32; - - // This is the confirmed / on-chain zero-conf SCID. - uint64 zero_conf_confirmed_scid = 33; -} - -message ListChannelsRequest { - bool active_only = 1; - bool inactive_only = 2; - bool public_only = 3; - bool private_only = 4; - - /* - Filters the response for channels with a target peer's pubkey. If peer is - empty, all channels will be returned. - */ - bytes peer = 5; -} -message ListChannelsResponse { - // The list of active channels - repeated Channel channels = 11; -} - -message AliasMap { - /* - For non-zero-conf channels, this is the confirmed SCID. Otherwise, this is - the first assigned "base" alias. - */ - uint64 base_scid = 1; - - // The set of all aliases stored for the base SCID. - repeated uint64 aliases = 2; -} -message ListAliasesRequest { -} -message ListAliasesResponse { - repeated AliasMap alias_maps = 1; -} - -enum Initiator { - INITIATOR_UNKNOWN = 0; - INITIATOR_LOCAL = 1; - INITIATOR_REMOTE = 2; - INITIATOR_BOTH = 3; -} - -message ChannelCloseSummary { - // The outpoint (txid:index) of the funding transaction. - string channel_point = 1; - - // The unique channel ID for the channel. - uint64 chan_id = 2 [jstype = JS_STRING]; - - // The hash of the genesis block that this channel resides within. - string chain_hash = 3; - - // The txid of the transaction which ultimately closed this channel. - string closing_tx_hash = 4; - - // Public key of the remote peer that we formerly had a channel with. - string remote_pubkey = 5; - - // Total capacity of the channel. - int64 capacity = 6; - - // Height at which the funding transaction was spent. - uint32 close_height = 7; - - // Settled balance at the time of channel closure - int64 settled_balance = 8; - - // The sum of all the time-locked outputs at the time of channel closure - int64 time_locked_balance = 9; - - enum ClosureType { - COOPERATIVE_CLOSE = 0; - LOCAL_FORCE_CLOSE = 1; - REMOTE_FORCE_CLOSE = 2; - BREACH_CLOSE = 3; - FUNDING_CANCELED = 4; - ABANDONED = 5; - } - - // Details on how the channel was closed. - ClosureType close_type = 10; - - /* - Open initiator is the party that initiated opening the channel. Note that - this value may be unknown if the channel was closed before we migrated to - store open channel information after close. - */ - Initiator open_initiator = 11; - - /* - Close initiator indicates which party initiated the close. This value will - be unknown for channels that were cooperatively closed before we started - tracking cooperative close initiators. Note that this indicates which party - initiated a close, and it is possible for both to initiate cooperative or - force closes, although only one party's close will be confirmed on chain. - */ - Initiator close_initiator = 12; - - repeated Resolution resolutions = 13; - - /* - This lists out the set of alias short channel ids that existed for the - closed channel. This may be empty. - */ - repeated uint64 alias_scids = 14; - - // The confirmed SCID for a zero-conf channel. - uint64 zero_conf_confirmed_scid = 15 [jstype = JS_STRING]; -} - -enum ResolutionType { - TYPE_UNKNOWN = 0; - - // We resolved an anchor output. - ANCHOR = 1; - - /* - We are resolving an incoming htlc on chain. This if this htlc is - claimed, we swept the incoming htlc with the preimage. If it is timed - out, our peer swept the timeout path. - */ - INCOMING_HTLC = 2; - - /* - We are resolving an outgoing htlc on chain. If this htlc is claimed, - the remote party swept the htlc with the preimage. If it is timed out, - we swept it with the timeout path. - */ - OUTGOING_HTLC = 3; - - // We force closed and need to sweep our time locked commitment output. - COMMIT = 4; -} - -enum ResolutionOutcome { - // Outcome unknown. - OUTCOME_UNKNOWN = 0; - - // An output was claimed on chain. - CLAIMED = 1; - - // An output was left unclaimed on chain. - UNCLAIMED = 2; - - /* - ResolverOutcomeAbandoned indicates that an output that we did not - claim on chain, for example an anchor that we did not sweep and a - third party claimed on chain, or a htlc that we could not decode - so left unclaimed. - */ - ABANDONED = 3; - - /* - If we force closed our channel, our htlcs need to be claimed in two - stages. This outcome represents the broadcast of a timeout or success - transaction for this two stage htlc claim. - */ - FIRST_STAGE = 4; - - // A htlc was timed out on chain. - TIMEOUT = 5; -} - -message Resolution { - // The type of output we are resolving. - ResolutionType resolution_type = 1; - - // The outcome of our on chain action that resolved the outpoint. - ResolutionOutcome outcome = 2; - - // The outpoint that was spent by the resolution. - OutPoint outpoint = 3; - - // The amount that was claimed by the resolution. - uint64 amount_sat = 4; - - // The hex-encoded transaction ID of the sweep transaction that spent the - // output. - string sweep_txid = 5; -} - -message ClosedChannelsRequest { - bool cooperative = 1; - bool local_force = 2; - bool remote_force = 3; - bool breach = 4; - bool funding_canceled = 5; - bool abandoned = 6; -} - -message ClosedChannelsResponse { - repeated ChannelCloseSummary channels = 1; -} - -message Peer { - // The identity pubkey of the peer - string pub_key = 1; - - // Network address of the peer; eg `127.0.0.1:10011` - string address = 3; - - // Bytes of data transmitted to this peer - uint64 bytes_sent = 4; - - // Bytes of data transmitted from this peer - uint64 bytes_recv = 5; - - // Satoshis sent to this peer - int64 sat_sent = 6; - - // Satoshis received from this peer - int64 sat_recv = 7; - - // A channel is inbound if the counterparty initiated the channel - bool inbound = 8; - - // Ping time to this peer - int64 ping_time = 9; - - enum SyncType { - /* - Denotes that we cannot determine the peer's current sync type. - */ - UNKNOWN_SYNC = 0; - - /* - Denotes that we are actively receiving new graph updates from the peer. - */ - ACTIVE_SYNC = 1; - - /* - Denotes that we are not receiving new graph updates from the peer. - */ - PASSIVE_SYNC = 2; - - /* - Denotes that this peer is pinned into an active sync. - */ - PINNED_SYNC = 3; - } - - // The type of sync we are currently performing with this peer. - SyncType sync_type = 10; - - // Features advertised by the remote peer in their init message. - map features = 11; - - /* - The latest errors received from our peer with timestamps, limited to the 10 - most recent errors. These errors are tracked across peer connections, but - are not persisted across lnd restarts. Note that these errors are only - stored for peers that we have channels open with, to prevent peers from - spamming us with errors at no cost. - */ - repeated TimestampedError errors = 12; - - /* - The number of times we have recorded this peer going offline or coming - online, recorded across restarts. Note that this value is decreased over - time if the peer has not recently flapped, so that we can forgive peers - with historically high flap counts. - */ - int32 flap_count = 13; - - /* - The timestamp of the last flap we observed for this peer. If this value is - zero, we have not observed any flaps for this peer. - */ - int64 last_flap_ns = 14; - - /* - The last ping payload the peer has sent to us. - */ - bytes last_ping_payload = 15; -} - -message TimestampedError { - // The unix timestamp in seconds when the error occurred. - uint64 timestamp = 1; - - // The string representation of the error sent by our peer. - string error = 2; -} - -message ListPeersRequest { - /* - If true, only the last error that our peer sent us will be returned with - the peer's information, rather than the full set of historic errors we have - stored. - */ - bool latest_error = 1; -} -message ListPeersResponse { - // The list of currently connected peers - repeated Peer peers = 1; -} - -message PeerEventSubscription { -} - -message PeerEvent { - // The identity pubkey of the peer. - string pub_key = 1; - - enum EventType { - PEER_ONLINE = 0; - PEER_OFFLINE = 1; - } - - EventType type = 2; -} - -message GetInfoRequest { -} -message GetInfoResponse { - // The version of the LND software that the node is running. - string version = 14; - - // The SHA1 commit hash that the daemon is compiled with. - string commit_hash = 20; - - // The identity pubkey of the current node. - string identity_pubkey = 1; - - // If applicable, the alias of the current node, e.g. "bob" - string alias = 2; - - // The color of the current node in hex code format - string color = 17; - - // Number of pending channels - uint32 num_pending_channels = 3; - - // Number of active channels - uint32 num_active_channels = 4; - - // Number of inactive channels - uint32 num_inactive_channels = 15; - - // Number of peers - uint32 num_peers = 5; - - // The node's current view of the height of the best block - uint32 block_height = 6; - - // The node's current view of the hash of the best block - string block_hash = 8; - - // Timestamp of the block best known to the wallet - int64 best_header_timestamp = 13; - - // Whether the wallet's view is synced to the main chain - bool synced_to_chain = 9; - - // Whether we consider ourselves synced with the public channel graph. - bool synced_to_graph = 18; - - /* - Whether the current node is connected to testnet. This field is - deprecated and the network field should be used instead - **/ - bool testnet = 10 [deprecated = true]; - - reserved 11; - - // A list of active chains the node is connected to - repeated Chain chains = 16; - - // The URIs of the current node. - repeated string uris = 12; - - /* - Features that our node has advertised in our init message, node - announcements and invoices. - */ - map features = 19; - - /* - Indicates whether the HTLC interceptor API is in always-on mode. - */ - bool require_htlc_interceptor = 21; -} - -message GetRecoveryInfoRequest { -} -message GetRecoveryInfoResponse { - // Whether the wallet is in recovery mode - bool recovery_mode = 1; - - // Whether the wallet recovery progress is finished - bool recovery_finished = 2; - - // The recovery progress, ranging from 0 to 1. - double progress = 3; -} - -message Chain { - // The blockchain the node is on (eg bitcoin, litecoin) - string chain = 1; - - // The network the node is on (eg regtest, testnet, mainnet) - string network = 2; -} - -message ConfirmationUpdate { - bytes block_sha = 1; - int32 block_height = 2; - - uint32 num_confs_left = 3; -} - -message ChannelOpenUpdate { - ChannelPoint channel_point = 1; -} - -message ChannelCloseUpdate { - bytes closing_txid = 1; - - bool success = 2; -} - -message CloseChannelRequest { - /* - The outpoint (txid:index) of the funding transaction. With this value, Bob - will be able to generate a signature for Alice's version of the commitment - transaction. - */ - ChannelPoint channel_point = 1; - - // If true, then the channel will be closed forcibly. This means the - // current commitment transaction will be signed and broadcast. - bool force = 2; - - // The target number of blocks that the closure transaction should be - // confirmed by. - int32 target_conf = 3; - - // Deprecated, use sat_per_vbyte. - // A manual fee rate set in sat/vbyte that should be used when crafting the - // closure transaction. - int64 sat_per_byte = 4 [deprecated = true]; - - /* - An optional address to send funds to in the case of a cooperative close. - If the channel was opened with an upfront shutdown script and this field - is set, the request to close will fail because the channel must pay out - to the upfront shutdown addresss. - */ - string delivery_address = 5; - - // A manual fee rate set in sat/vbyte that should be used when crafting the - // closure transaction. - uint64 sat_per_vbyte = 6; - - // The maximum fee rate the closer is willing to pay. - // - // NOTE: This field is only respected if we're the initiator of the channel. - uint64 max_fee_per_vbyte = 7; -} - -message CloseStatusUpdate { - oneof update { - PendingUpdate close_pending = 1; - ChannelCloseUpdate chan_close = 3; - } -} - -message PendingUpdate { - bytes txid = 1; - uint32 output_index = 2; -} - -message ReadyForPsbtFunding { - /* - The P2WSH address of the channel funding multisig address that the below - specified amount in satoshis needs to be sent to. - */ - string funding_address = 1; - - /* - The exact amount in satoshis that needs to be sent to the above address to - fund the pending channel. - */ - int64 funding_amount = 2; - - /* - A raw PSBT that contains the pending channel output. If a base PSBT was - provided in the PsbtShim, this is the base PSBT with one additional output. - If no base PSBT was specified, this is an otherwise empty PSBT with exactly - one output. - */ - bytes psbt = 3; -} - -message BatchOpenChannelRequest { - // The list of channels to open. - repeated BatchOpenChannel channels = 1; - - // The target number of blocks that the funding transaction should be - // confirmed by. - int32 target_conf = 2; - - // A manual fee rate set in sat/vByte that should be used when crafting the - // funding transaction. - int64 sat_per_vbyte = 3; - - // The minimum number of confirmations each one of your outputs used for - // the funding transaction must satisfy. - int32 min_confs = 4; - - // Whether unconfirmed outputs should be used as inputs for the funding - // transaction. - bool spend_unconfirmed = 5; - - // An optional label for the batch transaction, limited to 500 characters. - string label = 6; -} - -message BatchOpenChannel { - // The pubkey of the node to open a channel with. When using REST, this - // field must be encoded as base64. - bytes node_pubkey = 1; - - // The number of satoshis the wallet should commit to the channel. - int64 local_funding_amount = 2; - - // The number of satoshis to push to the remote side as part of the initial - // commitment state. - int64 push_sat = 3; - - // Whether this channel should be private, not announced to the greater - // network. - bool private = 4; - - // The minimum value in millisatoshi we will require for incoming HTLCs on - // the channel. - int64 min_htlc_msat = 5; - - // The delay we require on the remote's commitment transaction. If this is - // not set, it will be scaled automatically with the channel size. - uint32 remote_csv_delay = 6; - - /* - Close address is an optional address which specifies the address to which - funds should be paid out to upon cooperative close. This field may only be - set if the peer supports the option upfront feature bit (call listpeers - to check). The remote peer will only accept cooperative closes to this - address if it is set. - - Note: If this value is set on channel creation, you will *not* be able to - cooperatively close out to a different address. - */ - string close_address = 7; - - /* - An optional, unique identifier of 32 random bytes that will be used as the - pending channel ID to identify the channel while it is in the pre-pending - state. - */ - bytes pending_chan_id = 8; - - /* - The explicit commitment type to use. Note this field will only be used if - the remote peer supports explicit channel negotiation. - */ - CommitmentType commitment_type = 9; -} - -message BatchOpenChannelResponse { - repeated PendingUpdate pending_channels = 1; -} - -message OpenChannelRequest { - // A manual fee rate set in sat/vbyte that should be used when crafting the - // funding transaction. - uint64 sat_per_vbyte = 1; - - /* - The pubkey of the node to open a channel with. When using REST, this field - must be encoded as base64. - */ - bytes node_pubkey = 2; - - /* - The hex encoded pubkey of the node to open a channel with. Deprecated now - that the REST gateway supports base64 encoding of bytes fields. - */ - string node_pubkey_string = 3 [deprecated = true]; - - // The number of satoshis the wallet should commit to the channel - int64 local_funding_amount = 4; - - // The number of satoshis to push to the remote side as part of the initial - // commitment state - int64 push_sat = 5; - - // The target number of blocks that the funding transaction should be - // confirmed by. - int32 target_conf = 6; - - // Deprecated, use sat_per_vbyte. - // A manual fee rate set in sat/vbyte that should be used when crafting the - // funding transaction. - int64 sat_per_byte = 7 [deprecated = true]; - - // Whether this channel should be private, not announced to the greater - // network. - bool private = 8; - - // The minimum value in millisatoshi we will require for incoming HTLCs on - // the channel. - int64 min_htlc_msat = 9; - - // The delay we require on the remote's commitment transaction. If this is - // not set, it will be scaled automatically with the channel size. - uint32 remote_csv_delay = 10; - - // The minimum number of confirmations each one of your outputs used for - // the funding transaction must satisfy. - int32 min_confs = 11; - - // Whether unconfirmed outputs should be used as inputs for the funding - // transaction. - bool spend_unconfirmed = 12; - - /* - Close address is an optional address which specifies the address to which - funds should be paid out to upon cooperative close. This field may only be - set if the peer supports the option upfront feature bit (call listpeers - to check). The remote peer will only accept cooperative closes to this - address if it is set. - - Note: If this value is set on channel creation, you will *not* be able to - cooperatively close out to a different address. - */ - string close_address = 13; - - /* - Funding shims are an optional argument that allow the caller to intercept - certain funding functionality. For example, a shim can be provided to use a - particular key for the commitment key (ideally cold) rather than use one - that is generated by the wallet as normal, or signal that signing will be - carried out in an interactive manner (PSBT based). - */ - FundingShim funding_shim = 14; - - /* - The maximum amount of coins in millisatoshi that can be pending within - the channel. It only applies to the remote party. - */ - uint64 remote_max_value_in_flight_msat = 15; - - /* - The maximum number of concurrent HTLCs we will allow the remote party to add - to the commitment transaction. - */ - uint32 remote_max_htlcs = 16; - - /* - Max local csv is the maximum csv delay we will allow for our own commitment - transaction. - */ - uint32 max_local_csv = 17; - - /* - The explicit commitment type to use. Note this field will only be used if - the remote peer supports explicit channel negotiation. - */ - CommitmentType commitment_type = 18; - - /* - If this is true, then a zero-conf channel open will be attempted. - */ - bool zero_conf = 19; - - /* - If this is true, then an option-scid-alias channel-type open will be - attempted. - */ - bool scid_alias = 20; -} -message OpenStatusUpdate { - oneof update { - /* - Signals that the channel is now fully negotiated and the funding - transaction published. - */ - PendingUpdate chan_pending = 1; - - /* - Signals that the channel's funding transaction has now reached the - required number of confirmations on chain and can be used. - */ - ChannelOpenUpdate chan_open = 3; - - /* - Signals that the funding process has been suspended and the construction - of a PSBT that funds the channel PK script is now required. - */ - ReadyForPsbtFunding psbt_fund = 5; - } - - /* - The pending channel ID of the created channel. This value may be used to - further the funding flow manually via the FundingStateStep method. - */ - bytes pending_chan_id = 4; -} - -message KeyLocator { - // The family of key being identified. - int32 key_family = 1; - - // The precise index of the key being identified. - int32 key_index = 2; -} - -message KeyDescriptor { - /* - The raw bytes of the key being identified. - */ - bytes raw_key_bytes = 1; - - /* - The key locator that identifies which key to use for signing. - */ - KeyLocator key_loc = 2; -} - -message ChanPointShim { - /* - The size of the pre-crafted output to be used as the channel point for this - channel funding. - */ - int64 amt = 1; - - // The target channel point to refrence in created commitment transactions. - ChannelPoint chan_point = 2; - - // Our local key to use when creating the multi-sig output. - KeyDescriptor local_key = 3; - - // The key of the remote party to use when creating the multi-sig output. - bytes remote_key = 4; - - /* - If non-zero, then this will be used as the pending channel ID on the wire - protocol to initate the funding request. This is an optional field, and - should only be set if the responder is already expecting a specific pending - channel ID. - */ - bytes pending_chan_id = 5; - - /* - This uint32 indicates if this channel is to be considered 'frozen'. A frozen - channel does not allow a cooperative channel close by the initiator. The - thaw_height is the height that this restriction stops applying to the - channel. The height can be interpreted in two ways: as a relative height if - the value is less than 500,000, or as an absolute height otherwise. - */ - uint32 thaw_height = 6; -} - -message PsbtShim { - /* - A unique identifier of 32 random bytes that will be used as the pending - channel ID to identify the PSBT state machine when interacting with it and - on the wire protocol to initiate the funding request. - */ - bytes pending_chan_id = 1; - - /* - An optional base PSBT the new channel output will be added to. If this is - non-empty, it must be a binary serialized PSBT. - */ - bytes base_psbt = 2; - - /* - If a channel should be part of a batch (multiple channel openings in one - transaction), it can be dangerous if the whole batch transaction is - published too early before all channel opening negotiations are completed. - This flag prevents this particular channel from broadcasting the transaction - after the negotiation with the remote peer. In a batch of channel openings - this flag should be set to true for every channel but the very last. - */ - bool no_publish = 3; -} - -message FundingShim { - oneof shim { - /* - A channel shim where the channel point was fully constructed outside - of lnd's wallet and the transaction might already be published. - */ - ChanPointShim chan_point_shim = 1; - - /* - A channel shim that uses a PSBT to fund and sign the channel funding - transaction. - */ - PsbtShim psbt_shim = 2; - } -} - -message FundingShimCancel { - // The pending channel ID of the channel to cancel the funding shim for. - bytes pending_chan_id = 1; -} - -message FundingPsbtVerify { - /* - The funded but not yet signed PSBT that sends the exact channel capacity - amount to the PK script returned in the open channel message in a previous - step. - */ - bytes funded_psbt = 1; - - // The pending channel ID of the channel to get the PSBT for. - bytes pending_chan_id = 2; - - /* - Can only be used if the no_publish flag was set to true in the OpenChannel - call meaning that the caller is solely responsible for publishing the final - funding transaction. If skip_finalize is set to true then lnd will not wait - for a FundingPsbtFinalize state step and instead assumes that a transaction - with the same TXID as the passed in PSBT will eventually confirm. - IT IS ABSOLUTELY IMPERATIVE that the TXID of the transaction that is - eventually published does have the _same TXID_ as the verified PSBT. That - means no inputs or outputs can change, only signatures can be added. If the - TXID changes between this call and the publish step then the channel will - never be created and the funds will be in limbo. - */ - bool skip_finalize = 3; -} - -message FundingPsbtFinalize { - /* - The funded PSBT that contains all witness data to send the exact channel - capacity amount to the PK script returned in the open channel message in a - previous step. Cannot be set at the same time as final_raw_tx. - */ - bytes signed_psbt = 1; - - // The pending channel ID of the channel to get the PSBT for. - bytes pending_chan_id = 2; - - /* - As an alternative to the signed PSBT with all witness data, the final raw - wire format transaction can also be specified directly. Cannot be set at the - same time as signed_psbt. - */ - bytes final_raw_tx = 3; -} - -message FundingTransitionMsg { - oneof trigger { - /* - The funding shim to register. This should be used before any - channel funding has began by the remote party, as it is intended as a - preparatory step for the full channel funding. - */ - FundingShim shim_register = 1; - - // Used to cancel an existing registered funding shim. - FundingShimCancel shim_cancel = 2; - - /* - Used to continue a funding flow that was initiated to be executed - through a PSBT. This step verifies that the PSBT contains the correct - outputs to fund the channel. - */ - FundingPsbtVerify psbt_verify = 3; - - /* - Used to continue a funding flow that was initiated to be executed - through a PSBT. This step finalizes the funded and signed PSBT, finishes - negotiation with the peer and finally publishes the resulting funding - transaction. - */ - FundingPsbtFinalize psbt_finalize = 4; - } -} - -message FundingStateStepResp { -} - -message PendingHTLC { - // The direction within the channel that the htlc was sent - bool incoming = 1; - - // The total value of the htlc - int64 amount = 2; - - // The final output to be swept back to the user's wallet - string outpoint = 3; - - // The next block height at which we can spend the current stage - uint32 maturity_height = 4; - - /* - The number of blocks remaining until the current stage can be swept. - Negative values indicate how many blocks have passed since becoming - mature. - */ - int32 blocks_til_maturity = 5; - - // Indicates whether the htlc is in its first or second stage of recovery - uint32 stage = 6; -} - -message PendingChannelsRequest { -} -message PendingChannelsResponse { - message PendingChannel { - string remote_node_pub = 1; - string channel_point = 2; - - int64 capacity = 3; - - int64 local_balance = 4; - int64 remote_balance = 5; - - // The minimum satoshis this node is required to reserve in its - // balance. - int64 local_chan_reserve_sat = 6; - - /* - The minimum satoshis the other node is required to reserve in its - balance. - */ - int64 remote_chan_reserve_sat = 7; - - // The party that initiated opening the channel. - Initiator initiator = 8; - - // The commitment type used by this channel. - CommitmentType commitment_type = 9; - - // Total number of forwarding packages created in this channel. - int64 num_forwarding_packages = 10; - - // A set of flags showing the current state of the channel. - string chan_status_flags = 11; - - // Whether this channel is advertised to the network or not. - bool private = 12; - } - - message PendingOpenChannel { - // The pending channel - PendingChannel channel = 1; - - /* - The amount calculated to be paid in fees for the current set of - commitment transactions. The fee amount is persisted with the channel - in order to allow the fee amount to be removed and recalculated with - each channel state update, including updates that happen after a system - restart. - */ - int64 commit_fee = 4; - - // The weight of the commitment transaction - int64 commit_weight = 5; - - /* - The required number of satoshis per kilo-weight that the requester will - pay at all times, for both the funding transaction and commitment - transaction. This value can later be updated once the channel is open. - */ - int64 fee_per_kw = 6; - - // Previously used for confirmation_height. Do not reuse. - reserved 2; - } - - message WaitingCloseChannel { - // The pending channel waiting for closing tx to confirm - PendingChannel channel = 1; - - // The balance in satoshis encumbered in this channel - int64 limbo_balance = 2; - - /* - A list of valid commitment transactions. Any of these can confirm at - this point. - */ - Commitments commitments = 3; - - // The transaction id of the closing transaction - string closing_txid = 4; - } - - message Commitments { - // Hash of the local version of the commitment tx. - string local_txid = 1; - - // Hash of the remote version of the commitment tx. - string remote_txid = 2; - - // Hash of the remote pending version of the commitment tx. - string remote_pending_txid = 3; - - /* - The amount in satoshis calculated to be paid in fees for the local - commitment. - */ - uint64 local_commit_fee_sat = 4; - - /* - The amount in satoshis calculated to be paid in fees for the remote - commitment. - */ - uint64 remote_commit_fee_sat = 5; - - /* - The amount in satoshis calculated to be paid in fees for the remote - pending commitment. - */ - uint64 remote_pending_commit_fee_sat = 6; - } - - message ClosedChannel { - // The pending channel to be closed - PendingChannel channel = 1; - - // The transaction id of the closing transaction - string closing_txid = 2; - } - - message ForceClosedChannel { - // The pending channel to be force closed - PendingChannel channel = 1; - - // The transaction id of the closing transaction - string closing_txid = 2; - - // The balance in satoshis encumbered in this pending channel - int64 limbo_balance = 3; - - // The height at which funds can be swept into the wallet - uint32 maturity_height = 4; - - /* - Remaining # of blocks until the commitment output can be swept. - Negative values indicate how many blocks have passed since becoming - mature. - */ - int32 blocks_til_maturity = 5; - - // The total value of funds successfully recovered from this channel - int64 recovered_balance = 6; - - repeated PendingHTLC pending_htlcs = 8; - - enum AnchorState { - LIMBO = 0; - RECOVERED = 1; - LOST = 2; - } - - AnchorState anchor = 9; - } - - // The balance in satoshis encumbered in pending channels - int64 total_limbo_balance = 1; - - // Channels pending opening - repeated PendingOpenChannel pending_open_channels = 2; - - /* - Deprecated: Channels pending closing previously contained cooperatively - closed channels with a single confirmation. These channels are now - considered closed from the time we see them on chain. - */ - repeated ClosedChannel pending_closing_channels = 3 [deprecated = true]; - - // Channels pending force closing - repeated ForceClosedChannel pending_force_closing_channels = 4; - - // Channels waiting for closing tx to confirm - repeated WaitingCloseChannel waiting_close_channels = 5; -} - -message ChannelEventSubscription { -} - -message ChannelEventUpdate { - oneof channel { - Channel open_channel = 1; - ChannelCloseSummary closed_channel = 2; - ChannelPoint active_channel = 3; - ChannelPoint inactive_channel = 4; - PendingUpdate pending_open_channel = 6; - ChannelPoint fully_resolved_channel = 7; - } - - enum UpdateType { - OPEN_CHANNEL = 0; - CLOSED_CHANNEL = 1; - ACTIVE_CHANNEL = 2; - INACTIVE_CHANNEL = 3; - PENDING_OPEN_CHANNEL = 4; - FULLY_RESOLVED_CHANNEL = 5; - } - - UpdateType type = 5; -} - -message WalletAccountBalance { - // The confirmed balance of the account (with >= 1 confirmations). - int64 confirmed_balance = 1; - - // The unconfirmed balance of the account (with 0 confirmations). - int64 unconfirmed_balance = 2; -} - -message WalletBalanceRequest { -} - -message WalletBalanceResponse { - // The balance of the wallet - int64 total_balance = 1; - - // The confirmed balance of a wallet(with >= 1 confirmations) - int64 confirmed_balance = 2; - - // The unconfirmed balance of a wallet(with 0 confirmations) - int64 unconfirmed_balance = 3; - - // The total amount of wallet UTXOs held in outputs that are locked for - // other usage. - int64 locked_balance = 5; - - // The amount of reserve required. - int64 reserved_balance_anchor_chan = 6; - - // A mapping of each wallet account's name to its balance. - map account_balance = 4; -} - -message Amount { - // Value denominated in satoshis. - uint64 sat = 1; - - // Value denominated in milli-satoshis. - uint64 msat = 2; -} - -message ChannelBalanceRequest { -} -message ChannelBalanceResponse { - // Deprecated. Sum of channels balances denominated in satoshis - int64 balance = 1 [deprecated = true]; - - // Deprecated. Sum of channels pending balances denominated in satoshis - int64 pending_open_balance = 2 [deprecated = true]; - - // Sum of channels local balances. - Amount local_balance = 3; - - // Sum of channels remote balances. - Amount remote_balance = 4; - - // Sum of channels local unsettled balances. - Amount unsettled_local_balance = 5; - - // Sum of channels remote unsettled balances. - Amount unsettled_remote_balance = 6; - - // Sum of channels pending local balances. - Amount pending_open_local_balance = 7; - - // Sum of channels pending remote balances. - Amount pending_open_remote_balance = 8; -} - -message QueryRoutesRequest { - // The 33-byte hex-encoded public key for the payment destination - string pub_key = 1; - - /* - The amount to send expressed in satoshis. - - The fields amt and amt_msat are mutually exclusive. - */ - int64 amt = 2; - - /* - The amount to send expressed in millisatoshis. - - The fields amt and amt_msat are mutually exclusive. - */ - int64 amt_msat = 12; - - reserved 3; - - /* - An optional CLTV delta from the current height that should be used for the - timelock of the final hop. Note that unlike SendPayment, QueryRoutes does - not add any additional block padding on top of final_ctlv_delta. This - padding of a few blocks needs to be added manually or otherwise failures may - happen when a block comes in while the payment is in flight. - */ - int32 final_cltv_delta = 4; - - /* - The maximum number of satoshis that will be paid as a fee of the payment. - This value can be represented either as a percentage of the amount being - sent, or as a fixed amount of the maximum fee the user is willing the pay to - send the payment. If not specified, lnd will use a default value of 100% - fees for small amounts (<=1k sat) or 5% fees for larger amounts. - */ - FeeLimit fee_limit = 5; - - /* - A list of nodes to ignore during path finding. When using REST, these fields - must be encoded as base64. - */ - repeated bytes ignored_nodes = 6; - - /* - Deprecated. A list of edges to ignore during path finding. - */ - repeated EdgeLocator ignored_edges = 7 [deprecated = true]; - - /* - The source node where the request route should originated from. If empty, - self is assumed. - */ - string source_pub_key = 8; - - /* - If set to true, edge probabilities from mission control will be used to get - the optimal route. - */ - bool use_mission_control = 9; - - /* - A list of directed node pairs that will be ignored during path finding. - */ - repeated NodePair ignored_pairs = 10; - - /* - An optional maximum total time lock for the route. If the source is empty or - ourselves, this should not exceed lnd's `--max-cltv-expiry` setting. If - zero, then the value of `--max-cltv-expiry` is used as the limit. - */ - uint32 cltv_limit = 11; - - /* - An optional field that can be used to pass an arbitrary set of TLV records - to a peer which understands the new records. This can be used to pass - application specific data during the payment attempt. If the destination - does not support the specified records, an error will be returned. - Record types are required to be in the custom range >= 65536. When using - REST, the values must be encoded as base64. - */ - map dest_custom_records = 13; - - /* - The channel id of the channel that must be taken to the first hop. If zero, - any channel may be used. - */ - uint64 outgoing_chan_id = 14 [jstype = JS_STRING]; - - /* - The pubkey of the last hop of the route. If empty, any hop may be used. - */ - bytes last_hop_pubkey = 15; - - /* - Optional route hints to reach the destination through private channels. - */ - repeated lnrpc.RouteHint route_hints = 16; - - /* - Features assumed to be supported by the final node. All transitive feature - dependencies must also be set properly. For a given feature bit pair, either - optional or remote may be set, but not both. If this field is nil or empty, - the router will try to load destination features from the graph as a - fallback. - */ - repeated lnrpc.FeatureBit dest_features = 17; - - /* - The time preference for this payment. Set to -1 to optimize for fees - only, to 1 to optimize for reliability only or a value inbetween for a mix. - */ - double time_pref = 18; -} - -message NodePair { - /* - The sending node of the pair. When using REST, this field must be encoded as - base64. - */ - bytes from = 1; - - /* - The receiving node of the pair. When using REST, this field must be encoded - as base64. - */ - bytes to = 2; -} - -message EdgeLocator { - // The short channel id of this edge. - uint64 channel_id = 1 [jstype = JS_STRING]; - - /* - The direction of this edge. If direction_reverse is false, the direction - of this edge is from the channel endpoint with the lexicographically smaller - pub key to the endpoint with the larger pub key. If direction_reverse is - is true, the edge goes the other way. - */ - bool direction_reverse = 2; -} - -message QueryRoutesResponse { - /* - The route that results from the path finding operation. This is still a - repeated field to retain backwards compatibility. - */ - repeated Route routes = 1; - - /* - The success probability of the returned route based on the current mission - control state. [EXPERIMENTAL] - */ - double success_prob = 2; -} - -message Hop { - /* - The unique channel ID for the channel. The first 3 bytes are the block - height, the next 3 the index within the block, and the last 2 bytes are the - output index for the channel. - */ - uint64 chan_id = 1 [jstype = JS_STRING]; - int64 chan_capacity = 2 [deprecated = true]; - int64 amt_to_forward = 3 [deprecated = true]; - int64 fee = 4 [deprecated = true]; - uint32 expiry = 5; - int64 amt_to_forward_msat = 6; - int64 fee_msat = 7; - - /* - An optional public key of the hop. If the public key is given, the payment - can be executed without relying on a copy of the channel graph. - */ - string pub_key = 8; - - /* - If set to true, then this hop will be encoded using the new variable length - TLV format. Note that if any custom tlv_records below are specified, then - this field MUST be set to true for them to be encoded properly. - */ - bool tlv_payload = 9 [deprecated = true]; - - /* - An optional TLV record that signals the use of an MPP payment. If present, - the receiver will enforce that the same mpp_record is included in the final - hop payload of all non-zero payments in the HTLC set. If empty, a regular - single-shot payment is or was attempted. - */ - MPPRecord mpp_record = 10; - - /* - An optional TLV record that signals the use of an AMP payment. If present, - the receiver will treat all received payments including the same - (payment_addr, set_id) pair as being part of one logical payment. The - payment will be settled by XORing the root_share's together and deriving the - child hashes and preimages according to BOLT XX. Must be used in conjunction - with mpp_record. - */ - AMPRecord amp_record = 12; - - /* - An optional set of key-value TLV records. This is useful within the context - of the SendToRoute call as it allows callers to specify arbitrary K-V pairs - to drop off at each hop within the onion. - */ - map custom_records = 11; - - // The payment metadata to send along with the payment to the payee. - bytes metadata = 13; -} - -message MPPRecord { - /* - A unique, random identifier used to authenticate the sender as the intended - payer of a multi-path payment. The payment_addr must be the same for all - subpayments, and match the payment_addr provided in the receiver's invoice. - The same payment_addr must be used on all subpayments. - */ - bytes payment_addr = 11; - - /* - The total amount in milli-satoshis being sent as part of a larger multi-path - payment. The caller is responsible for ensuring subpayments to the same node - and payment_hash sum exactly to total_amt_msat. The same - total_amt_msat must be used on all subpayments. - */ - int64 total_amt_msat = 10; -} - -message AMPRecord { - bytes root_share = 1; - - bytes set_id = 2; - - uint32 child_index = 3; -} - -/* -A path through the channel graph which runs over one or more channels in -succession. This struct carries all the information required to craft the -Sphinx onion packet, and send the payment along the first hop in the path. A -route is only selected as valid if all the channels have sufficient capacity to -carry the initial payment amount after fees are accounted for. -*/ -message Route { - /* - The cumulative (final) time lock across the entire route. This is the CLTV - value that should be extended to the first hop in the route. All other hops - will decrement the time-lock as advertised, leaving enough time for all - hops to wait for or present the payment preimage to complete the payment. - */ - uint32 total_time_lock = 1; - - /* - The sum of the fees paid at each hop within the final route. In the case - of a one-hop payment, this value will be zero as we don't need to pay a fee - to ourselves. - */ - int64 total_fees = 2 [deprecated = true]; - - /* - The total amount of funds required to complete a payment over this route. - This value includes the cumulative fees at each hop. As a result, the HTLC - extended to the first-hop in the route will need to have at least this many - satoshis, otherwise the route will fail at an intermediate node due to an - insufficient amount of fees. - */ - int64 total_amt = 3 [deprecated = true]; - - /* - Contains details concerning the specific forwarding details at each hop. - */ - repeated Hop hops = 4; - - /* - The total fees in millisatoshis. - */ - int64 total_fees_msat = 5; - - /* - The total amount in millisatoshis. - */ - int64 total_amt_msat = 6; -} - -message NodeInfoRequest { - // The 33-byte hex-encoded compressed public of the target node - string pub_key = 1; - - // If true, will include all known channels associated with the node. - bool include_channels = 2; -} - -message NodeInfo { - /* - An individual vertex/node within the channel graph. A node is - connected to other nodes by one or more channel edges emanating from it. As - the graph is directed, a node will also have an incoming edge attached to - it for each outgoing edge. - */ - LightningNode node = 1; - - // The total number of channels for the node. - uint32 num_channels = 2; - - // The sum of all channels capacity for the node, denominated in satoshis. - int64 total_capacity = 3; - - // A list of all public channels for the node. - repeated ChannelEdge channels = 4; -} - -/* -An individual vertex/node within the channel graph. A node is -connected to other nodes by one or more channel edges emanating from it. As the -graph is directed, a node will also have an incoming edge attached to it for -each outgoing edge. -*/ -message LightningNode { - uint32 last_update = 1; - string pub_key = 2; - string alias = 3; - repeated NodeAddress addresses = 4; - string color = 5; - map features = 6; -} - -message NodeAddress { - string network = 1; - string addr = 2; -} - -message RoutingPolicy { - uint32 time_lock_delta = 1; - int64 min_htlc = 2; - int64 fee_base_msat = 3; - int64 fee_rate_milli_msat = 4; - bool disabled = 5; - uint64 max_htlc_msat = 6; - uint32 last_update = 7; -} - -/* -A fully authenticated channel along with all its unique attributes. -Once an authenticated channel announcement has been processed on the network, -then an instance of ChannelEdgeInfo encapsulating the channels attributes is -stored. The other portions relevant to routing policy of a channel are stored -within a ChannelEdgePolicy for each direction of the channel. -*/ -message ChannelEdge { - /* - The unique channel ID for the channel. The first 3 bytes are the block - height, the next 3 the index within the block, and the last 2 bytes are the - output index for the channel. - */ - uint64 channel_id = 1 [jstype = JS_STRING]; - string chan_point = 2; - - uint32 last_update = 3 [deprecated = true]; - - string node1_pub = 4; - string node2_pub = 5; - - int64 capacity = 6; - - RoutingPolicy node1_policy = 7; - RoutingPolicy node2_policy = 8; -} - -message ChannelGraphRequest { - /* - Whether unannounced channels are included in the response or not. If set, - unannounced channels are included. Unannounced channels are both private - channels, and public channels that are not yet announced to the network. - */ - bool include_unannounced = 1; -} - -// Returns a new instance of the directed channel graph. -message ChannelGraph { - // The list of `LightningNode`s in this channel graph - repeated LightningNode nodes = 1; - - // The list of `ChannelEdge`s in this channel graph - repeated ChannelEdge edges = 2; -} - -enum NodeMetricType { - UNKNOWN = 0; - BETWEENNESS_CENTRALITY = 1; -} - -message NodeMetricsRequest { - // The requested node metrics. - repeated NodeMetricType types = 1; -} - -message NodeMetricsResponse { - /* - Betweenness centrality is the sum of the ratio of shortest paths that pass - through the node for each pair of nodes in the graph (not counting paths - starting or ending at this node). - Map of node pubkey to betweenness centrality of the node. Normalized - values are in the [0,1] closed interval. - */ - map betweenness_centrality = 1; -} - -message FloatMetric { - // Arbitrary float value. - double value = 1; - - // The value normalized to [0,1] or [-1,1]. - double normalized_value = 2; -} - -message ChanInfoRequest { - /* - The unique channel ID for the channel. The first 3 bytes are the block - height, the next 3 the index within the block, and the last 2 bytes are the - output index for the channel. - */ - uint64 chan_id = 1 [jstype = JS_STRING]; -} - -message NetworkInfoRequest { -} -message NetworkInfo { - uint32 graph_diameter = 1; - double avg_out_degree = 2; - uint32 max_out_degree = 3; - - uint32 num_nodes = 4; - uint32 num_channels = 5; - - int64 total_network_capacity = 6; - - double avg_channel_size = 7; - int64 min_channel_size = 8; - int64 max_channel_size = 9; - int64 median_channel_size_sat = 10; - - // The number of edges marked as zombies. - uint64 num_zombie_chans = 11; - - // TODO(roasbeef): fee rate info, expiry - // * also additional RPC for tracking fee info once in -} - -message StopRequest { -} -message StopResponse { -} - -message GraphTopologySubscription { -} -message GraphTopologyUpdate { - repeated NodeUpdate node_updates = 1; - repeated ChannelEdgeUpdate channel_updates = 2; - repeated ClosedChannelUpdate closed_chans = 3; -} -message NodeUpdate { - /* - Deprecated, use node_addresses. - */ - repeated string addresses = 1 [deprecated = true]; - - string identity_key = 2; - - /* - Deprecated, use features. - */ - bytes global_features = 3 [deprecated = true]; - - string alias = 4; - string color = 5; - repeated NodeAddress node_addresses = 7; - - /* - Features that the node has advertised in the init message, node - announcements and invoices. - */ - map features = 6; -} -message ChannelEdgeUpdate { - /* - The unique channel ID for the channel. The first 3 bytes are the block - height, the next 3 the index within the block, and the last 2 bytes are the - output index for the channel. - */ - uint64 chan_id = 1 [jstype = JS_STRING]; - - ChannelPoint chan_point = 2; - - int64 capacity = 3; - - RoutingPolicy routing_policy = 4; - - string advertising_node = 5; - string connecting_node = 6; -} -message ClosedChannelUpdate { - /* - The unique channel ID for the channel. The first 3 bytes are the block - height, the next 3 the index within the block, and the last 2 bytes are the - output index for the channel. - */ - uint64 chan_id = 1 [jstype = JS_STRING]; - int64 capacity = 2; - uint32 closed_height = 3; - ChannelPoint chan_point = 4; -} - -message HopHint { - // The public key of the node at the start of the channel. - string node_id = 1; - - // The unique identifier of the channel. - uint64 chan_id = 2 [jstype = JS_STRING]; - - // The base fee of the channel denominated in millisatoshis. - uint32 fee_base_msat = 3; - - /* - The fee rate of the channel for sending one satoshi across it denominated in - millionths of a satoshi. - */ - uint32 fee_proportional_millionths = 4; - - // The time-lock delta of the channel. - uint32 cltv_expiry_delta = 5; -} - -message SetID { - bytes set_id = 1; -} - -message RouteHint { - /* - A list of hop hints that when chained together can assist in reaching a - specific destination. - */ - repeated HopHint hop_hints = 1; -} - -message AMPInvoiceState { - // The state the HTLCs associated with this setID are in. - InvoiceHTLCState state = 1; - - // The settle index of this HTLC set, if the invoice state is settled. - uint64 settle_index = 2; - - // The time this HTLC set was settled expressed in unix epoch. - int64 settle_time = 3; - - // The total amount paid for the sub-invoice expressed in milli satoshis. - int64 amt_paid_msat = 5; -} - -message Invoice { - /* - An optional memo to attach along with the invoice. Used for record keeping - purposes for the invoice's creator, and will also be set in the description - field of the encoded payment request if the description_hash field is not - being used. - */ - string memo = 1; - - reserved 2; - - /* - The hex-encoded preimage (32 byte) which will allow settling an incoming - HTLC payable to this preimage. When using REST, this field must be encoded - as base64. - */ - bytes r_preimage = 3; - - /* - The hash of the preimage. When using REST, this field must be encoded as - base64. - Note: Output only, don't specify for creating an invoice. - */ - bytes r_hash = 4; - - /* - The value of this invoice in satoshis - - The fields value and value_msat are mutually exclusive. - */ - int64 value = 5; - - /* - The value of this invoice in millisatoshis - - The fields value and value_msat are mutually exclusive. - */ - int64 value_msat = 23; - - /* - Whether this invoice has been fulfilled - - The field is deprecated. Use the state field instead (compare to SETTLED). - */ - bool settled = 6 [deprecated = true]; - - /* - When this invoice was created. - Note: Output only, don't specify for creating an invoice. - */ - int64 creation_date = 7; - - /* - When this invoice was settled. - Note: Output only, don't specify for creating an invoice. - */ - int64 settle_date = 8; - - /* - A bare-bones invoice for a payment within the Lightning Network. With the - details of the invoice, the sender has all the data necessary to send a - payment to the recipient. - Note: Output only, don't specify for creating an invoice. - */ - string payment_request = 9; - - /* - Hash (SHA-256) of a description of the payment. Used if the description of - payment (memo) is too long to naturally fit within the description field - of an encoded payment request. When using REST, this field must be encoded - as base64. - */ - bytes description_hash = 10; - - // Payment request expiry time in seconds. Default is 3600 (1 hour). - int64 expiry = 11; - - // Fallback on-chain address. - string fallback_addr = 12; - - // Delta to use for the time-lock of the CLTV extended to the final hop. - uint64 cltv_expiry = 13; - - /* - Route hints that can each be individually used to assist in reaching the - invoice's destination. - */ - repeated RouteHint route_hints = 14; - - // Whether this invoice should include routing hints for private channels. - bool private = 15; - - /* - The "add" index of this invoice. Each newly created invoice will increment - this index making it monotonically increasing. Callers to the - SubscribeInvoices call can use this to instantly get notified of all added - invoices with an add_index greater than this one. - Note: Output only, don't specify for creating an invoice. - */ - uint64 add_index = 16; - - /* - The "settle" index of this invoice. Each newly settled invoice will - increment this index making it monotonically increasing. Callers to the - SubscribeInvoices call can use this to instantly get notified of all - settled invoices with an settle_index greater than this one. - Note: Output only, don't specify for creating an invoice. - */ - uint64 settle_index = 17; - - // Deprecated, use amt_paid_sat or amt_paid_msat. - int64 amt_paid = 18 [deprecated = true]; - - /* - The amount that was accepted for this invoice, in satoshis. This will ONLY - be set if this invoice has been settled. We provide this field as if the - invoice was created with a zero value, then we need to record what amount - was ultimately accepted. Additionally, it's possible that the sender paid - MORE that was specified in the original invoice. So we'll record that here - as well. - Note: Output only, don't specify for creating an invoice. - */ - int64 amt_paid_sat = 19; - - /* - The amount that was accepted for this invoice, in millisatoshis. This will - ONLY be set if this invoice has been settled. We provide this field as if - the invoice was created with a zero value, then we need to record what - amount was ultimately accepted. Additionally, it's possible that the sender - paid MORE that was specified in the original invoice. So we'll record that - here as well. - Note: Output only, don't specify for creating an invoice. - */ - int64 amt_paid_msat = 20; - - enum InvoiceState { - OPEN = 0; - SETTLED = 1; - CANCELED = 2; - ACCEPTED = 3; - } - - /* - The state the invoice is in. - Note: Output only, don't specify for creating an invoice. - */ - InvoiceState state = 21; - - /* - List of HTLCs paying to this invoice [EXPERIMENTAL]. - Note: Output only, don't specify for creating an invoice. - */ - repeated InvoiceHTLC htlcs = 22; - - /* - List of features advertised on the invoice. - Note: Output only, don't specify for creating an invoice. - */ - map features = 24; - - /* - Indicates if this invoice was a spontaneous payment that arrived via keysend - [EXPERIMENTAL]. - Note: Output only, don't specify for creating an invoice. - */ - bool is_keysend = 25; - - /* - The payment address of this invoice. This value will be used in MPP - payments, and also for newer invoices that always require the MPP payload - for added end-to-end security. - Note: Output only, don't specify for creating an invoice. - */ - bytes payment_addr = 26; - - /* - Signals whether or not this is an AMP invoice. - */ - bool is_amp = 27; - - /* - [EXPERIMENTAL]: - - Maps a 32-byte hex-encoded set ID to the sub-invoice AMP state for the - given set ID. This field is always populated for AMP invoices, and can be - used along side LookupInvoice to obtain the HTLC information related to a - given sub-invoice. - Note: Output only, don't specify for creating an invoice. - */ - map amp_invoice_state = 28; -} - -enum InvoiceHTLCState { - ACCEPTED = 0; - SETTLED = 1; - CANCELED = 2; -} - -// Details of an HTLC that paid to an invoice -message InvoiceHTLC { - // Short channel id over which the htlc was received. - uint64 chan_id = 1 [jstype = JS_STRING]; - - // Index identifying the htlc on the channel. - uint64 htlc_index = 2; - - // The amount of the htlc in msat. - uint64 amt_msat = 3; - - // Block height at which this htlc was accepted. - int32 accept_height = 4; - - // Time at which this htlc was accepted. - int64 accept_time = 5; - - // Time at which this htlc was settled or canceled. - int64 resolve_time = 6; - - // Block height at which this htlc expires. - int32 expiry_height = 7; - - // Current state the htlc is in. - InvoiceHTLCState state = 8; - - // Custom tlv records. - map custom_records = 9; - - // The total amount of the mpp payment in msat. - uint64 mpp_total_amt_msat = 10; - - // Details relevant to AMP HTLCs, only populated if this is an AMP HTLC. - AMP amp = 11; -} - -// Details specific to AMP HTLCs. -message AMP { - // An n-of-n secret share of the root seed from which child payment hashes - // and preimages are derived. - bytes root_share = 1; - - // An identifier for the HTLC set that this HTLC belongs to. - bytes set_id = 2; - - // A nonce used to randomize the child preimage and child hash from a given - // root_share. - uint32 child_index = 3; - - // The payment hash of the AMP HTLC. - bytes hash = 4; - - // The preimage used to settle this AMP htlc. This field will only be - // populated if the invoice is in InvoiceState_ACCEPTED or - // InvoiceState_SETTLED. - bytes preimage = 5; -} - -message AddInvoiceResponse { - bytes r_hash = 1; - - /* - A bare-bones invoice for a payment within the Lightning Network. With the - details of the invoice, the sender has all the data necessary to send a - payment to the recipient. - */ - string payment_request = 2; - - /* - The "add" index of this invoice. Each newly created invoice will increment - this index making it monotonically increasing. Callers to the - SubscribeInvoices call can use this to instantly get notified of all added - invoices with an add_index greater than this one. - */ - uint64 add_index = 16; - - /* - The payment address of the generated invoice. This value should be used - in all payments for this invoice as we require it for end to end - security. - */ - bytes payment_addr = 17; -} -message PaymentHash { - /* - The hex-encoded payment hash of the invoice to be looked up. The passed - payment hash must be exactly 32 bytes, otherwise an error is returned. - Deprecated now that the REST gateway supports base64 encoding of bytes - fields. - */ - string r_hash_str = 1 [deprecated = true]; - - /* - The payment hash of the invoice to be looked up. When using REST, this field - must be encoded as base64. - */ - bytes r_hash = 2; -} - -message ListInvoiceRequest { - /* - If set, only invoices that are not settled and not canceled will be returned - in the response. - */ - bool pending_only = 1; - - /* - The index of an invoice that will be used as either the start or end of a - query to determine which invoices should be returned in the response. - */ - uint64 index_offset = 4; - - // The max number of invoices to return in the response to this query. - uint64 num_max_invoices = 5; - - /* - If set, the invoices returned will result from seeking backwards from the - specified index offset. This can be used to paginate backwards. - */ - bool reversed = 6; -} -message ListInvoiceResponse { - /* - A list of invoices from the time slice of the time series specified in the - request. - */ - repeated Invoice invoices = 1; - - /* - The index of the last item in the set of returned invoices. This can be used - to seek further, pagination style. - */ - uint64 last_index_offset = 2; - - /* - The index of the last item in the set of returned invoices. This can be used - to seek backwards, pagination style. - */ - uint64 first_index_offset = 3; -} - -message InvoiceSubscription { - /* - If specified (non-zero), then we'll first start by sending out - notifications for all added indexes with an add_index greater than this - value. This allows callers to catch up on any events they missed while they - weren't connected to the streaming RPC. - */ - uint64 add_index = 1; - - /* - If specified (non-zero), then we'll first start by sending out - notifications for all settled indexes with an settle_index greater than - this value. This allows callers to catch up on any events they missed while - they weren't connected to the streaming RPC. - */ - uint64 settle_index = 2; -} - -enum PaymentFailureReason { - /* - Payment isn't failed (yet). - */ - FAILURE_REASON_NONE = 0; - - /* - There are more routes to try, but the payment timeout was exceeded. - */ - FAILURE_REASON_TIMEOUT = 1; - - /* - All possible routes were tried and failed permanently. Or were no - routes to the destination at all. - */ - FAILURE_REASON_NO_ROUTE = 2; - - /* - A non-recoverable error has occured. - */ - FAILURE_REASON_ERROR = 3; - - /* - Payment details incorrect (unknown hash, invalid amt or - invalid final cltv delta) - */ - FAILURE_REASON_INCORRECT_PAYMENT_DETAILS = 4; - - /* - Insufficient local balance. - */ - FAILURE_REASON_INSUFFICIENT_BALANCE = 5; -} - -message Payment { - // The payment hash - string payment_hash = 1; - - // Deprecated, use value_sat or value_msat. - int64 value = 2 [deprecated = true]; - - // Deprecated, use creation_time_ns - int64 creation_date = 3 [deprecated = true]; - - reserved 4; - - // Deprecated, use fee_sat or fee_msat. - int64 fee = 5 [deprecated = true]; - - // The payment preimage - string payment_preimage = 6; - - // The value of the payment in satoshis - int64 value_sat = 7; - - // The value of the payment in milli-satoshis - int64 value_msat = 8; - - // The optional payment request being fulfilled. - string payment_request = 9; - - enum PaymentStatus { - UNKNOWN = 0; - IN_FLIGHT = 1; - SUCCEEDED = 2; - FAILED = 3; - } - - // The status of the payment. - PaymentStatus status = 10; - - // The fee paid for this payment in satoshis - int64 fee_sat = 11; - - // The fee paid for this payment in milli-satoshis - int64 fee_msat = 12; - - // The time in UNIX nanoseconds at which the payment was created. - int64 creation_time_ns = 13; - - // The HTLCs made in attempt to settle the payment. - repeated HTLCAttempt htlcs = 14; - - /* - The creation index of this payment. Each payment can be uniquely identified - by this index, which may not strictly increment by 1 for payments made in - older versions of lnd. - */ - uint64 payment_index = 15; - - PaymentFailureReason failure_reason = 16; -} - -message HTLCAttempt { - // The unique ID that is used for this attempt. - uint64 attempt_id = 7; - - enum HTLCStatus { - IN_FLIGHT = 0; - SUCCEEDED = 1; - FAILED = 2; - } - - // The status of the HTLC. - HTLCStatus status = 1; - - // The route taken by this HTLC. - Route route = 2; - - // The time in UNIX nanoseconds at which this HTLC was sent. - int64 attempt_time_ns = 3; - - /* - The time in UNIX nanoseconds at which this HTLC was settled or failed. - This value will not be set if the HTLC is still IN_FLIGHT. - */ - int64 resolve_time_ns = 4; - - // Detailed htlc failure info. - Failure failure = 5; - - // The preimage that was used to settle the HTLC. - bytes preimage = 6; -} - -message ListPaymentsRequest { - /* - If true, then return payments that have not yet fully completed. This means - that pending payments, as well as failed payments will show up if this - field is set to true. This flag doesn't change the meaning of the indices, - which are tied to individual payments. - */ - bool include_incomplete = 1; - - /* - The index of a payment that will be used as either the start or end of a - query to determine which payments should be returned in the response. The - index_offset is exclusive. In the case of a zero index_offset, the query - will start with the oldest payment when paginating forwards, or will end - with the most recent payment when paginating backwards. - */ - uint64 index_offset = 2; - - // The maximal number of payments returned in the response to this query. - uint64 max_payments = 3; - - /* - If set, the payments returned will result from seeking backwards from the - specified index offset. This can be used to paginate backwards. The order - of the returned payments is always oldest first (ascending index order). - */ - bool reversed = 4; - - /* - If set, all payments (complete and incomplete, independent of the - max_payments parameter) will be counted. Note that setting this to true will - increase the run time of the call significantly on systems that have a lot - of payments, as all of them have to be iterated through to be counted. - */ - bool count_total_payments = 5; -} - -message ListPaymentsResponse { - // The list of payments - repeated Payment payments = 1; - - /* - The index of the first item in the set of returned payments. This can be - used as the index_offset to continue seeking backwards in the next request. - */ - uint64 first_index_offset = 2; - - /* - The index of the last item in the set of returned payments. This can be used - as the index_offset to continue seeking forwards in the next request. - */ - uint64 last_index_offset = 3; - - /* - Will only be set if count_total_payments in the request was set. Represents - the total number of payments (complete and incomplete, independent of the - number of payments requested in the query) currently present in the payments - database. - */ - uint64 total_num_payments = 4; -} - -message DeletePaymentRequest { - // Payment hash to delete. - bytes payment_hash = 1; - - /* - Only delete failed HTLCs from the payment, not the payment itself. - */ - bool failed_htlcs_only = 2; -} - -message DeleteAllPaymentsRequest { - // Only delete failed payments. - bool failed_payments_only = 1; - - /* - Only delete failed HTLCs from payments, not the payment itself. - */ - bool failed_htlcs_only = 2; -} - -message DeletePaymentResponse { -} - -message DeleteAllPaymentsResponse { -} - -message AbandonChannelRequest { - ChannelPoint channel_point = 1; - - bool pending_funding_shim_only = 2; - - /* - Override the requirement for being in dev mode by setting this to true and - confirming the user knows what they are doing and this is a potential foot - gun to lose funds if used on active channels. - */ - bool i_know_what_i_am_doing = 3; -} - -message AbandonChannelResponse { -} - -message DebugLevelRequest { - bool show = 1; - string level_spec = 2; -} -message DebugLevelResponse { - string sub_systems = 1; -} - -message PayReqString { - // The payment request string to be decoded - string pay_req = 1; -} -message PayReq { - string destination = 1; - string payment_hash = 2; - int64 num_satoshis = 3; - int64 timestamp = 4; - int64 expiry = 5; - string description = 6; - string description_hash = 7; - string fallback_addr = 8; - int64 cltv_expiry = 9; - repeated RouteHint route_hints = 10; - bytes payment_addr = 11; - int64 num_msat = 12; - map features = 13; -} - -enum FeatureBit { - DATALOSS_PROTECT_REQ = 0; - DATALOSS_PROTECT_OPT = 1; - INITIAL_ROUING_SYNC = 3; - UPFRONT_SHUTDOWN_SCRIPT_REQ = 4; - UPFRONT_SHUTDOWN_SCRIPT_OPT = 5; - GOSSIP_QUERIES_REQ = 6; - GOSSIP_QUERIES_OPT = 7; - TLV_ONION_REQ = 8; - TLV_ONION_OPT = 9; - EXT_GOSSIP_QUERIES_REQ = 10; - EXT_GOSSIP_QUERIES_OPT = 11; - STATIC_REMOTE_KEY_REQ = 12; - STATIC_REMOTE_KEY_OPT = 13; - PAYMENT_ADDR_REQ = 14; - PAYMENT_ADDR_OPT = 15; - MPP_REQ = 16; - MPP_OPT = 17; - WUMBO_CHANNELS_REQ = 18; - WUMBO_CHANNELS_OPT = 19; - ANCHORS_REQ = 20; - ANCHORS_OPT = 21; - ANCHORS_ZERO_FEE_HTLC_REQ = 22; - ANCHORS_ZERO_FEE_HTLC_OPT = 23; - AMP_REQ = 30; - AMP_OPT = 31; -} - -message Feature { - string name = 2; - bool is_required = 3; - bool is_known = 4; -} - -message FeeReportRequest { -} -message ChannelFeeReport { - // The short channel id that this fee report belongs to. - uint64 chan_id = 5 [jstype = JS_STRING]; - - // The channel that this fee report belongs to. - string channel_point = 1; - - // The base fee charged regardless of the number of milli-satoshis sent. - int64 base_fee_msat = 2; - - // The amount charged per milli-satoshis transferred expressed in - // millionths of a satoshi. - int64 fee_per_mil = 3; - - // The effective fee rate in milli-satoshis. Computed by dividing the - // fee_per_mil value by 1 million. - double fee_rate = 4; -} -message FeeReportResponse { - // An array of channel fee reports which describes the current fee schedule - // for each channel. - repeated ChannelFeeReport channel_fees = 1; - - // The total amount of fee revenue (in satoshis) the switch has collected - // over the past 24 hrs. - uint64 day_fee_sum = 2; - - // The total amount of fee revenue (in satoshis) the switch has collected - // over the past 1 week. - uint64 week_fee_sum = 3; - - // The total amount of fee revenue (in satoshis) the switch has collected - // over the past 1 month. - uint64 month_fee_sum = 4; -} - -message PolicyUpdateRequest { - oneof scope { - // If set, then this update applies to all currently active channels. - bool global = 1; - - // If set, this update will target a specific channel. - ChannelPoint chan_point = 2; - } - - // The base fee charged regardless of the number of milli-satoshis sent. - int64 base_fee_msat = 3; - - // The effective fee rate in milli-satoshis. The precision of this value - // goes up to 6 decimal places, so 1e-6. - double fee_rate = 4; - - // The effective fee rate in micro-satoshis (parts per million). - uint32 fee_rate_ppm = 9; - - // The required timelock delta for HTLCs forwarded over the channel. - uint32 time_lock_delta = 5; - - // If set, the maximum HTLC size in milli-satoshis. If unset, the maximum - // HTLC will be unchanged. - uint64 max_htlc_msat = 6; - - // The minimum HTLC size in milli-satoshis. Only applied if - // min_htlc_msat_specified is true. - uint64 min_htlc_msat = 7; - - // If true, min_htlc_msat is applied. - bool min_htlc_msat_specified = 8; -} -enum UpdateFailure { - UPDATE_FAILURE_UNKNOWN = 0; - UPDATE_FAILURE_PENDING = 1; - UPDATE_FAILURE_NOT_FOUND = 2; - UPDATE_FAILURE_INTERNAL_ERR = 3; - UPDATE_FAILURE_INVALID_PARAMETER = 4; -} - -message FailedUpdate { - // The outpoint in format txid:n - OutPoint outpoint = 1; - - // Reason for the policy update failure. - UpdateFailure reason = 2; - - // A string representation of the policy update error. - string update_error = 3; -} - -message PolicyUpdateResponse { - // List of failed policy updates. - repeated FailedUpdate failed_updates = 1; -} - -message ForwardingHistoryRequest { - // Start time is the starting point of the forwarding history request. All - // records beyond this point will be included, respecting the end time, and - // the index offset. - uint64 start_time = 1; - - // End time is the end point of the forwarding history request. The - // response will carry at most 50k records between the start time and the - // end time. The index offset can be used to implement pagination. - uint64 end_time = 2; - - // Index offset is the offset in the time series to start at. As each - // response can only contain 50k records, callers can use this to skip - // around within a packed time series. - uint32 index_offset = 3; - - // The max number of events to return in the response to this query. - uint32 num_max_events = 4; -} -message ForwardingEvent { - // Timestamp is the time (unix epoch offset) that this circuit was - // completed. Deprecated by timestamp_ns. - uint64 timestamp = 1 [deprecated = true]; - - // The incoming channel ID that carried the HTLC that created the circuit. - uint64 chan_id_in = 2 [jstype = JS_STRING]; - - // The outgoing channel ID that carried the preimage that completed the - // circuit. - uint64 chan_id_out = 4 [jstype = JS_STRING]; - - // The total amount (in satoshis) of the incoming HTLC that created half - // the circuit. - uint64 amt_in = 5; - - // The total amount (in satoshis) of the outgoing HTLC that created the - // second half of the circuit. - uint64 amt_out = 6; - - // The total fee (in satoshis) that this payment circuit carried. - uint64 fee = 7; - - // The total fee (in milli-satoshis) that this payment circuit carried. - uint64 fee_msat = 8; - - // The total amount (in milli-satoshis) of the incoming HTLC that created - // half the circuit. - uint64 amt_in_msat = 9; - - // The total amount (in milli-satoshis) of the outgoing HTLC that created - // the second half of the circuit. - uint64 amt_out_msat = 10; - - // The number of nanoseconds elapsed since January 1, 1970 UTC when this - // circuit was completed. - uint64 timestamp_ns = 11; - - // TODO(roasbeef): add settlement latency? - // * use FPE on the chan id? - // * also list failures? -} -message ForwardingHistoryResponse { - // A list of forwarding events from the time slice of the time series - // specified in the request. - repeated ForwardingEvent forwarding_events = 1; - - // The index of the last time in the set of returned forwarding events. Can - // be used to seek further, pagination style. - uint32 last_offset_index = 2; -} - -message ExportChannelBackupRequest { - // The target channel point to obtain a back up for. - ChannelPoint chan_point = 1; -} - -message ChannelBackup { - /* - Identifies the channel that this backup belongs to. - */ - ChannelPoint chan_point = 1; - - /* - Is an encrypted single-chan backup. this can be passed to - RestoreChannelBackups, or the WalletUnlocker Init and Unlock methods in - order to trigger the recovery protocol. When using REST, this field must be - encoded as base64. - */ - bytes chan_backup = 2; -} - -message MultiChanBackup { - /* - Is the set of all channels that are included in this multi-channel backup. - */ - repeated ChannelPoint chan_points = 1; - - /* - A single encrypted blob containing all the static channel backups of the - channel listed above. This can be stored as a single file or blob, and - safely be replaced with any prior/future versions. When using REST, this - field must be encoded as base64. - */ - bytes multi_chan_backup = 2; -} - -message ChanBackupExportRequest { -} -message ChanBackupSnapshot { - /* - The set of new channels that have been added since the last channel backup - snapshot was requested. - */ - ChannelBackups single_chan_backups = 1; - - /* - A multi-channel backup that covers all open channels currently known to - lnd. - */ - MultiChanBackup multi_chan_backup = 2; -} - -message ChannelBackups { - /* - A set of single-chan static channel backups. - */ - repeated ChannelBackup chan_backups = 1; -} - -message RestoreChanBackupRequest { - oneof backup { - /* - The channels to restore as a list of channel/backup pairs. - */ - ChannelBackups chan_backups = 1; - - /* - The channels to restore in the packed multi backup format. When using - REST, this field must be encoded as base64. - */ - bytes multi_chan_backup = 2; - } -} -message RestoreBackupResponse { -} - -message ChannelBackupSubscription { -} - -message VerifyChanBackupResponse { -} - -message MacaroonPermission { - // The entity a permission grants access to. - string entity = 1; - - // The action that is granted. - string action = 2; -} -message BakeMacaroonRequest { - // The list of permissions the new macaroon should grant. - repeated MacaroonPermission permissions = 1; - - // The root key ID used to create the macaroon, must be a positive integer. - uint64 root_key_id = 2; - - /* - Informs the RPC on whether to allow external permissions that LND is not - aware of. - */ - bool allow_external_permissions = 3; -} -message BakeMacaroonResponse { - // The hex encoded macaroon, serialized in binary format. - string macaroon = 1; -} - -message ListMacaroonIDsRequest { -} -message ListMacaroonIDsResponse { - // The list of root key IDs that are in use. - repeated uint64 root_key_ids = 1; -} - -message DeleteMacaroonIDRequest { - // The root key ID to be removed. - uint64 root_key_id = 1; -} -message DeleteMacaroonIDResponse { - // A boolean indicates that the deletion is successful. - bool deleted = 1; -} - -message MacaroonPermissionList { - // A list of macaroon permissions. - repeated MacaroonPermission permissions = 1; -} - -message ListPermissionsRequest { -} -message ListPermissionsResponse { - /* - A map between all RPC method URIs and their required macaroon permissions to - access them. - */ - map method_permissions = 1; -} - -message Failure { - enum FailureCode { - /* - The numbers assigned in this enumeration match the failure codes as - defined in BOLT #4. Because protobuf 3 requires enums to start with 0, - a RESERVED value is added. - */ - RESERVED = 0; - - INCORRECT_OR_UNKNOWN_PAYMENT_DETAILS = 1; - INCORRECT_PAYMENT_AMOUNT = 2; - FINAL_INCORRECT_CLTV_EXPIRY = 3; - FINAL_INCORRECT_HTLC_AMOUNT = 4; - FINAL_EXPIRY_TOO_SOON = 5; - INVALID_REALM = 6; - EXPIRY_TOO_SOON = 7; - INVALID_ONION_VERSION = 8; - INVALID_ONION_HMAC = 9; - INVALID_ONION_KEY = 10; - AMOUNT_BELOW_MINIMUM = 11; - FEE_INSUFFICIENT = 12; - INCORRECT_CLTV_EXPIRY = 13; - CHANNEL_DISABLED = 14; - TEMPORARY_CHANNEL_FAILURE = 15; - REQUIRED_NODE_FEATURE_MISSING = 16; - REQUIRED_CHANNEL_FEATURE_MISSING = 17; - UNKNOWN_NEXT_PEER = 18; - TEMPORARY_NODE_FAILURE = 19; - PERMANENT_NODE_FAILURE = 20; - PERMANENT_CHANNEL_FAILURE = 21; - EXPIRY_TOO_FAR = 22; - MPP_TIMEOUT = 23; - INVALID_ONION_PAYLOAD = 24; - - /* - An internal error occurred. - */ - INTERNAL_FAILURE = 997; - - /* - The error source is known, but the failure itself couldn't be decoded. - */ - UNKNOWN_FAILURE = 998; - - /* - An unreadable failure result is returned if the received failure message - cannot be decrypted. In that case the error source is unknown. - */ - UNREADABLE_FAILURE = 999; - } - - // Failure code as defined in the Lightning spec - FailureCode code = 1; - - reserved 2; - - // An optional channel update message. - ChannelUpdate channel_update = 3; - - // A failure type-dependent htlc value. - uint64 htlc_msat = 4; - - // The sha256 sum of the onion payload. - bytes onion_sha_256 = 5; - - // A failure type-dependent cltv expiry value. - uint32 cltv_expiry = 6; - - // A failure type-dependent flags value. - uint32 flags = 7; - - /* - The position in the path of the intermediate or final node that generated - the failure message. Position zero is the sender node. - **/ - uint32 failure_source_index = 8; - - // A failure type-dependent block height. - uint32 height = 9; -} - -message ChannelUpdate { - /* - The signature that validates the announced data and proves the ownership - of node id. - */ - bytes signature = 1; - - /* - The target chain that this channel was opened within. This value - should be the genesis hash of the target chain. Along with the short - channel ID, this uniquely identifies the channel globally in a - blockchain. - */ - bytes chain_hash = 2; - - /* - The unique description of the funding transaction. - */ - uint64 chan_id = 3 [jstype = JS_STRING]; - - /* - A timestamp that allows ordering in the case of multiple announcements. - We should ignore the message if timestamp is not greater than the - last-received. - */ - uint32 timestamp = 4; - - /* - The bitfield that describes whether optional fields are present in this - update. Currently, the least-significant bit must be set to 1 if the - optional field MaxHtlc is present. - */ - uint32 message_flags = 10; - - /* - The bitfield that describes additional meta-data concerning how the - update is to be interpreted. Currently, the least-significant bit must be - set to 0 if the creating node corresponds to the first node in the - previously sent channel announcement and 1 otherwise. If the second bit - is set, then the channel is set to be disabled. - */ - uint32 channel_flags = 5; - - /* - The minimum number of blocks this node requires to be added to the expiry - of HTLCs. This is a security parameter determined by the node operator. - This value represents the required gap between the time locks of the - incoming and outgoing HTLC's set to this node. - */ - uint32 time_lock_delta = 6; - - /* - The minimum HTLC value which will be accepted. - */ - uint64 htlc_minimum_msat = 7; - - /* - The base fee that must be used for incoming HTLC's to this particular - channel. This value will be tacked onto the required for a payment - independent of the size of the payment. - */ - uint32 base_fee = 8; - - /* - The fee rate that will be charged per millionth of a satoshi. - */ - uint32 fee_rate = 9; - - /* - The maximum HTLC value which will be accepted. - */ - uint64 htlc_maximum_msat = 11; - - /* - The set of data that was appended to this message, some of which we may - not actually know how to iterate or parse. By holding onto this data, we - ensure that we're able to properly validate the set of signatures that - cover these new fields, and ensure we're able to make upgrades to the - network in a forwards compatible manner. - */ - bytes extra_opaque_data = 12; -} - -message MacaroonId { - bytes nonce = 1; - bytes storageId = 2; - repeated Op ops = 3; -} - -message Op { - string entity = 1; - repeated string actions = 2; -} - -message CheckMacPermRequest { - bytes macaroon = 1; - repeated MacaroonPermission permissions = 2; - string fullMethod = 3; -} - -message CheckMacPermResponse { - bool valid = 1; -} - -message RPCMiddlewareRequest { - /* - The unique ID of the intercepted original gRPC request. Useful for mapping - request to response when implementing full duplex message interception. For - streaming requests, this will be the same ID for all incoming and outgoing - middleware intercept messages of the _same_ stream. - */ - uint64 request_id = 1; - - /* - The raw bytes of the complete macaroon as sent by the gRPC client in the - original request. This might be empty for a request that doesn't require - macaroons such as the wallet unlocker RPCs. - */ - bytes raw_macaroon = 2; - - /* - The parsed condition of the macaroon's custom caveat for convenient access. - This field only contains the value of the custom caveat that the handling - middleware has registered itself for. The condition _must_ be validated for - messages of intercept_type stream_auth and request! - */ - string custom_caveat_condition = 3; - - /* - There are three types of messages that will be sent to the middleware for - inspection and approval: Stream authentication, request and response - interception. The first two can only be accepted (=forward to main RPC - server) or denied (=return error to client). Intercepted responses can also - be replaced/overwritten. - */ - oneof intercept_type { - /* - Intercept stream authentication: each new streaming RPC call that is - initiated against lnd and contains the middleware's custom macaroon - caveat can be approved or denied based upon the macaroon in the stream - header. This message will only be sent for streaming RPCs, unary RPCs - must handle the macaroon authentication in the request interception to - avoid an additional message round trip between lnd and the middleware. - */ - StreamAuth stream_auth = 4; - - /* - Intercept incoming gRPC client request message: all incoming messages, - both on streaming and unary RPCs, are forwarded to the middleware for - inspection. For unary RPC messages the middleware is also expected to - validate the custom macaroon caveat of the request. - */ - RPCMessage request = 5; - - /* - Intercept outgoing gRPC response message: all outgoing messages, both on - streaming and unary RPCs, are forwarded to the middleware for inspection - and amendment. The response in this message is the original response as - it was generated by the main RPC server. It can either be accepted - (=forwarded to the client), replaced/overwritten with a new message of - the same type, or replaced by an error message. - */ - RPCMessage response = 6; - - /* - This is used to indicate to the client that the server has successfully - registered the interceptor. This is only used in the very first message - that the server sends to the client after the client sends the server - the middleware registration message. - */ - bool reg_complete = 8; - } - - /* - The unique message ID of this middleware intercept message. There can be - multiple middleware intercept messages per single gRPC request (one for the - incoming request and one for the outgoing response) or gRPC stream (one for - each incoming message and one for each outgoing response). This message ID - must be referenced when responding (accepting/rejecting/modifying) to an - intercept message. - */ - uint64 msg_id = 7; -} - -message StreamAuth { - /* - The full URI (in the format /./MethodName, for - example /lnrpc.Lightning/GetInfo) of the streaming RPC method that was just - established. - */ - string method_full_uri = 1; -} - -message RPCMessage { - /* - The full URI (in the format /./MethodName, for - example /lnrpc.Lightning/GetInfo) of the RPC method the message was sent - to/from. - */ - string method_full_uri = 1; - - /* - Indicates whether the message was sent over a streaming RPC method or not. - */ - bool stream_rpc = 2; - - /* - The full canonical gRPC name of the message type (in the format - .TypeName, for example lnrpc.GetInfoRequest). In case of an - error being returned from lnd, this simply contains the string "error". - */ - string type_name = 3; - - /* - The full content of the gRPC message, serialized in the binary protobuf - format. - */ - bytes serialized = 4; - - /* - Indicates that the response from lnd was an error, not a gRPC response. If - this is set to true then the type_name contains the string "error" and - serialized contains the error string. - */ - bool is_error = 5; -} - -message RPCMiddlewareResponse { - /* - The request message ID this response refers to. Must always be set when - giving feedback to an intercept but is ignored for the initial registration - message. - */ - uint64 ref_msg_id = 1; - - /* - The middleware can only send two types of messages to lnd: The initial - registration message that identifies the middleware and after that only - feedback messages to requests sent to the middleware. - */ - oneof middleware_message { - /* - The registration message identifies the middleware that's being - registered in lnd. The registration message must be sent immediately - after initiating the RegisterRpcMiddleware stream, otherwise lnd will - time out the attempt and terminate the request. NOTE: The middleware - will only receive interception messages for requests that contain a - macaroon with the custom caveat that the middleware declares it is - responsible for handling in the registration message! As a security - measure, _no_ middleware can intercept requests made with _unencumbered_ - macaroons! - */ - MiddlewareRegistration register = 2; - - /* - The middleware received an interception request and gives feedback to - it. The request_id indicates what message the feedback refers to. - */ - InterceptFeedback feedback = 3; - } -} - -message MiddlewareRegistration { - /* - The name of the middleware to register. The name should be as informative - as possible and is logged on registration. - */ - string middleware_name = 1; - - /* - The name of the custom macaroon caveat that this middleware is responsible - for. Only requests/responses that contain a macaroon with the registered - custom caveat are forwarded for interception to the middleware. The - exception being the read-only mode: All requests/responses are forwarded to - a middleware that requests read-only access but such a middleware won't be - allowed to _alter_ responses. As a security measure, _no_ middleware can - change responses to requests made with _unencumbered_ macaroons! - NOTE: Cannot be used at the same time as read_only_mode. - */ - string custom_macaroon_caveat_name = 2; - - /* - Instead of defining a custom macaroon caveat name a middleware can register - itself for read-only access only. In that mode all requests/responses are - forwarded to the middleware but the middleware isn't allowed to alter any of - the responses. - NOTE: Cannot be used at the same time as custom_macaroon_caveat_name. - */ - bool read_only_mode = 3; -} - -message InterceptFeedback { - /* - The error to return to the user. If this is non-empty, the incoming gRPC - stream/request is aborted and the error is returned to the gRPC client. If - this value is empty, it means the middleware accepts the stream/request/ - response and the processing of it can continue. - */ - string error = 1; - - /* - A boolean indicating that the gRPC message should be replaced/overwritten. - This boolean is needed because in protobuf an empty message is serialized as - a 0-length or nil byte slice and we wouldn't be able to distinguish between - an empty replacement message and the "don't replace anything" case. - */ - bool replace_response = 2; - - /* - If the replace_response field is set to true, this field must contain the - binary serialized gRPC message in the protobuf format. - */ - bytes replacement_serialized = 3; -} +syntax = "proto3"; + +package lnrpc; + +option go_package = "github.com/lightningnetwork/lnd/lnrpc"; + +/* + * 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 + */ + +// Lightning is the main RPC server of the daemon. +service Lightning { + /* lncli: `walletbalance` + WalletBalance returns total unspent outputs(confirmed and unconfirmed), all + confirmed unspent outputs and all unconfirmed unspent outputs under control + of the wallet. + */ + rpc WalletBalance (WalletBalanceRequest) returns (WalletBalanceResponse); + + /* lncli: `channelbalance` + ChannelBalance returns a report on the total funds across all open channels, + categorized in local/remote, pending local/remote and unsettled local/remote + balances. + */ + rpc ChannelBalance (ChannelBalanceRequest) returns (ChannelBalanceResponse); + + /* lncli: `listchaintxns` + GetTransactions returns a list describing all the known transactions + relevant to the wallet. + */ + rpc GetTransactions (GetTransactionsRequest) returns (TransactionDetails); + + /* lncli: `estimatefee` + EstimateFee asks the chain backend to estimate the fee rate and total fees + for a transaction that pays to multiple specified outputs. + + When using REST, the `AddrToAmount` map type can be set by appending + `&AddrToAmount[
]=` to the URL. Unfortunately this + map type doesn't appear in the REST API documentation because of a bug in + the grpc-gateway library. + */ + rpc EstimateFee (EstimateFeeRequest) returns (EstimateFeeResponse); + + /* lncli: `sendcoins` + SendCoins executes a request to send coins to a particular address. Unlike + SendMany, this RPC call only allows creating a single output at a time. If + neither target_conf, or sat_per_vbyte are set, then the internal wallet will + consult its fee model to determine a fee for the default confirmation + target. + */ + rpc SendCoins (SendCoinsRequest) returns (SendCoinsResponse); + + /* lncli: `listunspent` + Deprecated, use walletrpc.ListUnspent instead. + + ListUnspent returns a list of all utxos spendable by the wallet with a + number of confirmations between the specified minimum and maximum. + */ + rpc ListUnspent (ListUnspentRequest) returns (ListUnspentResponse); + + /* + SubscribeTransactions creates a uni-directional stream from the server to + the client in which any newly discovered transactions relevant to the + wallet are sent over. + */ + rpc SubscribeTransactions (GetTransactionsRequest) + returns (stream Transaction); + + /* lncli: `sendmany` + SendMany handles a request for a transaction that creates multiple specified + outputs in parallel. If neither target_conf, or sat_per_vbyte are set, then + the internal wallet will consult its fee model to determine a fee for the + default confirmation target. + */ + rpc SendMany (SendManyRequest) returns (SendManyResponse); + + /* lncli: `newaddress` + NewAddress creates a new address under control of the local wallet. + */ + rpc NewAddress (NewAddressRequest) returns (NewAddressResponse); + + /* lncli: `signmessage` + SignMessage signs a message with this node's private key. The returned + signature string is `zbase32` encoded and pubkey recoverable, meaning that + only the message digest and signature are needed for verification. + */ + rpc SignMessage (SignMessageRequest) returns (SignMessageResponse); + + /* lncli: `verifymessage` + VerifyMessage verifies a signature over a msg. The signature must be + zbase32 encoded and signed by an active node in the resident node's + channel database. In addition to returning the validity of the signature, + VerifyMessage also returns the recovered pubkey from the signature. + */ + rpc VerifyMessage (VerifyMessageRequest) returns (VerifyMessageResponse); + + /* lncli: `connect` + ConnectPeer attempts to establish a connection to a remote peer. This is at + the networking level, and is used for communication between nodes. This is + distinct from establishing a channel with a peer. + */ + rpc ConnectPeer (ConnectPeerRequest) returns (ConnectPeerResponse); + + /* lncli: `disconnect` + DisconnectPeer attempts to disconnect one peer from another identified by a + given pubKey. In the case that we currently have a pending or active channel + with the target peer, then this action will be not be allowed. + */ + rpc DisconnectPeer (DisconnectPeerRequest) returns (DisconnectPeerResponse); + + /* lncli: `listpeers` + ListPeers returns a verbose listing of all currently active peers. + */ + rpc ListPeers (ListPeersRequest) returns (ListPeersResponse); + + /* + SubscribePeerEvents creates a uni-directional stream from the server to + the client in which any events relevant to the state of peers are sent + over. Events include peers going online and offline. + */ + rpc SubscribePeerEvents (PeerEventSubscription) returns (stream PeerEvent); + + /* lncli: `getinfo` + GetInfo returns general information concerning the lightning node including + it's identity pubkey, alias, the chains it is connected to, and information + concerning the number of open+pending channels. + */ + rpc GetInfo (GetInfoRequest) returns (GetInfoResponse); + + /** lncli: `getrecoveryinfo` + GetRecoveryInfo returns information concerning the recovery mode including + whether it's in a recovery mode, whether the recovery is finished, and the + progress made so far. + */ + rpc GetRecoveryInfo (GetRecoveryInfoRequest) + returns (GetRecoveryInfoResponse); + + // TODO(roasbeef): merge with below with bool? + /* lncli: `pendingchannels` + PendingChannels returns a list of all the channels that are currently + considered "pending". A channel is pending if it has finished the funding + workflow and is waiting for confirmations for the funding txn, or is in the + process of closure, either initiated cooperatively or non-cooperatively. + */ + rpc PendingChannels (PendingChannelsRequest) + returns (PendingChannelsResponse); + + /* lncli: `listchannels` + ListChannels returns a description of all the open channels that this node + is a participant in. + */ + rpc ListChannels (ListChannelsRequest) returns (ListChannelsResponse); + + /* + SubscribeChannelEvents creates a uni-directional stream from the server to + the client in which any updates relevant to the state of the channels are + sent over. Events include new active channels, inactive channels, and closed + channels. + */ + rpc SubscribeChannelEvents (ChannelEventSubscription) + returns (stream ChannelEventUpdate); + + /* lncli: `closedchannels` + ClosedChannels returns a description of all the closed channels that + this node was a participant in. + */ + rpc ClosedChannels (ClosedChannelsRequest) returns (ClosedChannelsResponse); + + /* + OpenChannelSync is a synchronous version of the OpenChannel RPC call. This + call is meant to be consumed by clients to the REST proxy. As with all + other sync calls, all byte slices are intended to be populated as hex + encoded strings. + */ + rpc OpenChannelSync (OpenChannelRequest) returns (ChannelPoint); + + /* lncli: `openchannel` + OpenChannel attempts to open a singly funded channel specified in the + request to a remote peer. Users are able to specify a target number of + blocks that the funding transaction should be confirmed in, or a manual fee + rate to us for the funding transaction. If neither are specified, then a + lax block confirmation target is used. Each OpenStatusUpdate will return + the pending channel ID of the in-progress channel. Depending on the + arguments specified in the OpenChannelRequest, this pending channel ID can + then be used to manually progress the channel funding flow. + */ + rpc OpenChannel (OpenChannelRequest) returns (stream OpenStatusUpdate); + + /* lncli: `batchopenchannel` + BatchOpenChannel attempts to open multiple single-funded channels in a + single transaction in an atomic way. This means either all channel open + requests succeed at once or all attempts are aborted if any of them fail. + This is the safer variant of using PSBTs to manually fund a batch of + channels through the OpenChannel RPC. + */ + rpc BatchOpenChannel (BatchOpenChannelRequest) + returns (BatchOpenChannelResponse); + + /* + FundingStateStep is an advanced funding related call that allows the caller + to either execute some preparatory steps for a funding workflow, or + manually progress a funding workflow. The primary way a funding flow is + identified is via its pending channel ID. As an example, this method can be + used to specify that we're expecting a funding flow for a particular + pending channel ID, for which we need to use specific parameters. + Alternatively, this can be used to interactively drive PSBT signing for + funding for partially complete funding transactions. + */ + rpc FundingStateStep (FundingTransitionMsg) returns (FundingStateStepResp); + + /* + ChannelAcceptor dispatches a bi-directional streaming RPC in which + OpenChannel requests are sent to the client and the client responds with + a boolean that tells LND whether or not to accept the channel. This allows + node operators to specify their own criteria for accepting inbound channels + through a single persistent connection. + */ + rpc ChannelAcceptor (stream ChannelAcceptResponse) + returns (stream ChannelAcceptRequest); + + /* lncli: `closechannel` + CloseChannel attempts to close an active channel identified by its channel + outpoint (ChannelPoint). The actions of this method can additionally be + augmented to attempt a force close after a timeout period in the case of an + inactive peer. If a non-force close (cooperative closure) is requested, + then the user can specify either a target number of blocks until the + closure transaction is confirmed, or a manual fee rate. If neither are + specified, then a default lax, block confirmation target is used. + */ + rpc CloseChannel (CloseChannelRequest) returns (stream CloseStatusUpdate); + + /* lncli: `abandonchannel` + AbandonChannel removes all channel state from the database except for a + close summary. This method can be used to get rid of permanently unusable + channels due to bugs fixed in newer versions of lnd. This method can also be + used to remove externally funded channels where the funding transaction was + never broadcast. Only available for non-externally funded channels in dev + build. + */ + rpc AbandonChannel (AbandonChannelRequest) returns (AbandonChannelResponse); + + /* lncli: `sendpayment` + Deprecated, use routerrpc.SendPaymentV2. SendPayment dispatches a + bi-directional streaming RPC for sending payments through the Lightning + Network. A single RPC invocation creates a persistent bi-directional + stream allowing clients to rapidly send payments through the Lightning + Network with a single persistent connection. + */ + rpc SendPayment (stream SendRequest) returns (stream SendResponse) { + option deprecated = true; + } + + /* + SendPaymentSync is the synchronous non-streaming version of SendPayment. + This RPC is intended to be consumed by clients of the REST proxy. + Additionally, this RPC expects the destination's public key and the payment + hash (if any) to be encoded as hex strings. + */ + rpc SendPaymentSync (SendRequest) returns (SendResponse); + + /* lncli: `sendtoroute` + Deprecated, use routerrpc.SendToRouteV2. SendToRoute is a bi-directional + streaming RPC for sending payment through the Lightning Network. This + method differs from SendPayment in that it allows users to specify a full + route manually. This can be used for things like rebalancing, and atomic + swaps. + */ + rpc SendToRoute (stream SendToRouteRequest) returns (stream SendResponse) { + option deprecated = true; + } + + /* + SendToRouteSync is a synchronous version of SendToRoute. It Will block + until the payment either fails or succeeds. + */ + rpc SendToRouteSync (SendToRouteRequest) returns (SendResponse); + + /* lncli: `addinvoice` + AddInvoice attempts to add a new invoice to the invoice database. Any + duplicated invoices are rejected, therefore all invoices *must* have a + unique payment preimage. + */ + rpc AddInvoice (Invoice) returns (AddInvoiceResponse); + + /* lncli: `listinvoices` + ListInvoices returns a list of all the invoices currently stored within the + database. Any active debug invoices are ignored. It has full support for + paginated responses, allowing users to query for specific invoices through + their add_index. This can be done by using either the first_index_offset or + last_index_offset fields included in the response as the index_offset of the + next request. By default, the first 100 invoices created will be returned. + Backwards pagination is also supported through the Reversed flag. + */ + rpc ListInvoices (ListInvoiceRequest) returns (ListInvoiceResponse); + + /* lncli: `lookupinvoice` + LookupInvoice attempts to look up an invoice according to its payment hash. + The passed payment hash *must* be exactly 32 bytes, if not, an error is + returned. + */ + rpc LookupInvoice (PaymentHash) returns (Invoice); + + /* + SubscribeInvoices returns a uni-directional stream (server -> client) for + notifying the client of newly added/settled invoices. The caller can + optionally specify the add_index and/or the settle_index. If the add_index + is specified, then we'll first start by sending add invoice events for all + invoices with an add_index greater than the specified value. If the + settle_index is specified, the next, we'll send out all settle events for + invoices with a settle_index greater than the specified value. One or both + of these fields can be set. If no fields are set, then we'll only send out + the latest add/settle events. + */ + rpc SubscribeInvoices (InvoiceSubscription) returns (stream Invoice); + + /* lncli: `decodepayreq` + DecodePayReq takes an encoded payment request string and attempts to decode + it, returning a full description of the conditions encoded within the + payment request. + */ + rpc DecodePayReq (PayReqString) returns (PayReq); + + /* lncli: `listpayments` + ListPayments returns a list of all outgoing payments. + */ + rpc ListPayments (ListPaymentsRequest) returns (ListPaymentsResponse); + + /* + 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); + + /* + DeleteAllPayments deletes all outgoing payments from DB. Note that it will + not attempt to delete In-Flight payments, since that would be unsafe. + */ + rpc DeleteAllPayments (DeleteAllPaymentsRequest) + returns (DeleteAllPaymentsResponse); + + /* lncli: `describegraph` + DescribeGraph returns a description of the latest graph state from the + point of view of the node. The graph information is partitioned into two + components: all the nodes/vertexes, and all the edges that connect the + vertexes themselves. As this is a directed graph, the edges also contain + the node directional specific routing policy which includes: the time lock + delta, fee information, etc. + */ + rpc DescribeGraph (ChannelGraphRequest) returns (ChannelGraph); + + /* lncli: `getnodemetrics` + GetNodeMetrics returns node metrics calculated from the graph. Currently + the only supported metric is betweenness centrality of individual nodes. + */ + rpc GetNodeMetrics (NodeMetricsRequest) returns (NodeMetricsResponse); + + /* lncli: `getchaninfo` + GetChanInfo returns the latest authenticated network announcement for the + given channel identified by its channel ID: an 8-byte integer which + uniquely identifies the location of transaction's funding output within the + blockchain. + */ + rpc GetChanInfo (ChanInfoRequest) returns (ChannelEdge); + + /* lncli: `getnodeinfo` + GetNodeInfo returns the latest advertised, aggregated, and authenticated + channel information for the specified node identified by its public key. + */ + rpc GetNodeInfo (NodeInfoRequest) returns (NodeInfo); + + /* lncli: `queryroutes` + QueryRoutes attempts to query the daemon's Channel Router for a possible + route to a target destination capable of carrying a specific amount of + satoshis. The returned route contains the full details required to craft and + send an HTLC, also including the necessary information that should be + present within the Sphinx packet encapsulated within the HTLC. + + When using REST, the `dest_custom_records` map type can be set by appending + `&dest_custom_records[]=` + to the URL. Unfortunately this map type doesn't appear in the REST API + documentation because of a bug in the grpc-gateway library. + */ + rpc QueryRoutes (QueryRoutesRequest) returns (QueryRoutesResponse); + + /* lncli: `getnetworkinfo` + GetNetworkInfo returns some basic stats about the known channel graph from + the point of view of the node. + */ + rpc GetNetworkInfo (NetworkInfoRequest) returns (NetworkInfo); + + /* lncli: `stop` + StopDaemon will send a shutdown request to the interrupt handler, triggering + a graceful shutdown of the daemon. + */ + rpc StopDaemon (StopRequest) returns (StopResponse); + + /* + SubscribeChannelGraph launches a streaming RPC that allows the caller to + receive notifications upon any changes to the channel graph topology from + the point of view of the responding node. Events notified include: new + nodes coming online, nodes updating their authenticated attributes, new + channels being advertised, updates in the routing policy for a directional + channel edge, and when channels are closed on-chain. + */ + rpc SubscribeChannelGraph (GraphTopologySubscription) + returns (stream GraphTopologyUpdate); + + /* lncli: `debuglevel` + DebugLevel allows a caller to programmatically set the logging verbosity of + lnd. The logging can be targeted according to a coarse daemon-wide logging + level, or in a granular fashion to specify the logging for a target + sub-system. + */ + rpc DebugLevel (DebugLevelRequest) returns (DebugLevelResponse); + + /* lncli: `feereport` + FeeReport allows the caller to obtain a report detailing the current fee + schedule enforced by the node globally for each channel. + */ + rpc FeeReport (FeeReportRequest) returns (FeeReportResponse); + + /* lncli: `updatechanpolicy` + UpdateChannelPolicy allows the caller to update the fee schedule and + channel policies for all channels globally, or a particular channel. + */ + rpc UpdateChannelPolicy (PolicyUpdateRequest) + returns (PolicyUpdateResponse); + + /* lncli: `fwdinghistory` + ForwardingHistory allows the caller to query the htlcswitch for a record of + all HTLCs forwarded within the target time range, and integer offset + within that time range, for a maximum number of events. If no maximum number + of events is specified, up to 100 events will be returned. If no time-range + is specified, then events will be returned in the order that they occured. + + A list of forwarding events are returned. The size of each forwarding event + is 40 bytes, and the max message size able to be returned in gRPC is 4 MiB. + As a result each message can only contain 50k entries. Each response has + the index offset of the last entry. The index offset can be provided to the + request to allow the caller to skip a series of records. + */ + rpc ForwardingHistory (ForwardingHistoryRequest) + returns (ForwardingHistoryResponse); + + /* lncli: `exportchanbackup` + ExportChannelBackup attempts to return an encrypted static channel backup + for the target channel identified by it channel point. The backup is + encrypted with a key generated from the aezeed seed of the user. The + returned backup can either be restored using the RestoreChannelBackup + method once lnd is running, or via the InitWallet and UnlockWallet methods + from the WalletUnlocker service. + */ + rpc ExportChannelBackup (ExportChannelBackupRequest) + returns (ChannelBackup); + + /* + ExportAllChannelBackups returns static channel backups for all existing + channels known to lnd. A set of regular singular static channel backups for + each channel are returned. Additionally, a multi-channel backup is returned + as well, which contains a single encrypted blob containing the backups of + each channel. + */ + rpc ExportAllChannelBackups (ChanBackupExportRequest) + returns (ChanBackupSnapshot); + + /* + 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. + */ + rpc VerifyChanBackup (ChanBackupSnapshot) + returns (VerifyChanBackupResponse); + + /* lncli: `restorechanbackup` + RestoreChannelBackups accepts a set of singular channel backups, or a + single encrypted multi-chan backup and attempts to recover any funds + remaining within the channel. If we are able to unpack the backup, then the + new channel will be shown under listchannels, as well as pending channels. + */ + rpc RestoreChannelBackups (RestoreChanBackupRequest) + returns (RestoreBackupResponse); + + /* + SubscribeChannelBackups allows a client to sub-subscribe to the most up to + date information concerning the state of all channel backups. Each time a + new channel is added, we return the new set of channels, along with a + multi-chan backup containing the backup info for all channels. Each time a + channel is closed, we send a new update, which contains new new chan back + ups, but the updated set of encrypted multi-chan backups with the closed + channel(s) removed. + */ + rpc SubscribeChannelBackups (ChannelBackupSubscription) + returns (stream ChanBackupSnapshot); + + /* lncli: `bakemacaroon` + BakeMacaroon allows the creation of a new macaroon with custom read and + write permissions. No first-party caveats are added since this can be done + offline. + */ + rpc BakeMacaroon (BakeMacaroonRequest) returns (BakeMacaroonResponse); + + /* lncli: `listmacaroonids` + ListMacaroonIDs returns all root key IDs that are in use. + */ + rpc ListMacaroonIDs (ListMacaroonIDsRequest) + returns (ListMacaroonIDsResponse); + + /* lncli: `deletemacaroonid` + DeleteMacaroonID deletes the specified macaroon ID and invalidates all + macaroons derived from that ID. + */ + rpc DeleteMacaroonID (DeleteMacaroonIDRequest) + returns (DeleteMacaroonIDResponse); + + /* lncli: `listpermissions` + ListPermissions lists all RPC method URIs and their required macaroon + permissions to access them. + */ + rpc ListPermissions (ListPermissionsRequest) + returns (ListPermissionsResponse); + + /* + CheckMacaroonPermissions checks whether a request follows the constraints + imposed on the macaroon and that the macaroon is authorized to follow the + provided permissions. + */ + rpc CheckMacaroonPermissions (CheckMacPermRequest) + returns (CheckMacPermResponse); + + /* + RegisterRPCMiddleware adds a new gRPC middleware to the interceptor chain. A + gRPC middleware is software component external to lnd that aims to add + additional business logic to lnd by observing/intercepting/validating + incoming gRPC client requests and (if needed) replacing/overwriting outgoing + messages before they're sent to the client. When registering the middleware + must identify itself and indicate what custom macaroon caveats it wants to + be responsible for. Only requests that contain a macaroon with that specific + custom caveat are then sent to the middleware for inspection. The other + option is to register for the read-only mode in which all requests/responses + are forwarded for interception to the middleware but the middleware is not + allowed to modify any responses. As a security measure, _no_ middleware can + modify responses for requests made with _unencumbered_ macaroons! + */ + rpc RegisterRPCMiddleware (stream RPCMiddlewareResponse) + returns (stream RPCMiddlewareRequest); + + /* lncli: `sendcustom` + SendCustomMessage sends a custom peer message. + */ + rpc SendCustomMessage (SendCustomMessageRequest) + returns (SendCustomMessageResponse); + + /* lncli: `subscribecustom` + SubscribeCustomMessages subscribes to a stream of incoming custom peer + messages. + */ + rpc SubscribeCustomMessages (SubscribeCustomMessagesRequest) + returns (stream CustomMessage); + + /* lncli: `listaliases` + ListAliases returns the set of all aliases that have ever existed with + their confirmed SCID (if it exists) and/or the base SCID (in the case of + zero conf). + */ + rpc ListAliases (ListAliasesRequest) returns (ListAliasesResponse); +} + +message SubscribeCustomMessagesRequest { +} + +message CustomMessage { + // Peer from which the message originates + bytes peer = 1; + + // Message type. This value will be in the custom range (>= 32768). + uint32 type = 2; + + // Raw message data + bytes data = 3; +} + +message SendCustomMessageRequest { + // Peer to send the message to + bytes peer = 1; + + // Message type. This value needs to be in the custom range (>= 32768). + uint32 type = 2; + + // Raw message data. + bytes data = 3; +} + +message SendCustomMessageResponse { +} + +message Utxo { + // The type of address + AddressType address_type = 1; + + // The address + string address = 2; + + // The value of the unspent coin in satoshis + int64 amount_sat = 3; + + // The pkscript in hex + string pk_script = 4; + + // The outpoint in format txid:n + OutPoint outpoint = 5; + + // The number of confirmations for the Utxo + int64 confirmations = 6; +} + +enum OutputScriptType { + SCRIPT_TYPE_PUBKEY_HASH = 0; + SCRIPT_TYPE_SCRIPT_HASH = 1; + SCRIPT_TYPE_WITNESS_V0_PUBKEY_HASH = 2; + SCRIPT_TYPE_WITNESS_V0_SCRIPT_HASH = 3; + SCRIPT_TYPE_PUBKEY = 4; + SCRIPT_TYPE_MULTISIG = 5; + SCRIPT_TYPE_NULLDATA = 6; + SCRIPT_TYPE_NON_STANDARD = 7; + SCRIPT_TYPE_WITNESS_UNKNOWN = 8; +} + +message OutputDetail { + // The type of the output + OutputScriptType output_type = 1; + + // The address + string address = 2; + + // The pkscript in hex + string pk_script = 3; + + // The output index used in the raw transaction + int64 output_index = 4; + + // The value of the output coin in satoshis + int64 amount = 5; + + // Denotes if the output is controlled by the internal wallet + bool is_our_address = 6; +} + +message Transaction { + // The transaction hash + string tx_hash = 1; + + // The transaction amount, denominated in satoshis + int64 amount = 2; + + // The number of confirmations + int32 num_confirmations = 3; + + // The hash of the block this transaction was included in + string block_hash = 4; + + // The height of the block this transaction was included in + int32 block_height = 5; + + // Timestamp of this transaction + int64 time_stamp = 6; + + // Fees paid for this transaction + int64 total_fees = 7; + + // Addresses that received funds for this transaction. Deprecated as it is + // now incorporated in the output_details field. + repeated string dest_addresses = 8 [deprecated = true]; + + // Outputs that received funds for this transaction + repeated OutputDetail output_details = 11; + + // The raw transaction hex. + string raw_tx_hex = 9; + + // A label that was optionally set on transaction broadcast. + string label = 10; + + // PreviousOutpoints/Inputs of this transaction. + repeated PreviousOutPoint previous_outpoints = 12; +} + +message GetTransactionsRequest { + /* + The height from which to list transactions, inclusive. If this value is + greater than end_height, transactions will be read in reverse. + */ + int32 start_height = 1; + + /* + The height until which to list transactions, inclusive. To include + unconfirmed transactions, this value should be set to -1, which will + return transactions from start_height until the current chain tip and + unconfirmed transactions. If no end_height is provided, the call will + default to this option. + */ + int32 end_height = 2; + + // An optional filter to only include transactions relevant to an account. + string account = 3; +} + +message TransactionDetails { + // The list of transactions relevant to the wallet. + repeated Transaction transactions = 1; +} + +message FeeLimit { + oneof limit { + /* + The fee limit expressed as a fixed amount of satoshis. + + The fields fixed and fixed_msat are mutually exclusive. + */ + int64 fixed = 1; + + /* + The fee limit expressed as a fixed amount of millisatoshis. + + The fields fixed and fixed_msat are mutually exclusive. + */ + int64 fixed_msat = 3; + + // The fee limit expressed as a percentage of the payment amount. + int64 percent = 2; + } +} + +message SendRequest { + /* + The identity pubkey of the payment recipient. When using REST, this field + must be encoded as base64. + */ + bytes dest = 1; + + /* + The hex-encoded identity pubkey of the payment recipient. Deprecated now + that the REST gateway supports base64 encoding of bytes fields. + */ + string dest_string = 2 [deprecated = true]; + + /* + The amount to send expressed in satoshis. + + The fields amt and amt_msat are mutually exclusive. + */ + int64 amt = 3; + + /* + The amount to send expressed in millisatoshis. + + The fields amt and amt_msat are mutually exclusive. + */ + int64 amt_msat = 12; + + /* + The hash to use within the payment's HTLC. When using REST, this field + must be encoded as base64. + */ + bytes payment_hash = 4; + + /* + The hex-encoded hash to use within the payment's HTLC. Deprecated now + that the REST gateway supports base64 encoding of bytes fields. + */ + string payment_hash_string = 5 [deprecated = true]; + + /* + A bare-bones invoice for a payment within the Lightning Network. With the + details of the invoice, the sender has all the data necessary to send a + payment to the recipient. + */ + string payment_request = 6; + + /* + The CLTV delta from the current height that should be used to set the + timelock for the final hop. + */ + int32 final_cltv_delta = 7; + + /* + The maximum number of satoshis that will be paid as a fee of the payment. + This value can be represented either as a percentage of the amount being + sent, or as a fixed amount of the maximum fee the user is willing the pay to + send the payment. If not specified, lnd will use a default value of 100% + fees for small amounts (<=1k sat) or 5% fees for larger amounts. + */ + FeeLimit fee_limit = 8; + + /* + The channel id of the channel that must be taken to the first hop. If zero, + any channel may be used. + */ + uint64 outgoing_chan_id = 9 [jstype = JS_STRING]; + + /* + The pubkey of the last hop of the route. If empty, any hop may be used. + */ + bytes last_hop_pubkey = 13; + + /* + An optional maximum total time lock for the route. This should not exceed + lnd's `--max-cltv-expiry` setting. If zero, then the value of + `--max-cltv-expiry` is enforced. + */ + uint32 cltv_limit = 10; + + /* + An optional field that can be used to pass an arbitrary set of TLV records + to a peer which understands the new records. This can be used to pass + application specific data during the payment attempt. Record types are + required to be in the custom range >= 65536. When using REST, the values + must be encoded as base64. + */ + map dest_custom_records = 11; + + // If set, circular payments to self are permitted. + bool allow_self_payment = 14; + + /* + Features assumed to be supported by the final node. All transitive feature + dependencies must also be set properly. For a given feature bit pair, either + optional or remote may be set, but not both. If this field is nil or empty, + the router will try to load destination features from the graph as a + fallback. + */ + repeated FeatureBit dest_features = 15; + + /* + The payment address of the generated invoice. + */ + bytes payment_addr = 16; +} + +message SendResponse { + string payment_error = 1; + bytes payment_preimage = 2; + Route payment_route = 3; + bytes payment_hash = 4; +} + +message SendToRouteRequest { + /* + The payment hash to use for the HTLC. When using REST, this field must be + encoded as base64. + */ + bytes payment_hash = 1; + + /* + An optional hex-encoded payment hash to be used for the HTLC. Deprecated now + that the REST gateway supports base64 encoding of bytes fields. + */ + string payment_hash_string = 2 [deprecated = true]; + + reserved 3; + + // Route that should be used to attempt to complete the payment. + Route route = 4; +} + +message ChannelAcceptRequest { + // The pubkey of the node that wishes to open an inbound channel. + bytes node_pubkey = 1; + + // The hash of the genesis block that the proposed channel resides in. + bytes chain_hash = 2; + + // The pending channel id. + bytes pending_chan_id = 3; + + // The funding amount in satoshis that initiator wishes to use in the + // channel. + uint64 funding_amt = 4; + + // The push amount of the proposed channel in millisatoshis. + uint64 push_amt = 5; + + // The dust limit of the initiator's commitment tx. + uint64 dust_limit = 6; + + // The maximum amount of coins in millisatoshis that can be pending in this + // channel. + uint64 max_value_in_flight = 7; + + // The minimum amount of satoshis the initiator requires us to have at all + // times. + uint64 channel_reserve = 8; + + // The smallest HTLC in millisatoshis that the initiator will accept. + uint64 min_htlc = 9; + + // The initial fee rate that the initiator suggests for both commitment + // transactions. + uint64 fee_per_kw = 10; + + /* + The number of blocks to use for the relative time lock in the pay-to-self + output of both commitment transactions. + */ + uint32 csv_delay = 11; + + // The total number of incoming HTLC's that the initiator will accept. + uint32 max_accepted_htlcs = 12; + + // A bit-field which the initiator uses to specify proposed channel + // behavior. + uint32 channel_flags = 13; + + // The commitment type the initiator wishes to use for the proposed channel. + CommitmentType commitment_type = 14; + + // Whether the initiator wants to open a zero-conf channel via the channel + // type. + bool wants_zero_conf = 15; + + // Whether the initiator wants to use the scid-alias channel type. This is + // separate from the feature bit. + bool wants_scid_alias = 16; +} + +message ChannelAcceptResponse { + // Whether or not the client accepts the channel. + bool accept = 1; + + // The pending channel id to which this response applies. + bytes pending_chan_id = 2; + + /* + An optional error to send the initiating party to indicate why the channel + was rejected. This field *should not* contain sensitive information, it will + be sent to the initiating party. This field should only be set if accept is + false, the channel will be rejected if an error is set with accept=true + because the meaning of this response is ambiguous. Limited to 500 + characters. + */ + string error = 3; + + /* + The upfront shutdown address to use if the initiating peer supports option + upfront shutdown script (see ListPeers for the features supported). Note + that the channel open will fail if this value is set for a peer that does + not support this feature bit. + */ + string upfront_shutdown = 4; + + /* + The csv delay (in blocks) that we require for the remote party. + */ + uint32 csv_delay = 5; + + /* + The reserve amount in satoshis that we require the remote peer to adhere to. + We require that the remote peer always have some reserve amount allocated to + them so that there is always a disincentive to broadcast old state (if they + hold 0 sats on their side of the channel, there is nothing to lose). + */ + uint64 reserve_sat = 6; + + /* + The maximum amount of funds in millisatoshis that we allow the remote peer + to have in outstanding htlcs. + */ + uint64 in_flight_max_msat = 7; + + /* + The maximum number of htlcs that the remote peer can offer us. + */ + uint32 max_htlc_count = 8; + + /* + The minimum value in millisatoshis for incoming htlcs on the channel. + */ + uint64 min_htlc_in = 9; + + /* + The number of confirmations we require before we consider the channel open. + */ + uint32 min_accept_depth = 10; + + /* + Whether the responder wants this to be a zero-conf channel. This will fail + if either side does not have the scid-alias feature bit set. The minimum + depth field must be zero if this is true. + */ + bool zero_conf = 11; +} + +message ChannelPoint { + oneof funding_txid { + /* + Txid of the funding transaction. When using REST, this field must be + encoded as base64. + */ + bytes funding_txid_bytes = 1; + + /* + Hex-encoded string representing the byte-reversed hash of the funding + transaction. + */ + string funding_txid_str = 2; + } + + // The index of the output of the funding transaction + uint32 output_index = 3; +} + +message OutPoint { + // Raw bytes representing the transaction id. + bytes txid_bytes = 1; + + // Reversed, hex-encoded string representing the transaction id. + string txid_str = 2; + + // The index of the output on the transaction. + uint32 output_index = 3; +} + +message PreviousOutPoint { + // The outpoint in format txid:n. + string outpoint = 1; + + // Denotes if the outpoint is controlled by the internal wallet. + // The flag will only detect p2wkh, np2wkh and p2tr inputs as its own. + bool is_our_output = 2; +} + +message LightningAddress { + // The identity pubkey of the Lightning node. + string pubkey = 1; + + // The network location of the lightning node, e.g. `69.69.69.69:1337` or + // `localhost:10011`. + string host = 2; +} + +message EstimateFeeRequest { + // The map from addresses to amounts for the transaction. + map AddrToAmount = 1; + + // The target number of blocks that this transaction should be confirmed + // by. + int32 target_conf = 2; + + // The minimum number of confirmations each one of your outputs used for + // the transaction must satisfy. + int32 min_confs = 3; + + // Whether unconfirmed outputs should be used as inputs for the transaction. + bool spend_unconfirmed = 4; +} + +message EstimateFeeResponse { + // The total fee in satoshis. + int64 fee_sat = 1; + + // Deprecated, use sat_per_vbyte. + // The fee rate in satoshi/vbyte. + int64 feerate_sat_per_byte = 2 [deprecated = true]; + + // The fee rate in satoshi/vbyte. + uint64 sat_per_vbyte = 3; +} + +message SendManyRequest { + // The map from addresses to amounts + map AddrToAmount = 1; + + // The target number of blocks that this transaction should be confirmed + // by. + int32 target_conf = 3; + + // A manual fee rate set in sat/vbyte that should be used when crafting the + // transaction. + uint64 sat_per_vbyte = 4; + + // Deprecated, use sat_per_vbyte. + // A manual fee rate set in sat/vbyte that should be used when crafting the + // transaction. + int64 sat_per_byte = 5 [deprecated = true]; + + // An optional label for the transaction, limited to 500 characters. + string label = 6; + + // The minimum number of confirmations each one of your outputs used for + // the transaction must satisfy. + int32 min_confs = 7; + + // Whether unconfirmed outputs should be used as inputs for the transaction. + bool spend_unconfirmed = 8; +} +message SendManyResponse { + // The id of the transaction + string txid = 1; +} + +message SendCoinsRequest { + // The address to send coins to + string addr = 1; + + // The amount in satoshis to send + int64 amount = 2; + + // The target number of blocks that this transaction should be confirmed + // by. + int32 target_conf = 3; + + // A manual fee rate set in sat/vbyte that should be used when crafting the + // transaction. + uint64 sat_per_vbyte = 4; + + // Deprecated, use sat_per_vbyte. + // A manual fee rate set in sat/vbyte that should be used when crafting the + // transaction. + int64 sat_per_byte = 5 [deprecated = true]; + + /* + If set, then the amount field will be ignored, and lnd will attempt to + send all the coins under control of the internal wallet to the specified + address. + */ + bool send_all = 6; + + // An optional label for the transaction, limited to 500 characters. + string label = 7; + + // The minimum number of confirmations each one of your outputs used for + // the transaction must satisfy. + int32 min_confs = 8; + + // Whether unconfirmed outputs should be used as inputs for the transaction. + bool spend_unconfirmed = 9; +} +message SendCoinsResponse { + // The transaction ID of the transaction + string txid = 1; +} + +message ListUnspentRequest { + // The minimum number of confirmations to be included. + int32 min_confs = 1; + + // The maximum number of confirmations to be included. + int32 max_confs = 2; + + // An optional filter to only include outputs belonging to an account. + string account = 3; +} +message ListUnspentResponse { + // A list of utxos + repeated Utxo utxos = 1; +} + +/* +`AddressType` has to be one of: + +- `p2wkh`: Pay to witness key hash (`WITNESS_PUBKEY_HASH` = 0) +- `np2wkh`: Pay to nested witness key hash (`NESTED_PUBKEY_HASH` = 1) +- `p2tr`: Pay to taproot pubkey (`TAPROOT_PUBKEY` = 4) +*/ +enum AddressType { + WITNESS_PUBKEY_HASH = 0; + NESTED_PUBKEY_HASH = 1; + UNUSED_WITNESS_PUBKEY_HASH = 2; + UNUSED_NESTED_PUBKEY_HASH = 3; + TAPROOT_PUBKEY = 4; + UNUSED_TAPROOT_PUBKEY = 5; +} + +message NewAddressRequest { + // The type of address to generate. + AddressType type = 1; + + /* + The name of the account to generate a new address for. If empty, the + default wallet account is used. + */ + string account = 2; +} +message NewAddressResponse { + // The newly generated wallet address + string address = 1; +} + +message SignMessageRequest { + /* + The message to be signed. When using REST, this field must be encoded as + base64. + */ + bytes msg = 1; + + /* + Instead of the default double-SHA256 hashing of the message before signing, + only use one round of hashing instead. + */ + bool single_hash = 2; +} +message SignMessageResponse { + // The signature for the given message + string signature = 1; +} + +message VerifyMessageRequest { + /* + The message over which the signature is to be verified. When using REST, + this field must be encoded as base64. + */ + bytes msg = 1; + + // The signature to be verified over the given message + string signature = 2; +} +message VerifyMessageResponse { + // Whether the signature was valid over the given message + bool valid = 1; + + // The pubkey recovered from the signature + string pubkey = 2; +} + +message ConnectPeerRequest { + /* + Lightning address of the peer to connect to. + */ + LightningAddress addr = 1; + + /* + If set, the daemon will attempt to persistently connect to the target + peer. Otherwise, the call will be synchronous. + */ + bool perm = 2; + + /* + The connection timeout value (in seconds) for this request. It won't affect + other requests. + */ + uint64 timeout = 3; +} +message ConnectPeerResponse { +} + +message DisconnectPeerRequest { + // The pubkey of the node to disconnect from + string pub_key = 1; +} +message DisconnectPeerResponse { +} + +message HTLC { + bool incoming = 1; + int64 amount = 2; + bytes hash_lock = 3; + uint32 expiration_height = 4; + + // Index identifying the htlc on the channel. + uint64 htlc_index = 5; + + // If this HTLC is involved in a forwarding operation, this field indicates + // the forwarding channel. For an outgoing htlc, it is the incoming channel. + // For an incoming htlc, it is the outgoing channel. When the htlc + // originates from this node or this node is the final destination, + // forwarding_channel will be zero. The forwarding channel will also be zero + // for htlcs that need to be forwarded but don't have a forwarding decision + // persisted yet. + uint64 forwarding_channel = 6; + + // Index identifying the htlc on the forwarding channel. + uint64 forwarding_htlc_index = 7; +} + +enum CommitmentType { + /* + Returned when the commitment type isn't known or unavailable. + */ + UNKNOWN_COMMITMENT_TYPE = 0; + + /* + A channel using the legacy commitment format having tweaked to_remote + keys. + */ + LEGACY = 1; + + /* + A channel that uses the modern commitment format where the key in the + output of the remote party does not change each state. This makes back + up and recovery easier as when the channel is closed, the funds go + directly to that key. + */ + STATIC_REMOTE_KEY = 2; + + /* + A channel that uses a commitment format that has anchor outputs on the + commitments, allowing fee bumping after a force close transaction has + been broadcast. + */ + ANCHORS = 3; + + /* + A channel that uses a commitment type that builds upon the anchors + commitment format, but in addition requires a CLTV clause to spend outputs + paying to the channel initiator. This is intended for use on leased channels + to guarantee that the channel initiator has no incentives to close a leased + channel before its maturity date. + */ + SCRIPT_ENFORCED_LEASE = 4; +} + +message ChannelConstraints { + /* + The CSV delay expressed in relative blocks. If the channel is force closed, + we will need to wait for this many blocks before we can regain our funds. + */ + uint32 csv_delay = 1; + + // The minimum satoshis this node is required to reserve in its balance. + uint64 chan_reserve_sat = 2; + + // The dust limit (in satoshis) of the initiator's commitment tx. + uint64 dust_limit_sat = 3; + + // The maximum amount of coins in millisatoshis that can be pending in this + // channel. + uint64 max_pending_amt_msat = 4; + + // The smallest HTLC in millisatoshis that the initiator will accept. + uint64 min_htlc_msat = 5; + + // The total number of incoming HTLC's that the initiator will accept. + uint32 max_accepted_htlcs = 6; +} + +message Channel { + // Whether this channel is active or not + bool active = 1; + + // The identity pubkey of the remote node + string remote_pubkey = 2; + + /* + The outpoint (txid:index) of the funding transaction. With this value, Bob + will be able to generate a signature for Alice's version of the commitment + transaction. + */ + string channel_point = 3; + + /* + The unique channel ID for the channel. The first 3 bytes are the block + height, the next 3 the index within the block, and the last 2 bytes are the + output index for the channel. + */ + uint64 chan_id = 4 [jstype = JS_STRING]; + + // The total amount of funds held in this channel + int64 capacity = 5; + + // This node's current balance in this channel + int64 local_balance = 6; + + // The counterparty's current balance in this channel + int64 remote_balance = 7; + + /* + The amount calculated to be paid in fees for the current set of commitment + transactions. The fee amount is persisted with the channel in order to + allow the fee amount to be removed and recalculated with each channel state + update, including updates that happen after a system restart. + */ + int64 commit_fee = 8; + + // The weight of the commitment transaction + int64 commit_weight = 9; + + /* + The required number of satoshis per kilo-weight that the requester will pay + at all times, for both the funding transaction and commitment transaction. + This value can later be updated once the channel is open. + */ + int64 fee_per_kw = 10; + + // The unsettled balance in this channel + int64 unsettled_balance = 11; + + /* + The total number of satoshis we've sent within this channel. + */ + int64 total_satoshis_sent = 12; + + /* + The total number of satoshis we've received within this channel. + */ + int64 total_satoshis_received = 13; + + /* + The total number of updates conducted within this channel. + */ + uint64 num_updates = 14; + + /* + The list of active, uncleared HTLCs currently pending within the channel. + */ + repeated HTLC pending_htlcs = 15; + + /* + Deprecated. The CSV delay expressed in relative blocks. If the channel is + force closed, we will need to wait for this many blocks before we can regain + our funds. + */ + uint32 csv_delay = 16 [deprecated = true]; + + // Whether this channel is advertised to the network or not. + bool private = 17; + + // True if we were the ones that created the channel. + bool initiator = 18; + + // A set of flags showing the current state of the channel. + string chan_status_flags = 19; + + // Deprecated. The minimum satoshis this node is required to reserve in its + // balance. + int64 local_chan_reserve_sat = 20 [deprecated = true]; + + /* + Deprecated. The minimum satoshis the other node is required to reserve in + its balance. + */ + int64 remote_chan_reserve_sat = 21 [deprecated = true]; + + // Deprecated. Use commitment_type. + bool static_remote_key = 22 [deprecated = true]; + + // The commitment type used by this channel. + CommitmentType commitment_type = 26; + + /* + The number of seconds that the channel has been monitored by the channel + scoring system. Scores are currently not persisted, so this value may be + less than the lifetime of the channel [EXPERIMENTAL]. + */ + int64 lifetime = 23; + + /* + The number of seconds that the remote peer has been observed as being online + by the channel scoring system over the lifetime of the channel + [EXPERIMENTAL]. + */ + int64 uptime = 24; + + /* + Close address is the address that we will enforce payout to on cooperative + close if the channel was opened utilizing option upfront shutdown. This + value can be set on channel open by setting close_address in an open channel + request. If this value is not set, you can still choose a payout address by + cooperatively closing with the delivery_address field set. + */ + string close_address = 25; + + /* + The amount that the initiator of the channel optionally pushed to the remote + party on channel open. This amount will be zero if the channel initiator did + not push any funds to the remote peer. If the initiator field is true, we + pushed this amount to our peer, if it is false, the remote peer pushed this + amount to us. + */ + uint64 push_amount_sat = 27; + + /* + This uint32 indicates if this channel is to be considered 'frozen'. A + frozen channel doest not allow a cooperative channel close by the + initiator. The thaw_height is the height that this restriction stops + applying to the channel. This field is optional, not setting it or using a + value of zero will mean the channel has no additional restrictions. The + height can be interpreted in two ways: as a relative height if the value is + less than 500,000, or as an absolute height otherwise. + */ + uint32 thaw_height = 28; + + // List constraints for the local node. + ChannelConstraints local_constraints = 29; + + // List constraints for the remote node. + ChannelConstraints remote_constraints = 30; + + /* + This lists out the set of alias short channel ids that exist for a channel. + This may be empty. + */ + repeated uint64 alias_scids = 31; + + // Whether or not this is a zero-conf channel. + bool zero_conf = 32; + + // This is the confirmed / on-chain zero-conf SCID. + uint64 zero_conf_confirmed_scid = 33; +} + +message ListChannelsRequest { + bool active_only = 1; + bool inactive_only = 2; + bool public_only = 3; + bool private_only = 4; + + /* + Filters the response for channels with a target peer's pubkey. If peer is + empty, all channels will be returned. + */ + bytes peer = 5; +} +message ListChannelsResponse { + // The list of active channels + repeated Channel channels = 11; +} + +message AliasMap { + /* + For non-zero-conf channels, this is the confirmed SCID. Otherwise, this is + the first assigned "base" alias. + */ + uint64 base_scid = 1; + + // The set of all aliases stored for the base SCID. + repeated uint64 aliases = 2; +} +message ListAliasesRequest { +} +message ListAliasesResponse { + repeated AliasMap alias_maps = 1; +} + +enum Initiator { + INITIATOR_UNKNOWN = 0; + INITIATOR_LOCAL = 1; + INITIATOR_REMOTE = 2; + INITIATOR_BOTH = 3; +} + +message ChannelCloseSummary { + // The outpoint (txid:index) of the funding transaction. + string channel_point = 1; + + // The unique channel ID for the channel. + uint64 chan_id = 2 [jstype = JS_STRING]; + + // The hash of the genesis block that this channel resides within. + string chain_hash = 3; + + // The txid of the transaction which ultimately closed this channel. + string closing_tx_hash = 4; + + // Public key of the remote peer that we formerly had a channel with. + string remote_pubkey = 5; + + // Total capacity of the channel. + int64 capacity = 6; + + // Height at which the funding transaction was spent. + uint32 close_height = 7; + + // Settled balance at the time of channel closure + int64 settled_balance = 8; + + // The sum of all the time-locked outputs at the time of channel closure + int64 time_locked_balance = 9; + + enum ClosureType { + COOPERATIVE_CLOSE = 0; + LOCAL_FORCE_CLOSE = 1; + REMOTE_FORCE_CLOSE = 2; + BREACH_CLOSE = 3; + FUNDING_CANCELED = 4; + ABANDONED = 5; + } + + // Details on how the channel was closed. + ClosureType close_type = 10; + + /* + Open initiator is the party that initiated opening the channel. Note that + this value may be unknown if the channel was closed before we migrated to + store open channel information after close. + */ + Initiator open_initiator = 11; + + /* + Close initiator indicates which party initiated the close. This value will + be unknown for channels that were cooperatively closed before we started + tracking cooperative close initiators. Note that this indicates which party + initiated a close, and it is possible for both to initiate cooperative or + force closes, although only one party's close will be confirmed on chain. + */ + Initiator close_initiator = 12; + + repeated Resolution resolutions = 13; + + /* + This lists out the set of alias short channel ids that existed for the + closed channel. This may be empty. + */ + repeated uint64 alias_scids = 14; + + // The confirmed SCID for a zero-conf channel. + uint64 zero_conf_confirmed_scid = 15 [jstype = JS_STRING]; +} + +enum ResolutionType { + TYPE_UNKNOWN = 0; + + // We resolved an anchor output. + ANCHOR = 1; + + /* + We are resolving an incoming htlc on chain. This if this htlc is + claimed, we swept the incoming htlc with the preimage. If it is timed + out, our peer swept the timeout path. + */ + INCOMING_HTLC = 2; + + /* + We are resolving an outgoing htlc on chain. If this htlc is claimed, + the remote party swept the htlc with the preimage. If it is timed out, + we swept it with the timeout path. + */ + OUTGOING_HTLC = 3; + + // We force closed and need to sweep our time locked commitment output. + COMMIT = 4; +} + +enum ResolutionOutcome { + // Outcome unknown. + OUTCOME_UNKNOWN = 0; + + // An output was claimed on chain. + CLAIMED = 1; + + // An output was left unclaimed on chain. + UNCLAIMED = 2; + + /* + ResolverOutcomeAbandoned indicates that an output that we did not + claim on chain, for example an anchor that we did not sweep and a + third party claimed on chain, or a htlc that we could not decode + so left unclaimed. + */ + ABANDONED = 3; + + /* + If we force closed our channel, our htlcs need to be claimed in two + stages. This outcome represents the broadcast of a timeout or success + transaction for this two stage htlc claim. + */ + FIRST_STAGE = 4; + + // A htlc was timed out on chain. + TIMEOUT = 5; +} + +message Resolution { + // The type of output we are resolving. + ResolutionType resolution_type = 1; + + // The outcome of our on chain action that resolved the outpoint. + ResolutionOutcome outcome = 2; + + // The outpoint that was spent by the resolution. + OutPoint outpoint = 3; + + // The amount that was claimed by the resolution. + uint64 amount_sat = 4; + + // The hex-encoded transaction ID of the sweep transaction that spent the + // output. + string sweep_txid = 5; +} + +message ClosedChannelsRequest { + bool cooperative = 1; + bool local_force = 2; + bool remote_force = 3; + bool breach = 4; + bool funding_canceled = 5; + bool abandoned = 6; +} + +message ClosedChannelsResponse { + repeated ChannelCloseSummary channels = 1; +} + +message Peer { + // The identity pubkey of the peer + string pub_key = 1; + + // Network address of the peer; eg `127.0.0.1:10011` + string address = 3; + + // Bytes of data transmitted to this peer + uint64 bytes_sent = 4; + + // Bytes of data transmitted from this peer + uint64 bytes_recv = 5; + + // Satoshis sent to this peer + int64 sat_sent = 6; + + // Satoshis received from this peer + int64 sat_recv = 7; + + // A channel is inbound if the counterparty initiated the channel + bool inbound = 8; + + // Ping time to this peer + int64 ping_time = 9; + + enum SyncType { + /* + Denotes that we cannot determine the peer's current sync type. + */ + UNKNOWN_SYNC = 0; + + /* + Denotes that we are actively receiving new graph updates from the peer. + */ + ACTIVE_SYNC = 1; + + /* + Denotes that we are not receiving new graph updates from the peer. + */ + PASSIVE_SYNC = 2; + + /* + Denotes that this peer is pinned into an active sync. + */ + PINNED_SYNC = 3; + } + + // The type of sync we are currently performing with this peer. + SyncType sync_type = 10; + + // Features advertised by the remote peer in their init message. + map features = 11; + + /* + The latest errors received from our peer with timestamps, limited to the 10 + most recent errors. These errors are tracked across peer connections, but + are not persisted across lnd restarts. Note that these errors are only + stored for peers that we have channels open with, to prevent peers from + spamming us with errors at no cost. + */ + repeated TimestampedError errors = 12; + + /* + The number of times we have recorded this peer going offline or coming + online, recorded across restarts. Note that this value is decreased over + time if the peer has not recently flapped, so that we can forgive peers + with historically high flap counts. + */ + int32 flap_count = 13; + + /* + The timestamp of the last flap we observed for this peer. If this value is + zero, we have not observed any flaps for this peer. + */ + int64 last_flap_ns = 14; + + /* + The last ping payload the peer has sent to us. + */ + bytes last_ping_payload = 15; +} + +message TimestampedError { + // The unix timestamp in seconds when the error occurred. + uint64 timestamp = 1; + + // The string representation of the error sent by our peer. + string error = 2; +} + +message ListPeersRequest { + /* + If true, only the last error that our peer sent us will be returned with + the peer's information, rather than the full set of historic errors we have + stored. + */ + bool latest_error = 1; +} +message ListPeersResponse { + // The list of currently connected peers + repeated Peer peers = 1; +} + +message PeerEventSubscription { +} + +message PeerEvent { + // The identity pubkey of the peer. + string pub_key = 1; + + enum EventType { + PEER_ONLINE = 0; + PEER_OFFLINE = 1; + } + + EventType type = 2; +} + +message GetInfoRequest { +} +message GetInfoResponse { + // The version of the LND software that the node is running. + string version = 14; + + // The SHA1 commit hash that the daemon is compiled with. + string commit_hash = 20; + + // The identity pubkey of the current node. + string identity_pubkey = 1; + + // If applicable, the alias of the current node, e.g. "bob" + string alias = 2; + + // The color of the current node in hex code format + string color = 17; + + // Number of pending channels + uint32 num_pending_channels = 3; + + // Number of active channels + uint32 num_active_channels = 4; + + // Number of inactive channels + uint32 num_inactive_channels = 15; + + // Number of peers + uint32 num_peers = 5; + + // The node's current view of the height of the best block + uint32 block_height = 6; + + // The node's current view of the hash of the best block + string block_hash = 8; + + // Timestamp of the block best known to the wallet + int64 best_header_timestamp = 13; + + // Whether the wallet's view is synced to the main chain + bool synced_to_chain = 9; + + // Whether we consider ourselves synced with the public channel graph. + bool synced_to_graph = 18; + + /* + Whether the current node is connected to testnet. This field is + deprecated and the network field should be used instead + **/ + bool testnet = 10 [deprecated = true]; + + reserved 11; + + // A list of active chains the node is connected to + repeated Chain chains = 16; + + // The URIs of the current node. + repeated string uris = 12; + + /* + Features that our node has advertised in our init message, node + announcements and invoices. + */ + map features = 19; + + /* + Indicates whether the HTLC interceptor API is in always-on mode. + */ + bool require_htlc_interceptor = 21; +} + +message GetRecoveryInfoRequest { +} +message GetRecoveryInfoResponse { + // Whether the wallet is in recovery mode + bool recovery_mode = 1; + + // Whether the wallet recovery progress is finished + bool recovery_finished = 2; + + // The recovery progress, ranging from 0 to 1. + double progress = 3; +} + +message Chain { + // The blockchain the node is on (eg bitcoin, litecoin) + string chain = 1; + + // The network the node is on (eg regtest, testnet, mainnet) + string network = 2; +} + +message ConfirmationUpdate { + bytes block_sha = 1; + int32 block_height = 2; + + uint32 num_confs_left = 3; +} + +message ChannelOpenUpdate { + ChannelPoint channel_point = 1; +} + +message ChannelCloseUpdate { + bytes closing_txid = 1; + + bool success = 2; +} + +message CloseChannelRequest { + /* + The outpoint (txid:index) of the funding transaction. With this value, Bob + will be able to generate a signature for Alice's version of the commitment + transaction. + */ + ChannelPoint channel_point = 1; + + // If true, then the channel will be closed forcibly. This means the + // current commitment transaction will be signed and broadcast. + bool force = 2; + + // The target number of blocks that the closure transaction should be + // confirmed by. + int32 target_conf = 3; + + // Deprecated, use sat_per_vbyte. + // A manual fee rate set in sat/vbyte that should be used when crafting the + // closure transaction. + int64 sat_per_byte = 4 [deprecated = true]; + + /* + An optional address to send funds to in the case of a cooperative close. + If the channel was opened with an upfront shutdown script and this field + is set, the request to close will fail because the channel must pay out + to the upfront shutdown addresss. + */ + string delivery_address = 5; + + // A manual fee rate set in sat/vbyte that should be used when crafting the + // closure transaction. + uint64 sat_per_vbyte = 6; + + // The maximum fee rate the closer is willing to pay. + // + // NOTE: This field is only respected if we're the initiator of the channel. + uint64 max_fee_per_vbyte = 7; +} + +message CloseStatusUpdate { + oneof update { + PendingUpdate close_pending = 1; + ChannelCloseUpdate chan_close = 3; + } +} + +message PendingUpdate { + bytes txid = 1; + uint32 output_index = 2; +} + +message ReadyForPsbtFunding { + /* + The P2WSH address of the channel funding multisig address that the below + specified amount in satoshis needs to be sent to. + */ + string funding_address = 1; + + /* + The exact amount in satoshis that needs to be sent to the above address to + fund the pending channel. + */ + int64 funding_amount = 2; + + /* + A raw PSBT that contains the pending channel output. If a base PSBT was + provided in the PsbtShim, this is the base PSBT with one additional output. + If no base PSBT was specified, this is an otherwise empty PSBT with exactly + one output. + */ + bytes psbt = 3; +} + +message BatchOpenChannelRequest { + // The list of channels to open. + repeated BatchOpenChannel channels = 1; + + // The target number of blocks that the funding transaction should be + // confirmed by. + int32 target_conf = 2; + + // A manual fee rate set in sat/vByte that should be used when crafting the + // funding transaction. + int64 sat_per_vbyte = 3; + + // The minimum number of confirmations each one of your outputs used for + // the funding transaction must satisfy. + int32 min_confs = 4; + + // Whether unconfirmed outputs should be used as inputs for the funding + // transaction. + bool spend_unconfirmed = 5; + + // An optional label for the batch transaction, limited to 500 characters. + string label = 6; +} + +message BatchOpenChannel { + // The pubkey of the node to open a channel with. When using REST, this + // field must be encoded as base64. + bytes node_pubkey = 1; + + // The number of satoshis the wallet should commit to the channel. + int64 local_funding_amount = 2; + + // The number of satoshis to push to the remote side as part of the initial + // commitment state. + int64 push_sat = 3; + + // Whether this channel should be private, not announced to the greater + // network. + bool private = 4; + + // The minimum value in millisatoshi we will require for incoming HTLCs on + // the channel. + int64 min_htlc_msat = 5; + + // The delay we require on the remote's commitment transaction. If this is + // not set, it will be scaled automatically with the channel size. + uint32 remote_csv_delay = 6; + + /* + Close address is an optional address which specifies the address to which + funds should be paid out to upon cooperative close. This field may only be + set if the peer supports the option upfront feature bit (call listpeers + to check). The remote peer will only accept cooperative closes to this + address if it is set. + + Note: If this value is set on channel creation, you will *not* be able to + cooperatively close out to a different address. + */ + string close_address = 7; + + /* + An optional, unique identifier of 32 random bytes that will be used as the + pending channel ID to identify the channel while it is in the pre-pending + state. + */ + bytes pending_chan_id = 8; + + /* + The explicit commitment type to use. Note this field will only be used if + the remote peer supports explicit channel negotiation. + */ + CommitmentType commitment_type = 9; +} + +message BatchOpenChannelResponse { + repeated PendingUpdate pending_channels = 1; +} + +message OpenChannelRequest { + // A manual fee rate set in sat/vbyte that should be used when crafting the + // funding transaction. + uint64 sat_per_vbyte = 1; + + /* + The pubkey of the node to open a channel with. When using REST, this field + must be encoded as base64. + */ + bytes node_pubkey = 2; + + /* + The hex encoded pubkey of the node to open a channel with. Deprecated now + that the REST gateway supports base64 encoding of bytes fields. + */ + string node_pubkey_string = 3 [deprecated = true]; + + // The number of satoshis the wallet should commit to the channel + int64 local_funding_amount = 4; + + // The number of satoshis to push to the remote side as part of the initial + // commitment state + int64 push_sat = 5; + + // The target number of blocks that the funding transaction should be + // confirmed by. + int32 target_conf = 6; + + // Deprecated, use sat_per_vbyte. + // A manual fee rate set in sat/vbyte that should be used when crafting the + // funding transaction. + int64 sat_per_byte = 7 [deprecated = true]; + + // Whether this channel should be private, not announced to the greater + // network. + bool private = 8; + + // The minimum value in millisatoshi we will require for incoming HTLCs on + // the channel. + int64 min_htlc_msat = 9; + + // The delay we require on the remote's commitment transaction. If this is + // not set, it will be scaled automatically with the channel size. + uint32 remote_csv_delay = 10; + + // The minimum number of confirmations each one of your outputs used for + // the funding transaction must satisfy. + int32 min_confs = 11; + + // Whether unconfirmed outputs should be used as inputs for the funding + // transaction. + bool spend_unconfirmed = 12; + + /* + Close address is an optional address which specifies the address to which + funds should be paid out to upon cooperative close. This field may only be + set if the peer supports the option upfront feature bit (call listpeers + to check). The remote peer will only accept cooperative closes to this + address if it is set. + + Note: If this value is set on channel creation, you will *not* be able to + cooperatively close out to a different address. + */ + string close_address = 13; + + /* + Funding shims are an optional argument that allow the caller to intercept + certain funding functionality. For example, a shim can be provided to use a + particular key for the commitment key (ideally cold) rather than use one + that is generated by the wallet as normal, or signal that signing will be + carried out in an interactive manner (PSBT based). + */ + FundingShim funding_shim = 14; + + /* + The maximum amount of coins in millisatoshi that can be pending within + the channel. It only applies to the remote party. + */ + uint64 remote_max_value_in_flight_msat = 15; + + /* + The maximum number of concurrent HTLCs we will allow the remote party to add + to the commitment transaction. + */ + uint32 remote_max_htlcs = 16; + + /* + Max local csv is the maximum csv delay we will allow for our own commitment + transaction. + */ + uint32 max_local_csv = 17; + + /* + The explicit commitment type to use. Note this field will only be used if + the remote peer supports explicit channel negotiation. + */ + CommitmentType commitment_type = 18; + + /* + If this is true, then a zero-conf channel open will be attempted. + */ + bool zero_conf = 19; + + /* + If this is true, then an option-scid-alias channel-type open will be + attempted. + */ + bool scid_alias = 20; +} +message OpenStatusUpdate { + oneof update { + /* + Signals that the channel is now fully negotiated and the funding + transaction published. + */ + PendingUpdate chan_pending = 1; + + /* + Signals that the channel's funding transaction has now reached the + required number of confirmations on chain and can be used. + */ + ChannelOpenUpdate chan_open = 3; + + /* + Signals that the funding process has been suspended and the construction + of a PSBT that funds the channel PK script is now required. + */ + ReadyForPsbtFunding psbt_fund = 5; + } + + /* + The pending channel ID of the created channel. This value may be used to + further the funding flow manually via the FundingStateStep method. + */ + bytes pending_chan_id = 4; +} + +message KeyLocator { + // The family of key being identified. + int32 key_family = 1; + + // The precise index of the key being identified. + int32 key_index = 2; +} + +message KeyDescriptor { + /* + The raw bytes of the key being identified. + */ + bytes raw_key_bytes = 1; + + /* + The key locator that identifies which key to use for signing. + */ + KeyLocator key_loc = 2; +} + +message ChanPointShim { + /* + The size of the pre-crafted output to be used as the channel point for this + channel funding. + */ + int64 amt = 1; + + // The target channel point to refrence in created commitment transactions. + ChannelPoint chan_point = 2; + + // Our local key to use when creating the multi-sig output. + KeyDescriptor local_key = 3; + + // The key of the remote party to use when creating the multi-sig output. + bytes remote_key = 4; + + /* + If non-zero, then this will be used as the pending channel ID on the wire + protocol to initate the funding request. This is an optional field, and + should only be set if the responder is already expecting a specific pending + channel ID. + */ + bytes pending_chan_id = 5; + + /* + This uint32 indicates if this channel is to be considered 'frozen'. A frozen + channel does not allow a cooperative channel close by the initiator. The + thaw_height is the height that this restriction stops applying to the + channel. The height can be interpreted in two ways: as a relative height if + the value is less than 500,000, or as an absolute height otherwise. + */ + uint32 thaw_height = 6; +} + +message PsbtShim { + /* + A unique identifier of 32 random bytes that will be used as the pending + channel ID to identify the PSBT state machine when interacting with it and + on the wire protocol to initiate the funding request. + */ + bytes pending_chan_id = 1; + + /* + An optional base PSBT the new channel output will be added to. If this is + non-empty, it must be a binary serialized PSBT. + */ + bytes base_psbt = 2; + + /* + If a channel should be part of a batch (multiple channel openings in one + transaction), it can be dangerous if the whole batch transaction is + published too early before all channel opening negotiations are completed. + This flag prevents this particular channel from broadcasting the transaction + after the negotiation with the remote peer. In a batch of channel openings + this flag should be set to true for every channel but the very last. + */ + bool no_publish = 3; +} + +message FundingShim { + oneof shim { + /* + A channel shim where the channel point was fully constructed outside + of lnd's wallet and the transaction might already be published. + */ + ChanPointShim chan_point_shim = 1; + + /* + A channel shim that uses a PSBT to fund and sign the channel funding + transaction. + */ + PsbtShim psbt_shim = 2; + } +} + +message FundingShimCancel { + // The pending channel ID of the channel to cancel the funding shim for. + bytes pending_chan_id = 1; +} + +message FundingPsbtVerify { + /* + The funded but not yet signed PSBT that sends the exact channel capacity + amount to the PK script returned in the open channel message in a previous + step. + */ + bytes funded_psbt = 1; + + // The pending channel ID of the channel to get the PSBT for. + bytes pending_chan_id = 2; + + /* + Can only be used if the no_publish flag was set to true in the OpenChannel + call meaning that the caller is solely responsible for publishing the final + funding transaction. If skip_finalize is set to true then lnd will not wait + for a FundingPsbtFinalize state step and instead assumes that a transaction + with the same TXID as the passed in PSBT will eventually confirm. + IT IS ABSOLUTELY IMPERATIVE that the TXID of the transaction that is + eventually published does have the _same TXID_ as the verified PSBT. That + means no inputs or outputs can change, only signatures can be added. If the + TXID changes between this call and the publish step then the channel will + never be created and the funds will be in limbo. + */ + bool skip_finalize = 3; +} + +message FundingPsbtFinalize { + /* + The funded PSBT that contains all witness data to send the exact channel + capacity amount to the PK script returned in the open channel message in a + previous step. Cannot be set at the same time as final_raw_tx. + */ + bytes signed_psbt = 1; + + // The pending channel ID of the channel to get the PSBT for. + bytes pending_chan_id = 2; + + /* + As an alternative to the signed PSBT with all witness data, the final raw + wire format transaction can also be specified directly. Cannot be set at the + same time as signed_psbt. + */ + bytes final_raw_tx = 3; +} + +message FundingTransitionMsg { + oneof trigger { + /* + The funding shim to register. This should be used before any + channel funding has began by the remote party, as it is intended as a + preparatory step for the full channel funding. + */ + FundingShim shim_register = 1; + + // Used to cancel an existing registered funding shim. + FundingShimCancel shim_cancel = 2; + + /* + Used to continue a funding flow that was initiated to be executed + through a PSBT. This step verifies that the PSBT contains the correct + outputs to fund the channel. + */ + FundingPsbtVerify psbt_verify = 3; + + /* + Used to continue a funding flow that was initiated to be executed + through a PSBT. This step finalizes the funded and signed PSBT, finishes + negotiation with the peer and finally publishes the resulting funding + transaction. + */ + FundingPsbtFinalize psbt_finalize = 4; + } +} + +message FundingStateStepResp { +} + +message PendingHTLC { + // The direction within the channel that the htlc was sent + bool incoming = 1; + + // The total value of the htlc + int64 amount = 2; + + // The final output to be swept back to the user's wallet + string outpoint = 3; + + // The next block height at which we can spend the current stage + uint32 maturity_height = 4; + + /* + The number of blocks remaining until the current stage can be swept. + Negative values indicate how many blocks have passed since becoming + mature. + */ + int32 blocks_til_maturity = 5; + + // Indicates whether the htlc is in its first or second stage of recovery + uint32 stage = 6; +} + +message PendingChannelsRequest { +} +message PendingChannelsResponse { + message PendingChannel { + string remote_node_pub = 1; + string channel_point = 2; + + int64 capacity = 3; + + int64 local_balance = 4; + int64 remote_balance = 5; + + // The minimum satoshis this node is required to reserve in its + // balance. + int64 local_chan_reserve_sat = 6; + + /* + The minimum satoshis the other node is required to reserve in its + balance. + */ + int64 remote_chan_reserve_sat = 7; + + // The party that initiated opening the channel. + Initiator initiator = 8; + + // The commitment type used by this channel. + CommitmentType commitment_type = 9; + + // Total number of forwarding packages created in this channel. + int64 num_forwarding_packages = 10; + + // A set of flags showing the current state of the channel. + string chan_status_flags = 11; + + // Whether this channel is advertised to the network or not. + bool private = 12; + } + + message PendingOpenChannel { + // The pending channel + PendingChannel channel = 1; + + /* + The amount calculated to be paid in fees for the current set of + commitment transactions. The fee amount is persisted with the channel + in order to allow the fee amount to be removed and recalculated with + each channel state update, including updates that happen after a system + restart. + */ + int64 commit_fee = 4; + + // The weight of the commitment transaction + int64 commit_weight = 5; + + /* + The required number of satoshis per kilo-weight that the requester will + pay at all times, for both the funding transaction and commitment + transaction. This value can later be updated once the channel is open. + */ + int64 fee_per_kw = 6; + + // Previously used for confirmation_height. Do not reuse. + reserved 2; + } + + message WaitingCloseChannel { + // The pending channel waiting for closing tx to confirm + PendingChannel channel = 1; + + // The balance in satoshis encumbered in this channel + int64 limbo_balance = 2; + + /* + A list of valid commitment transactions. Any of these can confirm at + this point. + */ + Commitments commitments = 3; + + // The transaction id of the closing transaction + string closing_txid = 4; + } + + message Commitments { + // Hash of the local version of the commitment tx. + string local_txid = 1; + + // Hash of the remote version of the commitment tx. + string remote_txid = 2; + + // Hash of the remote pending version of the commitment tx. + string remote_pending_txid = 3; + + /* + The amount in satoshis calculated to be paid in fees for the local + commitment. + */ + uint64 local_commit_fee_sat = 4; + + /* + The amount in satoshis calculated to be paid in fees for the remote + commitment. + */ + uint64 remote_commit_fee_sat = 5; + + /* + The amount in satoshis calculated to be paid in fees for the remote + pending commitment. + */ + uint64 remote_pending_commit_fee_sat = 6; + } + + message ClosedChannel { + // The pending channel to be closed + PendingChannel channel = 1; + + // The transaction id of the closing transaction + string closing_txid = 2; + } + + message ForceClosedChannel { + // The pending channel to be force closed + PendingChannel channel = 1; + + // The transaction id of the closing transaction + string closing_txid = 2; + + // The balance in satoshis encumbered in this pending channel + int64 limbo_balance = 3; + + // The height at which funds can be swept into the wallet + uint32 maturity_height = 4; + + /* + Remaining # of blocks until the commitment output can be swept. + Negative values indicate how many blocks have passed since becoming + mature. + */ + int32 blocks_til_maturity = 5; + + // The total value of funds successfully recovered from this channel + int64 recovered_balance = 6; + + repeated PendingHTLC pending_htlcs = 8; + + enum AnchorState { + LIMBO = 0; + RECOVERED = 1; + LOST = 2; + } + + AnchorState anchor = 9; + } + + // The balance in satoshis encumbered in pending channels + int64 total_limbo_balance = 1; + + // Channels pending opening + repeated PendingOpenChannel pending_open_channels = 2; + + /* + Deprecated: Channels pending closing previously contained cooperatively + closed channels with a single confirmation. These channels are now + considered closed from the time we see them on chain. + */ + repeated ClosedChannel pending_closing_channels = 3 [deprecated = true]; + + // Channels pending force closing + repeated ForceClosedChannel pending_force_closing_channels = 4; + + // Channels waiting for closing tx to confirm + repeated WaitingCloseChannel waiting_close_channels = 5; +} + +message ChannelEventSubscription { +} + +message ChannelEventUpdate { + oneof channel { + Channel open_channel = 1; + ChannelCloseSummary closed_channel = 2; + ChannelPoint active_channel = 3; + ChannelPoint inactive_channel = 4; + PendingUpdate pending_open_channel = 6; + ChannelPoint fully_resolved_channel = 7; + } + + enum UpdateType { + OPEN_CHANNEL = 0; + CLOSED_CHANNEL = 1; + ACTIVE_CHANNEL = 2; + INACTIVE_CHANNEL = 3; + PENDING_OPEN_CHANNEL = 4; + FULLY_RESOLVED_CHANNEL = 5; + } + + UpdateType type = 5; +} + +message WalletAccountBalance { + // The confirmed balance of the account (with >= 1 confirmations). + int64 confirmed_balance = 1; + + // The unconfirmed balance of the account (with 0 confirmations). + int64 unconfirmed_balance = 2; +} + +message WalletBalanceRequest { +} + +message WalletBalanceResponse { + // The balance of the wallet + int64 total_balance = 1; + + // The confirmed balance of a wallet(with >= 1 confirmations) + int64 confirmed_balance = 2; + + // The unconfirmed balance of a wallet(with 0 confirmations) + int64 unconfirmed_balance = 3; + + // The total amount of wallet UTXOs held in outputs that are locked for + // other usage. + int64 locked_balance = 5; + + // The amount of reserve required. + int64 reserved_balance_anchor_chan = 6; + + // A mapping of each wallet account's name to its balance. + map account_balance = 4; +} + +message Amount { + // Value denominated in satoshis. + uint64 sat = 1; + + // Value denominated in milli-satoshis. + uint64 msat = 2; +} + +message ChannelBalanceRequest { +} +message ChannelBalanceResponse { + // Deprecated. Sum of channels balances denominated in satoshis + int64 balance = 1 [deprecated = true]; + + // Deprecated. Sum of channels pending balances denominated in satoshis + int64 pending_open_balance = 2 [deprecated = true]; + + // Sum of channels local balances. + Amount local_balance = 3; + + // Sum of channels remote balances. + Amount remote_balance = 4; + + // Sum of channels local unsettled balances. + Amount unsettled_local_balance = 5; + + // Sum of channels remote unsettled balances. + Amount unsettled_remote_balance = 6; + + // Sum of channels pending local balances. + Amount pending_open_local_balance = 7; + + // Sum of channels pending remote balances. + Amount pending_open_remote_balance = 8; +} + +message QueryRoutesRequest { + // The 33-byte hex-encoded public key for the payment destination + string pub_key = 1; + + /* + The amount to send expressed in satoshis. + + The fields amt and amt_msat are mutually exclusive. + */ + int64 amt = 2; + + /* + The amount to send expressed in millisatoshis. + + The fields amt and amt_msat are mutually exclusive. + */ + int64 amt_msat = 12; + + reserved 3; + + /* + An optional CLTV delta from the current height that should be used for the + timelock of the final hop. Note that unlike SendPayment, QueryRoutes does + not add any additional block padding on top of final_ctlv_delta. This + padding of a few blocks needs to be added manually or otherwise failures may + happen when a block comes in while the payment is in flight. + */ + int32 final_cltv_delta = 4; + + /* + The maximum number of satoshis that will be paid as a fee of the payment. + This value can be represented either as a percentage of the amount being + sent, or as a fixed amount of the maximum fee the user is willing the pay to + send the payment. If not specified, lnd will use a default value of 100% + fees for small amounts (<=1k sat) or 5% fees for larger amounts. + */ + FeeLimit fee_limit = 5; + + /* + A list of nodes to ignore during path finding. When using REST, these fields + must be encoded as base64. + */ + repeated bytes ignored_nodes = 6; + + /* + Deprecated. A list of edges to ignore during path finding. + */ + repeated EdgeLocator ignored_edges = 7 [deprecated = true]; + + /* + The source node where the request route should originated from. If empty, + self is assumed. + */ + string source_pub_key = 8; + + /* + If set to true, edge probabilities from mission control will be used to get + the optimal route. + */ + bool use_mission_control = 9; + + /* + A list of directed node pairs that will be ignored during path finding. + */ + repeated NodePair ignored_pairs = 10; + + /* + An optional maximum total time lock for the route. If the source is empty or + ourselves, this should not exceed lnd's `--max-cltv-expiry` setting. If + zero, then the value of `--max-cltv-expiry` is used as the limit. + */ + uint32 cltv_limit = 11; + + /* + An optional field that can be used to pass an arbitrary set of TLV records + to a peer which understands the new records. This can be used to pass + application specific data during the payment attempt. If the destination + does not support the specified records, an error will be returned. + Record types are required to be in the custom range >= 65536. When using + REST, the values must be encoded as base64. + */ + map dest_custom_records = 13; + + /* + The channel id of the channel that must be taken to the first hop. If zero, + any channel may be used. + */ + uint64 outgoing_chan_id = 14 [jstype = JS_STRING]; + + /* + The pubkey of the last hop of the route. If empty, any hop may be used. + */ + bytes last_hop_pubkey = 15; + + /* + Optional route hints to reach the destination through private channels. + */ + repeated lnrpc.RouteHint route_hints = 16; + + /* + Features assumed to be supported by the final node. All transitive feature + dependencies must also be set properly. For a given feature bit pair, either + optional or remote may be set, but not both. If this field is nil or empty, + the router will try to load destination features from the graph as a + fallback. + */ + repeated lnrpc.FeatureBit dest_features = 17; + + /* + The time preference for this payment. Set to -1 to optimize for fees + only, to 1 to optimize for reliability only or a value inbetween for a mix. + */ + double time_pref = 18; +} + +message NodePair { + /* + The sending node of the pair. When using REST, this field must be encoded as + base64. + */ + bytes from = 1; + + /* + The receiving node of the pair. When using REST, this field must be encoded + as base64. + */ + bytes to = 2; +} + +message EdgeLocator { + // The short channel id of this edge. + uint64 channel_id = 1 [jstype = JS_STRING]; + + /* + The direction of this edge. If direction_reverse is false, the direction + of this edge is from the channel endpoint with the lexicographically smaller + pub key to the endpoint with the larger pub key. If direction_reverse is + is true, the edge goes the other way. + */ + bool direction_reverse = 2; +} + +message QueryRoutesResponse { + /* + The route that results from the path finding operation. This is still a + repeated field to retain backwards compatibility. + */ + repeated Route routes = 1; + + /* + The success probability of the returned route based on the current mission + control state. [EXPERIMENTAL] + */ + double success_prob = 2; +} + +message Hop { + /* + The unique channel ID for the channel. The first 3 bytes are the block + height, the next 3 the index within the block, and the last 2 bytes are the + output index for the channel. + */ + uint64 chan_id = 1 [jstype = JS_STRING]; + int64 chan_capacity = 2 [deprecated = true]; + int64 amt_to_forward = 3 [deprecated = true]; + int64 fee = 4 [deprecated = true]; + uint32 expiry = 5; + int64 amt_to_forward_msat = 6; + int64 fee_msat = 7; + + /* + An optional public key of the hop. If the public key is given, the payment + can be executed without relying on a copy of the channel graph. + */ + string pub_key = 8; + + /* + If set to true, then this hop will be encoded using the new variable length + TLV format. Note that if any custom tlv_records below are specified, then + this field MUST be set to true for them to be encoded properly. + */ + bool tlv_payload = 9 [deprecated = true]; + + /* + An optional TLV record that signals the use of an MPP payment. If present, + the receiver will enforce that the same mpp_record is included in the final + hop payload of all non-zero payments in the HTLC set. If empty, a regular + single-shot payment is or was attempted. + */ + MPPRecord mpp_record = 10; + + /* + An optional TLV record that signals the use of an AMP payment. If present, + the receiver will treat all received payments including the same + (payment_addr, set_id) pair as being part of one logical payment. The + payment will be settled by XORing the root_share's together and deriving the + child hashes and preimages according to BOLT XX. Must be used in conjunction + with mpp_record. + */ + AMPRecord amp_record = 12; + + /* + An optional set of key-value TLV records. This is useful within the context + of the SendToRoute call as it allows callers to specify arbitrary K-V pairs + to drop off at each hop within the onion. + */ + map custom_records = 11; + + // The payment metadata to send along with the payment to the payee. + bytes metadata = 13; +} + +message MPPRecord { + /* + A unique, random identifier used to authenticate the sender as the intended + payer of a multi-path payment. The payment_addr must be the same for all + subpayments, and match the payment_addr provided in the receiver's invoice. + The same payment_addr must be used on all subpayments. + */ + bytes payment_addr = 11; + + /* + The total amount in milli-satoshis being sent as part of a larger multi-path + payment. The caller is responsible for ensuring subpayments to the same node + and payment_hash sum exactly to total_amt_msat. The same + total_amt_msat must be used on all subpayments. + */ + int64 total_amt_msat = 10; +} + +message AMPRecord { + bytes root_share = 1; + + bytes set_id = 2; + + uint32 child_index = 3; +} + +/* +A path through the channel graph which runs over one or more channels in +succession. This struct carries all the information required to craft the +Sphinx onion packet, and send the payment along the first hop in the path. A +route is only selected as valid if all the channels have sufficient capacity to +carry the initial payment amount after fees are accounted for. +*/ +message Route { + /* + The cumulative (final) time lock across the entire route. This is the CLTV + value that should be extended to the first hop in the route. All other hops + will decrement the time-lock as advertised, leaving enough time for all + hops to wait for or present the payment preimage to complete the payment. + */ + uint32 total_time_lock = 1; + + /* + The sum of the fees paid at each hop within the final route. In the case + of a one-hop payment, this value will be zero as we don't need to pay a fee + to ourselves. + */ + int64 total_fees = 2 [deprecated = true]; + + /* + The total amount of funds required to complete a payment over this route. + This value includes the cumulative fees at each hop. As a result, the HTLC + extended to the first-hop in the route will need to have at least this many + satoshis, otherwise the route will fail at an intermediate node due to an + insufficient amount of fees. + */ + int64 total_amt = 3 [deprecated = true]; + + /* + Contains details concerning the specific forwarding details at each hop. + */ + repeated Hop hops = 4; + + /* + The total fees in millisatoshis. + */ + int64 total_fees_msat = 5; + + /* + The total amount in millisatoshis. + */ + int64 total_amt_msat = 6; +} + +message NodeInfoRequest { + // The 33-byte hex-encoded compressed public of the target node + string pub_key = 1; + + // If true, will include all known channels associated with the node. + bool include_channels = 2; +} + +message NodeInfo { + /* + An individual vertex/node within the channel graph. A node is + connected to other nodes by one or more channel edges emanating from it. As + the graph is directed, a node will also have an incoming edge attached to + it for each outgoing edge. + */ + LightningNode node = 1; + + // The total number of channels for the node. + uint32 num_channels = 2; + + // The sum of all channels capacity for the node, denominated in satoshis. + int64 total_capacity = 3; + + // A list of all public channels for the node. + repeated ChannelEdge channels = 4; +} + +/* +An individual vertex/node within the channel graph. A node is +connected to other nodes by one or more channel edges emanating from it. As the +graph is directed, a node will also have an incoming edge attached to it for +each outgoing edge. +*/ +message LightningNode { + uint32 last_update = 1; + string pub_key = 2; + string alias = 3; + repeated NodeAddress addresses = 4; + string color = 5; + map features = 6; +} + +message NodeAddress { + string network = 1; + string addr = 2; +} + +message RoutingPolicy { + uint32 time_lock_delta = 1; + int64 min_htlc = 2; + int64 fee_base_msat = 3; + int64 fee_rate_milli_msat = 4; + bool disabled = 5; + uint64 max_htlc_msat = 6; + uint32 last_update = 7; +} + +/* +A fully authenticated channel along with all its unique attributes. +Once an authenticated channel announcement has been processed on the network, +then an instance of ChannelEdgeInfo encapsulating the channels attributes is +stored. The other portions relevant to routing policy of a channel are stored +within a ChannelEdgePolicy for each direction of the channel. +*/ +message ChannelEdge { + /* + The unique channel ID for the channel. The first 3 bytes are the block + height, the next 3 the index within the block, and the last 2 bytes are the + output index for the channel. + */ + uint64 channel_id = 1 [jstype = JS_STRING]; + string chan_point = 2; + + uint32 last_update = 3 [deprecated = true]; + + string node1_pub = 4; + string node2_pub = 5; + + int64 capacity = 6; + + RoutingPolicy node1_policy = 7; + RoutingPolicy node2_policy = 8; +} + +message ChannelGraphRequest { + /* + Whether unannounced channels are included in the response or not. If set, + unannounced channels are included. Unannounced channels are both private + channels, and public channels that are not yet announced to the network. + */ + bool include_unannounced = 1; +} + +// Returns a new instance of the directed channel graph. +message ChannelGraph { + // The list of `LightningNode`s in this channel graph + repeated LightningNode nodes = 1; + + // The list of `ChannelEdge`s in this channel graph + repeated ChannelEdge edges = 2; +} + +enum NodeMetricType { + UNKNOWN = 0; + BETWEENNESS_CENTRALITY = 1; +} + +message NodeMetricsRequest { + // The requested node metrics. + repeated NodeMetricType types = 1; +} + +message NodeMetricsResponse { + /* + Betweenness centrality is the sum of the ratio of shortest paths that pass + through the node for each pair of nodes in the graph (not counting paths + starting or ending at this node). + Map of node pubkey to betweenness centrality of the node. Normalized + values are in the [0,1] closed interval. + */ + map betweenness_centrality = 1; +} + +message FloatMetric { + // Arbitrary float value. + double value = 1; + + // The value normalized to [0,1] or [-1,1]. + double normalized_value = 2; +} + +message ChanInfoRequest { + /* + The unique channel ID for the channel. The first 3 bytes are the block + height, the next 3 the index within the block, and the last 2 bytes are the + output index for the channel. + */ + uint64 chan_id = 1 [jstype = JS_STRING]; +} + +message NetworkInfoRequest { +} +message NetworkInfo { + uint32 graph_diameter = 1; + double avg_out_degree = 2; + uint32 max_out_degree = 3; + + uint32 num_nodes = 4; + uint32 num_channels = 5; + + int64 total_network_capacity = 6; + + double avg_channel_size = 7; + int64 min_channel_size = 8; + int64 max_channel_size = 9; + int64 median_channel_size_sat = 10; + + // The number of edges marked as zombies. + uint64 num_zombie_chans = 11; + + // TODO(roasbeef): fee rate info, expiry + // * also additional RPC for tracking fee info once in +} + +message StopRequest { +} +message StopResponse { +} + +message GraphTopologySubscription { +} +message GraphTopologyUpdate { + repeated NodeUpdate node_updates = 1; + repeated ChannelEdgeUpdate channel_updates = 2; + repeated ClosedChannelUpdate closed_chans = 3; +} +message NodeUpdate { + /* + Deprecated, use node_addresses. + */ + repeated string addresses = 1 [deprecated = true]; + + string identity_key = 2; + + /* + Deprecated, use features. + */ + bytes global_features = 3 [deprecated = true]; + + string alias = 4; + string color = 5; + repeated NodeAddress node_addresses = 7; + + /* + Features that the node has advertised in the init message, node + announcements and invoices. + */ + map features = 6; +} +message ChannelEdgeUpdate { + /* + The unique channel ID for the channel. The first 3 bytes are the block + height, the next 3 the index within the block, and the last 2 bytes are the + output index for the channel. + */ + uint64 chan_id = 1 [jstype = JS_STRING]; + + ChannelPoint chan_point = 2; + + int64 capacity = 3; + + RoutingPolicy routing_policy = 4; + + string advertising_node = 5; + string connecting_node = 6; +} +message ClosedChannelUpdate { + /* + The unique channel ID for the channel. The first 3 bytes are the block + height, the next 3 the index within the block, and the last 2 bytes are the + output index for the channel. + */ + uint64 chan_id = 1 [jstype = JS_STRING]; + int64 capacity = 2; + uint32 closed_height = 3; + ChannelPoint chan_point = 4; +} + +message HopHint { + // The public key of the node at the start of the channel. + string node_id = 1; + + // The unique identifier of the channel. + uint64 chan_id = 2 [jstype = JS_STRING]; + + // The base fee of the channel denominated in millisatoshis. + uint32 fee_base_msat = 3; + + /* + The fee rate of the channel for sending one satoshi across it denominated in + millionths of a satoshi. + */ + uint32 fee_proportional_millionths = 4; + + // The time-lock delta of the channel. + uint32 cltv_expiry_delta = 5; +} + +message SetID { + bytes set_id = 1; +} + +message RouteHint { + /* + A list of hop hints that when chained together can assist in reaching a + specific destination. + */ + repeated HopHint hop_hints = 1; +} + +message AMPInvoiceState { + // The state the HTLCs associated with this setID are in. + InvoiceHTLCState state = 1; + + // The settle index of this HTLC set, if the invoice state is settled. + uint64 settle_index = 2; + + // The time this HTLC set was settled expressed in unix epoch. + int64 settle_time = 3; + + // The total amount paid for the sub-invoice expressed in milli satoshis. + int64 amt_paid_msat = 5; +} + +message Invoice { + /* + An optional memo to attach along with the invoice. Used for record keeping + purposes for the invoice's creator, and will also be set in the description + field of the encoded payment request if the description_hash field is not + being used. + */ + string memo = 1; + + reserved 2; + + /* + The hex-encoded preimage (32 byte) which will allow settling an incoming + HTLC payable to this preimage. When using REST, this field must be encoded + as base64. + */ + bytes r_preimage = 3; + + /* + The hash of the preimage. When using REST, this field must be encoded as + base64. + Note: Output only, don't specify for creating an invoice. + */ + bytes r_hash = 4; + + /* + The value of this invoice in satoshis + + The fields value and value_msat are mutually exclusive. + */ + int64 value = 5; + + /* + The value of this invoice in millisatoshis + + The fields value and value_msat are mutually exclusive. + */ + int64 value_msat = 23; + + /* + Whether this invoice has been fulfilled + + The field is deprecated. Use the state field instead (compare to SETTLED). + */ + bool settled = 6 [deprecated = true]; + + /* + When this invoice was created. + Note: Output only, don't specify for creating an invoice. + */ + int64 creation_date = 7; + + /* + When this invoice was settled. + Note: Output only, don't specify for creating an invoice. + */ + int64 settle_date = 8; + + /* + A bare-bones invoice for a payment within the Lightning Network. With the + details of the invoice, the sender has all the data necessary to send a + payment to the recipient. + Note: Output only, don't specify for creating an invoice. + */ + string payment_request = 9; + + /* + Hash (SHA-256) of a description of the payment. Used if the description of + payment (memo) is too long to naturally fit within the description field + of an encoded payment request. When using REST, this field must be encoded + as base64. + */ + bytes description_hash = 10; + + // Payment request expiry time in seconds. Default is 3600 (1 hour). + int64 expiry = 11; + + // Fallback on-chain address. + string fallback_addr = 12; + + // Delta to use for the time-lock of the CLTV extended to the final hop. + uint64 cltv_expiry = 13; + + /* + Route hints that can each be individually used to assist in reaching the + invoice's destination. + */ + repeated RouteHint route_hints = 14; + + // Whether this invoice should include routing hints for private channels. + bool private = 15; + + /* + The "add" index of this invoice. Each newly created invoice will increment + this index making it monotonically increasing. Callers to the + SubscribeInvoices call can use this to instantly get notified of all added + invoices with an add_index greater than this one. + Note: Output only, don't specify for creating an invoice. + */ + uint64 add_index = 16; + + /* + The "settle" index of this invoice. Each newly settled invoice will + increment this index making it monotonically increasing. Callers to the + SubscribeInvoices call can use this to instantly get notified of all + settled invoices with an settle_index greater than this one. + Note: Output only, don't specify for creating an invoice. + */ + uint64 settle_index = 17; + + // Deprecated, use amt_paid_sat or amt_paid_msat. + int64 amt_paid = 18 [deprecated = true]; + + /* + The amount that was accepted for this invoice, in satoshis. This will ONLY + be set if this invoice has been settled. We provide this field as if the + invoice was created with a zero value, then we need to record what amount + was ultimately accepted. Additionally, it's possible that the sender paid + MORE that was specified in the original invoice. So we'll record that here + as well. + Note: Output only, don't specify for creating an invoice. + */ + int64 amt_paid_sat = 19; + + /* + The amount that was accepted for this invoice, in millisatoshis. This will + ONLY be set if this invoice has been settled. We provide this field as if + the invoice was created with a zero value, then we need to record what + amount was ultimately accepted. Additionally, it's possible that the sender + paid MORE that was specified in the original invoice. So we'll record that + here as well. + Note: Output only, don't specify for creating an invoice. + */ + int64 amt_paid_msat = 20; + + enum InvoiceState { + OPEN = 0; + SETTLED = 1; + CANCELED = 2; + ACCEPTED = 3; + } + + /* + The state the invoice is in. + Note: Output only, don't specify for creating an invoice. + */ + InvoiceState state = 21; + + /* + List of HTLCs paying to this invoice [EXPERIMENTAL]. + Note: Output only, don't specify for creating an invoice. + */ + repeated InvoiceHTLC htlcs = 22; + + /* + List of features advertised on the invoice. + Note: Output only, don't specify for creating an invoice. + */ + map features = 24; + + /* + Indicates if this invoice was a spontaneous payment that arrived via keysend + [EXPERIMENTAL]. + Note: Output only, don't specify for creating an invoice. + */ + bool is_keysend = 25; + + /* + The payment address of this invoice. This value will be used in MPP + payments, and also for newer invoices that always require the MPP payload + for added end-to-end security. + Note: Output only, don't specify for creating an invoice. + */ + bytes payment_addr = 26; + + /* + Signals whether or not this is an AMP invoice. + */ + bool is_amp = 27; + + /* + [EXPERIMENTAL]: + + Maps a 32-byte hex-encoded set ID to the sub-invoice AMP state for the + given set ID. This field is always populated for AMP invoices, and can be + used along side LookupInvoice to obtain the HTLC information related to a + given sub-invoice. + Note: Output only, don't specify for creating an invoice. + */ + map amp_invoice_state = 28; +} + +enum InvoiceHTLCState { + ACCEPTED = 0; + SETTLED = 1; + CANCELED = 2; +} + +// Details of an HTLC that paid to an invoice +message InvoiceHTLC { + // Short channel id over which the htlc was received. + uint64 chan_id = 1 [jstype = JS_STRING]; + + // Index identifying the htlc on the channel. + uint64 htlc_index = 2; + + // The amount of the htlc in msat. + uint64 amt_msat = 3; + + // Block height at which this htlc was accepted. + int32 accept_height = 4; + + // Time at which this htlc was accepted. + int64 accept_time = 5; + + // Time at which this htlc was settled or canceled. + int64 resolve_time = 6; + + // Block height at which this htlc expires. + int32 expiry_height = 7; + + // Current state the htlc is in. + InvoiceHTLCState state = 8; + + // Custom tlv records. + map custom_records = 9; + + // The total amount of the mpp payment in msat. + uint64 mpp_total_amt_msat = 10; + + // Details relevant to AMP HTLCs, only populated if this is an AMP HTLC. + AMP amp = 11; +} + +// Details specific to AMP HTLCs. +message AMP { + // An n-of-n secret share of the root seed from which child payment hashes + // and preimages are derived. + bytes root_share = 1; + + // An identifier for the HTLC set that this HTLC belongs to. + bytes set_id = 2; + + // A nonce used to randomize the child preimage and child hash from a given + // root_share. + uint32 child_index = 3; + + // The payment hash of the AMP HTLC. + bytes hash = 4; + + // The preimage used to settle this AMP htlc. This field will only be + // populated if the invoice is in InvoiceState_ACCEPTED or + // InvoiceState_SETTLED. + bytes preimage = 5; +} + +message AddInvoiceResponse { + bytes r_hash = 1; + + /* + A bare-bones invoice for a payment within the Lightning Network. With the + details of the invoice, the sender has all the data necessary to send a + payment to the recipient. + */ + string payment_request = 2; + + /* + The "add" index of this invoice. Each newly created invoice will increment + this index making it monotonically increasing. Callers to the + SubscribeInvoices call can use this to instantly get notified of all added + invoices with an add_index greater than this one. + */ + uint64 add_index = 16; + + /* + The payment address of the generated invoice. This value should be used + in all payments for this invoice as we require it for end to end + security. + */ + bytes payment_addr = 17; +} +message PaymentHash { + /* + The hex-encoded payment hash of the invoice to be looked up. The passed + payment hash must be exactly 32 bytes, otherwise an error is returned. + Deprecated now that the REST gateway supports base64 encoding of bytes + fields. + */ + string r_hash_str = 1 [deprecated = true]; + + /* + The payment hash of the invoice to be looked up. When using REST, this field + must be encoded as base64. + */ + bytes r_hash = 2; +} + +message ListInvoiceRequest { + /* + If set, only invoices that are not settled and not canceled will be returned + in the response. + */ + bool pending_only = 1; + + /* + The index of an invoice that will be used as either the start or end of a + query to determine which invoices should be returned in the response. + */ + uint64 index_offset = 4; + + // The max number of invoices to return in the response to this query. + uint64 num_max_invoices = 5; + + /* + If set, the invoices returned will result from seeking backwards from the + specified index offset. This can be used to paginate backwards. + */ + bool reversed = 6; +} +message ListInvoiceResponse { + /* + A list of invoices from the time slice of the time series specified in the + request. + */ + repeated Invoice invoices = 1; + + /* + The index of the last item in the set of returned invoices. This can be used + to seek further, pagination style. + */ + uint64 last_index_offset = 2; + + /* + The index of the last item in the set of returned invoices. This can be used + to seek backwards, pagination style. + */ + uint64 first_index_offset = 3; +} + +message InvoiceSubscription { + /* + If specified (non-zero), then we'll first start by sending out + notifications for all added indexes with an add_index greater than this + value. This allows callers to catch up on any events they missed while they + weren't connected to the streaming RPC. + */ + uint64 add_index = 1; + + /* + If specified (non-zero), then we'll first start by sending out + notifications for all settled indexes with an settle_index greater than + this value. This allows callers to catch up on any events they missed while + they weren't connected to the streaming RPC. + */ + uint64 settle_index = 2; +} + +enum PaymentFailureReason { + /* + Payment isn't failed (yet). + */ + FAILURE_REASON_NONE = 0; + + /* + There are more routes to try, but the payment timeout was exceeded. + */ + FAILURE_REASON_TIMEOUT = 1; + + /* + All possible routes were tried and failed permanently. Or were no + routes to the destination at all. + */ + FAILURE_REASON_NO_ROUTE = 2; + + /* + A non-recoverable error has occured. + */ + FAILURE_REASON_ERROR = 3; + + /* + Payment details incorrect (unknown hash, invalid amt or + invalid final cltv delta) + */ + FAILURE_REASON_INCORRECT_PAYMENT_DETAILS = 4; + + /* + Insufficient local balance. + */ + FAILURE_REASON_INSUFFICIENT_BALANCE = 5; +} + +message Payment { + // The payment hash + string payment_hash = 1; + + // Deprecated, use value_sat or value_msat. + int64 value = 2 [deprecated = true]; + + // Deprecated, use creation_time_ns + int64 creation_date = 3 [deprecated = true]; + + reserved 4; + + // Deprecated, use fee_sat or fee_msat. + int64 fee = 5 [deprecated = true]; + + // The payment preimage + string payment_preimage = 6; + + // The value of the payment in satoshis + int64 value_sat = 7; + + // The value of the payment in milli-satoshis + int64 value_msat = 8; + + // The optional payment request being fulfilled. + string payment_request = 9; + + enum PaymentStatus { + UNKNOWN = 0; + IN_FLIGHT = 1; + SUCCEEDED = 2; + FAILED = 3; + } + + // The status of the payment. + PaymentStatus status = 10; + + // The fee paid for this payment in satoshis + int64 fee_sat = 11; + + // The fee paid for this payment in milli-satoshis + int64 fee_msat = 12; + + // The time in UNIX nanoseconds at which the payment was created. + int64 creation_time_ns = 13; + + // The HTLCs made in attempt to settle the payment. + repeated HTLCAttempt htlcs = 14; + + /* + The creation index of this payment. Each payment can be uniquely identified + by this index, which may not strictly increment by 1 for payments made in + older versions of lnd. + */ + uint64 payment_index = 15; + + PaymentFailureReason failure_reason = 16; +} + +message HTLCAttempt { + // The unique ID that is used for this attempt. + uint64 attempt_id = 7; + + enum HTLCStatus { + IN_FLIGHT = 0; + SUCCEEDED = 1; + FAILED = 2; + } + + // The status of the HTLC. + HTLCStatus status = 1; + + // The route taken by this HTLC. + Route route = 2; + + // The time in UNIX nanoseconds at which this HTLC was sent. + int64 attempt_time_ns = 3; + + /* + The time in UNIX nanoseconds at which this HTLC was settled or failed. + This value will not be set if the HTLC is still IN_FLIGHT. + */ + int64 resolve_time_ns = 4; + + // Detailed htlc failure info. + Failure failure = 5; + + // The preimage that was used to settle the HTLC. + bytes preimage = 6; +} + +message ListPaymentsRequest { + /* + If true, then return payments that have not yet fully completed. This means + that pending payments, as well as failed payments will show up if this + field is set to true. This flag doesn't change the meaning of the indices, + which are tied to individual payments. + */ + bool include_incomplete = 1; + + /* + The index of a payment that will be used as either the start or end of a + query to determine which payments should be returned in the response. The + index_offset is exclusive. In the case of a zero index_offset, the query + will start with the oldest payment when paginating forwards, or will end + with the most recent payment when paginating backwards. + */ + uint64 index_offset = 2; + + // The maximal number of payments returned in the response to this query. + uint64 max_payments = 3; + + /* + If set, the payments returned will result from seeking backwards from the + specified index offset. This can be used to paginate backwards. The order + of the returned payments is always oldest first (ascending index order). + */ + bool reversed = 4; + + /* + If set, all payments (complete and incomplete, independent of the + max_payments parameter) will be counted. Note that setting this to true will + increase the run time of the call significantly on systems that have a lot + of payments, as all of them have to be iterated through to be counted. + */ + bool count_total_payments = 5; +} + +message ListPaymentsResponse { + // The list of payments + repeated Payment payments = 1; + + /* + The index of the first item in the set of returned payments. This can be + used as the index_offset to continue seeking backwards in the next request. + */ + uint64 first_index_offset = 2; + + /* + The index of the last item in the set of returned payments. This can be used + as the index_offset to continue seeking forwards in the next request. + */ + uint64 last_index_offset = 3; + + /* + Will only be set if count_total_payments in the request was set. Represents + the total number of payments (complete and incomplete, independent of the + number of payments requested in the query) currently present in the payments + database. + */ + uint64 total_num_payments = 4; +} + +message DeletePaymentRequest { + // Payment hash to delete. + bytes payment_hash = 1; + + /* + Only delete failed HTLCs from the payment, not the payment itself. + */ + bool failed_htlcs_only = 2; +} + +message DeleteAllPaymentsRequest { + // Only delete failed payments. + bool failed_payments_only = 1; + + /* + Only delete failed HTLCs from payments, not the payment itself. + */ + bool failed_htlcs_only = 2; +} + +message DeletePaymentResponse { +} + +message DeleteAllPaymentsResponse { +} + +message AbandonChannelRequest { + ChannelPoint channel_point = 1; + + bool pending_funding_shim_only = 2; + + /* + Override the requirement for being in dev mode by setting this to true and + confirming the user knows what they are doing and this is a potential foot + gun to lose funds if used on active channels. + */ + bool i_know_what_i_am_doing = 3; +} + +message AbandonChannelResponse { +} + +message DebugLevelRequest { + bool show = 1; + string level_spec = 2; +} +message DebugLevelResponse { + string sub_systems = 1; +} + +message PayReqString { + // The payment request string to be decoded + string pay_req = 1; +} +message PayReq { + string destination = 1; + string payment_hash = 2; + int64 num_satoshis = 3; + int64 timestamp = 4; + int64 expiry = 5; + string description = 6; + string description_hash = 7; + string fallback_addr = 8; + int64 cltv_expiry = 9; + repeated RouteHint route_hints = 10; + bytes payment_addr = 11; + int64 num_msat = 12; + map features = 13; +} + +enum FeatureBit { + DATALOSS_PROTECT_REQ = 0; + DATALOSS_PROTECT_OPT = 1; + INITIAL_ROUING_SYNC = 3; + UPFRONT_SHUTDOWN_SCRIPT_REQ = 4; + UPFRONT_SHUTDOWN_SCRIPT_OPT = 5; + GOSSIP_QUERIES_REQ = 6; + GOSSIP_QUERIES_OPT = 7; + TLV_ONION_REQ = 8; + TLV_ONION_OPT = 9; + EXT_GOSSIP_QUERIES_REQ = 10; + EXT_GOSSIP_QUERIES_OPT = 11; + STATIC_REMOTE_KEY_REQ = 12; + STATIC_REMOTE_KEY_OPT = 13; + PAYMENT_ADDR_REQ = 14; + PAYMENT_ADDR_OPT = 15; + MPP_REQ = 16; + MPP_OPT = 17; + WUMBO_CHANNELS_REQ = 18; + WUMBO_CHANNELS_OPT = 19; + ANCHORS_REQ = 20; + ANCHORS_OPT = 21; + ANCHORS_ZERO_FEE_HTLC_REQ = 22; + ANCHORS_ZERO_FEE_HTLC_OPT = 23; + AMP_REQ = 30; + AMP_OPT = 31; +} + +message Feature { + string name = 2; + bool is_required = 3; + bool is_known = 4; +} + +message FeeReportRequest { +} +message ChannelFeeReport { + // The short channel id that this fee report belongs to. + uint64 chan_id = 5 [jstype = JS_STRING]; + + // The channel that this fee report belongs to. + string channel_point = 1; + + // The base fee charged regardless of the number of milli-satoshis sent. + int64 base_fee_msat = 2; + + // The amount charged per milli-satoshis transferred expressed in + // millionths of a satoshi. + int64 fee_per_mil = 3; + + // The effective fee rate in milli-satoshis. Computed by dividing the + // fee_per_mil value by 1 million. + double fee_rate = 4; +} +message FeeReportResponse { + // An array of channel fee reports which describes the current fee schedule + // for each channel. + repeated ChannelFeeReport channel_fees = 1; + + // The total amount of fee revenue (in satoshis) the switch has collected + // over the past 24 hrs. + uint64 day_fee_sum = 2; + + // The total amount of fee revenue (in satoshis) the switch has collected + // over the past 1 week. + uint64 week_fee_sum = 3; + + // The total amount of fee revenue (in satoshis) the switch has collected + // over the past 1 month. + uint64 month_fee_sum = 4; +} + +message PolicyUpdateRequest { + oneof scope { + // If set, then this update applies to all currently active channels. + bool global = 1; + + // If set, this update will target a specific channel. + ChannelPoint chan_point = 2; + } + + // The base fee charged regardless of the number of milli-satoshis sent. + int64 base_fee_msat = 3; + + // The effective fee rate in milli-satoshis. The precision of this value + // goes up to 6 decimal places, so 1e-6. + double fee_rate = 4; + + // The effective fee rate in micro-satoshis (parts per million). + uint32 fee_rate_ppm = 9; + + // The required timelock delta for HTLCs forwarded over the channel. + uint32 time_lock_delta = 5; + + // If set, the maximum HTLC size in milli-satoshis. If unset, the maximum + // HTLC will be unchanged. + uint64 max_htlc_msat = 6; + + // The minimum HTLC size in milli-satoshis. Only applied if + // min_htlc_msat_specified is true. + uint64 min_htlc_msat = 7; + + // If true, min_htlc_msat is applied. + bool min_htlc_msat_specified = 8; +} +enum UpdateFailure { + UPDATE_FAILURE_UNKNOWN = 0; + UPDATE_FAILURE_PENDING = 1; + UPDATE_FAILURE_NOT_FOUND = 2; + UPDATE_FAILURE_INTERNAL_ERR = 3; + UPDATE_FAILURE_INVALID_PARAMETER = 4; +} + +message FailedUpdate { + // The outpoint in format txid:n + OutPoint outpoint = 1; + + // Reason for the policy update failure. + UpdateFailure reason = 2; + + // A string representation of the policy update error. + string update_error = 3; +} + +message PolicyUpdateResponse { + // List of failed policy updates. + repeated FailedUpdate failed_updates = 1; +} + +message ForwardingHistoryRequest { + // Start time is the starting point of the forwarding history request. All + // records beyond this point will be included, respecting the end time, and + // the index offset. + uint64 start_time = 1; + + // End time is the end point of the forwarding history request. The + // response will carry at most 50k records between the start time and the + // end time. The index offset can be used to implement pagination. + uint64 end_time = 2; + + // Index offset is the offset in the time series to start at. As each + // response can only contain 50k records, callers can use this to skip + // around within a packed time series. + uint32 index_offset = 3; + + // The max number of events to return in the response to this query. + uint32 num_max_events = 4; +} +message ForwardingEvent { + // Timestamp is the time (unix epoch offset) that this circuit was + // completed. Deprecated by timestamp_ns. + uint64 timestamp = 1 [deprecated = true]; + + // The incoming channel ID that carried the HTLC that created the circuit. + uint64 chan_id_in = 2 [jstype = JS_STRING]; + + // The outgoing channel ID that carried the preimage that completed the + // circuit. + uint64 chan_id_out = 4 [jstype = JS_STRING]; + + // The total amount (in satoshis) of the incoming HTLC that created half + // the circuit. + uint64 amt_in = 5; + + // The total amount (in satoshis) of the outgoing HTLC that created the + // second half of the circuit. + uint64 amt_out = 6; + + // The total fee (in satoshis) that this payment circuit carried. + uint64 fee = 7; + + // The total fee (in milli-satoshis) that this payment circuit carried. + uint64 fee_msat = 8; + + // The total amount (in milli-satoshis) of the incoming HTLC that created + // half the circuit. + uint64 amt_in_msat = 9; + + // The total amount (in milli-satoshis) of the outgoing HTLC that created + // the second half of the circuit. + uint64 amt_out_msat = 10; + + // The number of nanoseconds elapsed since January 1, 1970 UTC when this + // circuit was completed. + uint64 timestamp_ns = 11; + + // TODO(roasbeef): add settlement latency? + // * use FPE on the chan id? + // * also list failures? +} +message ForwardingHistoryResponse { + // A list of forwarding events from the time slice of the time series + // specified in the request. + repeated ForwardingEvent forwarding_events = 1; + + // The index of the last time in the set of returned forwarding events. Can + // be used to seek further, pagination style. + uint32 last_offset_index = 2; +} + +message ExportChannelBackupRequest { + // The target channel point to obtain a back up for. + ChannelPoint chan_point = 1; +} + +message ChannelBackup { + /* + Identifies the channel that this backup belongs to. + */ + ChannelPoint chan_point = 1; + + /* + Is an encrypted single-chan backup. this can be passed to + RestoreChannelBackups, or the WalletUnlocker Init and Unlock methods in + order to trigger the recovery protocol. When using REST, this field must be + encoded as base64. + */ + bytes chan_backup = 2; +} + +message MultiChanBackup { + /* + Is the set of all channels that are included in this multi-channel backup. + */ + repeated ChannelPoint chan_points = 1; + + /* + A single encrypted blob containing all the static channel backups of the + channel listed above. This can be stored as a single file or blob, and + safely be replaced with any prior/future versions. When using REST, this + field must be encoded as base64. + */ + bytes multi_chan_backup = 2; +} + +message ChanBackupExportRequest { +} +message ChanBackupSnapshot { + /* + The set of new channels that have been added since the last channel backup + snapshot was requested. + */ + ChannelBackups single_chan_backups = 1; + + /* + A multi-channel backup that covers all open channels currently known to + lnd. + */ + MultiChanBackup multi_chan_backup = 2; +} + +message ChannelBackups { + /* + A set of single-chan static channel backups. + */ + repeated ChannelBackup chan_backups = 1; +} + +message RestoreChanBackupRequest { + oneof backup { + /* + The channels to restore as a list of channel/backup pairs. + */ + ChannelBackups chan_backups = 1; + + /* + The channels to restore in the packed multi backup format. When using + REST, this field must be encoded as base64. + */ + bytes multi_chan_backup = 2; + } +} +message RestoreBackupResponse { +} + +message ChannelBackupSubscription { +} + +message VerifyChanBackupResponse { +} + +message MacaroonPermission { + // The entity a permission grants access to. + string entity = 1; + + // The action that is granted. + string action = 2; +} +message BakeMacaroonRequest { + // The list of permissions the new macaroon should grant. + repeated MacaroonPermission permissions = 1; + + // The root key ID used to create the macaroon, must be a positive integer. + uint64 root_key_id = 2; + + /* + Informs the RPC on whether to allow external permissions that LND is not + aware of. + */ + bool allow_external_permissions = 3; +} +message BakeMacaroonResponse { + // The hex encoded macaroon, serialized in binary format. + string macaroon = 1; +} + +message ListMacaroonIDsRequest { +} +message ListMacaroonIDsResponse { + // The list of root key IDs that are in use. + repeated uint64 root_key_ids = 1; +} + +message DeleteMacaroonIDRequest { + // The root key ID to be removed. + uint64 root_key_id = 1; +} +message DeleteMacaroonIDResponse { + // A boolean indicates that the deletion is successful. + bool deleted = 1; +} + +message MacaroonPermissionList { + // A list of macaroon permissions. + repeated MacaroonPermission permissions = 1; +} + +message ListPermissionsRequest { +} +message ListPermissionsResponse { + /* + A map between all RPC method URIs and their required macaroon permissions to + access them. + */ + map method_permissions = 1; +} + +message Failure { + enum FailureCode { + /* + The numbers assigned in this enumeration match the failure codes as + defined in BOLT #4. Because protobuf 3 requires enums to start with 0, + a RESERVED value is added. + */ + RESERVED = 0; + + INCORRECT_OR_UNKNOWN_PAYMENT_DETAILS = 1; + INCORRECT_PAYMENT_AMOUNT = 2; + FINAL_INCORRECT_CLTV_EXPIRY = 3; + FINAL_INCORRECT_HTLC_AMOUNT = 4; + FINAL_EXPIRY_TOO_SOON = 5; + INVALID_REALM = 6; + EXPIRY_TOO_SOON = 7; + INVALID_ONION_VERSION = 8; + INVALID_ONION_HMAC = 9; + INVALID_ONION_KEY = 10; + AMOUNT_BELOW_MINIMUM = 11; + FEE_INSUFFICIENT = 12; + INCORRECT_CLTV_EXPIRY = 13; + CHANNEL_DISABLED = 14; + TEMPORARY_CHANNEL_FAILURE = 15; + REQUIRED_NODE_FEATURE_MISSING = 16; + REQUIRED_CHANNEL_FEATURE_MISSING = 17; + UNKNOWN_NEXT_PEER = 18; + TEMPORARY_NODE_FAILURE = 19; + PERMANENT_NODE_FAILURE = 20; + PERMANENT_CHANNEL_FAILURE = 21; + EXPIRY_TOO_FAR = 22; + MPP_TIMEOUT = 23; + INVALID_ONION_PAYLOAD = 24; + + /* + An internal error occurred. + */ + INTERNAL_FAILURE = 997; + + /* + The error source is known, but the failure itself couldn't be decoded. + */ + UNKNOWN_FAILURE = 998; + + /* + An unreadable failure result is returned if the received failure message + cannot be decrypted. In that case the error source is unknown. + */ + UNREADABLE_FAILURE = 999; + } + + // Failure code as defined in the Lightning spec + FailureCode code = 1; + + reserved 2; + + // An optional channel update message. + ChannelUpdate channel_update = 3; + + // A failure type-dependent htlc value. + uint64 htlc_msat = 4; + + // The sha256 sum of the onion payload. + bytes onion_sha_256 = 5; + + // A failure type-dependent cltv expiry value. + uint32 cltv_expiry = 6; + + // A failure type-dependent flags value. + uint32 flags = 7; + + /* + The position in the path of the intermediate or final node that generated + the failure message. Position zero is the sender node. + **/ + uint32 failure_source_index = 8; + + // A failure type-dependent block height. + uint32 height = 9; +} + +message ChannelUpdate { + /* + The signature that validates the announced data and proves the ownership + of node id. + */ + bytes signature = 1; + + /* + The target chain that this channel was opened within. This value + should be the genesis hash of the target chain. Along with the short + channel ID, this uniquely identifies the channel globally in a + blockchain. + */ + bytes chain_hash = 2; + + /* + The unique description of the funding transaction. + */ + uint64 chan_id = 3 [jstype = JS_STRING]; + + /* + A timestamp that allows ordering in the case of multiple announcements. + We should ignore the message if timestamp is not greater than the + last-received. + */ + uint32 timestamp = 4; + + /* + The bitfield that describes whether optional fields are present in this + update. Currently, the least-significant bit must be set to 1 if the + optional field MaxHtlc is present. + */ + uint32 message_flags = 10; + + /* + The bitfield that describes additional meta-data concerning how the + update is to be interpreted. Currently, the least-significant bit must be + set to 0 if the creating node corresponds to the first node in the + previously sent channel announcement and 1 otherwise. If the second bit + is set, then the channel is set to be disabled. + */ + uint32 channel_flags = 5; + + /* + The minimum number of blocks this node requires to be added to the expiry + of HTLCs. This is a security parameter determined by the node operator. + This value represents the required gap between the time locks of the + incoming and outgoing HTLC's set to this node. + */ + uint32 time_lock_delta = 6; + + /* + The minimum HTLC value which will be accepted. + */ + uint64 htlc_minimum_msat = 7; + + /* + The base fee that must be used for incoming HTLC's to this particular + channel. This value will be tacked onto the required for a payment + independent of the size of the payment. + */ + uint32 base_fee = 8; + + /* + The fee rate that will be charged per millionth of a satoshi. + */ + uint32 fee_rate = 9; + + /* + The maximum HTLC value which will be accepted. + */ + uint64 htlc_maximum_msat = 11; + + /* + The set of data that was appended to this message, some of which we may + not actually know how to iterate or parse. By holding onto this data, we + ensure that we're able to properly validate the set of signatures that + cover these new fields, and ensure we're able to make upgrades to the + network in a forwards compatible manner. + */ + bytes extra_opaque_data = 12; +} + +message MacaroonId { + bytes nonce = 1; + bytes storageId = 2; + repeated Op ops = 3; +} + +message Op { + string entity = 1; + repeated string actions = 2; +} + +message CheckMacPermRequest { + bytes macaroon = 1; + repeated MacaroonPermission permissions = 2; + string fullMethod = 3; +} + +message CheckMacPermResponse { + bool valid = 1; +} + +message RPCMiddlewareRequest { + /* + The unique ID of the intercepted original gRPC request. Useful for mapping + request to response when implementing full duplex message interception. For + streaming requests, this will be the same ID for all incoming and outgoing + middleware intercept messages of the _same_ stream. + */ + uint64 request_id = 1; + + /* + The raw bytes of the complete macaroon as sent by the gRPC client in the + original request. This might be empty for a request that doesn't require + macaroons such as the wallet unlocker RPCs. + */ + bytes raw_macaroon = 2; + + /* + The parsed condition of the macaroon's custom caveat for convenient access. + This field only contains the value of the custom caveat that the handling + middleware has registered itself for. The condition _must_ be validated for + messages of intercept_type stream_auth and request! + */ + string custom_caveat_condition = 3; + + /* + There are three types of messages that will be sent to the middleware for + inspection and approval: Stream authentication, request and response + interception. The first two can only be accepted (=forward to main RPC + server) or denied (=return error to client). Intercepted responses can also + be replaced/overwritten. + */ + oneof intercept_type { + /* + Intercept stream authentication: each new streaming RPC call that is + initiated against lnd and contains the middleware's custom macaroon + caveat can be approved or denied based upon the macaroon in the stream + header. This message will only be sent for streaming RPCs, unary RPCs + must handle the macaroon authentication in the request interception to + avoid an additional message round trip between lnd and the middleware. + */ + StreamAuth stream_auth = 4; + + /* + Intercept incoming gRPC client request message: all incoming messages, + both on streaming and unary RPCs, are forwarded to the middleware for + inspection. For unary RPC messages the middleware is also expected to + validate the custom macaroon caveat of the request. + */ + RPCMessage request = 5; + + /* + Intercept outgoing gRPC response message: all outgoing messages, both on + streaming and unary RPCs, are forwarded to the middleware for inspection + and amendment. The response in this message is the original response as + it was generated by the main RPC server. It can either be accepted + (=forwarded to the client), replaced/overwritten with a new message of + the same type, or replaced by an error message. + */ + RPCMessage response = 6; + + /* + This is used to indicate to the client that the server has successfully + registered the interceptor. This is only used in the very first message + that the server sends to the client after the client sends the server + the middleware registration message. + */ + bool reg_complete = 8; + } + + /* + The unique message ID of this middleware intercept message. There can be + multiple middleware intercept messages per single gRPC request (one for the + incoming request and one for the outgoing response) or gRPC stream (one for + each incoming message and one for each outgoing response). This message ID + must be referenced when responding (accepting/rejecting/modifying) to an + intercept message. + */ + uint64 msg_id = 7; +} + +message StreamAuth { + /* + The full URI (in the format /./MethodName, for + example /lnrpc.Lightning/GetInfo) of the streaming RPC method that was just + established. + */ + string method_full_uri = 1; +} + +message RPCMessage { + /* + The full URI (in the format /./MethodName, for + example /lnrpc.Lightning/GetInfo) of the RPC method the message was sent + to/from. + */ + string method_full_uri = 1; + + /* + Indicates whether the message was sent over a streaming RPC method or not. + */ + bool stream_rpc = 2; + + /* + The full canonical gRPC name of the message type (in the format + .TypeName, for example lnrpc.GetInfoRequest). In case of an + error being returned from lnd, this simply contains the string "error". + */ + string type_name = 3; + + /* + The full content of the gRPC message, serialized in the binary protobuf + format. + */ + bytes serialized = 4; + + /* + Indicates that the response from lnd was an error, not a gRPC response. If + this is set to true then the type_name contains the string "error" and + serialized contains the error string. + */ + bool is_error = 5; +} + +message RPCMiddlewareResponse { + /* + The request message ID this response refers to. Must always be set when + giving feedback to an intercept but is ignored for the initial registration + message. + */ + uint64 ref_msg_id = 1; + + /* + The middleware can only send two types of messages to lnd: The initial + registration message that identifies the middleware and after that only + feedback messages to requests sent to the middleware. + */ + oneof middleware_message { + /* + The registration message identifies the middleware that's being + registered in lnd. The registration message must be sent immediately + after initiating the RegisterRpcMiddleware stream, otherwise lnd will + time out the attempt and terminate the request. NOTE: The middleware + will only receive interception messages for requests that contain a + macaroon with the custom caveat that the middleware declares it is + responsible for handling in the registration message! As a security + measure, _no_ middleware can intercept requests made with _unencumbered_ + macaroons! + */ + MiddlewareRegistration register = 2; + + /* + The middleware received an interception request and gives feedback to + it. The request_id indicates what message the feedback refers to. + */ + InterceptFeedback feedback = 3; + } +} + +message MiddlewareRegistration { + /* + The name of the middleware to register. The name should be as informative + as possible and is logged on registration. + */ + string middleware_name = 1; + + /* + The name of the custom macaroon caveat that this middleware is responsible + for. Only requests/responses that contain a macaroon with the registered + custom caveat are forwarded for interception to the middleware. The + exception being the read-only mode: All requests/responses are forwarded to + a middleware that requests read-only access but such a middleware won't be + allowed to _alter_ responses. As a security measure, _no_ middleware can + change responses to requests made with _unencumbered_ macaroons! + NOTE: Cannot be used at the same time as read_only_mode. + */ + string custom_macaroon_caveat_name = 2; + + /* + Instead of defining a custom macaroon caveat name a middleware can register + itself for read-only access only. In that mode all requests/responses are + forwarded to the middleware but the middleware isn't allowed to alter any of + the responses. + NOTE: Cannot be used at the same time as custom_macaroon_caveat_name. + */ + bool read_only_mode = 3; +} + +message InterceptFeedback { + /* + The error to return to the user. If this is non-empty, the incoming gRPC + stream/request is aborted and the error is returned to the gRPC client. If + this value is empty, it means the middleware accepts the stream/request/ + response and the processing of it can continue. + */ + string error = 1; + + /* + A boolean indicating that the gRPC message should be replaced/overwritten. + This boolean is needed because in protobuf an empty message is serialized as + a 0-length or nil byte slice and we wouldn't be able to distinguish between + an empty replacement message and the "don't replace anything" case. + */ + bool replace_response = 2; + + /* + If the replace_response field is set to true, this field must contain the + binary serialized gRPC message in the protobuf format. + */ + bytes replacement_serialized = 3; +} diff --git a/vendor/peersrpc/peers.proto b/vendor/peersrpc/peers.proto index 4cfdab5..41d6daa 100644 --- a/vendor/peersrpc/peers.proto +++ b/vendor/peersrpc/peers.proto @@ -1,94 +1,94 @@ -syntax = "proto3"; - -import "lightning.proto"; - -package peersrpc; - -option go_package = "github.com/lightningnetwork/lnd/lnrpc/peersrpc"; - -// Peers is a service that can be used to get information and interact -// with the other nodes of the network. -service Peers { - /* lncli: peers updatenodeannouncement - UpdateNodeAnnouncement allows the caller to update the node parameters - and broadcasts a new version of the node announcement to its peers. - */ - rpc UpdateNodeAnnouncement (NodeAnnouncementUpdateRequest) - returns (NodeAnnouncementUpdateResponse); -} - -// UpdateAction is used to determine the kind of action we are referring to. -enum UpdateAction { - // ADD indicates this is an "insertion" kind of action. - ADD = 0; - - // REMOVE indicates this is a "deletion" kind of action. - REMOVE = 1; -} - -enum FeatureSet { - /* - SET_INIT identifies features that should be sent in an Init message to - a remote peer. - */ - SET_INIT = 0; - - /* - SET_LEGACY_GLOBAL identifies features that should be set in the legacy - GlobalFeatures field of an Init message, which maintains backwards - compatibility with nodes that haven't implemented flat features. - */ - SET_LEGACY_GLOBAL = 1; - - /* - SET_NODE_ANN identifies features that should be advertised on node - announcements. - */ - SET_NODE_ANN = 2; - - /* - SET_INVOICE identifies features that should be advertised on invoices - generated by the daemon. - */ - SET_INVOICE = 3; - - /* - SET_INVOICE_AMP identifies the features that should be advertised on - AMP invoices generated by the daemon. - */ - SET_INVOICE_AMP = 4; -} - -message UpdateAddressAction { - // Determines the kind of action. - UpdateAction action = 1; - - // The address used to apply the update action. - string address = 2; -} - -message UpdateFeatureAction { - // Determines the kind of action. - UpdateAction action = 1; - - // The feature bit used to apply the update action. - lnrpc.FeatureBit feature_bit = 2; -} - -message NodeAnnouncementUpdateRequest { - // Set of changes for the features that the node supports. - repeated UpdateFeatureAction feature_updates = 1; - - // Color is the node's color in hex code format. - string color = 2; - - // Alias or nick name of the node. - string alias = 3; - - // Set of changes for the node's known addresses. - repeated UpdateAddressAction address_updates = 4; -} - -message NodeAnnouncementUpdateResponse { - repeated lnrpc.Op ops = 1; -} +syntax = "proto3"; + +import "lightning.proto"; + +package peersrpc; + +option go_package = "github.com/lightningnetwork/lnd/lnrpc/peersrpc"; + +// Peers is a service that can be used to get information and interact +// with the other nodes of the network. +service Peers { + /* lncli: peers updatenodeannouncement + UpdateNodeAnnouncement allows the caller to update the node parameters + and broadcasts a new version of the node announcement to its peers. + */ + rpc UpdateNodeAnnouncement (NodeAnnouncementUpdateRequest) + returns (NodeAnnouncementUpdateResponse); +} + +// UpdateAction is used to determine the kind of action we are referring to. +enum UpdateAction { + // ADD indicates this is an "insertion" kind of action. + ADD = 0; + + // REMOVE indicates this is a "deletion" kind of action. + REMOVE = 1; +} + +enum FeatureSet { + /* + SET_INIT identifies features that should be sent in an Init message to + a remote peer. + */ + SET_INIT = 0; + + /* + SET_LEGACY_GLOBAL identifies features that should be set in the legacy + GlobalFeatures field of an Init message, which maintains backwards + compatibility with nodes that haven't implemented flat features. + */ + SET_LEGACY_GLOBAL = 1; + + /* + SET_NODE_ANN identifies features that should be advertised on node + announcements. + */ + SET_NODE_ANN = 2; + + /* + SET_INVOICE identifies features that should be advertised on invoices + generated by the daemon. + */ + SET_INVOICE = 3; + + /* + SET_INVOICE_AMP identifies the features that should be advertised on + AMP invoices generated by the daemon. + */ + SET_INVOICE_AMP = 4; +} + +message UpdateAddressAction { + // Determines the kind of action. + UpdateAction action = 1; + + // The address used to apply the update action. + string address = 2; +} + +message UpdateFeatureAction { + // Determines the kind of action. + UpdateAction action = 1; + + // The feature bit used to apply the update action. + lnrpc.FeatureBit feature_bit = 2; +} + +message NodeAnnouncementUpdateRequest { + // Set of changes for the features that the node supports. + repeated UpdateFeatureAction feature_updates = 1; + + // Color is the node's color in hex code format. + string color = 2; + + // Alias or nick name of the node. + string alias = 3; + + // Set of changes for the node's known addresses. + repeated UpdateAddressAction address_updates = 4; +} + +message NodeAnnouncementUpdateResponse { + repeated lnrpc.Op ops = 1; +} diff --git a/vendor/routerrpc/router.proto b/vendor/routerrpc/router.proto index debc7ef..e424485 100644 --- a/vendor/routerrpc/router.proto +++ b/vendor/routerrpc/router.proto @@ -1,834 +1,834 @@ -syntax = "proto3"; - -import "lightning.proto"; - -package routerrpc; - -option go_package = "github.com/lightningnetwork/lnd/lnrpc/routerrpc"; - -// Router is a service that offers advanced interaction with the router -// subsystem of the daemon. -service Router { - /* - SendPaymentV2 attempts to route a payment described by the passed - PaymentRequest to the final destination. The call returns a stream of - payment updates. - */ - rpc SendPaymentV2 (SendPaymentRequest) returns (stream lnrpc.Payment); - - /* - TrackPaymentV2 returns an update stream for the payment identified by the - payment hash. - */ - rpc TrackPaymentV2 (TrackPaymentRequest) returns (stream lnrpc.Payment); - - /* - EstimateRouteFee allows callers to obtain a lower bound w.r.t how much it - may cost to send an HTLC to the target end destination. - */ - rpc EstimateRouteFee (RouteFeeRequest) returns (RouteFeeResponse); - - /* - Deprecated, use SendToRouteV2. SendToRoute attempts to make a payment via - the specified route. This method differs from SendPayment in that it - allows users to specify a full route manually. This can be used for - things like rebalancing, and atomic swaps. It differs from the newer - SendToRouteV2 in that it doesn't return the full HTLC information. - */ - rpc SendToRoute (SendToRouteRequest) returns (SendToRouteResponse) { - option deprecated = true; - } - - /* - SendToRouteV2 attempts to make a payment via the specified route. This - method differs from SendPayment in that it allows users to specify a full - route manually. This can be used for things like rebalancing, and atomic - swaps. - */ - rpc SendToRouteV2 (SendToRouteRequest) returns (lnrpc.HTLCAttempt); - - /* - ResetMissionControl clears all mission control state and starts with a clean - slate. - */ - rpc ResetMissionControl (ResetMissionControlRequest) - returns (ResetMissionControlResponse); - - /* - QueryMissionControl exposes the internal mission control state to callers. - It is a development feature. - */ - rpc QueryMissionControl (QueryMissionControlRequest) - returns (QueryMissionControlResponse); - - /* - 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. - */ - rpc XImportMissionControl (XImportMissionControlRequest) - returns (XImportMissionControlResponse); - - /* - GetMissionControlConfig returns mission control's current config. - */ - rpc GetMissionControlConfig (GetMissionControlConfigRequest) - returns (GetMissionControlConfigResponse); - - /* - SetMissionControlConfig will set mission control's config, if the config - provided is valid. - */ - rpc SetMissionControlConfig (SetMissionControlConfigRequest) - returns (SetMissionControlConfigResponse); - - /* - QueryProbability returns the current success probability estimate for a - given node pair and amount. - */ - rpc QueryProbability (QueryProbabilityRequest) - returns (QueryProbabilityResponse); - - /* - 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. - */ - rpc BuildRoute (BuildRouteRequest) returns (BuildRouteResponse); - - /* - SubscribeHtlcEvents creates a uni-directional stream from the server to - the client which delivers a stream of htlc events. - */ - rpc SubscribeHtlcEvents (SubscribeHtlcEventsRequest) - returns (stream HtlcEvent); - - /* - Deprecated, use SendPaymentV2. SendPayment attempts to route a payment - described by the passed PaymentRequest to the final destination. The call - returns a stream of payment status updates. - */ - rpc SendPayment (SendPaymentRequest) returns (stream PaymentStatus) { - option deprecated = true; - } - - /* - Deprecated, use TrackPaymentV2. TrackPayment returns an update stream for - the payment identified by the payment hash. - */ - rpc TrackPayment (TrackPaymentRequest) returns (stream PaymentStatus) { - option deprecated = true; - } - - /** - HtlcInterceptor dispatches a bi-directional streaming RPC in which - Forwarded HTLC requests are sent to the client and the client responds with - a boolean that tells LND if this htlc should be intercepted. - In case of interception, the htlc can be either settled, cancelled or - resumed later by using the ResolveHoldForward endpoint. - */ - rpc HtlcInterceptor (stream ForwardHtlcInterceptResponse) - returns (stream ForwardHtlcInterceptRequest); - - /* - 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 - "enable" or "auto". - */ - rpc UpdateChanStatus (UpdateChanStatusRequest) - returns (UpdateChanStatusResponse); -} - -message SendPaymentRequest { - // The identity pubkey of the payment recipient - bytes dest = 1; - - /* - Number of satoshis to send. - - The fields amt and amt_msat are mutually exclusive. - */ - int64 amt = 2; - - /* - Number of millisatoshis to send. - - The fields amt and amt_msat are mutually exclusive. - */ - int64 amt_msat = 12; - - // The hash to use within the payment's HTLC - bytes payment_hash = 3; - - /* - The CLTV delta from the current height that should be used to set the - timelock for the final hop. - */ - int32 final_cltv_delta = 4; - - // An optional payment addr to be included within the last hop of the route. - bytes payment_addr = 20; - - /* - A bare-bones invoice for a payment within the Lightning Network. With the - details of the invoice, the sender has all the data necessary to send a - payment to the recipient. The amount in the payment request may be zero. In - that case it is required to set the amt field as well. If no payment request - is specified, the following fields are required: dest, amt and payment_hash. - */ - string payment_request = 5; - - /* - An upper limit on the amount of time we should spend when attempting to - fulfill the payment. This is expressed in seconds. If we cannot make a - successful payment within this time frame, an error will be returned. - This field must be non-zero. - */ - int32 timeout_seconds = 6; - - /* - The maximum number of satoshis that will be paid as a fee of the payment. - If this field is left to the default value of 0, only zero-fee routes will - be considered. This usually means single hop routes connecting directly to - the destination. To send the payment without a fee limit, use max int here. - - The fields fee_limit_sat and fee_limit_msat are mutually exclusive. - */ - int64 fee_limit_sat = 7; - - /* - The maximum number of millisatoshis that will be paid as a fee of the - payment. If this field is left to the default value of 0, only zero-fee - routes will be considered. This usually means single hop routes connecting - directly to the destination. To send the payment without a fee limit, use - max int here. - - The fields fee_limit_sat and fee_limit_msat are mutually exclusive. - */ - int64 fee_limit_msat = 13; - - /* - Deprecated, use outgoing_chan_ids. The channel id of the channel that must - be taken to the first hop. If zero, any channel may be used (unless - outgoing_chan_ids are set). - */ - uint64 outgoing_chan_id = 8 [jstype = JS_STRING, deprecated = true]; - - /* - The channel ids of the channels are allowed for the first hop. If empty, - any channel may be used. - */ - repeated uint64 outgoing_chan_ids = 19; - - /* - The pubkey of the last hop of the route. If empty, any hop may be used. - */ - bytes last_hop_pubkey = 14; - - /* - An optional maximum total time lock for the route. This should not exceed - lnd's `--max-cltv-expiry` setting. If zero, then the value of - `--max-cltv-expiry` is enforced. - */ - int32 cltv_limit = 9; - - /* - Optional route hints to reach the destination through private channels. - */ - repeated lnrpc.RouteHint route_hints = 10; - - /* - An optional field that can be used to pass an arbitrary set of TLV records - to a peer which understands the new records. This can be used to pass - application specific data during the payment attempt. Record types are - required to be in the custom range >= 65536. When using REST, the values - must be encoded as base64. - */ - map dest_custom_records = 11; - - // If set, circular payments to self are permitted. - bool allow_self_payment = 15; - - /* - Features assumed to be supported by the final node. All transitive feature - dependencies must also be set properly. For a given feature bit pair, either - optional or remote may be set, but not both. If this field is nil or empty, - the router will try to load destination features from the graph as a - fallback. - */ - repeated lnrpc.FeatureBit dest_features = 16; - - /* - The maximum number of partial payments that may be use to complete the full - amount. - */ - uint32 max_parts = 17; - - /* - If set, only the final payment update is streamed back. Intermediate updates - that show which htlcs are still in flight are suppressed. - */ - bool no_inflight_updates = 18; - - /* - The largest payment split that should be attempted when making a payment if - splitting is necessary. Setting this value will effectively cause lnd to - split more aggressively, vs only when it thinks it needs to. Note that this - value is in milli-satoshis. - */ - uint64 max_shard_size_msat = 21; - - /* - If set, an AMP-payment will be attempted. - */ - bool amp = 22; - - /* - The time preference for this payment. Set to -1 to optimize for fees - only, to 1 to optimize for reliability only or a value inbetween for a mix. - */ - double time_pref = 23; -} - -message TrackPaymentRequest { - // The hash of the payment to look up. - bytes payment_hash = 1; - - /* - If set, only the final payment update is streamed back. Intermediate updates - that show which htlcs are still in flight are suppressed. - */ - bool no_inflight_updates = 2; -} - -message RouteFeeRequest { - /* - The destination once wishes to obtain a routing fee quote to. - */ - bytes dest = 1; - - /* - The amount one wishes to send to the target destination. - */ - int64 amt_sat = 2; -} - -message RouteFeeResponse { - /* - A lower bound of the estimated fee to the target destination within the - network, expressed in milli-satoshis. - */ - int64 routing_fee_msat = 1; - - /* - An estimate of the worst case time delay that can occur. Note that callers - will still need to factor in the final CLTV delta of the last hop into this - value. - */ - int64 time_lock_delay = 2; -} - -message SendToRouteRequest { - // The payment hash to use for the HTLC. - bytes payment_hash = 1; - - // Route that should be used to attempt to complete the payment. - lnrpc.Route route = 2; - - /* - Whether the payment should be marked as failed when a temporary error is - returned from the given route. Set it to true so the payment won't be - failed unless a terminal error is occurred, such as payment timeout, no - routes, incorrect payment details, or insufficient funds. - */ - bool skip_temp_err = 3; -} - -message SendToRouteResponse { - // The preimage obtained by making the payment. - bytes preimage = 1; - - // The failure message in case the payment failed. - lnrpc.Failure failure = 2; -} - -message ResetMissionControlRequest { -} - -message ResetMissionControlResponse { -} - -message QueryMissionControlRequest { -} - -// QueryMissionControlResponse contains mission control state. -message QueryMissionControlResponse { - reserved 1; - - // Node pair-level mission control state. - repeated PairHistory pairs = 2; -} - -message XImportMissionControlRequest { - // Node pair-level mission control state to be imported. - repeated PairHistory pairs = 1; - - // Whether to force override MC pair history. Note that even with force - // override the failure pair is imported before the success pair and both - // still clamp existing failure/success amounts. - bool force = 2; -} - -message XImportMissionControlResponse { -} - -// PairHistory contains the mission control state for a particular node pair. -message PairHistory { - // The source node pubkey of the pair. - bytes node_from = 1; - - // The destination node pubkey of the pair. - bytes node_to = 2; - - reserved 3, 4, 5, 6; - - PairData history = 7; -} - -message PairData { - // Time of last failure. - int64 fail_time = 1; - - /* - Lowest amount that failed to forward rounded to whole sats. This may be - set to zero if the failure is independent of amount. - */ - int64 fail_amt_sat = 2; - - /* - Lowest amount that failed to forward in millisats. This may be - set to zero if the failure is independent of amount. - */ - int64 fail_amt_msat = 4; - - reserved 3; - - // Time of last success. - int64 success_time = 5; - - // Highest amount that we could successfully forward rounded to whole sats. - int64 success_amt_sat = 6; - - // Highest amount that we could successfully forward in millisats. - int64 success_amt_msat = 7; -} - -message GetMissionControlConfigRequest { -} - -message GetMissionControlConfigResponse { - /* - Mission control's currently active config. - */ - MissionControlConfig config = 1; -} - -message SetMissionControlConfigRequest { - /* - The config to set for mission control. Note that all values *must* be set, - because the full config will be applied. - */ - MissionControlConfig config = 1; -} - -message SetMissionControlConfigResponse { -} - -message MissionControlConfig { - /* - The amount of time mission control will take to restore a penalized node - or channel back to 50% success probability, expressed in seconds. Setting - this value to a higher value will penalize failures for longer, making - mission control less likely to route through nodes and channels that we - have previously recorded failures for. - */ - uint64 half_life_seconds = 1; - - /* - The probability of success mission control should assign to hop in a route - where it has no other information available. Higher values will make mission - control more willing to try hops that we have no information about, lower - values will discourage trying these hops. - */ - float hop_probability = 2; - - /* - The importance that mission control should place on historical results, - expressed as a value in [0;1]. Setting this value to 1 will ignore all - historical payments and just use the hop probability to assess the - probability of success for each hop. A zero value ignores hop probability - completely and relies entirely on historical results, unless none are - available. - */ - float weight = 3; - - /* - The maximum number of payment results that mission control will store. - */ - uint32 maximum_payment_results = 4; - - /* - The minimum time that must have passed since the previously recorded failure - before we raise the failure amount. - */ - uint64 minimum_failure_relax_interval = 5; -} - -message QueryProbabilityRequest { - // The source node pubkey of the pair. - bytes from_node = 1; - - // The destination node pubkey of the pair. - bytes to_node = 2; - - // The amount for which to calculate a probability. - int64 amt_msat = 3; -} - -message QueryProbabilityResponse { - // The success probability for the requested pair. - double probability = 1; - - // The historical data for the requested pair. - PairData history = 2; -} - -message BuildRouteRequest { - /* - The amount to send expressed in msat. If set to zero, the minimum routable - amount is used. - */ - int64 amt_msat = 1; - - /* - CLTV delta from the current height that should be used for the timelock - of the final hop - */ - int32 final_cltv_delta = 2; - - /* - The channel id of the channel that must be taken to the first hop. If zero, - any channel may be used. - */ - uint64 outgoing_chan_id = 3 [jstype = JS_STRING]; - - /* - A list of hops that defines the route. This does not include the source hop - pubkey. - */ - repeated bytes hop_pubkeys = 4; - - // An optional payment addr to be included within the last hop of the route. - bytes payment_addr = 5; -} - -message BuildRouteResponse { - /* - Fully specified route that can be used to execute the payment. - */ - lnrpc.Route route = 1; -} - -message SubscribeHtlcEventsRequest { -} - -/* -HtlcEvent contains the htlc event that was processed. These are served on a -best-effort basis; events are not persisted, delivery is not guaranteed -(in the event of a crash in the switch, forward events may be lost) and -some events may be replayed upon restart. Events consumed from this package -should be de-duplicated by the htlc's unique combination of incoming and -outgoing channel id and htlc id. [EXPERIMENTAL] -*/ -message HtlcEvent { - /* - The short channel id that the incoming htlc arrived at our node on. This - value is zero for sends. - */ - uint64 incoming_channel_id = 1; - - /* - The short channel id that the outgoing htlc left our node on. This value - is zero for receives. - */ - uint64 outgoing_channel_id = 2; - - /* - Incoming id is the index of the incoming htlc in the incoming channel. - This value is zero for sends. - */ - uint64 incoming_htlc_id = 3; - - /* - Outgoing id is the index of the outgoing htlc in the outgoing channel. - This value is zero for receives. - */ - uint64 outgoing_htlc_id = 4; - - /* - The time in unix nanoseconds that the event occurred. - */ - uint64 timestamp_ns = 5; - - enum EventType { - UNKNOWN = 0; - SEND = 1; - RECEIVE = 2; - FORWARD = 3; - } - - /* - The event type indicates whether the htlc was part of a send, receive or - forward. - */ - EventType event_type = 6; - - oneof event { - ForwardEvent forward_event = 7; - ForwardFailEvent forward_fail_event = 8; - SettleEvent settle_event = 9; - LinkFailEvent link_fail_event = 10; - } -} - -message HtlcInfo { - // The timelock on the incoming htlc. - uint32 incoming_timelock = 1; - - // The timelock on the outgoing htlc. - uint32 outgoing_timelock = 2; - - // The amount of the incoming htlc. - uint64 incoming_amt_msat = 3; - - // The amount of the outgoing htlc. - uint64 outgoing_amt_msat = 4; -} - -message ForwardEvent { - // Info contains details about the htlc that was forwarded. - HtlcInfo info = 1; -} - -message ForwardFailEvent { -} - -message SettleEvent { - // The revealed preimage. - bytes preimage = 1; -} - -message LinkFailEvent { - // Info contains details about the htlc that we failed. - HtlcInfo info = 1; - - // FailureCode is the BOLT error code for the failure. - lnrpc.Failure.FailureCode wire_failure = 2; - - /* - FailureDetail provides additional information about the reason for the - failure. This detail enriches the information provided by the wire message - and may be 'no detail' if the wire message requires no additional metadata. - */ - FailureDetail failure_detail = 3; - - // A string representation of the link failure. - string failure_string = 4; -} - -enum FailureDetail { - UNKNOWN = 0; - NO_DETAIL = 1; - ONION_DECODE = 2; - LINK_NOT_ELIGIBLE = 3; - ON_CHAIN_TIMEOUT = 4; - HTLC_EXCEEDS_MAX = 5; - INSUFFICIENT_BALANCE = 6; - INCOMPLETE_FORWARD = 7; - HTLC_ADD_FAILED = 8; - FORWARDS_DISABLED = 9; - INVOICE_CANCELED = 10; - INVOICE_UNDERPAID = 11; - INVOICE_EXPIRY_TOO_SOON = 12; - INVOICE_NOT_OPEN = 13; - MPP_INVOICE_TIMEOUT = 14; - ADDRESS_MISMATCH = 15; - SET_TOTAL_MISMATCH = 16; - SET_TOTAL_TOO_LOW = 17; - SET_OVERPAID = 18; - UNKNOWN_INVOICE = 19; - INVALID_KEYSEND = 20; - MPP_IN_PROGRESS = 21; - CIRCULAR_ROUTE = 22; -} - -enum PaymentState { - /* - Payment is still in flight. - */ - IN_FLIGHT = 0; - - /* - Payment completed successfully. - */ - SUCCEEDED = 1; - - /* - There are more routes to try, but the payment timeout was exceeded. - */ - FAILED_TIMEOUT = 2; - - /* - All possible routes were tried and failed permanently. Or were no - routes to the destination at all. - */ - FAILED_NO_ROUTE = 3; - - /* - A non-recoverable error has occurred. - */ - FAILED_ERROR = 4; - - /* - Payment details incorrect (unknown hash, invalid amt or - invalid final cltv delta) - */ - FAILED_INCORRECT_PAYMENT_DETAILS = 5; - - /* - Insufficient local balance. - */ - FAILED_INSUFFICIENT_BALANCE = 6; -} - -message PaymentStatus { - // Current state the payment is in. - PaymentState state = 1; - - /* - The pre-image of the payment when state is SUCCEEDED. - */ - bytes preimage = 2; - - reserved 3; - - /* - The HTLCs made in attempt to settle the payment [EXPERIMENTAL]. - */ - repeated lnrpc.HTLCAttempt htlcs = 4; -} - -message CircuitKey { - /// The id of the channel that the is part of this circuit. - uint64 chan_id = 1; - - /// The index of the incoming htlc in the incoming channel. - uint64 htlc_id = 2; -} - -message ForwardHtlcInterceptRequest { - /* - The key of this forwarded htlc. It defines the incoming channel id and - the index in this channel. - */ - CircuitKey incoming_circuit_key = 1; - - // The incoming htlc amount. - uint64 incoming_amount_msat = 5; - - // The incoming htlc expiry. - uint32 incoming_expiry = 6; - - /* - The htlc payment hash. This value is not guaranteed to be unique per - request. - */ - bytes payment_hash = 2; - - // The requested outgoing channel id for this forwarded htlc. Because of - // non-strict forwarding, this isn't necessarily the channel over which the - // packet will be forwarded eventually. A different channel to the same peer - // may be selected as well. - uint64 outgoing_requested_chan_id = 7; - - // The outgoing htlc amount. - uint64 outgoing_amount_msat = 3; - - // The outgoing htlc expiry. - uint32 outgoing_expiry = 4; - - // Any custom records that were present in the payload. - map custom_records = 8; - - // The onion blob for the next hop - bytes onion_blob = 9; -} - -/** -ForwardHtlcInterceptResponse enables the caller to resolve a previously hold -forward. The caller can choose either to: -- `Resume`: Execute the default behavior (usually forward). -- `Reject`: Fail the htlc backwards. -- `Settle`: Settle this htlc with a given preimage. -*/ -message ForwardHtlcInterceptResponse { - /** - The key of this forwarded htlc. It defines the incoming channel id and - the index in this channel. - */ - CircuitKey incoming_circuit_key = 1; - - // The resolve action for this intercepted htlc. - ResolveHoldForwardAction action = 2; - - // The preimage in case the resolve action is Settle. - bytes preimage = 3; - - // Encrypted failure message in case the resolve action is Fail. - // - // If failure_message is specified, the failure_code field must be set - // to zero. - bytes failure_message = 4; - - // Return the specified failure code in case the resolve action is Fail. The - // message data fields are populated automatically. - // - // If a non-zero failure_code is specified, failure_message must not be set. - // - // For backwards-compatibility reasons, TEMPORARY_CHANNEL_FAILURE is the - // default value for this field. - lnrpc.Failure.FailureCode failure_code = 5; -} - -enum ResolveHoldForwardAction { - SETTLE = 0; - FAIL = 1; - RESUME = 2; -} - -message UpdateChanStatusRequest { - lnrpc.ChannelPoint chan_point = 1; - - ChanStatusAction action = 2; -} - -enum ChanStatusAction { - ENABLE = 0; - DISABLE = 1; - AUTO = 2; -} - -message UpdateChanStatusResponse { +syntax = "proto3"; + +import "lightning.proto"; + +package routerrpc; + +option go_package = "github.com/lightningnetwork/lnd/lnrpc/routerrpc"; + +// Router is a service that offers advanced interaction with the router +// subsystem of the daemon. +service Router { + /* + SendPaymentV2 attempts to route a payment described by the passed + PaymentRequest to the final destination. The call returns a stream of + payment updates. + */ + rpc SendPaymentV2 (SendPaymentRequest) returns (stream lnrpc.Payment); + + /* + TrackPaymentV2 returns an update stream for the payment identified by the + payment hash. + */ + rpc TrackPaymentV2 (TrackPaymentRequest) returns (stream lnrpc.Payment); + + /* + EstimateRouteFee allows callers to obtain a lower bound w.r.t how much it + may cost to send an HTLC to the target end destination. + */ + rpc EstimateRouteFee (RouteFeeRequest) returns (RouteFeeResponse); + + /* + Deprecated, use SendToRouteV2. SendToRoute attempts to make a payment via + the specified route. This method differs from SendPayment in that it + allows users to specify a full route manually. This can be used for + things like rebalancing, and atomic swaps. It differs from the newer + SendToRouteV2 in that it doesn't return the full HTLC information. + */ + rpc SendToRoute (SendToRouteRequest) returns (SendToRouteResponse) { + option deprecated = true; + } + + /* + SendToRouteV2 attempts to make a payment via the specified route. This + method differs from SendPayment in that it allows users to specify a full + route manually. This can be used for things like rebalancing, and atomic + swaps. + */ + rpc SendToRouteV2 (SendToRouteRequest) returns (lnrpc.HTLCAttempt); + + /* + ResetMissionControl clears all mission control state and starts with a clean + slate. + */ + rpc ResetMissionControl (ResetMissionControlRequest) + returns (ResetMissionControlResponse); + + /* + QueryMissionControl exposes the internal mission control state to callers. + It is a development feature. + */ + rpc QueryMissionControl (QueryMissionControlRequest) + returns (QueryMissionControlResponse); + + /* + 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. + */ + rpc XImportMissionControl (XImportMissionControlRequest) + returns (XImportMissionControlResponse); + + /* + GetMissionControlConfig returns mission control's current config. + */ + rpc GetMissionControlConfig (GetMissionControlConfigRequest) + returns (GetMissionControlConfigResponse); + + /* + SetMissionControlConfig will set mission control's config, if the config + provided is valid. + */ + rpc SetMissionControlConfig (SetMissionControlConfigRequest) + returns (SetMissionControlConfigResponse); + + /* + QueryProbability returns the current success probability estimate for a + given node pair and amount. + */ + rpc QueryProbability (QueryProbabilityRequest) + returns (QueryProbabilityResponse); + + /* + 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. + */ + rpc BuildRoute (BuildRouteRequest) returns (BuildRouteResponse); + + /* + SubscribeHtlcEvents creates a uni-directional stream from the server to + the client which delivers a stream of htlc events. + */ + rpc SubscribeHtlcEvents (SubscribeHtlcEventsRequest) + returns (stream HtlcEvent); + + /* + Deprecated, use SendPaymentV2. SendPayment attempts to route a payment + described by the passed PaymentRequest to the final destination. The call + returns a stream of payment status updates. + */ + rpc SendPayment (SendPaymentRequest) returns (stream PaymentStatus) { + option deprecated = true; + } + + /* + Deprecated, use TrackPaymentV2. TrackPayment returns an update stream for + the payment identified by the payment hash. + */ + rpc TrackPayment (TrackPaymentRequest) returns (stream PaymentStatus) { + option deprecated = true; + } + + /** + HtlcInterceptor dispatches a bi-directional streaming RPC in which + Forwarded HTLC requests are sent to the client and the client responds with + a boolean that tells LND if this htlc should be intercepted. + In case of interception, the htlc can be either settled, cancelled or + resumed later by using the ResolveHoldForward endpoint. + */ + rpc HtlcInterceptor (stream ForwardHtlcInterceptResponse) + returns (stream ForwardHtlcInterceptRequest); + + /* + 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 + "enable" or "auto". + */ + rpc UpdateChanStatus (UpdateChanStatusRequest) + returns (UpdateChanStatusResponse); +} + +message SendPaymentRequest { + // The identity pubkey of the payment recipient + bytes dest = 1; + + /* + Number of satoshis to send. + + The fields amt and amt_msat are mutually exclusive. + */ + int64 amt = 2; + + /* + Number of millisatoshis to send. + + The fields amt and amt_msat are mutually exclusive. + */ + int64 amt_msat = 12; + + // The hash to use within the payment's HTLC + bytes payment_hash = 3; + + /* + The CLTV delta from the current height that should be used to set the + timelock for the final hop. + */ + int32 final_cltv_delta = 4; + + // An optional payment addr to be included within the last hop of the route. + bytes payment_addr = 20; + + /* + A bare-bones invoice for a payment within the Lightning Network. With the + details of the invoice, the sender has all the data necessary to send a + payment to the recipient. The amount in the payment request may be zero. In + that case it is required to set the amt field as well. If no payment request + is specified, the following fields are required: dest, amt and payment_hash. + */ + string payment_request = 5; + + /* + An upper limit on the amount of time we should spend when attempting to + fulfill the payment. This is expressed in seconds. If we cannot make a + successful payment within this time frame, an error will be returned. + This field must be non-zero. + */ + int32 timeout_seconds = 6; + + /* + The maximum number of satoshis that will be paid as a fee of the payment. + If this field is left to the default value of 0, only zero-fee routes will + be considered. This usually means single hop routes connecting directly to + the destination. To send the payment without a fee limit, use max int here. + + The fields fee_limit_sat and fee_limit_msat are mutually exclusive. + */ + int64 fee_limit_sat = 7; + + /* + The maximum number of millisatoshis that will be paid as a fee of the + payment. If this field is left to the default value of 0, only zero-fee + routes will be considered. This usually means single hop routes connecting + directly to the destination. To send the payment without a fee limit, use + max int here. + + The fields fee_limit_sat and fee_limit_msat are mutually exclusive. + */ + int64 fee_limit_msat = 13; + + /* + Deprecated, use outgoing_chan_ids. The channel id of the channel that must + be taken to the first hop. If zero, any channel may be used (unless + outgoing_chan_ids are set). + */ + uint64 outgoing_chan_id = 8 [jstype = JS_STRING, deprecated = true]; + + /* + The channel ids of the channels are allowed for the first hop. If empty, + any channel may be used. + */ + repeated uint64 outgoing_chan_ids = 19; + + /* + The pubkey of the last hop of the route. If empty, any hop may be used. + */ + bytes last_hop_pubkey = 14; + + /* + An optional maximum total time lock for the route. This should not exceed + lnd's `--max-cltv-expiry` setting. If zero, then the value of + `--max-cltv-expiry` is enforced. + */ + int32 cltv_limit = 9; + + /* + Optional route hints to reach the destination through private channels. + */ + repeated lnrpc.RouteHint route_hints = 10; + + /* + An optional field that can be used to pass an arbitrary set of TLV records + to a peer which understands the new records. This can be used to pass + application specific data during the payment attempt. Record types are + required to be in the custom range >= 65536. When using REST, the values + must be encoded as base64. + */ + map dest_custom_records = 11; + + // If set, circular payments to self are permitted. + bool allow_self_payment = 15; + + /* + Features assumed to be supported by the final node. All transitive feature + dependencies must also be set properly. For a given feature bit pair, either + optional or remote may be set, but not both. If this field is nil or empty, + the router will try to load destination features from the graph as a + fallback. + */ + repeated lnrpc.FeatureBit dest_features = 16; + + /* + The maximum number of partial payments that may be use to complete the full + amount. + */ + uint32 max_parts = 17; + + /* + If set, only the final payment update is streamed back. Intermediate updates + that show which htlcs are still in flight are suppressed. + */ + bool no_inflight_updates = 18; + + /* + The largest payment split that should be attempted when making a payment if + splitting is necessary. Setting this value will effectively cause lnd to + split more aggressively, vs only when it thinks it needs to. Note that this + value is in milli-satoshis. + */ + uint64 max_shard_size_msat = 21; + + /* + If set, an AMP-payment will be attempted. + */ + bool amp = 22; + + /* + The time preference for this payment. Set to -1 to optimize for fees + only, to 1 to optimize for reliability only or a value inbetween for a mix. + */ + double time_pref = 23; +} + +message TrackPaymentRequest { + // The hash of the payment to look up. + bytes payment_hash = 1; + + /* + If set, only the final payment update is streamed back. Intermediate updates + that show which htlcs are still in flight are suppressed. + */ + bool no_inflight_updates = 2; +} + +message RouteFeeRequest { + /* + The destination once wishes to obtain a routing fee quote to. + */ + bytes dest = 1; + + /* + The amount one wishes to send to the target destination. + */ + int64 amt_sat = 2; +} + +message RouteFeeResponse { + /* + A lower bound of the estimated fee to the target destination within the + network, expressed in milli-satoshis. + */ + int64 routing_fee_msat = 1; + + /* + An estimate of the worst case time delay that can occur. Note that callers + will still need to factor in the final CLTV delta of the last hop into this + value. + */ + int64 time_lock_delay = 2; +} + +message SendToRouteRequest { + // The payment hash to use for the HTLC. + bytes payment_hash = 1; + + // Route that should be used to attempt to complete the payment. + lnrpc.Route route = 2; + + /* + Whether the payment should be marked as failed when a temporary error is + returned from the given route. Set it to true so the payment won't be + failed unless a terminal error is occurred, such as payment timeout, no + routes, incorrect payment details, or insufficient funds. + */ + bool skip_temp_err = 3; +} + +message SendToRouteResponse { + // The preimage obtained by making the payment. + bytes preimage = 1; + + // The failure message in case the payment failed. + lnrpc.Failure failure = 2; +} + +message ResetMissionControlRequest { +} + +message ResetMissionControlResponse { +} + +message QueryMissionControlRequest { +} + +// QueryMissionControlResponse contains mission control state. +message QueryMissionControlResponse { + reserved 1; + + // Node pair-level mission control state. + repeated PairHistory pairs = 2; +} + +message XImportMissionControlRequest { + // Node pair-level mission control state to be imported. + repeated PairHistory pairs = 1; + + // Whether to force override MC pair history. Note that even with force + // override the failure pair is imported before the success pair and both + // still clamp existing failure/success amounts. + bool force = 2; +} + +message XImportMissionControlResponse { +} + +// PairHistory contains the mission control state for a particular node pair. +message PairHistory { + // The source node pubkey of the pair. + bytes node_from = 1; + + // The destination node pubkey of the pair. + bytes node_to = 2; + + reserved 3, 4, 5, 6; + + PairData history = 7; +} + +message PairData { + // Time of last failure. + int64 fail_time = 1; + + /* + Lowest amount that failed to forward rounded to whole sats. This may be + set to zero if the failure is independent of amount. + */ + int64 fail_amt_sat = 2; + + /* + Lowest amount that failed to forward in millisats. This may be + set to zero if the failure is independent of amount. + */ + int64 fail_amt_msat = 4; + + reserved 3; + + // Time of last success. + int64 success_time = 5; + + // Highest amount that we could successfully forward rounded to whole sats. + int64 success_amt_sat = 6; + + // Highest amount that we could successfully forward in millisats. + int64 success_amt_msat = 7; +} + +message GetMissionControlConfigRequest { +} + +message GetMissionControlConfigResponse { + /* + Mission control's currently active config. + */ + MissionControlConfig config = 1; +} + +message SetMissionControlConfigRequest { + /* + The config to set for mission control. Note that all values *must* be set, + because the full config will be applied. + */ + MissionControlConfig config = 1; +} + +message SetMissionControlConfigResponse { +} + +message MissionControlConfig { + /* + The amount of time mission control will take to restore a penalized node + or channel back to 50% success probability, expressed in seconds. Setting + this value to a higher value will penalize failures for longer, making + mission control less likely to route through nodes and channels that we + have previously recorded failures for. + */ + uint64 half_life_seconds = 1; + + /* + The probability of success mission control should assign to hop in a route + where it has no other information available. Higher values will make mission + control more willing to try hops that we have no information about, lower + values will discourage trying these hops. + */ + float hop_probability = 2; + + /* + The importance that mission control should place on historical results, + expressed as a value in [0;1]. Setting this value to 1 will ignore all + historical payments and just use the hop probability to assess the + probability of success for each hop. A zero value ignores hop probability + completely and relies entirely on historical results, unless none are + available. + */ + float weight = 3; + + /* + The maximum number of payment results that mission control will store. + */ + uint32 maximum_payment_results = 4; + + /* + The minimum time that must have passed since the previously recorded failure + before we raise the failure amount. + */ + uint64 minimum_failure_relax_interval = 5; +} + +message QueryProbabilityRequest { + // The source node pubkey of the pair. + bytes from_node = 1; + + // The destination node pubkey of the pair. + bytes to_node = 2; + + // The amount for which to calculate a probability. + int64 amt_msat = 3; +} + +message QueryProbabilityResponse { + // The success probability for the requested pair. + double probability = 1; + + // The historical data for the requested pair. + PairData history = 2; +} + +message BuildRouteRequest { + /* + The amount to send expressed in msat. If set to zero, the minimum routable + amount is used. + */ + int64 amt_msat = 1; + + /* + CLTV delta from the current height that should be used for the timelock + of the final hop + */ + int32 final_cltv_delta = 2; + + /* + The channel id of the channel that must be taken to the first hop. If zero, + any channel may be used. + */ + uint64 outgoing_chan_id = 3 [jstype = JS_STRING]; + + /* + A list of hops that defines the route. This does not include the source hop + pubkey. + */ + repeated bytes hop_pubkeys = 4; + + // An optional payment addr to be included within the last hop of the route. + bytes payment_addr = 5; +} + +message BuildRouteResponse { + /* + Fully specified route that can be used to execute the payment. + */ + lnrpc.Route route = 1; +} + +message SubscribeHtlcEventsRequest { +} + +/* +HtlcEvent contains the htlc event that was processed. These are served on a +best-effort basis; events are not persisted, delivery is not guaranteed +(in the event of a crash in the switch, forward events may be lost) and +some events may be replayed upon restart. Events consumed from this package +should be de-duplicated by the htlc's unique combination of incoming and +outgoing channel id and htlc id. [EXPERIMENTAL] +*/ +message HtlcEvent { + /* + The short channel id that the incoming htlc arrived at our node on. This + value is zero for sends. + */ + uint64 incoming_channel_id = 1; + + /* + The short channel id that the outgoing htlc left our node on. This value + is zero for receives. + */ + uint64 outgoing_channel_id = 2; + + /* + Incoming id is the index of the incoming htlc in the incoming channel. + This value is zero for sends. + */ + uint64 incoming_htlc_id = 3; + + /* + Outgoing id is the index of the outgoing htlc in the outgoing channel. + This value is zero for receives. + */ + uint64 outgoing_htlc_id = 4; + + /* + The time in unix nanoseconds that the event occurred. + */ + uint64 timestamp_ns = 5; + + enum EventType { + UNKNOWN = 0; + SEND = 1; + RECEIVE = 2; + FORWARD = 3; + } + + /* + The event type indicates whether the htlc was part of a send, receive or + forward. + */ + EventType event_type = 6; + + oneof event { + ForwardEvent forward_event = 7; + ForwardFailEvent forward_fail_event = 8; + SettleEvent settle_event = 9; + LinkFailEvent link_fail_event = 10; + } +} + +message HtlcInfo { + // The timelock on the incoming htlc. + uint32 incoming_timelock = 1; + + // The timelock on the outgoing htlc. + uint32 outgoing_timelock = 2; + + // The amount of the incoming htlc. + uint64 incoming_amt_msat = 3; + + // The amount of the outgoing htlc. + uint64 outgoing_amt_msat = 4; +} + +message ForwardEvent { + // Info contains details about the htlc that was forwarded. + HtlcInfo info = 1; +} + +message ForwardFailEvent { +} + +message SettleEvent { + // The revealed preimage. + bytes preimage = 1; +} + +message LinkFailEvent { + // Info contains details about the htlc that we failed. + HtlcInfo info = 1; + + // FailureCode is the BOLT error code for the failure. + lnrpc.Failure.FailureCode wire_failure = 2; + + /* + FailureDetail provides additional information about the reason for the + failure. This detail enriches the information provided by the wire message + and may be 'no detail' if the wire message requires no additional metadata. + */ + FailureDetail failure_detail = 3; + + // A string representation of the link failure. + string failure_string = 4; +} + +enum FailureDetail { + UNKNOWN = 0; + NO_DETAIL = 1; + ONION_DECODE = 2; + LINK_NOT_ELIGIBLE = 3; + ON_CHAIN_TIMEOUT = 4; + HTLC_EXCEEDS_MAX = 5; + INSUFFICIENT_BALANCE = 6; + INCOMPLETE_FORWARD = 7; + HTLC_ADD_FAILED = 8; + FORWARDS_DISABLED = 9; + INVOICE_CANCELED = 10; + INVOICE_UNDERPAID = 11; + INVOICE_EXPIRY_TOO_SOON = 12; + INVOICE_NOT_OPEN = 13; + MPP_INVOICE_TIMEOUT = 14; + ADDRESS_MISMATCH = 15; + SET_TOTAL_MISMATCH = 16; + SET_TOTAL_TOO_LOW = 17; + SET_OVERPAID = 18; + UNKNOWN_INVOICE = 19; + INVALID_KEYSEND = 20; + MPP_IN_PROGRESS = 21; + CIRCULAR_ROUTE = 22; +} + +enum PaymentState { + /* + Payment is still in flight. + */ + IN_FLIGHT = 0; + + /* + Payment completed successfully. + */ + SUCCEEDED = 1; + + /* + There are more routes to try, but the payment timeout was exceeded. + */ + FAILED_TIMEOUT = 2; + + /* + All possible routes were tried and failed permanently. Or were no + routes to the destination at all. + */ + FAILED_NO_ROUTE = 3; + + /* + A non-recoverable error has occurred. + */ + FAILED_ERROR = 4; + + /* + Payment details incorrect (unknown hash, invalid amt or + invalid final cltv delta) + */ + FAILED_INCORRECT_PAYMENT_DETAILS = 5; + + /* + Insufficient local balance. + */ + FAILED_INSUFFICIENT_BALANCE = 6; +} + +message PaymentStatus { + // Current state the payment is in. + PaymentState state = 1; + + /* + The pre-image of the payment when state is SUCCEEDED. + */ + bytes preimage = 2; + + reserved 3; + + /* + The HTLCs made in attempt to settle the payment [EXPERIMENTAL]. + */ + repeated lnrpc.HTLCAttempt htlcs = 4; +} + +message CircuitKey { + /// The id of the channel that the is part of this circuit. + uint64 chan_id = 1; + + /// The index of the incoming htlc in the incoming channel. + uint64 htlc_id = 2; +} + +message ForwardHtlcInterceptRequest { + /* + The key of this forwarded htlc. It defines the incoming channel id and + the index in this channel. + */ + CircuitKey incoming_circuit_key = 1; + + // The incoming htlc amount. + uint64 incoming_amount_msat = 5; + + // The incoming htlc expiry. + uint32 incoming_expiry = 6; + + /* + The htlc payment hash. This value is not guaranteed to be unique per + request. + */ + bytes payment_hash = 2; + + // The requested outgoing channel id for this forwarded htlc. Because of + // non-strict forwarding, this isn't necessarily the channel over which the + // packet will be forwarded eventually. A different channel to the same peer + // may be selected as well. + uint64 outgoing_requested_chan_id = 7; + + // The outgoing htlc amount. + uint64 outgoing_amount_msat = 3; + + // The outgoing htlc expiry. + uint32 outgoing_expiry = 4; + + // Any custom records that were present in the payload. + map custom_records = 8; + + // The onion blob for the next hop + bytes onion_blob = 9; +} + +/** +ForwardHtlcInterceptResponse enables the caller to resolve a previously hold +forward. The caller can choose either to: +- `Resume`: Execute the default behavior (usually forward). +- `Reject`: Fail the htlc backwards. +- `Settle`: Settle this htlc with a given preimage. +*/ +message ForwardHtlcInterceptResponse { + /** + The key of this forwarded htlc. It defines the incoming channel id and + the index in this channel. + */ + CircuitKey incoming_circuit_key = 1; + + // The resolve action for this intercepted htlc. + ResolveHoldForwardAction action = 2; + + // The preimage in case the resolve action is Settle. + bytes preimage = 3; + + // Encrypted failure message in case the resolve action is Fail. + // + // If failure_message is specified, the failure_code field must be set + // to zero. + bytes failure_message = 4; + + // Return the specified failure code in case the resolve action is Fail. The + // message data fields are populated automatically. + // + // If a non-zero failure_code is specified, failure_message must not be set. + // + // For backwards-compatibility reasons, TEMPORARY_CHANNEL_FAILURE is the + // default value for this field. + lnrpc.Failure.FailureCode failure_code = 5; +} + +enum ResolveHoldForwardAction { + SETTLE = 0; + FAIL = 1; + RESUME = 2; +} + +message UpdateChanStatusRequest { + lnrpc.ChannelPoint chan_point = 1; + + ChanStatusAction action = 2; +} + +enum ChanStatusAction { + ENABLE = 0; + DISABLE = 1; + AUTO = 2; +} + +message UpdateChanStatusResponse { } \ No newline at end of file diff --git a/vendor/signrpc/signer.proto b/vendor/signrpc/signer.proto index 5ea85dd..9d25a3c 100644 --- a/vendor/signrpc/signer.proto +++ b/vendor/signrpc/signer.proto @@ -1,640 +1,640 @@ -syntax = "proto3"; - -package signrpc; - -option go_package = "github.com/lightningnetwork/lnd/lnrpc/signrpc"; - -// Signer is a service that gives access to the signing functionality of the -// daemon's wallet. -service Signer { - /* - SignOutputRaw is a method that can be used to generated a signature for a - set of inputs/outputs to a transaction. Each request specifies details - concerning how the outputs should be signed, which keys they should be - signed with, and also any optional tweaks. The return value is a fixed - 64-byte signature (the same format as we use on the wire in Lightning). - - If we are unable to sign using the specified keys, then an error will be - returned. - */ - rpc SignOutputRaw (SignReq) returns (SignResp); - - /* - ComputeInputScript generates a complete InputIndex for the passed - transaction with the signature as defined within the passed SignDescriptor. - This method should be capable of generating the proper input script for both - regular p2wkh/p2tr outputs and p2wkh outputs nested within a regular p2sh - output. - - Note that when using this method to sign inputs belonging to the wallet, - the only items of the SignDescriptor that need to be populated are pkScript - in the TxOut field, the value in that same field, and finally the input - index. - */ - rpc ComputeInputScript (SignReq) returns (InputScriptResp); - - /* - SignMessage signs a message with the key specified in the key locator. The - returned signature is fixed-size LN wire format encoded. - - The main difference to SignMessage in the main RPC is that a specific key is - used to sign the message instead of the node identity private key. - */ - rpc SignMessage (SignMessageReq) returns (SignMessageResp); - - /* - VerifyMessage verifies a signature over a message using the public key - provided. The signature must be fixed-size LN wire format encoded. - - The main difference to VerifyMessage in the main RPC is that the public key - used to sign the message does not have to be a node known to the network. - */ - rpc VerifyMessage (VerifyMessageReq) returns (VerifyMessageResp); - - /* - DeriveSharedKey returns a shared secret key by performing Diffie-Hellman key - derivation between the ephemeral public key in the request and the node's - key specified in the key_desc parameter. Either a key locator or a raw - public key is expected in the key_desc, if neither is supplied, defaults to - the node's identity private key: - P_shared = privKeyNode * ephemeralPubkey - The resulting shared public key is serialized in the compressed format and - hashed with sha256, resulting in the final key length of 256bit. - */ - rpc DeriveSharedKey (SharedKeyRequest) returns (SharedKeyResponse); - - /* - MuSig2CombineKeys (experimental!) is a stateless helper RPC that can be used - to calculate the combined MuSig2 public key from a list of all participating - signers' public keys. This RPC is completely stateless and deterministic and - does not create any signing session. It can be used to determine the Taproot - public key that should be put in an on-chain output once all public keys are - known. A signing session is only needed later when that output should be - _spent_ again. - - NOTE: The MuSig2 BIP is not final yet and therefore this API must be - considered to be HIGHLY EXPERIMENTAL and subject to change in upcoming - releases. Backward compatibility is not guaranteed! - */ - rpc MuSig2CombineKeys (MuSig2CombineKeysRequest) - returns (MuSig2CombineKeysResponse); - - /* - MuSig2CreateSession (experimental!) creates a new MuSig2 signing session - using the local key identified by the key locator. The complete list of all - public keys of all signing parties must be provided, including the public - key of the local signing key. If nonces of other parties are already known, - they can be submitted as well to reduce the number of RPC calls necessary - later on. - - NOTE: The MuSig2 BIP is not final yet and therefore this API must be - considered to be HIGHLY EXPERIMENTAL and subject to change in upcoming - releases. Backward compatibility is not guaranteed! - */ - rpc MuSig2CreateSession (MuSig2SessionRequest) - returns (MuSig2SessionResponse); - - /* - MuSig2RegisterNonces (experimental!) registers one or more public nonces of - other signing participants for a session identified by its ID. This RPC can - be called multiple times until all nonces are registered. - - NOTE: The MuSig2 BIP is not final yet and therefore this API must be - considered to be HIGHLY EXPERIMENTAL and subject to change in upcoming - releases. Backward compatibility is not guaranteed! - */ - rpc MuSig2RegisterNonces (MuSig2RegisterNoncesRequest) - returns (MuSig2RegisterNoncesResponse); - - /* - MuSig2Sign (experimental!) creates a partial signature using the local - signing key that was specified when the session was created. This can only - be called when all public nonces of all participants are known and have been - registered with the session. If this node isn't responsible for combining - all the partial signatures, then the cleanup flag should be set, indicating - that the session can be removed from memory once the signature was produced. - - NOTE: The MuSig2 BIP is not final yet and therefore this API must be - considered to be HIGHLY EXPERIMENTAL and subject to change in upcoming - releases. Backward compatibility is not guaranteed! - */ - rpc MuSig2Sign (MuSig2SignRequest) returns (MuSig2SignResponse); - - /* - MuSig2CombineSig (experimental!) combines the given partial signature(s) - with the local one, if it already exists. Once a partial signature of all - participants is registered, the final signature will be combined and - returned. - - NOTE: The MuSig2 BIP is not final yet and therefore this API must be - considered to be HIGHLY EXPERIMENTAL and subject to change in upcoming - releases. Backward compatibility is not guaranteed! - */ - rpc MuSig2CombineSig (MuSig2CombineSigRequest) - returns (MuSig2CombineSigResponse); - - /* - MuSig2Cleanup (experimental!) allows a caller to clean up a session early in - cases where it's obvious that the signing session won't succeed and the - resources can be released. - - NOTE: The MuSig2 BIP is not final yet and therefore this API must be - considered to be HIGHLY EXPERIMENTAL and subject to change in upcoming - releases. Backward compatibility is not guaranteed! - */ - rpc MuSig2Cleanup (MuSig2CleanupRequest) returns (MuSig2CleanupResponse); -} - -message KeyLocator { - // The family of key being identified. - int32 key_family = 1; - - // The precise index of the key being identified. - int32 key_index = 2; -} - -message KeyDescriptor { - /* - The raw bytes of the public key in the key pair being identified. Either - this or the KeyLocator must be specified. - */ - bytes raw_key_bytes = 1; - - /* - The key locator that identifies which private key to use for signing. - Either this or the raw bytes of the target public key must be specified. - */ - KeyLocator key_loc = 2; -} - -message TxOut { - // The value of the output being spent. - int64 value = 1; - - // The script of the output being spent. - bytes pk_script = 2; -} - -enum SignMethod { - /* - Specifies that a SegWit v0 (p2wkh, np2wkh, p2wsh) input script should be - signed. - */ - SIGN_METHOD_WITNESS_V0 = 0; - - /* - Specifies that a SegWit v1 (p2tr) input should be signed by using the - BIP0086 method (commit to internal key only). - */ - SIGN_METHOD_TAPROOT_KEY_SPEND_BIP0086 = 1; - - /* - Specifies that a SegWit v1 (p2tr) input should be signed by using a given - taproot hash to commit to in addition to the internal key. - */ - SIGN_METHOD_TAPROOT_KEY_SPEND = 2; - - /* - Specifies that a SegWit v1 (p2tr) input should be spent using the script - path and that a specific leaf script should be signed for. - */ - SIGN_METHOD_TAPROOT_SCRIPT_SPEND = 3; -} - -message SignDescriptor { - /* - A descriptor that precisely describes *which* key to use for signing. This - may provide the raw public key directly, or require the Signer to re-derive - the key according to the populated derivation path. - - Note that if the key descriptor was obtained through walletrpc.DeriveKey, - then the key locator MUST always be provided, since the derived keys are not - persisted unlike with DeriveNextKey. - */ - KeyDescriptor key_desc = 1; - - /* - A scalar value that will be added to the private key corresponding to the - above public key to obtain the private key to be used to sign this input. - This value is typically derived via the following computation: - - * derivedKey = privkey + sha256(perCommitmentPoint || pubKey) mod N - */ - bytes single_tweak = 2; - - /* - A private key that will be used in combination with its corresponding - private key to derive the private key that is to be used to sign the target - input. Within the Lightning protocol, this value is typically the - commitment secret from a previously revoked commitment transaction. This - value is in combination with two hash values, and the original private key - to derive the private key to be used when signing. - - * k = (privKey*sha256(pubKey || tweakPub) + - tweakPriv*sha256(tweakPub || pubKey)) mod N - */ - bytes double_tweak = 3; - - /* - The 32 byte input to the taproot tweak derivation that is used to derive - the output key from an internal key: outputKey = internalKey + - tagged_hash("tapTweak", internalKey || tapTweak). - - When doing a BIP 86 spend, this field can be an empty byte slice. - - When doing a normal key path spend, with the output key committing to an - actual script root, then this field should be: the tapscript root hash. - */ - bytes tap_tweak = 10; - - /* - The full script required to properly redeem the output. This field will - only be populated if a p2tr, p2wsh or a p2sh output is being signed. If a - taproot script path spend is being attempted, then this should be the raw - leaf script. - */ - bytes witness_script = 4; - - /* - A description of the output being spent. The value and script MUST be - provided. - */ - TxOut output = 5; - - /* - The target sighash type that should be used when generating the final - sighash, and signature. - */ - uint32 sighash = 7; - - /* - The target input within the transaction that should be signed. - */ - int32 input_index = 8; - - /* - The sign method specifies how the input should be signed. Depending on the - method, either the tap_tweak, witness_script or both need to be specified. - Defaults to SegWit v0 signing to be backward compatible with older RPC - clients. - */ - SignMethod sign_method = 9; -} - -message SignReq { - // The raw bytes of the transaction to be signed. - bytes raw_tx_bytes = 1; - - // A set of sign descriptors, for each input to be signed. - repeated SignDescriptor sign_descs = 2; - - /* - The full list of UTXO information for each of the inputs being spent. This - is required when spending one or more taproot (SegWit v1) outputs. - */ - repeated TxOut prev_outputs = 3; -} - -message SignResp { - /* - A set of signatures realized in a fixed 64-byte format ordered in ascending - input order. - */ - repeated bytes raw_sigs = 1; -} - -message InputScript { - // The serializes witness stack for the specified input. - repeated bytes witness = 1; - - /* - The optional sig script for the specified witness that will only be set if - the input specified is a nested p2sh witness program. - */ - bytes sig_script = 2; -} - -message InputScriptResp { - // The set of fully valid input scripts requested. - repeated InputScript input_scripts = 1; -} - -message SignMessageReq { - /* - The message to be signed. When using REST, this field must be encoded as - base64. - */ - bytes msg = 1; - - // The key locator that identifies which key to use for signing. - KeyLocator key_loc = 2; - - // Double-SHA256 hash instead of just the default single round. - bool double_hash = 3; - - /* - Use the compact (pubkey recoverable) format instead of the raw lnwire - format. This option cannot be used with Schnorr signatures. - */ - bool compact_sig = 4; - - /* - Use Schnorr signature. This option cannot be used with compact format. - */ - bool schnorr_sig = 5; - - /* - The optional Taproot tweak bytes to apply to the private key before creating - a Schnorr signature. The private key is tweaked as described in BIP-341: - privKey + h_tapTweak(internalKey || tapTweak) - */ - bytes schnorr_sig_tap_tweak = 6; -} -message SignMessageResp { - /* - The signature for the given message in the fixed-size LN wire format. - */ - bytes signature = 1; -} - -message VerifyMessageReq { - // The message over which the signature is to be verified. When using - // REST, this field must be encoded as base64. - bytes msg = 1; - - /* - The fixed-size LN wire encoded signature to be verified over the given - message. When using REST, this field must be encoded as base64. - */ - bytes signature = 2; - - /* - The public key the signature has to be valid for. When using REST, this - field must be encoded as base64. If the is_schnorr_sig option is true, then - the public key is expected to be in the 32-byte x-only serialization - according to BIP-340. - */ - bytes pubkey = 3; - - /* - Specifies if the signature is a Schnorr signature. - */ - bool is_schnorr_sig = 4; -} - -message VerifyMessageResp { - // Whether the signature was valid over the given message. - bool valid = 1; -} - -message SharedKeyRequest { - // The ephemeral public key to use for the DH key derivation. - bytes ephemeral_pubkey = 1; - - /* - Deprecated. The optional key locator of the local key that should be used. - If this parameter is not set then the node's identity private key will be - used. - */ - KeyLocator key_loc = 2 [deprecated = true]; - - /* - A key descriptor describes the key used for performing ECDH. Either a key - locator or a raw public key is expected, if neither is supplied, defaults to - the node's identity private key. - */ - KeyDescriptor key_desc = 3; -} - -message SharedKeyResponse { - // The shared public key, hashed with sha256. - bytes shared_key = 1; -} - -message TweakDesc { - /* - Tweak is the 32-byte value that will modify the public key. - */ - bytes tweak = 1; - - /* - Specifies if the target key should be converted to an x-only public key - before tweaking. If true, then the public key will be mapped to an x-only - key before the tweaking operation is applied. - */ - bool is_x_only = 2; -} - -message TaprootTweakDesc { - /* - The root hash of the tapscript tree if a script path is committed to. If - the MuSig2 key put on chain doesn't also commit to a script path (BIP-0086 - key spend only), then this needs to be empty and the key_spend_only field - below must be set to true. This is required because gRPC cannot - differentiate between a zero-size byte slice and a nil byte slice (both - would be serialized the same way). So the extra boolean is required. - */ - bytes script_root = 1; - - /* - Indicates that the above script_root is expected to be empty because this - is a BIP-0086 key spend only commitment where only the internal key is - committed to instead of also including a script root hash. - */ - bool key_spend_only = 2; -} - -message MuSig2CombineKeysRequest { - /* - A list of all public keys (serialized in 32-byte x-only format!) - participating in the signing session. The list will always be sorted - lexicographically internally. This must include the local key which is - described by the above key_loc. - */ - repeated bytes all_signer_pubkeys = 1; - - /* - A series of optional generic tweaks to be applied to the the aggregated - public key. - */ - repeated TweakDesc tweaks = 2; - - /* - An optional taproot specific tweak that must be specified if the MuSig2 - combined key will be used as the main taproot key of a taproot output - on-chain. - */ - TaprootTweakDesc taproot_tweak = 3; -} - -message MuSig2CombineKeysResponse { - /* - The combined public key (in the 32-byte x-only format) with all tweaks - applied to it. If a taproot tweak is specified, this corresponds to the - taproot key that can be put into the on-chain output. - */ - bytes combined_key = 1; - - /* - The raw combined public key (in the 32-byte x-only format) before any tweaks - are applied to it. If a taproot tweak is specified, this corresponds to the - internal key that needs to be put into the witness if the script spend path - is used. - */ - bytes taproot_internal_key = 2; -} - -message MuSig2SessionRequest { - /* - The key locator that identifies which key to use for signing. - */ - KeyLocator key_loc = 1; - - /* - A list of all public keys (serialized in 32-byte x-only format!) - participating in the signing session. The list will always be sorted - lexicographically internally. This must include the local key which is - described by the above key_loc. - */ - repeated bytes all_signer_pubkeys = 2; - - /* - An optional list of all public nonces of other signing participants that - might already be known. - */ - repeated bytes other_signer_public_nonces = 3; - - /* - A series of optional generic tweaks to be applied to the the aggregated - public key. - */ - repeated TweakDesc tweaks = 4; - - /* - An optional taproot specific tweak that must be specified if the MuSig2 - combined key will be used as the main taproot key of a taproot output - on-chain. - */ - TaprootTweakDesc taproot_tweak = 5; -} - -message MuSig2SessionResponse { - /* - The unique ID that represents this signing session. A session can be used - for producing a signature a single time. If the signing fails for any - reason, a new session with the same participants needs to be created. - */ - bytes session_id = 1; - - /* - The combined public key (in the 32-byte x-only format) with all tweaks - applied to it. If a taproot tweak is specified, this corresponds to the - taproot key that can be put into the on-chain output. - */ - bytes combined_key = 2; - - /* - The raw combined public key (in the 32-byte x-only format) before any tweaks - are applied to it. If a taproot tweak is specified, this corresponds to the - internal key that needs to be put into the witness if the script spend path - is used. - */ - bytes taproot_internal_key = 3; - - /* - The two public nonces the local signer uses, combined into a single value - of 66 bytes. Can be split into the two 33-byte points to get the individual - nonces. - */ - bytes local_public_nonces = 4; - - /* - Indicates whether all nonces required to start the signing process are known - now. - */ - bool have_all_nonces = 5; -} - -message MuSig2RegisterNoncesRequest { - /* - The unique ID of the signing session those nonces should be registered with. - */ - bytes session_id = 1; - - /* - A list of all public nonces of other signing participants that should be - registered. - */ - repeated bytes other_signer_public_nonces = 3; -} - -message MuSig2RegisterNoncesResponse { - /* - Indicates whether all nonces required to start the signing process are known - now. - */ - bool have_all_nonces = 1; -} - -message MuSig2SignRequest { - /* - The unique ID of the signing session to use for signing. - */ - bytes session_id = 1; - - /* - The 32-byte SHA256 digest of the message to sign. - */ - bytes message_digest = 2; - - /* - Cleanup indicates that after signing, the session state can be cleaned up, - since another participant is going to be responsible for combining the - partial signatures. - */ - bool cleanup = 3; -} - -message MuSig2SignResponse { - /* - The partial signature created by the local signer. - */ - bytes local_partial_signature = 1; -} - -message MuSig2CombineSigRequest { - /* - The unique ID of the signing session to combine the signatures for. - */ - bytes session_id = 1; - - /* - The list of all other participants' partial signatures to add to the current - session. - */ - repeated bytes other_partial_signatures = 2; -} - -message MuSig2CombineSigResponse { - /* - Indicates whether all partial signatures required to create a final, full - signature are known yet. If this is true, then the final_signature field is - set, otherwise it is empty. - */ - bool have_all_signatures = 1; - - /* - The final, full signature that is valid for the combined public key. - */ - bytes final_signature = 2; -} - -message MuSig2CleanupRequest { - /* - The unique ID of the signing session that should be removed/cleaned up. - */ - bytes session_id = 1; -} - -message MuSig2CleanupResponse { +syntax = "proto3"; + +package signrpc; + +option go_package = "github.com/lightningnetwork/lnd/lnrpc/signrpc"; + +// Signer is a service that gives access to the signing functionality of the +// daemon's wallet. +service Signer { + /* + SignOutputRaw is a method that can be used to generated a signature for a + set of inputs/outputs to a transaction. Each request specifies details + concerning how the outputs should be signed, which keys they should be + signed with, and also any optional tweaks. The return value is a fixed + 64-byte signature (the same format as we use on the wire in Lightning). + + If we are unable to sign using the specified keys, then an error will be + returned. + */ + rpc SignOutputRaw (SignReq) returns (SignResp); + + /* + ComputeInputScript generates a complete InputIndex for the passed + transaction with the signature as defined within the passed SignDescriptor. + This method should be capable of generating the proper input script for both + regular p2wkh/p2tr outputs and p2wkh outputs nested within a regular p2sh + output. + + Note that when using this method to sign inputs belonging to the wallet, + the only items of the SignDescriptor that need to be populated are pkScript + in the TxOut field, the value in that same field, and finally the input + index. + */ + rpc ComputeInputScript (SignReq) returns (InputScriptResp); + + /* + SignMessage signs a message with the key specified in the key locator. The + returned signature is fixed-size LN wire format encoded. + + The main difference to SignMessage in the main RPC is that a specific key is + used to sign the message instead of the node identity private key. + */ + rpc SignMessage (SignMessageReq) returns (SignMessageResp); + + /* + VerifyMessage verifies a signature over a message using the public key + provided. The signature must be fixed-size LN wire format encoded. + + The main difference to VerifyMessage in the main RPC is that the public key + used to sign the message does not have to be a node known to the network. + */ + rpc VerifyMessage (VerifyMessageReq) returns (VerifyMessageResp); + + /* + DeriveSharedKey returns a shared secret key by performing Diffie-Hellman key + derivation between the ephemeral public key in the request and the node's + key specified in the key_desc parameter. Either a key locator or a raw + public key is expected in the key_desc, if neither is supplied, defaults to + the node's identity private key: + P_shared = privKeyNode * ephemeralPubkey + The resulting shared public key is serialized in the compressed format and + hashed with sha256, resulting in the final key length of 256bit. + */ + rpc DeriveSharedKey (SharedKeyRequest) returns (SharedKeyResponse); + + /* + MuSig2CombineKeys (experimental!) is a stateless helper RPC that can be used + to calculate the combined MuSig2 public key from a list of all participating + signers' public keys. This RPC is completely stateless and deterministic and + does not create any signing session. It can be used to determine the Taproot + public key that should be put in an on-chain output once all public keys are + known. A signing session is only needed later when that output should be + _spent_ again. + + NOTE: The MuSig2 BIP is not final yet and therefore this API must be + considered to be HIGHLY EXPERIMENTAL and subject to change in upcoming + releases. Backward compatibility is not guaranteed! + */ + rpc MuSig2CombineKeys (MuSig2CombineKeysRequest) + returns (MuSig2CombineKeysResponse); + + /* + MuSig2CreateSession (experimental!) creates a new MuSig2 signing session + using the local key identified by the key locator. The complete list of all + public keys of all signing parties must be provided, including the public + key of the local signing key. If nonces of other parties are already known, + they can be submitted as well to reduce the number of RPC calls necessary + later on. + + NOTE: The MuSig2 BIP is not final yet and therefore this API must be + considered to be HIGHLY EXPERIMENTAL and subject to change in upcoming + releases. Backward compatibility is not guaranteed! + */ + rpc MuSig2CreateSession (MuSig2SessionRequest) + returns (MuSig2SessionResponse); + + /* + MuSig2RegisterNonces (experimental!) registers one or more public nonces of + other signing participants for a session identified by its ID. This RPC can + be called multiple times until all nonces are registered. + + NOTE: The MuSig2 BIP is not final yet and therefore this API must be + considered to be HIGHLY EXPERIMENTAL and subject to change in upcoming + releases. Backward compatibility is not guaranteed! + */ + rpc MuSig2RegisterNonces (MuSig2RegisterNoncesRequest) + returns (MuSig2RegisterNoncesResponse); + + /* + MuSig2Sign (experimental!) creates a partial signature using the local + signing key that was specified when the session was created. This can only + be called when all public nonces of all participants are known and have been + registered with the session. If this node isn't responsible for combining + all the partial signatures, then the cleanup flag should be set, indicating + that the session can be removed from memory once the signature was produced. + + NOTE: The MuSig2 BIP is not final yet and therefore this API must be + considered to be HIGHLY EXPERIMENTAL and subject to change in upcoming + releases. Backward compatibility is not guaranteed! + */ + rpc MuSig2Sign (MuSig2SignRequest) returns (MuSig2SignResponse); + + /* + MuSig2CombineSig (experimental!) combines the given partial signature(s) + with the local one, if it already exists. Once a partial signature of all + participants is registered, the final signature will be combined and + returned. + + NOTE: The MuSig2 BIP is not final yet and therefore this API must be + considered to be HIGHLY EXPERIMENTAL and subject to change in upcoming + releases. Backward compatibility is not guaranteed! + */ + rpc MuSig2CombineSig (MuSig2CombineSigRequest) + returns (MuSig2CombineSigResponse); + + /* + MuSig2Cleanup (experimental!) allows a caller to clean up a session early in + cases where it's obvious that the signing session won't succeed and the + resources can be released. + + NOTE: The MuSig2 BIP is not final yet and therefore this API must be + considered to be HIGHLY EXPERIMENTAL and subject to change in upcoming + releases. Backward compatibility is not guaranteed! + */ + rpc MuSig2Cleanup (MuSig2CleanupRequest) returns (MuSig2CleanupResponse); +} + +message KeyLocator { + // The family of key being identified. + int32 key_family = 1; + + // The precise index of the key being identified. + int32 key_index = 2; +} + +message KeyDescriptor { + /* + The raw bytes of the public key in the key pair being identified. Either + this or the KeyLocator must be specified. + */ + bytes raw_key_bytes = 1; + + /* + The key locator that identifies which private key to use for signing. + Either this or the raw bytes of the target public key must be specified. + */ + KeyLocator key_loc = 2; +} + +message TxOut { + // The value of the output being spent. + int64 value = 1; + + // The script of the output being spent. + bytes pk_script = 2; +} + +enum SignMethod { + /* + Specifies that a SegWit v0 (p2wkh, np2wkh, p2wsh) input script should be + signed. + */ + SIGN_METHOD_WITNESS_V0 = 0; + + /* + Specifies that a SegWit v1 (p2tr) input should be signed by using the + BIP0086 method (commit to internal key only). + */ + SIGN_METHOD_TAPROOT_KEY_SPEND_BIP0086 = 1; + + /* + Specifies that a SegWit v1 (p2tr) input should be signed by using a given + taproot hash to commit to in addition to the internal key. + */ + SIGN_METHOD_TAPROOT_KEY_SPEND = 2; + + /* + Specifies that a SegWit v1 (p2tr) input should be spent using the script + path and that a specific leaf script should be signed for. + */ + SIGN_METHOD_TAPROOT_SCRIPT_SPEND = 3; +} + +message SignDescriptor { + /* + A descriptor that precisely describes *which* key to use for signing. This + may provide the raw public key directly, or require the Signer to re-derive + the key according to the populated derivation path. + + Note that if the key descriptor was obtained through walletrpc.DeriveKey, + then the key locator MUST always be provided, since the derived keys are not + persisted unlike with DeriveNextKey. + */ + KeyDescriptor key_desc = 1; + + /* + A scalar value that will be added to the private key corresponding to the + above public key to obtain the private key to be used to sign this input. + This value is typically derived via the following computation: + + * derivedKey = privkey + sha256(perCommitmentPoint || pubKey) mod N + */ + bytes single_tweak = 2; + + /* + A private key that will be used in combination with its corresponding + private key to derive the private key that is to be used to sign the target + input. Within the Lightning protocol, this value is typically the + commitment secret from a previously revoked commitment transaction. This + value is in combination with two hash values, and the original private key + to derive the private key to be used when signing. + + * k = (privKey*sha256(pubKey || tweakPub) + + tweakPriv*sha256(tweakPub || pubKey)) mod N + */ + bytes double_tweak = 3; + + /* + The 32 byte input to the taproot tweak derivation that is used to derive + the output key from an internal key: outputKey = internalKey + + tagged_hash("tapTweak", internalKey || tapTweak). + + When doing a BIP 86 spend, this field can be an empty byte slice. + + When doing a normal key path spend, with the output key committing to an + actual script root, then this field should be: the tapscript root hash. + */ + bytes tap_tweak = 10; + + /* + The full script required to properly redeem the output. This field will + only be populated if a p2tr, p2wsh or a p2sh output is being signed. If a + taproot script path spend is being attempted, then this should be the raw + leaf script. + */ + bytes witness_script = 4; + + /* + A description of the output being spent. The value and script MUST be + provided. + */ + TxOut output = 5; + + /* + The target sighash type that should be used when generating the final + sighash, and signature. + */ + uint32 sighash = 7; + + /* + The target input within the transaction that should be signed. + */ + int32 input_index = 8; + + /* + The sign method specifies how the input should be signed. Depending on the + method, either the tap_tweak, witness_script or both need to be specified. + Defaults to SegWit v0 signing to be backward compatible with older RPC + clients. + */ + SignMethod sign_method = 9; +} + +message SignReq { + // The raw bytes of the transaction to be signed. + bytes raw_tx_bytes = 1; + + // A set of sign descriptors, for each input to be signed. + repeated SignDescriptor sign_descs = 2; + + /* + The full list of UTXO information for each of the inputs being spent. This + is required when spending one or more taproot (SegWit v1) outputs. + */ + repeated TxOut prev_outputs = 3; +} + +message SignResp { + /* + A set of signatures realized in a fixed 64-byte format ordered in ascending + input order. + */ + repeated bytes raw_sigs = 1; +} + +message InputScript { + // The serializes witness stack for the specified input. + repeated bytes witness = 1; + + /* + The optional sig script for the specified witness that will only be set if + the input specified is a nested p2sh witness program. + */ + bytes sig_script = 2; +} + +message InputScriptResp { + // The set of fully valid input scripts requested. + repeated InputScript input_scripts = 1; +} + +message SignMessageReq { + /* + The message to be signed. When using REST, this field must be encoded as + base64. + */ + bytes msg = 1; + + // The key locator that identifies which key to use for signing. + KeyLocator key_loc = 2; + + // Double-SHA256 hash instead of just the default single round. + bool double_hash = 3; + + /* + Use the compact (pubkey recoverable) format instead of the raw lnwire + format. This option cannot be used with Schnorr signatures. + */ + bool compact_sig = 4; + + /* + Use Schnorr signature. This option cannot be used with compact format. + */ + bool schnorr_sig = 5; + + /* + The optional Taproot tweak bytes to apply to the private key before creating + a Schnorr signature. The private key is tweaked as described in BIP-341: + privKey + h_tapTweak(internalKey || tapTweak) + */ + bytes schnorr_sig_tap_tweak = 6; +} +message SignMessageResp { + /* + The signature for the given message in the fixed-size LN wire format. + */ + bytes signature = 1; +} + +message VerifyMessageReq { + // The message over which the signature is to be verified. When using + // REST, this field must be encoded as base64. + bytes msg = 1; + + /* + The fixed-size LN wire encoded signature to be verified over the given + message. When using REST, this field must be encoded as base64. + */ + bytes signature = 2; + + /* + The public key the signature has to be valid for. When using REST, this + field must be encoded as base64. If the is_schnorr_sig option is true, then + the public key is expected to be in the 32-byte x-only serialization + according to BIP-340. + */ + bytes pubkey = 3; + + /* + Specifies if the signature is a Schnorr signature. + */ + bool is_schnorr_sig = 4; +} + +message VerifyMessageResp { + // Whether the signature was valid over the given message. + bool valid = 1; +} + +message SharedKeyRequest { + // The ephemeral public key to use for the DH key derivation. + bytes ephemeral_pubkey = 1; + + /* + Deprecated. The optional key locator of the local key that should be used. + If this parameter is not set then the node's identity private key will be + used. + */ + KeyLocator key_loc = 2 [deprecated = true]; + + /* + A key descriptor describes the key used for performing ECDH. Either a key + locator or a raw public key is expected, if neither is supplied, defaults to + the node's identity private key. + */ + KeyDescriptor key_desc = 3; +} + +message SharedKeyResponse { + // The shared public key, hashed with sha256. + bytes shared_key = 1; +} + +message TweakDesc { + /* + Tweak is the 32-byte value that will modify the public key. + */ + bytes tweak = 1; + + /* + Specifies if the target key should be converted to an x-only public key + before tweaking. If true, then the public key will be mapped to an x-only + key before the tweaking operation is applied. + */ + bool is_x_only = 2; +} + +message TaprootTweakDesc { + /* + The root hash of the tapscript tree if a script path is committed to. If + the MuSig2 key put on chain doesn't also commit to a script path (BIP-0086 + key spend only), then this needs to be empty and the key_spend_only field + below must be set to true. This is required because gRPC cannot + differentiate between a zero-size byte slice and a nil byte slice (both + would be serialized the same way). So the extra boolean is required. + */ + bytes script_root = 1; + + /* + Indicates that the above script_root is expected to be empty because this + is a BIP-0086 key spend only commitment where only the internal key is + committed to instead of also including a script root hash. + */ + bool key_spend_only = 2; +} + +message MuSig2CombineKeysRequest { + /* + A list of all public keys (serialized in 32-byte x-only format!) + participating in the signing session. The list will always be sorted + lexicographically internally. This must include the local key which is + described by the above key_loc. + */ + repeated bytes all_signer_pubkeys = 1; + + /* + A series of optional generic tweaks to be applied to the the aggregated + public key. + */ + repeated TweakDesc tweaks = 2; + + /* + An optional taproot specific tweak that must be specified if the MuSig2 + combined key will be used as the main taproot key of a taproot output + on-chain. + */ + TaprootTweakDesc taproot_tweak = 3; +} + +message MuSig2CombineKeysResponse { + /* + The combined public key (in the 32-byte x-only format) with all tweaks + applied to it. If a taproot tweak is specified, this corresponds to the + taproot key that can be put into the on-chain output. + */ + bytes combined_key = 1; + + /* + The raw combined public key (in the 32-byte x-only format) before any tweaks + are applied to it. If a taproot tweak is specified, this corresponds to the + internal key that needs to be put into the witness if the script spend path + is used. + */ + bytes taproot_internal_key = 2; +} + +message MuSig2SessionRequest { + /* + The key locator that identifies which key to use for signing. + */ + KeyLocator key_loc = 1; + + /* + A list of all public keys (serialized in 32-byte x-only format!) + participating in the signing session. The list will always be sorted + lexicographically internally. This must include the local key which is + described by the above key_loc. + */ + repeated bytes all_signer_pubkeys = 2; + + /* + An optional list of all public nonces of other signing participants that + might already be known. + */ + repeated bytes other_signer_public_nonces = 3; + + /* + A series of optional generic tweaks to be applied to the the aggregated + public key. + */ + repeated TweakDesc tweaks = 4; + + /* + An optional taproot specific tweak that must be specified if the MuSig2 + combined key will be used as the main taproot key of a taproot output + on-chain. + */ + TaprootTweakDesc taproot_tweak = 5; +} + +message MuSig2SessionResponse { + /* + The unique ID that represents this signing session. A session can be used + for producing a signature a single time. If the signing fails for any + reason, a new session with the same participants needs to be created. + */ + bytes session_id = 1; + + /* + The combined public key (in the 32-byte x-only format) with all tweaks + applied to it. If a taproot tweak is specified, this corresponds to the + taproot key that can be put into the on-chain output. + */ + bytes combined_key = 2; + + /* + The raw combined public key (in the 32-byte x-only format) before any tweaks + are applied to it. If a taproot tweak is specified, this corresponds to the + internal key that needs to be put into the witness if the script spend path + is used. + */ + bytes taproot_internal_key = 3; + + /* + The two public nonces the local signer uses, combined into a single value + of 66 bytes. Can be split into the two 33-byte points to get the individual + nonces. + */ + bytes local_public_nonces = 4; + + /* + Indicates whether all nonces required to start the signing process are known + now. + */ + bool have_all_nonces = 5; +} + +message MuSig2RegisterNoncesRequest { + /* + The unique ID of the signing session those nonces should be registered with. + */ + bytes session_id = 1; + + /* + A list of all public nonces of other signing participants that should be + registered. + */ + repeated bytes other_signer_public_nonces = 3; +} + +message MuSig2RegisterNoncesResponse { + /* + Indicates whether all nonces required to start the signing process are known + now. + */ + bool have_all_nonces = 1; +} + +message MuSig2SignRequest { + /* + The unique ID of the signing session to use for signing. + */ + bytes session_id = 1; + + /* + The 32-byte SHA256 digest of the message to sign. + */ + bytes message_digest = 2; + + /* + Cleanup indicates that after signing, the session state can be cleaned up, + since another participant is going to be responsible for combining the + partial signatures. + */ + bool cleanup = 3; +} + +message MuSig2SignResponse { + /* + The partial signature created by the local signer. + */ + bytes local_partial_signature = 1; +} + +message MuSig2CombineSigRequest { + /* + The unique ID of the signing session to combine the signatures for. + */ + bytes session_id = 1; + + /* + The list of all other participants' partial signatures to add to the current + session. + */ + repeated bytes other_partial_signatures = 2; +} + +message MuSig2CombineSigResponse { + /* + Indicates whether all partial signatures required to create a final, full + signature are known yet. If this is true, then the final_signature field is + set, otherwise it is empty. + */ + bool have_all_signatures = 1; + + /* + The final, full signature that is valid for the combined public key. + */ + bytes final_signature = 2; +} + +message MuSig2CleanupRequest { + /* + The unique ID of the signing session that should be removed/cleaned up. + */ + bytes session_id = 1; +} + +message MuSig2CleanupResponse { } \ No newline at end of file diff --git a/vendor/staterpc/state.proto b/vendor/staterpc/state.proto index 78c61e0..199a8d1 100644 --- a/vendor/staterpc/state.proto +++ b/vendor/staterpc/state.proto @@ -1,60 +1,60 @@ -syntax = "proto3"; - -package staterpc; - -/* - * 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 - */ - -// State service is a always running service that exposes the current state of -// the wallet and RPC server. -service State { - // SubscribeState subscribes to the state of the wallet. The current wallet - // state will always be delivered immediately. - rpc SubscribeState (SubscribeStateRequest) - returns (stream SubscribeStateResponse); - - // GetState returns the current wallet state without streaming further - // changes. - rpc GetState (GetStateRequest) returns (GetStateResponse); -} - -enum WalletState { - NON_EXISTING = 0; - LOCKED = 1; - UNLOCKED = 2; - RPC_ACTIVE = 3; - - // SERVER_ACTIVE means that the lnd server is ready to accept calls. - SERVER_ACTIVE = 4; - - WAITING_TO_START = 255; -} - -message SubscribeStateRequest { -} - -message SubscribeStateResponse { - WalletState state = 1; -} - -message GetStateRequest { -} - -message GetStateResponse { - WalletState state = 1; -} +syntax = "proto3"; + +package staterpc; + +/* + * 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 + */ + +// State service is a always running service that exposes the current state of +// the wallet and RPC server. +service State { + // SubscribeState subscribes to the state of the wallet. The current wallet + // state will always be delivered immediately. + rpc SubscribeState (SubscribeStateRequest) + returns (stream SubscribeStateResponse); + + // GetState returns the current wallet state without streaming further + // changes. + rpc GetState (GetStateRequest) returns (GetStateResponse); +} + +enum WalletState { + NON_EXISTING = 0; + LOCKED = 1; + UNLOCKED = 2; + RPC_ACTIVE = 3; + + // SERVER_ACTIVE means that the lnd server is ready to accept calls. + SERVER_ACTIVE = 4; + + WAITING_TO_START = 255; +} + +message SubscribeStateRequest { +} + +message SubscribeStateResponse { + WalletState state = 1; +} + +message GetStateRequest { +} + +message GetStateResponse { + WalletState state = 1; +} diff --git a/vendor/verrpc/verrpc.proto b/vendor/verrpc/verrpc.proto index 6f3120e..3300cfe 100644 --- a/vendor/verrpc/verrpc.proto +++ b/vendor/verrpc/verrpc.proto @@ -1,47 +1,47 @@ -syntax = "proto3"; - -package verrpc; - -option go_package = "github.com/lightningnetwork/lnd/lnrpc/verrpc"; - -// Versioner is a service that can be used to get information about the version -// and build information of the running daemon. -service Versioner { - /* lncli: `version` - GetVersion returns the current version and build information of the running - daemon. - */ - rpc GetVersion (VersionRequest) returns (Version); -} - -message VersionRequest { -} - -message Version { - // A verbose description of the daemon's commit. - string commit = 1; - - // The SHA1 commit hash that the daemon is compiled with. - string commit_hash = 2; - - // The semantic version. - string version = 3; - - // The major application version. - uint32 app_major = 4; - - // The minor application version. - uint32 app_minor = 5; - - // The application patch number. - uint32 app_patch = 6; - - // The application pre-release modifier, possibly empty. - string app_pre_release = 7; - - // The list of build tags that were supplied during compilation. - repeated string build_tags = 8; - - // The version of go that compiled the executable. - string go_version = 9; -} +syntax = "proto3"; + +package verrpc; + +option go_package = "github.com/lightningnetwork/lnd/lnrpc/verrpc"; + +// Versioner is a service that can be used to get information about the version +// and build information of the running daemon. +service Versioner { + /* lncli: `version` + GetVersion returns the current version and build information of the running + daemon. + */ + rpc GetVersion (VersionRequest) returns (Version); +} + +message VersionRequest { +} + +message Version { + // A verbose description of the daemon's commit. + string commit = 1; + + // The SHA1 commit hash that the daemon is compiled with. + string commit_hash = 2; + + // The semantic version. + string version = 3; + + // The major application version. + uint32 app_major = 4; + + // The minor application version. + uint32 app_minor = 5; + + // The application patch number. + uint32 app_patch = 6; + + // The application pre-release modifier, possibly empty. + string app_pre_release = 7; + + // The list of build tags that were supplied during compilation. + repeated string build_tags = 8; + + // The version of go that compiled the executable. + string go_version = 9; +} diff --git a/vendor/walletrpc/walletkit.proto b/vendor/walletrpc/walletkit.proto index 2e5f453..2ed6fec 100644 --- a/vendor/walletrpc/walletkit.proto +++ b/vendor/walletrpc/walletkit.proto @@ -1,918 +1,918 @@ -syntax = "proto3"; - -import "lightning.proto"; -import "signrpc/signer.proto"; - -package walletrpc; - -option go_package = "github.com/lightningnetwork/lnd/lnrpc/walletrpc"; - -// WalletKit is a service that gives access to the core functionalities of the -// daemon's wallet. -service WalletKit { - /* - ListUnspent returns a list of all utxos spendable by the wallet with a - number of confirmations between the specified minimum and maximum. By - default, all utxos are listed. To list only the unconfirmed utxos, set - the unconfirmed_only to true. - */ - rpc ListUnspent (ListUnspentRequest) returns (ListUnspentResponse); - - /* - 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`. - */ - rpc LeaseOutput (LeaseOutputRequest) returns (LeaseOutputResponse); - - /* - 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); - - /* - ListLeases lists all currently locked utxos. - */ - rpc ListLeases (ListLeasesRequest) returns (ListLeasesResponse); - - /* - DeriveNextKey attempts to derive the *next* key within the key family - (account in BIP43) specified. This method should return the next external - child within this branch. - */ - rpc DeriveNextKey (KeyReq) returns (signrpc.KeyDescriptor); - - /* - DeriveKey attempts to derive an arbitrary key specified by the passed - KeyLocator. - */ - rpc DeriveKey (signrpc.KeyLocator) returns (signrpc.KeyDescriptor); - - /* - NextAddr returns the next unused address within the wallet. - */ - rpc NextAddr (AddrRequest) returns (AddrResponse); - - /* - 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); - - /* - 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. - */ - rpc RequiredReserve (RequiredReserveRequest) - returns (RequiredReserveResponse); - - /* - 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 - derivation path m/). This may be required by some hardware wallets for - proper identification and signing. - - The address type can usually be inferred from the key's version, but may be - required for certain keys to map them into the proper scope. - - For BIP-0044 keys, an address type must be specified as we intend to not - support importing BIP-0044 keys into the wallet using the legacy - pay-to-pubkey-hash (P2PKH) scheme. A nested witness address type will force - the standard BIP-0049 derivation scheme, while a witness address type will - force the standard BIP-0084 derivation scheme. - - For BIP-0049 keys, an address type must also be specified to make a - distinction between the standard BIP-0049 address schema (nested witness - pubkeys everywhere) and our own BIP-0049Plus address schema (nested pubkeys - externally, witness pubkeys internally). - - NOTE: Events (deposits/spends) for keys derived from an account will only be - detected by lnd if they happen after the import. Rescans to detect past - events will be supported later on. - */ - rpc ImportAccount (ImportAccountRequest) returns (ImportAccountResponse); - - /* - ImportPublicKey imports a public key as watch-only into the wallet. - - NOTE: Events (deposits/spends) for a key will only be detected by lnd if - they happen after the import. Rescans to detect past events will be - supported later on. - */ - rpc ImportPublicKey (ImportPublicKeyRequest) - returns (ImportPublicKeyResponse); - - /* - 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 - chain. - */ - rpc PublishTransaction (Transaction) returns (PublishResponse); - - /* - SendOutputs is similar to the existing sendmany call in Bitcoind, and - allows the caller to create a transaction that sends to several outputs at - once. This is ideal when wanting to batch create a set of transactions. - */ - rpc SendOutputs (SendOutputsRequest) returns (SendOutputsResponse); - - /* - EstimateFee attempts to query the internal fee estimator of the wallet to - determine the fee (in sat/kw) to attach to a transaction in order to - achieve the confirmation target. - */ - rpc EstimateFee (EstimateFeeRequest) returns (EstimateFeeResponse); - - /* - 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 - transaction. - - NOTE: Some of the fields within PendingSweepsRequest are not guaranteed to - remain supported. This is an advanced API that depends on the internals of - the UtxoSweeper, so things may change. - */ - rpc PendingSweeps (PendingSweepsRequest) returns (PendingSweepsResponse); - - /* - 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 - together to save on transaction fees. Due to this, we cannot rely on - bumping the fee on a specific transaction, since transactions can change at - any point with the addition of new inputs. The list of inputs that - currently exist within lnd's central batching engine can be retrieved - through the PendingSweeps RPC. - - When bumping the fee of an input that currently exists within lnd's central - batching engine, a higher fee transaction will be created that replaces the - lower fee transaction through the Replace-By-Fee (RBF) policy. If it - - This RPC also serves useful when wanting to perform a Child-Pays-For-Parent - (CPFP), where the child transaction pays for its parent's fee. This can be - done by specifying an outpoint within the low fee transaction that is under - the control of the wallet. - - The fee preference can be expressed either as a specific fee rate or a delta - of blocks in which the output should be swept on-chain within. If a fee - preference is not explicitly specified, then an error is returned. - - Note that this RPC currently doesn't perform any validation checks on the - fee preference being provided. For now, the responsibility of ensuring that - the new fee preference is sufficient is delegated to the user. - */ - rpc BumpFee (BumpFeeRequest) returns (BumpFeeResponse); - - /* - 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); - - /* - 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. - */ - rpc LabelTransaction (LabelTransactionRequest) - returns (LabelTransactionResponse); - - /* - 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 - by passing in a raw TxTemplate message. - - If there are no inputs specified in the template, coin selection is - performed automatically. If the template does contain any inputs, it is - assumed that full coin selection happened externally and no additional - inputs are added. If the specified inputs aren't enough to fund the outputs - with the given fee rate, an error is returned. - - After either selecting or verifying the inputs, all input UTXOs are locked - with an internal app ID. - - NOTE: If this method returns without an error, it is the caller's - responsibility to either spend the locked UTXOs (by finalizing and then - publishing the transaction) or to unlock/release the locked UTXOs in case of - an error on the caller's side. - */ - rpc FundPsbt (FundPsbtRequest) returns (FundPsbtResponse); - - /* - SignPsbt expects a partial transaction with all inputs and outputs fully - declared and tries to sign all unsigned inputs that have all required fields - (UTXO information, BIP32 derivation information, witness or sig scripts) - set. - If no error is returned, the PSBT is ready to be given to the next signer or - to be finalized if lnd was the last signer. - - NOTE: This RPC only signs inputs (and only those it can sign), it does not - perform any other tasks (such as coin selection, UTXO locking or - input/output/fee value validation, PSBT finalization). Any input that is - incomplete will be skipped. - */ - rpc SignPsbt (SignPsbtRequest) returns (SignPsbtResponse); - - /* - 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 - non-witness inputs or inputs without UTXO information attached or inputs - without witness data that do not belong to lnd's wallet, this method will - fail. If no error is returned, the PSBT is ready to be extracted and the - final TX within to be broadcast. - - NOTE: This method does NOT publish the transaction once finalized. It is the - caller's responsibility to either publish the transaction on success or - unlock/release any locked UTXOs in case of an error in this method. - */ - rpc FinalizePsbt (FinalizePsbtRequest) returns (FinalizePsbtResponse); -} - -message ListUnspentRequest { - // The minimum number of confirmations to be included. - int32 min_confs = 1; - - // The maximum number of confirmations to be included. - int32 max_confs = 2; - - // An optional filter to only include outputs belonging to an account. - string account = 3; - - /* - When min_confs and max_confs are zero, setting false implicitly - overrides max_confs to be MaxInt32, otherwise max_confs remains - zero. An error is returned if the value is true and both min_confs - and max_confs are non-zero. (default: false) - */ - bool unconfirmed_only = 4; -} - -message ListUnspentResponse { - // A list of utxos satisfying the specified number of confirmations. - repeated lnrpc.Utxo utxos = 1; -} - -message LeaseOutputRequest { - /* - An ID of 32 random bytes that must be unique for each distinct application - using this RPC which will be used to bound the output lease to. - */ - bytes id = 1; - - // The identifying outpoint of the output being leased. - lnrpc.OutPoint outpoint = 2; - - // The time in seconds before the lock expires. If set to zero, the default - // lock duration is used. - uint64 expiration_seconds = 3; -} - -message LeaseOutputResponse { - /* - The absolute expiration of the output lease represented as a unix timestamp. - */ - uint64 expiration = 1; -} - -message ReleaseOutputRequest { - // The unique ID that was used to lock the output. - bytes id = 1; - - // The identifying outpoint of the output being released. - lnrpc.OutPoint outpoint = 2; -} - -message ReleaseOutputResponse { -} - -message KeyReq { - /* - Is the key finger print of the root pubkey that this request is targeting. - This allows the WalletKit to possibly serve out keys for multiple HD chains - via public derivation. - */ - int32 key_finger_print = 1; - - /* - The target key family to derive a key from. In other contexts, this is - known as the "account". - */ - int32 key_family = 2; -} - -message AddrRequest { - /* - The name of the account to retrieve the next address of. If empty, the - default wallet account is used. - */ - string account = 1; - - /* - The type of address to derive. - */ - AddressType type = 2; - - /* - Whether a change address should be derived. - */ - bool change = 3; -} -message AddrResponse { - /* - The address encoded using a bech32 format. - */ - string addr = 1; -} - -enum AddressType { - UNKNOWN = 0; - WITNESS_PUBKEY_HASH = 1; - NESTED_WITNESS_PUBKEY_HASH = 2; - HYBRID_NESTED_WITNESS_PUBKEY_HASH = 3; - TAPROOT_PUBKEY = 4; -} -message Account { - // The name used to identify the account. - string name = 1; - - /* - The type of addresses the account supports. - AddressType | External Branch | Internal Branch - --------------------------------------------------------------------- - WITNESS_PUBKEY_HASH | P2WPKH | P2WPKH - NESTED_WITNESS_PUBKEY_HASH | NP2WPKH | NP2WPKH - HYBRID_NESTED_WITNESS_PUBKEY_HASH | NP2WPKH | P2WPKH - */ - AddressType address_type = 2; - - /* - The public key backing the account that all keys are derived from - represented as an extended key. This will always be empty for the default - imported account in which single public keys are imported into. - */ - string extended_public_key = 3; - - /* - The fingerprint of the root key from which the account public key was - derived from. This will always be zero for the default imported account in - which single public keys are imported into. The bytes are in big-endian - order. - */ - bytes master_key_fingerprint = 4; - - /* - The derivation path corresponding to the account public key. This will - always be empty for the default imported account in which single public keys - are imported into. - */ - string derivation_path = 5; - - /* - The number of keys derived from the external branch of the account public - key. This will always be zero for the default imported account in which - single public keys are imported into. - */ - uint32 external_key_count = 6; - - /* - The number of keys derived from the internal branch of the account public - key. This will always be zero for the default imported account in which - single public keys are imported into. - */ - uint32 internal_key_count = 7; - - // Whether the wallet stores private keys for the account. - bool watch_only = 8; -} -message ListAccountsRequest { - // An optional filter to only return accounts matching this name. - string name = 1; - - // An optional filter to only return accounts matching this address type. - AddressType address_type = 2; -} -message ListAccountsResponse { - repeated Account accounts = 1; -} - -message RequiredReserveRequest { - // The number of additional channels the user would like to open. - uint32 additional_public_channels = 1; -} - -message RequiredReserveResponse { - // The amount of reserve required. - int64 required_reserve = 1; -} - -message ImportAccountRequest { - // A name to identify the account with. - string name = 1; - - /* - A public key that corresponds to a wallet account represented as an extended - key. It must conform to a derivation path of the form - m/purpose'/coin_type'/account'. - */ - string extended_public_key = 2; - - /* - The fingerprint of the root key (also known as the key with derivation path - m/) from which the account public key was derived from. This may be required - by some hardware wallets for proper identification and signing. The bytes - must be in big-endian order. - */ - bytes master_key_fingerprint = 3; - - /* - An address type is only required when the extended account public key has a - legacy version (xpub, tpub, etc.), such that the wallet cannot detect what - address scheme it belongs to. - */ - AddressType address_type = 4; - - /* - Whether a dry run should be attempted when importing the account. This - serves as a way to confirm whether the account is being imported correctly - by returning the first N addresses for the external and internal branches of - the account. If these addresses match as expected, then it should be safe to - import the account as is. - */ - bool dry_run = 5; -} -message ImportAccountResponse { - // The details of the imported account. - Account account = 1; - - /* - The first N addresses that belong to the external branch of the account. - The external branch is typically used for external non-change addresses. - These are only returned if a dry run was specified within the request. - */ - repeated string dry_run_external_addrs = 2; - - /* - The first N addresses that belong to the internal branch of the account. - The internal branch is typically used for change addresses. These are only - returned if a dry run was specified within the request. - */ - repeated string dry_run_internal_addrs = 3; -} - -message ImportPublicKeyRequest { - // A compressed public key represented as raw bytes. - bytes public_key = 1; - - // The type of address that will be generated from the public key. - AddressType address_type = 2; -} -message ImportPublicKeyResponse { -} - -message Transaction { - /* - The raw serialized transaction. - */ - bytes tx_hex = 1; - - /* - An optional label to save with the transaction. Limited to 500 characters. - */ - string label = 2; -} -message PublishResponse { - /* - If blank, then no error occurred and the transaction was successfully - published. If not the empty string, then a string representation of the - broadcast error. - - TODO(roasbeef): map to a proper enum type - */ - string publish_error = 1; -} - -message SendOutputsRequest { - /* - The number of satoshis per kilo weight that should be used when crafting - this transaction. - */ - int64 sat_per_kw = 1; - - /* - A slice of the outputs that should be created in the transaction produced. - */ - repeated signrpc.TxOut outputs = 2; - - // An optional label for the transaction, limited to 500 characters. - string label = 3; - - // The minimum number of confirmations each one of your outputs used for - // the transaction must satisfy. - int32 min_confs = 4; - - // Whether unconfirmed outputs should be used as inputs for the transaction. - bool spend_unconfirmed = 5; -} -message SendOutputsResponse { - /* - The serialized transaction sent out on the network. - */ - bytes raw_tx = 1; -} - -message EstimateFeeRequest { - /* - The number of confirmations to shoot for when estimating the fee. - */ - int32 conf_target = 1; -} -message EstimateFeeResponse { - /* - The amount of satoshis per kw that should be used in order to reach the - confirmation target in the request. - */ - int64 sat_per_kw = 1; -} - -enum WitnessType { - UNKNOWN_WITNESS = 0; - - /* - A witness that allows us to spend the output of a commitment transaction - after a relative lock-time lockout. - */ - COMMITMENT_TIME_LOCK = 1; - - /* - A witness that allows us to spend a settled no-delay output immediately on a - counterparty's commitment transaction. - */ - COMMITMENT_NO_DELAY = 2; - - /* - A witness that allows us to sweep the settled output of a malicious - counterparty's who broadcasts a revoked commitment transaction. - */ - COMMITMENT_REVOKE = 3; - - /* - A witness that allows us to sweep an HTLC which we offered to the remote - party in the case that they broadcast a revoked commitment state. - */ - HTLC_OFFERED_REVOKE = 4; - - /* - A witness that allows us to sweep an HTLC output sent to us in the case that - the remote party broadcasts a revoked commitment state. - */ - HTLC_ACCEPTED_REVOKE = 5; - - /* - A witness that allows us to sweep an HTLC output that we extended to a - party, but was never fulfilled. This HTLC output isn't directly on the - commitment transaction, but is the result of a confirmed second-level HTLC - transaction. As a result, we can only spend this after a CSV delay. - */ - HTLC_OFFERED_TIMEOUT_SECOND_LEVEL = 6; - - /* - A witness that allows us to sweep an HTLC output that was offered to us, and - for which we have a payment preimage. This HTLC output isn't directly on our - commitment transaction, but is the result of confirmed second-level HTLC - transaction. As a result, we can only spend this after a CSV delay. - */ - HTLC_ACCEPTED_SUCCESS_SECOND_LEVEL = 7; - - /* - A witness that allows us to sweep an HTLC that we offered to the remote - party which lies in the commitment transaction of the remote party. We can - spend this output after the absolute CLTV timeout of the HTLC as passed. - */ - HTLC_OFFERED_REMOTE_TIMEOUT = 8; - - /* - A witness that allows us to sweep an HTLC that was offered to us by the - remote party. We use this witness in the case that the remote party goes to - chain, and we know the pre-image to the HTLC. We can sweep this without any - additional timeout. - */ - HTLC_ACCEPTED_REMOTE_SUCCESS = 9; - - /* - A witness that allows us to sweep an HTLC from the remote party's commitment - transaction in the case that the broadcast a revoked commitment, but then - also immediately attempt to go to the second level to claim the HTLC. - */ - HTLC_SECOND_LEVEL_REVOKE = 10; - - /* - A witness type that allows us to spend a regular p2wkh output that's sent to - an output which is under complete control of the backing wallet. - */ - WITNESS_KEY_HASH = 11; - - /* - A witness type that allows us to sweep an output that sends to a nested P2SH - script that pays to a key solely under our control. - */ - NESTED_WITNESS_KEY_HASH = 12; - - /* - A witness type that allows us to spend our anchor on the commitment - transaction. - */ - COMMITMENT_ANCHOR = 13; -} - -message PendingSweep { - // The outpoint of the output we're attempting to sweep. - lnrpc.OutPoint outpoint = 1; - - // The witness type of the output we're attempting to sweep. - WitnessType witness_type = 2; - - // The value of the output we're attempting to sweep. - uint32 amount_sat = 3; - - /* - Deprecated, use sat_per_vbyte. - The fee rate we'll use to sweep the output, expressed in sat/vbyte. The fee - rate is only determined once a sweeping transaction for the output is - created, so it's possible for this to be 0 before this. - */ - uint32 sat_per_byte = 4 [deprecated = true]; - - // The number of broadcast attempts we've made to sweep the output. - uint32 broadcast_attempts = 5; - - /* - The next height of the chain at which we'll attempt to broadcast the - sweep transaction of the output. - */ - uint32 next_broadcast_height = 6; - - // The requested confirmation target for this output. - uint32 requested_conf_target = 8; - - // Deprecated, use requested_sat_per_vbyte. - // The requested fee rate, expressed in sat/vbyte, for this output. - uint32 requested_sat_per_byte = 9 [deprecated = true]; - - /* - The fee rate we'll use to sweep the output, expressed in sat/vbyte. The fee - rate is only determined once a sweeping transaction for the output is - created, so it's possible for this to be 0 before this. - */ - uint64 sat_per_vbyte = 10; - - // The requested fee rate, expressed in sat/vbyte, for this output. - uint64 requested_sat_per_vbyte = 11; - - /* - Whether this input must be force-swept. This means that it is swept even - if it has a negative yield. - */ - bool force = 7; -} - -message PendingSweepsRequest { -} - -message PendingSweepsResponse { - /* - The set of outputs currently being swept by lnd's central batching engine. - */ - repeated PendingSweep pending_sweeps = 1; -} - -message BumpFeeRequest { - // The input we're attempting to bump the fee of. - lnrpc.OutPoint outpoint = 1; - - // The target number of blocks that the input should be spent within. - uint32 target_conf = 2; - - /* - Deprecated, use sat_per_vbyte. - The fee rate, expressed in sat/vbyte, that should be used to spend the input - with. - */ - uint32 sat_per_byte = 3 [deprecated = true]; - - /* - Whether this input must be force-swept. This means that it is swept even - if it has a negative yield. - */ - bool force = 4; - - /* - The fee rate, expressed in sat/vbyte, that should be used to spend the input - with. - */ - uint64 sat_per_vbyte = 5; -} - -message BumpFeeResponse { -} - -message ListSweepsRequest { - /* - Retrieve the full sweep transaction details. If false, only the sweep txids - will be returned. Note that some sweeps that LND publishes will have been - replaced-by-fee, so will not be included in this output. - */ - bool verbose = 1; -} - -message ListSweepsResponse { - message TransactionIDs { - /* - Reversed, hex-encoded string representing the transaction ids of the - sweeps that our node has broadcast. Note that these transactions may - not have confirmed yet, we record sweeps on broadcast, not confirmation. - */ - repeated string transaction_ids = 1; - } - - oneof sweeps { - lnrpc.TransactionDetails transaction_details = 1; - TransactionIDs transaction_ids = 2; - } -} - -message LabelTransactionRequest { - // The txid of the transaction to label. - bytes txid = 1; - - // The label to add to the transaction, limited to 500 characters. - string label = 2; - - // Whether to overwrite the existing label, if it is present. - bool overwrite = 3; -} - -message LabelTransactionResponse { -} - -message FundPsbtRequest { - oneof template { - /* - Use an existing PSBT packet as the template for the funded PSBT. - - The packet must contain at least one non-dust output. If one or more - inputs are specified, no coin selection is performed. In that case every - input must be an UTXO known to the wallet that has not been locked - before. The sum of all inputs must be sufficiently greater than the sum - of all outputs to pay a miner fee with the specified fee rate. A change - output is added to the PSBT if necessary. - */ - bytes psbt = 1; - - /* - Use the outputs and optional inputs from this raw template. - */ - TxTemplate raw = 2; - } - - oneof fees { - /* - The target number of blocks that the transaction should be confirmed in. - */ - uint32 target_conf = 3; - - /* - The fee rate, expressed in sat/vbyte, that should be used to spend the - input with. - */ - uint64 sat_per_vbyte = 4; - } - - /* - The name of the account to fund the PSBT with. If empty, the default wallet - account is used. - */ - string account = 5; - - // The minimum number of confirmations each one of your outputs used for - // the transaction must satisfy. - int32 min_confs = 6; - - // Whether unconfirmed outputs should be used as inputs for the transaction. - bool spend_unconfirmed = 7; -} -message FundPsbtResponse { - /* - The funded but not yet signed PSBT packet. - */ - bytes funded_psbt = 1; - - /* - The index of the added change output or -1 if no change was left over. - */ - int32 change_output_index = 2; - - /* - The list of lock leases that were acquired for the inputs in the funded PSBT - packet. - */ - repeated UtxoLease locked_utxos = 3; -} - -message TxTemplate { - /* - An optional list of inputs to use. Every input must be an UTXO known to the - wallet that has not been locked before. The sum of all inputs must be - sufficiently greater than the sum of all outputs to pay a miner fee with the - fee rate specified in the parent message. - - If no inputs are specified, coin selection will be performed instead and - inputs of sufficient value will be added to the resulting PSBT. - */ - repeated lnrpc.OutPoint inputs = 1; - - /* - A map of all addresses and the amounts to send to in the funded PSBT. - */ - map outputs = 2; -} - -message UtxoLease { - /* - A 32 byte random ID that identifies the lease. - */ - bytes id = 1; - - // The identifying outpoint of the output being leased. - lnrpc.OutPoint outpoint = 2; - - /* - The absolute expiration of the output lease represented as a unix timestamp. - */ - uint64 expiration = 3; - - /* - The public key script of the leased output. - */ - bytes pk_script = 4; - - /* - The value of the leased output in satoshis. - */ - uint64 value = 5; -} - -message SignPsbtRequest { - /* - The PSBT that should be signed. The PSBT must contain all required inputs, - outputs, UTXO data and custom fields required to identify the signing key. - */ - bytes funded_psbt = 1; -} - -message SignPsbtResponse { - // The signed transaction in PSBT format. - bytes signed_psbt = 1; -} - -message FinalizePsbtRequest { - /* - A PSBT that should be signed and finalized. The PSBT must contain all - required inputs, outputs, UTXO data and partial signatures of all other - signers. - */ - bytes funded_psbt = 1; - - /* - The name of the account to finalize the PSBT with. If empty, the default - wallet account is used. - */ - string account = 5; -} -message FinalizePsbtResponse { - // The fully signed and finalized transaction in PSBT format. - bytes signed_psbt = 1; - - // The fully signed and finalized transaction in the raw wire format. - bytes raw_final_tx = 2; -} - -message ListLeasesRequest { -} - -message ListLeasesResponse { - // The list of currently leased utxos. - repeated UtxoLease locked_utxos = 1; -} +syntax = "proto3"; + +import "lightning.proto"; +import "signrpc/signer.proto"; + +package walletrpc; + +option go_package = "github.com/lightningnetwork/lnd/lnrpc/walletrpc"; + +// WalletKit is a service that gives access to the core functionalities of the +// daemon's wallet. +service WalletKit { + /* + ListUnspent returns a list of all utxos spendable by the wallet with a + number of confirmations between the specified minimum and maximum. By + default, all utxos are listed. To list only the unconfirmed utxos, set + the unconfirmed_only to true. + */ + rpc ListUnspent (ListUnspentRequest) returns (ListUnspentResponse); + + /* + 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`. + */ + rpc LeaseOutput (LeaseOutputRequest) returns (LeaseOutputResponse); + + /* + 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); + + /* + ListLeases lists all currently locked utxos. + */ + rpc ListLeases (ListLeasesRequest) returns (ListLeasesResponse); + + /* + DeriveNextKey attempts to derive the *next* key within the key family + (account in BIP43) specified. This method should return the next external + child within this branch. + */ + rpc DeriveNextKey (KeyReq) returns (signrpc.KeyDescriptor); + + /* + DeriveKey attempts to derive an arbitrary key specified by the passed + KeyLocator. + */ + rpc DeriveKey (signrpc.KeyLocator) returns (signrpc.KeyDescriptor); + + /* + NextAddr returns the next unused address within the wallet. + */ + rpc NextAddr (AddrRequest) returns (AddrResponse); + + /* + 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); + + /* + 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. + */ + rpc RequiredReserve (RequiredReserveRequest) + returns (RequiredReserveResponse); + + /* + 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 + derivation path m/). This may be required by some hardware wallets for + proper identification and signing. + + The address type can usually be inferred from the key's version, but may be + required for certain keys to map them into the proper scope. + + For BIP-0044 keys, an address type must be specified as we intend to not + support importing BIP-0044 keys into the wallet using the legacy + pay-to-pubkey-hash (P2PKH) scheme. A nested witness address type will force + the standard BIP-0049 derivation scheme, while a witness address type will + force the standard BIP-0084 derivation scheme. + + For BIP-0049 keys, an address type must also be specified to make a + distinction between the standard BIP-0049 address schema (nested witness + pubkeys everywhere) and our own BIP-0049Plus address schema (nested pubkeys + externally, witness pubkeys internally). + + NOTE: Events (deposits/spends) for keys derived from an account will only be + detected by lnd if they happen after the import. Rescans to detect past + events will be supported later on. + */ + rpc ImportAccount (ImportAccountRequest) returns (ImportAccountResponse); + + /* + ImportPublicKey imports a public key as watch-only into the wallet. + + NOTE: Events (deposits/spends) for a key will only be detected by lnd if + they happen after the import. Rescans to detect past events will be + supported later on. + */ + rpc ImportPublicKey (ImportPublicKeyRequest) + returns (ImportPublicKeyResponse); + + /* + 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 + chain. + */ + rpc PublishTransaction (Transaction) returns (PublishResponse); + + /* + SendOutputs is similar to the existing sendmany call in Bitcoind, and + allows the caller to create a transaction that sends to several outputs at + once. This is ideal when wanting to batch create a set of transactions. + */ + rpc SendOutputs (SendOutputsRequest) returns (SendOutputsResponse); + + /* + EstimateFee attempts to query the internal fee estimator of the wallet to + determine the fee (in sat/kw) to attach to a transaction in order to + achieve the confirmation target. + */ + rpc EstimateFee (EstimateFeeRequest) returns (EstimateFeeResponse); + + /* + 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 + transaction. + + NOTE: Some of the fields within PendingSweepsRequest are not guaranteed to + remain supported. This is an advanced API that depends on the internals of + the UtxoSweeper, so things may change. + */ + rpc PendingSweeps (PendingSweepsRequest) returns (PendingSweepsResponse); + + /* + 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 + together to save on transaction fees. Due to this, we cannot rely on + bumping the fee on a specific transaction, since transactions can change at + any point with the addition of new inputs. The list of inputs that + currently exist within lnd's central batching engine can be retrieved + through the PendingSweeps RPC. + + When bumping the fee of an input that currently exists within lnd's central + batching engine, a higher fee transaction will be created that replaces the + lower fee transaction through the Replace-By-Fee (RBF) policy. If it + + This RPC also serves useful when wanting to perform a Child-Pays-For-Parent + (CPFP), where the child transaction pays for its parent's fee. This can be + done by specifying an outpoint within the low fee transaction that is under + the control of the wallet. + + The fee preference can be expressed either as a specific fee rate or a delta + of blocks in which the output should be swept on-chain within. If a fee + preference is not explicitly specified, then an error is returned. + + Note that this RPC currently doesn't perform any validation checks on the + fee preference being provided. For now, the responsibility of ensuring that + the new fee preference is sufficient is delegated to the user. + */ + rpc BumpFee (BumpFeeRequest) returns (BumpFeeResponse); + + /* + 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); + + /* + 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. + */ + rpc LabelTransaction (LabelTransactionRequest) + returns (LabelTransactionResponse); + + /* + 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 + by passing in a raw TxTemplate message. + + If there are no inputs specified in the template, coin selection is + performed automatically. If the template does contain any inputs, it is + assumed that full coin selection happened externally and no additional + inputs are added. If the specified inputs aren't enough to fund the outputs + with the given fee rate, an error is returned. + + After either selecting or verifying the inputs, all input UTXOs are locked + with an internal app ID. + + NOTE: If this method returns without an error, it is the caller's + responsibility to either spend the locked UTXOs (by finalizing and then + publishing the transaction) or to unlock/release the locked UTXOs in case of + an error on the caller's side. + */ + rpc FundPsbt (FundPsbtRequest) returns (FundPsbtResponse); + + /* + SignPsbt expects a partial transaction with all inputs and outputs fully + declared and tries to sign all unsigned inputs that have all required fields + (UTXO information, BIP32 derivation information, witness or sig scripts) + set. + If no error is returned, the PSBT is ready to be given to the next signer or + to be finalized if lnd was the last signer. + + NOTE: This RPC only signs inputs (and only those it can sign), it does not + perform any other tasks (such as coin selection, UTXO locking or + input/output/fee value validation, PSBT finalization). Any input that is + incomplete will be skipped. + */ + rpc SignPsbt (SignPsbtRequest) returns (SignPsbtResponse); + + /* + 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 + non-witness inputs or inputs without UTXO information attached or inputs + without witness data that do not belong to lnd's wallet, this method will + fail. If no error is returned, the PSBT is ready to be extracted and the + final TX within to be broadcast. + + NOTE: This method does NOT publish the transaction once finalized. It is the + caller's responsibility to either publish the transaction on success or + unlock/release any locked UTXOs in case of an error in this method. + */ + rpc FinalizePsbt (FinalizePsbtRequest) returns (FinalizePsbtResponse); +} + +message ListUnspentRequest { + // The minimum number of confirmations to be included. + int32 min_confs = 1; + + // The maximum number of confirmations to be included. + int32 max_confs = 2; + + // An optional filter to only include outputs belonging to an account. + string account = 3; + + /* + When min_confs and max_confs are zero, setting false implicitly + overrides max_confs to be MaxInt32, otherwise max_confs remains + zero. An error is returned if the value is true and both min_confs + and max_confs are non-zero. (default: false) + */ + bool unconfirmed_only = 4; +} + +message ListUnspentResponse { + // A list of utxos satisfying the specified number of confirmations. + repeated lnrpc.Utxo utxos = 1; +} + +message LeaseOutputRequest { + /* + An ID of 32 random bytes that must be unique for each distinct application + using this RPC which will be used to bound the output lease to. + */ + bytes id = 1; + + // The identifying outpoint of the output being leased. + lnrpc.OutPoint outpoint = 2; + + // The time in seconds before the lock expires. If set to zero, the default + // lock duration is used. + uint64 expiration_seconds = 3; +} + +message LeaseOutputResponse { + /* + The absolute expiration of the output lease represented as a unix timestamp. + */ + uint64 expiration = 1; +} + +message ReleaseOutputRequest { + // The unique ID that was used to lock the output. + bytes id = 1; + + // The identifying outpoint of the output being released. + lnrpc.OutPoint outpoint = 2; +} + +message ReleaseOutputResponse { +} + +message KeyReq { + /* + Is the key finger print of the root pubkey that this request is targeting. + This allows the WalletKit to possibly serve out keys for multiple HD chains + via public derivation. + */ + int32 key_finger_print = 1; + + /* + The target key family to derive a key from. In other contexts, this is + known as the "account". + */ + int32 key_family = 2; +} + +message AddrRequest { + /* + The name of the account to retrieve the next address of. If empty, the + default wallet account is used. + */ + string account = 1; + + /* + The type of address to derive. + */ + AddressType type = 2; + + /* + Whether a change address should be derived. + */ + bool change = 3; +} +message AddrResponse { + /* + The address encoded using a bech32 format. + */ + string addr = 1; +} + +enum AddressType { + UNKNOWN = 0; + WITNESS_PUBKEY_HASH = 1; + NESTED_WITNESS_PUBKEY_HASH = 2; + HYBRID_NESTED_WITNESS_PUBKEY_HASH = 3; + TAPROOT_PUBKEY = 4; +} +message Account { + // The name used to identify the account. + string name = 1; + + /* + The type of addresses the account supports. + AddressType | External Branch | Internal Branch + --------------------------------------------------------------------- + WITNESS_PUBKEY_HASH | P2WPKH | P2WPKH + NESTED_WITNESS_PUBKEY_HASH | NP2WPKH | NP2WPKH + HYBRID_NESTED_WITNESS_PUBKEY_HASH | NP2WPKH | P2WPKH + */ + AddressType address_type = 2; + + /* + The public key backing the account that all keys are derived from + represented as an extended key. This will always be empty for the default + imported account in which single public keys are imported into. + */ + string extended_public_key = 3; + + /* + The fingerprint of the root key from which the account public key was + derived from. This will always be zero for the default imported account in + which single public keys are imported into. The bytes are in big-endian + order. + */ + bytes master_key_fingerprint = 4; + + /* + The derivation path corresponding to the account public key. This will + always be empty for the default imported account in which single public keys + are imported into. + */ + string derivation_path = 5; + + /* + The number of keys derived from the external branch of the account public + key. This will always be zero for the default imported account in which + single public keys are imported into. + */ + uint32 external_key_count = 6; + + /* + The number of keys derived from the internal branch of the account public + key. This will always be zero for the default imported account in which + single public keys are imported into. + */ + uint32 internal_key_count = 7; + + // Whether the wallet stores private keys for the account. + bool watch_only = 8; +} +message ListAccountsRequest { + // An optional filter to only return accounts matching this name. + string name = 1; + + // An optional filter to only return accounts matching this address type. + AddressType address_type = 2; +} +message ListAccountsResponse { + repeated Account accounts = 1; +} + +message RequiredReserveRequest { + // The number of additional channels the user would like to open. + uint32 additional_public_channels = 1; +} + +message RequiredReserveResponse { + // The amount of reserve required. + int64 required_reserve = 1; +} + +message ImportAccountRequest { + // A name to identify the account with. + string name = 1; + + /* + A public key that corresponds to a wallet account represented as an extended + key. It must conform to a derivation path of the form + m/purpose'/coin_type'/account'. + */ + string extended_public_key = 2; + + /* + The fingerprint of the root key (also known as the key with derivation path + m/) from which the account public key was derived from. This may be required + by some hardware wallets for proper identification and signing. The bytes + must be in big-endian order. + */ + bytes master_key_fingerprint = 3; + + /* + An address type is only required when the extended account public key has a + legacy version (xpub, tpub, etc.), such that the wallet cannot detect what + address scheme it belongs to. + */ + AddressType address_type = 4; + + /* + Whether a dry run should be attempted when importing the account. This + serves as a way to confirm whether the account is being imported correctly + by returning the first N addresses for the external and internal branches of + the account. If these addresses match as expected, then it should be safe to + import the account as is. + */ + bool dry_run = 5; +} +message ImportAccountResponse { + // The details of the imported account. + Account account = 1; + + /* + The first N addresses that belong to the external branch of the account. + The external branch is typically used for external non-change addresses. + These are only returned if a dry run was specified within the request. + */ + repeated string dry_run_external_addrs = 2; + + /* + The first N addresses that belong to the internal branch of the account. + The internal branch is typically used for change addresses. These are only + returned if a dry run was specified within the request. + */ + repeated string dry_run_internal_addrs = 3; +} + +message ImportPublicKeyRequest { + // A compressed public key represented as raw bytes. + bytes public_key = 1; + + // The type of address that will be generated from the public key. + AddressType address_type = 2; +} +message ImportPublicKeyResponse { +} + +message Transaction { + /* + The raw serialized transaction. + */ + bytes tx_hex = 1; + + /* + An optional label to save with the transaction. Limited to 500 characters. + */ + string label = 2; +} +message PublishResponse { + /* + If blank, then no error occurred and the transaction was successfully + published. If not the empty string, then a string representation of the + broadcast error. + + TODO(roasbeef): map to a proper enum type + */ + string publish_error = 1; +} + +message SendOutputsRequest { + /* + The number of satoshis per kilo weight that should be used when crafting + this transaction. + */ + int64 sat_per_kw = 1; + + /* + A slice of the outputs that should be created in the transaction produced. + */ + repeated signrpc.TxOut outputs = 2; + + // An optional label for the transaction, limited to 500 characters. + string label = 3; + + // The minimum number of confirmations each one of your outputs used for + // the transaction must satisfy. + int32 min_confs = 4; + + // Whether unconfirmed outputs should be used as inputs for the transaction. + bool spend_unconfirmed = 5; +} +message SendOutputsResponse { + /* + The serialized transaction sent out on the network. + */ + bytes raw_tx = 1; +} + +message EstimateFeeRequest { + /* + The number of confirmations to shoot for when estimating the fee. + */ + int32 conf_target = 1; +} +message EstimateFeeResponse { + /* + The amount of satoshis per kw that should be used in order to reach the + confirmation target in the request. + */ + int64 sat_per_kw = 1; +} + +enum WitnessType { + UNKNOWN_WITNESS = 0; + + /* + A witness that allows us to spend the output of a commitment transaction + after a relative lock-time lockout. + */ + COMMITMENT_TIME_LOCK = 1; + + /* + A witness that allows us to spend a settled no-delay output immediately on a + counterparty's commitment transaction. + */ + COMMITMENT_NO_DELAY = 2; + + /* + A witness that allows us to sweep the settled output of a malicious + counterparty's who broadcasts a revoked commitment transaction. + */ + COMMITMENT_REVOKE = 3; + + /* + A witness that allows us to sweep an HTLC which we offered to the remote + party in the case that they broadcast a revoked commitment state. + */ + HTLC_OFFERED_REVOKE = 4; + + /* + A witness that allows us to sweep an HTLC output sent to us in the case that + the remote party broadcasts a revoked commitment state. + */ + HTLC_ACCEPTED_REVOKE = 5; + + /* + A witness that allows us to sweep an HTLC output that we extended to a + party, but was never fulfilled. This HTLC output isn't directly on the + commitment transaction, but is the result of a confirmed second-level HTLC + transaction. As a result, we can only spend this after a CSV delay. + */ + HTLC_OFFERED_TIMEOUT_SECOND_LEVEL = 6; + + /* + A witness that allows us to sweep an HTLC output that was offered to us, and + for which we have a payment preimage. This HTLC output isn't directly on our + commitment transaction, but is the result of confirmed second-level HTLC + transaction. As a result, we can only spend this after a CSV delay. + */ + HTLC_ACCEPTED_SUCCESS_SECOND_LEVEL = 7; + + /* + A witness that allows us to sweep an HTLC that we offered to the remote + party which lies in the commitment transaction of the remote party. We can + spend this output after the absolute CLTV timeout of the HTLC as passed. + */ + HTLC_OFFERED_REMOTE_TIMEOUT = 8; + + /* + A witness that allows us to sweep an HTLC that was offered to us by the + remote party. We use this witness in the case that the remote party goes to + chain, and we know the pre-image to the HTLC. We can sweep this without any + additional timeout. + */ + HTLC_ACCEPTED_REMOTE_SUCCESS = 9; + + /* + A witness that allows us to sweep an HTLC from the remote party's commitment + transaction in the case that the broadcast a revoked commitment, but then + also immediately attempt to go to the second level to claim the HTLC. + */ + HTLC_SECOND_LEVEL_REVOKE = 10; + + /* + A witness type that allows us to spend a regular p2wkh output that's sent to + an output which is under complete control of the backing wallet. + */ + WITNESS_KEY_HASH = 11; + + /* + A witness type that allows us to sweep an output that sends to a nested P2SH + script that pays to a key solely under our control. + */ + NESTED_WITNESS_KEY_HASH = 12; + + /* + A witness type that allows us to spend our anchor on the commitment + transaction. + */ + COMMITMENT_ANCHOR = 13; +} + +message PendingSweep { + // The outpoint of the output we're attempting to sweep. + lnrpc.OutPoint outpoint = 1; + + // The witness type of the output we're attempting to sweep. + WitnessType witness_type = 2; + + // The value of the output we're attempting to sweep. + uint32 amount_sat = 3; + + /* + Deprecated, use sat_per_vbyte. + The fee rate we'll use to sweep the output, expressed in sat/vbyte. The fee + rate is only determined once a sweeping transaction for the output is + created, so it's possible for this to be 0 before this. + */ + uint32 sat_per_byte = 4 [deprecated = true]; + + // The number of broadcast attempts we've made to sweep the output. + uint32 broadcast_attempts = 5; + + /* + The next height of the chain at which we'll attempt to broadcast the + sweep transaction of the output. + */ + uint32 next_broadcast_height = 6; + + // The requested confirmation target for this output. + uint32 requested_conf_target = 8; + + // Deprecated, use requested_sat_per_vbyte. + // The requested fee rate, expressed in sat/vbyte, for this output. + uint32 requested_sat_per_byte = 9 [deprecated = true]; + + /* + The fee rate we'll use to sweep the output, expressed in sat/vbyte. The fee + rate is only determined once a sweeping transaction for the output is + created, so it's possible for this to be 0 before this. + */ + uint64 sat_per_vbyte = 10; + + // The requested fee rate, expressed in sat/vbyte, for this output. + uint64 requested_sat_per_vbyte = 11; + + /* + Whether this input must be force-swept. This means that it is swept even + if it has a negative yield. + */ + bool force = 7; +} + +message PendingSweepsRequest { +} + +message PendingSweepsResponse { + /* + The set of outputs currently being swept by lnd's central batching engine. + */ + repeated PendingSweep pending_sweeps = 1; +} + +message BumpFeeRequest { + // The input we're attempting to bump the fee of. + lnrpc.OutPoint outpoint = 1; + + // The target number of blocks that the input should be spent within. + uint32 target_conf = 2; + + /* + Deprecated, use sat_per_vbyte. + The fee rate, expressed in sat/vbyte, that should be used to spend the input + with. + */ + uint32 sat_per_byte = 3 [deprecated = true]; + + /* + Whether this input must be force-swept. This means that it is swept even + if it has a negative yield. + */ + bool force = 4; + + /* + The fee rate, expressed in sat/vbyte, that should be used to spend the input + with. + */ + uint64 sat_per_vbyte = 5; +} + +message BumpFeeResponse { +} + +message ListSweepsRequest { + /* + Retrieve the full sweep transaction details. If false, only the sweep txids + will be returned. Note that some sweeps that LND publishes will have been + replaced-by-fee, so will not be included in this output. + */ + bool verbose = 1; +} + +message ListSweepsResponse { + message TransactionIDs { + /* + Reversed, hex-encoded string representing the transaction ids of the + sweeps that our node has broadcast. Note that these transactions may + not have confirmed yet, we record sweeps on broadcast, not confirmation. + */ + repeated string transaction_ids = 1; + } + + oneof sweeps { + lnrpc.TransactionDetails transaction_details = 1; + TransactionIDs transaction_ids = 2; + } +} + +message LabelTransactionRequest { + // The txid of the transaction to label. + bytes txid = 1; + + // The label to add to the transaction, limited to 500 characters. + string label = 2; + + // Whether to overwrite the existing label, if it is present. + bool overwrite = 3; +} + +message LabelTransactionResponse { +} + +message FundPsbtRequest { + oneof template { + /* + Use an existing PSBT packet as the template for the funded PSBT. + + The packet must contain at least one non-dust output. If one or more + inputs are specified, no coin selection is performed. In that case every + input must be an UTXO known to the wallet that has not been locked + before. The sum of all inputs must be sufficiently greater than the sum + of all outputs to pay a miner fee with the specified fee rate. A change + output is added to the PSBT if necessary. + */ + bytes psbt = 1; + + /* + Use the outputs and optional inputs from this raw template. + */ + TxTemplate raw = 2; + } + + oneof fees { + /* + The target number of blocks that the transaction should be confirmed in. + */ + uint32 target_conf = 3; + + /* + The fee rate, expressed in sat/vbyte, that should be used to spend the + input with. + */ + uint64 sat_per_vbyte = 4; + } + + /* + The name of the account to fund the PSBT with. If empty, the default wallet + account is used. + */ + string account = 5; + + // The minimum number of confirmations each one of your outputs used for + // the transaction must satisfy. + int32 min_confs = 6; + + // Whether unconfirmed outputs should be used as inputs for the transaction. + bool spend_unconfirmed = 7; +} +message FundPsbtResponse { + /* + The funded but not yet signed PSBT packet. + */ + bytes funded_psbt = 1; + + /* + The index of the added change output or -1 if no change was left over. + */ + int32 change_output_index = 2; + + /* + The list of lock leases that were acquired for the inputs in the funded PSBT + packet. + */ + repeated UtxoLease locked_utxos = 3; +} + +message TxTemplate { + /* + An optional list of inputs to use. Every input must be an UTXO known to the + wallet that has not been locked before. The sum of all inputs must be + sufficiently greater than the sum of all outputs to pay a miner fee with the + fee rate specified in the parent message. + + If no inputs are specified, coin selection will be performed instead and + inputs of sufficient value will be added to the resulting PSBT. + */ + repeated lnrpc.OutPoint inputs = 1; + + /* + A map of all addresses and the amounts to send to in the funded PSBT. + */ + map outputs = 2; +} + +message UtxoLease { + /* + A 32 byte random ID that identifies the lease. + */ + bytes id = 1; + + // The identifying outpoint of the output being leased. + lnrpc.OutPoint outpoint = 2; + + /* + The absolute expiration of the output lease represented as a unix timestamp. + */ + uint64 expiration = 3; + + /* + The public key script of the leased output. + */ + bytes pk_script = 4; + + /* + The value of the leased output in satoshis. + */ + uint64 value = 5; +} + +message SignPsbtRequest { + /* + The PSBT that should be signed. The PSBT must contain all required inputs, + outputs, UTXO data and custom fields required to identify the signing key. + */ + bytes funded_psbt = 1; +} + +message SignPsbtResponse { + // The signed transaction in PSBT format. + bytes signed_psbt = 1; +} + +message FinalizePsbtRequest { + /* + A PSBT that should be signed and finalized. The PSBT must contain all + required inputs, outputs, UTXO data and partial signatures of all other + signers. + */ + bytes funded_psbt = 1; + + /* + The name of the account to finalize the PSBT with. If empty, the default + wallet account is used. + */ + string account = 5; +} +message FinalizePsbtResponse { + // The fully signed and finalized transaction in PSBT format. + bytes signed_psbt = 1; + + // The fully signed and finalized transaction in the raw wire format. + bytes raw_final_tx = 2; +} + +message ListLeasesRequest { +} + +message ListLeasesResponse { + // The list of currently leased utxos. + repeated UtxoLease locked_utxos = 1; +}