misc: fix litcli command docs, add group key support to DecodeAssetPayReq

[guggero]

Fixes a couple of smaller issues.

Fixes #1496.
Fixes #1493.

PR with itests is here: lightninglabs/lightning-terminal#1052

[ZZiigguurraatt]

While we are updating docs, can we add a comment This command is a shortcut for 'sendpayment --pay_req=' when we use litcli ln payinvoice -h so that people understand the difference with litcli ln sendpayment? We already get such a message when we run lncli payinvoice -h.

[guggero]

While we are updating docs, can we add a comment This command is a shortcut for 'sendpayment --pay_req=' when we use litcli ln payinvoice -h so that people understand the difference with litcli ln sendpayment? We already get such a message when we run lncli payinvoice -h.

Yes, added that here: lightninglabs/lightning-terminal#1052.

[ZZiigguurraatt]

Yes, added that here: lightninglabs/lightning-terminal#1052.

Not seeing that. Here is what I get

de20a9034ac0:/$ litcli ln payinvoice -h
NAME:
   litcli ln payinvoice - Pay an invoice over lightning using an asset.

USAGE:
   litcli ln payinvoice [command options] pay_req [--asset_id=X | --group_key=X] [--rfq_peer_pubkey=y] [--allow_overpay]

CATEGORY:
   Payments

DESCRIPTION:
   
  This command attempts to pay an invoice using an asset channel as the
  source of the payment. The asset ID of the channel must be specified
  using the --asset_id flag.
  

OPTIONS:
   --pay_req value              a zpay32 encoded payment request to fulfill
   --fee_limit value            maximum fee allowed in satoshis when sending the payment (default: 0)
   --fee_limit_percent value    percentage of the payment's amount used as the maximum fee allowed when sending the payment (default: 0)
   --timeout value              the maximum amount of time we should spend trying to fulfill the payment, failing after the timeout has elapsed (default: 1m0s)
   --cancelable                 if set to true, the payment loop can be interrupted by manually canceling the payment context, even before the payment timeout is reached. Note that the payment may still succeed after cancellation, as in-flight attempts can still settle afterwards. Canceling will only prevent further attempts from being sent
   --cltv_limit value           the maximum time lock that may be used for this payment (default: 0)
   --last_hop value             pubkey of the last hop (penultimate node in the path) to route through for this payment
   --outgoing_chan_id value     short channel id of the outgoing channel to use for the first hop of the payment; can be specified multiple times in the same command
   --force, -f                  will skip payment request confirmation
   --allow_self_payment         allow sending a circular payment to self
   --data value                 attach custom data to the payment. The required format is: <record_id>=<hex_value>,<record_id>=<hex_value>,.. For example: --data 3438382=0a21ff. Custom record ids start from 65536.
   --inflight_updates           if set, intermediate payment state updates will be displayed. Only valid in combination with --json.
   --max_parts value            the maximum number of partial payments that may be used (default: 16)
   --json                       if set, payment updates are printed as json messages. Set by default on Windows because table formatting is unsupported.
   --max_shard_size_sat value   the largest payment split that should be attempted if payment splitting is required to attempt a payment, specified in satoshis (default: 0)
   --max_shard_size_msat value  the largest payment split that should be attempted if payment splitting is required to attempt a payment, specified in milli-satoshis (default: 0)
   --amp                        if set to true, then AMP will be used to complete the payment
   --time_pref value            (optional) expresses time preference (range -1 to 1) (default: 0)
   --amt value                  (optional) number of satoshis to fulfill the invoice (default: 0)
   --asset_id value             the asset ID of the asset to use when sending payments with assets; cannot be used at the same time as --group_key
   --group_key value            the group key of the asset to use when sending payments with assets; cannot be used at the same time as --asset_id
   --rfq_peer_pubkey value      (optional) the public key of the peer to ask for a quote when converting from assets to sats; must be set if there are multiple channels with the same asset ID present
   --allow_overpay              allow sending asset payments that are uneconomical because the required non-dust amount for an asset carrier HTLC plus one asset unit is higher than the total invoice/payment amount that arrives at the destination; meaning that the total amount sent exceeds the total amount received plus routing fees
   
de20a9034ac0:/$ 

but I do here, which is a mistake

de20a9034ac0:/$ litcli ln addinvoice -h
NAME:
   litcli ln addinvoice - Add a new invoice to receive Taproot Assets.

USAGE:
   litcli ln addinvoice [command options] [--asset_id=X | --group_key=X] --asset_amount=Y [--rfq_peer_pubkey=Z] 

CATEGORY:
   Invoices

DESCRIPTION:
   
  Add a new invoice, expressing intent for a future payment, received in
  Taproot Assets.

  This command is a shortcut for 'sendpayment --pay_req='.
  

