├── .DS_Store
├── images
├── lnurl.png
├── balancedopen.jpg
└── helpcommand.jpg
├── .vscode
└── settings.json
├── LICENSE
└── README.md
/.DS_Store:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/niteshbalusu11/BOS-Commands-Document/HEAD/.DS_Store
--------------------------------------------------------------------------------
/images/lnurl.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/niteshbalusu11/BOS-Commands-Document/HEAD/images/lnurl.png
--------------------------------------------------------------------------------
/images/balancedopen.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/niteshbalusu11/BOS-Commands-Document/HEAD/images/balancedopen.jpg
--------------------------------------------------------------------------------
/images/helpcommand.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/niteshbalusu11/BOS-Commands-Document/HEAD/images/helpcommand.jpg
--------------------------------------------------------------------------------
/.vscode/settings.json:
--------------------------------------------------------------------------------
1 | {
2 | "editor.defaultFormatter": "esbenp.prettier-vscode",
3 | "editor.formatOnSaveMode": "modifications"
4 | }
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | MIT License
2 |
3 | Copyright (c) 2021 Nitesh Balusu
4 |
5 | Permission is hereby granted, free of charge, to any person obtaining a copy
6 | of this software and associated documentation files (the "Software"), to deal
7 | in the Software without restriction, including without limitation the rights
8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 |
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 |
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # Balance of Satoshis Commands
2 |
3 | **This document helps with BOS Commands:**
4 |
5 | ### **Updated until version `19.1.1`**
6 |
7 |
8 | Most bos commands follow the following format.
9 | `bos CommandName Argument --Flag` or `bos CommandName --Flag` or `bos CommandName Option --Flag`if a command does not have an argument.
10 | **Arguments are always mandatory, options and flags are optional.**
11 |
12 |
13 | 1. `bos` or `bos --help` or `bos -h`: This brings up the help menu with the list of all BOS Commands
14 | 2. `bos --version` or `bos -V`: Shows the current version of BOS
15 | 3. `bos help CommandName` or `bos CommandName --help` or `bos CommandName -h`: Displays help section and usage of each command. Example usage `bos help peers`
16 | 4. All bos commands can use a node flag that can be used to call any saved node you might have saved in the `~/.bos` directory. If you have multiple nodes you can remotely control your node from bos. Example: `bos peers --node=alice` where alice is the name of your saved node.
17 |
18 | ### **Always double check with `bos commandName -h` before running a command**
19 |
20 |
21 | If this guide was of help and you want to share some ❤️, please feel free to send a ⚡ tip to the ⚡ address: `nitesh@noderunner.wtf`
22 |
23 | 
24 |
25 | ## Commands List
26 |
27 | - [accounting](#accounting) - Do accounting on your node
28 | - [advertise](#advertise) - Send keysend advertisements to the network
29 | - [balance](#balance) - Shows offchain and onchain balances
30 | - [cert-validity-days](#cert-validity-days) - Shows your certificate validity
31 | - [chain-deposit](#chain-deposit) - Deposit funds on your on-chain wallet
32 | - [chainfees](#chainfees) - Shows current on-chain fees
33 | - [chart-chain-fees](#chart-chain-fees) - On-chain fees you paid
34 | - [chart-fees-earned](#chart-fees-earned) - Routing fees you earned
35 | - [chart-fees-paid](#chart-fees-paid) - Routing fees you paid
36 | - [chart-payments-received](#chart-payments-received) - Payments you received
37 | - [clean-failed-payments](#clean-failed-payments) - Clean failed payments like probes (works with lnd 0.14.0+ only)
38 | - [closed](#closed) - Lists your closed channels
39 | - [create-channel-group](#create-channel-group) - Coordinate balanced channels group
40 | - [credentials](#credentials) - Generates credentials for your node
41 | - [fees](#fees) - Set fees to your channels
42 | - [find](#find) - Query a string
43 | - [forwards](#forwards) - List your forwards and fees earned
44 | - [fund](#fund) - Fund an onchain address
45 | - [get-inbound-channel](#get-inbound-channel) - Buy an inbound channel from a node using LSPS1 protocol
46 | - [graph](#graph) - Get node information from a graph
47 | - [inbound-channel-rules](#inbound-channel-rules) - Set rules for nodes to open channels to you
48 | - [inbound-liquidity](#inbound-liquidity) - Shows your inbound liquidity
49 | - [increase-inbound-liquidity](#increase-inbound-liquidity) - Increase inbound liquidity by looping out
50 | - [increase-outbound-liquidity](#increase-outbound-liquidity) - Increase outbound liquidity by opening channels
51 | - [invoice](#invoice) - Create an invoice and get a BOLT 11 payment request
52 | - [limit-forwarding](#limit-forwarding) - Add restrictions to forwardind through your node
53 | - [lnurl](#lnurl) - Lets you perform a list of LNUrl functions
54 | - [nodes](#nodes) - Configure a saved node
55 | - [offer-channel-open](#offer-channel-open) - Sell a channel to a node using LSPS1 protocol
56 | - [open](#open) - Open channels to nodes
57 | - [open-balanced-channel](#open-balanced-channel) - Open a balanced channel with a node
58 | - [open-group-channel](#open-group-channel) - Open balanced channels with multiple peers
59 | - [outbound-liquidity](#outbound-liquidity) - Shows your outbound liquidity
60 | - [pay](#pay) - Pay a payment request
61 | - [peers](#peers) - Displays your peers
62 | - [price](#price) - Current BTC Price
63 | - [probe](#probe) - Probes a node with junk payments
64 | - [rebalance](#rebalance) - Rebalance your channels
65 | - [reconnect](#reconnect) - Attempt to reconnect to disconnected peers
66 | - [remove-peer](#remove-peer) - Close a channel with a peer
67 | - [send](#send) - Keysend payment to a node
68 | - [swap](#swap) - Do a submarine swap with a node
69 | - [tags](#tags) - Create tags for categorizing nodes
70 | - [telegram](#telegram) - Connect bos to a telegram bot to receive updates from your node
71 | - [trade-secret](#trade-secret) - Trade between peers by encoding and decoding a secret
72 | - [utxos](#utxos) - Displays your UTXOs
73 |
74 |
75 |
76 | ## Secret Commands List
77 |
78 | - [delete-payments-history](#delete-payments-history) - Delete all your payment history
79 | - [gift](#gift) - Gift a peer routing fees
80 | - [encrypt](#encrypt) - Encrypt data with a public key
81 | - [decrypt](#decrypt) - Decrypt data with a public key
82 | - [recover-p2pk](#recover-p2pk) - Sweep onchain funds sent to a public key
83 |
84 |
85 |
86 | ## Commands:
87 |
88 | ### accounting
89 |
90 | There are 6 different categories for accounting:
91 |
92 | - Arguments:
93 | - `chain-fees`: All on-chain fees paid, example channel opens and closures.
94 | - `chain-receives`: All onchain payments you receive including any from channel closures.
95 | - `chain-sends`: Any onchain payments you made.
96 | - `forwards`: Fees you earned from routing payments
97 | - `invoices`: any invoices settled
98 | - `payments`: any payments made on the LN including keysends.
99 | - Usage example: `bos accounting chain-fees`. Displays amounts spent on chain-fees in a table.
100 | - Flags:
101 | - `csv`: outputs the accounting results to a csv file: Example: `bos accounting chain-fees --csv > chainfees.csv`
102 | - `date`: Pick a date with in the month.
103 | - `disable-fiat`: Disables the usage of fiat in accounting, it defaults to sats as the unit of account.
104 | - `month`: select the month number to get accounting only for that specific month. `bos accounting forwards --month 8` returns results for August.
105 | - `rate-provider`: BOS provides two rate providers, coindesk and coingecko to provide accounting in fiat, this flag is defaulted to coindesk. To switch provider if the default provider is down or results take too long to pop-up use `bos accounting forwards --rate-provider coingecko`
106 | - `year`: returns accounting results for a specifc year, it can be used in combination with month or separately to display results for the entire year. `bos accounting payments --month 10 --year 2021`
107 | - Flags can be used together, example: `bos accounting forwards --month 10 --day 15 --disable-fiat`
108 |
109 |
110 |
111 | ### advertise
112 |
113 | Send keysend advertisements to the network.
114 |
115 | - Flags:
116 | - `budget`: Max budget amount you want to spend for advertising
117 | - `dryrun`: Avoid sending advertisements and only calculate estimate
118 | - `filter`: Pass an expression for nodes matching a certain condition
119 | - `max-hops`: Maximum hops you want to target the advertisement. max-hops=0 is your peers only.
120 | - `min-hops`: Minimum hops you want to target the advertisement.
121 | - `tag`: Advertise to a tag, check `tags` command to learn how to setup tags.
122 |
123 | Example: `bos advertise --budget 3000 --max-hops 2`
124 |
125 |
126 |
127 | ### balance
128 |
129 | Gives total balance of on-chain, off-chain, pending and commit fees.
130 |
131 | - Flags:
132 | - `above`: Returns balance above a certain number, `bos balance --above 10000`
133 | - `below`: Returns balance below a certain number, `bos balance --below 10000`
134 | - `confirmed`: Returns confirmed balance only. Removes any pending funds.
135 | - `detailed`: Returns detailed balance, a break down of offchain and onchain
136 | - `offchain`: Returns offchain balance only, amount on channels.
137 | - `onchain`: Returns onchain balance only, amount in your LND onchain wallet.
138 |
139 | Example: `bos balance --onchain --confirmed`
140 |
141 |
142 |
143 | ### cert-validity-days
144 |
145 | Returns how many days your certificate is valid.
146 |
147 | - Flags:
148 | - `below`: returns number of days below a certain number
149 |
150 | Example: `bos cert-validity-days --below 10`
151 |
152 |
153 |
154 | ### chain-deposit
155 |
156 | Generates address and QR code to deposit funds to your onchain wallet.
157 |
158 | - Options:
159 | - `amount`: generate an address to deposit a specific amount. `bos chain-deposit 100000`.
160 | - Flags:
161 | - `format`: set the address format, supported options are np2wpkh, p2wpkh, p2tr (default).
162 | - `fresh`: generates a fresh address every time.
163 |
164 |
165 | Example: `bos chain-deposit` or `bos chain-deposit 100000 --format p2tr`
166 |
167 |
168 |
169 | ### chainfees
170 |
171 | Gives you an estimate of the chain-fees for various confirmation targets
172 |
173 | - Flags:
174 | - `blocks`: Fees estimate based on block confirmation target
175 | - `file`: Enter path to a JSON file to write the output of the command to.
176 |
177 | Example: `bos chainfees --blocks 10 --file /home/umbrel/blocks.json`
178 |
179 |
180 |
181 | ### chart-chain-fees
182 |
183 | Gives you a chart and total onchain fees you paid in the last 60 days (default and can be changed)
184 |
185 | - Flags:
186 | - `days`: Produces a chart for the last N number of days specified.
187 | - `end`: End date for the chart.
188 | - `start`: Start date for the chart.
189 |
190 | Example: `bos chart-chain-fees --days 90`
191 | Example: `bos chart-chain-fees --start 2022-06-01 --end 2022-06-30`
192 |
193 |
194 |
195 | ### chart-fees-earned
196 |
197 | Gives you a chart and total routing fees you earned in the last 60 days (default and can be changed)
198 |
199 | - Options:
200 | - `pubkey`: Enter the pubkey of for the peer to get the routing fees earned via a specific peer.
201 | - `tag`: Enter a `bos tag` that returns results earned via peers in the tag
202 | - Flags:
203 | - `count`: Give you a count of the number of forwards instead of sats
204 | - `days`: Produces a chart for the last N number of days specified.
205 | - `end`: End date for the chart.
206 | - `start`: Start date for the chart.
207 |
208 | Example: `bos chart-chain-earned --days 90`
209 |
210 |
211 |
212 | ### chart-fees-paid
213 |
214 | Gives you a chart and total routing fees you paid in the last 60 days (default and can be changed)
215 |
216 | - Flags:
217 | - `days`: Produces a chart for the last N number of days specified.
218 | - `end`: End date for the chart
219 | - `in`: Takes a public key/alias and charts fees paid coming into that node.
220 | - `most-fees`: Gives a table for fees paid per peer/network.
221 | - `most-forwarded`: Gives a table for amount forwarded per peer.
222 | - `network`: Fees paid to the network who are not your peers, example are other hops in a rebalance or a payment you made.
223 | - `node`: Gives a table of the fees for the node specified.
224 | - `out`: Takes a public key/alias and charts fees paid out through a node.
225 | - `peers`: Fees paid only to your peers excluding the others in the network
226 | - `rebalances`: shows only fees paid for rebalances or payments made to yourself
227 | - `start`: Start date for the chart
228 |
229 | Example: `bos chart-fees-paid --days 15 --rebalances`
230 |
231 | Example: `bos chart-fees-paid --most-forwarded --days 30`
232 |
233 |
234 | ### chart-payments-received
235 |
236 | Gives you a chart of all payments received on your node like keysends and settled invoices.
237 |
238 | - Flags:
239 | - `count`: Show count of settled instead of amount received
240 | - `days`: Produces a chart for the last N number of days specified
241 | - `end`: End date for the chart.
242 | - `for`: Only consider payments including a specific query
243 | - `start`: Start date for the chart.
244 |
245 | Example: `bos chart-payments-received --days 15`
246 | Example: `bos chart-payments-received --start 2022-06-01 --end 2022-06-30`
247 |
248 |
249 |
250 | ### clean-failed-payments
251 |
252 | Cleans all failed payments on your node like probes, helps reduce your channel.db size. Works with lnd 0.14.0-beta and above only.
253 | bos also deletes failed payments on the fly if you're on lnd 0.14.0-beta or above.
254 |
255 | - Flags:
256 | - `dryrun`: Calculates and gives you an output of the number of failed payments. (dryrun flag works with versions of lnd below 0.14.0-beta)
257 |
258 | Example: `bos clean-failed-payments`
259 |
260 |
261 |
262 | ### closed
263 |
264 | Returns a list of confirmed channel closures.
265 |
266 | - Flags:
267 | - `limit`: Limits the number of records returned.
268 |
269 | Example: `bos closed --limit 20`
270 |
271 |
272 |
273 |
274 | ### create-channel-group
275 | Coordinate balanced channels group.
276 |
277 | - Flags:
278 | `allow`: Only allow a list of certain public keys to join a group and also specify the order of the group.
279 | `capacity`: Specify the total channel capacity of all the channels in the group.
280 | `fee-rate`: Specify the fee rate of the group open.
281 | `size`: Specify the size of the group.
282 |
283 | Example: `bos create-channel-group --allow pubkey1 --allow pubkey2 --size 3 --capacity 10000000`
284 |
285 |
286 |
287 | ### credentials
288 |
289 | Outputs credentials to access your node. Needs to be used in combination with `bos nodes --add`. Running the command without any flag will ask you a question to enter a pubkey to transfer the credentials in an encrypted way.
290 |
291 | - Flags:
292 | - `cleartext`: Outputs a cleartext format of macaroon, cert and socket and the credentials expire with default number of 365 days
293 | - `days`: Sets the number of days the credentials produced expire in
294 | - `readonly`: Outputs credentials that can only be used for read only
295 | - `nospend`: Outputs credentials that do not let you spend funds on the node
296 |
297 | Example: `bos credentials --cleartext --days 200 --readonly`
298 |
299 |
300 |
301 | ### fees
302 |
303 | Gives a chart of fees rates set per peer. Base fees is not included.
304 |
305 | - Flags:
306 | - `set-fee-rate`: Lets you set fee rate in ppm, you can use this set fee rate to a channel that is pending open, this requires the SSH session to be open while it attempts to set fees until the channel opens
307 | - `to`: Specify the public key of the peer you want to set fee rate to, multiple public keys can be passed.
308 |
309 | Example: `bos fees --set-fee-rate 1000 --to pubkey1 --to pubkey2`
310 |
311 |
312 |
313 | ### find
314 |
315 | Lets you find something that is stored in the data base, like a transaction, payment information, peer info, channel information etc.
316 |
317 | - Arguments:
318 | - Takes differnt kinds arguments:
319 |
320 | Example: `bos find 703539x1305x0` OR `bos find Bitrefill` OR `bos find 02816caed43171d3c9854e3b0ab2cf0c42be086ff1bd4005acc2a5f7db70d83774`
321 | Find now also returns the size a channel is taking up on the db when you search with Alias or pubkey
322 |
323 |
324 |
325 | ### forwards
326 |
327 | Outputs a chart of forwards that took place from both inbound and outbound peers.
328 |
329 | - Flags:
330 | - `days`: Table view only shows forwards per peer for the last N number of days selected
331 | - `complete`: Shows complete results in a non table format
332 | - `sort`: Allows you to sort the table output by earnings or liquidity
333 |
334 | Example: `bos forwards --days 15 --sort="earned_out"`
335 |
336 |
337 |
338 | ### fund
339 |
340 | Lets you make a signed transaction to an address and a specific amount to spend your onchain funds.
341 |
342 | - Arguments:
343 | - `address`: Enter the address you're funding.
344 | - `amount`: Enter the amount you're funding.
345 | - Flags:
346 | - `dryrun`: Does a dryrun and prevents your funds (UTXOs) from getting locked.
347 | - `utxo`: Enter a specific tx_id:vout that you want to use to fund. Unconfirmed UTXOs are allowed.
348 | - `select-utxos`: Opens an interactive view to select your spendable UTXOs, use "Space" to select a UTXO and hit "Enter" when done.
349 | - `fee-rate`: Set onchain fee rate for the funding transaction in sats/vByte.
350 | - `broadcast`: Broadcasts the transaction to the network.
351 |
352 | Example: `bos fund addressToFund amountToFund --select-utxos --fee-rate 1`
353 |
354 |
355 |
356 | ### get-inbound-channel
357 |
358 | Buy an inbound channel from a node using [LSPS1](https://github.com/BitcoinAndLightningLayerSpecs/lsp/tree/main/LSPS1) protocol.
359 |
360 | - Arguments:
361 | - `pubkey`: Enter the pubkey of the node you want to buy an inbound channel from. (Optional) If it's not specified, you will query the lightning network to find nodes that are offering inbound channels using LSPS1.
362 |
363 | - Flags:
364 | - `amount`: Set the amount of inbound capacity you want to buy. (default: 5,000,000 sats)
365 | - `days`: Minimum number of days you want the channel to be open for. The expected lifetime of the channel.
366 | - `dryrun`: Request a quote from the node selling the channel.
367 | - `max-wait-hours`: Set the maximum number of hours you want to wait for the channel to be open. (default: 40 hours)
368 | - `receovery`: Check the status of an open or closed order using the order id.
369 | - `type`: Set the type of channel you want to buy (public/private). (default: public)
370 |
371 | Example: `bos get-inbound-channel --amount 1000000 --days 10 --max-wait-hours 20 --type private`
372 |
373 |
374 |
375 |
376 | ### graph
377 |
378 | Returns a list of connections and other public information of a node.
379 |
380 | - Arguments:
381 | - Takes `pubkey` or `alias` as an option to return output.
382 | - Flags:
383 | - `filter`: Set a filter to filter returned results, example `--filter CAPACITY>1000000` returns channels with peers greater than 1M capacity.
384 | - `sort`: Sorts the rows in the table by the column specified. example `--sort out_fee`
385 |
386 | Example: `bos graph Bitrefill --sort in_fee`
387 |
388 |
389 |
390 | ### inbound-channel-rules
391 |
392 | Sets rules for other peers to open channels to you. It takes formulas as the as the rule.
393 |
394 | - Flags:
395 | - `rule`: Select the rule you want to set, examples are `CAPACITY>5000000` to only allow inbound channels of more than 5M capacity. `CAPACITIES>100*M` to only allow an inbound channel if the peer has a total of 1BTC capacity from all public channels put together. Other examples include `CHANNEL_AGES`, `FEE_RATES`, `LOCAL_BALANCE`, `PUBLIC_KEY`, `PRIVATE`, `TOR`, `CLEARNET`, `OBSOLETE`, `JOINT_PUBLIC_CAPACITY` etc.
396 | - `TOR` and `CLEARNET` let you control if you want to accept inbound channels from TOR or CLEARNET peers.
397 | - `OBSELETE` lets you control if you want to accept inbound channels from peers that are opening a channels to you with a legacy channel type.
398 | - `JOIN_PUBLIC_CAPACITY` is the sum of capacities of all public channels between you and the requesting peer.
399 | - `reason` sends back a reason message when rejecting an inbound channel.
400 | - `coop-close-address`: Listens to inbound channel open requests and intercepts them to add a cooperative closing address to send funds to when the channel to closed. Can be repeatable and it will cycle through the addresses.
401 |
402 | Example: `bos inbound-channel-rules --rule CAPACITY>=5000000 --reason "Will only accept a minimum 5M inbound channel"`
403 |
404 |
405 |
406 | ### inbound-liquidity
407 |
408 | Returns your total inbound liquidity you currently have
409 |
410 | - Flags:
411 | - `above` returns tokens above a number you specify
412 | - `below` returns tokens below a number you specify
413 | - `min-score` set a minimum fee rate filter
414 | - `max-fee-rate` set a maximum fee rate filter
415 | - `top` returns liquidity in the top percentile for an individual channel
416 | - `with` use a `bos tag` to view inbound liquidity with peers in a tag
417 |
418 | Example: `bos inbound-liquidity` or `bos inbound-liquidity --max-fee-rate 200`
419 |
420 |
421 |
422 | ### increase-inbound-liquidity
423 |
424 | Helps increase your inbound liquidity by doing a loop out.
425 |
426 | - Flags:
427 | - `address`: you can specify an external address to send the looped out onchain funds to
428 | - `api-key`: specify a prepaid API key to use
429 | - `avoid`: avoid certain pubkeys or channels IDs while taking the path to LOOP. You can use this with `bos tags` and set an avoid tag
430 | - `confs`: Number of onchain confirmations to consider you have received the funds successfully, defaulted to 1
431 | - `dryrun`: Does not actually loop out but can give you an estimation of how much amount can be looped out and how much it would cost in routing fees
432 | - `fast`: Request LOOP server to avoid batching your onchain transaction
433 | - `amount`: amount you want to increase inbound liquidity by
434 | - `max-fee`: max fees you're willing to pay in total for the swap
435 | - `recover`: you can use the recovery key provided by bos to recover funds in an in-progress swap
436 | - `set-fee-rate`: Set a fee rate to the channel once the channel opens
437 | - `with`: specify the pubkey of the peer you want to increase inbound liquidity for
438 |
439 | Example: `bos increase-inbound-liquidity --with yourPeerPubkey --max-fee 2000 --dryrun`
440 |
441 |
442 |
443 | ### increase-outbound-liquidity
444 |
445 | Opens a new channel to increase your outbound liquidity. If you don't specify `with` flag, BOS chooses a peer for you to open a channel to.
446 |
447 | - Flags:
448 | - `amount`: amount to increase liquidity
449 | - `fee-rate`: set channel open fee rate (sats/vByte)
450 | - `private`: opens a private channel
451 | - `with`: enter the pubkey to open channel with
452 | - `dryrun`: avoids opening the channel but gives you a summary of the channel open
453 |
454 | Example: `bos increase-outbound-liquidity --with yourPeerPubkey --fee-rate 1 --dryrun`
455 |
456 |
457 |
458 |
459 | ### invoice
460 | Create an invoice and get a BOLT 11 payment request
461 |
462 | - Arguments:
463 | - `amount`: Amount in sats/fiat (USD/EUR)
464 |
465 | - Flags:
466 | `for`: Add a description for the invoice.
467 | `hours`: Number of hours the invoice expires.
468 | `include-hints`: Include private channel hints in the invoice.
469 | `rate-provider`: Set a rate provider for fiat rates. coindesk (default), coinbase or coingecko.
470 | `reject-on-amount-increase`: Reject if fiat amount changes in a way its unfavorable for you.
471 | `select-hints`: Select specific private channel routing hints to add to the invoice.
472 | `virtual`: Adds a fake pubkey as the destination and your real node intercepts the payment.
473 | `virtual-fee-rate`: Add the fee rate you want to charge for the final hop to the fake pubkey.
474 |
475 | Example: `bos invoice 10*usd --description "For 6 pack beer"`
476 | Example: `bos invoice 50000 --virtual --virtual-fee-rate 100`
477 |
478 |
479 |
480 | ### limit-forwarding
481 |
482 | Limits forwards through your node.
483 |
484 | - Flags:
485 | - `disable-forwards`: Disable all forwards through your node.
486 | - `max-hours-since-last-block`: Requires fresh blocks before forwarding resumes.
487 | - `max-new-pending-per-hour`: Limit the number of pending HTLCs.
488 | - `min-channel-confirmation`: Minimum channel confs required.
489 | - `only-allow`: Only allow forwards from/to a pubkey.
490 |
491 | Example: `bos limit-forwarding --disable-forwards`
492 |
493 |
494 |
495 | ### lnurl
496 |
497 | Perform a list of LNUrl functions
498 |
499 | - Arguments:
500 | - `auth`: Authenticate to a website or an app that supports LNUrl login/sign up.
501 | - `channel`: Request to open an inbound payment channel using LNUrl.
502 | - `pay`: Pay to a Bolt-11 pay request (invoice) returned from a LNUrl or lightning address.
503 | - `withdraw`: Withdraw from an lnurl withdraw server by passing a BOLT 11 invoice.
504 | - Flags:
505 | - `avoid`: Avoid a node, channel or a `bos tag` while paying to a LNUrl pay request.
506 | - `max-fee`: Maximum fees to be paid when paying the invoice, default: 1337.
507 | - `max-paths`: Maximum number of paths to use while paying to a LNUrl pay request.
508 | - `out`: Specify an out peer to pay the lnurl pay request.
509 | - `url`: LNUrl that returns an invoice to pay to.
510 |
511 | Example: `bos lnurl pay --url lightning:LNURL1DP68GURN8GHJ7MRWW4EXCTT5DAHKCCN00QHXGET8WFJK2UM0VEAX2UN09E3K7MF0W5LHZ0F5XAJXZVNYXQUNGDTRXGERYVFCXYERGCTXX33R2VR9XG6NXEP3VYUNWE3EVEJNSE3SVEJRGCNZV56KXVTXVYERQWR9X5ER2DEKVCUXYDWUW2V --max-fee 600 --avoid ban`
512 |
513 |
514 |
515 | ### nodes
516 |
517 | Adds a saved node for you to control remotely
518 |
519 | - Options:
520 | - `nodeName`: Enter the name of the node, new or existing
521 | - Flags:
522 | - `add`: will add a new saved node, will ask you a series of questions to fill out.
523 | - `remove`: removes an existing saved node
524 | - `unlock`: removes encryption on the macaroon of a saved node
525 | - `lock`: encrypt a saved node using a GPG key
526 |
527 |
528 |
529 | ### offer-channel-open
530 |
531 | Sell a channel to a node using [LSPS1](https://github.com/BitcoinAndLightningLayerSpecs/lsp/tree/main/LSPS1) protocol. If you run this server, your node will broadcast a feature bit to the network so that other nodes can see your channel offers.
532 |
533 | - Flags:
534 | - `added-base-fee`: Add a base fee surcharge to the sale. (default: 75,000 sats)
535 | - `capacity-fee-rate`: Set a fee rate for the capacity you are selling. (default: 10,000 ppm)
536 | - `max-capacity`: Set a maximum capacity for the channel you are selling. (default: 100,000,000 sats)
537 | - `min-capacity`: Set a minimum capacity for the channel you are selling. (default: 1,000,000 sats)
538 | - `private-fee-rate`: Set an additional fee rate if the channel is private. (default: 1,000 ppm)
539 |
540 | Example: `bos offer-channel-open --capacity-fee-rate 10000 --max-capacity 5000000 --min-capacity 1000000 --private-fee-rate 1000`
541 |
542 |
543 |
544 |
545 | ### open
546 |
547 | Helps to open channels to the network, batch opening and funding from external/cold wallet is supported. Open also supports p2tr and multisig funding for external funding of channels. Open also supports opening trusted funding channels.
548 | **IF USING EXTERNAL WALLET, DO NOT BROADCAST THE TRANSACTION FROM THE EXTERNAL WALLET, BOS WILL DO IT FOR YOU**
549 |
550 | - Arguments:
551 | - `pubkey`: public key of the node you want to open a channel to. Can enter multiple with a space in between.
552 | - Flags:
553 | - `amount`: capacity of the channel in Sats you want to open, can specify a separate amount if batch opening channels, default 5M sats if not specified
554 | - `avoid-broadcast`: Avoid broadcast of funding transaction
555 | - `external-funding`: give you an address for you to sign from your external wallet along with the amount. **IF USING EXTERNAL WALLET, DO NOT BROADCAST THE TRANSACTION FROM THE EXTERNAL WALLET, BOS WILL DO IT FOR YOU**
556 | - `internal-fund-at-fee-rate`: Add an internal fund fee rate to open a channel to skip the interactive dialog that asks for you for internal/external funding.
557 | - `opening-node`: Add an opening node for each pubkey to open channels on multiple saved nodes in the same transaction.
558 | - `set-fee-rate`: waits until the channel is open and attempts to set a forwarding fee rate, this process needs to run in the background until a channel is open. Have to run in background process manager like tmux, nohup or keep the ssh session open
559 | - `type`: public/private/public-trusted/private-trusted, default: public
560 | - `coop-close-address`: Add an external wallet address like your cold storage wallet to send funds when a channel is coop closed.
561 | - `set-fee-rate`: Set a fee rate on opening a channel when supported.
562 | - `skip-anchors-check`: Bos defaults to opening anchor channels only, this flag allows you to skip that check to open legacy channels.
563 | - `commitment`: Use this flag to specify the channel commitment type like `simple_taproot` to open a taproot channel.
564 |
565 | Example: `bos open pubkey1 --amount 1000000 pubkey2 --amount 3000000 pubkey3 --amount 4000000`. Once you enter the command and hit enter, it will ask the onchain transaction fee you want to set and also if you want to use your internal LND wallet for funding the transaction.
566 |
567 |
568 |
569 | ### open-balanced-channel
570 |
571 | Lets you open a balanced channel with your peer, both peers involved need to have keysend turned on. Funding from external/cold wallet is supported. **IF USING EXTERNAL WALLET, DO NOT BROADCAST THE TRANSACTION FROM THE EXTERNAL WALLET, BOS WILL DO IT FOR YOU**
572 |
573 | - Flags:
574 | - `recover`: Enter the address if funds were accidentally sent to it.
575 | - `coop-close-address`: Adds a closing addresses to send funds to when the channel is cooperatively closed.
576 |
577 | Simple running the command `bos open-balanced-channel` will ask you a series of questions to enter, like the `pubkey`, `total capacity` of the channel and the funding `fee rate`. It then key sends all that information to your peer to fund the other half for the channel. Your peer needs to run the same command to accept the request and review all information and agree to it, then the 1st peer or initiator will broadcast the transaction.
578 |
579 | 
580 |
581 |
582 |
583 | ### open-group-channel
584 |
585 | Lets you open balanced channels with multiple peers. This is an interactive command where each participant in the group runs the command and one participant initiates. Here's a video of how it works:
586 |
587 | https://user-images.githubusercontent.com/84944042/184359226-df90d4fb-e644-4667-ab0a-5e7fe0693f26.mov
588 |
589 |
590 |
591 |
592 | ### outbound-liquidity
593 |
594 | Returns your total inbound liquidity you currently have
595 |
596 | - Flags:
597 | - `above` returns tokens above a number you specify
598 | - `below` returns tokens below a number you specify
599 | - `with` with a specific peer public key
600 | - `top` returns liquidity in the top percentile for an individual channel
601 | - `with` use a `bos tag` to view outbound liquidity with peers in a tag
602 |
603 | Example: `bos outbound-liquidity` or `bos outbound-liquidity --with yourPeerPubkey`
604 |
605 |
606 |
607 | ### pay
608 |
609 | This command is used to pay a payment request (Invoice)
610 |
611 | - Arguments:
612 | - `request`: Enter the invoice you want to pay
613 | - Flags:
614 | - `avoid`: When paying the payment request you can set to avoid a node by entering a public key or a specific channel by entering a channel ID. You can also avoid multiple nodes/channels by using the avoid flag multiple times. You can also use a `bos tag` (more on this in a separate command below) to avoid a group of nodes or channels by grouping them together.
615 | - `avoid-high-fee-routes`: Ignore trying paths with fees greater than specified fees.
616 | - `out`: Pay the payment request out from a specifc peer of yours so the first hop is through that peer.
617 | - `in`: Enter a pubkey if you want the last hop to be through a specific in peer of the destination node.
618 | Note: If you create an invoice yourself, and you pay it using an out peer and an in peer of yours, it becomes a command that can you do rebalance with.
619 | - `message`: Enter a message of your choice to be attached to the payment request
620 | - `max-fee`: Max total routing fees you're willing to pay in order to pay the payment req. Default: 1337
621 | - `max-paths`: You can use multi path payments to pay the payment req via multiple paths, bos splits the payment and sends it out. Default: 1
622 |
623 | Example: `bos pay invoiceToBePaid --avoid 03f10c03894188447dbf0a88691387972d93416cc6f2f6e0c0d3505b38f6db8eb5 --avoid bannedNodes --out 02c91d6aa51aa940608b497b6beebcb1aec05be3c47704b682b3889424679ca490 --avoid bannedNodes --max-fee 100`
624 |
625 | Here `bannedNodes` is an example `bos tag` name.
626 |
627 |
628 |
629 | ### peers
630 |
631 | Lists your current peers that you have channels with in a table view.
632 |
633 | - Flags:
634 | - `active`: Shows all your active peers (not offline)
635 | - `complete`: Outputs a detailed view and does not use the table view.
636 | - `fee-days`: If you enter the number of days, it shows the peers you have earned fees with over N number of days along with the fees earned in a separate column
637 | - `filter`: You can apply filter formulas to display results, filter takes the column names as the filters, they include AGE, INBOUND_LIQUIDITY, OUTBOUND_LIQUIDITY. You can use filters like this `OUTBOUND_LIQUIDITY>100000` and it will filter results accordingly. You can also use formula expressions like `m` for million and `k` for 100k, example `OUTBOUND_LIQUIDITY<1*m` - `idle-days`: If you enter the number of days, it shows the peers you had no activity over N number of days, it includes both routing and payments received - `omit`: enter a public key to omit that peer from the list - `private`: shows peers you have private channels with - `public`: shows peers you have public channels with - `sort`: you can sort by column name, example: `sort OUTBOUND_LIQUIDITY` - `tag`: show peers that you have added to your tag, more on this in another command called `bos tags` below.
638 | `filter` variable support `AGE`, `BLOCKS_SINCE_LAST_CHANNEL`, `CAPACITY`, `DISK_USAGE_MB`, `INBOUND_LIQUIDITY`, `OUTBOUND_LIQUIDITY`.
639 |
640 | Example: `bos peers --active --filter OUTBOUND_LIQUIDITY>5*M --idle days 10`
641 |
642 |
643 |
644 | ### price
645 |
646 | Shows the current price of Bitcoin from the rate provider coindesk (default)
647 |
648 | - Options:
649 | - `symbols`: You can use currency ticker symbols to get the price in the fiat currency of your choice. Example: `bos price AUD` for Australian Dollar, `GBP` for British Pound, its defaulted to `USD`
650 | - Flags:
651 | - `file`: Enter the path to a JSON file to write the output to a file
652 | - `from`: You can pick the rate provider from coindesk (default), coinbase or coingecko
653 |
654 | Example: `bos price GBP --from coingecko` or just `bos price` for USD and from coindesk
655 |
656 |
657 |
658 | ### probe
659 |
660 | Simulate a payment for a certain amount and it will be simulated through the conditions specified, probing sends junk HTLCs to check if a real payment can go though. Can be used to check rebalance routes, payment routes as well or check the approximate liquidity available on a node via a particular channel.
661 |
662 | - Arguments:
663 | - `pubkey`: Enter the destination pubkey you want to probe, can be yours as well if you want to probe yourself for a rebalance.
664 | - OR `invoice`: Enter an invoice you want to probe (e. g. for probing private nodes which are not known to the network).
665 | - Options:
666 | - `amount`: Amount you want to probe for
667 | - Flags:
668 | - `avoid`: When probing you can set to avoid a node by entering a public key or a specific channel by entering a channel ID. You can also avoid multiple nodes/channels by using the avoid flag multiple times. You can also use a `bos tag` (more on this in a separate command below) to avoid a group of nodes or channels by grouping them together.
669 | - `avoid-high-fee-routes`: Ignore trying paths with fees greater than specified fees.
670 | - `max-fee`: the maximum total fees in sats that you want to use for probing.
671 | - `out`: Probe out from a specifc peer of yours so the first hop is through that peer.
672 | - `in`: Enter a pubkey if you want the last hop to be through a specific in peer of the destination node.
673 | Note: If you enter your pubkey, and you probe it using an out peer and an in peer of yours, it becomes a command that can you simulate a rebalance with.
674 | - `find-max`: Find the maximum amount you can route when you simulate a payment
675 |
676 | Example: `bos probe 03f10c03894188447dbf0a88691387972d93416cc6f2f6e0c0d3505b38f6db8eb5 3000000 --out 02c91d6aa51aa940608b497b6beebcb1aec05be3c47704b682b3889424679ca490 --avoid crapNodes`
677 |
678 |
679 |
680 | ### rebalance
681 |
682 | Rebalances your channels by moving liquidity between your peers. A rebalance moves local funds from one peer to another peer of yours which helps in gaining inbound liquidity in the channel the funds are leaving and gaining outbound liquidity in the channel the funds are arriving.
683 |
684 | - Flags:
685 | - `amount`: The maximum amount you want to rebalance
686 | - `out`: this flag can take the pubkey or Alias of your peer, its the first hop where you want the funds to leave from.
687 | - `in`: this flag can take the pubkey or Alias of your peer, its the last hop where the funds arrive into.
688 | - `avoid`: this can take pubkey, channel ID or a `bos tag` (more on this in a separate command below) where you can group multiple pubkeys to avoid while doing a rebalance. Avoid can take filters as well, explained in example below.
689 | - `avoid-high-fee-routes`: Avoids routes above the specified fee rate.
690 | - `in-target-outbound`: the amount of outbound you want to target for a peer's channel where the funds are coming into.
691 | - `out-target-inbound`: the amount of inbound you want to target for a peer's channel through which the funds are going out of.
692 | - `max-fee-rate`: the maximum fee rate in ppm that you want to pay for your rebalance
693 | - `max-fee`: the maximum total fees in sats that you want to pay for your rebalance
694 | - `minutes`: the maximum time you want the rebalance to run if it does not succeed or fail within the time you specified. The command will time-out after N number of minutes you specify.
695 | - `in-filter`: the set of in-peers you want the rebalance to filter through, this option is used with `bos tags`. - `out-filter`: the set of out-peers you want the rebalance to filter through, this option is used with `bos tags`.
696 |
697 | Example: ` bos rebalance --out "WalletOfSatoshi.com" --in "EDON" --out-target-inbound=capacity*0.85 --max-fee-rate 700 --max-fee 2000 --minutes 20 --avoid ban --avoid "035e4ff418fc8b5554c5d9eea66396c227bd429a3251c8cbc711002ba215bfc226/OR(FEE_RATE<80 , FEE_RATE>500)" --avoid "035e4ff418fc8b5554c5d9eea66396c227bd429a3251c8cbc711002ba215bfc226/HEIGHT<600000" --avoid "035e4ff418fc8b5554c5d9eea66396c227bd429a3251c8cbc711002ba215bfc226/opposite_fee_rate<100" --avoid "fee_rate<50/0296b46141cd8baf13f3eff9bb217c5f62ce0a871886559d661af0ef422c042d4b"`
698 |
699 | - **Breaking down this example:** - `--out "WalletOfSatoshi.com"` is the peer's channel where local funds move out from so it's the peer you want to gain inbound. - `-- in "EDON"` is the peer's channel where funds leaving from the WalletOfSatoshi.com channel are coming into and local balance is increased or outbound is gained. - `--out-target-inbound=capacity*0.85` This flag indicates that you want the channel with WalletOfSatoshi.com to have inbound liquidity of 85% of the total channel capacity, for example, if you have a 1M channel with WoS, you're targetting 850K of inbound. If you want a 50-50 channel with WoS, it would be `--out-target-inbound=capacity*0.5` OR `--out-target-inbound=capacity/2` - `--max-fee-rate 700` is the maximum fee rate in ppm you're willing to pay for the total rebalance - `--max-fee 2000` is the total maxmimum fee in sats you're willing to pay for the rebalance including base fee.
700 | **Note: Specify both values during a rebalance, the rebalance will fail if it finds a route and does not satisfy one of the criterias**
- `--minutes 20` the rebalance will time out after 20 minutes of path finding, the time-out occurs if the rebalance does not succeed/fail within the specified time. - `--avoid ban` "ban" is the name of the `bos tag` that I created, a tag can be named anything of your choice and you can add multiple pubkeys to the tag to categorize nodes. In this example, nodes specified in the tag "ban" will be avoided during path finding.
701 | - **Avoid Filters:**
702 | - avoid flag can take filter formulas along with a pubkey to filter channels of the pubkey specified during path finding.
703 | - Syntax: `--avoid pubkey/forumla`: If the syntax is pubkey followed by formula, the filter applies to channels of the node specified in the outbound direction.
704 | - Syntax: `--avoid formula/pubkey`: If the syntax is formula followed by pubkey, the filter applies to channels of the node specified in the inbound direction.
705 | - **Example Breakdown Continued:**
706 | - `--avoid "035e4ff418fc8b5554c5d9eea66396c227bd429a3251c8cbc711002ba215bfc226/OR(FEE_RATE<80 , FEE_RATE>500)"`, the pubkey specified in the filter belongs to WalletOfSatoshi.com, this formula implies you want to avoid all channels of WalletOfSatoshi that they charge less than 80ppm or greater than 500ppm. For example, if you just want to avoid a peer's channels greater than 200ppm the syntax is: `--avoid "pubkey/FEE_RATE>200)`
707 | - `--avoid "035e4ff418fc8b5554c5d9eea66396c227bd429a3251c8cbc711002ba215bfc226/HEIGHT<680000"` the pubkey specified in the filter belongs to WalletOfSatoshi.com, this formula implies you want to avoid all channels of WalletOfSatoshi that were created before the block height of 680000, this block was mined on `2021-04-21 05:58` which implies you want to avoid all your WalletOfSatoshi's channels that were created before that date. The reason for using this could be, all old channels might not be well maintained and might not have liquidity in the direction you want.
708 | - `--avoid "035e4ff418fc8b5554c5d9eea66396c227bd429a3251c8cbc711002ba215bfc226/opposite_fee_rate<100"` the pubkey specified in the filter belongs to WalletOfSatoshi.com, this formula implies you want avoid all channels of WalletOfSatoshi.com where the opposite_fee_rate is less than 100 or the rate which WalletOfSatoshi's peers charge them to route in the opposite direction, this is the fee rate that does NOT apply to you in the path finding because its in the opposite direction. The purpose of this filter is, a lot of nodes today are using dynamic fee rates to indicate to the network the direction in which they have liquidity using tools like charge-lnd. In the formula, by specifying you want to avoid low fee rates in the opposite direction you're effectively saying you want to avoid channels of WoS that are charging low because the liquidity is on the side of WoS's peers which is not the direction you need it for your rebalance to succeed. If the fee is high in the opposite direction an assumption can be made that liquidity is on WoS's side which is favorable for the success of your rebalance.
709 | - **Example of inbound 2nd syntax:**
710 | - `--avoid "fee_rate<50/0296b46141cd8baf13f3eff9bb217c5f62ce0a871886559d661af0ef422c042d4b"` the pubkey specified in the filter belongs to EDON, this formula implies you want avoid all channels of coming into EDON that charge less than 50 ppm.
711 | - Similar inbound syntax can be applied to all other filters mentioned above.
712 |
713 | **Note: Avoid formulas can be applied to any node in the graph, it is not limited to just your peers, you can replace the public key with any public key of your choice.**
714 |
715 | - **Using --out-filter and --in-filter** - If you create `bos tags` for your peers (check the tags command on how to create tags), you can use them for rebalances. instead of specifying `--out` and `--in` peer you can specify a group of nodes you want and bos can pick from those nodes to do rebalances with. Note the peer must exist within a tag to be considered for rebalance attempts. Usage: `bos rebalance --out --out-filter "inbound_liquidity<1*m" --in --in-filter "outbound_liquidity<1*m" --out-target-inbound=capacity*0.85 --max-fee-rate 700 --max-fee 2000 --minutes 20 --avoid ban`
716 |
717 |
718 |
719 | ### reconnect
720 |
721 | This command attempts to reconnect any disconnected peers, channels that are inactive are also treated as disconnected. DO NOT use this command with the `--node` flag.
722 | Example: `bos reconnect`, you can set to run a reconnect automatically in a cronjob like this: Run `crontab -e`, add this line and save it. `*/300 * * * * /bin/timeout -s 2 30 /home/ubuntu/.npm-global/bin/bos reconnect`, this runs the command every 5 hours. **Adjust your path according to where bos is installed on your node.** Running `which bos` can you give your path.
723 |
724 |
725 |
726 | ### remove-peer
727 |
728 | Closes a channel with a connected peer.
729 |
730 | - Options:
731 | - `public key`: Enter the public key of the peer you want to close the channel with.
732 | - Flags:
733 | - `active`: Makes sure the peer is online before closing the channel to ensure a coop close.
734 | - `address`: if you want to send funds that you get back (your local balance) straight to an external wallet, enter the destination address.
735 | - `fee-rate`: Set the fee rate for the closure. - `force`: Force close channel with a peer
736 | - `filter`: Add a filter formula to remove a peer matching the filter, example: `--filter "capacity<1*m"`
737 | - `inbound-below`: close channels with peers below a certain inbound liquidity level
738 | - `outbound-below`: close channels with peers whose outbound is below a certain number
739 | - `omit`: omit a peer you don't want to close a channel with if they fall under filter criteria of other flags such as `inbound-below`
740 | - `outpoint`: if you have multiple channels with the same peer, use this flag to only close one specific channel using `txid:vout`, you can get this value from `lncli listchannels`
741 | - `private`: make sure you have a private channel with the peer
742 | - `public`: make sure you have a public channel with the peer
743 | - `offline`: check if the peer is offline
744 |
745 | Example: `bos remove-peer pubkeyOfYourPeer --fee-rate 1 --force`. **You can quickly do `ctrl + c` if you accidentally selected the wrong peer.**
746 |
747 |
748 |
749 | ### send
750 |
751 | This command is used to make a keysend payment using a node's pubkey.
752 |
753 | - Arguments:
754 | - `pubkey or lnurl`: Enter the pubkey of the node you want to make a payment to You can also enter an lnurl or lightning address to pay to.
755 | - Flags:
756 | - `avoid`: When paying via keysend you can set to avoid a node by entering a public key or a specific channel by entering a channel ID. You can also avoid multiple nodes/channels by using the avoid flag multiple times. You can also use a `bos tag` (more on this in a separate command below) to avoid a group of nodes or channels by grouping them together.
757 | - `avoid-high-fee-routes`: Ignore trying paths with fees greater than specified fees.
758 | - `out`: Keysend out from a specifc peer of yours so the first hop is through that peer.
759 | - `in`: Enter a pubkey if you want the last hop to be through a specific in peer of the destination node.
760 | Note: If you enter your own pubkey, you can keysend using an out peer and an in peer of yours, it becomes a command that can you do rebalance with. Useful for rebalances below 50k sats since `bos rebalance` does not support rebalances below 50k sats.
761 | - `message`: Enter a message of your choice to be attached to the keysend
762 | - `max-fee`: Max total routing fees you're willing to pay in order to pay the payment req. Default: 1337
763 | - `max-fee-rate`: Max fee rate allowed to be paid for the keysend in ppm.
764 | - `message-omit-from-key`: BOS by default adds your pubkey to the keysend message, you can add this flag to avoid it.
765 | - `amount`: Add the amount in sats you want to keysend.
766 |
767 | Example: `bos send pubKeytoPay --avoid 03f10c03894188447dbf0a88691387972d93416cc6f2f6e0c0d3505b38f6db8eb5 --avoid bannedNodes --out 02c91d6aa51aa940608b497b6beebcb1aec05be3c47704b682b3889424679ca490 --avoid bannedNodes --max-fee 100 --message "Welcome to plebnet. RTFW plebnet.wiki"`
768 |
769 | `bos send nitesh_btc@lntxbot.com --amount 500"`
770 |
771 | Here `bannedNodes` is an example `bos tag` name.
772 |
773 |
774 |
775 | ### swap
776 |
777 | This command allows you to do a submarine swap with a peer. (Currently supports Testnet Only).
778 |
779 | If you run a testnet node, simply run the command, it is interactive to do a submarine swap with a peer.
780 |
781 |
782 |
783 | ### tags
784 |
785 | This commands allows you to create custom tags to categorize your peers. You can create a tag name of your choice and add pubkeys of nodes to the tags.
786 |
787 | - Options:
788 | - `tagname`: Enter a tagname you want to create or an existing tag that you already have.
789 | - Flags:
790 | - `add`: add a public key to a tag
791 | - `remove`: remove a public key from a tag
792 | - `icon`: you can add an emoji to your tag
793 |
794 | Example: `bos tags bannedNodes --add 03c2abfa93eacec04721c019644584424aab2ba4dff3ac9bdab4e9c97007491dda`.
795 | Simply running `bos tags` will display all your tags. Tags are stored in `~/.bos` folder, you can also edit your tags by editing the `tags.json` file. You can use `bos tags` in rebalance, peers, send, pay etc commands.
796 |
797 |
798 |
799 | ### telegram
800 |
801 | This command allows you to connect bos to a personal telegram bot. https://plebnet.wiki/wiki/Umbrel_-_Installing_BoS. Scroll down to the Installing Telegram Bot section and follow along to setup your bot.
802 | - Flags:
803 | - `budget`: Enter a budget amount that allows you to pay invoices from telegram upto the budget amount. (Not a very good idea to use this flag for security reasons).
804 | - `connect`: Enter a connect code to connect to your bot.
805 | - `ignore-forwards-below`: Enter an amount and forwards below the entered amount will be ignored in the notifications you receive.
806 | - `reset-api-key`: Allows you to start the setup process from start and enter a new API key.
807 | - `use-proxy`: Pass a flag to a json file that stores socksproxy (such as Tor) information for bos to communicate with telegram. Supports host, port, userId and password keys
808 | - `use-small-units`: This flag switches units on telegram from BTC to Satoshis. Example: Default `0.00456123` will be displayed as `456,123.2003` which includes millisats.
809 | - `use-rounded-units`: Formats amounts as rounded amounts.
810 |
811 | Sample File `proxy-config.json` (you can use any name of your choice):
812 | ```
813 | {
814 | "host": "127.0.0.1",
815 | "port": 9050
816 | }
817 | ```
818 |
819 | Example: `bos telegram --connect 123456789 --use-proxy="/home/ubuntu/someFolder/someConfig.json"`
820 |
821 |
822 |
823 | ### trade-secret
824 |
825 | This commands allows you to trade between peers (p2p trading), for example invite to a telegram group, sell gift card codes and much more.
826 |
827 | Example: Simply run `bos trade-secret`, it will ask you to create a trade or decode a trade, look at your open trades and serve stopped trades. Supports both open and closed trades. Run the command and you will be presented with options. An open trade is where you will not be entering the pubkey of the node your trading with and any node can purchase secrets from you by connecting with you and exchanging information of LN p2p messaging. A closed trade involves entering a pubkey and the trade will be encoded with the peer's pubkey and only that specific node can decode the trade.
828 | Trade Secret now also supports p2p channel sales and all trades in fiat (USD).
829 |
830 |
831 |
832 | ### utxos
833 |
834 | Returns a list of your UTXOS.
835 |
836 | - Flags:
837 | - `confirmed`: returns only confirmed utxos.
838 | - `count`: returns the number of utxos you have available in pending and confirmed
839 | - `count-below`: returns a utxos count number below the number you specified
840 | - `size`: returns utxos greater than the specified amount
841 |
842 | Example: `bos utxos` or `bos utxos --confirmed --count`
843 |
844 |
845 |
846 | ## **Secret BOS Commands:**
847 |
848 | **These commands don't come up in the help section of BOS:**
849 |
850 | ### delete-payments-history
851 |
852 | Deletes all your payments (not invoices). Helps in reducing the size of your DB.
**Important: Make sure to export your payments to a CSV using `bos accounting` if you want to keep a copy of them or need them to do accounting on your node.**
853 |
854 | - This command has no arguments or flags (except the `--node` flag to use a saved node). Directly run it as `bos delete-payments-history`.
855 | - It may take a LONG TIME for the command to finish executing.
856 |
857 |
858 |
859 | ### gift
860 |
861 | Send a routing fee gift to a node of your choice. It executes a rebalance command through that peer so that they make money on routing fees.
862 |
863 | - Arguments:
864 | - `target`: Takes the node pubkey
865 | - `amount`: Enter the amount you want to rebalance, the minimum amount you can enter depends on the minimum HTLC size and fee rate of the peer you're gifting routing fees to.
866 |
867 | Example: `bos gift 03c5528c628681aa17ab9e117aa3ee6f06c750dfb17df758ecabcd68f1567ad8c1 100`
868 |
869 |
870 |
871 | ### encrypt
872 |
873 | Encrypts data using your public key or another node's public key. You have to then use the `bos decrypt` command to decrypt the data and can be done only on the node whose key has been used to encrypt.
874 |
875 | - Options:
876 | - `message`: The message to encrypt
877 | - `to`: The pubkey of the node you want to encrypt the data for, default: your pubkey.
878 |
879 | Example: `bos encrypt --message "I love plebnet" --to 03c5528c628681aa17ab9e117aa3ee6f06c750dfb17df758ecabcd68f1567ad8c1`
880 |
You can then send the encrypted message to the node you used to encrypt, they can then use `bos decrypt` to decrypt the data.
881 |
882 |
883 |
884 | ### decrypt
885 |
886 | Decrypts the encrypted data from `bos encrypt`
887 |
888 | - Arguments: - `encrypted data`: Enter the data that needs to be decrypted.
889 |
890 | Example: `bos decrypt a569656e637279707465644ecd12dacf44c83a11e6451bfbe5d362697650f16e8eb72c0e5ec94e31c0f3aaa18f7e6473616c745820c7a8e6540ef1c9ac33d17d82eab6b4a3128300f44b17b60eba9cbceff25e4b276873657474696e6773a669616c676f726974686d6b6165732d3235362d67636d6a64657269766174696f6e66736372797074666469676573746673686135313268656e636f64696e6764757466386a6b65795f6c6`
891 |
892 |
893 |
894 | ### recover-p2pk
895 |
896 | If you accidentally sent on-chain funds to your public key instead of your wallet address, this command can help you sweep the funds back to your on-chain wallet.
897 |
898 | - Arguments:
899 | - `id`: Transaction id of funds sent to p2pk
900 | - `vout`: Transaction output index of funds sent to p2pk
901 |
902 | Example: `bos recover-p2pk 59qadc75d655cca5fa2qwef5ab87cd39fzxc99f563b9f71e0a5e245680fc6fd5 0 `
903 |
904 |
905 |
906 |
907 | ## If the latest Umbrel version broke bos, here’s how to fix it.
908 | ```
909 |
910 | ls ~/.bos
911 | ```
912 | If it throws an error saying: No such file or directory
913 | ```
914 | mkdir ~/.bos && cd ~/.bos
915 | ```
916 | If the directory exists:
917 | ```
918 | cd ~/.bos
919 | ```
920 | make a saved node directory, go into it and create a credentials file
921 | ```
922 | mkdir anySavedNodeName && cd anySavedNodeName && nano credentials.json
923 | ```
924 | Edit the JSON file
925 | ```
926 | {
927 | "cert_path":"/home/umbrel/umbrel/app-data/lightning/data/lnd/tls.cert",
928 | "macaroon_path":"/home/umbrel/umbrel/app-data/lightning/data/lnd/data/chain/bitcoin/mainnet/admin.macaroon",
929 | "socket":"umbrel.local:10009"
930 | }
931 | ```
932 | If umbrel.local:10009 doesn't work, try localhost:10009
933 |
934 | Save the file and exit
935 | ```
936 | ctrl + x
937 | y
938 | ```
939 | At this point bos commands should work like this
940 | ```
941 | bos balance --node anySavedNodeName
942 | ```
943 | Now make the saved node as default saved node
944 |
945 | Go back to bos dir
946 | ```
947 | cd ~/.bos
948 | ```
949 | Make a config file
950 | ```
951 | nano config.json
952 | ```
953 | Add the config setting
954 | ```
955 | {"default_saved_node":"anySavedNodeName"}
956 | ```
957 | Save and exit
958 |
959 | Now run bos commands normally
960 | ```
961 | bos balance
962 | ```
963 |
--------------------------------------------------------------------------------