Indivisible Asset type about stellar-protocol

[MonsieurNicolas]

How is this more special than other multipliers like k, M, etc? If you're going to add meta data (and I don't think we should), we should solve it for the other multipliers as well.

"stroops" are already indivisible

[jedmccaleb]

I think there are only two cases, divisible assets and non-divisible ones. If a thing is divisible and usable by humans than 7 decimal places is fine.
If a thing is non-divisible that needs to be reflected in the client. Yes the non-divisible asset is just using stroops but you want it to show up like "12 IBM" not ".0000012 IBM" in the client.

[MonsieurNicolas]

divisible and non-divisible is completely arbitrary information to communicate to the client. core doesn't care either way; your argument for not including the multiplier in the currency in the first place was that "people will know what they are buying/selling", how is it different here? Non divisible just means the multiplier is 10e7.
If you're arguying for a way to standardize on how clients figure out the multiplier, this is a fair (albeit late), argument to have if you think it should be included in the core protocol.

[MonsieurNicolas]

by the way I just saw that #20 and #21 are also tracking the same problem that there is a need for additional meta data tied to the asset type. The more I look at those, and the more I think it should not be included in the core protocol as people are going to tag more and more things to inclde in the various clients like "short description", or sub divide asset types; in your example, IBM would be tagged with "10e7", "stock symbol", "traded on the NYSE", probably an authoritative link on what it describes, etc.

[FredericHeem]

There is only one case, an asset with a decimal place parameter, a non-divisible asset is just a special case when the decimal place is 0. There is also the case where the decimal place is negative: the asset can only be sold/bought in bulk.
I wish there were a new core operation to create an asset with the relevant information such as the decimal places. By the way, Nxt has such API: http://wiki.nxtcrypto.org/wiki/The_Nxt_API#Issue_Asset
Bear in mind that not only the client code needs to know the decimal place but the horizon importer too. Therefore, in the current situation, for each new user's defined asset, the importer will have to be modified, this is clearly not desirable and not maintainable.
The asset decimal place is an intrinsic and essential property, that's why this information should be stored inside the ledger.

[MikeFair]

Speaking as someone with some experience in dealing with tech processes on assets; an asset actually requires two type indicators.

One is the asset instance type/class for legal identification and assigning property values (like if it's a currency, how many decimal places is it quoted/summed/rounded to; CNY for instance is non-divisible, USD is quoted to 4 decimal places; GBp (pence) is a different scale than GBP (pounds) but are the same underlying asset (aka they can be summed if done properly); and that's just currencies, corporate stock issues are non-divisible, but mutual funds and 401ks (which are also exchange traded share assets) are divisble). That's the first type that people generally think of when they think of an asset type.

The second is a "processing type" identifier and this one is oftentimes more meaningful from a general system's perspective. Think of this one as more like the "Asset Type Schema" value.

For example, all currencies have pretty much all the same properties, go through the same workflows, and all have roughly the same operations available to them even though their property values (like number of decimal places) might be different.

If you were to write an algorithm to "sum a group of currencies" or "get a market value for a currency asset"; it would generally look the same for all currency type assets (go to the distributed exchange and look for order pairs to build a quote price). The properties from each currency asset would adjust for the specific differences, but they all have the same "kind" of differences (generally follow the same schema).

Summing currencies is very different then summing "USD" and "MyHouse". Calculating a market value on the "MyHouse" "Real Property"asset is a very different process from the "USD" "Currency" asset. Likewise, those are both different from calculating the market value for the "Equity/Futures", "Equity/Equity", "Currency/Mortgage Loan", etc. assets.

I'm hopefully writing up a proposal for importing all this kind of global metadata reference information into the Stellar network (by using accounts as property bags for assets). Then when a new Asset gets created, you can assign a system schema so you can easily be provided the appropriate metadata values and the network can process the asset appropriately.

Outside systems can retrieve the same information when receiving the assets held by an account. Stellar then becomes a useful public repository for the shared global description of all assets. It can also trade them if you want.

In short, having rich asset descriptions is a huge opportunity to making the system more useful.

[jedmccaleb]

I feel like most of that info doesn't need to be in the protocol though. It can be outside and left to clients. Maybe the issuing account can put the meta data for the assets it issues in the data of the account.

[MikeFair]

Quick side comment/observation:

Maybe the issuing account can put the meta data for the assets it issues in the data of the account.

I totally agree; the question then is, and exactly which AccountId does this metadata go on?
How would a holder of this asset find that account id, how would a validator?
If it's the issuer's account id, then what if the issuer issues multiple currencies?
See #33 for the basic proposal I'd like to see.

I feel like most of that info doesn't need to be in the protocol though. It can be outside and left to clients.

