# Blockchain Values

Formats addresses, hashes, amounts, and timestamps so people can verify them.

## Overview

An address has 42 characters, a transaction hash has 66, and a token amount can carry 6 decimal places. Nothing reverses a misread decimal or a mistyped address.

Format each value the same way in every view. Four principles apply to every value:

* **Exact:** Round only for display. Never round an amount the reader is about to send.
* **Labelled:** Pair every number with its unit, and every known address with a name.
* **Comparable:** Keep both ends of a long value visible for comparison with another source.
* **Copyable:** Let the reader copy the full value, not only the visible part.

```tsx
import { Amount, Badge, Button, Hex, Identicon, ListGroup, style, Surface, TokenLogo, Tooltip } from '@tempoxyz/ds'
import { ExternalLink } from '@tempoxyz/ds/icons'

export const fill = true
const hash = '0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060'
const from = '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'
const to = '0x71C7656EC7ab88b098defB751B7401B5f6d8976F'

function Explorer(props: { label: string }) {
  return (
    <Tooltip.Root>
      <Tooltip.Trigger
        render={
          <Button.Link
            aria-label={props.label}
            href="https://explore.tempo.xyz"
            rel="noreferrer"
            shape="icon"
            size="small"
            target="_blank"
            variant="tertiary"
          />
        }
      >
        <ExternalLink />
      </Tooltip.Trigger>
      <Tooltip.Popup>{props.label}</Tooltip.Popup>
    </Tooltip.Root>
  )
}

export function Demo() {
  return (
    <Tooltip.Provider>
      <Surface render={<section aria-labelledby="transaction-title" />} {...styles.card()}>
        <Surface.Header>
          <Surface.Title id="transaction-title">Transaction</Surface.Title>
          <Badge>Confirmed</Badge>
        </Surface.Header>
        <ListGroup.Root>
          <ListGroup.Row>
            <ListGroup.Label>Hash</ListGroup.Label>
            <span {...styles.value()}>
              <Hex copy value={hash} />
              <Explorer label="View transaction on explorer" />
            </span>
          </ListGroup.Row>
          <ListGroup.Row>
            <ListGroup.Label>Block</ListGroup.Label>
            <span {...styles.value()}>
              <span {...styles.number()}>18,204,551</span>
              <Explorer label="View block 18204551 on explorer" />
            </span>
          </ListGroup.Row>
          <ListGroup.Row>
            <ListGroup.Label>Time</ListGroup.Label>
            <span {...styles.value()}>
              <time dateTime="2026-10-20T09:41:07Z">Oct 20, 2026, 09:41:07 UTC</time>
            </span>
          </ListGroup.Row>
          <ListGroup.Row>
            <ListGroup.Label>From</ListGroup.Label>
            <span {...styles.value()}>
              <Identicon aria-hidden address={from} size="16" />
              <Hex copy value={from} />
            </span>
          </ListGroup.Row>
          <ListGroup.Row>
            <ListGroup.Label>To</ListGroup.Label>
            <span {...styles.value()}>
              <Identicon aria-hidden address={to} size="16" />
              <span {...styles.name()}>Tempo Labs</span>
              <Hex copy value={to} />
            </span>
          </ListGroup.Row>
          <ListGroup.Row>
            <ListGroup.Label>Amount</ListGroup.Label>
            <span {...styles.value()}>
              <TokenLogo address="0x20c0000000000000000000000000000000000000" size="small" />
              <Amount symbol="PathUSD" value="1250.504211" />
            </span>
          </ListGroup.Row>
          <ListGroup.Row>
            <ListGroup.Label>Network fee</ListGroup.Label>
            <Amount currency="USD" precise value="0.00003" />
          </ListGroup.Row>
        </ListGroup.Root>
      </Surface>
    </Tooltip.Provider>
  )
}

namespace styles {
  export const card = style({
    boxSizing: 'border-box',
    marginInline: 'auto !custom',
    maxWidth: '576',
    width: '100% !custom',
  })

  export const name = style({ flexShrink: '0 !custom', typography: 'body.b2Strong' })

  export const number = style({ fontVariantNumeric: 'tabular-nums !custom' })

  export const value = style({
    alignItems: 'center',
    columnGap: '8',
    display: 'flex',
    justifyContent: 'flex-end',
    minWidth: '0',
  })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Patterns/BlockchainTransaction.tsx)

## Addresses and Hashes

Use [Hex](/docs/components/hex) for addresses and transaction hashes. Add `copy` wherever the reader may need the full value.

### Truncate in the Middle

[Hex](/docs/components/hex) keeps the prefix and the checksum ending, and fits the value to its container. For plain strings, such as a [Toast](/docs/components/toast) title, `formatHex` keeps four characters on each side of an ellipsis: 0xd8dA…6045.

**Do:** Truncate addresses in the middle with [Hex](/docs/components/hex).

```tsx
/**
 * Do example for "Truncate in the Middle" on the Blockchain Values page.
 * Truncate addresses in the middle with Hex.
 * @module
 */
