[feature]: more clearly define the `payment_addr` field in all documentation

[AndySchroder]

lncli addinvoice yields a payment_addr field. When using lncli sendpayment and manually specifying a payment, a pay_addr field is required. Similarly for lncli buildroute, we must pass a payment_addr in order for lncli sendtoroute to actually work with the route that was built. What is this parameter for? I can't find it in any BOLTS.

I "think" it is supposed to be the payment_secret, which is mentioned here https://github.com/lightning/bolts/blob/master/04-onion-routing.md#payload-for-the-last-node and https://github.com/lightning/bolts/blob/master/11-payment-encoding.md#tagged-fields . Also, lightning/bolts#643 (comment) suggests a payment_address parameter, which I think is the same thing.

If I run lncli addinvoice and put the payment_request output into https://www.bolt11.org/ the payment_secret seems to match the payment_addr.

Please clarify the documentation so that so much interrogation isn't required to understand the payment_addr field.

[morehouse]

+1

I just spent at least 20 minutes figuring out that payment_addr corresponds to payment_secret in the spec. payment_secret shows up nowhere in the LND source code.

[daredevil3435]

I want to work on this issue. I have recently found this repo so I'll be asking very basic questions like how do i get started. So can anyone please explain me what I am supposed to do? I think in documentation payment_secret is being used instead of
payment_addr? so we need to clarify difference between these two terms if there any. correct me if I am wrong

[guggero]

I think a good starting point would be to add a comment to all *.proto files in lnrpc/ where a payment_addr field appears. Maybe something along the lines of This field is also called "payment_secret" in other contexts.
Also make sure to read our contribution guidelines, formatting guides and our pull request checklist