Kaleido Asset Manager migration (v24.6.0)
The v24.6.0 release of the Kaleido Asset Platform includes a number of changes in the Asset Manager service which have database migration impacts. This guide details the changes that will occur during migration of existing records in the Asset Manager data model, as well as changes that may be required in code/tasks that interact with Asset Manager going forward.
Background
The changes in this version allow for better de-coupling of "asset modeling" and "blockchain indexing", which is critical for both efficiency and flexibility. The types in the data model have been split into three categories, and some of the mandatory and optional relationships between them have changed. The types and their relationships now are:
Asset model:
- Collection
- Asset (may have an optional parent collection)
- Data (may have an optional parent collection/asset/address/pool/NFT/fragment)
Indexing:
- Address
- Pool (must have a parent address, may have an optional parent asset)
- NFT (must have a parent address, may have an optional parent asset)
- Fragment (must have a parent address, may have an optional parent asset)
- Transfer (must have a parent pool/NFT/fragment)
Activity:
- Activity
- Event (must have a parent activity, may have an optional parent collection/asset/address/pool/nft/fragment/data)
The scoping of names has also changed slightly, as follows:
- Collection/Asset/Activity - must have fully unique names within the service (unchanged)
- Data - must have fully unique names within the service* (changed from being a name unique only under a parent Asset)
- Pool/NFT/Fragment - must have a name that is unique only under their parent Address (changed from being a name unique under their parent Asset)
- Event - must have a name that is unique only under their parent Activity (unchanged)
* Due to Data now requiring a fully unique `name`, an additional `role` field has been added to this type, which can be used for a short description of the data's purpose in context, such as "metadata" or "image" or "documentation".
Migration details
Below are the detailed changes that will occur during this upgrade, for any data already existing in the Asset Manager database.
- For `addresses`: the `id` column is removed, and the `address` itself becomes the primary key
- All addresses will be lowercased in the database, and all queries will now be case-insensitive
- A new `contract` boolean will be set on any address that is used by a `pool`, `nft`, or `fragment` (to indicate that the address represents a smart contract address)
- For `pools` and `nfts`: the `address` field will become a foreign key to the `addresses` table (required entries will be created there if they do not already exist)
- Pool and NFT names must now only be unique within the scope of their parent `address`
- The `asset` field will be retained, but it becomes optional (nullable) and no longer has any bearing on the name uniqueness of the pool/NFT
- For `fragments`: if the optional `pool` reference is set, they will copy the `address` field from that pool and turn it into a foreign key in the same manner as above
- If `pool` is not set, a new `address` object will be created as a placeholder, and will use the name of the fragment's `asset` (may be semantically incorrect, but this avoids deleting the fragment altogether)
- The optional `pool` field will be dropped
- The `asset` field becomes optional (just as with pools/NFTs)
- For `data`: every existing item will be renamed, so its `name` will now be `<asset name>_<data name>` to ensure uniqueness
- The previous `name` field of every data item will be copied to the new `role` field
Required changes
Any code or tasks used to insert items to or query items from the Asset Manager data model will likely need to be updated. Below are the major changes that will be needed, although this may not be an exhaustive list of changes.
- When creating `address` objects:
- Set the new `contract` boolean to "true" for addresses that are known to be smart contracts
- When creating `pool`, `nft`, or `fragment` objects:
- Ensure that the `address` field is set
- Ensure that you also create the separate `address` object wherever you are creating one of these objects
- Do not set `pool` when creating `fragments`
- When creating `transfers`:
- The parent ref must use a "qualified name" syntax of `<address>/<pool or nft name>` (or can use a pool or NFT ID)
- Do not set `asset`
- When creating or querying `data`:
- Begin using a fully unique `name` for each item (a hash, UUID, or IPFS CID may be appropriate)
- Begin using `role` instead of `name`, as appropriate
- Replace `asset: "<name>"` field with the more generic `parent: { type: "asset", ref: "<name>" }` syntax
- Adjust API usage as needed - creation has moved to a top-level `/data` API