Revise referencing of assets

[philippwerner]

(work in progress)

Asset

Every share is identified by:

1. Asset name
2. Issuer
3. Owner
4. Possessor
5. Ownership managing contract
6. Possession managing contract

Shares with identical values in 1-6 are initially represented by one possession record (P) + one ownership record (O) + one issuance record (I). Each possession record (P) refers to its corresponding ownership record (O). Each ownership (O) record refers to its corresponding issuance record (I).
If possession and/or ownership are transferred, it usually leads to creation of new P and/or O records. In consequence, an I record then has multiple O records and/or multiple P records.
Thus, regarding the number of associated elements we have a 1:N relation for both I to O and O to P records.

A type of asset ("ISSUANCE") is identified by:

1. Asset name
2. Issuer public key

An OWNERSHIP of a share (specific record) is identified by:

1. Owner public key
2. ISSUANCE
3. Ownership managing contract

An POSSESSION ("rented right to use") of a share (specific record) is identified by:

1. Possessor public key
2. OWNERSHIP
3. Possession managing contract

Requirements

The following functions are needed in QPI:

• issue asset -> pass all info and create issuance record
• get number of shares
  • of specific POSSESSION record
  • of all POSSESSIONs having given possessor identity
  • of all POSSESSIONs with given conract managing possession rights
  • of specific OWNERSHIP record
  • of all OWNERSHIPs with given possessor
  • of all OWNERSHIPs with given conract managing ownership rights
  • of specific ISSUANCE (all ownerships / possessions)
• iterate possessors of issuance
• distributeDividends -> iterate all POSSESSIONs of specific ISSUANCE
• transfer ownership and possession
• transfer ownership -> requires to update possession records (fast access to N possession records associated with ownership is needed)
• transfer possession
• qpi.acquireShares(assetName, issuer, owner, possessor, numberOfShares, sourceOwnershipManagingContractIndex, sourcePossessionManagingContractIndex):
  Try to acquire management rights for ownership and possession from source contract (transferring rights to calling contract).
• list all issued assets Add qxListAssets or similar to list all assets #109
• list all owernship records for given issuance
• list all possession records for a given ownership

Existing data structures

Asset issuance, possession, and ownership records are stored in one hash map named assets. It provides fast access:

• to issuance records by the issuer public key (needs additional check of asset name)
• to owership records by the owner public key (needs additional check of issuanceIndex and managingContractIndex)
• to possession records by the possessor public key (needs additional check of ownershipIndex and managingContractIndex)

Further, each possession record contains a reference to its one associated ownership record for fast access (index in hash map) and each ownership record contains a reference to its one associated issuance record for fast access (index in hash map).

The assets hash map is cleaned up at the end of the epoch and only assets which have at least one possession record with numberOfShares > 0 are copied to the cleaned-up hash map.

New data structures

Set of linked lists, with:

• one list for each issuance record containing indices of the assiciated ownership records, key is the index of the issuance record,
• one list for each owership record containing indices of the assiciated possession records, key is the index of the owership record,
• one list containing indices of all issuance records. key is an invalid universe index, such as the max value of the index data type

References

• https://discord.com/channels/@me/1167399046357471242/1259127000929538088
• https://discord.com/channels/@me/1167399046357471242/1263577849189892237
• https://discord.com/channels/@me/1167399046357471242/1263803146484977769
• https://discord.com/channels/@me/1167399046357471242/1264871458362884168
• https://discord.com/channels/@me/1167399046357471242/1266322026038038671