Yes and no, nothing specific needs to be in the low level transaction protocol, but eventually this will end up with requiring putting something in whatever part of the system tries to validate the transactions and transforms the account balances object.

To put together a successful transaction, the fact that these assets have these fields, what they are called, and how to retrieve and set them needs to be baked into the framework. We need to know that this thing is a "currency" asset class and it uses "version 1.2 of the currency schema" which says that the number of decimal places in a transaction involving an asset currency is called "decimalPlaces" and not "decimals", "precision", "quoteDigits", "decimal_places", or "decimales".

Also, there are transactions which aren't simple balance transfers, where the number of units that went in is not the same as the number of units that comes out; and sometimes it's not even the same asset (or even number of assets).

For examples, I haven't seen anyone talk about it yet, but someday someone is going to experience a "split" or a "merge" or "spin-off" on their stock asset.

What was once 100 shares of IBM, will magically become 200 (or 50). Or what was once my "HotStartup" asset will simply cease to exist and magically become "BigCompanyBuyer". Or "CompanyOnTheRocks" will become two assets "ThePartOfTheCompanyThatWorks" and "TheRestOfIt". Or they'll get issued a stock dividend or a currency dividend. These transactions aren't even "trades" in the traditional sense; they're more like "transformations" (collectively referred to as "Corporate Actions" in finance; and I see Stellar being capable of going way beyond just finance stuff).

In these transaction types, magically, the balances in these assets modify, new assets appear out of thin air, some assets that were there yesterday flat out disappear, some don't even impact the asset that sourced the transaction (like a currency dividend increases currency without touching the stock that issued it); all without anyone having done a trade transaction. The only thing that happened was it became tomorrow and the "system" is expected to know/process these transformations; and in a global system, new zealander's see "the start of tomorrow" before the Pacific Time Zone is even done trading today. If the system isn't able to process these transactions directly, it at least needs to provide a mechanism for the asset holder to fix the balances in their accounts; which currently doesn't seem to exist. (There's no way for me to "self-adjust" the balance of the stock credit I was issued.)

What's a little worse, is that ideally, it impacts the entire system all at once; every account, every buy/sell offer, the shares outstanding numbers, everything; in an instant (again ideally; in practice it's never that clean ;) ).

When I have 100 shares of IBM today, and a 2 for 1 split happens, I magically only have 50 shares (now valued at double the price though); however the market order I have out there offering 75 shares at yesterday's price is no longer valid but really attractive (because it's at yesterday's half the price of today's valuation). Plus, I don't even have 100 units of which I could offer 75 anymore; I actually only have 50. So without the system's assistance; I could end myself up in a real sticky quagmire because "it turned tomorrow and I wasn't prepared for the corporate action".

Currently, I don't see any way to logically execute these transaction types in a way that makes sense.
Nor if I could, are all assets equally transactable; a "split" isn't a valid transaction for a "currency" asset.

So the part that goes in the protocol, are what elements will trigger which functions to perform the proper portfolio transformation; what properties will those functions look to; and which validation functions get run to ensure everything about the transaction is kosher.

In a "Spin-off" transaction; one asset will disappear, and either two new ones will replace it (or one new asset and a reduction in units on the original asset). That shouldn't be a valid operation on all asset types (like "MyHouse"), and to execute it, the transaction needs to know what percentage of the original asset each of the two new assets represents (so it can compute the number of units properly). Those fields just don't exist on other transactions.

In the currency case, technically, rounding happens at the quote precision of the currency. So you can get a different answer by tracking too many or too few decimal places.

If someone attempts to execute a "split" transaction on a currency asset processing type, the system should reject it as "Invalid Transaction". How did it know?

And what will the transaction needs of the future bring? We want someone else to write the code and contribute new "Asset Types" and "Transaction Types" to the system. I could even see a consensus vote being used to accept or reject allowing the new type or the new code into the swarm.

That's why I'm advocating the protocol be built in a way that the system, especially the validators and whatever does the actual holdings transformations, can learn about new asset types and new transaction types dynamically through some kind of plugin system and the separation of the "Processing Asset Type" (which has to do with code execution) and the standard "Asset Type" (which has to do with what type people say they have).

I'm hopefully painting a picture for the kinds of transactions real financial asset managers require. I believe Stellar is up to the task by embracing a bigger picture and more flexible concept of what an Asset and a Transaction are. It's got a powerful base to start with.

---

What will work here/What I'd like to see; is using "Component Based Programming" (inspired/ripped off from how game engines typically work) and transform what's currently the idea of an "Account" into something more like a generic "StellarObject" which hosts a collection of Component Instances.