import { Hex, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.frame()}>
      <Hex copy value="0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" />
    </div>
  )
}

namespace styles {
  export const frame = style({ display: 'flex', width: '12rem !custom' })
}
```

**Don't:** Cut off the end of an address with a CSS ellipsis.

```tsx
/**
 * Don't example for "Truncate in the Middle" on the Blockchain Values page.
 * Don't cut off the end of an address with a CSS ellipsis.
 * @module
 */
import { style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return <span {...styles.value()}>0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045</span>
}

namespace styles {
  export const value = style({
    display: 'block',
    overflow: 'hidden',
    textOverflow: 'ellipsis',
    typography: 'mono.m1',
    whiteSpace: 'nowrap',
    width: '12rem !custom',
  })
}
```

### Show the Full Value Where You Verify

Attackers create addresses that match the first and last characters of a known one. Where the reader chooses or confirms a recipient, show the full address, as the [review and receive steps](/docs/patterns/payments#review-before-confirming) of a payment do.

* **Short forms:** If only a short form fits but people compare it, keep more characters with the `min` option of `formatHex`, such as 0xd8dA6B…A96045.
* **Activity lists:** A short value with a contact name is enough. The reader opens the record to verify it.

### Pair Addresses With Names

Show the known contact or account name beside the address, with an [Identicon](/docs/components/identicon) before both. The [Identicon](/docs/components/identicon) is a cue, never the identifier.

**Do:** Pair the name, identicon, and truncated address with a copy button.

```tsx
<Inline gap="12">
  <Identicon aria-hidden address="0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" size="32" />
  <Stack gap="0">
    <span>Alice</span>
    <Hex copy value="0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" />
  </Stack>
</Inline>
```

**Don't:** Let an identicon stand in for the address or the name.

```tsx
<Identicon aria-hidden address="0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" size="32" />
```

Keep the letter case of an address as received, since mixed case carries its checksum. Compare addresses without regard to case. [Identicon](/docs/components/identicon) renders the same colors for any letter case.

## Copy Values

* **Name the Button (aria-label):** The default name is Copy and the value. If that reads poorly, compose `Hex.Copy` with a label such as Copy address.
* **Confirm Once (2 seconds):** The button shows Copied and announces it politely. Do not add a [Toast](/docs/components/toast).
* **Your Own Layouts (CopyButton):** Use [CopyButton](/docs/components/copy-button) beside values you lay out yourself, named by what it copies.

## Link to the Explorer

Link transaction hashes, block numbers, and addresses to their page on [explore.tempo.xyz](https://explore.tempo.xyz). In a receipt, use a text link labelled View on explorer.

* **Icon Links (shape=icon):** Name an icon link by destination, and repeat the name in a [Tooltip](/docs/components/tooltip).
* **Separate Controls:** Keep copy and link as separate controls. One text never copies on one click and navigates on another.

## Amounts and Precision

Always pass a unit: `currency` with an ISO 4217 code for money, or `symbol` for a token.

Pass amounts as decimal strings, such as `"1250.50"`, so floating-point math never changes the value. TIP-20 tokens use 6 decimal places, so convert base units first (12500000 to 12.5).

```tsx
import { Amount, style } from '@tempoxyz/ds'

export const fill = true
export function Demo() {
  return (
    <div {...styles.stack()}>
      <Amount currency="USD" size="lg" value={1234.5} />
      <Amount currency="EUR" value={1234.5} />
      <Amount size="lg" symbol="PathUSD" value={1234.5} />
    </div>
  )
}

