feat: build the token picker's list from the ledger and the registries

canton-dappbooster/architecture.md

@@ -146,6 +146,48 @@ number is arbitrary and human-picked, which is the point — the row wraps and d
 without a cap its height is the consumer's to set and the card has no scroll of its own to catch
 the spill.
 
+## Where a token's identity and its balance come from
+
+The list is the consumer's, and the kit reads no ledger. What that costs and buys:
+
+- **A token is identified by its `instrumentId`**, the admin party plus the id that registry gave
+  it, because nothing on Canton is a global address and two registries can both issue a `USDC`.
+  Nothing takes one string for a token, so `tokenKey` is what makes a map key, a React key or an
+  equality check out of the pair. Compare keys, never symbols.
+- **`balance` sits on the token, beside the metadata.** A party's holdings are private to the
+  participant hosting it, so only a read through the connected wallet can supply them: `useHoldings`
+  on the `/connect` sub-path is that read, and `sumHoldings` groups its one-per-contract answer into
+  one row per instrument. An absent balance means the read has not reached, not that the party holds
+  nothing, so the row shows no figure and sorts below every one that has a figure.
+- **A list is a catalogue, not a balance sheet.** `mergeTokens` builds one row per instrument out of
+  every source that knows about it, later sources winning field by field and an absent field meaning
+  a source had nothing to say. So holdings annotate rows rather than create them: a token nobody
+  holds is still offerable, which is what a swap's buy side needs, and an app that wants only what
+  it can spend filters the result itself. That filter is a screen's rule, never the list's.
+- **Metadata comes from the registry, over plain HTTP.** `readInstruments` reads a registry's
+  catalogue and stamps its admin party, taken from that registry's own `/info`, onto every id: the
+  instrument list carries bare ids, and an id identifies a token only together with the party that
+  issued it. It serves no logo, so artwork stays the app's or a curated list's. No session, so it
+  sits on the main barrel beside `sumHoldings`.
+- **The read lives here rather than in `canton-connect`**, even though it needs that package's
+  session. What it knows is the token standard — an interface id, the shape of a holding view, an
+  instrument id — and `canton-connect` is a layer over the wallet SDK, kept thin enough to delete.
+  Putting it there duplicated `InstrumentId` across two published packages and split one operation
+  in half, because the exact-decimal summing is here and that package cannot import it.
+  `useLedger` is the documented escape hatch for a read like this, and this is what it is for.
+- **`balance` is what the party can spend, and `locked` is the rest.** Not the total, because
+  `balance` is also what `<TokenInput>`'s Max fills and what it validates against, so a total would
+  have Max offer coin the ledger then refuses. The row shows locked as a second, quieter figure
+  under the first, and both reach the row's accessible name: the lock icon is `aria-hidden` and says
+  nothing on its own. Nothing locked and no read at all are one case — `getLockedFigure` drops both,
+  rather than putting a `0` on every row.
+- **`TokenListProvider` owns the order**, balance first and then the order given, so the field, the
+  list and the favourites cannot disagree about which token leads. A query re-ranks on top of that,
+  by match kind, in `filterTokens`.
+- **A token the metadata missed still renders.** `mergeTokens` fills `name` and `symbol` from the
+  raw instrument id rather than leaving them out: the row, the chip and the logo's initials all
+  need them, and a holding that renders as nothing is worse than one that renders as its id.
+
 ## What `<TokenInput>` does not take
 
 Three props a token field usually has are deliberately absent. **Precision** is not configurable

canton-dappbooster/doc-fixtures.d.ts

@@ -6,7 +6,14 @@
 
 type FixtureNode = import('react').ReactNode
 type FixtureElement = import('react').ReactElement
-type FixtureToken = { id: string; logo?: FixtureNode; name: string; symbol: string }
+type FixtureInstrumentId = { admin: string; id: string }
+type FixtureToken = {
+  balance?: string
+  instrumentId: FixtureInstrumentId
+  logo?: FixtureNode
+  name: string
+  symbol: string
+}
 
 /* Identifiers and amounts */
 
@@ -40,6 +47,13 @@ declare const darkSheet: string
 
 /* Tokens */
 