For example, the existing "balances" part of an account object would move into one of these Object Component Instances instead of being native to all StellarObjects. What is typically considered an Account today would actually be two Objects; the generic "StellarObject" that has the public address, and the "Balances Component Instance". The "Balances Component Instance" is a separate object, with its own address that is stored in the metadata on the generic "StellarObject" and contains the Object's "Balances" array.

These new "Components" are how a generic StellarObject gets its behavior and schemas.

In principle, the metadata for a StellarObject would have an "ObjectClass" key_name, and the 64 byte value holds the address of some class, code, library, dll, hash_address, or something, that represented the behaviors and validation constraints for that component on this object. Think SNMP OID referencing an SNMP MIB if you know anything about how that works.

"StellarObjects" that represented an "Asset Class" (like the "Currency" asset class) wouldn't have a "Balances" component on them (and would be invalid objects for any transaction that dealt with the Balances component); these "Asset Class" objects would most likely have an array of transaction components for each of the valid transactions that an asset of that type could undergo.

Each of those transaction components would have references to the code base for how to execute the transaction, a list of its required and optional properties, etc. This way, the transaction builders/validators as high up as the Horizon server, or even JavaScript UIs, could get enough information to detect that the submitted transaction is invalid and help the user to fix it.

A StellarObject would then be presented in JSON as a dictionary with some basic global identifier information at the top, and then a "components" array which listed the component instances and their specific values. For existing Accounts one of those components would be "balances".

Transactions would be written around the expectation of requiring certain components. As long as a StellarObject had an instance of the Components that Transaction required to execute, it could validate for that StellarObject.

Databasewise, each Component Type would be a separate table, the primary keys being a "StellarObjectId", and a "ComponentInstanceId", the table's columns would be the properties that version of the component type supported.

...

[MikeFair]

The TL; DR on my last post :)

The part that is sort of protocol specific is the step in the process that validates a transaction contains a legal operation for that asset (like you can't "sell" 10 if you've only got 5; but you could borrow more when you're doing a "short_sell" transaction even when you're already at -10).

When you start having assets outside a basic currency like thing, you get new operations that only exist for those new kinds of Assets.

---

By thinking of a swarm address id as an "Object" with a "name" and an array of "Components" (which are other swarm addresses) in a tree structure (a Component is equivalent to a JSON Doc of kvps).

This models an Object as an addressable, typeless, bucket of Component instance objects.
Components have a type and they provide code.
Component instances carry data values for an object related to that Component.
Components provide the effects for operations on Objects.

A transaction operation knows the type of components it needs to execute.

If the Objects involved don't have the required Components; it's an invalid operation on that Object.

If the Objects do have the required Components; then the operation can test/modify the values stored on the Object's Component instances and commit the operation's effects to the ledger.

Adding Components to an Object is itself an operation that requires Validation. Aka some Components are Mutually Exclusive to each other; or are single instance only.

The collection of Component instances on an Object more or less defines its "type".

[jedmccaleb]

I think this needs ecosystem support now and we can just use stroops

[MikeFair]

we can just use stroops

No, we can't.
Talk to people who have tried it.
The DEX gets all messed up, and IEEE floats regularly round the Stroops up or down.

---

The folks looking for it are generally okay with a flag that simply causes transactions that create fractional math to get rejected even at the cost of not getting the full 64-bit usage of the value.

The "best" answer is a "precision" flag that indicates how many decimal points the asset supports.
I was thinking something like using 3 flag bits on the trustline, precision values 0-7:
0 - integer
1-6 - (n * 2) decimal places (2, 4, 6, 8, 10)
7 - IEEE 64-bit Float

[Or reverse 0 and 7 so that "default 0" means "IEEE 64-bit float"]

Or storing some other precision value(s) like what the Arbitrary Math libraries use.
(This would simultaneously encourage that software writers actually use an arbitrary precision math lib.)

A "workable" answer would be a flag on the issuer/asset that simply indicates integer vs decimal causing certain transactions (payments/offers/etc.) to either fail if fractional, or truncate off any fractional parts.

[japhiaolson]

I think there are only two cases, divisible assets and non-divisible ones. If a thing is divisible and usable by humans than 7 decimal places is fine. If a thing is non-divisible that needs to be reflected in the client. Yes the non-divisible asset is just using stroops but you want it to show up like "12 IBM" not ".0000012 IBM" in the client.

If there was simply a way to notify asset display interfaces on how to handle the specific asset, that seems like an okay solution for now.

We recently built a project around a non-divisible asset type and implemented the logic to convert Stellar numbers by scaling them up and translating between standard 7th decimal assets and the scaled integer asset for trades.
At the moment our ui is set up to show this correctly, but it's unfortunate that all 3rd party wallets/explorers have no way of doing this, as there is no official specification, so the asset's trades and general information all look incorrect.

Example order book with non-divisible asset trading with a standard asset:

What we see on 3rd party Stellar explorers: