Asset Management Feature

Implement complete asset management functionality for Polkadot dApps.

Implementation Overview

Generate asset management in this order:

1. Pure functions (lib/) - Asset operations, toast configs, error messages
2. Custom hooks - Mutation management, fee estimation, asset ID queries
3. Components - Forms for create/mint/transfer/destroy, asset lists, portfolio
4. Integration - Exports and routing

Output: 14 new files, 4 modified files, ~2,100 lines

Template provides:

useFee

FeeDisplay

Critical Conventions

Follow template's CLAUDE.md strictly:

State: NEVER

useReducer

useState

any

as

unknown

lib/

index.ts

toPlanck

fromPlanck

Common Mistakes

❌ Creating tab navigation in page content - Navigation belongs in App.tsx sidebar ❌ Custom balance utilities - Use template's

toPlanck

fromPlanck

@polkadot/api

polkadot-api

as

Layer 1: Pure Functions

1. lib/assetOperations.ts

See

references/asset-operations.md

Exports:

• createAssetBatch(api, params, signerAddress)

  - Create + metadata + optional mint

• mintTokens(api, params)

  - Mint tokens to recipient

• transferTokens(api, params)

  - Transfer tokens

• destroyAssetBatch(api, params)

  - 5-step destruction

Key: Use

toPlanck

MultiAddress.Id()

Binary.fromText()

.decodedCall

Utility.batch_all()

2. lib/assetToasts.ts

Toast configurations for all operations:

import type { ToastConfig } from './toastConfigs'

export const createAssetToasts: ToastConfig<CreateAssetParams> = {
  signing: (params) => ({ description: `Creating ${params.symbol}...` }),
  broadcasted: (params) => ({ description: `${params.symbol} sent to network` }),
  inBlock: (params) => ({ description: `${params.symbol} in block` }),
  finalized: (params) => ({ title: 'Asset Created! 🎉', description: `${params.name} ready` }),
  error: (params, error) => ({ title: 'Creation Failed', description: parseError(error) }),
}

Create similar configs for mint, transfer, destroy.

3. lib/assetErrorMessages.ts

See

references/error-messages.md

Exports

ASSET_ERROR_MESSAGES

getAssetErrorMessage(errorType)

4. lib/assetQueryHelpers.ts (NEW file)

Asset-specific query invalidation helpers:

import type { QueryClient } from '@tanstack/react-query'

export const invalidateAssetQueries = async (queryClient: QueryClient) => {
  await queryClient.invalidateQueries({ queryKey: ['assets'] })
  await queryClient.invalidateQueries({ queryKey: ['assetMetadata'] })
}

export const invalidateBalanceQueries = (
  queryClient: QueryClient,
  assetId: number,
  addresses: (string | undefined)[]
) => {
  addresses.forEach((address) => {
    if (address) {
      queryClient.invalidateQueries({ queryKey: ['assetBalance', assetId, address] })
    }
  })
}

Note: Template has base

queryHelpers.ts

Layer 2: Custom Hooks

5. hooks/useAssetMutation.ts

Generic mutation hook:

export const useAssetMutation = <TParams>({
  params,
  operationFn,
  toastConfig,
  onSuccess,
  transactionKey,
  isValid,
}: AssetMutationConfig<TParams>) => {
  const { selectedAccount } = useWalletContext()
  const { executeTransaction } = useTransaction<TParams>(toastConfig)

  const transaction = selectedAccount && (!isValid || isValid(params))
    ? operationFn(params)
    : null

  const mutation = useMutation({
    mutationFn: async () => {
      if (!selectedAccount || !transaction) throw new Error('No account or transaction')
      const observable = transaction.signSubmitAndWatch(selectedAccount.polkadotSigner)
      await executeTransaction(transactionKey, observable, params)
    },
    onSuccess,
  })

  return { mutation, transaction }
}

6. hooks/useNextAssetId.ts

Query next available asset ID:

export function useNextAssetId() {
  const { api } = useConnectionContext()

  const { data, isLoading } = useQuery({
    queryKey: ['nextAssetId'],
    queryFn: async () => {
      const result = await api.query.Assets.NextAssetId.getValue()
      if (result === undefined) throw new Error('NextAssetId undefined')
      return result
    },
    staleTime: 0,
    gcTime: 0,
  })

  return { nextAssetId: data?.toString() ?? '', isLoading }
}

Layer 3: Components

See

references/form-patterns.md

references/template-integration.md

8-11. Form Components

Create these forms using standard layout from

references/form-patterns.md

