Asset index is a high performance blockchain re-organization aware flag that allows users to be able to query historical information related to Syscoin Assets.
The asset index was created as a way for exchanges and other services to be able to manage Syscoin assets via viewing transactional history without requiring third party tools. This index is useful for viewing information only. The current set of RPCs to create transactions for managing assets are created in a way that are not dependent on a wallet and thus are compatible with signing tools such as hardware wallets. This is a reference implementation and of course third party tools in some contexts make sense. However as a fallback we created a reference implementation for those requiring all information to be available from within Syscoin Core itself without the need for custom modifications. You do not need to enable txindex and it is pruning compatible. There are two RPCs exposed for the use of asset index.
- listassetindex - This will let you filter all assets + asset allocations via an asset GUID and/or an address. You can leave the address field empty to scan through the entire asset.
- listassetindexassets - Takes in an address and returns any asset GUIDs that are owned by the address as allocations.
There are two configuration variables to use when dealing with an asset index. -assetindex and -blockindex. Blockindex allows once to view the block related to an asset transaction. It is re-org aware. This means that every transaction is associated with a blockhash and on a disconnect of a block the blockindex is updated to remove the blockhash associated with the disconnected transactions in the block(s) rolled back. The blockhash is output in the
listassetindex command as the block_hash field. This makes the assetindex re-org aware by extension as one would be able to rely on the block_hash field of the returned entries to know if a transaction was confirmed or potentially not part of the longest chain on a node.
You somtimes do not want to have to index all assets in Syscoin and just want to index the ones you care about and thus there are configurations for those cases you can read about below.
The main usecases of using such an index are as follows:
Use case #1: enter an asset GUID and address and get back a list of transactions (sends/receives) related to that asset/address tuple.
Use case #2: enter an address and view all assets connected to an address.
Use case #3: enter an asset GUID and view all transactions (sends/receives/updates) related to an asset.
We needed high performance to avoid large delays as transactional volume increased. The requirement for this index in the design phase was to have O(1) time complexity and <= O(N) space complexity. We solved this by using a Key-Value storage database and using a tuple of information as Key to reduce lookup complexity yet remain flexible to be able to walk through the historical information with intuition. We require the Key to have a page number to create this efficiency and thus consuming clients would work under a paged view mechanism. The default page size is 25 results per page.
Assetindexpagesize is dynamic and set upon configuration, if changed you need to reindex the blockchain from start.
Pseudocode for Connect Block logic:
Pseudocode for Disconnect Block logic:
Pseudocode for listassetindex RPC function:
Pseudocode for listassetindexassets RPC function:
What does re-org protected mean? It means that if the blockchain tip is disconnected for whatever reason (longer chain is found) then you have to rollback transactions, we wouldn't want our asset view to incorrectly show transactions as confirmed when they have been rolled back.
What does asset indexing mean? It means that we need a way to show all transactions related to an asset+address tuple. You need to be able to as a wallet or explorer view pertaining transactions for your asset allocation as a sender or receiver.