Skip to content

Be consistent with using terms Transaction / transfer and Payment  #612

Closed

Description

@Bosch-0

Based on this slack discussion I think we need to be consistent in the guide when we are discussing a transaction / transfer and a payment.

Based on that discussion, we should go with the following terminology:

Transaction / Transfer = Used when discussing paying for more significant things like selling a house. This term should be synonymous with on-chain addresses / sends.

Payment = Used when discussing paying for less significant things like buying a coffee. This term should be synonymous with Lightning invoices / sends.

I already went with this terminology is my currently open Requesting bitcoin PR #611 of which I referred to on-chain requests as Transfer requests.

Incase Slack purges this discussion:

GBKS

I’d like to get a vibe check (:partying_face:) on the two terms “Transaction” and “Payment”. I basically use them interchangeable, but I’ve also seen others use them in very specific ways. For example, “transaction” referring to what is technically happening, and “payment” on the user-facing side. Or, “transactions” are what happens on-chain, and “payments” describe what happens on the Lightning network. It’s ideal if we have a simple, standard way of using the terms in the guide. How do you see them? Should we keep it simple or use them to describe different things?

Steve Lee

Outside the bitcoin context, I feel like transaction is for more significant things. Like if I sell you my house, we conducted a transaction. But then your monthly mortgage is payments not transactions.

With the bitcoin context, I think there is even more reason to follow this pattern, since transactions are tied to a specific technical meaning for on-chain bitcoin, and they’ll undoubtedly be for more substantial exchanges in the future since capacity is limited to a few per second. Whereas LN facilitates what we often call payments.

Patricia

similarly, i tend to think generally that a payment is small scale (paid for an uber etc) and transaction is for something larger (something like retirement planning). kind of agree with steve here in that when i think about buying something with lightning it automatically registers as a payment in my mind. idk why but every time i withdraw (exchanges, gaming, whatever) i feel like it is a transaction (even if its like 100 sats).

Bosch

A transfer also fits the description Steve outlined above for a transaction. I agree Transaction seems more suited for on-chain sends whilst payments can be used for Lightning sends.

GBKS

Also note the comments in the thread below. https://bitcoindesign.slack.com/archives/C015856BDME/p1639994002171500