+declare const instrumentId: FixtureInstrumentId
+declare const registryUrl: string
+declare const holdings: readonly {
+  amount: string
+  instrumentId: FixtureInstrumentId
+  isLocked: boolean
+}[]
 declare const token: FixtureToken
 declare const tokens: readonly FixtureToken[]
 declare const mockTokens: readonly FixtureToken[]

canton-dappbooster/src/components/TokenInput/TokenFavorites.test.tsx

@@ -20,14 +20,17 @@ const favorites = (
 )
 
 const many = Array.from({ length: MAX_FAVORITES + 3 }, (_, index) => ({
-  id: `token-${index}`,
+  instrumentId: { admin: 'registry::1220ab', id: `token-${index}` },
   name: `Token ${index}`,
   symbol: `TK${index}`,
 }))
 
+const [CC, USDC] = TOKENS
+const GONE = { admin: 'nobody::1220ff', id: 'GONE' }
+
 describe('TokenFavorites', () => {
   it('renders the tokens its ids resolve to, in the order given', () => {
-    render(favorites({ ids: ['usdc', 'canton-coin'], onSelect: vi.fn() }))
+    render(favorites({ ids: [USDC.instrumentId, CC.instrumentId], onSelect: vi.fn() }))
 
     const symbols = screen
       .getAllByRole('button')
@@ -39,17 +42,17 @@ describe('TokenFavorites', () => {
   })
 
   it('drops an id the list does not hold', () => {
-    render(favorites({ ids: ['canton-coin', 'gone'], onSelect: vi.fn() }))
+    render(favorites({ ids: [CC.instrumentId, GONE], onSelect: vi.fn() }))
     expect(screen.getAllByRole('button')).toHaveLength(1)
   })
 
   it('renders nothing without an id that resolves', () => {
-    const { container } = render(favorites({ ids: ['gone'], onSelect: vi.fn() }))
+    const { container } = render(favorites({ ids: [GONE], onSelect: vi.fn() }))
     expect(container).toBeEmptyDOMElement()
   })
 
   it('renders no more chips than the cap, keeping the first', () => {
-    render(favorites({ ids: many.map((token) => token.id), onSelect: vi.fn() }, many))
+    render(favorites({ ids: many.map((token) => token.instrumentId), onSelect: vi.fn() }, many))
 
     const chips = screen.getAllByRole('button')
     expect(chips).toHaveLength(MAX_FAVORITES)
@@ -58,7 +61,7 @@ describe('TokenFavorites', () => {
 
   it('hands the whole token to onSelect', () => {
     const onSelect = vi.fn()
-    render(favorites({ ids: ['canton-coin'], onSelect }))
+    render(favorites({ ids: [CC.instrumentId], onSelect }))
     fireEvent.click(screen.getByRole('button', { name: 'Canton Coin CC' }))
 
     expect(onSelect).toHaveBeenCalledWith(TOKENS[0])

canton-dappbooster/src/components/TokenInput/TokenFavorites.tsx

@@ -1,13 +1,14 @@
 import type { ReactElement } from 'react'
 import { dialogAnatomy as anatomy } from '#src/components/TokenInput/anatomy'
 import { MAX_FAVORITES } from '#src/components/TokenInput/constants'
-import { tokenLabel } from '#src/components/TokenInput/tokenLabel'
+import { getTokenLabel } from '#src/components/TokenInput/getTokenLabel'
 import { TokenLogo } from '#src/components/TokenLogo'
-import type { Token } from '#src/providers/TokenListProvider/context'
+import type { InstrumentId, Token } from '#src/providers/TokenListProvider/context'
 import { useTokenList } from '#src/providers/TokenListProvider/useTokenList'
+import { tokenKey } from '#src/utils/tokenKey'
 
 interface TokenFavoritesProps {
-  ids?: readonly string[]
+  ids?: readonly InstrumentId[]
   onSelect: (token: Token) => void
 }
 
@@ -16,15 +17,15 @@ interface TokenFavoritesProps {
  * the order given, and drops the rest.
  *
  * @example
- * <TokenFavorites ids={['canton-coin']} onSelect={setToken} />
+ * <TokenFavorites ids={[{ admin: 'DSO::1220ab', id: 'Amulet' }]} onSelect={setToken} />
  */
 export const TokenFavorites = ({
   ids = [],
   onSelect,
 }: TokenFavoritesProps): ReactElement | null => {
-  const { byId } = useTokenList()
+  const { byKey } = useTokenList()
   const favorites = ids
-    .map((id) => byId.get(id))
+    .map((id) => byKey.get(tokenKey(id)))
     .filter((token) => token !== undefined)
     .slice(0, MAX_FAVORITES)
 
@@ -34,9 +35,9 @@ export const TokenFavorites = ({
     <section aria-label="Favorite tokens" className={anatomy.parts.favorites}>
       {favorites.map((token) => (
         <button
-          aria-label={tokenLabel(token)}
+          aria-label={getTokenLabel(token)}
           className={anatomy.parts.favorite}
-          key={token.id}
+          key={tokenKey(token.instrumentId)}
           onClick={() => onSelect(token)}
           type="button"
         >

canton-dappbooster/src/components/TokenInput/TokenList.test.tsx

@@ -3,6 +3,7 @@ import type { ReactElement } from 'react'
 import { describe, expect, it, vi } from 'vitest'
 import { dialogAnatomy as anatomy } from '#src/components/TokenInput/anatomy'
 import { ROW_HEIGHT_REM } from '#src/components/TokenInput/constants'
+import { formatFigure } from '#src/components/TokenInput/formatFigure'
 import { TokenList } from '#src/components/TokenInput/TokenList'
 import { TokenListProvider } from '#src/providers/TokenListProvider'
 import type { Token } from '#src/providers/TokenListProvider/context'
@@ -13,7 +14,7 @@ const ROW = ROW_HEIGHT_REM * 16
 const VIEWPORT = ROW * 4
 
 const tokens: Token[] = Array.from({ length: 100 }, (_, index) => ({
-  id: `token-${index}`,
+  instrumentId: { admin: 'registry::1220ab', id: `token-${index}` },
   name: `Token ${index}`,
   symbol: `TK${index}`,
 }))
@@ -39,6 +40,13 @@ const setup = (query?: string) => {
   return { container, onSelect, scroller, search: (next?: string) => rerender(list(next)) }
 }
 
+const one = (figures: Partial<Token>) =>
+  renderList(
+    <TokenListProvider tokens={[{ ...tokens[0], ...figures }]}>
+      <TokenList onSelect={vi.fn()} />
+    </TokenListProvider>,
+  )
+
 const rows = (): HTMLElement[] => screen.getAllByRole('button')
 
 const row = (index: number): HTMLElement =>
@@ -89,6 +97,39 @@ describe('TokenList', () => {
     expect(row(0)).toBeInTheDocument()
   })
 
+  it('shows the balance and carries it into the row name', () => {
+    const balance = formatFigure('1234.5')
+    const { container } = one({ balance: '1234.5' })
+
+    expect(container.querySelector(`.${anatomy.parts.rowBalance}`)).toHaveTextContent(balance)
+    expect(
+      screen.getByRole('button', { name: `Token 0 TK0, balance ${balance}` }),
+    ).toBeInTheDocument()
+  })
+
+  it('renders no figure for a token whose balance is unknown', () => {
+    const { container } = setup()
+    expect(container.querySelector(`.${anatomy.parts.rowBalance}`)).not.toBeInTheDocument()
+  })
+
+  it('shows what is locked under the balance, named and not left to the icon', () => {
+    const { container } = one({ balance: '900', locked: '100' })
+
+    expect(container.querySelector(`.${anatomy.parts.rowLocked}`)).toHaveTextContent('100')
+    expect(container.querySelector(`.${anatomy.parts.rowLocked} svg`)).toHaveAttribute(
+      'aria-hidden',
+    )
+    expect(
+      screen.getByRole('button', { name: 'Token 0 TK0, balance 900.00, 100.00 locked' }),
+    ).toBeInTheDocument()
+  })
+
+  // A row per token, so a lock nothing holds is a lock on every row.
+  it('leaves the locked line out when nothing is locked', () => {
+    const { container } = one({ balance: '900', locked: '0' })
+    expect(container.querySelector(`.${anatomy.parts.rowLocked}`)).not.toBeInTheDocument()
+  })
+
   // Windowed, so the rows out of view are not in the DOM to tab to: one tab stop and the arrow keys
   // are what reach them, not a tab stop per token.
   it('carries a single tab stop, starting on the first row', () => {