The difference between token and card

[buhtignew]

Here you've mentioned that token balances has been moved to card balances command and the Token class was removed.

Since token balances command was quite easy to remember, while I have some difficulty with card balances I was wondering what is the difference between card and token concept and whether it would make sense consider rename the whole Card class into Token.

[d5000]

card is simply the PeerAssets-specific term for a "token unit". You can read the whitepaper of PeerAssets for the "story" behind that, why the chose these terminology (analogies to card games).

In short, they chose these analogies because words like "asset" or "token" don't specify if you mean a token "currency" (which in PeerAssets terminology is a Deck) or an "unit" of the currency (a Card). If you spawn a Deck, you create a new currency, but first you don't create currency units. This is done with card issue or, in the case of AT/PoB/dPoD tokens, with the claim commands.

[buhtignew]

I agree with the term "deck", but the term "card" is still difficult for me to digest. However if we want to use the "card" term then we'd need to change any reference to "token" in our documentation, help messages, flags and even tech definition which should be not dPoD token but dPoD card. I think using both terms would create confusion for the final users which will need to learn the story behind the term and then understand, accept and memorize that the term is synonym of token. Of course we don't know whether someone will even dedicate any time to understand what has been created here, but for the vast majority of crypto people the term "token" is much more immediate than "card" and considering the huge quantity of information one has to learn to orient himself in the world of crypto chances are that the difficulties to understand that the term "card" basically means the same thing as token may decimate the number of potential users, at least in the beginning. I don't insist on my point but I'd like you to know that even for me, after we've been testing the tech for a bit, the term card still sounds weird.

[d5000]

I will not change basic PeerAssets terminology. The term "card" is used all over the code.

And I think "token" can coexist with "card" and "deck", simply indicating that "card" is the unit and "deck" the currency system. There is no need to eliminate "token" from the documentation.

[buhtignew]

I understand that changing that term would be a lot of work but we've already applied at least one big change since the first time we've begun testing the code.

However please keep in mind that I strongly dislike the term "card" and in my experience it prevents understanding of commands and hinders the smooth usage of the code.

I also think that the card's allegory in context of a project that has to do with money conveys the idea of gambling which is the opposite of what people are usually seeking for their funds.

And last but not least, usually when I come across a project that call something that has an established name with another terminology I become suspicious whether the leaders of the project are trying to fool people who doesn't understand things. I don't know whether it happens also to you, so it may be a subjective point of mine.

However I'm not going to discuss about this anymore since I've understood that you are not available to consider this point.

[buhtignew]

I think we can turn back to the compromise solution we had previously. I.e. keeping all vanilla commands from the PeerAssets in the card group and all the really useful commands like token balances and so on in the token group. Can it work for you?

[d5000]

That would introduce another keyword for one or two commands for no reason. The token command group existed only because I had no compatibility mode before, and myself then became convinced that it's inconsistent if we have already "card" and "deck".

The card-deck terminology was clear from the start of the project in 2020 and if it was so important we should have discussed that much earlier (and probably have tried to convince the PeerAssets devs to change the terminology too).

I'm myself also not 100% convinced of the card-deck analogy. But it is serviceable to distinguish token currency/token unit. An alternative is to create aliases for both deck and card which respect the token system/currency (deck) and token unit (card) distinction. So please come up with a better analogy for both "deck" and "card" and we can talk about that, because that would be a simple change. I would however insist in "card" and "deck" staying as aliases. And having aliases would be also probably not really make the help texts more user friendly.

All I'm doing here, is a PeerAssets extension, not a perfect CLI. A GUI would probably not need to be focused on the "card"/"deck" keywords. And I really want to concentrate on bugfixing now.

[buhtignew]

The card-deck terminology was clear from the start of the project in 2020 and if it was so important we should have discussed that much earlier (and probably have tried to convince the PeerAssets devs to change the terminology too).