• CreateAsset.tsx - Create with

  useNextAssetId()

  , fields: name, symbol, decimals, minBalance, initialSupply
• MintTokens.tsx - Mint, fields: assetId, recipient, amount
• TransferTokens.tsx - Transfer, fields: assetId, recipient, amount
• DestroyAsset.tsx - Destroy with confirmation, field: assetId (type to confirm)

All forms use:

• AccountDashboard

  at top

• TransactionReview

  in right column

• TransactionFormFooter

  at bottom

• FeatureErrorBoundary

  wrapper

12-14. Display Components

AssetList.tsx - Query and display all assets:

const { data: assets } = useQuery({
  queryKey: ['assets'],
  queryFn: async () => await api.query.Assets.Asset.getEntries(),
})

AssetCard.tsx - Individual asset display with action menu

AssetBalance.tsx - Display asset balance for account using

formatBalance

15. AssetDashboard.tsx

Portfolio view combining

AccountDashboard

AssetList

NO tab navigation in this component - navigation is in App.tsx sidebar (see Layer 4).

Layer 4: Integration

16-18. Exports

components/index.ts - Add:

export { CreateAsset } from './CreateAsset'
export { MintTokens } from './MintTokens'
export { TransferTokens } from './TransferTokens'
export { DestroyAsset } from './DestroyAsset'
export { AssetList } from './AssetList'
export { AssetCard } from './AssetCard'
export { AssetBalance } from './AssetBalance'
export { AssetDashboard } from './AssetDashboard'

hooks/index.ts - Add:

export { useAssetMutation } from './useAssetMutation'
export { useNextAssetId } from './useNextAssetId'
// Note: useFee is in template, not generated here

lib/index.ts - Add:

export * from './assetOperations'
export { invalidateAssetQueries, invalidateBalanceQueries } from './assetQueryHelpers'
export { getAssetErrorMessage } from './assetErrorMessages'

19. App.tsx

CRITICAL: Add navigation links to EXISTING SIDEBAR, not as separate tabs.

Common mistake: Creating tab navigation in the main content area. Instead:

// In App.tsx sidebar navigation
<nav className="sidebar">
  {/* Existing links */}
  <Link to="/dashboard">Dashboard</Link>
  
  {/* ADD asset management links HERE in sidebar */}
  <Link to="/assets/create">Create Asset</Link>
  <Link to="/assets/mint">Mint Tokens</Link>
  <Link to="/assets/transfer">Transfer Tokens</Link>
  <Link to="/assets/destroy">Destroy Asset</Link>
  <Link to="/assets/portfolio">Portfolio</Link>
</nav>

// In routes
<Routes>
  {/* Existing routes */}
  <Route path="/" element={<Dashboard />} />
  
  {/* ADD asset management routes */}
  <Route path="/assets/create" element={<CreateAsset />} />
  <Route path="/assets/mint" element={<MintTokens />} />
  <Route path="/assets/transfer" element={<TransferTokens />} />
  <Route path="/assets/destroy" element={<DestroyAsset />} />
  <Route path="/assets/portfolio" element={<AssetDashboard />} />
</Routes>

DO NOT create separate tab navigation in the page content - use the existing sidebar.

Validation

After generation:

# REQUIRED
bash .claude/scripts/validate-typescript.sh

# Verify imports
grep -r "@polkadot/api" src/  # Should be ZERO
grep -r "parseUnits\|formatUnits" src/  # Should be ZERO (use template utilities)

Expected Capabilities

After implementation:

• ✅ Create custom tokens with metadata
• ✅ Mint tokens to recipients
• ✅ Transfer tokens between accounts
• ✅ Destroy tokens (5-step process)
• ✅ View portfolio and balances
• ✅ Real-time fee estimation (via template's

  useFee

  )
• ✅ Transaction notifications (via template's TransactionContext)
• ✅ User-friendly error messages

References

Load these as needed during implementation:

• Asset operations:

  references/asset-operations.md

• Form patterns:

  references/form-patterns.md

• Error messages:

  references/error-messages.md

• Template integration:

  references/template-integration.md

Completion Checklist

• 14 new files generated (useFee is in template, not generated)
• 4 files modified (3 index.ts + App.tsx)
• Navigation added to EXISTING SIDEBAR (not as separate tabs)
• TypeScript validation passes
• Zero @polkadot/api imports
• Template utilities used:

  toPlanck

  ,

  fromPlanck

  ,

  formatBalance

  ,

  useFee

  ,

  FeeDisplay

• Shared components used:

  TransactionFormFooter

  ,

  TransactionReview

  ,

  AccountDashboard

• All exports through barrel files