namespace styles {
  export const stack = style({ display: 'grid', gap: '12', maxWidth: '24rem !custom' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Amount/Currency.tsx)

### Decimals

Pick the precision by context. Show as many decimals as the value needs to stay exact.

```tsx
import { Amount, Surface, Table } from '@tempoxyz/ds'

export const fill = true
export function Demo() {
  return (
    <Surface size="medium">
      <Table.Root>
        <Table.Caption>
          One balance of 1250.504211 PathUSD and a 0.00003 fee, by context
        </Table.Caption>
        <Table.Head>
          <Table.Row>
            <Table.HeaderCell>Context</Table.HeaderCell>
            <Table.HeaderCell>Props</Table.HeaderCell>
            <Table.HeaderCell justify="end">Shows</Table.HeaderCell>
          </Table.Row>
        </Table.Head>
        <Table.Body>
          <Table.Row>
            <Table.Cell>Balance in a list</Table.Cell>
            <Table.Cell mono>currency="USD"</Table.Cell>
            <Table.Cell numeric>
              <Amount align="right" currency="USD" value="1250.504211" />
            </Table.Cell>
          </Table.Row>
          <Table.Row>
            <Table.Cell>Receipt or detail</Table.Cell>
            <Table.Cell mono>symbol="PathUSD"</Table.Cell>
            <Table.Cell numeric>
              <Amount align="right" symbol="PathUSD" value="1250.504211" />
            </Table.Cell>
          </Table.Row>
          <Table.Row>
            <Table.Cell>Compact token amount</Table.Cell>
            <Table.Cell mono>maxDecimals={'{2}'}</Table.Cell>
            <Table.Cell numeric>
              <Amount align="right" maxDecimals={2} symbol="PathUSD" value="1250.504211" />
            </Table.Cell>
          </Table.Row>
          <Table.Row>
            <Table.Cell>Fee in dollars</Table.Cell>
            <Table.Cell mono>currency="USD"</Table.Cell>
            <Table.Cell numeric>
              <Amount align="right" currency="USD" value="0.00003" />
            </Table.Cell>
          </Table.Row>
          <Table.Row>
            <Table.Cell>Fee on a review step</Table.Cell>
            <Table.Cell mono>currency="USD" precise</Table.Cell>
            <Table.Cell numeric>
              <Amount align="right" currency="USD" precise value="0.00003" />
            </Table.Cell>
          </Table.Row>
        </Table.Body>
      </Table.Root>
    </Surface>
  )
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Patterns/BlockchainPrecision.tsx)

* **Lists and Balances (maxDecimals):** Round fiat and stablecoin amounts to two decimals. Cap other token amounts.
* **Review and Receipts (Full):** Show the full value where the reader confirms it. A string keeps every digit, even trailing zeros.
* **Spendable Balances:** Never round a spendable balance up. Amounts round to the nearest digit, so truncate the string first.

**Do:** Keep a sub-cent amount, such as a fee, exact with `precise`.

```tsx
<Amount currency="USD" precise size="md" value="0.00003" />
```

**Don't:** Hide a sub-cent amount behind a `<$0.01` bound.

```tsx
<Amount currency="USD" size="md" value="0.00003" />
```

### Signs

In lists of moving amounts, such as activity, mark direction with `sign`: "+" for money in, the minus sign "−" for money out. Pair the sign with text, such as "Received" or "Sent".

```tsx
import { Amount, style } from '@tempoxyz/ds'

export const fill = true
export function Demo() {
  return (
    <div {...styles.stack()}>
      <Amount align="center" sign="+" size="md" symbol="PathUSD" value="1250.50" />
      <Amount align="right" currency="USD" sign="−" size="md" value={1234.5} />
    </div>
  )
}

namespace styles {
  export const stack = style({ display: 'grid', gap: '12', maxWidth: '24rem !custom' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Amount/Sign.tsx)

[Payments](/docs/patterns/payments#enter-the-amount) covers entering amounts with [AmountInput](/docs/components/amount-input).

## Tokens

* **Icon Beside Symbol (alt):** Beside the symbol, the empty default fits. If the icon stands alone, pass the token name.
* **Prefer Address (address):** Prefer it over a symbol. A symbol lookup adds a request, and symbols are not unique.
* **Contract in Details:** Show the contract address in token details to separate tokens with similar names.
* **Shared Lookups (TokenLogo.Provider):** Wrap lists in it, so tokens with the same symbol share one lookup.

**Do:** Show the token's symbol as text beside its icon and amount.

```tsx
/**
 * Do example for "Signs" on the Blockchain Values page.
 * Show the token's symbol as text beside its icon and amount.
 * @module
 */
import { Amount, style, TokenLogo } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.row()}>
      <TokenLogo address="0x20c0000000000000000000000000000000000000" />
      <span {...styles.name()}>PathUSD</span>
      <Amount symbol="PathUSD" value="1240.50" />
    </div>
  )
}

namespace styles {
  export const name = style({ flex: '1 !custom', typography: 'body.b2Strong' })

  export const row = style({
    alignItems: 'center',
    columnGap: '12',
    display: 'flex',
    width: '16rem !custom',
  })
}
```

**Don't:** Rely on the icon alone to identify the token.

```tsx
/**
 * Don't example for "Signs" on the Blockchain Values page.
 * Don't rely on the icon alone to identify the token.
 * @module
 */
import { style, TokenLogo } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.row()}>
      <TokenLogo address="0x20c0000000000000000000000000000000000000" />
      <span {...styles.value()}>1,240.50</span>
    </div>
  )
}

namespace styles {
  export const row = style({
    alignItems: 'center',
    columnGap: '12',
    display: 'flex',
    justifyContent: 'space-between',
    width: '16rem !custom',
  })

  export const value = style({ typography: 'body.b2Strong' })
}
```

## Block Numbers

* **On screen:** Group digits with the locale separator, such as 18,204,551, in tabular figures.
* **In copies:** Use the raw digits, such as 18204551, in copied values, URLs, and API calls.
* **Label:** Label the value Block in details, not with a `#` prefix.

## Timestamps

* **Markup:** Render a `time` element with a machine-readable `dateTime`, such as 2026-10-20T09:41:07Z, so assistive technology and translation tools read the exact time.
* **Lists:** Show relative times for the last day, such as 5 min ago, then dates. Refresh them on a timer without announcing each change.
* **Details:** In receipts and details, show the absolute time with seconds and a time zone, such as Oct 20, 2026, 09:41:07 UTC.
* **Durations:** Switch units at one second, such as 633 ms and then 1.2 s.

## Hidden Amounts

A privacy toggle hides balances from people nearby.

```tsx
import { Amount, Button, style, Surface, TokenLogo } from '@tempoxyz/ds'
import { Eye, EyeOff } from '@tempoxyz/ds/icons'
import { useState } from 'react'

export const fill = true
const balances = [
  ['PathUSD', '0x20c0000000000000000000000000000000000000', '1240.50'],
  ['USDC.e', '0x20c000000000000000000000b9537d11c60e8b50', '845.00'],
  ['USDT0', '0x20c00000000000000000000014f22ca97301eb73', '12.25'],
] as const

export function Demo() {
  const [hidden, setHidden] = useState(false)

  return (
    <Surface render={<section aria-labelledby="balance-title" />} {...styles.card()}>
      <Surface.Header>
        <Surface.Title id="balance-title">Balance</Surface.Title>
        <Button
          aria-label="Hide amounts"
          aria-pressed={hidden}
          onClick={() => setHidden(!hidden)}
          shape="icon"
          size="small"
          variant="tertiary"
        >
          {hidden ? <Eye /> : <EyeOff />}
        </Button>
      </Surface.Header>
      <div {...styles.total()}>
        <Amount currency="USD" masked={hidden} size="xl" value="2097.75" />
      </div>
      <ul {...styles.list()}>
        {balances.map(([symbol, address, value]) => (
          <li key={symbol} {...styles.item()}>
            <TokenLogo address={address} />
            <span {...styles.symbol()}>{symbol}</span>
            <Amount masked={hidden} symbol={symbol} value={value} />
          </li>
        ))}
      </ul>
    </Surface>
  )
}

namespace styles {
  export const card = style({
    boxSizing: 'border-box',
    marginInline: 'auto !custom',
    maxWidth: '360',
    width: '100% !custom',
  })

  export const item = style({
    alignItems: 'center',
    columnGap: '12',
    display: 'flex',
    minHeight: '40',
    typography: 'body.b2Strong',
  })

  export const list = style({ listStyle: 'none !custom', margin: '0', padding: '0' })

  export const symbol = style({ flex: '1 !custom' })

  export const total = style({
    fontVariantNumeric: 'tabular-nums !custom',
    marginBlockEnd: '16',
    minHeight: '48',
    typography: 'display.d2',
  })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Patterns/BlockchainHiddenAmounts.tsx)

* **Toggle:** Use an icon [Button](/docs/components/button) with the eye icons, named Hide amounts, that reports its pressed state.
* **Everywhere:** Hide every amount, including totals, activity, and charts.
* **Out of the page:** Set `masked` on [Amount](/docs/components/amount), which renders the mask in place of the value, not a blur, so the value is absent from the page. Screen readers read Hidden instead of the dots.
* **Remembered:** Keep the choice on the device, so amounts stay hidden on the next launch.

**Do:** Use the same fixed mask for every hidden amount.

```tsx
/** Do example for "Signs" on the Blockchain Values page: use the same fixed mask for every hidden amount. @module */
import { style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.list()}>
      {['PathUSD', 'USDC.e', 'USDT0'].map((symbol) => (
        <div key={symbol} {...styles.row()}>
          <span>{symbol}</span>
          <span>••••••</span>
        </div>
      ))}
    </div>
  )
}

namespace styles {
  export const list = style({
    display: 'flex',
    flexDirection: 'column',
    rowGap: '8',
    width: '14rem !custom',
  })

  export const row = style({
    display: 'flex',
    justifyContent: 'space-between',
    typography: 'body.b2Strong',
  })
}
```

**Don't:** Shape the mask like the number, which reveals its size.

```tsx
/**
 * Don't example for "Signs" on the Blockchain Values page.
 * Don't shape the mask like the number, which reveals its size.
 * @module
 */
import { style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.list()}>
      {[
        ['PathUSD', '•,•••.••'],
        ['USDC.e', '•••.••'],
        ['USDT0', '••.••'],
      ].map(([symbol, mask]) => (
        <div key={symbol} {...styles.row()}>
          <span>{symbol}</span>
          <span>{mask}</span>
        </div>
      ))}
    </div>
  )
}

namespace styles {
  export const list = style({
    display: 'flex',
    flexDirection: 'column',
    rowGap: '8',
    width: '14rem !custom',
  })

