Chain-read support for collectibles, credits & collections #318

Below are our use cases for Scarcity and I am sure other apps can reuse those too in the future.

Implementable today:

• getItemDisplay(instance) - read by instance. No purse/identity dependency. (feat(nfts): Read the display metadata of minted NFTs by instance id #426)
• ✅getVerifiedArtwork(imageRef) - IPFS fetch + verify; the gateway origin is a config question, not a blocker.
• ✅previewClaim(credit, collections) - takes a credit hash + collection ids.
• ✅getCollections() - reads the registry. (part of feat(nfts): collections #329)
• ✅getCollectionItems(id) - reads a collection's catalogue. (part of feat(nfts): collections #329)
• ✅getCredits -> getClaims

The rest has to wait for purses etc.

NFTs

Get NFTs a user holds. getOwnedNfts(identity) → OwnedNft[]

• storage: Scarcity.NftsByOwner (map AccountId → Nft, one per purse)
• scans the purse subtree + resolves metadata for each NFT

Get metadata for an NFT or a batch of NFTs.getItemDisplay(instance) → { hash?, name?, imageUrl?, rarity? }

• metadata: name + artwork + rarity + hash + others.
• runtime ScarcityApi.metadata_batch
• batched variant getItemDisplays(instances[])

Fetch Artwork bytes + verification. getVerifiedArtwork(imageRef) → Blob | null

• fetch image by CID/digest, verify against on-chain hash.

Credits

Get a user's credits to show in the UI, getCredits(identity) → Credit[]

• All credits awarded to the player, newest first, each carrying its state (earned / claimable / claimed).
• People Chain — awards + proofs:
  storage NftCredits.NftClaimCreditBlocks, NftClaimCreditAwards;
  runtime NftCreditsApi.nft_claim_credit_roots, nft_claim_credit_proofs
  (ref: fetchCredits)
• Asset Hub — claim state per credit:
  storage NftClaims.CreditTrees, NftClaims.ClaimedCredits
  (ref: fetchClaimStates)

Credit

• hash ← the credit field from NftClaimCreditAwards / the proofs API
• awardBlock ← the block key from NftClaimCreditBlocks
• awardedAt, root ← the roots API's per-block { root, timestamp }
• leaf ← the proofs API's { leaf, leaf_index, proof }
• state ← a different chain (Asset Hub CreditTrees/ClaimedCredits)

Show mint preview. previewClaim(credit, collections) → MintPreview[]

What a single credit would mint in each of the given collections (one result per collection) - powers the collection picker.

• runtime NftClaimsApi.preview_mints
• ref: previewMints

Collections

Get information about collections — getCollections() → MintCollection[]

• Every collection registered to accept claims, with names + item counts ({ id, name?, selection, itemCount? }).
• storage NftClaims.CollectionMinters, Scarcity.Collections; names via ScarcityApi.metadata_batch
• ref: fetchMintCollections

Get a collection's full item catalogue — getCollectionItems(id) → CollectionDetail

• Every item defined in a collection, with per-item display metadata.
• storage Scarcity.Collections (the record), Scarcity.ItemDefs (getEntries per collection — the item list); per-item name/image/rarity via ScarcityApi.metadata_batch (Item queries)
• CollectionDetail ≈ { id, name?, itemCount, items: CollectionItem[] }
  CollectionItem ≈ { index, supply, liveSupply, transferability, name?, imageRef?, rarity? }

Purse related calls

Purse - set of addresses, where a user can store an NFT at.

One address holds exactly one NFT.

Get the next empty address for a user. getNextEmptyPurse(identity) → address

• The mint/receive target
• a purse must be empty to hold an item

Find which address holds a given NFT. findPurseHolding(identity, hash) → address | null

• The sending address for a transfer.
• To send an item we must sign as the purse key that currently holds it. findPurseHolding(source, hash) locates which of the addresses holds the item.

Get signer for a purse

• in order to send an NFT, we need to be able to sign with the purse that the NFT holds