You are right. Unfortunately I've fully understood all the implications only now. I've always been thinking that the underlying terminology wouldn't influence our decisions that much, because we'd be always able to change the interface terminology while the back-end would remain the original one.

So please come up with a better analogy for both "deck" and "card" and we can talk about that...

I was thinking about the origin of the word "bank". AFAIK in XIII century there was people in the market places in Italy holding the desks (desk spells banco in Italian) on which they'd exchange money, gold, silver and release the notes of their desk (the bank-notes). Later on those desks would become banks as we know them today and the desk's notes would become banknotes, i.e. the local currency. So adhering to this original meaning we can rename our "decks" into "desks" and keep the "tokens" instead of "cards". How does it sound to you?

[d5000]

The "desk" story sounds interesting. But the problem with this keyword is that we would have to introduce it and people would have to memorize it, just like the card-deck analogy. For me, the additional work needed (help texts would also need to be adapted etc.) is thus not justified by such a change from one uncommon word to another uncommon one.

I would strongly favour to just keep the card-deck keywords, except we find something really immediately understandable which can be used as an alias. I had thought about something like assetcurrency for deck and token for card, but I think the first word is too long (and "asset" alone would hage a similar ambiguous meaning as "token"). In addition, in the altcoin world "a token" often refers to what in PeerAssets would be "a deck", i.e. the currency, not the unit.

I looked into online thesaurus sites and at least in English it's quite difficult to find really good words that describe this differentiation. And I think it's just for this reason the PeerAssets team came up with the card-deck analogy.

We could look into other token protocols if they use a similar analogy, but I'm not really willing to invest much time into this.

[buhtignew]