  export const row = style({
    display: 'flex',
    justifyContent: 'space-between',
    typography: 'body.b2Strong',
  })
}
```

## Secrets

Recovery phrases, private keys, API keys, and access keys grant control of funds. Show them with [SecretValue](/docs/components/secret-value), which starts masked and copies without revealing. Never show a secret with [Hex](/docs/components/hex).

**Do:** Start masked, and copy without revealing.

```tsx
<SecretValue label="Access key" value="tempo-access-key-example-0000" />
```

**Don't:** Reveal a secret by default.

```tsx
<SecretValue defaultRevealed label="Access key" value="tempo-access-key-example-0000" />
```

## States

* **Loading (Skeleton):** Keeps the row height while a value loads. A token shows a gray circle until its icon arrives.
* **Unknown TokenLogo:** An unknown token keeps the gray circle. Show its symbol and contract address as text.
* **Pending Transaction (Badge):** Show the hash at once, tagged Pending. Add the block and time when it confirms.
* **Copy Failed:** The copy button falls back to an older browser method. If that fails, keep the value selectable.

## Content

* **Plain words:** Write "address", not "public key", and "network fee", not "gas".
* **Exact symbols:** Keep the casing of token symbols, such as "pathUSD" and "USDC".

## Accessibility

* **Hex (Full value):** Screen readers read the full value, even when it is truncated. Pair it with a name.
* **Identicon (role=img):** Named by its address. If the address or name is beside it, set `aria-hidden` to avoid a double read.
* **Amount (strikethrough):** Screen readers do not announce it. State in text when an amount is superseded.

## Related

[Hex](/docs/components/hex)

Use for addresses and hashes.

[CopyButton](/docs/components/copy-button)

Use for copying values.

[Amount](/docs/components/amount)

Use for formatting amounts.

[TokenLogo](/docs/components/token-logo)

Use for token icons.

[Identicon](/docs/components/identicon)

Use for address avatars.

[SecretValue](/docs/components/secret-value)

Use for secrets.

[Payments](/docs/patterns/payments)

Covers send, receive, and deposit flows.

[Tables and Lists](/docs/patterns/tables-and-lists)

Covers columns of values.