Activity

  1. added
    CopyTask is about improving text.
    on Jan 6, 2022
  2. GBKS commented on Jan 6, 2022

    @GBKS
    Contributor

    What's the benefit of doing this? Is it currently causing confusion to use them interchangeably?

  3. Bosch-0 commented on Jan 6, 2022

    @Bosch-0
    CollaboratorAuthor

    There isn't any data that exists to back up that it would be beneficial, though it's more in line with traditional finance terminology so it would likely be more intuitive to people. Things will be more clear once we have more people using Lightning - it's to small right right to really pinpoint pain points.

    It's just an assumption, though most recommendations we are making are assumptions so I don't see an issue with recommending it.

  4. sbddesign commented on Jan 14, 2022

    @sbddesign
    Collaborator

    I'm in support of making sure we use our language consistently. I'm not convinced that the payment vs. transaction dichotomy is the right way. @Bosch-0 I was totally in agreement about a month or so ago, but I've done a lot of thinking and I don't think payment vs. transaction helps the user in any way.

    Technical Discussions

    When we are having technical discussions about Bitcoin and Lightning, word choice is critical. A transaction and a payment refer to very distinctive things (on-chain and Lighting, respectively).

    I pushed for this when I was updating the Transactions page in PR #593 because that page provides a technical description of what is happening.

    However, just because this dichotomy is necessary for technical discussions, does that mean it automatically becomes the best choice for the user experience?

    UX Discussions

    though it's more in line with traditional finance terminology so it would likely be more intuitive to people.

    Personally, I don't find the distinction intuitive.

    Look at this image (or view it on Figma). This was an exercise where I tried to create a map of transactional words in US English. I didn't consult a dictionary because I wanted the map to be informed by how I would naturally use these words in my daily life. I shared to slack beck in December.

    Types of Transactions

    Examples

    I can only really speak to the way I use English in the US. Transaction is a broad and general term, with other words meaning more specific things. It's a little bit contextual:

    • If I go to the coffee shop, I pay for my coffee.
      • At the end of the day when the shop manager is looking at sales, they say "Wow, we had 3,000 transactions today! Good sales."
      • The manager isn't going to say "oh, wait, hold up, these are all really tiny purchases like cups of coffee. My bad, these are actually 3,000 payments".
    • If I buy a house, that initial sale is a transaction...but every month, I make a mortgage payment.
      • I never hear anybody in the US saying "gee, I better watch my spending 'cause I don't want to miss my mortgage transaction".
      • It doesn't matter that the mortgage is 25,000% the cost of the coffee...the mortgage is still called a mortgage payment.
      • What is the cut-off? When does a "payment" become so large that it crosses over into being a transaction?
    • If I go to the store and return an item that was defective, the store doesn't give me a "payment" for the return -- they refund my money.
      • But in the eyes of the accountant this is one among many transactions that the store processed during the day.
    • If I move money from PayPal to my checking account, I'm transferring money to myself. It's not as common for one to say "I made a payment to myself".
      • But in the eyes of both PayPal and my bank, these are all transactions.

    What should we do?

    I think the most important thing is just being clear about if we are talking about something that's technical or something that the user is doing or experiencing.

    Here is an example: on the left side, I am speaking about the UX, and on the right side, I am describing what is happening in technical terms. See on Figma. The context of the sentence is important.

    Lightning Descriptions

    On-chain Descriptions

  5. Bosch-0 commented on Jan 18, 2022

    @Bosch-0
    CollaboratorAuthor

    Thanks for the thorough feedback on this, lots of very valid points and I pretty much agree with everything you've laid out. The only thing I disagree with, and the reason I think there needs to be a distinction between an on-chain and Lightning payment (or transaction), is that the UX of sending and receiving on each layer is different. They have different error states, variables (confirmation times, fees etc) and so forth so I don't see it as simple as saying Alice and Bob had a transaction for both.

    Distinguishing them as a transaction and payment like I mentioned in the OP maybe isn't the best solution, and it does get convoluted with the technical terms for these, but nonetheless I think some distinction in the UI needs to be made.

    In the future when most people are (likely unknowingly) just using Lightning this won't be a problem but for now we are in a time where on-chain is still used quite a bit.

    How about in the guide, outside of technical sections, we just refer to everything as a payments - so on-chain payment or Lightning payment. Payment is a more simple term than transaction imo. I'll revise my requesting PR to reflect this.

  6. GBKS commented on Jan 18, 2022

    @GBKS
    Contributor

    That's essentially what I was trying to figure out with the term "Instant payments" in this Tweet. To create a distinction between payment types that is not technical, but based on user benefits.

    So the user can choose between "Fast and cheap" or "Slow and expensive", but "Fast and cheap" requires a bit more extra setup (meaning Lightning channels and liquidity). Not sure that's the term to go with though, it only makes sense with various additional descriptive details in the overall user flow. We'll see.

  7. Bosch-0 commented on Jan 19, 2022

    @Bosch-0
    CollaboratorAuthor

    I've gone about this a little different in Zeus but it makes use of accounts of which we haven't covered in the Guide so it wouldn't be a simple terminology change.

    With Zeus you have an Lightning and On-chain account which are called a payment and savings account respectively. The only time the user is exposed to Lightning / On-chain terminology is when they setup the account and get presented the differences / trade-offs between the two. Once an account is setup you simply request / pay to an account and depending on the account type the required format is used (invoice / address etc.). So I guess I'm attempting to name the layers based on their, what I perceive, as their ideal use case.

    Opening or closing a channel is also called a "transfer" as you are essentially moving between your own accounts - this is the conventional terminology for a transaction of this type.

  8. changed the title [-]Be consistent with using terms ` Transaction / transfer` and `Payment` [/-] [+]Be consistent with using terms `Transaction / transfer` and `Payment` [/+] on Feb 8, 2022
  9. GBKS commented on Feb 22, 2022

    @GBKS
    Contributor

    Is this resolved?

  10. Bosch-0 commented on Feb 25, 2022

    @Bosch-0
    CollaboratorAuthor

    I'd say so yes , closing

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    CopyTask is about improving text.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions