V1 to V2 Migration Guide


  • Players remain the same
  • Templates are now Collections
  • Tokens are now split into Items and Item Balances
    • Token Metadata is defined on Item Creation. Creating an item is effectively a "pre-mint"
    • The token is then added to a player's item balance on /item/balance/add
  • v1/player/get-inventory is now replaced by the list endpoint v2/item/balance. Pass in the player's ID to filter for a given player's item balances.
  • V2 Performance Improvements
    • The Stardust service that packages transactions and submits them to the chain has been rewritten in V2 giving a higher throughput for the rate transactions are submitted.

Recommended Migration

  1. Your players will not change, you are merely giving them new items
  2. Decide on Collection grouping
    1. Option 1: one collection for multiple item types
    2. Option 2: one collection per v1 template
  3. Create items and define metadata
  4. Re-mint V1 tokens to every player as V2 Item balances. We recommend migrating tokens > items on demand, so that when a player logs in and loads their inventory, the token is automatically re-minted as an item.


Withdrawn Tokens

If players have withdrawn tokens, it will be hard to determine which Stardust player gets the new token. We recommend having an event where a token must be deposited back into their Stardust wallet in order to redeem the v2 token/item.

V2 Parity

We are in the process of reaching parity, and will be releasing the missing features on a rolling basis.

Mint & BurnYesYes
Deposits & WithdrawalsYesYes