OPTIONS:
   --memo value                     a description of the payment to attach along with the invoice (default="")
   --preimage value                 the hex-encoded preimage (32 byte) which will allow settling an incoming HTLC payable to this preimage. If not set, a random preimage will be created.
   --amt value                      the amt of satoshis in this invoice (default: 0)
   --amt_msat value                 the amt of millisatoshis in this invoice (default: 0)
   --description_hash value         SHA-256 hash of the description of the payment. Used if the purpose of payment cannot naturally fit within the memo. If provided this will be used instead of the description(memo) field in the encoded invoice.
   --fallback_addr value            fallback on-chain address that can be used in case the lightning payment fails
   --expiry value                   the invoice's expiry time in seconds. If not specified, an expiry of 86400 seconds (24 hours) is implied. (default: 0)
   --cltv_expiry_delta value        The minimum CLTV delta to use for the final hop. If this is set to 0, the default value is used. The default value for cltv_expiry_delta is configured by the 'bitcoin.timelockdelta' option. (default: 0)
   --private                        encode routing hints in the invoice with private channels in order to assist the payer in reaching you. If amt and amt_msat are zero, a large number of hints with these channels can be included, which might not be desirable.
   --amp                            creates an AMP invoice. If true, preimage should not be set.
   --blind                          creates an invoice that contains blinded paths. Note that invoices with blinded paths will be signed using a random ephemeral key so as not to reveal the real node ID of this node.
   --min_real_blinded_hops --blind  The minimum number of real hops to use in a blinded path. This option will only be used if --blind has also been set. (default: 0)
   --num_blinded_hops --blind       The number of hops to use for each blinded path included in the invoice. This option will only be used if --blind has also been set. Dummy hops will be used to pad paths shorter than this. (default: 0)
   --max_blinded_paths --blind      The maximum number of blinded paths to add to an invoice. This option will only be used if --blind has also been set. (default: 0)
   --blinded_path_omit_node value   The pub key (in hex) of a node not to use on a blinded path. The flag may be specified multiple times.
   --asset_id value                 the asset ID of the asset to receive; cannot be used at the same time as --group_key
   --group_key value                the group key of the asset to receive; cannot be used at the same time as --asset_id
   --asset_amount value             the amount of assets to receive (default: 0)
   --rfq_peer_pubkey value          (optional) the public key of the peer to ask for a quote when converting from assets to sats for the invoice; must be set if there are multiple channels with the same asset ID present
   
de20a9034ac0:/$ 

[guggero]

Oops, yeah, added it to the wrong command. Updated in lightninglabs/lightning-terminal#1052 (can you please comment CLI related issues there so we don't mix responsibilities in the PRs?).

[ZZiigguurraatt]

When running litcli ln decodeassetinvoice --group_key, does it make sense to return an asset_id, meta_hash, etc.? Seems like this might mislead users into thinking there is a single asset_id for the group, but really it seems you are just responding with the first one.

[guggero]

When running litcli ln decodeassetinvoice --group_key, does it make sense to return an asset_id, meta_hash, etc.? Seems like this might mislead users into thinking there is a single asset_id for the group, but really it seems you are just responding with the first one.

Makes sense. I've added a condition that only prints that information if we requested to decode the invoice with an asset ID and not a group key.

[coveralls]

Pull Request Test Coverage Report for Build 15019506596

Details

• 3 of 190 (1.58%) changed or added relevant lines in 6 files are covered.
• 38 unchanged lines in 7 files lost coverage.
• Overall coverage decreased (-0.05%) to 36.842%

---

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
rfq/manager.go	0	1	0.0%
tapchannel/aux_funding_controller.go	0	7	0.0%
address/book.go	0	16	0.0%
universe/auto_syncer.go	0	22	0.0%
rpcserver.go	0	141	0.0%

Files with Coverage Reduction	New Missed Lines	%
asset/asset.go	2	49.17%
asset/mock.go	2	65.45%
tappsbt/create.go	2	26.74%
universe/auto_syncer.go	2	0.0%
tapchannel/aux_leaf_signer.go	3	43.43%
tapdb/universe.go	12	79.28%
rpcserver.go	15	0.0%

Totals
Change from base Build 15014433046:	-0.05%
Covered Lines:	26535
Relevant Lines:	72024

---

💛 - Coveralls

[Roasbeef]

Alternatively, we can have QueryAssetInfo accept an asset.Specifier.

[Roasbeef]

The way the function is setup, if you call it twice, only the first time will it actually try to fetch data.

[guggero]

But QueryAssetInfo does the opposite of what we want: Given an asset ID it finds out what the group key is.
But what we need for this use case is: Given a group key, what asset IDs does that group contain?

[Roasbeef]

What order are we actually relying on here?

[guggero]

No specific order (meaning natural database order), since it's not really important which asset we get.

[ZZiigguurraatt]

I'm thinking you should sync regardless in order to make sure you use the asset_id of the first minted traunch is used so that decimal_display is enforced properly. See also, #1503 .

[ZZiigguurraatt]

what did you think about this comment?

[guggero]

We'll enforce that all assets minted will have the same decimal display. But that will be a different PR that fixes #1503. At this point we need to be able to assume that any asset of the same group key has the same properties in this regard. Finding out which one was the actual first tranche isn't easy to do here.

[ZZiigguurraatt]

@guggero do you see my review comments for this one too now?

[gijswijs]

Just one nit. No blockers, so LGTM!

[guggero]

Okay, as discussed, I reverted the matching logic in the channel compatibility test.
We now return a more informative error (no compatible asset channel found for %s, make sure to use group key for grouped asset channels) in the following cases:

• The user uses --asset_id on send or receive
• There are grouped asset channels present
• The channel that contains the asset with the ID specified contains other asset IDs

Which means, one can still use --asset_id for a grouped channel that only has assets from a single tranche. But as soon as multiple tranches are in a channel, only the --group_key flag will work.

[guggero]

The litd itest is expected to fail btw. It will be fixed once lightninglabs/lightning-terminal#1052 is merged. So as long as that PR is green, this PR can be merged.

[GeorgeTsagk]

Lgtm, ty! 🦫