I understand your point, but I think that the word desk is more immediate in our context than the word deck (it's also much more known among not native English speaker, just consider the word "desktop" for those who uses computer, for instance).

The desk (counter) that releases tokens sounds quite natural to me. The tokens that are valid only in context of the desk that has released them is also an image that seems meaningful (so as if those tokens were being moved on that desk, i.e. the surface of the table, only). By other hand we are already speaking about tokens, while "dPoD cards" instead of "dPoD token" wouldn't sound natural at all. And the "deck of tokens" makes even less sense.

Another word can be board.

I understand that you've already got used to this terminology, but I'm having really hard times right now to use the commands from the card group. My mind refuses to create a meaningful image for it, thus it costs me a great effort using them. I felt so relieved because of the simplification we've introduced with token balances, token list and so on. Now I feel as if we've made a big step behind. Thus it would be very important for me to find a solution for this issue.

[d5000]

I'm not convinced neither by desk nor by board.

However I have some ideas which could let us use token without inconsistencies but I need to investigate more. I will not change anything which leads to a significant amount of refactoring work, nor introduce any term not common in the DeFi world.

By the way, it was never thought to eliminate the word "token" from the manual etc. ("dPoD token" would never have been renamed to "dPoD card" or so).

[buhtignew]

By the way, it was never thought to eliminate the word "token" from the manual etc. ("dPoD token" would never have been renamed to "dPoD card" or so).

That can be of course a strategy, but since the word "token" is not a synonym of "card" in the real life and it has a completely different shape and use it's difficult to associate them, thus the command like card balances is just hard to remember and to use, at least for me.

By other hand the word "deck" means also "a floorlike surface of a ship", "an open, unroofed porch or platform extending from a house or other building", "a level, tier, or section of a structure, such as of a stadium or vehicle" and so on (here are all the possible meanings: https://www.dictionary.com/browse/deck). So a part the "set of card's" meaning (which is not the first one in the list), the word deck have some slight relationship to what we are looking for. (That's is the reason I've never raised objections about it). And interesting analogy I've found between the word deck and what we are trying to introduce as concept is the term "flying deck" which has as the first definition: "the upper deck of an aircraft carrier, constructed and equipped for the landing and takeoff of aircraft." and as the second one: "an elevated compartment containing the instruments and controls used by the pilot, copilot, and flight engineer to operate the aircraft" (https://www.dictionary.com/browse/flight-deck). Both seem to me somehow related to our need. What do you think?

Update: Here is the list of other possible candidates I've found: cluster, bunch, stock, inventory, registry, set, standard, protocol, pattern, instance, allotment, store. Or even more banally - asset, issuance, release, distribution or collection. If we want to use two words is can be tokenset, but there is an asset management tool that has the name TokenSets, you can find them online. I've also found a Java class that has that name. However here someone uses the term in a similar way: https://docs.bueno.art/v/generator/generation-and-tokenset-management/generating-a-tokenset

[d5000]

Again, I don't want to introduce any new term not used commonly in DeFi.

My idea I mentioned briefly before was simply to use token as an alias for both deck and card commands, i.e. create a Token class which inherits all commands from the Card and Deck classes. I have tried it now and it works technically, i.e. probably no refactoring would be necessary. Only a few commands would have to be renamed because they are used in both Deck and Card classes. That would basically mean that in the interface the distinction between card and deck is removed, and a "card" in the documentation then would be simply called a "token unit", but still mentioning the terms card and deck in the more technical parts of the docs, because developers will have to know that distinction.

I however would like to check what other DeFi programs use for these purposes.

[buhtignew]

I feel like your idea can work, although the distinction between all the issued tokens as a whole and the single unit token is something that I've got used with while testing the code and I think it would have sense for the average user keeping it, if possible. It would be strange if we weren't able to find the term in the DeFi realm (it's possible that the term "asset" is something that is being used in that way by the people without being conscious). However, if it may be helpful, I can tell that I've got used with the term "deck", I'm only uncomfortable with the term "card"

[d5000]

The problem if we keep "deck" is that in the original analogy it's a deck of a card game. I think all explanations, also the one you mentioned with the flying deck, are quite abstract and would have to be explained -- and then I'd simply keep the current words. Because if we have to explain one term to "normal users" and the card-deck analogy to developers, I think this will get too complicated.

"Asset" has the problem for me that it can also be an unit of an asset, so it has the same problem as "token".

I have briefly considered terms like "symbol" or "ticker" as replacement for "deck", which are used for example in BRC-20, but the problem is that PeerAssets doesn't have unique token names, so this would be misleading.

Yeah, it's not a trivial problem to solve. I've looked into the new Runes protocol and they have also all kinds of weird analogies, like "runestone" for the OP_RETURN output. Runes in general is quite similar to PeerAssets by the way ... So I think we're not alone here with such an issue, it seems the problem is that the English language simply hasn't considered this distinction properly. And I can also imagine the PeerAssets creators have discussed that stuff extensively before establishing the deck-card analogy.

That's why I fear to lose too much time overthinking this issue.

I would thus still prefer sticking with the card-deck terms, but the alternative idea to use "token" for both could be attractive for usability reasons, based on the following reasoning:

First, I think the main signification of "token" in normal DeFi usage would be what PeerAssets calls "deck", i.e. a "kind" of new asset, not the asset/token unit. If we talk about "creating a new token" in DeFi, we would mean "spawning a Deck" in PeerAssets. So all Deck commands would be easy to understand if we rename them to Token.

Second, the card balances command in particular I think is misnamed because it shows the balances of all users of a deck and not something like the balances of the individual "cards" (units) which would not make much sense. If I'd designed PeerAssets I would have called that command deck balances. So token balances would be instantly understandable.

card transfer can also be renamed to token transfer with everybody knowing instantly what is meant. While you could imagine a way to transfer a deck to another owner for example, this possibility doesn't exist in current PeerAssets, and thus if this is necessary later (e.g. for deck "swaps"), then a new command could be established.

card list is one of the cases where I would agree that a distinction unit-type is helpful because it shows a list of card transactions, but I don't consider that a "blocker". It could be simply renamed to token transactions or token transfers.

A more critical command could be card issue, which could be confused with the creation of a deck if we call it token issue. However I think if it is clear that spawn is used for a "new token" to be created, then it can stay I think. An alternative would be to rename it to token newunits/issueunits or so. In PoD and PoB tokens we generally use claim anyway.

The rest of the card class are mostly very technical commands, where the usability factor is not that important, so in the case one of them overlaps with a command of the Deck class a renaming would not be critical.

[buhtignew]

If there is no appropriate analogy we can find and there is no appropriate term in the DeFi world, we can just pick up a word without any particular analogy. After all someone has to introduce a term if it's needed at some point. And since the tech we are working on is quite novel there is nothing strange if we become a kind of pioneers in the term creating for our needs.

We've picked up the word "gateway", for instance, because it looked appropriate to us in the context of what we were looking for.

Or another example: in the beginning of the internet era there was the word "hyperlink" that wasn't representing a particular analogy to anything, but it was introduced because there was a need for it. There are bunch of words that were introduced in any epoch not because of an analogy or because someone else were already using it. To name just some of them: "watch", "wheel", "engine", "compass", "lifeline", "hotdog", "fire" and so on (there are myriads of them).

I think the words like "desk", "board", "counter", "panel" are both generic and well known by people who don't even know English that well. And they represent the general concept of some place where something is being released, registered, exchanged or received.

Just consider the "information desk", for instance: it's a place where someone can take the information and use it at his wish, moving around with it, selling it, exchanging it with other people. So as analogy, the token desk is also a kind of a source of tokens that are being moved, sold and exchanged.

The idea I've initially described about the banks being basically desks in origin was only a support to the general meaning of the word. I don't think we'll need to explain to anybody why we've renamed the Peerasset's "decks" into "desks". Because the desk's meaning is appropriate regardless the story that is behind.

However I'm ready to try the idea you've expressed to merge the cards and decks into tokens group. I'm only afraid we'll lose too much time with inventing new terms for the conflicting commands and flags, and possibly re-testing them as well, while by substituting cards with tokens and decks with desks we'll keep our commands and flags construction as it is.

So basically I'd say it's easier to agree on just one term that on many more than one.

And by other hand it can be that after testing the idea of merging cards with decks, we'll need to find another solution because the usage might become more complex. (That will become clear only after we've fully implemented the idea).

At the moment I'm a bit stuck with this question, because I don't like the word "cards", I'd need it to become "token" again and to go on with testing. So please let us take a decision, make the necessary modifications and to go on, as soon as possible. _ In this part of my answer I'll reply to your previous post, as if we've already decided to go on with your idea, so you know I'm not against it at all.

card list is one of the cases where I would agree that a distinction unit-type is helpful because it shows a list of card transactions, but I don't consider that a "blocker". It could be simply renamed to token transactions or token transfers

token transactions would create a bit of conflict with transaction group we already have. Should we have such a command it would become harder to remember both, at least for me. And also as I can see the card list command doesn't show any transaction. It shows the current situation what address each token of that deck is on in that moment. In the similar way the token transfers wouldn't show us actually any transfer, but a status, the result of those transfers.

An alternative would be to rename it to token newunits/issueunits or so. In PoD and PoB tokens we generally use claim anyway.

Maybe we can opt for token generate here, for instance?

Second, the card balances command in particular I think is misnamed because it shows the balances of all users of a deck and not something like the balances of the individual "cards" (units) which would not make much sense.

I agree with you. I've always imagined a plural here when we've been using the term token, as if it were a collective noun (like family, band, crowd). But with the term card it doesn't work that way. That's one of the reasons I'm not comfortable with it.

[d5000]

You're wrong about card list, it's actually a list of token transfers and token issues, not a status. The status is card balances.

token generate looks good.

As you want a fast decision I decided to go forward with the "merging card and deck commands into token" idea, but I will be busy these days so you will have to wait a couple of days. There are other commands to test if you are so disgusted by the "card" commands for whatever reason. And I'll not be changing this again so you will have to accept some "not 100% perfect" choices for commands. Of course I'll hearing your feedback now, but later I'd change command names only if they are easy and there's really a good reason. Don't disrespect the time I'm putting into this please. I want to take this project to a close and these endless CLI discussions are really tiring me, sorry.

---

I've looked again into it and the conflicting commands of the card class are the following, I include the proposal(s) I have to rename them:

• list -> transfers, listtransfers, alltransfers, txes, transactions
• issue -> generate, mint (not really a conflict only to avoid confusion, we could also simply preserve issue, which would perhaps not be the worst idea, because in reality you don't "issue" a deck. "mint" is actually a "fashionable" term in the Runes/Ordinals "scene", so it could work too)

Then the more technical commands I mentioned:

• encode -> encode_transfer or encode_tx (if txes/transactions is used for "list")
• decode -> decode_transfer or decode_tx
• parse -> parse_transfer or parse_tx (this is not a conflict but I'd change it due to it not parsing a token "deck" but a transfer/card)
• simulate_issue -> simulate_generation or simulate_mint (only if we change "issue" to "generate", otherwise it can stay)

So this is not a very large list of commands, and thus for me the change both classes to token would be feasible without much hassle.

[buhtignew]

Don't disrespect the time I'm putting into this please.

I have a great respect of all the work you've done. That's why I'm putting all this time and effort into it too. I don't think that our discussion has to do with respect. Our goal is the same, I guess - to deliver a good, usable code. Of course we can disagree on some direction to take and I can not be aware of how much time would one decision require to you against another one. So I apologize for that. But I have a great consideration of you, please believe me, and keep it in mind.

You're wrong about card list, it's actually a list of token transfers and token issues, not a status. The status is card balances.

Oh, my! You are right.

list -> transfers issue -> generate encode -> encode_transfer decode -> decode_transfer parse -> parse_transfer simulate_issue -> simulate_generation

I believe this ones can work.

[buhtignew]

There are other commands to test if you are so disgusted by the "card" commands for whatever reason.

I'm a bit stuck right now with the testing. Considering our list of priorities I'm not able to test the block locator mechanism because I'm waiting for the -s and -r flags issue being solved. While for the card group I'd prefer to wait until the change into token is implemented, because otherwise I need to conduct a strong fight with my brain that just refuses working on that group (I'm really sorry for that). Is there any other command you can suggest that would be important to test the mean time?

[d5000]

Unfortunately I ran into an issue. I'll look into it again tomorrow, now it's late here. If I'm not able to fix it I'll provide the token category simply as an alias for card, but without changing other things like messages.

Edit: Nevermind, solved the problem. I hope to upload the new update with the Token class until tomorrow.

[d5000]

I added the Token class to the newest update.

I decided to follow your suggestions with one exception: the issue/simulate_issue wil stay. The reason is that the word "issue"/"issuance" is very common in PeerAssets documentation, messages and command outputs, so I don't want to change it. I think the probability to confuse it with deck/token spawn actually is low.

I have already changed the help for some commands to include the token variant and add alternatives if Deck or Card terminology is used. But that's not ready still, but it should be usable mostly. Getting rid totally of Deck/Card is too difficult, so I will not change everything there.

Ther only issue which is still missing is that for the four modified commands from the card group (transfers, parse_transfer, encode_transfer and decode_transfer), the help doesn't work properly. I'll have to look into that again these days, and if it's not possible to fix then I'll have to add the docstrings manually to the file with the Token class, which is not exactly a good solution because each typo etc. would have to be corrected twice for these commands. Anyway, some of these commands (encode/decode/parse_transfer) still have the old vanilla docstrings which should probably be improved.

[buhtignew]

Thank you so much! I think we can close this issue and then open the other ones if needed, with a more appropriate titles.