feat!: holdings, NFTs and the movement ledger (redesign 5/10)

[prashantasdeveloper]

PR 6 of 10 in the indexer redesign series. Based on redesign/04-polyx-ledger (#349), not
master. Implements docs/implementation/03-holdings-nfts.md and
docs/implementation/05-movement-ledger.md.

What changed

#	Commit
1	feat!: add the Holding entity at portfolio and account grain	G8. Holding at the finest grain the chain uses (a portfolio, or a v8 account-level holder), with a genesis seeder following the accountBalance.ts pattern. Asset gains assetId, holderCount, holdings. rawAssetHolderToAssetHolder now carries a HolderKind discriminator. AssetHolder/NftHolder stay as maintained rollups (recommendation (b) — the SDK queries them directly).
2	feat: write Holding rows from asset balance updates	handleAssetBalanceUpdated writes a Holding row per side alongside the rollup; holderCount follows the rollup crossing zero. An account holder with no known Identity gets its Holding row without being folded into a DID rollup.
3	feat: add the Nft entity and stop rewriting NftHolder.nftIds as a whole array	G9, G10, and the largest single throughput cost in the indexer. Each token id is its own small immutable Nft row — mint = N inserts, transfer = one location update, burn = one column update — replacing push/filter on a lengthening nftIds array that historical mode re-serialises in full every mutation. burnedBlock is a nullable relation (Boolean can't be indexed); filter burnedBlockId: { isNull: true }.
4	feat: index v8 asset allowances	G11. AssetAllowance (assetId/owner/spender). handleAllowanceSpent takes the chain's own remainingAllowance rather than subtracting, so a missed/reordered event can't drift. Approval/AllowanceSpent are new project.ts keys with v8 decoder shapes.
5	feat: index asset metadata and CreatedAssetTransfer	G13 + rest of G11. AssetMetadata (MetadataScope Local/Global), GlobalMetadataKey, CustomAssetType. Ten previously-unregistered metadata/type events handled. SetAssetMetadataValue/Details carry no key — it's recovered from the setAssetMetadata call args, else from a RegisterAssetMetadata*Type event in the same extrinsic (the register-and-set path — this was a review finding: registerAndSetLocalAssetMetadata was silently dropping values), else recorded as an anomaly. handleCreatedAssetTransfer writes an account-side AssetTransaction and links instruction when pendingTransferId is present (it's an InstructionId, no new state).
6	feat!: normalise Asset ids and drop isUniquenessRequired	Asset.id is the assetId; isUniquenessRequired (dead pre-6.0 concept) removed; NftHolder.nftIds → [BigInt] (the one [Int] left, G10).
7	feat!: fold PortfolioMovement into AssetTransaction	Plan 05. AssetTransaction gains isInternalTransfer (not indexed — filter by equality), memo, address. The three PortfolioMovement writers funnel through one shared writer; classification is a helper in utils/portfolios.ts, keyed on holder presence first, DID equality second — an unresolved-DID holder classifies false, never falling through to the issuance/redemption (null) case. PortfolioMovement and PortfolioMovementTypeEnum removed.
8	feat: index the v5-era portfolio movement events	A8. FungibleTokensMovedBetweenPortfolios (6 args) / NFTsMovedBetweenPortfolios (5 args), emitted only at v5.4.3 via unchecked_move_funds and never registered. Each gets its own legacy decoder entry; both write AssetTransaction with isInternalTransfer: true. Measured: 0 on mainnet, 1 on testnet.
9	chore: address SonarCloud findings on the phase 5 diff	typescript:S6551 in parseMetadataKey — narrow the metadata-key value from unknown to number | string. new_duplicated_lines — the store mock, codec stand-in and tuple-event builder copy-pasted across the five new handler tests are extracted to tests/unit/helpers.ts. No behaviour change.

D5: full resync from genesis, no db/migrations entries.

NFT throughput — the measured cost this removes

NftHolder.nftIds.push(...) / .filter(...) rewrites the whole array on every mutation, and
under historical state each save() inserts a new row carrying the entire array. Testnet block
15,391,572: 399 RedeemedNFT, one id per event, all against a holder whose array held 2,724
ids ≈ 1.16M integer serialisations across 399 row versions — to delete 399 ids. The Nft
entity removes this class of cost structurally: that block becomes 399 single-column updates.

Consumer impact — BREAKING, coordinate releases with both teams

This is the only plan in the series where a portal change is mandatory — the portal queries
portfolioMovements directly.

• SDK
  • assetHolders / nftHolders — compatible, kept as rollups. nftHolders.nftIds narrows
    [Int] → [BigInt]; check SDK typings.
  • assets — gains assetId, loses isUniquenessRequired; holders derived-field shape may
    change.
  • portfolioMovements → rewrite to assetTransactions with
    isInternalTransfer: { equalTo: true }.
• Portal
  • portfolioMovements → rewrite to assetTransactions. Its
    type: { equalTo: Fungible|NonFungible } filter maps to amount / nftIds null-checks — which
    its existing assetTransactions query already does. fromPortfolioId/toPortfolioId filters
    are unaffected and become better-served once Holding exists.
• New capability for both teams:
  holdings(filter: { portfolioId: { equalTo: "did/1" } }) — not expressible against anything today.

Notes

• Commit 2 is scoped to handleAssetBalanceUpdated (v6+). Pre-v6 Issued/Redeemed carry only a
  DID, not a portfolio, so Holding stays identity-grain via the rollup for the v5 era and becomes
  portfolio-precise from v6.
• Commit 3: Nft sits at 9 indexes (subql auto-indexes the metadata jsonField), so burnedBlock
  is not @index-ed — isNull filtering is fine at the measured NFT cardinality (thousands). The
  genesis Holding seeder is fungible-only; the NFT read for an arbitrary start block belongs to
  plan 10.
• Commit 5: metadata-event decoder shapes are registered stable() (arity assumed constant pre-v8;
  only the v8 arity fixture exists to check against).
• tests/entities/* snapshot suites (Docker, not in the unit gate) are stale across the whole
  redesign and regenerate on the first resync. This branch is unit-gate-only, like phases 1–3.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud